This chapter describes the routines that are available for storing and retrieving data and file annotations.
Annotation Tags
It is often useful to associate in human readable form information about an HDF file and its data contents, and to keep that information in the same file that contains the data. HDF provides this capability in the form of annotations. An HDF annotation is a sequence of ASCII characters that is associated with one of three types of objects: (1) the file itself, (2) the individual data elements in the file, or (3) the tags that identify the data elements. The current annotation interface supports only the latter type of annotation.
HDF annotations can accommodate a wide variety of types of information, including titles, comments, variable names, parameters, formulas, and source code. Virtually any information that a user might normally put into a notebook concerning the collection, meaning, or use of a file or data can be put into a file's annotations.
Annotations are optionally supplied by a creator or user of an HDF file or data object. Annotations come in two forms: labels, which normally consist of a short string of characters, and descriptions, which can be long and complex bodies of text.
Since each data object in an HDF file is uniquely identified by the combination of a tag and reference number, an annotation is associated with a data object by storing the unique identifier (tag and reference number) together with the annotation.
For example, suppose you wish to annotate a scientific dataset by storing the following annotation with it in the file: "Data from black hole experiment 8/18/87." This statement would be stored in an HDF file as an annotation, and it would have stored with it the tag and reference number for the corresponding scientific dataset. The tag that goes with a scientific dataset is DFTAG_SDG. If you assume that the reference number for this particular dataset is 3, then Figure 5.1 illustrates how the annotation would look in the file.
Figure 5.1Example of an Annotation
The Annotation Interface
The HDF library provides a number of routines for storing and retrieving annotations. These routines are callable from C and FORTRAN programs that have access to the HDF library, version 3.0 and later.
In the following explanations, the term label refers to a string that identifies a data element such as an image or floating-point dataset. Labels can contain only printable ASCII characters and are assumed to be strings in the formal sense. A description, on the other hand, can contain more than one string and therefore, can contain NULL characters (zero bytes), which are normally used to delimit strings in C. In those routines that read or write descriptions, it is always necessary to specify explicitly the lengths of the descriptions.
All of the callable annotations routines begin with the letters DFAN. Since there are some FORTRAN compilers that only accept identifiers with eight or fewer characters, an alternate set of short names has been devised that can be used when programming with one of these compilers. Table 5.1 contains the normal names of the annotation routines, as well as the shorter names. Both sets of names are supported on all HDF-supported machines.(Refer to Appendix E, ╥Rouitne Lists,╙ for a complete listing of HDF routines.)
Table 5.1Long and Short Names for Annotation Routines
Long NameShort NamePurpose
DFANgetlablendagllengets length of label of tag/ref.
DFANgetlabeldaglabgets label of tag/ref.
DFANgetdesclendagdlen gets length of description of tag/ref.
DFANgetdescdagdescgets description of tag/ref.
DFANputlabeldaplabputs label of tag/ref.
DFANputdescdapdescputs description of tag/ref.
DFANlastref*returns ref of last annotation
read or written.
DFANlablistdallistgets list of labels for a
particular tag.
Writing Annotations to an HDF File
DFANputlabel
FORTRAN:
INTEGER FUNCTION DFANputlabel(filename, tag, ref, label)
CHARACTER*(*) filename-name of HDF file to put label in
CHARACTER*(*) label-space to return label in
INTEGER tag, ref-tag/ref of item whose label we want
to store
C:
int DFANputlabel(filename, tag, ref, label)
char *filename;/* name of HDF file to put label in */
uint16 tag, ref;/* tag/ref of item whose label we want to
store*/
char *label;/* space to return label in */
Purpose: To write out a label for the data object with the given tag/ref.
Return value: 0 on success; ╨1 on failure.
DFANputdesc
FORTRAN:
INTEGER FUNCTION DFANputdesc(filename, tag, ref, desc, desclen)
CHARACTER*(*) filename-name of HDF file to put descr in
CHARACTER*(*) desc-description to write to the file
INTEGER tag, ref-tag/ref of item whose description
we want to store
INTEGER desclen-length of description
C:
int DFANputdesc(filename, tag, ref, desc, desclen)
char *filename;/* name of HDF file descr stored in */
uint16 tag, ref;/* tag/ref of item whose descr we want to
store */
char *desc;/* description to write to file */
int32 desclen;/* length of description */
Purpose: To write out a description for the data object with the given tag/ref.
Return value: 0 on success; ╨1 on failure.
The parameter desclen gives the amount of space that is available for storing the annotation.
Example: Adding Annotations to a Scientific Dataset
The example in Figure 5.2 illustrates the use of DFANputlabel and DFANputdesc to write to an HDF file a label and description for a scientific dataset. It is not necessary to write both a label and a description. One or the other or both may be written, depending on your needs.
Figure 5.2Adding Annotations to a Scientific Dataset
C:
#include "df.h"
...
int i, rank, dimsizes[2];
char s[50];
float *data;
...
DFSDadddata("myfile",rank,dimsizes,data);
...
sprintf(s,"Data from black hole experiment\n8/18/87");
i = DFSDlastref();
DFANputlabel("myfile", DFTAG_SDG, i, "black hole");
DFANputdesc("myfile", DFTAG_SDG, i, s, strlen(s));
Remarks:
ÑDFTAG_SDG is the tag that goes with a scientific data group. A scientific data group in an HDF file is a group of tag/refs that describe a scientific dataset.
ÑThe call to DFSDlastref (see the section in this chapter, ╥Getting Annotation Information from a File╙) returns the value of the last reference number written to the file. This call is needed to complete the tag/ref combination that uniquely identifies the desired scientific data group that is being annotated.
ÑThe file df.h that is included with the source contains the number that corresponds to the tag for a scientific dataset. Tags and their numbers are listed in Appendix A, ╥NCSA HDF Tags.╙
Reading Annotations from an HDF File
DFANgetlablen
FORTRAN:
INTEGER FUNCTION DFANgetlablen(filename, tag, ref)
CHARACTER*(*) filename-HDF file with label is stored in
INTEGER tag, ref,-tag/ref of item whose label we want
C:
int32 DFANgetlablen(filename, tag, ref)
char *filename;/* name of HDF file label is stored in */
uint16 tag, ref;/* tag/ref of item whose label we want */
Purpose: To get the length of a label of the data object with the given tag and reference number. This routine allows you to insure that there is enough space allocated for a label before actually loading it.
Return value: The length of label on success; ╨1 on failure.
DFANgetlabel
FORTRAN:
INTEGER FUNCTION DFANgetlabel(filename, tag, ref, label, maxlen)
CHARACTER*(*) filename,-name of HDF file label is stored in
CHARACTER*(*) label-space to return label in
INTEGER tag, ref-tag/ref of item whose label we want
INTEGER maxlen-size of space to return label in
C:
int DFANgetlabel(filename, tag, ref, label, maxlen)
char *filename;/* name of HDF file label is stored in */
uint16 tag, ref;/* tag/ref of item whose label we want */
char *label;/* space to return label in */
int32 maxlen;/* size of space to return label in */
Purpose: To read in the label of the data object with the given tag and reference number.
Return value: 0 on success; ╨1 on failure.
The parameter maxlen gives the amount of space that is available for storing the label. The length of maxlen must be at least one greater than the anticipated length of the label, because a NULL byte is appended to the annotation.
DFANgetdesclen
FORTRAN:
INTEGER FUNCTION DFANgetdesclen(filename, tag, ref)
CHARACTER*(*) filename-name of HDF file descr is stored in
INTEGER tag, ref-tag/ref of item whose descr we want
C:
int32 DFANgetdesclen(filename, tag, ref)
char *filename;/* name of HDF file descr is stored in */
uint16 tag, ref;/*tag/ref of item whose descr we want */
Purpose: To get the length of a description gf the data object with the given tag and reference number. This routine allows you do insure that there is enough space allocated for a description before actually loading it.
Return value: The length of description on success; ╨1 on failure.
DFANgetdesc
FORTRAN:
INTEGER FUNCTION DFANgetdesc(filename, tag, ref, desc, maxlen)
CHARACTER*(*) filename-name of HDF file descr is stored in
CHARACTER*(*) desc-space to return description in
INTEGER tag, ref-tag/ref of item whose descr we want
INTEGER maxlen-size of space to return descr in
C:
int DFANgetdesc(filename, tag, ref, desc, maxlen)
char *filename;/* name of HDF file descr is stored in */
uint16 tag, ref;/*tag/ref of item whose descr we want */
char *desc;/*space to return description in */
int32 maxlen;/*size of space to return descr in */
Purpose: To read in the description of the data object with the given tag and reference number.
Return value: 0 on success; ╨1 on failure.
The parameter maxlen gives the amount of space that is available for storing the description. The length of maxlen must be at least one greater than the anticipated length of the description, because a NULL byte is appended to the annotation.
Example: Reading a Label and Description
This example illustrates the use of DFANgetlabel, DFANgetdesclen, and DFANgetdesc to read from an HDF file a label and description for a scientific dataset.
ÑLower level routines DFopen, DFclose, and DFfindnextref are used here to find the ref number of the first occurrance of the SDG tag.
ÑIn the above example, DFANgetlabel assumes that the label is not more than 10 bytes long. If the program needs to know the length of a label, it can call DFANgetlablen to find this out.
ÑSince the description could be very long, the routine DFANgetdesclen is called to find the space requirements for the description. This space is allocated before calling DFANgetdesc to get the description.
Getting Annotation Information from a File
DFANlastref
Figure 5.4Getting Most Recent Reference Number Written
C:
int DFANlastref()
Purpose: Return most recent reference number written or read.
Returnvalue: The reference number on success; ╨1 on error.
This routine is useful when your program reads or writes a data object, then needs to know the corresponding reference number in order to read or write a corresponding label or description. Figure 5.4 illustrates the use of this routine.
Listing All Labels for a Given Tag
DFANlablist
FORTRAN:
INTEGER FUNCTION DFANlablist(filename, tag, reflist, labellist,
listsize, maxlen, startpos)
CHARACTER*(*) filename-name of HDF file labels stored in
CHARACTER*(*) labellist-array of strings to place labels in
INTEGER tag-tag to find labels for
INTEGER reflist(*)-array to place refs in
INTEGER listsize-size of ref and label lists
INTEGER maxlen-maximum length allowed for label
INTEGER startpos-beginning from the startpos'th
entry, up to listsize entries will
be returned.
C:
int DFANlablist(filename, tag, reflist, labellist, listsize, maxlen, startpos)
char *filename;/* name of HDF file labels stored in */
uint16 tag; /* tag to find labels for */
unit16 reflist[];/* array to place refs in */
char *labellist;/* array of strings to place labels in */
int listsize;/* size of ref and label lists */
int maxlen;/* maximum length allowed for label */
int startpos;/* beginning from the startpos'th entry,
up to listsize entries will be
returned.*/
Purpose: To return a list of all reference numbers and labels for a given tag.
Return value: The number of entries on success; ╨1 on error.
Input parameters are filename, tag, listsize, maxlen and startpos. Listsize gives the number of available entries in the ref and label lists, maxlen is the maximum length allowed for a label, and startpos tells which label to start reading for the given tag. Beginning from the startpos entry and extending to the listsize parameter, entries will be returned. (If startpos is 1, for instance, all labels will be read; if startpos=4, all but the first 3 labels will be read.)
Taken together, the reflist and labellist returned by DFANlablist constitute a directory of all labels for a given tag in a file. The list, labellist, can be displayed to show all of the labels for a given tag. Or, it can be searched to find the ref of a data object with a certain label. Once the ref for a given label is found, the corresponding data object can be accessed by invoking the routine DFgetelement. This routine provides you with a mechanism for direct access to data objects in HDF files.
Example: Getting a List of Labels for Images in a File
The example in Figure 5.5 illustrates the use of DFANlablist to get a list of all labels used for scientific datasets in an HDF file.
Figure 5.5Getting a List of Labels from a File
C:
#include "df.h"
...
int i, nlabels;
uint16 reflist[20];
char labellist[320];
...
printf("\nLabels of scientific datasets in myfile:\n");
nlabels = DFANlablist(argv[1],DFTAG_SDG, reflist,
labellist, 20, 15, 1);
for (i=0; i<nlabels; i++)
printf("\tRef number: %d\tLabel: %s\n",
reflist[i], labellist+(i*15));
}
Remarks:
ÑIn the call to DFANlablist the arrays, reflist and labellist, have to be preallocated with enough space to hold the reference numbers and labels.
ÑThe '20' in the parameter list tells the routine to read, at most, 20 labels and reference numbers. The '15' indicates that each label is to be stored in a 15-byte sequence in the array labellist. The '1' tells the routine to start with the first entry.
* DFANlastref is callable only by C routines. There is no equivalent FORTRAN routine in the HDF library.
