[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]
VSgetattdatainfo
intn VSgetattdatainfo(int32 vdata_id, int32 field_index, char* attr_index, int32* offset, int32* length)
|
vdata_id
|
IN:
|
Vdata identifier returned by VSattach
|
|
field_index
|
IN:
|
Index of the field
|
|
attr_index
|
IN:
|
Index of the attribute
|
|
offset
|
OUT:
|
Offset of the attribute's data
|
|
length
|
OUT:
|
Length of the attribute's data
|
|
Purpose
|
Retrieves location and size of the data of an attribute (H4 Mapping project specific.)
|
|
Return value
|
Returns the number of data blocks retrieved, which should be 1, if successful and FAIL (or -1) otherwise.
|
|
Description
|
VSgetattdatainfo retrieves the offset and length of the data that belongs to the attribute specified its index, attr_index. The specified attribute is either attached to the vdata, specified by vdata_id, or to the vdata field, depending on the value of the parameter field_index. To specify an attribute of a vdata, the application will set field_index to _HDF_VDATA (or -1 ). To specify an attribute of a vdata field, the application will set field_index to the index of the vdata field. A valid 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 parameter attr_index specifies the position of the attribute in the list of all attributes belonging to the vdata or the vdata field. VSfnattrs routine can be used to obtain the number of attributes of a vdata or of a field contained in the vdata.
|
|
FORTRAN
|
Currently unavailable
|
|
|
|
[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]
VSgetdatainfo
intn VSgetdatainfo(int32 vdata_id, uintn start_block, uintn info_count, int32 *offsetarray, int32 *lengtharray)
|
vdata_id
|
IN:
|
Vdata identifier returned by VSattach
|
|
start_block
|
IN:
|
Value indicating where to start reading offsets
|
|
info_count
|
IN:
|
Number of elements each offset or length list can hold
|
|
offsetarray
|
OUT:
|
Array to hold offsets of the data blocks
|
|
lengtharray
|
OUT:
|
Array to hold lengths of the data blocks
|
|
Purpose
|
Retrieves location and size of data blocks in a specified vdata, after a specified data block (H4 Mapping project specific.)
|
|
Return value
|
Returns the actual number of blocks in the vdata's data or the number of blocks retrieved if successful and FAIL (or -1) otherwise.
|
|
Description
|
VSgetdatainfo retrieves two lists containing the offsets and lengths of the blocks of data belonging to the vdata specified by vdata_id.
|
|
|
The parameter info_count provides the number of offset/length values that the lists offsetarray and lengtharray can hold. The application can first invoke VSgetdatainfo passing in 0 for info_count and NULL for both arrays to get the value for info_count and to provide proper memory allocation for offsetarray and lengtharray in the next call to VSgetdatainfo.
|
|
|
The parameter start_block indicates the block number where to start reading the offsets from the file. The combination of parameters info_count and start_block provide applications with flexibility of where and how much data information to retrieve. The value for start_block must be non-negative and smaller than or equal to the number of blocks in the vdata's data.
- When start_block is 0, VSgetdatainfo will start getting data info from the beginning of the vdata's data.
- When start_block is greater than the number of blocks in the vdata, VSgetdatainfo will return
FAIL (or -1 ).
|
|
FORTRAN
|
currently unavailable
|
|
|
|
|
|
|
[VS Interface][Top]
VSgetexternalfile
intn VSgetexternalfile(int32 vdata_id, uintn buf_size, char *filename, int32 *offset)
|
vdata_id
|
IN:
|
Vdata identifier returned by VSattach
|
|
buf_size
|
IN:
|
Size of buffer for external file name
|
|
filename
|
OUT:
|
Buffer for external file name
|
|
offset
|
OUT:
|
Offset, in bytes, of the location in the external file where the data was written
|
|
Purpose
|
Retrieves information about external file of the vdata.
|
|
Return value
|
Returns length of the external file name if successful or FAIL (or -1 ) otherwise.
|
|
Description
|
If the vdata has external element, VSgetexternalfile will retrieve the name of the external file and the offset where the data is being stored in the external file. If the vdata does not have external element, VSgetexternalfile will return FAIL .
|
|
|
To sufficiently allocate buffer for the file name, an application can call VSgetexternalfile passing in 0 for buf_size. If the length returned is greater than 0 , the application will use it to allocate the buffer before calling VSgetexternalfile again to get the actual file name.
|
|
Note
|
It is the user's responsibility to see that the external files are kept with the main file prior to accessing the vdata with external element. The function will fail if the external file is missing from the directory where the main file is located.
|
|
FORTRAN
|
Currently unavailable
|
|
|
|
[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]
VSgetvdatas
intn VSgetvdatas(int32 id, const uintn start_vd, const uintn n_vds, uint16 *refarray)
|
id
|
IN:
|
File identifier returned by Hopen or vgroup identifier returned by Vattach
|
|
start_vd
|
IN:
|
Vdata number to start retrieving at
|
|
vd_count
|
IN:
|
Number of vdatas to be retrieved
|
|
refarray
|
OUT:
|
Array to hold reference numbers of retrieved vdatas
|
|
Purpose
|
Retrieves reference numbers of vdatas in a file or in a vgroup.
|
|
Return value
|
Returns the actual number of user-created vdatas retrieved if successful, and FAIL (-1 ) otherwise.
|
|
Description
|
VSgetvdatas retrieves a list containing the reference numbers of vdatas found in a file or under a vgroup. The file or the vgroup is specified by id.
|
|
|
The retrieved vdatas will be the ones that were previously created by user applications, not including those that were created by the library internally. They are referred to as user-created vdatas, for brevity.
|
|
|
The parameter vd_count provides the number of items that the list refarray can hold. The retrieval starts at the vdata number start_vd going forward in the order which the vdatas were created. For example, if there are 100 vdatas that can be retrieved, specifying start_vd as 90 and vd_count as 10 will retrieve the last ten vdatas. The value for start_vd must be non-negative and smaller than or equal to the number of user-created vdatas in the specified file or vgroup.
|
|
|
- When start_vd is 0, VSgetvdatas will start retrieving at the beginning of the file or the first vdata of the specified vgroup.
- When start_vd is between 0 and the number of user-created vdatas in the file or the vgroup, VSgetvdatas will start retrieving vdatas from the vdata number start_vd.
- When start_vd is greater than the number of user-created vdatas in the file or the vgroup, VSgetvdatas will return
FAIL .
|
|
|
To allocate sufficient memory for refarray, the application can first invoke VSgetvdatas passing in NULL for refarray to get the value for vd_count then call VSgetvdatas again with proper memory allocation for refarray.
|
|
|
When id is a vgroup identifier, only the immediate vdatas will be retrieved; that is, the sub-vgroups will not be searched.
|
|
FORTRAN
|
Currently unavailable
|
|
|
|
[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]
VSofclass
intn VSofclass(int32 id, const char *vsclass, const uintn start_vd, const uintn n_vds, uint16 *refarray)
|
id
|
IN:
|
File identifier, returned by Hopen, or vgroup identifier, returned by Vattach
|
|
vsclass
|
IN:
|
Name of class for vdatas to be queried
|
|
start_vd
|
IN:
|
Vdata number to start retrieving at
|
|
n_vds
|
IN:
|
Number of vdatas to retrieve
|
|
refarray
|
OUT:
|
Array to hold vdata reference numbers
|
|
Purpose
|
Retrieves reference numbers of vdatas of the specified class.
|
|
Return value
|
Returns 0 if none is found, FAIL (-1 ) if error occurs, or the number of reference numbers returned in the refarray, if successful.
|
|
Description
|
VSofclass retrieves n_vds vdatas by their reference numbers via the caller-supplied array refarray. The vdatas to be retrieved have class name as vsclass.
|
|
|
The parameter n_vds provides the number of values that the refarray list can hold and can be any positive number smaller than MAX_REF (65535 ). If n_vds is larger than the actual number of vdatas that has the specified class, then only the actual number of vdatas will be retrieved.
|
|
|
The parameter start_vd specifies the vdata number where the retrieval will start.
- When start_vd is
0 , VSofclass will start retrieving at the beginning.
- When start_vd is between
0 and the number of vdatas that meet the search criteria, VSofclass will start retrieving from the vdata number start_vd.
- When start_vd is greater than the number of vdatas that meet the search criteria, VSofclass will return
FAIL .
|
|
|
When refarray argument is NULL , VSofclass will return the actual number of vdatas that meet the search criteria. This will allow application to determine the size of the array for dynamic allocation before invoking VSofclass again.
|
|
FORTRAN
|
Currently unavailable
|
|
|
|
[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. Consequently, the library does not check for uniqueness among vdatas. In addition, 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.
|
|
|
Refer to 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. Consequently, the library does not check for uniqueness of the name. In addition, 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
|