-<Open and construct the desired file with the Core file driver>
-H5Fflush(fid);
-size = H5Fget_file_image(fid, NULL, 0);
-buffer_ptr = malloc(size);
-H5Fget_file_image(fid, buffer_ptr, size);
-<transmit size>
-<transmit *buffer_ptr>
-free(buffer_ptr);
-<close core file>
-*** Process B ***
-hid_t file_id;
-<receive size>
-buffer_ptr = malloc(size)
-<receive image in *buffer_ptr>
-file_id = H5LTopen_file_image(buf,
+
+
+| *** Process A *** |
+*** Process B *** |
+
+
+| <Open and construct the desired file with the Core file driver> |
+hid_t file_id; |
+
+
+| H5Fflush(fid); |
+ |
+
+
+| size = H5Fget_file_image(fid, NULL, 0); |
+ |
+
+
+| buffer_ptr = malloc(size); |
+ |
+
+
+| H5Fget_file_image(fid, buffer_ptr, size); |
+ |
+
+
+| <transmit size> |
+
<receive size> |
+
+
+| <transmit *buffer_ptr> |
+buffer_ptr = malloc(size) |
+
+
+| free(buffer_ptr); |
+<receive image in *buffer_ptr> |
+
+
+| <close core file> |
+file_id = H5LTopen_file_image(buf,
buf_len,
- H5LT_FILE_IMAGE_DONT_COPY);
-<read data from file, then close. note that the Core file driver will discard the buffer on close>
-
+ H5LT_FILE_IMAGE_DONT_COPY); |
+
+
+ |
+<read data from file, then close. note that the Core file driver will discard the buffer on close> |
+
+
-Example 11. Building and passing a file image from one process to another
+Example 11. Building and passing a file image from one process to another
4.4. Using a Template File
+
After the above examples, an example of the use of a template file might seem anti-climactic. A template file might be used to enforce consistency on file structure between files or in parallel HDF5 to avoid long sequences of collective operations to create the desired groups, datatypes, and possibly datasets. The following pseudo code outlines a potential use:
-<allocate and initialize buf and buflen, with buf containing the desired initial image (which in turn contains the desired group, datatype, and dataset definitions), and buf_len containing the size of buf>
+
+
+<allocate and initialize buf and buflen, with buf containing the desired initial image (which in turn contains the desired group, datatype, and dataset definitions), and buf_len containing the size of buf>
<allocate fapl_id>
<set fapl to use desired file driver that supports initial images>
H5Pset_file_image(fapl_id, buf, buf_len);
@@ -1090,7 +1204,8 @@ 4.4. Using a Template File
<read and/or write file as desired, close>
-Example 12. Using a template file
+Example 12. Using a template file
+
Observe that the above pseudo code includes an unnecessary buffer allocation and copy in the call to H5Pset_file_image(). As we have already discussed ways of avoiding this, we will not address that issue here.
What is interesting in this case is to consider why the application would find this use case attractive.
In the serial case, at first glance there seems little reason to use the initial image facility at all. It is easy enough to use standard C calls to duplicate a template file, rename it as desired, and then open it as an HDF5 file.
@@ -1101,14 +1216,18 @@ 4.4. Using a Template File
In closing, we would like to consider one last point. In the parallel case, we would expect template files to be quite large. Parallel HDF5 requires eager space allocation for chunked datasets. For similar reasons, we would expect template files in this context to contain long sequences of zeros with a scattering of metadata here and there. Such files would compress well, and the compressed images would be cheap to distribute across the available processes if necessary. Once distributed, each process could uncompress the image and write to file those sections containing actual data that lay within the section of the file assigned to the process. This approach might be significantly faster than a simple copy as it would allow sparse writes, and thus it might provide a compelling use case for template files. However, this approach would require extending our current API to allow compressed images. We would also have to add the H5Pget/set_image_decompression_callback() API calls. We see no problem in doing this. However, it is beyond the scope of the current effort, and thus we will not pursue the matter further unless there is interest in our doing so.
5. Java Signatures for File Image Operations API Calls
+
Potential Java function call signatures for the file image operation APIs are described in this section. These have not yet been implemented, and there are no immediate plans for implementation.
Note that the H5LTopen_file_image() call is omitted. Our practice has been to not support high-level library calls in Java.
-H5Pset_file_image
-int H5Pset_file_image(int fapl_id, const byte[] buf_ptr);
-H5Pget_file_image
-herr_t H5Pget_file_image(hid_t fapl_id, byte[] buf_ptr_ptr);
-H5_file_image_op_t
-public static H5_file_image_op_t
+
+
H5Pset_file_image
+int H5Pset_file_image(int fapl_id, const byte[] buf_ptr);
+
+H5Pget_file_image
+herr_t H5Pget_file_image(hid_t fapl_id, byte[] buf_ptr_ptr);
+
+H5_file_image_op_t
+public static H5_file_image_op_t
{
H5_FILE_IMAGE_OP_PROPERTY_LIST_SET,
H5_FILE_IMAGE_OP_PROPERTY_LIST_COPY,
@@ -1117,34 +1236,41 @@ 5. Java Signatures
H5_FILE_IMAGE_OP_FILE_OPEN,
H5_FILE_IMAGE_OP_FILE_RESIZE,
H5_FILE_IMAGE_OP_FILE_CLOSE
-}
-H5_file_image_malloc_cb
-
public interface H5_file_image_malloc_cb extends Callbacks {
+}
+
+H5_file_image_malloc_cb
+public interface H5_file_image_malloc_cb extends Callbacks {
buf[] callback(H5_file_image_op_t file_image_op, CBuserdata udata);
-}
-H5_file_image_memcpy_cb
-public interface H5_file_image_memcpy_cb extends Callbacks {
+}
+
+H5_file_image_memcpy_cb
+public interface H5_file_image_memcpy_cb extends Callbacks {
buf[] callback(buf[] dest, const buf[] src, H5_file_image_op_t file_image_op, CBuserdata
udata);
-}
-H5_file_image_realloc_cb
-public interface H5_file_image_realloc_cb extends Callbacks {
+}
+
+H5_file_image_realloc_cb
+public interface H5_file_image_realloc_cb extends Callbacks {
buf[] callback(buf[] ptr, H5_file_image_op_t file_image_op, CBuserdata udata);
-}
-H5_file_image_free_cb
-public interface H5_file_image_free_cb extends Callbacks {
+}
+
+H5_file_image_free_cb
+public interface H5_file_image_free_cb extends Callbacks {
void callback(buf[] ptr, H5_file_image_op_t file_image_op, CBuserdata udata);
-}
-H5_file_udata_copy_cb
-public interface H5_file_udata_copy_cb extends Callbacks {
+}
+
+H5_file_udata_copy_cb
+public interface H5_file_udata_copy_cb extends Callbacks {
buf[] callback(CBuserdata udata);
-}
-H5_file_udata_free_cb
-public interface H5_file_udata_free_cb extends Callbacks {
+}
+
+H5_file_udata_free_cb
+public interface H5_file_udata_free_cb extends Callbacks {
void callback(CBuserdata udata);
-}
-H5_file_image_callbacks_t
-public abstract class H5_file_image_callbacks_t
+}
+
+H5_file_image_callbacks_t
+public abstract class H5_file_image_callbacks_t
{
H5_file_image_malloc_cb image_malloc;
H5_file_image_memcpy_cb image_memcpy;
@@ -1169,52 +1295,79 @@ 5. Java Signatures
this.udata_free = udata_free;
this.udata = udata;
}
-}
-H5Pset_file_image_callbacks
-
int H5Pset_file_image_callbacks(int fapl_id,
- H5_file_image_callbacks_t callbacks_ptr);
-H5Pget_file_image_callbacks
-int H5Pget_file_image_callbacks(int fapl_id,
- H5_file_image_callbacks_t[] callbacks_ptr);
-H5Fget_file_image
-long H5Fget_file_image(int file_id, byte[] buf_ptr);
+}
+
+H5Pset_file_image_callbacks
+int H5Pset_file_image_callbacks(int fapl_id, H5_file_image_callbacks_t callbacks_ptr);
+
+H5Pget_file_image_callbacks
+int H5Pget_file_image_callbacks(int fapl_id, H5_file_image_callbacks_t[] callbacks_ptr);
+
+H5Fget_file_image
+long H5Fget_file_image(int file_id, byte[] buf_ptr);
6. Fortran Signatures for File Image Operations API Calls
+
Potential Fortran function call signatures for the file image operation APIs are described in this section. These have not yet been implemented, and there are no immediate plans for implementation.
-6.1. Low-level Fortran API Routines
+6.1. Low-level Fortran API Routines
+
The Fortran low-level APIs make use of Fortran 2003’s ISO_C_BINDING module in order to achieve portable and standard conforming interoperability with the C APIs. The C pointer (C_PTR) and function pointer (C_FUN_PTR) types are returned from the intrinsic procedures C_LOC(X) and C_FUNLOC(X), respectively, defined in the ISO_C_BINDING module. The argument X is the data or function to which the C pointers point to and must have the TARGET attribute in the calling program. Note that the variable name lengths of the Fortran equivalent of the predefined C constants were shortened to less than 31 characters in order to be Fortran standard compliant.
6.1.1. H5Pset_file_image_f
+
The signature of H5Pset_file_image_f is defined as follows:
SUBROUTINE H5Pset_file_image_f(fapl_id, buf_ptr, buf_len, hdferr)
The parameters of H5Pset_file_image are defined as follows:
-INTEGER(hid_t), INTENT(IN):: fapl_id
-Will contain the ID of the target file access property list.
-TYPE(C_PTR), INTENT(IN):: buf_ptr
-Will supply the C pointer to the initial file image or C_NULL_PTR if no initial file image is desired.
-INTEGER(size_t), INTENT(IN):: buf_len
-Will contain the size of the supplied buffer or 0 if no initial image is desired.
-INTEGER, INTENT(OUT) :: hdferr
-Will return the error status: 0 for success and -1 for failure.
+
+
+
+INTEGER(hid_t), INTENT(IN):: fapl_id |
+Will contain the ID of the target file access property list. |
+
+
+TYPE(C_PTR), INTENT(IN):: buf_ptr |
+Will supply the C pointer to the initial file image or C_NULL_PTR if no initial file image is desired. |
+
+
+INTEGER(size_t), INTENT(IN):: buf_len |
+Will contain the size of the supplied buffer or 0 if no initial image is desired. |
+
+
+INTEGER, INTENT(OUT) :: hdferr |
+Will return the error status: 0 for success and -1 for failure. |
+
+
6.1.2. H5Pget_file_image_f
The signature of H5Pget_file_image_f is defined as follows:
SUBROUTINE H5Pget_file_image_f(fapl_id, buf_ptr, buf_len, hdferr)
The parameters of H5Pget_file_image_f are defined as follows:
-INTEGER(hid_t), INTENT(IN) :: fapl_id
-Will contain the ID of the target file access property list
-TYPE(C_PTR), INTENT(INOUT), VALUE :: buf_ptr
-Will hold either a C_NULL_PTR or a scalar of type c_ptr. If buf_ptr is not C_NULL_PTR, on successful return, buf_ptr shall contain a C pointer to a copy of the initial image provided in the last call to H5Pset_file_image_f for the supplied fapl_id, or buf_ptr shall contain a C_NULL_PTR if there is no initial image set. The Fortran pointer can be obtained using the intrinsic C_F_POINTER.
-INTEGER(size_t), INTENT(OUT) :: buf_len
-Will contain the value of the buffer parameter for the initial image in the supplied fapl_id. The value will be 0 if no initial image is set.
-INTEGER, INTENT(OUT) :: hdferr
-Will return the error status: 0 for success and -1 for failure.
+
+
+INTEGER(hid_t), INTENT(IN) :: fapl_id |
+Will contain the ID of the target file access property list |
+
+
+TYPE(C_PTR), INTENT(INOUT), VALUE :: buf_ptr |
+Will hold either a C_NULL_PTR or a scalar of type c_ptr. If buf_ptr is not C_NULL_PTR, on successful return, buf_ptr shall contain a C pointer to a copy of the initial image provided in the last call to H5Pset_file_image_f for the supplied fapl_id, or buf_ptr shall contain a C_NULL_PTR if there is no initial image set. The Fortran pointer can be obtained using the intrinsic C_F_POINTER. |
+
+
+INTEGER(size_t), INTENT(OUT) :: buf_len |
+Will contain the value of the buffer parameter for the initial image in the supplied fapl_id. The value will be 0 if no initial image is set. |
+
+
+INTEGER, INTENT(OUT) :: hdferr |
+Will return the error status: 0 for success and -1 for failure. |
+
+
6.1.3. H5Pset_file_image_callbacks_f
-The signature of H5Pset_file_image_callbacks_f is defined as follows:
+The signature of H5Pset_file_image_callbacks_f is defined as follows:
+
+
INTEGER :: H5_IMAGE_OP_PROPERTY_LIST_SET_F=0,
H5_IMAGE_OP_PROPERTY_LIST_COPY_F=1,
H5_IMAGE_OP_PROPERTY_LIST_GET_F=2,
@@ -1232,82 +1385,163 @@
6.1.3. H5Pset_file_image_callbacks_f
TYPE(C_FUN_PTR), VALUE :: udata_free
TYPE(C_PTR), VALUE :: udata
END TYPE H5_file_image_callbacks_t
+
+
The semantics of the above values will be the same as those defined in the C enum. See Section 2.1.3 for more information.
Fortran Callback APIs
The Fortran callback APIs are shown below.
FUNCTION op_func(size, file_image_op, udata,) RESULT(image_malloc)
-INTEGER(size_t) :: size
-Will contain the size of the image buffer to allocate in bytes.
-INTEGER :: file_image_op
-Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked.
-TYPE(C_PTR), VALUE :: udata
-Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f.
-TYPE(C_FUN_PTR), VALUE :: image_malloc
-Shall contain a pointer to a function with functionality identical to the standard C library memcpy() call.
+
+
+
+| INTEGER(size_t) :: size |
+Will contain the size of the image buffer to allocate in bytes. |
+
+
+| INTEGER :: file_image_op |
+Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked. |
+
+
+| TYPE(C_PTR), VALUE :: udata |
+Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f. |
+
+
+| TYPE(C_FUN_PTR), VALUE :: image_malloc |
+Shall contain a pointer to a function with functionality identical to the standard C library memcpy() call. |
+
+
FUNCTION op_func(dest, src, size, & file_image_op, udata) RESULT(image_memcpy)
-TYPE(C_PTR), VALUE :: dest
-Will contain the address of the buffer into which to copy.
-TYPE(C_PTR), VALUE :: src
-Will contain the address of the buffer from which to copy
-INTEGER(size_t) :: size
-Will contain the number of bytes to copy.
-INTEGER :: file_image_op
-Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked.
-TYPE(C_PTR), VALUE :: udata
-Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f.
-TYPE(C_FUN_PTR), VALUE :: image_memcpy
-Shall contain a pointer to a function with functionality identical to the standard C library memcpy() call.
+
+
+
+| TYPE(C_PTR), VALUE :: dest |
+Will contain the address of the buffer into which to copy. |
+
+
+| TYPE(C_PTR), VALUE :: src |
+Will contain the address of the buffer from which to copy |
+
+
+| INTEGER(size_t) :: size |
+Will contain the number of bytes to copy. |
+
+
+| INTEGER :: file_image_op |
+Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked. |
+
+
+| TYPE(C_PTR), VALUE :: udata |
+Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f. |
+
+
+| TYPE(C_FUN_PTR), VALUE :: image_memcpy |
+Shall contain a pointer to a function with functionality identical to the standard C library memcpy() call. |
+
+
+
FUNCTION op_func(ptr, size, & file_image_op, udata) RESULT(image_realloc)
-TYPE(C_PTR), VALUE :: ptr
-Will contain the pointer to the buffer being reallocated
-INTEGER(size_t) :: size
-Will contain the desired size of the buffer after realloc in bytes.
-INTEGER :: file_image_op
-Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked.
-TYPE(C_PTR), VALUE :: udata
-Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f.
-TYPE(C_FUN_PTR), VALUE :: image_realloc
-Shall contain a pointer to a unction functionality identical to the standard C library realloc() call.
+
+
+| TYPE(C_PTR), VALUE :: ptr |
+Will contain the pointer to the buffer being reallocated |
+
+
+| INTEGER(size_t) :: size |
+Will contain the desired size of the buffer after realloc in bytes. |
+
+
+| INTEGER :: file_image_op |
+Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked. |
+
+
+| TYPE(C_PTR), VALUE :: udata |
+Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f. |
+
+
+| TYPE(C_FUN_PTR), VALUE :: image_realloc |
+Shall contain a pointer to a unction functionality identical to the standard C library realloc() call. |
+
+
+
FUNCTION op_func(ptr, file_image_op, udata) RESULT(image_free)
-TYPE(C_PTR), VALUE :: ptr
-Will contain the pointer to the buffer being released.
-INTEGER :: file_image_op
-Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked.
-TYPE(C_PTR), VALUE :: udata
-Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f.
-TYPE(C_PTR), VALUE :: image_free
-Shall contain a pointer to a function with functionality identical to the standard C library free() call
+
+
+| TYPE(C_PTR), VALUE :: ptr |
+Will contain the pointer to the buffer being released. |
+
+
+| INTEGER :: file_image_op |
+Will be set to one of the values of H5_IMAGE_OP_* indicating the operation being performed on the file image when this callback is invoked. |
+
+
+| TYPE(C_PTR), VALUE :: udata |
+Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f. |
+
+
+| TYPE(C_PTR), VALUE :: image_free |
+Shall contain a pointer to a function with functionality identical to the standard C library free() call |
+
+
+
FUNCTION op_func(udata) RESULT(udata_copy)
-TYPE(C_PTR), VALUE :: udata
-Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f.
-TYPE(C_FUN_PTR), VALUE :: udata_copy
-Shall contain a pointer to a function that will allocate a buffer of suitable size, copy the contents of the supplied udata into the new buffer, and return the address of the new buffer. The function will return C_NULL_PTR on failure.
+
+
+| TYPE(C_PTR), VALUE :: udata |
+Will be set to the value passed in for the udata parameter to H5Pset_file_image_callbacks_f. |
+
+
+| TYPE(C_FUN_PTR), VALUE :: udata_copy |
+Shall contain a pointer to a function that will allocate a buffer of suitable size, copy the contents of the supplied udata into the new buffer, and return the address of the new buffer. The function will return C_NULL_PTR on failure. |
+
+
+
FUNCTION op_func(udata) RESULT(udata_free)
-TYPE(C_PTR), VALUE :: udata
-Shall contain a pointer value, potentially to user-defined data, that will be passed to the image_malloc, image_memcpy, image_realloc, and image_free callbacks.
+
+
+| TYPE(C_PTR), VALUE :: udata |
+Shall contain a pointer value, potentially to user-defined data, that will be passed to the image_malloc, image_memcpy, image_realloc, and image_free callbacks. |
+
+
+
The signature of H5Pset_file_image_callbacks_f is defined as follows:
SUBROUTINE H5Pset_file_image_callbacks_f(fapl_id, &callbacks_ptr, hdferr)
The parameters are defined as follows:
-INTEGER(hid_t), INTENT(IN) :: fapl_id
-Will contain the ID of the target file access property list.
-TYPE(H5_file_image_callbacks_t), INTENT(IN) :: callbacks_ptr
-Will contain the callback derived type. callbacks_ptr shall contain a pointer to the Fortran function via the intrinsic functions C_LOC(X) and C_FUNLOC(X).
-INTEGER, INTENT(OUT) :: hdferr
-Will return the error status: 0 for success and -1 for failure.
+
+
+INTEGER(hid_t), INTENT(IN) :: fapl_id |
+Will contain the ID of the target file access property list. |
+
+
+TYPE(H5_file_image_callbacks_t), INTENT(IN) :: callbacks_ptr |
+Will contain the callback derived type. callbacks_ptr shall contain a pointer to the Fortran function via the intrinsic functions C_LOC(X) and C_FUNLOC(X). |
+
+
+INTEGER, INTENT(OUT) :: hdferr |
+Will return the error status: 0 for success and -1 for failure. |
+
+
6.1.4. H5Pget_file_image_callbacks_f
The H5Pget_file_image_callbacks_f routine is designed to obtain the current file image callbacks from a file access property list.
The signature is defined as follows
SUBROUTINE H5Pget_file_image_callbacks_f(fapl_id, callbacks_ptr, hdferr)
The parameters are defined as follows:
-INTEGER(hid_t), INTENT(IN) :: fapl_id
-Will contain the ID of the target file access property list.
-TYPE(H5_file_image_callbacks_t), INTENT(OUT) :: callbacks_ptr
-Will contain the callback derived type. Each member of the derived type shall have the same meaning as its C counterpart. See section 2.1.4 for more information.
-INTEGER, INTENT(OUT) :: hdferr
-Will return the error status: 0 for success and -1 for failure.
-
-6.1.5. Fortran Virtual File Driver Feature Flags
+
+
+| INTEGER(hid_t), INTENT(IN) :: fapl_id |
+Will contain the ID of the target file access property list. |
+
+
+| TYPE(H5_file_image_callbacks_t), INTENT(OUT) :: callbacks_ptr |
+Will contain the callback derived type. Each member of the derived type shall have the same meaning as its C counterpart. See section 2.1.4 for more information. |
+
+
+| INTEGER, INTENT(OUT) :: hdferr |
+Will return the error status: 0 for success and -1 for failure. |
+
+
+
+6.1.5. Fortran Virtual File Driver Feature Flags
Implementation of the H5Pget/set_file_image_callbacks_f() and H5Pget/set_file_image_f() APIs requires a pair of new virtual file driver feature flags:
H5FD_FEAT_LET_IMAGE_F
H5FD_FEAT_LET_IMAGE_CALLBACK_F
@@ -1317,31 +1551,58 @@
6.1.6. H5Fget_file_image_f
The signature of H5Fget_file_image_f shall be defined as follows:
SUBROUTINE H5Fget_file_image_f(file_id, buf_ptr, buf_len, hdferr, buf_size)
The parameters of H5Fget_file_image_f are defined as follows:
-INTEGER(hid_t), INTENT(IN) :: file_id
-Will contain the ID of the target file.
-TYPE(C_PTR), INTENT(IN) :: buf_ptr
-Will contain a C pointer to the buffer into which the image of the HDF5 file is to be copied. If buf_ptr is C_NULL_PTR, no data will be copied.
-INTEGER(size_t), INTENT(IN) :: buf_len
-Will contain the size in bytes of the supplied buffer.
-INTEGER(ssizet_t), INTENT(OUT), OPTIONAL :: buf_size
-Will indicate the buffer size required to store the file image (in other words, the length of the file). If only the buf_size is needed, then buf_ptr should be also be set to C_NULL_PTR
-INTEGER, INTENT(OUT) :: hdferr
-Returns the error status: 0 for success and -1 for failure.
+
+
+| INTEGER(hid_t), INTENT(IN) :: file_id |
+Will contain the ID of the target file. |
+
+
+| TYPE(C_PTR), INTENT(IN) :: buf_ptr |
+Will contain a C pointer to the buffer into which the image of the HDF5 file is to be copied. If buf_ptr is C_NULL_PTR, no data will be copied. |
+
+
+| INTEGER(size_t), INTENT(IN) :: buf_len |
+Will contain the size in bytes of the supplied buffer. |
+
+
+| INTEGER(ssizet_t), INTENT(OUT), OPTIONAL :: buf_size |
+Will indicate the buffer size required to store the file image (in other words, the length of the file). If only the buf_size is needed, then buf_ptr should be also be set to C_NULL_PTR |
+
+
+| INTEGER, INTENT(OUT) :: hdferr |
+Returns the error status: 0 for success and -1 for failure. |
See the “H5Fget_file_image” section for more information.
-6.2. High-level Fortran API Routine
+
+
+
+6.2. High-level Fortran API Routine
+
The new Fortran high-level routine H5LTopen_file_image_f will provide a wrapper for the high-level H5LTopen_file_image function. Consequently, the high-level Fortran API will not be implemented using low-level HDF5 Fortran APIs.
-6.2.1. H5LTopen_file_image_f
+
+6.2.1. H5LTopen_file_image_f
The signature of H5LTopen_file_image_f is defined as follows:
SUBROUTINE H5LTopen_file_image_f(buf_ptr, buf_len, flags, file_id, hdferr)
The parameters of H5LTopen_file_image_f are defined as follows:
-TYPE(C_PTR), INTENT(IN), VALUE :: buf_ptr
-Will contain a pointer to the supplied initial image. A C_NULL_PTR value is invalid and will cause H5LTopen_file_image_f to fail.
-INTEGER(size_t), INTENT(IN) :: buf_len
-Will contain the size of the supplied buffer. A value of 0 is invalid and will cause H5LTopen_file_image_f to fail.
-INTEGER, INTENT(IN) :: flags
-Will contain a set of flags indicating whether the image is to be opened read/write, whether HDF5 is to take control of the buffer, and how long the application promises to maintain the buffer. Possible flags are as follows: H5LT_IMAGE_OPEN_RW_F, H5LT_IMAGE_DONT_COPY_F, and H5LT_IMAGE_DONT_RELEASE_F. The C equivalent flags are defined in the “H5LTopen_file_image” section.
-INTEGER(hid_t), INTENT(IN) :: file_id
-Will be a file ID on success.
-INTEGER, INTENT(OUT) :: hdferr
-Returns the error status: 0 for success and -1 for failure.
+
+
+| TYPE(C_PTR), INTENT(IN), VALUE :: buf_ptr |
+Will contain a pointer to the supplied initial image. A C_NULL_PTR value is invalid and will cause H5LTopen_file_image_f to fail. |
+
+
+| INTEGER(size_t), INTENT(IN) :: buf_len |
+Will contain the size of the supplied buffer. A value of 0 is invalid and will cause H5LTopen_file_image_f to fail. |
+
+
+| INTEGER, INTENT(IN) :: flags |
+Will contain a set of flags indicating whether the image is to be opened read/write, whether HDF5 is to take control of the buffer, and how long the application promises to maintain the buffer. Possible flags are as follows: H5LT_IMAGE_OPEN_RW_F, H5LT_IMAGE_DONT_COPY_F, and H5LT_IMAGE_DONT_RELEASE_F. The C equivalent flags are defined in the “H5LTopen_file_image” section. |
+
+
+| INTEGER(hid_t), INTENT(IN) :: file_id |
+Will be a file ID on success. |
+
+
+| INTEGER, INTENT(OUT) :: hdferr |
+Returns the error status: 0 for success and -1 for failure. |
+
+