[Top] [Prev] [Next] [Bottom]

10.13 Obtaining Annotation Information Using the AN Interface

In some cases the HDF programmer must get annotation information for the purpose of either locating a particular annotation or set of annotations that correspond to a set of search criteria. The following sections describe the AN routines designed to do this.

10.13.1 Selecting an Annotation: ANselect

The ANselect function returns the ann_id corresponding to the index passed into the function as the second index parameter and the annotation type passed in as the third annot_type parameter. The interface identifier returned by ANstart must also be provided. The annot_type parameter must be one of the annotation type definitions listed in Section 10.9.2 on page 265. Upon unsuccessful completion ANselect returns a FAIL status code.

TABLE 10N ANselect Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANselect

(afselect)

an_id

int32

integer

AN interface identifier.

index

int32

integer

Index of the target annotation.

annot_type

int32

integer

Type of the target annotation.

10.13.2 Obtaining General Annotation Information: ANfileinfo

ANfileinfo returns the total number of file labels, file descriptors, data labels and data descriptors in the current file. The only input parameter required by ANfileinfo is the an_id passed as its first argument. The information provided by ANfileinfo can also be used as object indices. As such they can be passed into a call to ANselect within a loop for the purpose of accessing all annotations in a file.

The ANfileinfo routine returns either a SUCCEED or FAIL return code. These status codes are defined in the "hdf.h" header file.

TABLE 10O ANfileinfo Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANfileinfo

(affileinfo)

an_id

int32

integer

AN interface identifier.

n_file_label

int32 *

integer (*)

Number of file labels in the file.

n_file_desc

int32 *

integer (*)

Number of file descriptors in the file.

n_data_label

int32 *

integer (*)

Number of data labels in the file.

n_data_desc

int32 *

integer (*)

Number of data descriptors in the file.

10.13.3 Getting the Length of an Annotation: ANannlen

The ANannlen function returns either the length of the annotation corresponding to the ann_id passed in the function as it's only argument or a FAIL return code upon unsuccessful completion.

TABLE 10P ANannlen Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANannlen

(afannlen)

ann_id

int32

integer

Identifier of the target annotation.

EXAMPLE 9. Reading File Labels

The following examples reads the file label annotation in the HDF file named "Example6.hdf".

C:

#include "hdf.h"

main( )
{

	int32 file_id, an_id, ann_id, ann_idx, i, ann_length;
	int32 n_file_label, n_file_desc, n_data_label, n_data_desc;
	int32 status;
	char *ann_buf;

	/* Open the HDF file for reading. */
	file_id = Hopen("Example6.hdf", DFACC_RDWR, 0);

	/* Initialize the AN interface and obtain an interface id. */
	an_id = ANstart(file_id);

	/* Get the annotation information. */
	status = ANfileinfo(an_id, &n_file_label, &n_file_desc, \
					&n_data_label, &n_data_desc);

	/* Get the file labels. */
	for (i = 0; i < n_file_label; i++) {
   
		/* Get the identifier for the current file label. */
		ann_id = ANselect(an_id, i, AN_FILE_LABEL);

		/* Get the length of the file label. */
		ann_length = ANannlen(ann_id);

		/* Get the length of the file label. */
		ann_buf = HDmalloc(ann_length * sizeof(char));

		/* Read the file label. */
		status = ANreadann(ann_id, ann_buf, ann_length);
	}

	/* Terminate access to the annotation. */
	status = ANendaccess(ann_id);

	/* Terminate access to the AN interface. */
	status = ANend(an_id);

	/* Close the file. */
	status = Hclose(file_id);

}


 FORTRAN:	

PROGRAM GET LABELS integer*4 afstart, affileinfo, afselect, afendaccess, afend integer*4 afannlen, afendaccess, afend, hopen, hclose integer*4 status, file_id, an_id, ann_id, i character ann_buf(50) integer*4 DFACC_RDWR, AN_FILE_LABEL parameter (DFACC_RDWR = 3, AN_FILE_LABEL = 2) C Open the HDF file. file_id = hopen('Example6.hdf', DFACC_RDWR, 0) C Initialize the AN interface and obtain an interface id. an_id = afstart(file_id) C Get the annotation information. status = affileinfo(an_id, n_file_label, n_file_desc, + n_data_label, n_data_desc) C Get file label lengths. do 10 i = 0, n_file_label C Get the identifier for the current index. ann_id = afselect(i, AN_FILE_LABEL) C Get the length of the annotation for the current id. ann_length = afannlen(ann_id) C Read the file label. status = afreadann(ann_id, ann_buf, ann_length) 10 continue C Terminate access to the annotation. status = afendaccess(ann_id) C Terminate access to the AN interface. status = afend(an_id) C Close the file. status = hclose(file_id) end

10.13.4 Obtaining the Number of Annotations Corresponding to Given Search Criteria: ANnumann

The ANnumann routine returns the total number of annotations in the file that satisfy the search criteria supplied in the latter three parameters of the call. These parameters are: type, which is set to one of the type definitions listed in Section 10.9.2 on page 265, obj_tag, which is the tag of the object the annotation to be searched for is attached to, and obj_ref, which is the reference number of the object the annotation to be searched for is attached to. Upon unsuccessful completion ANnumann returns a FAIL status code.

TABLE 10Q ANnumann Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANnumann

(afnumann)

an_id

int32

integer

AN interface identifier.

annot_type

int32

integer

Type of the target annotation.

obj_tag

uint16

integer

Tag of the object the target annotation is attached to.

obj_ref

uint16

integer

Reference number of the object the target annotation is attached to.

10.13.5 Obtaining the List of Annotations Corresponding to Given Search Criteria: ANannlist

The ANannlist routine is the counterpart to ANnumann in that, instead of returning the number of annotations that satisfy a given set of search criteria supplied in the latter three parameters of the call, it returns the list of annotation identifers in the file that satisfy the search criteria. ANannlist's second, third and fourth parameters are the same as ANnumann's. ANannlist returns the list in it's fifth parameter. Upon unsuccessful completion ANannlist also returns a FAIL status code.

TABLE 10R ANannlist Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANannlist

(afannlist)

an_id

int32

integer

AN interface identifier.

annot_type

int32

integer

Type of the target annotation.

obj_tag

uint16

integer

Tag of the object the target annotation is attached to.

obj_ref

uint16

integer

Reference number of the object the target annotation is attached to.

ann_list

int32 *

integer (*)

Buffer for returned annotation identifiers that match the search criteria.

EXAMPLE 10. Returning the Number of and the List of Object Descriptions

The following examples return the total number and list of object descriptions in the "Example6.hdf" file. The DFTAG_DIA tag is defined in the "htags.h" header file as a object description tag. The AN_DATA_DESC definition is in the "mfan.h" header file.

C:

#include "hdf.h"

main( )
{
	int32 status, file_id, an_id, ann_id, ann_num;
	int32 *ann_list;
	uint16 obj_tag, obj_ref;
	int32 annot_type;

	/* Create the HDF file. */
	file_id = Hopen("Example6.hdf", DFACC_RDWR, 0);

	/* Initialize the AN interface and obtain an interface id. */
	an_id = ANstart(file_id);

	/* Set the annotation type to be a data description. */
	annot_type = AN_DATA_DESC;

	/* Set the tag to be a data identifier. */
	obj_tag = DFTAG_DIA;

	/* Set the reference number to be the first object. */
	obj_ref = 0;

	/* Get the number of object descriptions. */
	ann_num = ANnumann(an_id, annot_type, obj_tag, obj_ref);

	/* Allocate space for the annotation identifier. */
	ann_list = HDmalloc(ann_num * sizeof(int32));

	/* Get the list of object descriptions. */
	status = ANannlist(an_id, annot_type, obj_tag, obj_ref, ann_list);

	/* Terminate access to the annotation. */
	status = ANendaccess(ann_id);

	/* Terminate access to the AN interface. */
	status = ANend(an_id);

	/* Free the space allocated for the annotation identifier. */
	HDfree(ann_list);

	/* Close the file. */
	status = Hclose(file_id);

}


 FORTRAN:	

PROGRAM GET DATA DESC LIST integer hopen, afstart, affcreate, afendaccess, afend integer hclose status, file_id, an_id, ann_id integer annot_type, obj_tag, ann_num integer ann_list(50) integer*4 DFACC_CREATE, AN_DATA_DESC, DFTAG_DIA parameter (DFACC_CREATE = 4, AN_DATA_DESC = 1, + DFTAG_DIA = 105) C Open the HDF file. file_id = hopen('Example6.hdf', DFACC_RDWR, 0) C Initialize the AN interface and obtain an interface id. an_id = afstart(file_id) C Set the annotation type to be a data description. annot_type = AN_DATA_DESC C Set the tag to be a data identifier description. obj_tag = DFTAG_DIA C Set the reference number to be the first object. obj_ref = 0 C Get the number of file labels. ann_num = afnumann(an_id, annot_type, obj_tag, obj_ref) C Get the list of file labels. status = afannlist(an_id, annot_type, obj_tag, obj_ref, ann_list) C Terminate access to the annotation. status = afendaccess(ann_id) C Terminate access to the AN interface. status = afend(an_id) C Close the file. status = hclose(file_id) end

10.13.6 Obtaining the Tag/Reference Number Pair From a Specified Annotation Identifiers: ANget_tagref

The ANget_tagref routine returns the tag/reference number pair of the annotation identified by the specfied annotation identifier, index and annotation type.

The ann_index parameter is zero-based. The ann_type parameter value can be either AN_DATA_LABEL, AN_FILE_LABEL, AN_DATA_DESC or AN_FILE_DESC.

TABLE 10S ANget_tagref Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANget_tagref

(afgettagref)

an_id

int32

integer

AN interface identifier.

ann_index

int32 *

integer

Index of the target annotation.

ann_type

int32 *

integer

Annotation type of the target annotation.

ann_tag

uint16 *

integer

Tag of the target annotation.

ann_ref

uint16 *

integer

Reference number of the target annotation.

10.13.7 Obtaining the Tag/Reference Number Pair From a Specified Annotation Identifier: ANid2tagref

The ANid2tagref routine returns the tag/reference number pair of the annotation that is also identified by the specified annotation id.

ANid2tagref returns the tag/reference number pair if successful and FAIL (or -1) otherwise.

TABLE 10T ANid2tagref Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANid2tagref

(afidtagref)

an_id

int32

integer

AN interface identifier.

ann_tag

uint16 *

integer

Tag of the target annotation.

ann_ref

uint16 *

integer

Reference number of the target annotation.

10.13.8 Obtaining the Annotation Identifier From a Specified Tag/Reference Number Pair: ANtagref2id

The ANtagref2id routine returns the identifier of the annotation that is also identified by the specified tag/reference number pair.

ANtagref2id returns the annotation identifier if successful and FAIL (or -1) otherwise.

TABLE 10U ANtagref2id Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANtagref2id

(aftagrefid)

an_id

int32

integer

AN interface identifier.

ann_tag

uint16 *

integer

Type of the target annotation.

ann_ref

uint16

integer

Tag of the object the target annotation is attached to.

10.13.9 Obtaining an Object Tag From a Specified Annotation Type: ANatype2tag

The ANatype2tag routine returns the object tag (prefaced by DFTAG_) corresponding to a given annotation type (prefaced by AN_).

Return values are DFTAG_FID, DFTAG_FD, DFTAG_DIL or DFTAG_DIA.

TABLE 10V ANatype2tag Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANatype2tag

tag

int32 *

integer

Object type.

10.13.10 Obtaining an Annotation Type From a Specified Object Tag: ANtag2atype

The ANtag2atype routine returns theannotation type (prefaced by AN_) corresponding to a given object tag (prefaced by DFTAG_).

Return values are AN_FILE_LABEL, AN_FILE_DESC, AN_DATA_LABEL, AN_DATA_DESC.

TABLE 10W ANtag2atype Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANtag2atype

(aftagatype)

ann_type

uint16

integer

Annotation type.



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.