[Top] [Prev] [Next] [Bottom]

1.5 Creating and Writing to a Vgroup

There are two steps involved in the creation of vgroups. First, the vgroup must be created, then the data objects must be inserted into it. Any HDF data object can be inserted into a vgroup. Creation and insertion operations are usually performed at the same time - although, as with the VS interface routines it isn't required to do so.

1.5.1 Creating a Vgroup:Vattach

Creating a vgroup involves the following steps:

1. Open the file.
2. Initialize the V interface.
3. Create the new vgroup.
4. Optionally assign a vgroup name.
5. Optionally assign a vgroup class.
6. Optionally insert the data objects.
7. Terminate access to the vgroup.
8. Terminate access to the V interface.
9. Close the file.
These steps correspond to the following calling sequence:

C:		file_id = Hopen(filename, file_access_mode, n_dds);
		status = Vstart(file_id);
		vgroup_id = Vattach(file_id, vgroup_ref, vgroup_access_mode);
		status = Vsetname(vgroup_id, vgroup_name);
		status = Vsetclass(vgroup_id, vgroup_class);
		num_of_tag_refs = Vaddtagref(vgroup_id, tag, ref); or 
			obj_pos = Vinsert(vgroup_id, v_id);
		status = Vdetach(vgroup_id);
		status = Vend(file_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, file_access_mode, n_dds)
		status = vfstart(file_id)
		vgroup_id = vfatch(file_id, vgroup_ref, vgroup_access_mode)
		status = vfsnam(vgroup_id, vdata_name)
		status = vfscls(vgroup_id, vdata_class)
		num_of_tag_refs = vfadtr(vgroup_id, tag, ref) or 
			obj_pos = vfinsrt(vgroup_id, v_id)
		status = vfdtch(vgroup_id)
		status = vfend(file_id)
		status = hclose(file_id)

In the routines that follow, vgroup_id is the vgroup identifier returned by Vattach.

When a new vgroup is created, the value of vgroup_ref must be set to -1 and the value of access_mode must be "w".

1.5.2 Assigning a Vgroup Name and Class: Vsetname and Vsetclass

Vsetname assigns a name to a vgroup. The parameter vgroup_name is a character string with the name to be assigned to the vgroup. If Vsetname is not called, a vgroup name is set to a zero-length string. A name may be assigned and reset any time after the vgroup is created.

Vsetclass assigns a class to a vgroup. The parameter vgroup_class is a character string with the class name to be assigned to the vgroup. If Vsetclass is not called, a vgroup class is set to a zero-length string. As with the vgroup names, the class may be set and reset at any time after the vgroup is created.

Vsetname and Vsetclass are further described below. (See Table 5C on page 148.)

1.5.3 Inserting Any HDF Data Object Into a Vgroup: Vaddtagref

The routine most commonly used for inserting objects into a vgroup is Vaddtagref. Data objects may be added to a vgroup when the vgroup is created or at any point thereafter.

The tag and ref parameters in Vaddtagref are the tag and reference number of the data object to be inserted into the vgroup respectively. Vaddtagref returns the total number of tag and reference number pairs in the vgroup if the operation is successful and FAIL (or -1) otherwise.

Vaddtagref is firther described below. (See Table 5C on page 148.)

1.5.4 Inserting a Vdata or Vgroup Into a Vgroup: Vinsert

Vinsert is a routine designed specifically for inserting vdatas or vgroups into a parent vgroup. To use Vinsert, you must provide the vdata id of the parent vgroup, as well as the vdata id or the vgroup id of the vdata or vgroup to be inserted. These ids are obtained by inserting the vgroups and vdatas in the manner described in the preceeding subsection and in Chapter 4, titled Vdatas (VS API).

The v_id parameter in Vinsert is either a vdata id or a vgroup id, depending on whether a vdata or vgroup is to be inserted. Vinsert returns the index of the inserted vdata or vgroup if the operation is successful and FAIL (or -1) otherwise.

Vinsert is further defined in the following table.

TABLE 5C Vsetname, Vsetclass, Vaddtagref and Vinsert Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Vsetname

(vfsnam)

vgroup_id

int32

integer

Vgroup identifier.

vgroup_name

char *

character* (*)

Vgroup name.

Vsetclass

(vfscls)

vgroup_id

int32

integer

Vgroup identifier.

vgroup_class

char *

character* (*)

Vgroup class.

Vaddtagref

(vfadtr)

vgroup_id

int32

integer

Vgroup identifier.

tag

int32

integer

Tag of the object to be inserted.

ref

int32

integer

Reference number of the object to be inserted.

Vinsert

(vfinsrt)

vgroup_id

int32

integer

Vgroup identifier.

v_id

int32

integer

Vgroup or vdata identifier of the object to be inserted.

EXAMPLE 1. Creating a Vgroup Containing a Raster Image

The following examples use Vaddtagref to insert an 8-bit raster image into a vgroup that is created with the name "VG_Name_1" and the class "VG_Class_1". The following figure illustrates what these examples do. The C and Fortran-77 code uses two different means of initializing the example raster image set, but in most real-world applications this set would be read from an external data file using the RIS8 routines described in Chapter 6, titled 8-Bit Raster Images (DFR8 API).

C:

#include "hdf.h"


#define HEIGHT 6
#define WIDTH 5

main( ) 
{ 

    int32 file_id, vgroup_id, vdata_id, status; 
    uint16 tag, ref;

    /* Construct the image to be written to the vgroup. */
    static uint8 raster_data[HEIGHT][WIDTH] = 						
                           { 1, 2, 3, 4,  5, 
    						6,  7,  8,  9, 10,
    						11, 12, 13, 14, 15,   
    						16, 17, 18, 19, 20,
    						21, 22, 23, 24, 25,
    						26, 27, 28, 29, 30 };

    /* Open an HDF file with full access. */
    file_id = Hopen("Example1.hdf", DFACC_CREATE, 0);

    /* Initialize HDF for subsequent vgroup/vdata access. */
    status = Vstart(file_id);

    /* Create a vgroup. */
    vgroup_id = Vattach(file_id, -1, "w"); 

    /* Set the name and class for this vgroup. */
    status = Vsetname(vgroup_id, "VG_Name_1");
    status = Vsetclass(vgroup_id, "VG_Class_1");

    /* Write the data to file and determine its tag and ref number. */
    status = DFR8addimage("Example1.hdf", (VOIDP) raster_data, WIDTH, 
                          HEIGHT, 0);
    ref = DFR8lastref( );

    /* This tag definition is from hdf.h. */
    tag = DFTAG_RI8;

    /* Insert the data image into the vgroup. */
    status = Vaddtagref(vgroup_id, tag, ref);

    /* Terminate access to the vgroup interface. */
    status = Vdetach(vgroup_id);
    status = Vend(file_id);

    /* Close the HDF file. */
    status = Hclose(file_id);
    
}

FORTRAN:

PROGRAM VGROUP INSERT


      integer file_id, vgroup_id, status, tag, ref
      integer*4 raster_data(6, 5) 
      integer i, j, k
      integer hopen, vfatch, vfsnam, vfscls
      integer d8aimg, d8lref, vfadtr, vfdtch, vfatch
      integer hclose, vfstart, vfend
      integer DFACC_CREAT
      parameter (DFACC_CREAT = 4)

C     Construct the data image to be written to the vgroup.
      do 20 j = 1, 5
        do 10 i = 1, 6
            raster_data(i, j) = k
            k = k + 1
10      continue
20    continue

C     Open an HDF file with full access.
C     DFACC_CREAT is defined in hdf.inc.
      file_id = hopen('Example1.hdf', DFACC_CREAT, 0)

C     Open a vgroup with write access. 
      status = vfstart(file_id)
      vgroup_id = vfatch(file_id, -1, 'w') 

C     Set the name and class for this vgroup. 
      status = vfsnam(vgroup_id, 'VG_Name_1')
      status = vfscls(vgroup_id, 'VG_Class_1')

C     Write the data to file and determine its tag and reference 
C     number. 
      status = d8aimg('Example1.hdf', raster_data, 6, 5, 0)
      ref = d8lref( )

C     The number '202' corresponds to the value of DFTAG_RI8 in 
C     hdf.inc.
      tag = 202

C     Insert the data image into the vgroup. 
      status = vfadtr(vgroup_id, tag, ref)

C     Terminate access to the V interface. 
      status = vfdtch(vgroup_id)
      status = vfend(file_id)

C     Close the HDF file. 
      status = hclose(file_id)

      end

EXAMPLE 2. Inserting Three Vdatas Into a Vgroup to Create a Vset

Consider a heated mesh of twenty triangles formed by connecting thirty nodes. The following examples demonstrate how to create a vset containing three vdatas where the vdatas are the coordinate position of each node, the connectivity list describing each relation of three vertices (or triangles) in the vset and a temperature value for each node. The following figure illustrates what is done in the examples. In real-world applications, the contents of the vdatas would be read in from external files, not initialized as in these examples.

C:

#include "hdf.h"

main( )
{

	int32 file_id, vgroup_id, vdata_id, status;
	int32 num_of_elements, vg_position;
	float32 pxy[30][2] = {-1.5, 2.3, -1.5, 1.98, -2.4, .67,
						-3.4, 1.46, -.65, 3.1, -.62, 1.23,
						-.4, 3.8, -3.55, 2.3, -1.43, 2.44,
						.23, 1.13, -1.4, 5.43, -1.4, 5.8,
						-3.4, 3.85, -.55, .3, -.21, 1.22,
						-1.44, 1.9, -1.4, 2.8, .94, 1.78,
						-.4, 2.32, -.87, 1.99, -.54, 4.11,
						-1.5, 1.35, -1.4, 2.21, -.22, 1.8,
						-1.1, 4.55, -.44, .54, -1.11, 3.93,
						-.76, 1.9, -2.34, 1.7, -2.2, 1.21};

	float32 temp[30]; 
	uint8 mesh[20][3];
	uint8 i, j, k = 0;	

	/* Open an HDF file with full access. */
	file_id = Hopen("Example2.hdf", DFACC_CREATE, 0);

	/* Initialize HDF for subsequent vgroup/vdata access. */
	status = Vstart(file_id);

	/* Initialize the data buffer arrays. */
	for (i = 0; i < 30; i++)
	   temp[i] = i * 10.0;

	for (i = 0; i < 20; i++) {
	   for (j = 0; j < 3; j++) {
	      mesh[i][j] = ++k;
	   }
	}

	/* Create a vgroup with write access, then name it "Vertices". */
	vgroup_id = Vattach(file_id, -1, "w");
	status = Vsetname(vgroup_id, "Vertices");

	/* Create a vdata to store the x,y values, set its name and class. */
	vdata_id = VSattach(file_id, -1, "w");
	status = VSsetname(vdata_id, "PX and PY");
	status = VSsetclass(vdata_id, "Node List");

	/* Specify the PX field information. */
	status = VSfdefine(vdata_id, "PX", DFNT_FLOAT32, 2);

	/* Specify the PY field information. */
	status = VSfdefine(vdata_id, "PY", DFNT_FLOAT32, 2);

	/* Set the field names. */
	status = VSsetfields(vdata_id, "PX,PY");

	/* Write the buffered data into the vdata object. */
	num_of_elements = VSwrite(vdata_id, (VOIDP)pxy, 30, FULL_INTERLACE);

	/* Insert the vdata into the vgroup. */
	vg_position = Vinsert(vgroup_id, vdata_id);

	/* Detach from the vdata. */
	status = VSdetach(vdata_id);

	/* Create a vdata to store the temperature property data. */
	vdata_id = VSattach(file_id, -1, "w");
	status = VSsetname(vdata_id, "PLIST");
	status = VSsetclass(vdata_id, "Connectivity List");
	status = VSfdefine(vdata_id, "PLIST", DFNT_FLOAT32, 1);
	status = VSsetfields(vdata_id, "PLIST");
	num_of_elements = VSwrite(vdata_id, (VOIDP)temp, 30, FULL_INTERLACE);
	vg_position = Vinsert(vgroup_id, vdata_id);
	status = VSdetach(vdata_id);

	/* Create a vdata to store the mesh. */
	vdata_id = VSattach(file_id, -1, "w");
	status = VSsetname(vdata_id, "TMP");
	status = VSsetclass(vdata_id, "Property List");
	status = VSfdefine(vdata_id, "TMP", DFNT_INT8, 3);
	status = VSsetfields(vdata_id, "TMP");
	num_of_elements = VSwrite(vdata_id, (VOIDP)mesh, 20, FULL_INTERLACE);
	vg_position = Vinsert(vgroup_id, vdata_id);
	status = VSdetach(vdata_id);

	/* Terminate access to the "Vertices" vgroup. */
	status = Vdetach(vgroup_id);

	/* Terminate access to the V interface. */
	status = Vend(file_id);

	/* Close the HDF file. */
	status = Hclose(file_id);

}

FORTRAN:

PROGRAM VDATA INSERT


      integer*4 file_id, vgroup_id, vdata_id, status, num_of_elements
      integer*4 vg_position
      integer*4 mesh(20, 3)
      double precision pxy(30, 2), temp(30)
      integer i, j
      integer hopen, vfatch, vfsnam, vsfatch 
      integer vsfsfld, vsfwrit, vsfdtch, vsffdef, vfdtch 
      integer hclose, vfinsrt, vfstart, vfend, vsfscls, vsfsnam
      data    pxy / -1.5, 2.3, -1.5, 1.98, -2.4, .67,
     +              -3.4, 1.46, -.65, 3.1, -.62, 1.23,
     +             -.4, 3.8, -3.55, 2.3, -1.43, 2.44,
     +             .23, 1.13, -1.4, 5.43, -1.4, 5.8,
     +             -3.4, 3.85, -.55, .3, -.21, 1.22,
     +             -1.44, 1.9, -1.4, 2.8, .94, 1.78,
     +             -.4, 2.32, -.87, 1.99, -.54, 4.11,
     +             -1.5, 1.35, -1.4, 2.21, -.22, 1.8,
     +             -1.1, 4.55, -.44, .54, -1.11, 3.93,
     +             -.76, 1.9, -2.34, 1.7, -2.2, 1.21 /

      integer*4 DFACC_CREAT
      parameter (DFACC_CREAT = 4)

C     Open an HDF file with full access. 
C      DFACC_CREAT is defined in hdf.inc.
      file_id = hopen('Example2.hdf', DFACC_CREAT, 0)

C     Create a vgroup with write access, then name it 'Vertices'. 
      status = vfstart(file_id)

C     Initialize the data buffer arrays. 
      do 10 i = 1, 30
        temp(i) = i * 10.0
10    continue

      do 20 i = 1, 20
        do 30 j = 1, 3
          mesh(i, j) = k
             k = k + 1
30      continue
20    continue
      vgroup_id = vfatch(file_id, -1, 'w')
      status = vfsnam(vgroup_id, 'Vertices')

C     Create a vdata to store the x,y values.  The number
C     '5' in the third argument of vsffdef corresponds to 
C     DFNT_FLOAT32 in hdf.inc.
      vdata_id = vsfatch(file_id, -1, 'w')
      status = vsfsnam(vdata_id, 'PX,PY')
      status =  vsfscls(vdata_id, 'Node List')
      status = vsffdef(vdata_id, 'PX', 5, 1)
      status = vsffdef(vdata_id, 'PY', 5, 1)
      status = vsfsfld(vdata_id, 'PX,PY')
      num_of_elements = vsfwrit(vdata_id, pxy, 30, FULL_INTERLACE)
      vg_position = vfinsrt(vgroup_id, vdata_id)
      status = vsfdtch(vdata_id)

C     Create a vdata to store the temperature data.  The number
C     '5' in the third argument corresponds to DFNT_FLOAT32
C     in hdf.inc.
      vdata_id = vsfatch(file_id, -1, 'w')
      status = vsfsnam(vdata_id, 'TMP')
      status =  vsfscls(vdata_id, 'Property List')
      status = vsffdef(vdata_id, 'TMP', 5, 1)
      status = vsfsfld(vdata_id, 'TMP')
      num_of_elements = vsfwrit(vdata_id, temp, 30, FULL_INTERLACE)
      vg_position = vfinsrt(vgroup_id, vdata_id)
      status = vsfdtch(vdata_id)

C     Create a vdata to store the mesh. The number '24' in the 
C     third argument of vsffdef corresponds to DFNT_INT32 in 
C     hdf.inc.
      vdata_id = vsfatch(file_id, -1, 'w')
      status = vsfsnam(vdata_id, 'PLIST')
      status = vsfscls(vdata_id, 'Connectivity List')
      status = vsffdef(vdata_id, 'PLIST', 24, 3)
      status = vsfsfld(vdata_id, 'PLIST')
      num_of_elements = vsfwrit(vdata_id, mesh, 20, FULL_INTERLACE)
      vg_position = vfinsrt(vgroup_id, vdata_id)
      status = vsfdtch(vdata_id)

C     Terminate access to the vgroup and the file. 
      status = vfdtch(vgroup_id)
      status =  vfend(file_id)

C     Close the HDF file. 
      status = hclose(file_id)

      end


 

EXAMPLE 3. Adding a Scientific Data Set to a Vgroup

The following examples create an HDF file, an SDS and a vgroup. Then they insert the SDS into the vgroup.

C:

#include "hdf.h"
#include "mfhdf.h"
#include <stdio.h>

main()
{
   int ret;
   int32 fid, sds_id, sref;
   int32 dims[1];
   int32 vfid, vg_id, status;

   dims[0] = 10;

   vfid = Hopen("Example3.hdf", DFACC_CREATE, 0);
   fid = SDstart("Example3.hdf", DFACC_RDWR);
   sds_id = SDcreate(fid, "Test_SD1", DFNT_INT8, 1, dims);

   status = Vstart(vfid);
   vg_id = Vattach(vfid, -1, "w");

   sref = SDidtoref(sds_id);
   status = Vaddtagref(vg_id, DFTAG_NDG, sref);

   status = SDendaccess(sds_id);
   status = SDend(fid);

   status = Vdetach(vg_id);
   status = Vend(vfid);
   status = Hclose(vfid);

}

FORTRAN:

	 PROGRAM ADD SDS TO VGROUP

      integer status
      integer*4 fid, sds_id, sref, vfid, vg_id
      integer dims(1)
      integer*4 DFACC_CREATE, DFACC_RDWR, DFNT_INT8, DFTAG_NDG
      parameter (DFACC_CREATE = 4, DFACC_RDWR = 3, DFNT_INT8 = 20,
     +           DFTAG_NDG = 720)

      integer hopen, sfstart, sfcreate, vfstart, vfatch
      integer sfid2ref, vfadtr, sfendacc, vfdtch, vfend, hclose

      dims(1) = 10
      vfid = hopen('Example3.hdf', DFACC_CREATE, 0)
      fid = sfstart('Example3.hdf', DFACC_RDWR)
      sds_id = sfcreate(fid, 'Test_SD1', DFNT_INT8, 1, dims)
      status = vfstart(vfid)
      vg_id = vfatch(vfid, -1, 'w')

      sref = sfid2ref(sds_id)
      status = vfadtr(vg_id, DFTAG_NDG, sref)

      status = sfendacc(sds_id)

      status = vfdtch(vg_id)
      status = vfend(vfid)
      status = hclose(vfid)

      end



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.