[Top] [Prev]

10.6 Obtaining Annotation Information Using the AN Interface

The HDF library provides various AN routines to obtain annotation information for the purpose of locating either a particular annotation or a set of annotations that correspond to a set of search criteria. The following sections describe these AN routines.

10.6.1 Obtaining the Number of Annotations: ANfileinfo

ANfileinfo retrieves the total number of file labels, file descriptions, data labels, and data descriptions in the file identified by the parameter an_id. The syntax for ANfileinfo is as follows:

C:		status = ANfileinfo(an_id, &n_file_labels, &n_file_descs, &n_data_labels, &n_data_descs);
FORTRAN:	status = affileinfo(an_id, n_file_labels, n_file_descs, n_data_labels, n_data_descs)
The retrieved information will be stored in the parameters n_file_labels, n_file_descs, n_data_labels, and n_data_descs, respectively. They can also be used as loop boundaries.

ANfileinfo returns either SUCCEED (or 0) or FAIL (or -1). The parameters of ANfileinfo are further described in Table 10E.

10.6.2 Getting the Length of an Annotation: ANannlen

ANannlen returns either the length of the annotation, identified by the parameter ann_id, or FAIL (or -1) upon unsuccessful completion. The syntax for ANannlen is as follows:

C:		ann_len = ANannlen(ann_id);
FORTRAN:	ann_len = afannlen(ann_id)
The parameters of ANannlen are further described in Table 10E.

TABLE 10E - ANfileinfo and ANannlen Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
ANfileinfo

[intn]

(affileinfo)
an_id
int32
integer
AN interface identifier

n_file_labels
int32 *
integer
Number of file labels in the file

n_file_descs
int32 *
integer
Number of file descriptions in the file

n_data_labels
int32 *
integer
Number of data labels in the file

n_data_descs
int32 *
integer
Number of data descriptions in the file

ANannlen

[int32]

(afannlen)
ann_id
int32
integer
Annotation identifier

10.6.3 Obtaining the Number of Specifically-typed Annotations of a Data Object: ANnumann

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 reference number, obj_ref. The syntax for ANnumann is as follows:

C:		ann_num = ANnumann(an_id, annot_type, obj_tag, obj_ref);
FORTRAN:	ann_num = afnumann(an_id, annot_type, obj_tag, obj_ref)
As 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.

ANnumann returns the total number of qualified annotations or FAIL (or -1). The parameters of ANnumann are further described in Table 10F.

10.6.4 Obtaining the List of Specifically-typed Annotation Identifiers of a Data Object: ANannlist

ANannlist retrieves the annotation identifiers for all of the annotations that are of type annot_type and belong to the object identified by its tag, obj_tag, and its reference number, obj_ref. The syntax for ANannlist is as follows:

C:		status = ANannlist(an_id, annot_type, obj_tag, obj_ref, ann_list);
FORTRAN:	status = afselect(an_id, annot_type, obj_tag, obj_ref, ann_list)
The identifiers of the retrieved annotations are stored in the parameter ann_list. The routine ANnumann can be used to obtain the number of annotations to be retrieved for dynamic memory allocation.

ANannlist returns either SUCCEED (or 0) or FAIL (or -1). The parameters of ANannlist are further described in Table 10F.

TABLE 10F - ANnumann and ANannlist Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
ANnumann

[intn]

(afnumann)
an_id
int32
integer
AN interface identifier

annot_type
ann_type
integer
Type of the annotation

obj_tag
uint16
integer
Tag of the object the annotation is attached to

obj_ref
uint16
integer
Reference number of the object the annotation is attached to

ANannlist

[intn]

(afannlist)
an_id
int32
integer
AN interface identifier

annot_type
ann_type
integer
Type of the annotation

obj_tag
uint16
integer
Tag of the object the annotation is attached to

obj_ref
uint16
integer
Reference number of the object the annotation is attached to

ann_list
int32 *
integer (*)
Buffer for returned annotation identifiers that match the search criteria

10.6.5 Obtaining the Tag/Reference Number Pair of the Specified Annotation Index and Type: ANget_tagref

ANget_tagref retrieves the tag and reference number of the annotation identified by its index, specified by the parameter index, and by the annotation type, specified by the parameter annot_type. The syntax for ANget_tagref is as follows:

C:		status = ANget_tagref(an_id, index, annot_type, &ann_tag, &ann_ref);
FORTRAN:	status = afgettagref(an_id, index, annot_type, ann_tag, ann_ref)
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 value 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 type annot_type in the file.

The value of annot_type can be either AN_DATA_LABEL (or 0), AN_DATA_DESC (or 1), AN_FILE_LABEL (or 2), or AN_FILE_DESC (or 3).

ANget_tagref returns either SUCCEED (or 0) or FAIL (or -1). The parameters of ANget_tagref are further described in Table 10G on page 332.

10.6.6 Obtaining the Tag/Reference Number Pair from a Specified Annotation Identifier: ANid2tagref

ANid2tagref retrieves the tag/reference number pair of the annotation identified by the parameter ann_id. The syntax for ANid2tagref is as follows:

C:		status = ANid2tagref(ann_id, &ann_tag, &ann_ref);
FORTRAN:	status = afidtagref(ann_id, ann_tag, ann_ref)
ANid2tagref stores the retrieved tag and reference number into the parameters ann_tag and 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.

ANid2tagref returns either SUCCEED (or 0) or FAIL (or -1). The parameters of ANid2tagref are further described in Table 10G on page 332.

10.6.7 Obtaining the Annotation Identifier from a Specified Tag/Reference Number Pair: ANtagref2id

ANtagref2id routine returns the identifier of the annotation that is specified by its tag/reference number pair or FAIL (or -1). The syntax for ANtagref2id is as follows:

C:		ann_id = ANtagref2id(an_id, ann_tag, ann_ref);
FORTRAN:	ann_id = aftagrefid(an_id, ann_tag, ann_ref)
The parameters of ANtagref2id are further described in Table 10G on page 332.

10.6.8 Obtaining an Annotation Tag from a Specified Annotation Type: ANatype2tag

ANatype2tag returns the tag that corresponds to the annotation type specified by the parameter annot_type if successful, or DFTAG_NULL (or 0) otherwise. The syntax for ANatype2tag is as follows:

C:		ann_tag = ANatype2tag(annot_type);
FORTRAN:	ann_tag = afatypetag(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)

The parameters of ANatype2tag are further described in Table 10G.

10.6.9 Obtaining an Annotation Type from a Specified Object Tag: ANtag2atype

ANtag2atype returns the annotation type corresponding to the annotation tag ann_tag if successful, or AN_UNDEF (or -1) otherwise. The syntax for ANtag2atype is as follows:

C:		annot_type = ANtag2atype(ann_tag);
FORTRAN:	annot_type = aftagatype(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)

The parameters of ANtag2atype are further described in Table 10G.

TABLE 10G - ANget_tagref, ANid2tagref, ANtagref2id, ANatype2tag, and ANtag2atype Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
ANget_tagref

[int32]

(afgettagref)
an_id
int32
integer
AN interface identifier

ann_index
int32
integer
Index of the annotation

annot_type
ann_type
integer
Annotation type of the annotation

ann_tag
uint16 *
integer
Tag of the annotation

ann_ref
uint16 *
integer
Reference number of the annotation

ANid2tagref

[int32]

(afidtagref)
ann_id
int32
integer
Identifier of the annotation

ann_tag
uint16 *
integer
Tag of the annotation

ann_ref
uint16 *
integer
Reference number of the annotation

ANtagref2id

[int32]

(aftagrefid)
an_id
int32
integer
AN interface identifier

ann_tag
uint16
integer
Tag of the annotation

ann_ref
uint16
integer
Reference number of the annotation

ANatype2tag

[uint16]

(afatypetag)
annot_type
ann_type
integer
Annotation type

ANtag2atype

[ann_type]

(aftagatype)
ann_tag
uint16
integer
Annotation tag

EXAMPLE 3. Obtaining Annotation Information

This example illustrates the use of ANnumann/afnumann to obtain the number of annotations of an object, ANannlist/afannlist to obtain the list of annotation identifiers, and ANid2tagref/afidtagref, ANatype2tag/afatypetag, and ANtag2atype/aftagatype to perform some identifier conversions.

In this example, the program locates the vgroup named "AN Vgroup" that was created in the file "General_HDFobjects.hdf" by Example 1. The program then gets the number of data descriptions that this vgroup has and the list of their identifiers. If there are any identifers in the list, the program displays the corresponding reference numbers. Finally, the program makes two simple conversions, from an annotation type to a tag and from a tag to an annotation type, and displays the results.

C version

FORTRAN-77 version





[Top] [Prev]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 05/19/99, NCSA HDF Development Group.