The HDF Group

HDF Reference Manual


[AN Interface][Top]


ANannlen/afannlen

int32 ANannlen(int32 ann_id)

ann_id
IN:
Annotation identifier returned by ANcreate, ANcreatef, or ANselect

Purpose
Returns the length of an annotation.
Return value
Returns the length of the annotation or FAIL (or -1) otherwise.
Description
ANannlen returns the number of characters contained in the annotation specified by the parameter ann_id. This function is commonly used to determine the size of a buffer to store the annotation upon reading.

FORTRAN
integer function afannlen(ann_id)
 
integer ann_id

[AN Interface][Top]


ANannlist/afannlist

intn ANannlist(int32 an_id, ann_type annot_type, uint16 obj_tag, uint16 obj_ref, int32 *ann_list)

an_id
IN:
AN interface identifier returned by ANstart
annot_type
IN:
Type of the annotation
obj_tag
IN:
Tag of the object
obj_ref
IN:
Reference number of the object
ann_list
OUT:
Buffer for the annotation identifiers

Purpose
Retrieves the annotation identifiers of an object.
Return value
Returns SUCCEED (or 0) or FAIL (or -1) otherwise.
Description
ANannlist obtains a list of identifiers of the annotations that are of the type specified by the parameter annot_type and are attached to the object identified by its tag, obj_tag, and its reference number, obj_ref.
 
Since this routine is implemented only to obtain the identifiers of data annotations and not file annotations, the valid values of annot_type are AN_DATA_LABEL (or 0) and AN_DATA_DESC (or 1). To obtain file annotation identifiers, use ANfileinfo to determine the number of file labels and descriptions, and then use ANselect to obtain each file annotation identifier.
 
Sufficient space must be allocated for ann_list to hold the list of annotation identifiers. This can be done by using ANnumann to obtain the number of annotation identifiers to be retrieved, and then allocating memory for ann_list using this number.

FORTRAN
integer function afannlist(an_id, annot_type, obj_tag, obj_ref, ann_list)
 
integer ann_list(*)
 
integer an_id, obj_tag, obj_ref, annot_type

[AN Interface][Top]


ANatype2tag/afatypetag

uint16 ANatype2tag(ann_type *annot_type)

annot_type
IN:
Type of the annotation

Purpose
Returns the annotation tag corresponding to an annotation type.
Return value
Returns the annotation tag (ann_tag) if successful, and DFTAG_NULL (or 0) otherwise.
Description
ANatype2tag returns the tag that corresponds to the annotation type specified by the parameter annot_type.
 
The following table lists the valid values of annot_type in the left column and the corresponding values for the returned annotation tag on the right.

Annotation Type
Annotation Tag
AN_DATA_LABEL (or 0)
DFTAG_DIL (or 104)
AN_DATA_DESC (or 1)
DFTAG_DIA (or 105)
AN_FILE_LABEL (or 2)
DFTAG_FID (or 100)
AN_FILE_DESC (or 3)
DFTAG_FD (or 101)

FORTRAN
integer function afatypetag(annot_type)
 
integer annot_type

[AN Interface][Top]


ANcreate/afcreate

int32 ANcreate(int32 an_id, uint16 obj_tag, uint16 obj_ref, ann_type annot_type)

an_id
IN:
AN interface identifier returned by ANstart
obj_tag
IN:
Tag of the object to be annotated
obj_ref
IN:
Reference number of the object to be annotated
annot_type
IN:
Type of the data annotation

Purpose
Creates a data annotation for an object.
Return value
Returns the data annotation identifier (ann_id) if successful and FAIL (or -1) otherwise.
Description
ANcreate creates a data annotation of type annot_type for the object specified by its tag, obj_tag, and its reference number, obj_ref. The returned data annotation identifier can represent either a data label or a data description.
 
Valid values for annot_type are AN_DATA_LABEL (or 0) or AN_DATA_DESC (or 1).
 
Use ANcreatef to create a file annotation.
 
Currently, the user must write to a newly-created annotation before creating another annotation of the same type. Creating two consecutive annotations of the same type causes the second call to ANcreate to return FAIL (or -1).

FORTRAN
integer function afcreate(an_id, obj_tag, obj_ref, annot_type)
 
integer an_id, obj_tag, obj_ref, annot_type

[AN Interface][Top]


ANcreatef/affcreate

int32 ANcreatef(int32 an_id, ann_type annot_type)

an_id
IN:
AN interface identifier returned by ANstart
annot_type
IN:
Type of the file annotation

Purpose
Creates a file annotation.
Return value
Returns the file annotation identifier (ann_id) if successful and FAIL (or -1) otherwise.
Description
ANcreatef creates a file annotation of the type specified by the parameter annot_type. The file annotation identifier returned can either represent a file label or a file description.
 
Valid values for annot_type are AN_FILE_LABEL (or 2) and AN_FILE_DESC (or 3).
 
Use ANcreate to create a data annotation.
 
Currently, the user must write to a newly-created annotation before creating another annotation of the same type. Creating two consecutive annotations of the same type causes the second call to ANcreate to return FAIL (or -1).

FORTRAN
integer function affcreate(an_id, annot_type)
 
integer an_id, annot_type

[AN Interface][Top]


ANend/afend

int32 ANend(int32 an_id)

an_id
IN:
AN interface identifier returned by ANstart

Purpose
Terminates access to an AN interface.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
ANend terminates access to the AN interface identified by an_id, which is previously initialized by a call to ANstart. Note that there must be one call to ANend for each call to ANstart.

FORTRAN
integer function afend(an_id)
 
integer an_id

[AN Interface][Top]


ANendaccess/afendaccess

intn ANendaccess(int32 ann_id)

ann_id
IN:
Annotation identifier returned by ANcreate, ANcreatef or ANselect

Purpose
Terminates access to an annotation.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
ANendaccess terminates access to the annotation identified by the parameter ann_id. Note that there must be one call to ANendaccess for every call to ANselect, ANcreate or ANcreatef.

FORTRAN
integer function afendaccess(ann_id)
 
integer ann_id

[AN Interface][Top]


ANfileinfo/affileinfo

intn ANfileinfo(int32 an_id, int32 *n_file_labels, int32 *n_file_descs, int32 *n_data_labels, int32 *n_data_descs)

an_id
IN:
AN interface identifier returned by ANstart
n_file_labels
OUT:
Number of file labels
n_file_descs
OUT:
Number of file descriptions
n_data_labels
OUT:
Number of data labels
n_data_descs
OUT:
Number of data descriptions

Purpose
Retrieves the number of annotations of each type in a file.
Return value
Returns SUCCEED (or 0) if successful or FAIL (or -1) otherwise.
Description
ANfileinfo retrieves the total number of the four kinds of annotations and stores them in the appropriate parameters. The total number of data labels of all data objects in the file is stored in n_data_labels. The total number of data descriptions of all data objects in the file is stored in n_data_descs. The total number of file labels is stored in n_file_labels and the total number of file descriptions in n_file_descs.
 
Note that the numbers of data labels and descriptions refer to the total number of data labels and data descriptions in the file, not for a specific object. Use ANnumann to determine these numbers for a specific object.
 
This routine is generally used to find the range of acceptable indices for ANselect calls.

FORTRAN
integer function affileinfo(an_id, n_file_labels, n_file_descs, n_data_labels, n_data_descs)
 
integer an_id, n_file_labels, n_file_descs
 
integer n_data_labels, n_data_descs

[AN Interface][Top]


ANget_tagref/afgettagref

int32 ANget_tagref(int32 an_id, int32 index, ann_type annot_type, uint16 *ann_tag, uint16 *ann_ref)

an_id
IN:
AN interface identifier returned by ANstart
index
IN:
Index of the annotation
annot_type
IN:
Type of the annotation
ann_tag
OUT:
Tag of the annotation
ann_ref
OUT:
Reference number of the annotation

Purpose
Retrieves the tag/reference number pair of an annotation given its index and type.
Return value
Returns SUCCEED (or 0) if successful or FAIL (or -1) otherwise.
Description
ANget_tagref retrieves the tag and reference number of the annotation identified by its index, the parameter index, and by its annotation type, the parameter annot_type. The tag is stored in the parameter ann_tag and the reference number is stored in the parameter ann_ref.
 
The parameter index is a nonnegative integer and is less than the total number of annotations of type annot_type in the file. Use ANfileinfo to obtain the total number of annotations of each type in the file.
 
The following table lists the valid values of the parameter annot_type in the left column, and the corresponding values of the parameter ann_tag in the right column.

Annotation Type
Annotation Tag
AN_DATA_LABEL (or 0)
DFTAG_DIL (or 104)
AN_DATA_DESC (or 1)
DFTAG_DIA (or 105)
AN_FILE_LABEL (or 2)
DFTAG_FID (or 100)
AN_FILE_DESC (or 3)
DFTAG_FD (or 101)

FORTRAN
integer function afgettagref(an_id, index, annot_type, ann_tag, ann_ref)
 
integer an_id, index, annot_type
 
integer ann_tag, ann_ref

[AN Interface][Top]


ANid2tagref/afidtagref

int32 ANid2tagref(int32 ann_id, uint16 *ann_tag, uint16 *ann_ref)

ann_id
IN:
Annotation identifier returned by ANselect, ANcreate or ANcreatef
ann_tag
OUT:
Tag of the annotation
ann_ref
OUT:
Reference number of the annotation

Purpose
Retrieves the tag/reference number pair of an annotation given its identifier.
Return value
Returns SUCCEED (or 0) if successful or FAIL (or -1) otherwise.
Description
ANid2tagref retrieves the tag/reference number pair of the annotation identified by the parameter ann_id. The tag is stored in the parameter ann_tag and the reference number is stored in the parameter ann_ref.
 
Possible values returned in ann_tag are DFTAG_DIL (or 104) for a data label, DFTAG_DIA (or 105) for a data description, DFTAG_FID (or 100) for a file label and DFTAG_FD (or 101) for a file description.

FORTRAN
integer function afidtagref(ann_id, ann_tag, ann_ref)
 
integer ann_id, ann_tag, ann_ref

[AN Interface][Top]


ANnumann/afnumann

intn ANnumann(int32 an_id, ann_type annot_type, uint16 obj_tag, uint16 obj_ref)

an_id
IN:
AN interface identifier returned by ANstart
annot_type
IN:
Type of the annotation
obj_tag
IN:
Tag of the object
obj_ref
IN:
Reference number of the object

Purpose
Returns the number of annotations of a given type attached to an object.
Return value
Returns the number of annotations or FAIL (or -1) otherwise.
Description
ANnumann returns the total number of annotations that are of type annot_type and that are attached to the object identified by its tag, obj_tag, and its reference number, obj_ref.
 
Since this routine is implemented only to obtain the total number of data annotations and not file annotations, the valid values of annot_type are AN_DATA_LABEL (or 0) and AN_DATA_DESC (or 1). To obtain the total number of file annotations or all data annotations, use ANfileinfo.

FORTRAN
integer function afnumann(an_id, annot_type, obj_tag, obj_ref)
 
integer an_id, obj_tag, obj_ref, annot_type

[AN Interface][Top]


ANreadann/afreadann

int32 ANreadann(int32 ann_id, char* ann_buf, int32 ann_length)

ann_id
IN:
Annotation identifier returned by ANcreate, ANcreatef or ANselect
ann_buf
OUT:
Buffer for the annotation
ann_length
IN:
Length of the buffer ann_buf

Purpose
Reads an annotation.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
ANreadann reads the annotation identified by the parameter ann_id and stores the annotation in the parameter ann_buf.
 
The parameter ann_length specifies the size of the buffer ann_buf. If the length of the file or data label to be read is greater than or equal to ann_length, the label will be truncated to ann_length - 1 characters. If the length of the file or data description is greater than ann_length, the description will be truncated to ann_length characters. The HDF library adds a NULL character to the retrieved label but not to the retrieved description. The user must add a NULL character to the retrieved description if the C library string functions are to operate on this description.

FORTRAN
integer function afreadann(ann_id, ann_buf, ann_length)
 
integer ann_id, ann_length
 
character*(*) ann_buf

[AN Interface][Top]


ANselect/afselect

int32 ANselect(int32 an_id, int32 index, ann_type annot_type)

an_id
IN:
AN interface identifier returned by ANstart
index
IN:
Location of the annotation in the file
annot_type
IN:
Type of the annotation

Purpose
Obtains an existing annotation.
Return value
Returns the annotation identifier (ann_id) if successful or FAIL (or -1) otherwise.
Description
ANselect obtains the identifier of the annotation specified by its index, index, and by its annotation type, annot_type.
 
The parameter index is a nonnegative integer and is less than the total number of annotations of type annot_type in the file. Use ANfileinfo to obtain the total number of annotations of each type in the file.
 
Valid values of annot_type are AN_DATA_LABEL (or 0), AN_DATA_DESC (or 1), AN_FILE_LABEL (or 2), and AN_FILE_DESC (or 3).

FORTRAN
integer function afselect(an_id, index, annot_type)
 
integer an_id, index
 
integer annot_type

[AN Interface][Top]


ANstart/afstart

int32 ANstart(int32 file_id)

file_id
IN:
File identifier returned by Hopen

Purpose
Initializes the AN interface.
Return value
Returns the AN interface identifier (an_id) if successful and FAIL (or -1) otherwise.
Description
ANstart initializes the AN interface for the file identified by the parameter file_id. A call to ANstart is required before any AN functions can be invoked. ANstart is used with the ANend function to define the extent of AN interface session. A call to ANend is required for each call to ANstart.

FORTRAN
integer function afstart(file_id)
 
integer file_id

[AN Interface][Top]


ANtag2atype/aftagatype

ann_type ANtag2atype(uint16 ann_tag)

ann_tag
IN:
Tag of the annotation

Purpose
Returns the annotation type corresponding to an annotation tag.
Return value
Returns the annotation type if successful or AN_UNDEF (or -1) otherwise.
Description
ANtag2atype returns the annotation type that corresponds to the annotation tag specified by the parameter ann_tag.
 
The following table lists the valid values of ann_tag in the left column and the corresponding values of the returned annotation type in the right column.

Annotation Tag
Annotation Type
DFTAG_DIL (or 104)
AN_DATA_LABEL (or 0)
DFTAG_DIA (or 105)
AN_DATA_DESC (or 1)
DFTAG_FID (or 100)
AN_FILE_LABEL (or 2)
DFTAG_FD (or 101)
AN_FILE_DESC (or 3)

FORTRAN
integer function aftagatype(ann_tag)
 
integer ann_tag

[AN Interface][Top]


ANtagref2id/aftagrefid

int32 ANtagref2id(int32 an_id, uint16 ann_tag, uint16 ann_ref)

an_id
IN:
AN interface identifier returned by ANstart
ann_tag
IN:
Tag of the annotation
ann_ref
IN:
Reference number of the annotation

Purpose
Returns the identifier of an annotation given its tag/reference number pair.
Return value
Returns the annotation identifier (ann_id) if successful and FAIL (or -1) otherwise.
Description
ANtagref2id returns the identifier of the annotation specified by its tag, ann_tag, and its reference number, ann_ref.
 
Valid values of ann_tag are DFTAG_DIL (or 104) for a data label, DFTAG_DIA (or 105) for a data description, DFTAG_FID (or 100) for a file label, and DFTAG_FD (or 101) for a file description.

FORTRAN
integer function aftagrefid(an_id, ann_tag, ann_ref)
 
integer an_id, ann_tag, ann_ref

[AN Interface][Top]


ANwriteann/afwriteann

int32 ANwriteann(int32 ann_id, char* ann, int32 ann_length)

ann_id
IN:
Annotation identifier returned by ANcreate, ANcreatef, or ANselect
ann
IN:
Text to be written to the annotation
ann_length
IN:
Length of the annotation text

Purpose
Writes an annotation.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
ANwriteann writes the annotation text provided in the parameter ann to the annotation specified by the parameter ann_id. The parameter ann_length specifies the number of characters in the annotation text.
 
If the annotation has already been written with text, ANwriteann will overwrite the current text.

FORTRAN
integer function afwriteann(ann_id, ann, ann_length)
 
integer ann_id, ann_length
 
character*(*) ann


HDF4.2r4 - February 2009
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group