# HDF Reference Manual

> ##

> [VS Interface][Top]

> VHstoredata/vhfsd/vhfscd

> int32 VHstoredata(int32 file_id, char *fieldname, uint8 buf[], int32 n_records, int32 data_type, char *vdata_name, char *vdata_class)

> | file_id | IN: | File identifier returned by Hopen
> | fieldname | IN: | Field name for the new vdata
> | buf | IN: | Buffer containing the records to be stored
> | n_records | IN: | Number of records to be stored
> | data_type | IN: | Type of data to be stored
> | vdata_name | IN: | Name of the vdata to be created
> | vdata_class | IN | Class of the vdata to be created

> | Purpose | Creates and writes to a single-field vdata.
> | Return value | Returns reference number of the newly-created vdata if successful, and FAIL (or -1) otherwise.
> | Description | VHstoredata creates a single-field vdata in the file, file_id, and stores data from the buffer buf in it. Vdata name, class name and data type are specified by the parameters vdata_name, vdata_class, and data_type, respectively. Number of records in a vdata is specified by the parameter n_records. Field name is specified by the parameter fieldname.
> |  | Vstart must precede VHstoredata. It is not necessary, however, to call VSattach or VSdetach in conjunction with VHstoredata.
> |  | This routine provides a high-level method for creating single-order, single-field vdatas.
> |  | Note that there are two FORTRAN-77 versions of this routine; one for numeric data (vhfsd) and the other for character data (vhfsdc).

> | FORTRAN | integer function vhfsd(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class)
> |  | integer file_id, n_records, data_type
> |  | character*(*) vdata_name, vdata_class, fieldname
> |  | <valid numeric data type> buf(*)
> |  | integer function vhfscd(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class)
> |  | integer file_id, n_records, data_type
> |  | character*(*) vdata_name, vdata_class, fieldname
> |  | character*(*) buf

> ##

> [VS Interface][Top]

> VHstoredatam/vhfsdm/vhfscdm

> int32 VHstoredatam(int32 file_id, char *fieldname, uint8 buf[], int32 n_records, int32 data_type, char *vdata_name, char *vdata_class, int32 order)

> | file_id | IN: | File identifier returned by Hopen
> | fieldname | IN: | Field name
> | buf | IN: | Buffer containing the records to be stored
> | n_records | IN: | Number of records to be stored
> | data_type | IN: | Type of data to be stored
> | vdata_name | IN: | Name of the vdata to be created
> | vdata_class | IN: | Class of the vdata to be created
> | order | IN: | Field order

> | Purpose | Creates and writes to a multi-order, single-field vdata.
> | Return value | Returns the reference number of the newly created vdata if successful, and FAIL (or -1) otherwise.

> Description

> VHstoredatam creates a vdata with the name specified by the parameter vdata_name and a class name specified by the parameter vdata_class in the file identified by the parameter file_id. The data type of the vdata is specified by the parameter data_type. The vdata contains one field with the name specified by the parameter fieldname. The order of the field, order, indicates the number of vdata values stored per field. The vdata contains the number of records specified by the parameter n_records. The buf parameter should contain n_records records that will be stored in the vdata.

> |  | Vstart must precede VHstoredatam. It is not necessary, however, to call VSattach or VSdetach in conjunction with VHstoredatam.
> |  | This routine provides a high-level method for creating multi-order, single-field vdatas.
> |  | Note that there are two FORTRAN-77 versions of this routine; one for numeric data (vhfsdm) and the other for character data (vhfscdm).

> | FORTRAN | integer function vhfsdm(file_id, fieldname, buf, n_records,
> |  | integer file_id, n_records, data_type, order
> |  | character*(*) vdata_name, vdata_class, fieldname
> |  | <valid numeric data type> buf(*)
> |  | integer function vhfscdm(file_id, fieldname, buf, n_records, data_type, vdata_name, vdata_class, order)
> |  | integer file_id, n_records, data_type, order
> |  | character*(*) vdata_name, vdata_class, fieldname
> |  | character*(*) buf

> ##

> [VS Interface][Top]

> VSappendable/vsapp (Obsolete)

> int32 VSappendable(int32 vdata_id, int32 block_size)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | block_size | IN: | Standard block size of appended data

> | Purpose | Makes it possible to append to a vdata.
> | Return value | Retrieves `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | The HDF library makes all vdatas appendable upon creation. Therefore, this routine has been made obsolete.

> | FORTRAN | integer function vsapp(vdata_id, block_size)
> |  | integer vdata_id, block_size

> ##

> [VS Interface][Top]

> VSattach/vsfatch

> int32 VSattach(int32 file_id, int32 vdata_ref, char *access)

> | file_id | IN: | File identifier returned by Hopen
> | vdata_ref | IN: | Reference number of the vdata
> | access | IN: | Access mode

> | Purpose | Attaches to an existing vdata or creates a new vdata.
> | Return value | Returns a vdata identifier if successful and FAIL (or -1) otherwise.
> | Description | VSattach attaches to the vdata identified by the reference number, vdata_ref, in the file identified by the parameter file_id. Access to the vdata is specified by the parameter access. VSattach returns an identifier to the vdata, through which all further operations on that vdata are carried out.
> |  | An existing vdata may be multiply-attached for reads. Only one attach with write access to a vdata is allowed.
> |  | The default interlace mode for a new vdata is FULL_INTERLACE (or 0). This may be changed using VSsetinterlace.
> |  | The value of the parameter vdata_ref may be -1. This is used to create a new vdata.
> |  | Valid values for access are "r" for read access and "w" for write access.
> |  | If access is "r", then vdata_ref must be the valid reference number of an existing vdata returned from any of the vdata and vgroup search routines (e.g., Vgetnext or VSgetid). It is an error to attach to a vdata with a vdata_ref of -1 with "r" access.
> |  | If access is "w", then vdata_ref must be the valid reference number of an existing vdata or -1. An existing vdata is generally attached with "w" access to replace part of its data, or to append new data to it.

> | FORTRAN | integer function vsfatch(file_id, vdata_ref, access)
> |  | integer file_id, vdata_ref
> |  | character*1 access

> ##

> [VS Interface][Top]

> VSattrinfo/vsfainf

> intn VSattrinfo(int32 vdata_id, int32 field_index, intn attr_index, char *attr_name, int32 *data_type, int32 *count, int32 *size)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_index | IN: | Index of the field
> | attr_index | IN: | Index of the attribute
> | attr_name | OUT: | Name of the attribute
> | data_type | OUT: | Data type of the attribute
> | count | OUT: | Attribute value count
> | size | OUT: | Size of the attribute

> | Purpose | Retrieves attribute information of a vdata or a vdata field.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.

> Description

> VSattrinfo gets information on the attribute attached to the vdata, vdata_id, or to the vdata field. Vdata field is specified by its index, field_index. Attribute is specified by its index, attr_index. The attribute name is returned into the parameter attr_name, the data type is returned into the parameter data_type, the number of values of the attribute is returned into the parameter count, and the size of the attribute is returned into the parameter size.

> |  | The parameter field_index in VSattrinfo is the same as the parameter field_index in VSsetattr. It can be set to either an integer field index for the vdata field attribute, or _HDF_VDATA (or -1) to specify the vdata attribute.
> |  | In C the values of the parameters attr_name, data_type, count and size can be set to NULL if the information returned by these parameters is not needed.

> | FORTRAN | integer function vsfainf(vdata_id, field_index, attr_index, attr_name, data_type, count, size)
> |  | integer vdata_id, field_index, attr_index
> |  | character*(*) attr_name
> |  | integer data_type, count, size

> ##

> [VS Interface][Top]

> VSdelete/vsfdlte

> int32 VSdelete(int32 file_id, int32 vdata_ref)

> | file_id | IN: | File identifier returned by Hopen
> | vdata_ref | IN: | Vdata reference number returned by VSattach

> | Purpose | Remove a vdata from a file.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) if not successful.
> | Description | VSdelete removes the vdata identified by the parameter vdata_ref from the file identified by the parameter file_id.

> | FORTRAN | integer function vsfdlte(file_id, vdata_ref)
> |  | integer file_id, vdata_ref

> ##

> [VS Interface][Top]

> VSdetach/vsfdtch

> int32 VSdetach(int32 vdata_id)

> | vdata_id | IN: | Vdata identifier returned by VSattach

> | Purpose | Detaches from the current vdata, terminating further access to that vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSdetach detaches from the vdata identified by the parameter vdata_id and updates the vdata information in the file if there are any changes. All memory used for that vdata is freed.
> |  | The vdata_id identifier should not be used after that vdata is detached.

> | FORTRAN | integer function vsfdtch(vdata_id)
> |  | integer vdata_id

> ##

> [VS Interface][Top]

> VSelts/vsfelts

> int32 VSelts(int32 vdata_id)

> | vdata_id | IN: | Vdata identifier returned by VSattach

> | Purpose | Determines the number of records in a vdata.
> | Return value | Returns the number of records in the vdata if successful and FAIL (or -1) otherwise.
> | Description | VSelts returns the number of records in the vdata identified by vdata_id.

> | FORTRAN | integer function vsfelts(vdata_id)
> |  | integer vdata_id

> ##

> [VS Interface][Top]

> VSfdefine/vsffdef

> intn VSfdefine(int32 vdata_id, char *fieldname, int32 data_type, int32 order)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | fieldname | IN: | Name of the field to be defined
> | data_type | IN: | Data type of the field values
> | order | IN: | Order of the new field

> | Purpose | Defines a new field for in a vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSfdefine defines a field with the name specified by the parameter fieldname, of the data type specified by the parameter data_type, of the order specified by the parameter order, and within the vdata identified by the parameter vdata_id.

> VSfdefine is only used to define fields in a new vdata; it does not set the format of a vdata. Note that defining a field using VSfdefine does not prepare the storage format of the vdata. Once the fields have been defined, the routine VSsetfields must be used to set the format. VSfdefine may only be used with a new empty vdata. Once there is data in a vdata, definitions of vdata fields may not be modified or deleted.

> |  | There are certain field names the HDF library recognizes as predefined. A list of these predefined field types can be found in the HDF User's Guide.
> |  | A field is defined by its name (fieldname), its type (data_type) and its order (order). A fieldname is any sequence of characters. By convention, fieldnames are usually a mnemonic, e.g. "PRESSURE". The type of a field specifies whether a field is float, integer, etc. Thus, data_type may be one of the data types listed in Table 1A in Section I of this manual.
> |  | The order of a field is the number of components in that field. A field containing the value of a simple variable, such a time or pressure, would have an order of 1. Compound variables have an order greater than 1. For example, a field containing the values associated with a variable for velocity in three dimensions would have an order of 3.

> | FORTRAN | integer function vsffdef(vdata_id, fieldname, data_type, order)
> |  | integer vdata_id, data_type, order
> |  | character*(*) fieldname

> ##

> [VS Interface][Top]

> VSfexist/vsfex

> intn VSfexist(int32 vdata_id, char *field_name_list)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_name_list | IN: | List of field names

> | Purpose | Checks to see if certain fields exist in the current vdata.
> | Return value | Returns a value of 1 if all field(s) exist and FAIL (or -1) otherwise.
> | Description | VSfexist checks if all fields with the names specified in the parameter field_name_list exist in the vdata identified by the parameter vdata_id.
> |  | The parameter field_name_list is a string of comma-separated fieldnames (e.g., "PX,PY,PZ" in C and 'PX,PY,PZ' in Fortran).

> | FORTRAN | integer function vsfex(vdata_id, field_name_list)
> |  | integer vdata_id
> |  | character*(*) field_name_list

> ##

> [VS Interface][Top]

> VSfind/vsffnd

> int32 VSfind(int32 file_id, char *vdata_name)

> | file_id | IN: | File identifier returned by Hopen
> | vdata_name | IN: | Name of the vdata

> | Purpose | Returns the reference number of a vdata, given its name.
> | Return value | Returns the vdata reference number if successful and 0 if the vdata is not found or an error occurs.
> | Description | VSfind returns the reference number of the vdata with the name specified by the parameter vdata_name in the file specified by the parameter file_id. If there is more than one vdata with the same name, VSfind will only find the reference number of the first vdata in the file with that name.

> | FORTRAN | integer function vsffnd(file_id, vdata_name)
> |  | integer file_id
> |  | character*(*) vdata_name

> ##

> [VS Interface][Top]

> VSfindattr/vsffdat

> intn VSfindattr(int32 vdata_id, int32 field_index, char *attr_name)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_index | IN: | Field index
> | attr_name | IN: | Attribute name

> | Purpose | Returns the index of an attribute of a vdata or vdata field.
> | Return value | Returns the index of the attribute if successful and FAIL (or -1) otherwise.
> | Description | VSfindattr returns the index of the attribute with the name specified by the parameter attr_name in the vdata identified by the parameter vdata_id.
> |  | To return the index of the attribute attached to the vdata , set the value of the parameter field_index to _HDF_VDATA (or -1). To return the index of the attribute of a field in the vdata , set the value of the parameter field_index to the field index. Valid values of field_index range from 0 to the total number of the vdata fields - 1. The number of the vdata fields is returned by VFnfields.

> | FORTRAN | integer function vsffdat(vdata_id, field_index, attr_name)
> |  | integer vdata_id, field_index
> |  | character*(*) attr_name

> ##

> [VS Interface][Top]

> VSfindclass/vffcls

> int32 VSfindclass(int32 file_id, char *vdata_class)

> | file_id | IN: | File identifier returned by Hopen
> | vdata_class | IN: | Class of the vdata

> | Purpose | Returns the reference number of the first vdata with a given vdata class name
> | Return value | Returns the reference number of the vdata if successful and 0 if the vdata is not found or an error occurs.
> | Description | VSfindclass returns the reference number of the vdata with the class name specified by the parameter vdata_class in the file identified by the parameter file_id.

> | FORTRAN | integer function vffcls(vdata_id, vdata_class)
> |  | integer vdata_id
> |  | character*(*) vdata_class

> ##

> [VS Interface][Top]

> VSfindex/vsffidx

> intn VSfindex(int32 vdata_id, char *fieldname, int32 *field_index)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | fieldname | IN: | Name of the field
> | field_index | OUT: | Index of the field

> | Purpose | Retrieves the index of a field within a vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSfindex retrieves the index, field_index, of the field with a name specified by the parameter fieldname, within the vdata identified by the parameter vdata_id.

> | FORTRAN | integer function vsffidx(vdata_id, fieldname, field_index)
> |  | integer vdata_id, field_index
> |  | character*(*) fieldname

> ##

> [VS Interface][Top]

> VSfnattrs/vsffnas

> int32 VSfnattrs (int32 vdata_id, int32 field_index)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_index | IN: | Index of the field

> | Purpose | Returns the number of attributes attached to a vdata or the number of attributes attached to a vdata field.
> | Return value | Returns the number of attributes assigned to this vdata or its fields when successful, and FAIL (or -1) otherwise.
> | Description | VSfnattrs returns the number of attributes attached to a vdata specified by the parameter vdata_id, or the number of attributes attached to a vdata field, specified by the field index, field_index.
> |  | To return the number of attributes attached to the vdata , set the value of field_index to _HDF_VDATA (or -1). To return the number of attributes of a field in the vdata , set the value of field_index to the field index. Field index is a nonnegative integer less than the total number of the vdata fields. The number of vdata fields is returned by VFnfields.
> |  | VSfnattrs is different from the VSnattrs routine, which returns the number of attributes of the specified vdata and the fields contained in it.

> | FORTRAN | integer function vsffnas(vdata_id, field_index)
> |  | integer vdata_id, field_index

> ##

> [VS Interface][Top]

> VSfpack/vsfcpak/vsfnpak

> intn VSfpack(int32 vdata_id, intn action, char *fields_in_buf, VOIDP buf, intn buf_size, intn n_records, char *field_name_list, VOIDP bufptrs[])

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | action | IN: | Action to be performed
> | fields_in_buf | IN: | Names of the fields in buf
> | buf | IN/OUT: | Buffer containing the values of the packed fields to write to or read from the vdata
> | buf_size | IN: | Buffer size in bytes
> | n_records | IN: | Number of records to pack or unpack
> | field_name_list | IN: | Names of the fields to be packed or unpacked
> | bufptrs | IN/OUT: | Array of pointers to the field buffers

> | Purpose | Packs field data into a buffer or unpacks buffered field data into vdata field(s) for fully interlaced fields.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSfpack packs or unpacks the field(s) listed in the parameter field_name_list to or from the buffer buf according to the specified action in the parameter action.
> |  | Valid values for action are _HDF_VSPACK (or 0) which packs field values from bufptrs (the field buffers) to buf, or _HDF_VSUNPACK (or 1) which unpacks vdata field values from buf into bufptrs.
> |  | When VSfpack is called to pack field values into buf, fields_in_buf must list all fields of the vdata. When VSfpack is called to unpack field values, fields_in_buf may be a subset of the vdata fields. To specify all vdata fields in fields_in_buf, NULL can be used in C and a blank character (" ") in Fortran.
> |  | The name(s) of the field(s) to be packed or unpacked are specified by the field_name_list. In C, the names in the parameter field_name_list can be a subset of or all field names listed in fields_in_buf. To specify all vdata fields, NULL can be used in C.
> |  | The FORTRAN-77 versions of this routine can pack or unpack only one field at a time. Therefore, field_name_list will contain the name of the field that will be packed or unpacked.
> |  | The calling program must allocate sufficient space for buf to hold all of the packed fields. The size of the buf buffer should be at least n_records * (the total size of all fields specified in fields_in_buf).
> |  | Note that there are two FORTRAN-77 versions of this routine: vsfnpak to pack or unpack a numeric field and vsfcpak to pack or unpack a character field.
> |  | Refer to the HDF User's Guide for an example on how to use this routine.

> | FORTRAN | integer function vsfnpak(vdata_id, action, fields_in_buf, buf, buf_size, n_records, field_name_list, bufptrs)
> |  | integer vdata_id, action, buf(*), buf_size, n_records
> |  | character*(*) fields_in_buf, field_name_list
> |  | <valid numeric data type> bufptrs(*)
> |  | integer function vsfcpak(vdata_id, action, fields_in_buf, buf, buf_size, n_records, field_name_list, bufptrs)
> |  | integer vdata_id, action, buf(*), buf_size, n_records
> |  | character*(*) fields_in_buf, field_name_list, bufptrs(*)

> ##

> [VS Interface][Top]

> VSgetattr/vsfgnat/vsfgcat

> intn VSgetattr(int32 vdata_id, intn field_index, int32 attr_index, VOIDP values)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_index | IN: | Index of the field
> | attr_index | IN: | Index of the attribute
> | values | OUT: | Buffer for the attribute values

> | Purpose | Retrieves the attribute values of a vdata or vdata field.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSgetattr retrieves the attribute values of the vdata identified by the parameter vdata_id or the vdata field specified by the field index, field_index, into the buffer values.
> |  | If field_index is set to _HDF_VDATA (or -1), the value of the attribute attached to the vdata is returned. If field_index is set to the field index, attribute attached to a vdata field is returned. Field index is a nonnegative integer less than the total number of the vdata fields. The number of vdata fields is returned by VFnfields
> |  | Attribute to be retrieved is specified by its index, attr_index. Index is a nonnegative integer less than the total number of the vdata or vdata field attributes. Use VSfnattrs to find the number of the vdata or vdata field attributes.

> | FORTRAN | integer function vsfgnat(vdata_id, field_index, attr_index, values)
> |  | integer vdata_id, field_index, attr_index
> |  | <valid numeric data type> values(*)
> |  | integer function vsfgcat(vdata_id, field_index, attr_index, values)
> |  | integer vdata_id, field_index, attr_index
> |  | character*(*) values

> ##

> [VS Interface][Top]

> VSgetblockinfo/vsfgetblinfo

> intn VSgetblockinfo(int32 vdata_id, int32 *block_size, int32 *num_blocks)

> | vdata_id | IN: | Vdata identifier
> | block_size | OUT: | Block size in bytes
> | num_blocks | OUT: | Number of linked blocks

> | Purpose | Retrieves the block size and the number of blocks for a linked-block Vdata element.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSgetblockinfo retrieves the block size and the number of linked blocks for a linked-block Vdata element.
> |  | If no response is desired for either returned value, block_size and num_blocks may be set to `NULL`.

> | FORTRAN | integer function vsfgetblinfo(vdata_id, block_size, num_blocks)
> |  | integer vdata_id, num_blocks, block_size

> ##

> [VS Interface][Top]

> VSgetclass/vsfgcls

> int32 VSgetclass(int32 vdata_id, char *vdata_class)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | vdata_class | OUT: | Vdata class name

> | Purpose | Retrieves the vdata class name, if any.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSgetclass retrieves the class name of the vdata identified by the parameter vdata_id and places it in the buffer vdata_class.
> |  | Space for the buffer vdata_class must be allocated by the calling program before VSgetclass is called. The maximum length of the class name is defined by the macro VSNAMELENMAX (or 64).

> | FORTRAN | integer function vsfgcls(vdata_id, vdata_class)
> |  | integer vdata_id
> |  | character*(*) vdata_class

> ##

> [VS Interface][Top]

> VSgetfields/vsfgfld

> int32 VSgetfields(int32 vdata_id, char *field_name_list)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_name_list | OUT: | Field name list

> | Purpose | Retrieves the field names of all of the fields in a Vdata.
> | Return value | Returns the number of fields in the Vdata if successful and FAIL (or -1) otherwise.
> | Description | VSgetfields retrieves the names of the fields in the Vdata identified by the parameter vdata_id into the buffer field_name_list.
> |  | The parameter field_name_list is a character string containing a comma-separated list of names (e.g., "PX,PY,PZ" in C or `PX,PY,PZ' in Fortran).
> |  | The user must allocate the memory space for the buffer field_name_list before calling VSgetfields.
> |  | If the Vdata does not have any fields, a null string is returned in the parameter field_name_list.
> |  | The maximum length of a Vdata name is defined by VSNAMELENMAX (or 64).

> | FORTRAN | integer function vsfgfld(vdata_id, field_name_list)
> |  | integer vdata_id
> |  | character*(*) field_name_list

> ##

> [VS Interface][Top]

> VSgetid/vsfgid

> int32 VSgetid(int32 file_id, int32 vdata_ref)

> | file_id | IN: | File identifier returned by Hopen
> | vdata_ref | IN: | Vdata reference number

> | Purpose | Sequentially searches through a file for vdatas.
> | Return value | Returns the reference number for the next vdata if successful and FAIL (or -1) otherwise.
> | Description | VSgetid sequentially searches through a file identified by the parameter file_id and returns the reference number of the next vdata after the vdata that has reference number vdata_ref. This routine is generally used to sequentially search the file for vdatas. Searching past the last vdata in a file will result in an error condition.
> |  | To initiate a search, this routine must be called with the value of vdata_ref equal to -1. Doing so returns the reference number of the first vdata in the file.

> | FORTRAN | integer function vsfgid(file_id, vdata_ref)
> |  | integer file_id, vdata_ref

> ##

> [VS Interface][Top]

> VSgetinterlace/vsfgint

> int32 VSgetinterlace(int32 vdata_id)

> | vdata_id | IN: | Vdata identifier returned by VSattach

> | Purpose | Returns the interlace mode of a vdata.
> | Return value | Returns FULL_INTERLACE (or 0) or NO_INTERLACE (or 1) if successful and FAIL (or -1) otherwise.
> | Description | VSgetinterlace returns the interlace mode of the vdata identified by the parameter vdata_id.

> | FORTRAN | integer function vsfgint(vdata_id)
> |  | integer vdata_id

> ##

> [VS Interface][Top]

> VSgetname/vsfgnam

> int32 VSgetname(int32 vdata_id, char *vdata_name)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | vdata_name | OUT: | Vdata name

> | Purpose | Retrieves the name of a vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSgetname retrieves the name of the vdata identified by the parameter vdata_id into the buffer vdata_name.
> |  | The user must allocate the memory space for the buffer vdata_name before calling VSgetname. If the vdata does not have a name, a null string is returned in the parameter vdata_name . The maximum length of a vdata name is defined by VSNAMELENMAX (or 64)

> | FORTRAN | integer function vsfgnam(vdata_id, vdata_name)
> |  | integer vdata_id
> |  | character*(*) vdata_name

> ##

> [VS Interface][Top]

> VSgetversion/vsgver

> int32 VSgetversion(int32 vdata_id)

> | vdata_id | IN: | Vdata identifier returned by VSattach

> | Purpose | Returns the version number of a vdata.
> | Return value | Returns the version number if successful and FAIL (or -1) otherwise.
> | Description | VSgetversion returns the version number of the vdata identified by the parameter vdata_id. There are three valid version numbers: VSET_OLD_VERSION (or 2), VSET_VERSION (or 3), and VSET_NEW_VERSION (or 4).
> |  | VSET_OLD_VERSION is returned when the vdata is of a version that corresponds to an HDF library version before version 3.2.
> |  | VSET_VERSION is returned when the vdata is of a version that corresponds to an HDF library version between versions 3.2 and 4.0 release 2.
> |  | VSET_NEW_VERSION is returned when the vdata is of the version that corresponds to an HDF library version of version 4.1 release 1 or higher.

> | FORTRAN | integer vsgver(vdata_id)
> |  | integer vdata_id

> ##

> [VS Interface][Top]

> VSinquire/vsfinq

> intn VSinquire(int32 vdata_id, int32 *n_records, int32 *interlace_mode, char *field_name_list, int32 *vdata_size, char *vdata_name)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | n_records | OUT: | Number of records
> | interlace_mode | OUT: | Interlace mode of the data
> | field_name_list | OUT: | List of field names
> | vdata_size | OUT: | Size of a record
> | vdata_name | OUT: | Name of the vdata

> | Purpose | Retrieves general information about a vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) if it is unable to return any of the requested information.

> Description

> VSinquire retrieves the number of records, the interlace mode of the data, the name of the fields, the size, and the name of the vdata, vdata_id, and stores them in the parameters n_records, interlace_mode, field_name_list, vdata_size, and vdata_name, respectively. In C, if any of the output parameters are NULL, the corresponding information will not be retrieved. Refer to the Reference Manual pages on VSelts, VSgetfields, VSgetinterlace, VSsizeof and VSgetname for other routines that can be used to retrieve specific information.

> |  | Possible returned values for interlace_mode are FULL_INTERLACE (or 0) and NO_INTERLACE (or 1). The returned value of vdata_size is the number of bytes in a record and is machine-dependent.
> |  | The parameter field_name_list is a character string that contains the names of all the vdata fields, separated by commas. (e.g., "PX,PY,PZ" in C and 'PX,PY,PZ' in Fortran).
> |  | The user must allocate the memory space for the buffer vdata_name before calling VSinquire. If the vdata does not have a name, a null string is returned in the parameter vdata_name . The maximum length of a vdata name is defined by VSNAMELENMAX (or 64)
> | Note | VSinquire will return `FAIL` if it is called before VSdefine and VSsetfield on the same vdata.

> | FORTRAN | integer function vsfinq(vdata_id, n_records, interlace, field_name_list, vdata_size, vdata_name)
> |  | integer vdata_id, n_records, interlace, vdata_size
> |  | character*(*) field_name_list, vdata_name

> ##

> [VS Interface][Top]

> VSisattr/vsfisat

> intn VSisattr(int32 vdata_id)

> | vdata_id | IN: | Vdata identifier returned by VSattach

> | Purpose | Determines whether a vdata is an attribute.
> | Return value | Returns TRUE (or 1) if the vdata is an attribute, and FALSE (or 0) otherwise.
> | Description | VSisattr determines whether the vdata identified by the parameter vdata_id is an attribute.
> |  | As attributes are stored by the HDF library as vdatas, a means of testing whether or not a particular vdata is an attribute is needed, and is provided by this routine.

> | FORTRAN | integer function vsfisat(vdata_id)
> |  | integer vdata_id

> ##

> [VS Interface][Top]

> VSlone/vsflone

> int32 VSlone(int32 file_id, int32 ref_array[], int32 maxsize)

> | file_id | IN: | File identifier returned by Hopen
> | ref_array | OUT: | Array of reference numbers
> | max_refs | IN: | Maximum number of lone vdatas to be retrieved

> | Purpose | Retrieves the reference numbers of all lone vdatas, i.e., vdatas that are not grouped with other objects, in a file.
> | Return value | Returns the total number of lone vdatas if successful and FAIL (or -1) otherwise.
> | Description | VSlone retrieves the reference numbers of lone vgroups in the file identified by the parameter file_id. Although VSlone returns the number of lone vdatas in the file, only at most max_refs reference numbers are retrieved and stored in the buffer ref_array. The array must have at least max_refs elements.
> |  | An array size of 65,000 integers for ref_array is more than adequate if the user chooses to declare the array statically. However, the preferred method is to dynamically allocate memory instead; first call VSlone with a value of 0 for max_refs to return the total number of lone vdatas, then use the returned value to allocate memory for ref_array before calling VSlone again.

> | FORTRAN | integer function vsflone(file_id, ref_array, max_refs)
> |  | integer file_id, ref_array(*), max_refs

> ##

> [VS Interface][Top]

> VSnattrs/vsfnats

> intn VSnattrs(int32 vdata_id)

> | vdata_id | IN: | Vdata identifier returned by VSattach

> | Purpose | Returns the total number of attributes of a vdata and of its fields.
> | Return value | Returns the total number of attributes if successful and FAIL (or -1) otherwise.
> | Description | VSnattrs returns the total number of attributes of the vdata, vdata_id, and of its fields.
> |  | VSnattrs is different from the VSfnattrs routine, which returns the number of attributes of a specified vdata or of a field contained in a specified vdata.

> | FORTRAN | integer function vsfnats(vdata_id)
> |  | integer vdata_id

> ##

> [VS Interface][Top]

> VSread/vsfrd/vsfrdc/vsfread

> int32 VSread(int32 vdata_id, uint8 *databuf, int32 n_records, int32 interlace_mode)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | databuf | OUT: | Buffer to store the retrieved data
> | n_records | IN: | Number of records to be retrieved
> | interlace_mode | IN: | Interlace mode of the data to be stored in the buffer

> | Purpose | Retrieves data from a vdata.
> | Return value | Returns the total number of records read if successful and FAIL (or -1) otherwise.
> | Description | VSread reads n_records records from the vdata identified by the parameter vdata_id and stores the data in the buffer databuf using the interlace mode specified by the parameter interlace_mode.
> |  | The user can specify the fields and the order in which they are to be read by calling VSsetfields prior to reading. VSread stores the requested fields in databuf in the specified order.

> Valid values for interlace_mode are FULL_INTERLACE (or 1) and NO_INTERLACE (or 0). Selecting FULL_INTERLACE causes databuf to be filled by record and is recommended for speed and efficiency. Specifying NO_INTERLACE causes databuf to be filled by field, i.e., all values of a field in n_records records are filled before moving to the next field. Note that the default interlace mode of the buffer is FULL_INTERLACE.

> |  | As the data is stored contiguously in the vdata, VSfpack should be used to unpack the fields after reading. Refer to the discussion of VSfpack in the HDF User's Guide for more information.
> |  | Note that there are three FORTRAN-77 versions of this routine: vsfrd is for buffered numeric data, vsfrdc is for buffered character data and vsfread is for generic packed data.
> |  | See the notes regarding the potential performance impact of appendable data sets in the HDF User's Guide Section 14.4.3, "Unlimited Dimension Data Sets (SDSs and Vdatas) and Performance."

> | FORTRAN | On Windows systems, this function is available only for an integer data buffer.
> |  | integer function vsfrd(vdata_id, databuf, n_records, interlace_mode)
> |  | integer vdata_id, n_records, interlace_mode
> |  | <valid numeric data type> databuf(*)
> |  | integer function vsfrdc(vdata_id, databuf, n_records, interlace_mode)
> |  | integer vdata_id, n_records, interlace_mode
> |  | character*(*) databuf
> |  | integer function vsfread(vdata_id, databuf, n_records, interlace_mode)
> |  | integer vdata_id, n_records, interlace_mode
> |  | integer databuf(*)

> ##

> [VS Interface][Top]

> VSseek/vsfseek

> int32 VSseek(int32 vdata_id, int32 record_pos)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | record_pos | IN: | Position of the record

> | Purpose | Provides a mechanism for random-access I/O within a vdata.
> | Return value | Returns the record position (zero or a positive integer) if successful and FAIL (or -1) otherwise.
> | Description | VSseek moves the access pointer within the vdata identified by the parameter vdata_id to the position of the record specified by the parameter record_pos. The next call to VSread or VSwrite will read from or write to the record where the access pointer has been moved to.
> |  | The value of record_pos is zero-based. For example, to seek to the third record in the vdata, set record_pos to 2. The first record position is specified by specifying a record_pos value of 0. Each seek is constrained to a record boundary within the vdata.
> |  | See the notes regarding the potential performance impact of appendable data sets in the HDF User's Guide Section 14.4.3, "Unlimited Dimension Data Sets (SDSs and Vdatas) and Performance."

> | FORTRAN | integer function vsfseek(vdata_id, record_pos)
> |  | integer vdata_id, record_pos

> ##

> [VS Interface][Top]

> VSsetattr/vsfsnat/vsfscat

> intn VSsetattr(int32 vdata_id, int32 field_index, char *attr_name, int32 data_type, int32 count, VOIDP values)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_index | IN: | Index of the field
> | attr_name | IN: | Name of the attribute
> | data_type | IN: | Data type of the attribute
> | count | IN: | Number of attribute values
> | values | IN: | Buffer containing the attribute values

> | Purpose | Sets an attribute of a vdata or a vdata field.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetattr defines an attribute that has the name specified by the parameter attr_name, the data type specified by the parameter data_type, and the number of values specified by the parameter count, and that contains the values specified in the parameter values. The attribute is set for either the vdata or a vdata field depending on the value of the parameter field_index.
> |  | If the field already has an attribute with the same name, the current values will be replaced with the new values if the new data type and order are the same as the current ones. Any changes in the field data type or order will result in a value of FAIL (or -1) to be returned.
> |  | If field_index value is set to _HDF_VDATA (or -1), the attribute will be set for the vdata. If field_index is set to the field index, attribute will be set for the vdata field. Field index is a nonnegative integer less than the total number of the vdata fields. The number of vdata fields can be obtained using VFnfields.
> |  | The value of the parameter data_type can be any one of the data types listed in Table 1A in Section I of this manual.

> | FORTRAN | integer function vsfsnat(vdata_id, field_index, attr_name, data_type, count, values)
> |  | integer vdata_id, field_index, data_type, count, values(*)
> |  | character*(*) attr_name
> |  | integer function vsfscat(vdata_id, field_index, attr_name, data_type, count, values)
> |  | integer vdata_id, field_index, data_type, count
> |  | character*(*) attr_name, values(*)

> ##

> [VS Interface][Top]

> VSsetblocksize/vsfsetblsz

> intn VSsetblocksize(int32 vdata_id, int32 block_size)

> | vdata_id | IN: | Vdata identifier
> | block_size | IN: | Size of each block in bytes

> | Purpose | Sets linked-block Vdata element block size.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetblocksize sets the block size for linked-block elements that will be used to store Vdatas.
> |  | The default block size is `HDF_APPENDABLE_BLOCK_LEN`, which is set to `4096` in the library as it is distributed. VSsetblocksize modifies that default value and must be called before the first write to the Vdata. Once the linked-block element is created, the block size cannot be changed.

> The following note may be of interest to users who must pay very close attention to performance issues: VSsetblocksize sets the block size only for blocks following the first block. The first block can be arbitrarily large; the library continues to write to it until it encounters an obstacle, at which point the linked block mechanism is invoked. For example, a Vdata A that is the last item in a file can continue to grow, simply extending the file. If a new Vdata B is then written, that new object is (normally) placed at the end of the file, blocking off extension of the prior Vdata, A. At this point, new writes to A will write data to linked blocks per the block_size and num_blocks settings.

> | FORTRAN | integer function vsfsetblsz(vdata_id, block_size)
> |  | integer vdata_id, block_size

> ##

> [VS Interface][Top]

> VSsetclass/vsfscls

> int32 VSsetclass(int32 vdata_id, char *vdata_class)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | vdata_class | IN: | Name of the vdata class

> | Purpose | Sets the class name of a vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetclass sets the class name of the vdata identified by the parameter vdata_id to the value of the parameter vdata_class.
> |  | At creation, the class name of a vdata is NULL. The class name may be reset more than once. Class names, like vdata names, can be any character string. They exist solely as meaningful labels to user applications and are not used by the HDF library in any way. Class names will be truncated to VSNAMELENMAX (or 64) characters.

> | FORTRAN | integer function vsfscls(vdata_id, vdata_class)
> |  | integer vdata_id
> |  | character*(*) vdata_class

> ##

> [VS Interface][Top]

> VSsetexternalfile/vsfsextf

> intn VSsetexternalfile(int32 vdata_id, char *filename, int32 offset)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | filename | IN: | Name of the external file
> | offset | IN: | Offset, in bytes, of the location in the external file the new data is to be written

> | Purpose | Stores vdata information in an external file.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetexternalfile writes data in the vdata identified by the parameter vdata_id in the file named filename, at the byte offset specified by the parameter offset.
> |  | Only the data will be stored externally. Attributes and all metadata will remain in the primary HDF file.
> |  | IMPORTANT: The user must ensure that the external files are relocated along with the primary file.
> |  | Read the Reference Manual page on SDsetexternalfile for more information on using the external file feature.

> | FORTRAN | integer function vsfsextf(vdata_id, filename, offset)
> |  | integer vdata_id, offset
> |  | character*(*) filename

> ##

> [VS Interface][Top]

> VSsetfields/vsfsfld

> intn VSsetfields(int32 vdata_id, char *field_name_list)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_name_list | IN: | List of the field names to be accessed

> | Purpose | Specifies the fields to be accessed.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetfields specifies that the fields, whose names are listed in the parameter field_name_list, of the vdata identified by the parameter vdata_id will be accessed by the next call to VSread or VSwrite. VSsetfields must be called before any call to VSread or VSwrite.
> |  | For reading from a vdata, a call to VSsetfields sets up the fields that are to be retrieved from the records in the vdata. If the vdata is empty, VSsetfields will return FAIL (or -1).
> |  | For writing to a vdata, VSsetfields can only be called once, to set up the fields in a vdata. Once the vdata fields are set, they may not be changed. Thus, to update some fields of a record after the first write, the user must read all the fields to a buffer, update the buffer, then write the entire record back to the vdata.
> |  | The parameter field_name_list is a character string that contains a comma-separated list of fieldnames (i.e., "PX,PY,PZ" in C and 'PX,PY,PZ' in Fortran). The combined width of the fields in a vdata must be less than MAX_FIELD_SIZE (or 65535) bytes. If an attempt to create a larger record is made, VSsetfields will return FAIL (or -1).
> |  | If the vdata is attached with an "r" access mode, the parameter field_name_list must contain only the fields that already exist in the vdata. If the vdata is attached with a "w" access mode, field_name_list can contain the names of any fields that have been defined by VSfdefine or any predefined fields.

> | FORTRAN | integer function vsfsfld(vdata_id, field_name_list)
> |  | integer vdata_id
> |  | character*(*) field_name_list

> ##

> [VS Interface][Top]

> VSsetinterlace/vsfsint

> intn VSsetinterlace(int32 vdata_id, int32 interlace_mode)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | interlace_mode | IN: | Interlace mode of the data to be stored in the vdata

> | Purpose | Sets the interlace mode of a vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetinterlace sets the interlace mode of the vdata, vdata_id, to that specified by the parameter interlace_mode. This routine can only be used when creating new vdatas with write access.
> |  | The value of interlace_mode may be either FULL_INTERLACE (or 0) or NO_INTERLACE (or 1). If this routine is not called, the default interlace mode of the vdata is FULL_INTERLACE. The FULL_INTERLACE option is more efficient than NO_INTERLACE although both require the same amount of disk space.
> |  | Specifying FULL_INTERLACE accesses the vdata by record; in other words, all values of all fields in a record are accessed before moving to the next record. Specifying NO_INTERLACE accesses the vdata by field; in other words, all field values are accessed before moving to the next field. Thus, for writing data, all record data must be available before the write operation is invoked.
> |  | Note that the interlace mode of the data to be written is specified by a parameter of the VSwrite routine.

> | FORTRAN | integer function vsfsint(vdata_id, interlace_mode)
> |  | integer vdata_id, interlace_mode

> ##

> [VS Interface][Top]

> VSsetname/vsfsnam

> int32 VSsetname(int32 vdata_id, char *vdata_name)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | vdata_name | IN: | Name of the vdata

> | Purpose | Assigns a name to a vdata.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetname sets the name of the vdata identified by the parameter vdata_id to the value of the parameter vdata_name.
> |  | At creation, the name of the vdata is NULL. The name may be reset more than once. Vdata names, like class names, can be any character string. They exist solely as a meaningful label for user applications and are not used by the HDF library in any way. Vdata names will be truncated to VSNAMELENMAX (or 64) characters.

> | FORTRAN | integer function vsfsnam(vdata_id, vdata_name)
> |  | integer vdata_id
> |  | character*(*) vdata_name

> ##

> [VS Interface][Top]

> VSsetnumblocks/vsfsetnmbl

> intn VSsetnumblocks(int32 vdata_id, int32 num_blocks)

> | vdata_id | IN: | Vdata identifier
> | num_blocks | IN: | Number of blocks to be used for the linked-block element

> | Purpose | Sets the number of blocks for a linked-block Vdata element.
> | Return value | Returns `SUCCEED` (or 0) if successful and FAIL (or -1) otherwise.
> | Description | VSsetnumblocks sets the number of blocks in linked-block elements that will be used to store Vdatas.
> |  | The default number of blocks is `HDF_APPENDABLE_BLOCK_NUM`, which is set to `16` in the library as it is distributed. VSsetnumblocks modifies that default value and must be called before the first write to the Vdata. Once the linked-block element is created, the number of blocks cannot be changed.

> | FORTRAN | integer function vsfsetnmbl(vdata_id, num_blocks)
> |  | integer vdata_id, num_blocks

> ##

> [VS Interface][Top]

> VSsizeof/vsfsiz

> int32 VSsizeof(int32 vdata_id, char *field_name_list)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | field_name_list | IN: | Name(s) of the fields to check

> | Purpose | Computes the size, in bytes, of the given field(s) for the local machine.
> | Return value | Returns the fields size if successful and FAIL (or -1) otherwise.
> | Description | VSsizeof computes the size, in bytes, of the fields specified in the parameter field_name_list in the vdata identified by the parameter vdata_id.
> |  | The parameter field_name_list specifies a single field or several comma-separated fields. The field or fields should already exist in the vdata. If more than one field is specified, VSsizeof will return the total sizes of all of the fields.

> | FORTRAN | integer function vsfsiz(vdata_id, field_name_list)
> |  | integer vdata_id
> |  | character*(*) field_name_list

> ##

> [VS Interface][Top]

> VSwrite/vsfwrt/vsfwrtc/vsfwrit

> int32 VSwrite(int32 vdata_id, uint8 *databuf, int32 n_records, int32 interlace_mode)

> | vdata_id | IN: | Vdata identifier returned by VSattach
> | databuf | IN: | Buffer of records to be written to the vdata
> | n_records | IN: | Number of records to be written
> | interlace_mode | IN: | Interlace mode of the buffer in memory

> | Purpose | Writes data to a vdata.
> | Return value | Returns the total number of records written if successful and FAIL (or -1) otherwise.
> | Description | VSwrite writes the data stored in the buffer databuf into the vdata identified by the parameter vdata_id. The parameter n_records specifies the number of records to be written. The parameter interlace_mode defines the interlace mode of the vdata fields stored in the buffer databuf.

> Valid values for interlace_mode are FULL_INTERLACE (or 0) and NO_INTERLACE (or 1). Selecting FULL_INTERLACE fills databuf by record and is recommended for speed and efficiency. Specifying NO_INTERLACE causes databuf to be filled by field, i.e., all values of a field in all records must be written before moving to the next field. Thus, all data must be available before writing. If the data is to be written to the vdata with an interlace mode different from that of the buffer, VSsetinterlace must be called prior to VSwrite. Note that the default interlace mode of a vdata is FULL_INTERLACE.

> It is assumed that the data in databuf is organized as specified by the parameter interlace_mode. The number and order of the fields organized in the buffer must correspond with the number and order of the fields specified in the call to VSsetfields, which finalizes the vdata fields definition. Since VSwrite writes the data in databuf contiguously to the vdata, VSfpack must be used to remove any "padding", or non-data spaces, used for vdata field alignment. This process is called packing. Refer to the discussion of VSfpack in the HDF User's Guide for more information.

> |  | Before writing data to a newly-created vdata, VSdefine and VSsetfields must be called to define the fields to be written.
> |  | Note that there are three FORTRAN-77 versions of this routine: vsfwrt is for buffered numeric data, vsfwrtc is for buffered character data and vsfwrit is for generic packed data.

> | FORTRAN | On Windows systems, this function is available only for an integer data buffer.
> |  | integer function vsfwrt(vdata_id, databuf, n_records, interlace_mode)
> |  | integer vdata_id, n_records, interlace_mode
> |  | <valid numeric data type> databuf(*)
> |  | integer function vsfwrtc(vdata_id, databuf, n_records, interlace_mode)
> |  | integer vdata_id, n_records, interlace_mode
> |  | character*(*) databuf
> |  | integer function vsfwrit(vdata_id, databuf, n_records, interlace_mode)
> |  | integer vdata_id, n_records, interlace_mode
> |  | character*(*) databuf

HDF4.2r4 - February 2009 Copyright | The HDF Group www.hdfgroup.org