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
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.
The AN interface writes file labels, file descriptions, data object labels, and data object descriptions according to the following programming model:
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.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.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". 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).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. 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