[Top] [Prev] [Next]

10.3 The AN interface

The AN interface permits concurrent operations on a set of annotations that exist in more than one file rather than requiring the program to deal with the annotations on a file-by-file basis.

10.3.1 AN Library Routines

The C routine names of the AN interface are prefaced by the string "AN" and the FORTRAN-77 routine names are prefaced by "af". These routines are divided into the following categories:

The AN routines are listed in Table 10A and are described in more detail in subsequent sections of this chapter.

TABLE 10A - AN Library Routines

Category
Routine Names
Description
C
FORTRAN-77
Access
ANstart afstart Initializes the AN interface (Section 10.3.4 on page 325)

ANcreate afcreate Creates a new data annotation (Section 10.3.4 on page 325)

ANcreatef affcreate Creates a new file annotation (Section 10.3.4 on page 325)

ANselect afselect Obtains an existing annotation (Section 10.5.1 on page 327)

ANendaccess afendaccess Terminates access to an annotation (Section 10.3.4 on page 325)

ANend afend Terminates access to AN interface (Section 10.3.4 on page 325)

Read/write
ANreadann afreadeann Reads an annotation (Section 10.5.2 on page 328)

ANwriteann afwriteann Writes an annotation (Section 10.4 on page 326)

General Inquiry
ANannlen afannlen Returns the length of an annotation (Section 10.6.2 on page 329)

ANannlist afannlist Retrieves the annotation identifiers of an object (Section 10.6.4 on page 330)

ANatype2tag afatypetag Returns the annotation tag corresponding to an annotation type (Section 10.6.8 on page 331)

ANfileinfo affileinfo Retrieves the number of annotations of each type in a file (Section 10.6.1 on page 329)

ANnumann afnumann Returns the number of annotations of the given type attached to an object (Section 10.6.3 on page 329)

ANget_tagref afgettagref Retrieves the tag/reference number pair of an annotation specified by its index (Section 10.6.5 on page 330)

ANid2tagref afidtagref Retrieves the tag/reference number pair of an annotation specified by its identifier (Section 10.6.6 on page 331)

ANtag2atype aftagatype Returns the annotation type corresponding to an annotation tag (Section 10.6.9 on page 332)

ANtagref2id aftagrefid Returns the identifier of an annotation given its tag/reference number pair (Section 10.6.7 on page 331)

10.3.2 Type and Tag Definitions Used in the AN Interface

The AN interface uses the four general annotation types used in HDF: the data label, the data description, the file label and the file description. These annotation types correspondingly map to the AN_DATA_LABEL (or 0), the AN_DATA_DESC (or 1), the AN_FILE_LABEL (or 2) and the AN_FILE_DESC (or 3) definitions. Several routines in the AN interface require one of these type definitions to be passed in as an argument to designate the kind of annotation to be created or accessed.

10.3.3 Programming Model for the AN Interface

As with the GR and SD interfaces, the programming model for the AN interface allows several files to be open concurrently. The contents of these files can be operated on simultaneously as long as the calling program accurately keeps track of each interface. The file and object identifiers returned by the interface. Each object identifier and file identifier must be explicitly disposed of before the termination of the calling program.

The AN interface writes file labels, file descriptions, data object labels, and data object descriptions according to the following programming model:

  1. Open the HDF file.
  2. Initialize the AN interface.
  3. Create a file annotation or a data annotation.
  4. Perform the desired operations on the annotation.
  5. Terminate access to the annotation.
  6. Terminate access to the AN interface.
  7. Close the HDF file.

To create a file or object annotation, the calling program must contain the following AN routine calls:

C:		file_id = Hopen(filename, file_access_mode, num_dds_block);
		an_id = ANstart(file_id);
		ann_id = ANcreatef(an_id, annot_type);
	OR	ann_id = ANcreate(an_id, obj_tag, obj_ref, annot_type);
		<Optional operations>
		status = ANendaccess(ann_id);
		status = ANend(an_id);
		status = Hclose(file_id);
FORTRAN:	file_id = hopen(filename, file_access_mode, num_dds_block)
		an_id = afstart(file_id)
		ann_id = affcreate(an_id, annot_type)
	OR	ann_id = afcreate(an_id, obj_tag, obj_ref, annot_type)
		<Optional operations>
		status = afendaccess(ann_id)
		status = afend(an_id)
		status = hclose(file_id)

10.3.4 Accessing Files and Annotations: ANstart, ANcreatef, and ANcreate

An HDF file must be opened by Hopen before it can be accessed using the AN interface. Hopen is described in Chapter 2, HDF Fundamentals.

ANstart initializes the AN interface for subsequent AN interface operations. ANstart takes one argument, the file identifier, file_id, returned by Hopen, and returns an AN interface identifier, an_id or FAIL (or -1) upon unsuccessful completion.

ANcreatef creates a file label or file description. It takes two parameters: the AN interface identifier, an_id, returned by ANstart, and the type of the file annotation to be created, annot_type. The parameter annot_type must be set to either AN_FILE_LABEL (or 2) or AN_FILE_DESC (or 3). ANcreatef returns the file annotation identifier (ann_id) if successful, and FAIL (or -1) otherwise.

ANcreate creates a data label or data description. It takes four parameters: an_id, obj_tag, obj_ref, and annot_type. The parameter an_id is the AN interface identifier, returned by ANstart. The parameters obj_tag and obj_ref are the tag/reference number pair of the object the annotation will be assigned to. The parameter annot_type specifies the type of the data annotation. It must be set to either AN_DATA_LABEL (or 0) or AN_DATA_DESC (or 1). The annotation type definitions are defined in the header file "hdf.h".

ANcreate returns the data annotation identifier (ann_id) if successful and FAIL (or -1) otherwise. The parameters of ANcreate, ANcreatef, and ANstart are further defined in Table 10B.

10.3.5 Terminating Access to Annotations and Files: ANendaccess and ANend

ANendaccess terminates access to the annotation identified by the parameter ann_id, which is returned by ANcreate or ANcreatef. Any subsequent attempts to access this annotation identifier will result in a value of FAIL being returned. One ANendaccess must be called for every ANcreate, ANcreatef, or ANattach. Each ANendaccess returns either SUCCEED (or 0) or FAIL (or -1).

ANend terminates access to the AN interface identified by the parameter an_id, which is returned by ANstart. Any subsequent attempts to access the AN interface identifier or to use AN routines will result in a value of FAIL being returned.

ANend returns either SUCCEED (or 0) or FAIL (or -1). The parameters of ANendaccess and ANend are defined in Table 10B.

The HDF file must be closed by Hclose after all calls to ANend have been properly made. Hclose is described in Chapter 2, HDF Fundamentals.

TABLE 10B - ANstart, ANcreate, ANcreatef, ANendaccess and ANend Parameter Lists

Routine Name

[Return Type]

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

[int32]

(afstart)
file_id
int32
integer
File identifier

ANcreate

[int32]

(afcreate)
an_id
int32
integer
AN interface identifier

obj_tag
uint16
integer
Tag of the object to be annotated

obj_ref
uint16
integer
Reference number of the object to be annotated

annot_type
ann_type
integer
Data annotation type

ANcreatef

[int32]

(affcreate)
an_id
int32
integer
AN interface identifier

annot_type
ann_type
integer
File annotation type

ANendaccess

[intn]

(afendaccess)
ann_id
int32
integer
Annotation identifier

ANend

[int32]

(afend)
an_id
int32
integer
AN interface identifier



[Top] [Prev] [Next]

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