# HDF User’s Guide

Version 4.2r4

[Top] [Prev][Next]

> create_annotation.c

>     #include "hdf.h"
>     #define  FILE_NAME      "General_HDFobjects.hdf"
>     #define  VG_NAME        "AN Vgroup"
>     #define  FILE_LABEL_TXT "General HDF objects"
>     #define  FILE_DESC_TXT  "This is an HDF file that contains general HDF objects"
>     #define  DATA_LABEL_TXT "Common AN Vgroup"
>     #define  DATA_DESC_TXT  "This is a vgroup that is used to test data annotations"
>     main( )
>     {
>        /************************* Variable declaration **************************/
>        intn   status_n;     /* returned status for functions returning an intn  */
>        int32  status_32,    /* returned status for functions returning an int32 */
>               file_id,      /* HDF file identifier */
>               an_id,        /* AN interface identifier */
>               file_label_id,  /* file label identifier */
>               file_desc_id,   /* file description identifier */
>               data_label_id,  /* data label identifier */
>               data_desc_id,   /* data description identifier */
>               vgroup_id;
>        uint16 vgroup_tag, vgroup_ref;
>        /********************** End of variable declaration **********************/
>        /*
>        * Create the HDF file.
>        */
>        file_id = Hopen (FILE_NAME, DFACC_CREATE, 0);
>        /*
>        * Initialize the AN interface.
>        */
>        an_id = ANstart(file_id);
>        /*
>        * Create the file label.
>        */
>        file_label_id = ANcreatef(an_id, AN_FILE_LABEL);
>        /*
>        * Write the annotations to the file label.
>        */
>        status_32 = ANwriteann(file_label_id, FILE_LABEL_TXT,
>                               strlen (FILE_LABEL_TXT));
>        /*
>        * Create file description.
>        */
>        file_desc_id = ANcreatef(an_id, AN_FILE_DESC);
>        /*
>        * Write the annotation to the file description.
>        */
>        status_32 = ANwriteann(file_desc_id, FILE_DESC_TXT,
>                               strlen (FILE_DESC_TXT));
>        /*
>        * Create a vgroup in the V interface.  Note that the vgroup's ref number
>        * is set to -1 for creating and the access mode is "w" for writing.
>        */
>        status_n = Vstart(file_id);
>        vgroup_id = Vattach(file_id, -1, "w");
>        status_32 = Vsetname (vgroup_id, VG_NAME);
>        /*
>        * Obtain the tag and ref number of the vgroup for subsequent
>        * references.
>        */
>        vgroup_tag = (uint16) VQuerytag (vgroup_id);
>        vgroup_ref = (uint16) VQueryref (vgroup_id);
>        /*
>        * Create the data label for the vgroup identified by its tag
>        * and ref number.
>        */
>        data_label_id = ANcreate(an_id, vgroup_tag, vgroup_ref, AN_DATA_LABEL);
>        /*
>        * Write the annotation text to the data label.
>        */
>        status_32 = ANwriteann(data_label_id, DATA_LABEL_TXT,
>                               strlen(DATA_LABEL_TXT));
>        /*
>        * Create the data description for the vgroup identified by its tag
>        * and ref number.
>        */
>        data_desc_id = ANcreate(an_id, vgroup_tag, vgroup_ref, AN_DATA_DESC);
>        /*
>        * Write the annotation text to the data description.
>        */
>        status_32 = ANwriteann(data_desc_id, DATA_DESC_TXT, strlen(DATA_DESC_TXT));
>        /*
>        * Teminate access to the vgroup and to the V interface.
>        */
>        status_32 = Vdetach(vgroup_id);
>        status_n = Vend(file_id);
>        /*
>        * Terminate access to each annotation explicitly.
>        */
>        status_n = ANendaccess(file_label_id);
>        status_n = ANendaccess(file_desc_id);
>        status_n = ANendaccess(data_label_id);
>        status_n = ANendaccess(data_desc_id);
>        /*
>        * Terminate access to the AN interface and close the HDF file.
>        */
>        status_32 = ANend(an_id);
>        status_n = Hclose(file_id);
>     }

> create_annotation.f

>           program create_annotation
>           implicit none
>     C
>     C     Parameter declaration
>     C
>           character*22 FILE_NAME
>           character*9  VG_NAME
>           character*19 FILE_LABEL_TXT
>           character*53 FILE_DESC_TXT
>           character*16 DATA_LABEL_TXT
>           character*54 DATA_DESC_TXT
>     C
>           parameter (FILE_NAME      = 'General_HDFobjects.hdf',
>          +           VG_NAME        = 'AN Vgroup',
>          +           FILE_LABEL_TXT = 'General HDF objects',
>          +           DATA_LABEL_TXT = 'Common AN Vgroup',
>          +           FILE_DESC_TXT  =
>          + 'This is an HDF file that contains general HDF objects',
>          +           DATA_DESC_TXT  =
>          + 'This is a vgroup that is used to test data annotations')
>           integer DFACC_CREATE
>           parameter (DFACC_CREATE = 4)
>           integer AN_FILE_LABEL, AN_FILE_DESC, AN_DATA_LABEL, AN_DATA_DESC
>           parameter (AN_FILE_LABEL = 2,
>          +           AN_FILE_DESC  = 3,
>          +           AN_DATA_LABEL = 0,
>          +           AN_DATA_DESC  = 1)
>     C
>     C     Function declaration
>     C
>           integer hopen, hclose
>           integer afstart, affcreate, afwriteann, afcreate,
>          +        afendaccess, afend
>           integer vfstart, vfatch, vfsnam, vqref, vqtag, vfdtch, vfend
>     C
>     C**** Variable declaration *******************************************
>     C
>           integer status
>           integer file_id, an_id
>           integer file_label_id, file_desc_id
>           integer data_label_id, data_desc_id
>           integer vgroup_id, vgroup_tag, vgroup_ref
>     C
>     C**** End of variable declaration ************************************
>     C
>     C
>     C     Create the HDF file.
>     C
>           file_id = hopen(FILE_NAME, DFACC_CREATE, 0)
>     C
>     C     Initialize the AN interface.
>     C
>           an_id = afstart(file_id)
>     C
>     C     Create the file label.
>     C
>           file_label_id = affcreate(an_id, AN_FILE_LABEL)
>     C
>     C     Write the annotation to the file label.
>     C
>           status = afwriteann(file_label_id, FILE_LABEL_TXT,
>          +                    len(FILE_LABEL_TXT))
>     C
>     C     Create file description.
>     C
>           file_desc_id = affcreate(an_id, AN_FILE_DESC)
>     C
>     C     Write the annotation to the file description.
>     C
>           status = afwriteann(file_desc_id, FILE_DESC_TXT,
>          +                    len(FILE_DESC_TXT))
>     C
>     C     Create a vgroup in the file. Note that the vgroup's ref number is
>     C     set to -1 for creating and the access mode is 'w' for writing.
>     C
>           status    = vfstart(file_id)
>           vgroup_id = vfatch(file_id, -1, 'w')
>           status    = vfsnam(vgroup_id, VG_NAME)
>     C
>     C     Obtain the tag and reference number of the vgroup for subsequent
>     C     references.
>     C
>           vgroup_ref = vqref(vgroup_id)
>           vgroup_tag = vqtag(vgroup_id)
>     C
>     C     Create the data label for the vgroup identified by its tag and ref
>     C     number.
>     C
>           data_label_id = afcreate(an_id, vgroup_tag, vgroup_ref,
>          +                          AN_DATA_LABEL)
>     C
>     C     Write the annotation text to the data label.
>     C
>           status = afwriteann(data_label_id, DATA_LABEL_TXT,
>          +                    len(DATA_LABEL_TXT))

>     C
>     C     Create the data description for the vgroup identified by its tag and ref.
>     C
>           data_desc_id = afcreate(an_id, vgroup_tag, vgroup_ref,
>          +                        AN_DATA_DESC)
>     C
>     C     Write the annotation text to the data description.
>     C
>           status = afwriteann(data_desc_id, DATA_DESC_TXT,
>          +                    len(DATA_DESC_TXT))
>     C
>     C     Terminate access to the vgroup and to the V interface.
>     C
>           status = vfdtch(vgroup_id)
>           status = vfend(file_id)
>     C
>     C     Terminate access to each annotation explicitly.
>     C
>           status = afendaccess(file_label_id)
>           status = afendaccess(file_desc_id)
>           status = afendaccess(data_label_id)
>           status = afendaccess(data_desc_id)
>     C
>     C     Terminate access to the AN interface and close the HDF file.
>     C
>           status = afend(an_id)
>           status = hclose(file_id)
>           end

> read_annotation.c

>     #include "hdf.h"
>     #define  FILE_NAME   "General_HDFobjects.hdf"
>     main( )
>     {
>        /************************* Variable declaration **************************/
>        intn  status_n;      /* returned status for functions returning an intn  */
>        int32 status_32,     /* returned status for functions returning an int32 */
>              file_id,       /* HDF file identifier */
>              an_id,         /* AN interface identifier */
>              ann_id,        /* an annotation identifier */
>              index,         /* position of an annotation in all of the same type*/
>              ann_length,    /* length of the text in an annotation */
>              n_file_labels, n_file_descs, n_data_labels, n_data_descs;
>        char *ann_buf;       /* buffer to hold the read annotation */
>        /********************** End of variable declaration **********************/
>        /*
>        * Open the HDF file.
>        */
>        file_id = Hopen (FILE_NAME, DFACC_READ, 0);
>        /*
>        * Initialize the AN interface.
>        */
>        an_id = ANstart (file_id);
>        /*
>        * Get the annotation information, e.g., the numbers of file labels, file
>        * descriptions, data labels, and data descriptions.
>        */
>        status_n = ANfileinfo (an_id, &n_file_labels, &n_file_descs,
>                             &n_data_labels, &n_data_descs);
>        /*
>        * Get the data labels.  Note that this for loop can be used to
>        * obtain the contents of each kind of annotation with the appropriate
>        * number of annotations and the type of annotation, i.e., replace
>        * n_data_labels with n_file_labels, n_file_descs, or n_data_descs, and
>        * AN_DATA_LABEL with AN_FILE_LABEL, AN_FILE_DESC, or AN_DATA_DESC,
>        * respectively.
>        */
>        for (index = 0; index < n_data_labels; index++)
>        {
>           /*
>           * Get the identifier of the current data label.
>           */
>           ann_id = ANselect (an_id, index, AN_DATA_LABEL);
>           /*
>           * Get the length of the data label.
>           */
>           ann_length = ANannlen (ann_id);
>           /*
>           * Allocate space for the buffer to hold the data label text.
>           */
>           ann_buf = malloc ((ann_length+1) * sizeof (char));
>           /*
>           * Read and display the data label.  Note that the size of the buffer,
>           * i.e., the third parameter, is 1 character more than the length of
>           * the data label; that is for the null character.  It is not the case
>           * when a description is retrieved because the description does not
>           * necessarily end with a null character.
>           *
>           */
>           status_32 = ANreadann (ann_id, ann_buf, ann_length+1);
>           printf ("Data label index: %d\n", index);
>           printf ("Data label contents: %s\n", ann_buf);
>           /*
>           * Terminate access to the current data label.
>           */
>           status_n = ANendaccess (ann_id);
>           /*
>           * Free the space allocated for the annotation buffer.
>           */
>           free (ann_buf);
>        }
>        /*
>        * Terminate access to the AN interface and close the HDF file.
>        */
>        status_32 = ANend (an_id);
>        status_n = Hclose (file_id);
>     }

> read_annotation.f

>           program  read_annotation
>           implicit none
>     C
>     C     Parameter declaration
>     C
>           character*22 FILE_NAME
>     C
>           parameter (FILE_NAME = 'General_HDFobjects.hdf')
>           integer    DFACC_READ
>           parameter (DFACC_READ = 1)
>           integer    AN_DATA_LABEL
>           parameter (AN_DATA_LABEL = 0)
>     C
>     C     Function declaration
>     C
>           integer hopen, hclose
>           integer afstart, affileinfo, afselect, afannlen, afreadann,
>          +        afendaccess, afend
>     C
>     C**** Variable declaration *******************************************
>     C
>           integer status
>           integer file_id, an_id, ann_id
>           integer index, ann_length
>           integer n_file_labels, n_file_descs, n_data_labels, n_data_descs
>           character*256 ann_buf
>     C
>     C**** End of variable declaration ************************************
>     C
>     C
>     C     Open the HDF file for reading.
>     C
>           file_id = hopen(FILE_NAME, DFACC_READ, 0)
>     C
>     C     Initialize the AN interface.
>     C
>           an_id = afstart(file_id)
>     C
>     C     Get the annotation information, i.e., the number of file labels,
>     C     file descriptions, data labels, and data descriptions.
>     C
>           status = affileinfo(an_id, n_file_labels, n_file_descs,
>          +                    n_data_labels, n_data_descs)
>     C
>     C     Get the data labels. Note that this DO loop can be used to obtain
>     C     the contents of each kind of annotation with the appropriate number
>     C     of annotations and the type of annotation, i.e., replace
>     C     n_data_labels with n_file_labels, n_files_descs, or n_data_descs, and
>     C     AN_DATA_LABEL with AN_FILE_LABEL, AN_FILE_DESC, or AN_DATA_DESC,
>     C     respectively.
>     C
>           do 10 index = 0, n_data_labels-1
>     C
>     C     Get the identifier of the current data label.
>     C
>           ann_id = afselect(an_id, index, AN_DATA_LABEL)
>     C
>     C     Get the length of the data label.
>     C
>           ann_length = afannlen(ann_id)
>     C
>     C     Read and display the data label. The data label is read into buffer
>     C     ann_buf. One has to make sure that ann_buf has sufficient size to hold
>     C     the data label. Also note, that the third argument to afreadann is
>     C     1 greater that the actual length of the data label (see comment to
>     C     C example).
>     C
>           status = afreadann(ann_id, ann_buf, ann_length+1)
>           write(*,*) 'Data label index: ', index
>           write(*,*) 'Data label contents: ', ann_buf(1:ann_length)
>     10    continue
>     C
>     C     Terminate access to the current data label.
>     C
>           status = afendaccess(ann_id)
>     C
>     C     Terminate access to the AN interface and close the HDF file.
>     C
>           status = afend(an_id)
>           status = hclose(file_id)
>           end

> get_annotation_info.c

>     #include "hdf.h"
>     #define  FILE_NAME   "General_HDFobjects.hdf"
>     #define  VG_NAME     "AN Vgroup"
>     main( )
>     {
>        /************************* Variable declaration **************************/
>        intn   status_n;      /* returned status for functions returning an intn */
>        int32  status_32,     /* returned status for functions returning an int32*/
>               file_id, an_id, ann_id,
>               n_annots,      /* number of annotations */
>              *ann_list,      /* list of annotation identifiers */
>               vgroup_ref,    /* reference number of the vgroup */
>               index;         /* index of an annotation in the annotation list */
>               ann_type annot_type = AN_DATA_DESC;   /* annotation to be obtained*/
>        uint16 ann_tag, ann_ref,              /* tag/ref number of an annotation */
>               vgroup_tag = DFTAG_VG;         /* tag of the vgroup */
>        /********************** End of variable declaration **********************/
>        /*
>        * Create the HDF file.
>        */
>        file_id = Hopen (FILE_NAME, DFACC_READ, 0);
>        /*
>        * Initialize the V interface.
>        */
>        status_n = Vstart (file_id);
>        /*
>        * Get the vgroup named VG_NAME.
>        */
>        vgroup_ref = Vfind  (file_id, VG_NAME);
>        /*
>        * Initialize the AN interface and obtain an interface id.
>        */
>        an_id = ANstart (file_id);
>        /*
>        * Get the number of object descriptions.  Note that, since ANnumann takes
>        * the tag and reference number as being of type unit16, vgroup_ref must be
>        * safely cast to uint16 by checking for FAIL value first.
>        */
>        if (vgroup_ref != FAIL)
>        {
>           n_annots = ANnumann (an_id, annot_type, vgroup_tag, (uint16)vgroup_ref);
>           /*
>           * Allocate space to hold the annotation identifiers.
>           */
>           ann_list = malloc (n_annots * sizeof (int32));
>           /*
>           * Get the list of identifiers of the annotations attached to the
>           * vgroup and of type annot_type.
>           */
>           n_annots = ANannlist (an_id, annot_type, vgroup_tag, (uint16)vgroup_ref,
>                                 ann_list);
>           /*
>           * Get each annotation identifier from the list then display the
>           * tag/ref number pair of the corresponding annotation.
>           */
>           printf ("List of annotations of type AN_DATA_DESC:\n");
>           for (index = 0; index < n_annots; index++)
>           {
>             /*
>              * Get and display the ref number of the annotation from
>              * its identifier.
>              */
>              status_32 = ANid2tagref (ann_list[index], &ann_tag, &ann_ref);
>              printf ("Annotation index %d: tag = %s\nreference number= %d\n",
>                index, ann_tag == DFTAG_DIA ? "DFTAG_DIA (data description)":
>                "Incorrect", ann_ref);
>           } /* for */
>        } /* for */
>        /*
>        * Get and display an annotation type from an annotation tag.
>        */
>        annot_type = ANtag2atype (DFTAG_FID);
>        printf ("\nAnnotation type of DFTAG_FID (file label) is %s\n",
>                   annot_type == AN_FILE_LABEL ? "AN_FILE_LABEL":"Incorrect");
>        /*
>        * Get and display an annotation tag from an annotation type.
>        */
>        ann_tag = ANatype2tag (AN_DATA_LABEL);
>        printf ("\nAnnotation tag of AN_DATA_LABEL is %s\n",
>                   ann_tag == DFTAG_DIL ? "DFTAG_DIL (data label)":"Incorrect");
>        /*
>        * Terminate access to the AN interface and close the HDF file.
>        */
>        status_32 = ANend (an_id);
>        status_n = Hclose (file_id);
>        /*
>        * Free the space allocated for the annotation identifier list.
>        */
>        free (ann_list);
>     }

> get_annotation_info.f

>           program annotation_info
>           implicit none
>     C
>     C     Parameter declaration
>     C
>           character*22 FILE_NAME
>           character*9  VG_NAME
>     C
>           parameter (FILE_NAME      = 'General_HDFobjects.hdf',
>          +           VG_NAME        = 'AN Vgroup')
>           integer    DFACC_READ
>           parameter (DFACC_READ = 1)
>           integer AN_FILE_LABEL, AN_DATA_LABEL, AN_DATA_DESC
>           parameter (AN_FILE_LABEL = 2,
>          +           AN_DATA_LABEL = 0,
>          +           AN_DATA_DESC  = 1)
>           integer DFTAG_DIA, DFTAG_FID, DFTAG_DIL
>           parameter (DFTAG_DIA = 105,
>          +           DFTAG_FID = 100,
>          +           DFTAG_DIL = 104)
>           integer DFTAG_VG
>           parameter (DFTAG_VG = 1965)
>     C
>     C     Function declaration
>     C
>           integer hopen, hclose
>           integer afstart, afnumann, afannlist, afidtagref, aftagatype,
>          +        afatypetag, afend
>           integer vfstart, vfind
>     C
>     C**** Variable declaration *******************************************
>     C
>           integer status
>           integer file_id, an_id
>           integer n_annots, ann_index, annot_type, ann_tag, ann_ref
>           integer ann_list(10)
>           integer vgroup_tag, vgroup_ref
>     C
>     C**** End of variable declaration ************************************
>     C
>           annot_type = AN_DATA_DESC
>           vgroup_tag = DFTAG_VG
>     C
>     C     Open the HDF file for reading.
>     C
>           file_id = hopen(FILE_NAME, DFACC_READ, 0)
>     C
>     C     Initialize the V interface.
>     C
>           status = vfstart(file_id)
>     C
>     C     Get the group named VG_NAME.
>     C
>           vgroup_ref = vfind(file_id, VG_NAME)
>     C
>     C     Initialize the AN interface.
>     C
>           an_id = afstart(file_id)
>     C
>     C     Get the number of object descriptions.
>     C
>           if (vgroup_ref .eq. -1) goto 100
>           n_annots = afnumann(an_id, annot_type, vgroup_tag, vgroup_ref)
>     C
>     C     Get the list of identifiers of the annotations attached to the
>     C     vgroup and of type annot_type. Identifiers are read into ann_list
>     C     buffer. One has to make sure that ann_list has the size big enough
>     C     to hold the list of identifiers.
>     C
>           n_annots = afannlist(an_id, annot_type, vgroup_tag, vgroup_ref,
>          +                     ann_list)
>     C
>     C     Get each annotation identifier from the list then display the
>     C     tag/ref number pair of the corresponding annotation.
>     C
>           write(*,*) 'List of annotations of type AN_DATA_DESC'
>           do 10 ann_index = 0, n_annots - 1
>     C
>     C     Get and display the ref number of the annotation from its
>     C     identifier.
>     C
>           status = afidtagref(ann_list(ann_index+1), ann_tag, ann_ref)
>           write(*,*) 'Annotation index: ', ann_index
>           if (ann_tag .eq. DFTAG_DIA) then
>               write(*,*) 'tag = DFTAG_DIA (data description)'
>           else
>               write(*,*) ' tag = Incorrect'
>           endif
>           write(*,*) 'reference number = ', ann_ref
>     10    continue
>     C
>     C     Get and display an annotation type from an annotation tag.
>     C
>           annot_type = aftagatype(DFTAG_FID)
>           if (annot_type .eq. AN_FILE_LABEL) then
>              write(*,*) 'Annotation type of DFTAG_FID (file label) is ',
>          +               'AN_FILE_LABEL '
>           else
>              write(*,*) 'Annotation type of DFTAG_FID (file label) is ',
>          +               'Incorrect'
>           endif
>     C
>     C     Get and display an annotation tag from an annotation type.
>     C
>           ann_tag = afatypetag(AN_DATA_LABEL)
>           if (ann_tag .eq. DFTAG_DIL ) then
>              write(*,*) 'Annotation tag of AN_DATA_LABEL is ',
>          +               'DFTAG_DIL (data label)'
>           else
>              write(*,*) 'Annotation type of DFTAG_FID (file label) is ',
>          +               'Incorrect'
>           endif
>     C
>     C     Terminate access to the AN interface and close the HDF file.
>     C
>     100   continue
>           status = afend(an_id)
>           status = hclose(file_id)
>           end

HDF4.2r4 - February 2009 Copyright | The HDF Group www.hdfgroup.org