NCSA HDF Specification and DeveloperÕs Guide Annotations 5-1 National Center for Supercomputing Applications November 8, 1993 5-1 November 8, 1993 5-1 Chapter 5 Annotations Chapter Overview This chapter introduces annotations, HDF data objects used to annotate HDF files and objects. The tags introduced in this chapter are fully described in ChapterÊ6, ÒTag Specifications,Ó and are listed in the table in Appendix A, ÒTags and Extended Tag Labels.Ó General Description It is often useful to attach a text annotation to an HDF file or its contents and to store that annotation in the same HDF file. HDF provides this capability through the annotation data object. The data element of an annotation is a sequence of ASCII characters that can be associated with any of three types of objects: ¥ The file itself ¥ An individual HDF data object in the file ¥ A tag that identifies a data element The current annotation interface supports only the first two. Annotations come in two forms: Label A short, NULL-terminated string. Labels may include no embedded NULLs. Description A longer and more complex body of text of a pre-defined length. Descriptions may contain embedded NULLs. Annotations are never required; they are used strictly at the discretion of the creator or user of an HDF file. Table 5.1 shows the currently defined annotation types and their assigned tags. Table 5.1 Annotation Tags Label Types Description Types File annotations DFTAG_FID DFTAG_FD Object annotations DFTAG_DIL DFTAG_DIA Tag annotations DFTAG_TID DFTAG_TD The annotation interface is fully described in the document NCSA HDF Calling Interfaces and Utilities for Versions 3.2 and earlier and in the NCSA HDF UserÕs Guide and NCSA HDF Reference Manual for Version 3.3 File Annotations Any HDF file can include label annotations (DFTAG_FID) and/or description annotations (DFTAG_FD). The file annotation interface routines provided in the HDF software read and write file labels and file descriptions. Object Annotations HDF data object annotation is complicated by the fact that you must uniquely identify the object being annotated. Since a tag/ref uniquely identifies a data object, the data object that a particular annotation refers to can be identified by storing the object's tag and reference number with the annotation. Note that an HDF annotation is itself a data object, so it has its own DD. This DD has a tag/ref that points to the data element containing the annotation. The annotation data element contains the following information: ¥ The tag of the annotated object ¥ The reference number of the annotated object ¥ The annotation itself For example, suppose you have an HDF file that contains three scientific data sets (SDSs). Each SDS has its own DD consisting of the SDS tag DFTAG_SDG and a unique reference number, as illustrated in Figure 5.1. Figure 5.1 Three SDS Tag/refs Suppose you wish to attach the following annotation to the second SDS: ÒData from black hole experiment 8/18/87.Ó This text will be stored in a description annotation data object. The data element will include the tag/ref, DFTAG_NDG/4, and the annotation itself. Figure 5.2 illustrates the annotation data object. Figure 5.2 Sample Annotation Data Object Getting Reference Numbers for Object Annotations To use annotation routines, you need to know the tags and reference numbers of the objects you wish to annotate. The following routines return the most recent reference number used in either reading or writing the specified type of data object: DFSDlastref SDS data objects DFR8lastref RIS data objects DFPlastref Palettes DFANlastref Annotations Reference numbers for other objects can be obtained with the routine Hfindnextref, a general purpose HDF routine that searches an HDF file sequentially for reference numbers associated with a given tag. These routines are described in the document NCSA HDF Calling Interfaces and Utilities for Versions 3.2 and earlier and in the NCSA HDF UserÕs Guide and NCSA HDF Reference Manual for Version 3.3.