How to use heb library.
=======================

I. How to learn contents of the heb file?

   Use Unix commands less or more. You do not need a library
for that. :-)

Heb library consists of two routines:

heb_read 
heb_free

II. Using from C.
-----------------

1) Allocate structure heb
2) call heb_read as
   is = heb_read ( (char *) filin, (struct heb_struct *) heb, (char *) out_type ) ;

   where 
   filin    -- the name of the output file
   out_type -- output type: R4, R8, I4, I8, I2, I1. You need to know type.

   Public elements of the heb structure:                              
                                                                      
   heb->natts      int       -- number of attributes                  
   heb->dims       long long -- dimensions. Heb value is              
                                a four-dimensional array.             
   heb->attr_name  char      -- Array of attribute names.             
   heb->attr_val   char      -- Array of attribute values.            
   heb->xx_fill_value        -- fill_value. "xx" is the prefix that   
                                determines data type: i1, i2, i4, r4, 
                                or r8.                                
   heb->xx_i1_ptr            -- pointer to output array. "xx" is the  
                                prefix that determines data type:     
                                i1, i2, i4, r4, or r8.                
                   One of these six pointers is allocated and points  
                   to the contents of retrieved data section          
                   depending on out_type. The pointer points to the   
                   flat array of values. The 4D array is presented as 
                   a continuous chunk of memory. NB: Fortran memory   
                   layout is used: first dimension runs first.        
 
   A given element can be accessed using macros:       
                                                                      
           heb_2d_xx_elem(heb,i0,i1)                          
           heb_3d_xx_elem(heb,i0,i1,i2)                       
           heb_4d_xx_elem(heb,i0,i1,i2,i3)                    
                                                                      
   where i1, i2, i3, i4 are indices over dimensions   
   0,1,2,3, and xx is the data type (low case).       

III. Using from Fortran.
------------------------

   1) Declare module USO_C_BINDING;                                   
   2) Declare include block heb_c.inc;                                
   3) Declare an element of derived type HEB_C;                       
   4) Declare integer*4 routine HEB_READ;                             
   5) Call routine HEB_READ. The first argument is the file name with 
      trailing 0: TRIM(File_Name)//CHAR(0), the second argument is    
      an element of derived type (structure in C language) HEB_C,     
      the third argument is the output type: R4, R8, I4, I8, I2, I1.  
   6) Associate pointer of the specified type of the fortran array    
      with the pointer of C array. One, two, three, of four           
      dimensional arrays are supported:                               

   CALL C_F_POINTER ( HEB_C%xx_PTR, HEB_C%ARR_1D_xx, [HEB_C%DIMS(1)] ) 
   CALL C_F_POINTER ( HEB_C%xx_PTR, HEB_C%ARR_2D_xx, [HEB_C%DIMS(1), HEB_C%DIMS(2)] ) 
   CALL C_F_POINTER ( HEB_C%xx_PTR, HEB_C%ARR_3D_xx, [HEB_C%DIMS(1), HEB_C%DIMS(2), HEB_C%DIMS(3)] ) 
   CALL C_F_POINTER ( HEB_C%xx_PTR, HEB_C%ARR_4D_xx, [HEB_C%DIMS(1), HEB_C%DIMS(2), HEB_C%DIMS(3), HEB_C%DIMS(4)] ) 

   After this steps, you can access the data in the array             
   HEB_C%ARR_yD_xx.                                                   

   Derived type HEB_C contains other useful information:              

   HEB_C%DIMS          -- four dimensions of the array;               
   HEB_C%NATTS         -- the number of attributes;                   
   HEB_C%ATT_NAME      -- array of attribute names;                   
   HEB_C%ATT_VAL       -- array of attribute values as character      
                          strings;                              
   HEB_C%xx_FILL_VALUE -- Fill value where xx is the output type.