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