From cf629d9e6c89eadd77ce98a527ac43b2fc4fcdc4 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Tue, 7 Oct 2003 14:56:17 -0500 Subject: [svn-r7567] Purpose: Alphabetic sort of RM function entries Additional and modified HTML coding to accomodate HTMLdoc and automated PDF generation Description: Solution: Platforms tested: Misc. update: --- doc/html/RM_H5D.html | 815 ++++++++++++++++++++------------------- doc/html/RM_H5E.html | 260 +++++++------ doc/html/RM_H5F.html | 413 ++++++++++---------- doc/html/RM_H5Front.html | 39 +- doc/html/RM_H5S.html | 976 ++++++++++++++++++++++++----------------------- doc/html/RM_H5Z.html | 90 +++-- 6 files changed, 1348 insertions(+), 1245 deletions(-) diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html index 773ba76..17505db 100644 --- a/doc/html/RM_H5D.html +++ b/doc/html/RM_H5D.html @@ -25,6 +25,7 @@ HDF5/H5D API Specification +

@@ -60,8 +61,7 @@ And in this document, the -

- +

H5D: Datasets Interface

@@ -116,50 +116,56 @@ and set and retrieve their constant or persistent properties.

H5Dclose
H5Dcreate
H5Dextend
H5Dfill
H5Dget_create_plist -
H5Dget_offset +
H5Dget_offset +

H5Dget_space
H5Dget_space_status
H5Dget_storage_size
H5Dget_type
H5Diterate
H5Dopen +

H5Dread
H5Dvlen_get_buf_size
H5Dvlen_reclaim
H5Dwrite +

Name: H5Dclose +
Signature: +: herr_t H5Dclose(hid_t dataset_id + ) +
Purpose: +: Closes the specified dataset. +
Description: +: H5Dclose ends access to a dataset specified by + dataset_id and releases resources used by it. + Further use of the dataset identifier is illegal in calls to + the dataset API. +
Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset to close access to. +
+
Returns: +: Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +: + +

+ +

Name: H5Dcreate @@ -245,7 +285,7 @@ facilitate moving easily between them. of specifying when fill values will be written to a dataset. For further information on these topics, see the document - Fill Value and Dataset Storage Allocation Issues in HDF5 + Fill Value and Dataset Storage Allocation Issues in HDF5 and the descriptions of the following HDF5 functions in this HDF5 Reference Manual: @@ -294,33 +334,154 @@ facilitate moving easily between them. --> + + +
+
+
Name: H5Dextend +
Signature: +
herr_t H5Dextend(hid_t dataset_id, + const hsize_t * size + ) +
Purpose: +
Extends a dataset with unlimited dimension. +
Description: +
H5Dextend verifies that the dataset is at least of size + size. + The dimensionality of size is the same as that of + the dataspace of the dataset being changed. + This function cannot be applied to a dataset with fixed dimensions. +
+ Space on disk is immediately allocated for the new dataset extent + if the dataset's space allocation time is set to + H5D_ALLOC_TIME_EARLY. + Fill values will be written to the dataset if the dataset's fill time + is set to H5D_FILL_TIME_IFSET or + H5D_FILL_TIME_ALLOC. + (Also see + H5Pset_fill_time + and + H5Pset_alloc_time.) + +
Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset. +
const hsize_t * size +
IN: Array containing the new magnitude of each dimension. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
+ +
-
Name: H5Dopen +
Name: H5Dfill
Signature: -
hid_t H5Dopen(hid_t loc_id, - const char *name +
herr_t H5Dfill( + const void *fill, + hid_t fill_type_id, + void *buf, + hid_t buf_type_id, + hid_t space_id )
Purpose: -
Opens an existing dataset. +
Fills dataspace elements with a fill value in a memory buffer.
Description: -
H5Dopen opens an existing dataset for access in the file - or group specified in loc_id. name is - a dataset name and is used to identify the dataset in the file. +
H5Dfill explicitly fills + the dataspace selection in memory, space_id, + with the fill value specified in fill. + If fill is NULL, + a fill value of 0 (zero) is used. +
+ fill_type_id specifies the datatype + of the fill value.
+ buf specifies the buffer in which + the dataspace elements will be written.
+ buf_type_id specifies the datatype of + those data elements. +
+ Note that if the fill value datatype differs + from the memory buffer datatype, the fill value + will be converted to the memory buffer datatype + before filling the selection. +
Note: +
Applications sometimes write data only to portions of + an allocated dataset. It is often useful in such cases + to fill the unused space with a known + fill value. + See H5Pset_fill_value + for further discussion. + Other related functions include + H5Pget_fill_value, + H5Pfill_value_defined, + H5Pset_fill_time, + H5Pget_fill_time, + and + H5Dcreate.
Parameters:
-
hid_t loc_id -
IN: Identifier of the file or group - within which the dataset to be accessed will be found. -
const char * name -
IN: The name of the dataset to access. +
const void *fill +
IN: Pointer to the fill value to be used. +
hid_t fill_type_id +
IN: Fill value datatype identifier. +
void *buf +
IN/OUT: Pointer to the memory buffer containing the + selection to be filled. +
hid_t buf_type_id +
IN: Datatype of dataspace elements to be filled. +
hid_t space_id +
IN: Dataspace describing memory buffer and + containing the selection to be filled.

Returns: -
Returns a dataset identifier if successful; +
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
+ +
+ + + +
+
+
Name: H5Dget_create_plist +
Signature: +
hid_t H5Dget_create_plist(hid_t dataset_id + ) +
Purpose: +
Returns an identifier for a copy of the + dataset creation property list for a dataset. +
Description: +
H5Dget_create_plist returns an identifier for a + copy of the dataset creation property list for a dataset. + The creation property list identifier should be released with + the H5Pclose function. +
Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset to query. +
+
Returns: +
Returns a dataset creation property list identifier if successful; + otherwise returns a negative value. +
Non-C API(s): +

+ + +
+
+
Name: H5Dget_offset +
Signature: +
haddr_t H5Dget_offset(hid_t dset_id) +
Purpose: +
Returns dataset address in file. +
Description: +
H5Dget_offset returns the address in the file + of the dataset dset_id. + That address is expressed as the offset in bytes from + the beginning of the file. +
Parameters: +
+
hid_t dset_id +
Dataset identifier. +
+
Returns: +
Returns the offset in bytes; + otherwise returns HADDR_UNDEF, a negative value. + +
+ +

Name: H5Dget_space @@ -359,7 +553,8 @@ facilitate moving easily between them. -->
- + +

Name: H5Dget_space_status @@ -411,34 +606,33 @@ facilitate moving easily between them. -->
- + +
-
Name: H5Dget_type +
Name: H5Dget_storage_size
Signature: -
hid_t H5Dget_type(hid_t dataset_id +
hsize_t H5Dget_storage_size(hid_t dataset_id )
Purpose: -
Returns an identifier for a copy of the datatype for a dataset. +
Returns the amount of storage required for a dataset.
Description: -
H5Dget_type returns an identifier for a copy of the - datatype for a dataset. - The datatype should be released with the H5Tclose function. -
- If a dataset has a named datatype, then an identifier to the - opened datatype is returned. - Otherwise, the returned datatype is read-only. - If atomization of the datatype fails, then the datatype is closed. +
H5Dget_storage_size returns the amount of storage + that is required for the specified dataset, dataset_id. + For chunked datasets, this is the number of allocated chunks times + the chunk size. + The return value may be zero if no data has been stored.
Parameters:

hid_t dataset_id
IN: Identifier of the dataset to query.

Returns: -
Returns a datatype identifier if successful; - otherwise returns a negative value. +
Returns the amount of storage space allocated for the dataset, + not counting meta data; + otherwise returns 0 (zero).
Non-C API(s): -

- + +
-
Name: H5Dget_create_plist +
Name: H5Dget_type
Signature: -
hid_t H5Dget_create_plist(hid_t dataset_id +
hid_t H5Dget_type(hid_t dataset_id )
Purpose: -
Returns an identifier for a copy of the - dataset creation property list for a dataset. +
Returns an identifier for a copy of the datatype for a dataset.
Description: -
H5Dget_create_plist returns an identifier for a - copy of the dataset creation property list for a dataset. - The creation property list identifier should be released with - the H5Pclose function. +
H5Dget_type returns an identifier for a copy of the + datatype for a dataset. + The datatype should be released with the H5Tclose function. +
+ If a dataset has a named datatype, then an identifier to the + opened datatype is returned. + Otherwise, the returned datatype is read-only. + If atomization of the datatype fails, then the datatype is closed.
Parameters:

hid_t dataset_id
IN: Identifier of the dataset to query.

Returns: -
Returns a dataset creation property list identifier if successful; +
Returns a datatype identifier if successful; otherwise returns a negative value.
Non-C API(s): -

- + +
-
Name: H5Dget_offset +
Name: H5Diterate
Signature: -
haddr_t H5Dget_offset(hid_t dset_id) +
herr_t H5Diterate( + void *buf, + hid_t type_id, + hid_t space_id, + H5D_operator_t operator, + void *operator_data + )
Purpose: -
Returns dataset address in file. +
Iterates over all selected elements in a dataspace.
Description: -
H5Dget_offset returns the address in the file - of the dataset dset_id. - That address is expressed as the offset in bytes from - the beginning of the file. +
H5Diterate iterates over all the elements selected + in a memory buffer. The callback function is called once for each + element selected in the dataspace. +
+ The selection in the dataspace is modified so that any elements + already iterated over are removed from the selection if the + iteration is interrupted (by the H5D_operator_t + function returning non-zero) before the iteration is complete; + the iteration may then be re-started by the user where it left off. +
Parameters:
-
hid_t dset_id -
Dataset identifier. +
void *buf +
IN/OUT: Pointer to the buffer in memory containing the + elements to iterate over. +
hid_t type_id +
IN: Datatype identifier for the elements stored in + buf. +
hid_t space_id +
IN: Dataspace identifier for buf. + Also contains the selection to iterate over. +
H5D_operator_t operator +
IN: Function pointer to the routine to be called + for each element in buf iterated over. +
void *operator_data +
IN/OUT: Pointer to any user-defined data associated + with the operation.

Returns: -
Returns the offset in bytes; - otherwise returns HADDR_UNDEF, a negative value. +
Returns the return value of the last operator if it was non-zero, + or zero if all elements have been processed. + Otherwise returns a negative value.
- + +
-
Name: H5Dget_storage_size -
Signature: -
hsize_t H5Dget_storage_size(hid_t dataset_id - ) -
Purpose: -
Returns the amount of storage required for a dataset. -
Description: -
H5Dget_storage_size returns the amount of storage - that is required for the specified dataset, dataset_id. - For chunked datasets, this is the number of allocated chunks times - the chunk size. - The return value may be zero if no data has been stored. -
Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset to query. -
-
Returns: -
Returns the amount of storage space allocated for the dataset, - not counting meta data; - otherwise returns 0 (zero). -
Non-C API(s): -
- -
- - -
-
-
Name: H5Dvlen_get_buf_size -
Signature: -
herr_t H5Dvlen_get_buf_size(hid_t dataset_id, - hid_t type_id, - hid_t space_id, - hsize_t *size - ) -
Purpose: -
Determines the number of bytes required to store VL data. -
Description: -
H5Dvlen_get_buf_size determines the number of bytes - required to store the VL data from the dataset, using the - space_id for the selection in the dataset on - disk and the type_id for the memory representation - of the VL data in memory. -
- *size is returned with the number of bytes - required to store the VL data in memory. -
Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset to query. -
hid_t type_id -
IN: Datatype identifier. -
hid_t space_id -
IN: Dataspace identifier. -
hsize_t *size -
OUT: The size in bytes of the memory buffer required to store the VL data. -
-
Returns: -
Returns non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
There is no direct FORTRAN couterpart for the C function - H5Dvlen_get_buf_size; - corresponding functionality is provided by the FORTRAN function - h5dvlen_get_max_len_f. -
- - -
- - -
-
-
Name: H5Dvlen_reclaim +
Name: H5Dopen
Signature: -
herr_t H5Dvlen_reclaim(hid_t type_id, - hid_t space_id, - hid_t plist_id, - void *buf +
hid_t H5Dopen(hid_t loc_id, + const char *name )
Purpose: -
Reclaims VL datatype memory buffers. +
Opens an existing dataset.
Description: -
H5Dvlen_reclaim reclaims memory buffers created to - store VL datatypes. -
- The type_id must be the datatype stored in the buffer. - The space_id describes the selection for the memory buffer - to free the VL datatypes within. - The plist_id is the dataset transfer property list which - was used for the I/O transfer to create the buffer. - And buf is the pointer to the buffer to be reclaimed. -
- The VL structures (hvl_t) in the user's buffer are - modified to zero out the VL information after the memory has been reclaimed. -
- If nested VL datatypes were used to create the buffer, - this routine frees them from the bottom up, releasing all - the memory without creating memory leaks. +
H5Dopen opens an existing dataset for access in the file + or group specified in loc_id. name is + a dataset name and is used to identify the dataset in the file.
Parameters:
-
hid_t type_id -
IN: Identifier of the datatype. -
hid_t space_id -
IN: Identifier of the dataspace. -
hid_t plist_id -
IN: Identifier of the property list used to create the buffer. -
void *buf -
IN: Pointer to the buffer to be reclaimed. +
hid_t loc_id +
IN: Identifier of the file or group + within which the dataset to be accessed will be found. +
const char * name +
IN: The name of the dataset to access.

Returns: -
Returns non-negative value if successful; +
Returns a dataset identifier if successful; otherwise returns a negative value. -
- + +

Name: H5Dread @@ -814,8 +939,113 @@ facilitate moving easily between them. -->
+ + +
+
+
Name: H5Dvlen_get_buf_size +
Signature: +
herr_t H5Dvlen_get_buf_size(hid_t dataset_id, + hid_t type_id, + hid_t space_id, + hsize_t *size + ) +
Purpose: +
Determines the number of bytes required to store VL data. +
Description: +
H5Dvlen_get_buf_size determines the number of bytes + required to store the VL data from the dataset, using the + space_id for the selection in the dataset on + disk and the type_id for the memory representation + of the VL data in memory. +
+ *size is returned with the number of bytes + required to store the VL data in memory. +
Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset to query. +
hid_t type_id +
IN: Datatype identifier. +
hid_t space_id +
IN: Dataspace identifier. +
hsize_t *size +
OUT: The size in bytes of the memory buffer required to store the VL data. +
+
Returns: +
Returns non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
There is no direct FORTRAN couterpart for the C function + H5Dvlen_get_buf_size; + corresponding functionality is provided by the FORTRAN function + h5dvlen_get_max_len_f. +
+ + +
+ + +
+
+
Name: H5Dvlen_reclaim +
Signature: +
herr_t H5Dvlen_reclaim(hid_t type_id, + hid_t space_id, + hid_t plist_id, + void *buf + ) +
Purpose: +
Reclaims VL datatype memory buffers. +
Description: +
H5Dvlen_reclaim reclaims memory buffers created to + store VL datatypes. +
+ The type_id must be the datatype stored in the buffer. + The space_id describes the selection for the memory buffer + to free the VL datatypes within. + The plist_id is the dataset transfer property list which + was used for the I/O transfer to create the buffer. + And buf is the pointer to the buffer to be reclaimed. +
+ The VL structures (hvl_t) in the user's buffer are + modified to zero out the VL information after the memory has been reclaimed. +
+ If nested VL datatypes were used to create the buffer, + this routine frees them from the bottom up, releasing all + the memory without creating memory leaks. +
Parameters: +
+
hid_t type_id +
IN: Identifier of the datatype. +
hid_t space_id +
IN: Identifier of the dataspace. +
hid_t plist_id +
IN: Identifier of the property list used to create the buffer. +
void *buf +
IN: Pointer to the buffer to be reclaimed. +
+
Returns: +
Returns non-negative value if successful; + otherwise returns a negative value. + +
+ +

Name: H5Dwrite @@ -967,6 +1197,12 @@ facilitate moving easily between them. H5Pset_fill_time and H5Pset_alloc_time.) +
+ If a dataset's storage layout is 'compact', care must be taken when + writing data to the dataset in parallel. A compact dataset's raw data + is cached in memory and may be flushed to the file from any of the + parallel processes, so parallel applications should always attempt to + write identical data to the dataset from all processes.
Parameters:
@@ -996,214 +1232,6 @@ facilitate moving easily between them. -->
-
-
-
Name: H5Dextend -
Signature: -
herr_t H5Dextend(hid_t dataset_id, - const hsize_t * size - ) -
Purpose: -
Extends a dataset with unlimited dimension. -
Description: -
H5Dextend verifies that the dataset is at least of size - size. - The dimensionality of size is the same as that of - the dataspace of the dataset being changed. - This function cannot be applied to a dataset with fixed dimensions. -
- Space on disk is immediately allocated for the new dataset extent - if the dataset's space allocation time is set to - H5D_ALLOC_TIME_EARLY. - Fill values will be written to the dataset if the dataset's fill time - is set to H5D_FILL_TIME_IFSET or - H5D_FILL_TIME_ALLOC. - (Also see - H5Pset_fill_time - and - H5Pset_alloc_time.) - -
Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset. -
const hsize_t * size -
IN: Array containing the new magnitude of each dimension. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- - -
-
-
Name: H5Dclose -
Signature: -
herr_t H5Dclose(hid_t dataset_id - ) -
Purpose: -
Closes the specified dataset. -
Description: -
H5Dclose ends access to a dataset specified by - dataset_id and releases resources used by it. - Further use of the dataset identifier is illegal in calls to - the dataset API. -
Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset to close access to. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- - -
-
-
Name: H5Diterate -
Signature: -
herr_t H5Diterate( - void *buf, - hid_t type_id, - hid_t space_id, - H5D_operator_t operator, - void *operator_data - ) -
Purpose: -
Iterates over all selected elements in a dataspace. -
Description: -
H5Diterate iterates over all the elements selected - in a memory buffer. The callback function is called once for each - element selected in the dataspace. -
- The selection in the dataspace is modified so that any elements - already iterated over are removed from the selection if the - iteration is interrupted (by the H5D_operator_t - function returning non-zero) before the iteration is complete; - the iteration may then be re-started by the user where it left off. - -
Parameters: -
-
void *buf -
IN/OUT: Pointer to the buffer in memory containing the - elements to iterate over. -
hid_t type_id -
IN: Datatype identifier for the elements stored in - buf. -
hid_t space_id -
IN: Dataspace identifier for buf. - Also contains the selection to iterate over. -
H5D_operator_t operator -
IN: Function pointer to the routine to be called - for each element in buf iterated over. -
void *operator_data -
IN/OUT: Pointer to any user-defined data associated - with the operation. -
-
Returns: -
Returns the return value of the last operator if it was non-zero, - or zero if all elements have been processed. - Otherwise returns a negative value. - -
- - -
-
-
Name: H5Dfill -
Signature: -
herr_t H5Dfill( - const void *fill, - hid_t fill_type_id, - void *buf, - hid_t buf_type_id, - hid_t space_id - ) -
Purpose: -
Fills dataspace elements with a fill value in a memory buffer. -
Description: -
H5Dfill explicitly fills - the dataspace selection in memory, space_id, - with the fill value specified in fill. - If fill is NULL, - a fill value of 0 (zero) is used. -
- fill_type_id specifies the datatype - of the fill value.
- buf specifies the buffer in which - the dataspace elements will be written.
- buf_type_id specifies the datatype of - those data elements. -
- Note that if the fill value datatype differs - from the memory buffer datatype, the fill value - will be converted to the memory buffer datatype - before filling the selection. -
Note: -
Applications sometimes write data only to portions of - an allocated dataset. It is often useful in such cases - to fill the unused space with a known - fill value. - See H5Pset_fill_value - for further discussion. - Other related functions include - H5Pget_fill_value, - H5Pfill_value_defined, - H5Pset_fill_time, - H5Pget_fill_time, - and - H5Dcreate. -
Parameters: -
-
const void *fill -
IN: Pointer to the fill value to be used. -
hid_t fill_type_id -
IN: Fill value datatype identifier. -
void *buf -
IN/OUT: Pointer to the memory buffer containing the - selection to be filled. -
hid_t buf_type_id -
IN: Datatype of dataspace elements to be filled. -
hid_t space_id -
IN: Dataspace describing memory buffer and - containing the selection to be filled. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- -

@@ -1237,14 +1265,15 @@ And in this document, the

HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -

- -Last modified: 25 June 2003 +

diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html index f102ba4..e5fa126 100644 --- a/doc/html/RM_H5E.html +++ b/doc/html/RM_H5E.html @@ -25,6 +25,7 @@ HDF5/H5E API Specification +

@@ -60,8 +61,7 @@ And in this document, the -

- +

H5E: Error Interface

@@ -100,43 +100,49 @@ These functions provide error handling capabilities in the HDF5 environment.

H5Eclear
H5Eget_auto -
H5Eget_major +
H5Eget_major +

H5Eget_minor
H5Eprint
H5Epush +

H5Eset_auto
H5Ewalk
H5Ewalk_cb +

+
The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task -as the corresponding C function. The links below go to the C function +as the corresponding C function. The links below (electronic versions only) go to the C function descriptions, which serve as general descriptions for both. A button, under Non-C API(s) at the end of the C function description, opens an external browser window displaying the FORTRAN90-specific information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them. - +

@@ -185,42 +191,33 @@ package maintains a single error stack. The error stack is statically allocated to reduce the complexity of handling errors within the H5E package. - + + +

-
Name: H5Eset_auto +
Name: H5Eclear
Signature: -
herr_t H5Eset_auto(H5E_auto_t func, - void *client_data - ) +
herr_t H5Eclear(void)
Purpose: -
Turns automatic error printing on or off. +
Clears the error stack for the current thread.
Description: -
H5Eset_auto turns on or off automatic printing of - errors. When turned on (non-null func pointer), - any API function which returns an error indication will - first call func, passing it client_data - as an argument. +
H5Eclear clears the error stack for the current thread.
- When the library is first initialized the auto printing function - is set to H5Eprint (cast appropriately) and - client_data is the standard error stream pointer, - stderr. + The stack is also cleared whenever an API function is called, + with certain exceptions (for instance, H5Eprint).
- Automatic stack traversal is always in the - H5E_WALK_DOWNWARD direction. + H5Eclear can fail if there are problems initializing + the library.
Parameters:
-
H5E_auto_t func -
IN: Function to be called upon an error condition. -
void *client_data -
IN: Data passed to the error function. +
None

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Eget_auto @@ -266,31 +264,95 @@ errors within the H5E package. -->
+ + +
+
+
Name: H5Eget_major +
Signature: +
const char * H5Eget_major(H5E_major_t n) +
Purpose: +
Returns a character string describing an error specified by a + major error number. +
Description: +
Given a major error number, H5Eget_major returns a + constant character string that describes the error. +
Parameters: +
+
H5E_major_t n +
IN: Major error number. +
+
Returns: +
Returns a character string describing the error if successful. + Otherwise returns "Invalid major error number." +
Non-C API(s): +
+ +
+ + + +
+
+
Name: H5Eget_minor +
Signature: +
const char * H5Eget_minor(H5E_minor_t n) +
Purpose: +
Returns a character string describing an error specified by a + minor error number. +
Description: +
Given a minor error number, H5Eget_minor returns a + constant character string that describes the error. +
Parameters: +
+
H5E_minor_t n +
IN: Minor error number. +
+
Returns: +
Returns a character string describing the error if successful. + Otherwise returns "Invalid minor error number." +
Non-C API(s): +
+ +
+ +

-
Name: H5Eclear +
Name: H5Eprint
Signature: -
herr_t H5Eclear(void) +
herr_t H5Eprint(FILE * stream)
Purpose: -
Clears the error stack for the current thread. +
Prints the error stack in a default manner.
Description: -
H5Eclear clears the error stack for the current thread. -
- The stack is also cleared whenever an API function is called, - with certain exceptions (for instance, H5Eprint). +
H5Eprint prints the error stack on the specified + stream, stream. + Even if the error stack is empty, a one-line message will be printed: +
+ HDF5-DIAG: Error detected in thread 0.
- H5Eclear can fail if there are problems initializing - the library. + H5Eprint is a convenience function for + H5Ewalk with a function that prints error messages. + Users are encouraged to write their own more specific error handlers.
Parameters:
-
None +
FILE * stream +
IN: File pointer, or stderr if NULL.

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Epush @@ -355,34 +418,43 @@ errors within the H5E package. -->
- + +

-
Name: H5Eprint +
Name: H5Eset_auto
Signature: -
herr_t H5Eprint(FILE * stream) +
herr_t H5Eset_auto(H5E_auto_t func, + void *client_data + )
Purpose: -
Prints the error stack in a default manner. +
Turns automatic error printing on or off.
Description: -
H5Eprint prints the error stack on the specified - stream, stream. - Even if the error stack is empty, a one-line message will be printed: -
- HDF5-DIAG: Error detected in thread 0. +
H5Eset_auto turns on or off automatic printing of + errors. When turned on (non-null func pointer), + any API function which returns an error indication will + first call func, passing it client_data + as an argument.
- H5Eprint is a convenience function for - H5Ewalk with a function that prints error messages. - Users are encouraged to write their own more specific error handlers. + When the library is first initialized the auto printing function + is set to H5Eprint (cast appropriately) and + client_data is the standard error stream pointer, + stderr. +
+ Automatic stack traversal is always in the + H5E_WALK_DOWNWARD direction.
Parameters:
-
FILE * stream -
IN: File pointer, or stderr if NULL. +
H5E_auto_t func +
IN: Function to be called upon an error condition. +
void *client_data +
IN: Data passed to the error function.

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Ewalk @@ -469,7 +542,8 @@ errors within the H5E package. -->
- + +

Name: H5Ewalk_cb @@ -526,65 +600,6 @@ errors within the H5E package. -->
- -
-
-
Name: H5Eget_major -
Signature: -
const char * H5Eget_major(H5E_major_t n) -
Purpose: -
Returns a character string describing an error specified by a - major error number. -
Description: -
Given a major error number, H5Eget_major returns a - constant character string that describes the error. -
Parameters: -
-
H5E_major_t n -
IN: Major error number. -
-
Returns: -
Returns a character string describing the error if successful. - Otherwise returns "Invalid major error number." -
Non-C API(s): -
- -
- - -
-
-
Name: H5Eget_minor -
Signature: -
const char * H5Eget_minor(H5E_minor_t n) -
Purpose: -
Returns a character string describing an error specified by a - minor error number. -
Description: -
Given a minor error number, H5Eget_minor returns a - constant character string that describes the error. -
Parameters: -
-
H5E_minor_t n -
IN: Minor error number. -
-
Returns: -
Returns a character string describing the error if successful. - Otherwise returns "Invalid minor error number." -
Non-C API(s): -
- -
- -
@@ -618,14 +633,15 @@ And in this document, the

-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -
- -Last modified: 6 June 2003 +
diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html index a3fdcbb..c14c064 100644 --- a/doc/html/RM_H5F.html +++ b/doc/html/RM_H5F.html @@ -25,6 +25,7 @@ HDF5/H5F API Specification +
@@ -60,8 +61,7 @@ And in this document, the

- +

H5F: File Interface

@@ -106,49 +106,53 @@ documented below.

H5Fclose
H5Fcreate
H5Fflush
H5Fget_access_plist
H5Fget_create_plist - - +

H5Fget_obj_count
H5Fget_obj_ids
H5Fget_vfd_handle
H5Fis_hdf5
H5Fmount +

H5Fopen
H5Freopen
H5Funmount +

Name: H5Fopen +

Name: H5Fclose

Signature: -

hid_t H5Fopen(const char *name, - unsigned flags, - hid_t access_id +

herr_t H5Fclose(hid_t file_id )

Purpose: -

Opens an existing file. +

Terminates access to an HDF5 file.

Description: -

H5Fopen opens an existing file and is the primary - function for accessing existing HDF5 files. -

- The parameter access_id is a file access property - list identifier or H5P_DEFAULT if the - default I/O access parameters are to be used -

- The flags argument determines whether writing - to an existing file will be allowed. - The file is opened with read and write permission if - flags is set to H5F_ACC_RDWR. - All flags may be combined with the bit-wise OR operator (`|') - to change the behavior of the file open call. - More complex behaviors of file access are controlled - through the file-access property list. +

H5Fclose terminates access to an HDF5 file + by flushing all data to storage and terminating access + to the file through file_id.

- The return value is a file identifier for the open file; - this file identifier should be closed by calling - H5Fclose when it is no longer needed. + If this is the last file identifier open for the file + and no other access identifier is open (e.g., a dataset + identifier, group identifier, or shared datatype identifier), + the file will be fully closed and access will end.

- - Special case -- Multiple opens: + Delayed close:
- A file can often be opened with a new H5Fopen - call without closing an already-open identifier established - in a previous H5Fopen or H5Fcreate - call. Each such H5Fopen call will return a - unique identifier and the file can be accessed through any - of these identifiers as long as the identifier remains valid. - In such multiply-opened cases, all the open calls should - use the same flags argument. -

- In some cases, such as files on a local Unix file system, - the HDF5 library can detect that a file is multiply opened and - will maintain coherent access among the file identifiers. + Note the following deviation from the above-described behavior. + If H5Fclose is called for a file but one or more + objects within the file remain open, those objects will remain + accessible until they are individually closed. + Thus, if the dataset data_sample is open when + H5Fclose is called for the file containing it, + data_sample will remain open and accessible + (including writable) until it is explicitely closed. + The file will be automatically closed once all objects in the + file have been closed.

- But in many other cases, such as parallel file systems or - networked file systems, it is not always possible to detect - multiple opens of the same physical file. - In such cases, HDF5 will treat the file identifiers - as though they are accessing different files and - will be unable to maintain coherent access. - Errors are likely to result in these cases. - While unlikely, the HDF5 library may not be able to detect, - and thus report, such errors. + Be warned, hoever, that there are circumstances where it is + not possible to delay closing a file. + For example, an MPI-IO file close is a collective call; all of + the processes that opened the file must close it collectively. + The file cannot be closed at some time in the future by each + process in an independent fashion. + Another example is that an application using an AFS token-based + file access privilage may destroy its AFS token after + H5Fclose has returned successfully. + This would make any future access to the file, or any object + within it, illegal.

- It is generally recommended that applications avoid - multiple opens of the same file. - + In such situations, applications must close all open objects + in a file before calling H5Fclose. + It is generally recommended to do so in all cases.

Parameters:
-
const char *name -
IN: Name of the file to access. -
unsigned flags -
IN: File access flags. Allowable values are: -
-
H5F_ACC_RDWR -
Allow read and write access to file. -
H5F_ACC_RDONLY -
Allow read-only access to file. -
-
H5F_ACC_RDWR and H5F_ACC_RDONLY - are mutually exclusive; use exactly one. -
An additional flag, H5F_ACC_DEBUG, prints - debug information. This flag is used only by HDF5 library - developers; it is neither tested nor supported - for use in applications. -
-
hid_t access_id -
IN: Identifier for the file access properties list. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_id. - Use H5P_DEFAULT for default file access properties. +
hid_t file_id +
IN: Identifier of a file to terminate access to.

Returns: -

Returns a file identifier if successful; +

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

Non-C API(s): -

- + +

Name: H5Fcreate @@ -382,7 +354,8 @@ facilitate moving easily between them. -->

- + +

Name: H5Fflush @@ -438,37 +411,8 @@ facilitate moving easily between them. -->

- -

Name: H5Fis_hdf5 -
Signature: -: htri_t H5Fis_hdf5(const char *name - ) -
Purpose: -: Determines whether a file is in the HDF5 format. -
Description: -: H5Fis_hdf5 determines whether a file is in - the HDF5 format. -
Parameters: -
-
const char *name -
IN: File name to check format. -
-
Returns: -: When successful, returns a positive value, for TRUE, - or 0 (zero), for FALSE. - Otherwise returns a negative value. -
Non-C API(s): -: - -

- - + +

Name: H5Fget_access_plist @@ -504,7 +448,8 @@ facilitate moving easily between them. -->

- + +

Name: H5Fget_create_plist @@ -543,7 +488,8 @@ facilitate moving easily between them. -->

- + +

Name: H5Fget_obj_count @@ -622,7 +568,8 @@ facilitate moving easily between them. -->

- + +

Name: H5Fget_obj_ids @@ -674,7 +621,8 @@ facilitate moving easily between them. -->

- + +

Name: H5Fget_vfd_handle @@ -727,63 +675,30 @@ facilitate moving easily between them. -->

- + +

Name: H5Fclose +

Name: H5Fis_hdf5

Signature: -

herr_t H5Fclose(hid_t file_id +

htri_t H5Fis_hdf5(const char *name )

Purpose: -

Terminates access to an HDF5 file. +

Determines whether a file is in the HDF5 format.

Description: -

H5Fclose terminates access to an HDF5 file - by flushing all data to storage and terminating access - to the file through file_id. -

- If this is the last file identifier open for the file - and no other access identifier is open (e.g., a dataset - identifier, group identifier, or shared datatype identifier), - the file will be fully closed and access will end. -

- Delayed close: -
- Note the following deviation from the above-described behavior. - If H5Fclose is called for a file but one or more - objects within the file remain open, those objects will remain - accessible until they are individually closed. - Thus, if the dataset data_sample is open when - H5Fclose is called for the file containing it, - data_sample will remain open and accessible - (including writable) until it is explicitely closed. - The file will be automatically closed once all objects in the - file have been closed. -

- Be warned, hoever, that there are circumstances where it is - not possible to delay closing a file. - For example, an MPI-IO file close is a collective call; all of - the processes that opened the file must close it collectively. - The file cannot be closed at some time in the future by each - process in an independent fashion. - Another example is that an application using an AFS token-based - file access privilage may destroy its AFS token after - H5Fclose has returned successfully. - This would make any future access to the file, or any object - within it, illegal. -

- In such situations, applications must close all open objects - in a file before calling H5Fclose. - It is generally recommended to do so in all cases. +

H5Fis_hdf5 determines whether a file is in + the HDF5 format.

Parameters:
-
hid_t file_id -
IN: Identifier of a file to terminate access to. +
const char *name +
IN: File name to check format.

Returns: -

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

When successful, returns a positive value, for TRUE, + or 0 (zero), for FALSE. + Otherwise returns a negative value.

Non-C API(s): -

- + +

Name: H5Fmount @@ -837,44 +753,99 @@ facilitate moving easily between them. -->

- + +

Name: H5Funmount +

Name: H5Fopen

Signature: -

herr_t H5Funmount(hid_t loc_id, - const char *name +

hid_t H5Fopen(const char *name, + unsigned flags, + hid_t access_id )

Purpose: -

Unmounts a file. +

Opens an existing file.

Description: -

Given a mount point, H5Funmount - dissassociates the mount point's file - from the file mounted there. This function - does not close either file. -

- The mount point can be either the group in the - parent or the root group of the mounted file - (both groups have the same name). If the mount - point was opened before the mount then it is the - group in the parent; if it was opened after the - mount then it is the root group of the child. +

H5Fopen opens an existing file and is the primary + function for accessing existing HDF5 files.

- Note that loc_id is either a file or group identifier - and name is relative to loc_id. + The parameter access_id is a file access property + list identifier or H5P_DEFAULT if the + default I/O access parameters are to be used +

+ The flags argument determines whether writing + to an existing file will be allowed. + The file is opened with read and write permission if + flags is set to H5F_ACC_RDWR. + All flags may be combined with the bit-wise OR operator (`|') + to change the behavior of the file open call. + More complex behaviors of file access are controlled + through the file-access property list. +

+ The return value is a file identifier for the open file; + this file identifier should be closed by calling + H5Fclose when it is no longer needed. +

+ + Special case -- Multiple opens: +
+ A file can often be opened with a new H5Fopen + call without closing an already-open identifier established + in a previous H5Fopen or H5Fcreate + call. Each such H5Fopen call will return a + unique identifier and the file can be accessed through any + of these identifiers as long as the identifier remains valid. + In such multiply-opened cases, all the open calls should + use the same flags argument. +

+ In some cases, such as files on a local Unix file system, + the HDF5 library can detect that a file is multiply opened and + will maintain coherent access among the file identifiers. +

+ But in many other cases, such as parallel file systems or + networked file systems, it is not always possible to detect + multiple opens of the same physical file. + In such cases, HDF5 will treat the file identifiers + as though they are accessing different files and + will be unable to maintain coherent access. + Errors are likely to result in these cases. + While unlikely, the HDF5 library may not be able to detect, + and thus report, such errors. +

+ It is generally recommended that applications avoid + multiple opens of the same file. +

Parameters:
-
hid_t loc_id -
IN: File or group identifier for the location at which - the specified file is to be unmounted.
const char *name -
IN: Name of the mount point. +
IN: Name of the file to access. +
unsigned flags +
IN: File access flags. Allowable values are: +
+
H5F_ACC_RDWR +
Allow read and write access to file. +
H5F_ACC_RDONLY +
Allow read-only access to file. +
+
H5F_ACC_RDWR and H5F_ACC_RDONLY + are mutually exclusive; use exactly one. +
An additional flag, H5F_ACC_DEBUG, prints + debug information. This flag is used only by HDF5 library + developers; it is neither tested nor supported + for use in applications. +
+
hid_t access_id +
IN: Identifier for the file access properties list. + If parallel file access is desired, this is a collective + call according to the communicator stored in the + access_id. + Use H5P_DEFAULT for default file access properties.

Returns: -

Returns a non-negative value if successful; +

Returns a file identifier if successful; otherwise returns a negative value.

Non-C API(s): -

- + +

Name: H5Freopen @@ -926,6 +898,54 @@ facilitate moving easily between them. -->

+ + +

Name: H5Funmount +

Signature: +

herr_t H5Funmount(hid_t loc_id, + const char *name + ) +

Purpose: +

Unmounts a file. +

Description: +

Given a mount point, H5Funmount + dissassociates the mount point's file + from the file mounted there. This function + does not close either file. +

+ The mount point can be either the group in the + parent or the root group of the mounted file + (both groups have the same name). If the mount + point was opened before the mount then it is the + group in the parent; if it was opened after the + mount then it is the root group of the child. +

+ Note that loc_id is either a file or group identifier + and name is relative to loc_id. +

Parameters: +
+
hid_t loc_id +
IN: File or group identifier for the location at which + the specified file is to be unmounted. +
const char *name +
IN: Name of the mount point. +
+

Returns: +

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

Non-C API(s): +

+ +

+ + +

@@ -960,14 +980,15 @@ And in this document, the -

HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -

- -Last modified: 6 June 2003 +

diff --git a/doc/html/RM_H5Front.html b/doc/html/RM_H5Front.html index ea79e7d..480f01f 100644 --- a/doc/html/RM_H5Front.html +++ b/doc/html/RM_H5Front.html @@ -1,5 +1,7 @@ - +<head> +<a name="TopofRM"></a> +<title> HDF5 API Specification @@ -27,6 +29,9 @@ HDF5 API Specification + + +

@@ -129,7 +134,13 @@ See below for the FORTRAN90 and C++ APIs.

To top of Reference Manual. + + +

The Fortran90 and C++ APIs to HDF5

@@ -152,7 +163,8 @@ These APIs are described in the following documents. H5R, H5S, and H5T interfaces and are described on those pages.

In general, each Fortran subroutine performs exactly the same task - as the corresponding C function. The links at the top of each reference + as the corresponding C function. In the electronic version of this manual, + the links at the top of each reference manual section go to the C function descriptions, which serve as general descriptions for both the C and Fortran APIs. A button, under Non-C API(s) at the end of the C function description, @@ -217,23 +229,30 @@ And in this document, the

- +

HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -

- -Last modified: 9 April 2003 + +

-Copyright +

- + + diff --git a/doc/html/RM_H5S.html b/doc/html/RM_H5S.html index 0d73fd7..7bb5286 100644 --- a/doc/html/RM_H5S.html +++ b/doc/html/RM_H5S.html @@ -25,6 +25,7 @@ HDF5/H5S API Specification +

@@ -60,8 +61,7 @@ And in this document, the

- +

H5S: Dataspace Interface

@@ -159,20 +159,20 @@ elements of a dataset. -

Name: H5Sclose +
Signature: +: herr_t H5Sclose(hid_t space_id + ) +
Purpose: +: Releases and terminates access to a dataspace. +
Description: +: H5Sclose releases a dataspace. + Further access through the dataspace identifier is illegal. + Failure to release a dataspace with this call will + result in resource leaks. +
Parameters: +
+
hid_t space_id +
Identifier of dataspace to release. +
+
Returns: +: Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +: + +

+ + + +

Name: H5Scopy +
Signature: +: hid_t H5Scopy(hid_t space_id + ) +
Purpose: +: Creates an exact copy of a dataspace. +
Description: +: H5Scopy creates a new dataspace which is an exact + copy of the dataspace identified by space_id. + The dataspace identifier returned from this function should be + released with H5Sclose or resource leaks will occur. +
Parameters: +
+
hid_t space_id +
Identifier of dataspace to copy. +
+
Returns: +: Returns a dataspace identifier if successful; + otherwise returns a negative value. +
Non-C API(s): +: + +

+ +

Name: H5Screate @@ -272,7 +338,8 @@ of the HDF5 User's Guide.. -->

- + +

Name: H5Screate_simple @@ -326,30 +393,35 @@ of the HDF5 User's Guide.. -->

- + +

Name: H5Scopy +
Name: H5Sextent_copy
Signature: -: hid_t H5Scopy(hid_t space_id +; herr_t H5Sextent_copy(hid_t dest_space_id, + hid_t source_space_id )
Purpose: -: Creates an exact copy of a dataspace. +; Copies the extent of a dataspace.
Description: -: H5Scopy creates a new dataspace which is an exact - copy of the dataspace identified by space_id. - The dataspace identifier returned from this function should be - released with H5Sclose or resource leaks will occur. +; H5Sextent_copy copies the extent from + source_space_id to dest_space_id. + This action may change the type of the dataspace.
Parameters:
-
hid_t space_id -
Identifier of dataspace to copy. +
hid_t dest_space_id +
IN: The identifier for the dataspace to which + the extent is copied. +
hid_t source_space_id +
IN: The identifier for the dataspace from which + the extent is copied.
Returns: -: Returns a dataspace identifier if successful; +; Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Sselect_elements +

Name: H5Sget_select_bounds

Signature: -

herr_t H5Sselect_elements(hid_t space_id, - H5S_seloper_t op, - const size_t num_elements, - const hssize_t *coord[ ] +

herr_t H5Sget_select_bounds(hid_t space_id, + hssize_t *start, + hssize_t *end )

Purpose: -

Selects array elements to be included in the selection for a dataspace. +

Gets the bounding box containing the current selection.

Description: -

H5Sselect_elements selects array elements to be - included in the selection for the space_id - dataspace. The number of elements selected must be set with - the num_elements. The coord array - is a two-dimensional array of size dataspace rank - by num_elements (ie. a list of coordinates in - the array). The order of the element coordinates in the - coord array also specifies the order in which - the array elements are iterated through when I/O is performed. - Duplicate coordinate locations are not checked for. +

H5Sget_select_bounds retrieves the coordinates of + the bounding box containing the current selection and places + them into user-supplied buffers.

- The selection operator op determines how the - new selection is to be combined with the previously existing - selection for the dataspace. - The following operators are supported: -

- - -

- `H5S_SELECT_SET` -	- Replaces the existing selection with the parameters from this call. - Overlapping blocks are not supported with this operator. - Adds the new selection to the existing selection. -
- `H5S_SELECT_APPEND` -	- Adds the new selection following the last element of the existing selection. -
- `H5S_SELECT_PREPEND` -	- Adds the new selection preceding the first element of the existing selection. -

- - + The start and end buffers must be large + enough to hold the dataspace rank number of coordinates. +

+ The bounding box exactly contains the selection. + I.e., if a 2-dimensional element selection is currently + defined as containing the points (4,5), (6,8), and (10,7), + then the bounding box will be (4, 5), (10, 8). +

+ The bounding box calculation includes the current offset of the + selection within the dataspace extent. +

+ Calling this function on a none selection will + return FAIL.

Parameters:

hid_t space_id -
Identifier of the dataspace. -
H5S_seloper_t op -
operator specifying how the new selection is to be - combined with the existing selection for the dataspace. -
const size_t num_elements -
Number of elements to be selected. -
const hssize_t *coord[ ] -
A 2-dimensional array specifying the coordinates of the - elements being selected. +
IN: Identifier of dataspace to query. +
hssize_t *start +
OUT: Starting coordinates of the bounding box. +
hssize_t *end +
OUT: Ending coordinates of the bounding box, + i.e., the coordinates of the diagonally opposite corner.

Returns: -

Returns a non-negative value if successful; +

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

- + +

Name: H5Sselect_all +
Name: H5Sget_select_elem_npoints
Signature: -: herr_t H5Sselect_all(hid_t space_id) +; hssize_t H5Sget_select_elem_npoints(hid_t space_id + )
Purpose: -: Selects the entire dataspace. +; Gets the number of element points in the current selection.
Description: -: H5Sselect_all selects the entire extent - of the dataspace space_id. -
- More specifically, H5Sselect_all selects - the special 5S_SELECT_ALL region for the dataspace - space_id. H5S_SELECT_ALL selects the - entire dataspace for any dataspace it is applied to. +; H5Sget_select_elem_npoints returns + the number of element points in the current dataspace selection.
Parameters:

hid_t space_id -
IN: The identifier for the dataspace in which the - selection is being made. +
IN: Identifier of dataspace to query.
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. +; Returns the number of element points in the current dataspace selection if successful. + Otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Sselect_none +

Name: H5Sget_select_elem_pointlist

Signature: -

herr_t H5Sselect_none(hid_t space_id) +

herr_t H5Sget_select_elem_pointlist(hid_t space_id, + hsize_t startpoint, + hsize_t numpoints, + hsize_t *buf + )

Purpose: -

Resets the selection region to include no elements. +

Gets the list of element points currently selected.

Description: -

H5Sselect_none resets the selection region - for the dataspace space_id to include no elements. +

H5Sget_select_elem_pointlist returns the list of + element points in the current dataspace selection. Starting with + the startpoint-th point in the list of points, + numpoints points are put into the user's buffer. + If the user's buffer fills up before numpoints + points are inserted, the buffer will contain only as many + points as fit. +

+ The element point coordinates have the same dimensionality (rank) + as the dataspace they are located within. The list of element points + is formatted as follows: +
     + <coordinate>, followed by +
     + the next coordinate, +
     + etc. +
+ until all of the selected element points have been listed. +

+ The points are returned in the order they will be iterated through + when the selection is read/written from/to disk.

Parameters:

hid_t space_id -
IN: The identifier for the dataspace in which the - selection is being reset. +
IN: Dataspace identifier of selection to query. +
hsize_t startpoint +
IN: Element point to start with. +
hsize_t numpoints +
IN: Number of element points to get. +
hsize_t *buf +
OUT: List of element points selected.

Returns:

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

Non-C API(s): -

- + +

Name: H5Sselect_valid +

Name: H5Sget_select_hyper_blocklist

Signature: -

htri_t H5Sselect_valid(hid_t space_id) +

herr_t H5Sget_select_hyper_blocklist(hid_t space_id, + hsize_t startblock, + hsize_t numblocks, + hsize_t *buf + )

Purpose: -

Verifies that the selection is within the extent of the dataspace. +

Gets the list of hyperslab blocks currently selected.

Description: -

H5Sselect_valid verifies that the selection - for the dataspace space_id is within the extent - of the dataspace if the current offset for the dataspace is used. +

H5Sget_select_hyper_blocklist returns a list of + the hyperslab blocks currently selected. Starting with the + startblock-th block in the list of blocks, + numblocks blocks are put into the user's buffer. + If the user's buffer fills up before numblocks + blocks are inserted, the buffer will contain only as many + blocks as fit. +

+ The block coordinates have the same dimensionality (rank) + as the dataspace they are located within. The list of blocks + is formatted as follows: +
     + <"start" coordinate>, immediately followed by +
     + <"opposite" corner coordinate>, followed by +
     + the next "start" and "opposite" coordinates, +
     + etc. +
+ until all of the selected blocks have been listed. +

+ No guarantee is implied as the order in which blocks are listed.

Parameters:

hid_t space_id -
The identifier for the dataspace being queried. +
IN: Dataspace identifier of selection to query. +
hsize_t startblock +
IN: Hyperslab block to start with. +
hsize_t numblocks +
IN: Number of hyperslab blocks to get. +
hsize_t *buf +
OUT: List of hyperslab blocks selected.

Returns: -

Returns a positive value, for TRUE, - if the selection is contained within the extent - or 0 (zero), for FALSE, if it is not. - Returns a negative value on error conditions - such as the selection or extent not being defined. +

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

Non-C API(s): -

- + +

Name: H5Sget_simple_extent_npoints +
Name: H5Sget_select_hyper_nblocks
Signature: -: hssize_t H5Sget_simple_extent_npoints(hid_t space_id) +; hssize_t H5Sget_select_hyper_nblocks(hid_t space_id + )
Purpose: -: Determines the number of elements in a dataspace. +; Get number of hyperslab blocks.
Description: -: H5Sget_simple_extent_npoints determines the number of elements - in a dataspace. For example, a simple 3-dimensional dataspace - with dimensions 2, 3, and 4 would have 24 elements. +; H5Sget_select_hyper_nblocks returns the + number of hyperslab blocks in the current dataspace selection.
Parameters:

hid_t space_id -
ID of the dataspace object to query +
IN: Identifier of dataspace to query.
Returns: -: Returns the number of elements in the dataspace if successful; - otherwise returns 0. +; Returns the number of hyperslab blocks in + the current dataspace selection if successful. + Otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Sget_select_npoints @@ -588,27 +691,53 @@ of the HDF5 User's Guide.. -->

- + +

Name: H5Sget_simple_extent_ndims +

Name: H5Sget_select_type

Signature: -

int H5Sget_simple_extent_ndims(hid_t space_id) +

H5S_sel_type H5Sget_select_type(hid_t space_id)

Purpose: -

Determines the dimensionality of a dataspace. +

Determines the type of the dataspace selection.

Description: -

H5Sget_simple_extent_ndims determines the dimensionality (or rank) - of a dataspace. +

H5Sget_select_type retrieves the + type of selection currently defined for the dataspace + space_id.

Parameters:

hid_t space_id -
Identifier of the dataspace +
Dataspace identifier.

Returns: -

Returns the number of dimensions in the dataspace if successful; - otherwise returns a negative value. +

Returns the dataspace selection type, a value of + the enumerated datatype H5S_sel_type, + if successful. + Valid return values are as follows: + + + +

+ `H5S_SEL_NONE` +	+ No selection is defined. +
+ `H5S_SEL_POINTS` +	+ A sequence of points is selected. +
+ `H5S_SEL_HYPERSLABS` +	+ A hyperslab or compound hyperslab is selected. +
+ `H5S_SEL_ALL` +	+ The entire dataset is selected. +

+ + Otherwise returns a negative value.

Non-C API(s): -

- + +

Name: H5Sget_simple_extent_dims @@ -659,32 +789,28 @@ of the HDF5 User's Guide.. -->

- + +

Name: H5Sget_simple_extent_type +
Name: H5Sget_simple_extent_ndims
Signature: -: H5S_class_t H5Sget_simple_extent_type(hid_t space_id) +; int H5Sget_simple_extent_ndims(hid_t space_id)
Purpose: -: Determine the current class of a dataspace. +; Determines the dimensionality of a dataspace.
Description: -: H5Sget_simple_extent_type queries a dataspace to determine the - current class of a dataspace. -
- The function returns a class name, one of the following: - H5S_SCALAR, - H5S_SIMPLE, or - H5S_NONE. +; H5Sget_simple_extent_ndims determines the dimensionality (or rank) + of a dataspace.
Parameters:

hid_t space_id -
Dataspace identifier. +
Identifier of the dataspace
Returns: -: Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). +; Returns the number of dimensions in the dataspace if successful; + otherwise returns a negative value.
Non-C API(s): -

+ + +

Name: H5Sget_simple_extent_npoints +
Signature: +: hssize_t H5Sget_simple_extent_npoints(hid_t space_id) +
Purpose: +: Determines the number of elements in a dataspace. +
Description: +: H5Sget_simple_extent_npoints determines the number of elements + in a dataspace. For example, a simple 3-dimensional dataspace + with dimensions 2, 3, and 4 would have 24 elements. +
Parameters: +
+
hid_t space_id +
ID of the dataspace object to query +
+
Returns: +: Returns the number of elements in the dataspace if successful; + otherwise returns 0. +
Non-C API(s): +: + +

+ +

Name: H5Sset_extent_simple +

Name: H5Sget_simple_extent_type

Signature: -

herr_t H5Sset_extent_simple(hid_t space_id, - int rank, - const hsize_t *current_size, - const hsize_t *maximum_size - ) +

H5S_class_t H5Sget_simple_extent_type(hid_t space_id)

Purpose: -

Sets or resets the size of an existing dataspace. +

Determine the current class of a dataspace.

Description: -

H5Sset_extent_simple sets or resets the size of - an existing dataspace. -

- rank is the dimensionality, or number of - dimensions, of the dataspace. -

- current_size is an array of size rank - which contains the new size of each dimension in the dataspace. - maximum_size is an array of size rank - which contains the maximum size of each dimension in the - dataspace. +

H5Sget_simple_extent_type queries a dataspace to determine the + current class of a dataspace.

- Any previous extent is removed from the dataspace, the dataspace - type is set to H5S_SIMPLE, and the extent is set as - specified. + The function returns a class name, one of the following: + H5S_SCALAR, + H5S_SIMPLE, or + H5S_NONE.

Parameters:

hid_t space_id
Dataspace identifier. -
int rank -
Rank, or dimensionality, of the dataspace. -
const hsize_t *current_size -
Array containing current size of dataspace. -
const hsize_t *maximum_size -
Array containing maximum size of dataspace.

Returns: -

Returns a dataspace identifier if successful; - otherwise returns a negative value. +

Returns a dataspace class name if successful; + otherwise H5S_NO_CLASS (-1).

Non-C API(s): -

- + +

Name: H5Sis_simple @@ -773,7 +913,8 @@ of the HDF5 User's Guide.. -->

- + +

Name: H5Soffset_simple @@ -813,97 +954,114 @@ of the HDF5 User's Guide.. -->

- - +

Name: H5Sextent_class +
Name: H5Sselect_all
Signature: -: H5S_class_t H5Sextent_class(hid_t space_id) +; herr_t H5Sselect_all(hid_t space_id)
Purpose: -: Determine the current class of a dataspace. +; Selects the entire dataspace.
Description: -: H5Sextent_class queries a dataspace to determine the - current class of a dataspace. -
- The function returns a class name, one of the following: - H5S_SCALAR, - H5S_SIMPLE. +; H5Sselect_all selects the entire extent + of the dataspace space_id. +
+ More specifically, H5Sselect_all selects + the special 5S_SELECT_ALL region for the dataspace + space_id. H5S_SELECT_ALL selects the + entire dataspace for any dataspace it is applied to.
Parameters:

hid_t space_id -
Dataspace identifier. +
IN: The identifier for the dataspace in which the + selection is being made.
Returns: -: Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). +; Returns a non-negative value if successful; + otherwise returns a negative value.
Non-C API(s): -: +

---> - - + +

Name: H5Sextent_copy +
Name: H5Sselect_elements
Signature: -: herr_t H5Sextent_copy(hid_t dest_space_id, - hid_t source_space_id - ) -
Purpose: -: Copies the extent of a dataspace. -
Description: -: H5Sextent_copy copies the extent from - source_space_id to dest_space_id. - This action may change the type of the dataspace. -
Parameters: -
-
hid_t dest_space_id -
IN: The identifier for the dataspace to which - the extent is copied. -
hid_t source_space_id -
IN: The identifier for the dataspace from which - the extent is copied. -
-
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -: - -

- - -

Name: H5Sset_extent_none -

Signature: -

herr_t H5Sset_extent_none(hid_t space_id) +

herr_t H5Sselect_elements(hid_t space_id, + H5S_seloper_t op, + const size_t num_elements, + const hssize_t *coord[ ] + )

Purpose: -

Removes the extent from a dataspace. +

Selects array elements to be included in the selection for a dataspace.

Description: -

H5Sset_extent_none removes the extent from - a dataspace and sets the type to H5S_NO_CLASS. +

H5Sselect_elements selects array elements to be + included in the selection for the space_id + dataspace. The number of elements selected must be set with + the num_elements. The coord array + is a two-dimensional array of size dataspace rank + by num_elements (ie. a list of coordinates in + the array). The order of the element coordinates in the + coord array also specifies the order in which + the array elements are iterated through when I/O is performed. + Duplicate coordinate locations are not checked for. +

+ The selection operator op determines how the + new selection is to be combined with the previously existing + selection for the dataspace. + The following operators are supported: +

+ + +

+ `H5S_SELECT_SET` +	+ Replaces the existing selection with the parameters from this call. + Overlapping blocks are not supported with this operator. + Adds the new selection to the existing selection. +
+ `H5S_SELECT_APPEND` +	+ Adds the new selection following the last element of the existing selection. +
+ `H5S_SELECT_PREPEND` +	+ Adds the new selection preceding the first element of the existing selection. +

+ +

Parameters:

hid_t space_id -
The identifier for the dataspace from which - the extent is to be removed. +
Identifier of the dataspace. +
H5S_seloper_t op +
operator specifying how the new selection is to be + combined with the existing selection for the dataspace. +
const size_t num_elements +
Number of elements to be selected. +
const hssize_t *coord[ ] +
A 2-dimensional array specifying the coordinates of the + elements being selected.

Returns: -

Returns a non-negative value if successful; +

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

Non-C API(s): -

- + +

Name: H5Sselect_hyperslab @@ -1047,29 +1206,29 @@ of the HDF5 User's Guide.. -->

- + +

Name: H5Sget_select_hyper_nblocks +
Name: H5Sselect_none
Signature: -: hssize_t H5Sget_select_hyper_nblocks(hid_t space_id - ) +; herr_t H5Sselect_none(hid_t space_id)
Purpose: -: Get number of hyperslab blocks. +; Resets the selection region to include no elements.
Description: -: H5Sget_select_hyper_nblocks returns the - number of hyperslab blocks in the current dataspace selection. +; H5Sselect_none resets the selection region + for the dataspace space_id to include no elements.
Parameters:

hid_t space_id -
IN: Identifier of dataspace to query. +
IN: The identifier for the dataspace in which the + selection is being reset.
Returns: -: Returns the number of hyperslab blocks in - the current dataspace selection if successful. - Otherwise returns a negative value. +; Returns a non-negative value if successful; + otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Sget_select_hyper_blocklist +

Name: H5Sselect_valid

Signature: -

herr_t H5Sget_select_hyper_blocklist(hid_t space_id, - hsize_t startblock, - hsize_t numblocks, - hsize_t *buf - ) +

htri_t H5Sselect_valid(hid_t space_id)

Purpose: -

Gets the list of hyperslab blocks currently selected. +

Verifies that the selection is within the extent of the dataspace.

Description: -

H5Sget_select_hyper_blocklist returns a list of - the hyperslab blocks currently selected. Starting with the - startblock-th block in the list of blocks, - numblocks blocks are put into the user's buffer. - If the user's buffer fills up before numblocks - blocks are inserted, the buffer will contain only as many - blocks as fit. -

- The block coordinates have the same dimensionality (rank) - as the dataspace they are located within. The list of blocks - is formatted as follows: -
     - <"start" coordinate>, immediately followed by -
     - <"opposite" corner coordinate>, followed by -
     - the next "start" and "opposite" coordinates, -
     - etc. -
- until all of the selected blocks have been listed. -

- No guarantee is implied as the order in which blocks are listed. +

H5Sselect_valid verifies that the selection + for the dataspace space_id is within the extent + of the dataspace if the current offset for the dataspace is used.

Parameters:

hid_t space_id -
IN: Dataspace identifier of selection to query. -
hsize_t startblock -
IN: Hyperslab block to start with. -
hsize_t numblocks -
IN: Number of hyperslab blocks to get. -
hsize_t *buf -
OUT: List of hyperslab blocks selected. +
The identifier for the dataspace being queried.

Returns: -

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

Returns a positive value, for TRUE, + if the selection is contained within the extent + or 0 (zero), for FALSE, if it is not. + Returns a negative value on error conditions + such as the selection or extent not being defined.

Non-C API(s): -

- - + +

Name: H5Sget_select_elem_npoints +
Name: H5Sset_extent_none
Signature: -: hssize_t H5Sget_select_elem_npoints(hid_t space_id - ) +; herr_t H5Sset_extent_none(hid_t space_id)
Purpose: -: Gets the number of element points in the current selection. +; Removes the extent from a dataspace.
Description: -: H5Sget_select_elem_npoints returns - the number of element points in the current dataspace selection. +; H5Sset_extent_none removes the extent from + a dataspace and sets the type to H5S_NO_CLASS.
Parameters:

hid_t space_id -
IN: Identifier of dataspace to query. +
The identifier for the dataspace from which + the extent is to be removed.
Returns: -: Returns the number of element points in the current dataspace selection if successful. - Otherwise returns a negative value. +; Returns a non-negative value if successful; + otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Sget_select_elem_pointlist +

Name: H5Sset_extent_simple

Signature: -

herr_t H5Sget_select_elem_pointlist(hid_t space_id, - hsize_t startpoint, - hsize_t numpoints, - hsize_t *buf +

herr_t H5Sset_extent_simple(hid_t space_id, + int rank, + const hsize_t *current_size, + const hsize_t *maximum_size )

Purpose: -

Gets the list of element points currently selected. +

Sets or resets the size of an existing dataspace.

Description: -

H5Sget_select_elem_pointlist returns the list of - element points in the current dataspace selection. Starting with - the startpoint-th point in the list of points, - numpoints points are put into the user's buffer. - If the user's buffer fills up before numpoints - points are inserted, the buffer will contain only as many - points as fit. +

H5Sset_extent_simple sets or resets the size of + an existing dataspace.

- The element point coordinates have the same dimensionality (rank) - as the dataspace they are located within. The list of element points - is formatted as follows: -
     - <coordinate>, followed by -
     - the next coordinate, -
     - etc. -
- until all of the selected element points have been listed. + rank is the dimensionality, or number of + dimensions, of the dataspace.

- The points are returned in the order they will be iterated through - when the selection is read/written from/to disk. + current_size is an array of size rank + which contains the new size of each dimension in the dataspace. + maximum_size is an array of size rank + which contains the maximum size of each dimension in the + dataspace. +

+ Any previous extent is removed from the dataspace, the dataspace + type is set to H5S_SIMPLE, and the extent is set as + specified.

Parameters:

hid_t space_id -
IN: Dataspace identifier of selection to query. -
hsize_t startpoint -
IN: Element point to start with. -
hsize_t numpoints -
IN: Number of element points to get. -
hsize_t *buf -
OUT: List of element points selected. +
Dataspace identifier. +
int rank +
Rank, or dimensionality, of the dataspace. +
const hsize_t *current_size +
Array containing current size of dataspace. +
const hsize_t *maximum_size +
Array containing maximum size of dataspace.

Returns: -

Returns a non-negative value if successful; +

Returns a dataspace identifier if successful; otherwise returns a negative value.

Non-C API(s): -

- - - - +--> -

Name: H5Sget_select_type -

Signature: -

H5S_sel_type H5Sget_select_type(hid_t space_id) -

Purpose: -

Determines the type of the dataspace selection. -

Description: -

H5Sget_select_type retrieves the - type of selection currently defined for the dataspace - space_id. -

Parameters: -
-
hid_t space_id -
Dataspace identifier. -
-

Returns: -

Returns the dataspace selection type, a value of - the enumerated datatype H5S_sel_type, - if successful. - Valid return values are as follows: - - - -

- `H5S_SEL_NONE` -	- No selection is defined. -
- `H5S_SEL_POINTS` -	- A sequence of points is selected. -
- `H5S_SEL_HYPERSLABS` -	- A hyperslab or compound hyperslab is selected. -
- `H5S_SEL_ALL` -	- The entire dataset is selected. -

- - Otherwise returns a negative value. -

Non-C API(s): -

- -

- - -

Name: H5Sclose -
Signature: -: herr_t H5Sclose(hid_t space_id - ) -
Purpose: -: Releases and terminates access to a dataspace. -
Description: -: H5Sclose releases a dataspace. - Further access through the dataspace identifier is illegal. - Failure to release a dataspace with this call will - result in resource leaks. -
Parameters: -
-
hid_t space_id -
Identifier of dataspace to release. -
-
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -: - -

- -

@@ -1448,14 +1467,15 @@ And in this document, the

HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -

- -Last modified: 10 June 2003 +

diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index b73394b..87fb4e2 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -26,6 +26,7 @@ HDF5/H5Z API Specification +

@@ -61,8 +62,7 @@ And in this document, the -

- +

H5Z: Filter and Compression Interface

@@ -119,20 +119,20 @@ See The Dataset Interface (H5D) in the HDF5 User's Guide for further information regarding data compression. -

Name: H5Zfilter_avail +
Signature: +: herr_t H5Zfilter_avail(H5Z_filter_t filter) +
Purpose: +: Determines whether a filter is available. +
Description: +: H5Zfilter_avail determines whether the filter + specified in filter is available to the application. +
Parameters: +
+
H5Z_filter_t filter +
IN: Filter identifier. +
+
Returns: +: Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +: + +

+ +

Name: H5Zregister @@ -357,9 +388,8 @@ facilitate moving easily between them. -->

- - - + +

Name: H5Zunregister @@ -391,39 +421,6 @@ facilitate moving easily between them. -->

Name: H5Zfilter_avail -
Signature: -: herr_t H5Zfilter_avail(H5Z_filter_t filter) -
Purpose: -: Determines whether a filter is available. -
Description: -: H5Zfilter_avail determines whether the filter - specified in filter is available to the application. -
Parameters: -
-
H5Z_filter_t filter -
IN: Filter identifier. -
-
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -: - -

- - - - - - -

@@ -458,14 +455,15 @@ And in this document, the -

HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -

- -Last modified: 10 June 2003 +

-- cgit v0.12