Page tree









Encodes a data space object description into a binary buffer


H5S_ENCODE2 ( obj_id, buf, nalloc, fapl_id )


herr_t H5Sencode2 ( hid_t obj_id,  void *buf, size_t *nalloc,  hid_t fapl_id )

hid_t obj_idIN: Identifier of the object to be encoded
void *buf    

IN/OUT: Buffer for the object to be encoded into

If the provided buffer is NULL, only the size of buffer needed is returned through nalloc.

size_t *nallocIN: The size of the allocated buffer
OUT: The size of the buffer needed
hid_t fapl_idIN: File access property list


Given the data space identifier obj_id, H5S_ENCODE2 converts a data space description into binary form in a buffer. Using this binary form in the buffer, a data space object can be reconstructed with H5S_DECODE to return a new object handle (hid_t) for this data space.

A preliminary H5S_ENCODE2 call can be made to determine the size of the buffer needed. This value is returned in nalloc. That value can then be assigned to nalloc for a second H5S_ENCODE2 call, which will retrieve the actual encoded object.

If the library determines that nalloc is not big enough for the object, it simply returns the size of the buffer needed through nalloc without encoding the provided buffer.

The file access property list fapl_id is used to control the encoding via the libver_bounds property (see H5P_SET_LIBVER_BOUNDS). If the libver_bounds property is missing, H5S_ENCODE2 proceeds as if the libver_bounds property were set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST). (Functionally, H5S_ENCODE1 is identical to H5S_ENCODE2 with libver_bounds set to (H5F_LIBVER_EARLIEST, H5F_LIBVER_LATEST).)

The types of data space that are addressed in this function are null, scalar, and simple space. For a simple data space, the information on the selection, for example, hyperslab selection, is also encoded and decoded. A complex data space has not been implemented in the library.


This function was introduced in HDF5-1.12 as part of the H5Sencode format change to enable 64-bit selection encodings and a dataspace selection that is tied to a file. See the New Features in HDF5 Release 1.12 as well as the H5Sencode / H5Sdecode Format Change RFC.


Returns a non-negative value if successful; otherwise returns a negative value.


Coming Soon!

1.12.0Function introduced in this release

--- Last Modified: September 05, 2019 | 08:40 AM