# HDF Reference Manual

> ##

> [H Advance Interface][Top]

> Happendable

> intn Happendable(int32 h_id)

> | h_id | IN: | Access identifier returned by Hstartwrite

> | Purpose | Specifies that the specified element can be appended to
> | Return value | Returns `SUCCEED` (or 0) if data element can be appended and `FAIL` (or -1) otherwise.
> | Description | If a data element is at the end of a file Happendable allows Hwrite to append data to it, converting it to linked-block element only when necessary.

> ##

> [H Advance Interface][Top]

> Hcache

> intn Hcache(int32 file_id, intn cache_switch)

> | file_id | IN: | File identifier returned by Hopen
> | cache_switch | IN: | Flag to enable or disable caching

> | Purpose | Enables low-level caching for the specified file.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | If file_id is set to CACHE_ALL_FILES, then the value of cache_switch is used to modify the default file cache setting.
> |  | Valid values for cache_switch are: TRUE (or 1) to enable caching and FALSE (or 0) to disable caching.

> ##

> [H Advance Interface][Top]

> Hdeldd

> intn Hdeldd(int32 file_id, uint16 tag, uint16 ref)

> | file_id | IN: | File identifier returned by Hopen
> | tag | IN: | Tag of data descriptor to be deleted
> | ref | IN: | Reference number of data descriptor to be deleted

> | Purpose | Deletes a tag and reference number from the data descriptor list.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | Once the data descriptor is removed, the data in the data object becomes inaccessible and is marked as such. To remove inaccessible data from an HDF file, use the utility hdfpack.
> |  | Hdeldd only deletes the specified tag and reference number from the data descriptor list. Data objects containing the deleted tag and reference number are not automatically updated. For example, if the tag and reference number deleted from the descriptor list referenced an object in a vgroup, the tag and reference number will still exist in the vgroup even though the data is inaccessible.

> ##

> [H Advance Interface][Top]

> Hendaccess

> intn Hendaccess(int32 h_id)

> | h_id | IN: | Access identifier returned by Hstartread, Hstartwrite, or Hnextread

> | Purpose | Terminates access to a data object by disposing of the access identifier.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | The number of active access identifiers is limited to MAX_ACC as defined in the hlimits.h header file. Because of this restriction, it is very important to call Hendaccess immediately following the last operation on a data element.
> |  | When developing new interfaces, a common mistake is to omit calling Hendaccess for all of the elements accessed. When this happens, Hclose will return `FAIL`, and a dump of the error stack will report the number of active access identifiers. Refer to the Reference Manual page on HEprint.
> |  | This is a difficult problem to debug because the low levels of the HDF library cannot determine who and where an access identifier was originated. As a result, there is no automated method of determining which access identifiers have yet to be released.

> ##

> [H Advance Interface][Top]

> Hendbitaccess

> intn Hendbitaccess(int32 h_id, intn flushbit)

> | h_id | IN: | Identifier of the bit-access element to be disposed of
> | flushbit | IN: | Specifies how the leftover bits are to be flushed

> | Purpose | Disposes of the specified bit-access file element.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | If called after a bit-write operation, Hendbitaccess flushes all buffered bits to the dataset, then calls Hendaccess.
> |  | "Leftover bits" are bits that have been buffered, but are fewer than the number of bits defined by BITNUM, which is usually set to 8.
> |  | Valid codes for flushbit are: 0 for flush with zeros, 1 for flush with ones and -1 for dispose of leftover bits

> ##

> [H Advance Interface][Top]

> Hexist

> intn Hexist(int32 h_id, uint16 search_tag, uint16 search_ref)

> | h_id | IN: | Access identifier returned by Hstartread, Hstartwrite, or Hnextread
> | search_tag | IN: | Tag of the object to be searched for
> | search_ref | IN: | Reference number of the object to be searched for

> | Purpose | Locates an object in an HDF file.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | Simple interface to Hfind that determines if a given tag/reference number pair exists in a file. Wildcards apply.
> |  | Hfind performs all validity checking; this is just a very simple wrapper around it.

> ##

> [H Advance Interface][Top]

> Hfidinquire

> intn Hfidinquire(int32 file_id, char *filename, intn *access, intn *attach)

> | file_id | IN: | File identifier returned by Hopen
> | filename | OUT: | Complete path and filename for the file
> | access | OUT: | Access mode file is opened with
> | attach | OUT: | Number of access identifiers attached to the file

> | Purpose | Returns file information through a reference of its file identifier.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | Gets the complete path name, access mode, and number of access identifiers associated with a file. The filename parameter is a pointer to a character pointer which will be modified when the function returns. Upon completion, filename is set to point to the file name in internal storage. All output parameters must be non-null pointers.

> ##

> [H Advance Interface][Top]

> Hfind

> intn Hfind(int32 file_id, uint16 search_tag, uint16 search_ref, uint16 *find_tag, uint16 *find_ref, int32 *find_offset, int32 *find_length, intn direction)

> | file_id | IN: | File identifier returned by Hopen
> | search_tag | IN: | The tag to search for or DFTAG_WILDCARD
> | search_ref | IN: | Reference number to search for or DFREF_WILDCARD
> | find_tag | IN/OUT: | If (*find_tag == 0) and (*find_ref == 0) then start the search from either the beginning or the end of the file. If the object is found, the tags of the object will be returned here.
> | find_ref | IN/OUT: | If (*find_tag == 0) and (*find_ref == 0) then start the search from either the beginning or the end of the file. If the object is found, the reference numbers of the object will be returned here.
> | find_offset | OUT: | Offset of the data element found
> | find_length | OUT: | Length of the data element found
> | direction | IN: | Direction to search in DF_FORWARD searches forward from the current location, and DF_BACKWARD searches backward from the current location

> | Purpose | Locates the next object to be searched for in an HDF file.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | Hfind searches for the next data element that matches the specified tag and reference number. Wildcards apply. If direction is DF_FORWARD, searching is forward from the current position in the file, otherwise DF_BACKWARD specifies backward searches from the current position in the file.
> |  | If find_tag and find_ref are both set to 0, this indicates the beginning of a search, and the search will start from the beginning of the file if the direction is DF_FORWARD and from the end of the file if the direction is DF_BACKWARD.

> ##

> [H Advance Interface][Top]

> Hgetbit

> intn Hgetbit(int32 h_id)

> | h_id | IN: | Bit-access element identifier

> | Purpose | Reads one bit from the specified bit-access element.
> | Return value | Returns the bit read (or 0 or 1) if successful and `FAIL` (or -1) otherwise.
> | Description | This function is a wrapper for Hbitread.

> ##

> [H Advance Interface][Top]

> Hgetelement

> int32 Hgetelement(int32 file_id, uint16 tag, uint16 ref, uint8 *data)

> | file_id | IN: | File identifier returned by Hopen
> | tag | IN: | Tag of the data element to be read
> | ref | IN: | Reference number of the data element to be read
> | data | OUT: | Buffer the element will be read into

> | Purpose | Reads the data element for the specified tag and reference number and writes it to the data buffer.
> | Return value | Returns the number of bytes read if successful and `FAIL` (or -1) otherwise.
> | Description | It is assumed that the space allocated for the buffer is large enough to hold the data.

> ##

> [H Advance Interface][Top]

> Hinquire

> intn Hinquire(int32 h_id, int32 *file_id, uint16 *tag, uint16 *ref, int32 *length, int32 *offset, int32 *position, int16 *access, int16 *special)

> | h_id | IN: | Access identifier returned by Hstartread, Hstartwrite, or Hnextread
> | file_id | OUT: | File identifier returned by Hopen
> | tag | OUT: | Tag of the element pointed to
> | ref | OUT: | Reference number of the element pointed to
> | length | OUT: | Length of the element pointed to
> | offset | OUT: | Offset of the element in the file
> | position | OUT: | Current position within the data element
> | access | OUT: | The access type for this data element
> | special | OUT: | Special code

> | Purpose | Returns access information about a data element.
> | Return value | Returns `SUCCEED` (or 0) if the access identifier points to a valid data element and `FAIL` (or -1) otherwise.
> | Description | If h_id is a valid access identifier the access type (read or write) is set regardless of whether or not the return value is `FAIL` (or -1). If h_id is invalid, the function returns `FAIL` (or -1) and the access type is set to zero. To avoid excess information, pass NULL for any unnecessary pointer.

> ##

> [H Advance Interface][Top]

> Hlength

> int32 Hlength(int32 file_id, uint16 tag, uint16 ref)

> | file_id | IN: | File identifier returned by Hopen
> | tag | IN: | Tag of the data element
> | ref | IN: | Reference number of the data element

> | Purpose | Returns the length of a data object specified by the tag and reference number.
> | Return value | Returns the length of data element if found and `FAIL` (or -1) otherwise.
> | Description | Hlength calls Hstartread, HQuerylength, and Hendaccess to determine the length of a data element. Hlength uses Hstartread to obtain an access identifier for the specified data object.
> |  | Hlength will return the correct data length for linked-block elements, however it is important to remember that the data in linked-block elements is not stored contiguously.

> ##

> [H Advance Interface][Top]

> Hnewref

> uint16 Hnewref(int32 file_id)

> | file_id | IN: | File identifier returned by Hopen

> | Purpose | Returns a reference number that can be used with any tag to produce a unique tag /reference number pair.
> | Return value | Returns the reference number if successful and 0 otherwise.
> | Description | Successive calls to Hnewref will generate reference number values that increase by one each time until the highest possible reference number has been returned. At this point, additional calls to Hnewref will return an increasing sequence of unused reference number values starting from 1.

> ##

> [H Advance Interface][Top]

> Hnextread

> intn Hnextread(int32 h_id, uint16 tag, uint16 ref, int origin)

> | h_id | IN: | Access identifier returned by Hstartread or previous Hnextread
> | tag | IN: | Tag to search for
> | ref | IN: | Reference number to search for
> | origin | IN: | Position to begin search: DF_START or DF_CURRENT

> | Purpose | Searches for the next data descriptor that matches the specified tag and reference number.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | Wildcards apply. If origin is DF_START, the search will start at the beginning of the data descriptor list. If origin is DF_CURRENT, the search will begin at the current position. Searching backwards from the end of a data descriptor list is not yet implemented.
> |  | If the search is successful, the access identifier reflects the new data element, otherwise it is not modified.

> ##

> [H Advance Interface][Top]

> Hnumber/hnumber

> int32 Hnumber(int32 file_id, uint16 tag)

> | file_id | IN: | File identifier returned by Hopen
> | tag | IN: | Tag to be counted

> | Purpose | Returns the number of instances of a tag in a file.
> | Return value | Returns the number of instances of a tag in a file if successful, and `FAIL` (or -1) otherwise.
> | Description | Hnumber determines how many objects with the specified tag are in a file. To determine the total number of objects in a file, set the tag argument to DFTAG_WILDCARD. Note that a return value of zero is not a fail condition.

> | FORTRAN | integer function hnumber(file_id, tag)
> |  | integer file_id, tag

> ##

> [H Advance Interface][Top]

> Hoffset

> int32 Hoffset(int32 file_id, uint16 tag, uint16 ref)

> | file_id | IN: | File identifier returned by Hopen
> | tag | IN: | Tag of the data element
> | ref | IN: | Reference number of the data element

> | Purpose | Returns the offset of a data element in the file.
> | Return value | Returns the offset of the data element if the data element exists and `FAIL` (or -1) otherwise.
> | Description | Hoffset calls Hstartread, HQueryoffset, and Hendaccess to determine the length of a data element. Hoffset uses Hstartread to obtain an access identifier for the specified data object.
> |  | Hoffset will return the correct offset for a linked-block element, however it is important to remember that the data in linked-block elements is not stored contiguously. The offset returned by Hoffset only reflects the position of the first data block.
> |  | Hoffset should not be used to determine the offset of an external element. In this case, Hoffset returns zero, an invalid offset for HDF files.

> ##

> [H Advance Interface][Top]

> Hputbit

> intn Hputbit(int32 h_id, intn bit)

> | h_id | IN: | Bit-access element identifier
> | bit | IN: | Bit to be written

> | Purpose | Writes one bit to the specified bit-access element.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | This function is a wrapper for Hbitwrite.

> ##

> [H Advance Interface][Top]

> Hputelement

> int32 Hputelement(int32 file_id, uint16 tag, uint16 ref, uint8 *data, int32 length)

> | file_id | IN: | File identifier returned by Hopen
> | tag | IN: | Tag of the data element to add or replace
> | ref | IN: | Reference number of the data element to add or replace
> | data | IN: | Pointer to data buffer
> | length | IN: | Length of data to write

> | Purpose | Writes a data element or replaces an existing data element in a HDF file.
> | Return value | Returns the number of bytes written if successful and `FAIL` (or -1) otherwise.

> ##

> [H Advance Interface][Top]

> Hread

> int32 Hread(int32 h_id, int32 length, VOIDP data)

> | h_id | IN: | Access identifier returned by Hstartread, Hstartwrite, or Hnextread
> | length | IN: | Length of segment to be read
> | data | OUT: | Pointer to the data array to be read

> | Purpose | Reads the next segment in a data element.
> | Return value | Returns the length of segment actually read if successful and `FAIL` (or -1) otherwise.
> | Description | Hread begins reading at the current file position, reads the specified number of bytes, and increments the current file position by one. Calling Hread with the length = 0 reads the entire data element. To reposition an access identifier before writing data, use Hseek.
> |  | If length is longer than the data element, the read operation is terminated at the end of the data element, and the number of read bytes is returned. Although only one access identifier is allowed per data element, it is possible to interlace reads from multiple data elements in the same file. It is assumed that data is large enough to hold the specified data length.

> ##

> [H Advance Interface][Top]

> Hseek

> intn Hseek(int32 h_id, int32 offset, intn origin)

> | h_id | IN: | Access identifier returned by Hstartread, Hstartwrite, or Hnextread
> | offset | IN: | Number of bytes to seek to from the origin
> | origin | IN: | Position of the offset origin

> | Purpose | Sets the access pointer to an offset within a data element.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.

> Description

> Sets the seek position for the next Hread or Hwrite operation by moving an access identifier to the specified position in a data element. The origin and the offset arguments determine the byte location for the access identifier. If origin is set to DF_START, the offset is added to the beginning of the data element. If origin is set to DF_CURRENT, the offset is added to the current position of the access identifier.

> |  | Valid values for origin are: DF_START (the beginning of the file) or DF_CURRENT (the current position in the file).
> |  | This routine fails if the access identifier if h_id is invalid or if the seek position is outside the range of the data element.

> ##

> [H Advance Interface][Top]

> Hsetlength

> int32 Hsetlength(int32 file_id, int32 length)

> | file_id | IN: | File identifier returned by Hopen
> | length | IN: | Length of the new element

> | Purpose | Specifies the length of a new HDF element.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | This function can only be used when called after Hstartaccess on a new data element and before any data is written to that element.

> ##

> [H Advance Interface][Top]

> Hshutdown

> int32 Hshutdown( )

> | Purpose | Deallocates buffers previously allocated in other H routines.
> | Return value | Returns `SUCCEED` (or 0) if successful and `FAIL` (or -1) otherwise.
> | Description | Should only be called by the function HDFend.

> ##

> [H Advance Interface][Top]

> Htagnewref

> int32 Htagnewref(int32 file_id, uint16 tag)

> | file_id | IN: | Access identifier returned by Hstartread or Hnextread
> | tag | IN: | Tag to be identified with the returned reference number

> | Purpose | Returns a reference number that is unique for the specified file that will correspond to the specified tag. Creates a new tag/reference number pair.
> | Return value | Returns the reference number if successful and 0 otherwise.
> | Description | Successive calls to Hnewref will generate a increasing sequence of reference number values until the highest possible reference number value has been returned. It will then return unused reference number values starting from 1 in increasing order.

> ##

> [H Advance Interface][Top]

> Htrunc

> int32 Htrunc(int32 h_id, int32 trunc_len)

> | h_id | IN: | Access identifier returned by Hstartread or Hnextread
> | trunc_len | IN: | Length to truncate element

> | Purpose | Truncates the data object specified by the h_id to the length trunc_len.
> | Return value | Returns the length of a data element if found and `FAIL` (or -1) otherwise.
> | Description | Htrunc does not handle special elements.

> ##

> [H Advance Interface][Top]

> Hwrite

> int32 Hwrite(int32 h_id, int32 length, VOIDP data)

> | h_id | IN: | Access identifier returned by Hstartwrite
> | len | IN: | Length of segment to be written
> | data | IN: | Pointer to the data to be written

> | Purpose | Writes the next data segment to a specified data element.
> | Return value | Returns the length of the segment actually written if successful and `FAIL` (or -1) otherwise.
> | Description | Hwrite begins writing at the current position of the access identifier, writes the specified number of bytes, then moves the access identifier to the position immediately following the last accessed byte. Calling Hwrite with length = 0 results in an error condition. To reposition an access identifier before writing data, use Hseek.
> |  | If the space allocated in the data element is smaller than the length of data, the data is truncated to the length of the data element. Although only one access identifier is allowed per data element, it is possible to interlace writes to more than one data element in a file.

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