Jason Ng
15/May/91

 HDF VSET 2.1beta

These are additional routines that are added to version 2.0.
Refer to the existing HDF Vset manual for a description of the
entire Vset interface.


Some terminology

FIELD
A field is defined by the user to describe data associated with
one variable. It consists of a name, type and order. Users of
Vsets typically have datasets of several variables, and hence
define several fields. For example, a field can be defined for a
pressure variable to be called "pres". Its type is FLOAT, and its
order is 1.

ORDER
The number of distinct components in a field. Simple
variables/fields like pressure have order 1 (one distinct
component, ie itself).

VGROUP
A Vset element where links to other elements are stored. A vgroup
is used to group related elements together. Elements can be
vdatas, vgroups, and other HDF elements like raster images,
palettes, etc.

VDATA
A Vset element where data is stored. One vdata can store data of
one or several different fields. Fields can be of different types
(integer, float, etc). See FIELD.


VSET 2.1 VGROUP MANIPULATION ROUTINES

Vflocate()
Tests if a field exists in the vdatas belonging to a vgroup.
Fortran: VFLOCC

Vinqtagref()
Tests if a given tag/ref pair is in a vgroup.
Fortran: VFINGTR

Velts()
Returns the number of elements (links) in a vgroup.
Fortran: VFELTS

Vntagrefs()
Returns a count of the number of tag/ref pairs in a vgroup.
Fortran: VFNTR

Vgettagrefs()
Returns ALL the tag/ref pairs in a vgroup.
Not to be confused with Vgettagref() [VFGTR in Fortran].
Fortran: VFGTTRS

Vgettagref()
Returns a tag/ref pair at a specific position in the vgroup.
Not to be confused with Vgettagrefs() [VFGTRS in Fortran].
Fortran: VFGTTR

Vaddtagref()
Inserts a tag/ref pair into a vgroup.
Can be the tag/ref of non-vset elements.
Fortran: VFADTR


VSET 2.1 HIGH-LEVEL WRITE ROUTINES

VHstoredata()
Stores data of a simple field into a vdata.
Fortran: VHFSD

VHstoredatam()
Stores data of a compound field into a vdata.
Fortran: VHFSDM

VHmakegroup()
Creates a vgroup given some tag/ref pairs.
Fortran: VHFMKGP


Quick creation of simple Vsets in the majority of cases can be
achieved using only the High-Level Write routines.
VHstoredata - creates a vdata of a simple variable
VHstoredatam - creates a vdata of a compound variable
VHmakegroup - creates a vgroup.

VHstoredata() and VHstoredatam() are 2 routines used for storing
data from arrays into a vdata. VHmakegroup() creates a new vgroup
given a series of tag/ref pairs.

VHstoredata() is used for storing a simple variable.
VHstoredatam() is used only if a compound variable is to be
stored as a single field of order > 1.


C EXAMPLE

Vset created by the C sample program:

/*


SAMPLE C PROGRAM

HDF VSET 2.1
Jason Ng NCSA MAY 1991

This program demonstrates the use of the high-level VSET write
routines. It shows how data can be stored in vdatas, and how
vgroups can be created from vdatas, vgroups and other HDF
elements.

This example creates a file "vtesthi.hdf" that may be viewed
using the vset utility "vshow".


DETAILS

This example shows how pressure data and color data can be stored
as a vset. To store pressure data, a field named "PRES", is
defined of float type. The routine VHstoredata() stores the
pressure values in a vdata.

Color data comprises 3 components (red, green, blue). These can
be stored as 3 different fields in 3 vdatas. But this example
shows that they can be treated as ONE field, and stored together
as a compound field called "COLOR". The number of components of a
field is called its order. In this case, "COLOR" has order-3.
(whereas "PRES" above has order-1).

The routine VHstoredatam() must be used to store values of a
compound field. This is similar to VHstoredata() but has an extra
argument for the order to be specified.

Finally a vgroup is created, and the ids of the created vdatas
are stored in the vgroup. This effectively groups the vdatas
together. This example also shows that you can insert another
vgroup, as well as a non-vset element (in this case, some element
with tag=7777 and ref-1) into a vgroup.

*/


#include "vg.h"
#define fs "vtesthi.hdf"
#define NP 100
#define NC 60
#define ORDERC 3 /* 3 color components: rgb */

main (ac,av)   int ac; char**av; {
  printf("%s: tests high-level routines\n", av[0]);
  printf("Creates 2 vdatas, a vgroup, and a non-vset element\n");
  printf("then link them all into another vgroup\n");
  printf("Vdata 1 contains an order-1 float field PRES\n");
  printf("Vdata 2 contains an order-3 integer field COLOR\n\n");
  printf("The non-vset element has tag=7777, ref=1\n");
  doit();
  printf("all done. created file %s\n", fs);
}
/*-------------------------------------------------------*/

doit() {
DF * f;
float pvals[NP];
int cvals[NC] [ORDERC];
int i,j;

int16 pid, cid; /* refs of vdatas */
int16 eid; /* empty vgroup's ref  */
int16 gid; /* vgroup's ref  */
int16 tags[10], refs[16];
char *CLS = "EXAMPLE";

/* --- generate data here --- */
   for(i=0;i<NP;i++)   pvals[i]  = 100.0 + i * 0.001;
   for(i=0;i<NC;i++)  for(j=0;j<3;j++)  cvals[i][j] = i + j*100;


/* ---- open a new file --- */

if (NULL==(f-DFopen(fs,DFACC_ALL,0))) { printf("open %s
err\n",fs); exit(0); }

/* ---- create 2 vdatas --- */
pid = VHstoredata (f, "PRES", pvals NP, LOCAL_FLOATTYPE,
"pressure  vals",CLS);
if (pid == -1) { printf(" VHstoredata store PRES err. "); }

cid = VHstoredatam(f, "COLOR", cvals, NC, LOCAL_INTTYPE, "rgb
 colors", CLS, 3);
if (cid == -1) { printf(" VHstoredata store COLOR err. "); }

eid = VHmakegroup (f, tags, refs, 0, "This is an EMPTY vgroup",
 CLS);
if (eid == -1) { printf(" VHmakegroup err\n"); }

/* --- create a new vgroup to store the 2 vdatas and the empty
 vgroup -- */
tags[0] = VSDESCTAG; refs[0] = pid;
tags[1] = VSDESCTAG; refs[1] = cid;
tags[2] = VSDESCTAG; refs[2] = eid;
tags[3] = 7777 ;     refs[3] = 1;

gid = VHmakegroup (f, tags, refs, 4, "here is a vset with 4
links", CLS);
if (eid == -1) { printf(" VHmakegroup err\n"); }

/* --- close the file --- */
DFclose (f);
}


FORTRAN EXAMPLE

Vset created by the Fortran sample program.

c =====================================================
c    FORTRAN EXAMPLE
c
c    HDF VSET 2.1
c    Jason Ng NCSA MAY 1991
c
c    This program creates a Vset to store an array of pressure
c    values, and an array of color-triplets (red-green-blue). It
c    demonstrate the use of the Vset high-level write routines.

c    The pressure data is stored in one vdata (pid), and the
c    color-triplets are stored in another vdata (cid). These ids
c    are then stored together in a vgroup, thereby logically
c    grouping them as one vset.
c
c    Note that pressure is a simple variable. It is stored using
c    the function VHFSD. But color-triplet data is a compound
c    variable, with 3 components (red,green,blue). The function
c    VHFSDM is used instead so that the order (the number of
c    components, ie 3) can be specified.
c
c    The HDF file that is created,"eh.hdf", can be looked at with
c    the Vset utility "vshow"

c =====================================================

     program SAMPLE

     real              pbuf(100)
     integer           cbuf(3,60)
     integer           i,j, npres, ncolor
     integer f
     integer pid, cid, vgid
     character*10 class
     integer tagnums(10), refnums(10), ntagref

c    --- routines and functions used
     external DFOPEN, DFCLOSE
     integer DFOPEN
     external VHFSD, VHFSDM, VHFMKGP
     integer VHFSD, VHFSDM, VHFMKGP

c    --- The parameters below are defined constants from "vg.h"
c    -- float and integer types
     integer                    T_INT, T_FLOAT
     parameter         (T_INT=2)
     parameter         (T_FLOAT=3)

c    --- HDF tag for vgroup and vdata.
     integer                    VDATTAG, VGPTAG
     parameter        (VGPTAG=1965)
     parameter        (VDATTAG=1962)

c    --- full file access
     integer FULLACC
     parameter (FULLACC=7)

c    ------ generate pressure data -------------------
            npres - 100
            do 111 i=1,npres
                    pbuf(i) = 0.01 * i + 500
111  continue
c    ------ generate color-triplet (rgb) data -------
             ncolor = 60
             do 222 i=1,ncolor
                     do 225 j=1,3
                             cbuf(j,i) = i + j * 100
225          continue
222  continue

     class = "example"

c    --- open the HDF file
     f = DFOPEN ('eh.hdf', FULLACC, 0)

c    --- store pressure values in a new vdata
     pid - VHFSD (f, 'PRES', pbuf, npres, T_FLOAT,
     1                               'pressure values', class)
     print *, 'Pressure vdata id is ', pid

c    --- store color-triplet values in a new vdata
c    Note the argument 3 (for order=3 for a triplet)

     cid - VHFSDM (f, 'RGB', cbuf, ncolor, T_INT,
     1                         'a set of rgb values', class, 3)
     print *, 'Color-triplet vdata id is ', cid

c    --- create a new vgroup and then group the 2 vdatas into it

     tagnums(1) = VDATTAG
     tagnums(2) = VDATTAG
     refnums(1) = pid
     refnums(2) = cid
     ntagref    = 2

     vgid = VHFMKGP (f,tagnums refnums, ntagref,
     1                             'vgroup with 2 vdatas',
     1                             class)
     print *, 'Vgroup id is ', vgid

c    --- close the HDF file
     call DFCLOSE (f)
     print *,'HDF VSet file eh.hdf created'

     end


Calling Sequences

int VHstoredata (f, field, buf, n, datatype, vsname, vsclass)
DF * f;
char * field;
unsigned char buf[];
int32 n;
char * vsname, * vsclass;
int datatype;

Creates a new vdata and store data for one simple field. You give
it the name and class (strings)of that vdata, and the field name
(eg "PRES" for pressure), and tell it what datatype the data will
be in. The data is passed in as the array buf[], and you tell it
how many values there are (n).

Datatype is one of LOCAL_INTTYPE, LOCAL_LONGTYPE,LOCAL_FLOATTYPE,
LOCAL_CHARTYPE.

To store acompound field, use VHstoredatam() instead.

int VHstoredatam (f, field, buf, n, datatype, vsname, vsclass,
order)
DF      *f;
char    *field;
float   buf[];
int32   n;
int     datatype;
int     order;
char    *vsname, *vsclass;

Creates a new vdata and store data for one compound field. You
give it the name and class (strings)of that vdata, and the field
name (eg "PLIST3" for pressure), and tell it what datatype the
data will be in. In addition, you need to tell it the order of
that field. (ie, how many components there are per data item).
The data is passed in as the array buf[], and you tell it how
many values there are (n).

Datatype is one of LOCAL_INTTYPE, LOCAL_LONGTYPE,LOCAL_FLOATTYPE,
LOCAL_CHARTYPE.

This routine also works for a simple field - set the order to 1.
Or you can use VHstoredata() instead.

int VHmakegroup (f, tagarray, refarray , n, vgname, vgclass)
int tagarray[], refarray[];
int n;
char *vgname, *vgclass;

Creates a new vgroup. You give it the name, class and an array of
tags and refs. You also tell it how many tag/ref pairs there are.
It will create the vgroup, and return the ref number (id) of that
new vgroup. Vgname and vgclass are any text string to name the
vgroup.