[Top] [Prev] [Next]

10.5 Reading Annotations Using the AN Interface

Reading an annotation is done by first selecting the desired annotation of the appropriate type using ANselect, then reading the annotation text using ANreadann. These two routines are described in this section.

10.5.1 Selecting an Annotation: ANselect

ANselect obtains the identifier of the annotation specified by its index, index, and by its annotation type, annot_type. The syntax for ANselect is as follows:

C:		ann_id = ANselect(an_id, index, annot_type);
FORTRAN:	ann_id = afselect(an_id, index, 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, described in Section 10.6.1 on page 329, to obtain the total number of annotations of type annot_type in the file.

Possible valid values of annot_type are AN_DATA_LABEL (or 0) for a data label, AN_DATA_DESC (or 1) for a data description, AN_FILE_LABEL (or 2) for a file label, and AN_FILE_DESC (or 3) for a file description.

ANselect returns an annotation identifier or FAIL (or -1) upon unsuccessful completion. The parameters of ANselect are further described in Vdata .

10.5.2 Reading an Annotation: ANreadann

ANreadann reads the annotation specified by the parameter ann_id and stores the annotation text in the parameter ann_buf. The syntax for ANreadann is as follows

C:		status = ANreadann(ann_id, ann_buf, ann_length);
FORTRAN:	status = afreadann(ann_id, ann_buf, ann_length)
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 description. The user must add a NULL character to the retrieved description if the C library string functions are to operate on this description.

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

TABLE 10D - ANselect and ANreadann Parameter Lists

Routine Name

[Return Type]

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

[int32]

(afselect)
an_id
int32
integer
AN interface identifier

index
int32
integer
Index of the annotation

annot_type
ann_type
integer
Type of the annotation

ANreadann

[int32]

(afreadann)
ann_id
int32
integer
Annotation identifier

ann_buf
char *
character*(*)
Buffer for the returned annotation text

ann_length
int32
integer
Number of characters to be retrieved from the annotation

EXAMPLE 2. Reading File and Data Annotations

This example illustrates the use of ANfileinfo/affileinfo to get the number of data and file annotations in the file, ANselect/afselect to get an annotation, ANannlen/afannlen to get the length of the annotation, and ANreadann/afreadann to read the contents of the annotation.

In this example, the program reads some of the annotations created in the file "General_HDFobjects.hdf" by Example 1. The program first gets the information on the annotations in the file so that the number of existing annotations of each kind is available prior to reading. The program then gets the length of each annotation and allocates sufficient space for the contents of the annotation to be read. For the simplicity of this example, only the data labels are read. Any other annotations can be read by adding the for loop with appropriate values as noted below.

This example uses the ANfileinfo/affileinfo routine to get annotation information. This rouitne is described in the Section 10.6.1

C version

FORTRAN-77 version

	


[Top] [Prev] [Next]

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