The HDF Group

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
The HDF Group