From 38af6a43fa7b537ed435d7aadbb110945853a554 Mon Sep 17 00:00:00 2001 From: Quincey Koziol Date: Thu, 11 Dec 2003 13:30:27 -0500 Subject: [svn-r7937] Purpose: Add RM docs for new H5I routines. Description: Add new H5I routines to the reference manual. --- doc/html/RM_H5I.html | 238 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 235 insertions(+), 3 deletions(-) diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html index b100372..478671f 100644 --- a/doc/html/RM_H5I.html +++ b/doc/html/RM_H5I.html @@ -78,19 +78,52 @@ object names.
             
+
+ +Alphabetical Listing + + + + + + + + + + + + + +
+ +        + +        + +

The FORTRAN90 Interfaces: @@ -102,20 +135,96 @@ as the corresponding C function.
             
+ +
+
+
Name: H5Idec_ref +
Signature: +
int H5Idec_ref(hid_t obj_id) +
Purpose: +
Decrements the reference count for an object. +
Description: +
H5Idec_ref decrements the reference count of the object + identified by obj_id. + +

+ The reference count for an object ID is attached to the information + about an object in memory and has no relation to the number of links to + an object on disk. + +

+ The reference count for a newly created object will be 1. + Reference counts for objects may be explicitly modified with this + function or with H5Iinc_ref. + When an object ID's reference count reaches zero, the object will be + closed. + Calling an object ID's 'close' function decrements the reference count + for the ID which normally closes the object, but + if the reference count for the ID has been incremented with + H5Iinc_ref, the object will only be closed when the + reference count + reaches zero with further calls to this function or the + object ID's 'close' function. + +

+ If the object ID was created by a collective parallel call (such as + H5Dcreate, H5Gopen, etc.), the reference + count should be modified by all the processes which have copies of + the ID. Generally this means that group, dataset, attribute, file + and named datatype IDs should be modified by all the processes and + that all other types of IDs are safe to modify by individual processes. + +

+ This function is of particular value when an application is maintaining + multiple copies of an object ID. The object ID can be incremented when + a copy is made. Each copy of the ID can then be safely closed or + decremented and the HDF5 object will be closed when the reference count + for that that object drops to zero. +

Parameters: +
+
hid_t obj_id +
IN: Object identifier whose reference count will be modified. +
+
Returns: +
Returns a non-negative reference count of the object ID after + decrementing it if successful; otherwise a negative value is returned. +
Fortran90 Interface: h5idec_ref_f +
+ 
+SUBROUTINE h5idec_ref_f(obj_id, ref_count, hdferr) 
+  IMPLICIT NONE
+  INTEGER(HID_T), INTENT(IN) :: obj_id  !Object identifier 
+  INTEGER, INTENT(OUT) :: ref_count     !Reference count of object ID
+  INTEGER, INTENT(OUT) :: hdferr        ! Error code
+                                        ! 0 on success, and -1 on failure
+END SUBROUTINE h5idec_ref_f
+
+ + +
+ +
@@ -190,6 +299,56 @@ END SUBROUTINE h5iget_name_f + +
+
+
Name: H5Iget_ref +
Signature: +
int H5Iget_ref(hid_t obj_id) +
Purpose: +
Retrieves the reference count for an object. +
Description: +
H5Iget_ref retrieves the reference count of the object + identified by obj_id. + +

+ The reference count for an object ID is attached to the information + about an object in memory and has no relation to the number of links to + an object on disk. + +

+ This function can also be used to check if an object ID is still valid. + A non-negative return value from this function indicates that the ID + is still valid. +

Parameters: +
+
hid_t obj_id +
IN: Object identifier whose reference count will be retrieved. +
+
Returns: +
Returns a non-negative current reference count of the object ID + if successful; otherwise a negative value is returned. +
Fortran90 Interface: h5iget_ref_f +
+ 
+SUBROUTINE h5iget_ref_f(obj_id, ref_count, hdferr) 
+  IMPLICIT NONE
+  INTEGER(HID_T), INTENT(IN) :: obj_id  !Object identifier 
+  INTEGER, INTENT(OUT) :: ref_count     !Reference count of object ID
+  INTEGER, INTENT(OUT) :: hdferr        ! Error code
+                                        ! 0 on success, and -1 on failure
+END SUBROUTINE h5iget_ref_f
+
+ + +
+ +
@@ -264,6 +423,79 @@ END SUBROUTINE h5iget_type_f -->
+ + +
+
+
Name: H5Iinc_ref +
Signature: +
int H5Iinc_ref(hid_t obj_id) +
Purpose: +
Increments the reference count for an object. +
Description: +
H5Iinc_ref increments the reference count of the object + identified by obj_id. + +

+ The reference count for an object ID is attached to the information + about an object in memory and has no relation to the number of links to + an object on disk. + +

+ The reference count for a newly created object will be 1. + Reference counts for objects may be explicitly modified with this + function or with H5Idec_ref. + When an object ID's reference count reaches zero, the object will be + closed. + Calling an object ID's 'close' function decrements the reference count + for the ID which normally closes the object, but + if the reference count for the ID has been incremented with this + function, the object will only be closed when the reference count + reaches zero with further calls to H5Idec_ref or the + object ID's 'close' function. + +

+ If the object ID was created by a collective parallel call (such as + H5Dcreate, H5Gopen, etc.), the reference + count should be modified by all the processes which have copies of + the ID. Generally this means that group, dataset, attribute, file + and named datatype IDs should be modified by all the processes and + that all other types of IDs are safe to modify by individual processes. + +

+ This function is of particular value when an application is maintaining + multiple copies of an object ID. The object ID can be incremented when + a copy is made. Each copy of the ID can then be safely closed or + decremented and the HDF5 object will be closed when the reference count + for that that object drops to zero. +

Parameters: +
+
hid_t obj_id +
IN: Object identifier whose reference count will be modified. +
+
Returns: +
Returns a non-negative reference count of the object ID after + incrementing it if successful; otherwise a negative value is returned. +
Fortran90 Interface: h5iinc_ref_f +
+ 
+SUBROUTINE h5iinc_ref_f(obj_id, ref_count, hdferr) 
+  IMPLICIT NONE
+  INTEGER(HID_T), INTENT(IN) :: obj_id  !Object identifier 
+  INTEGER, INTENT(OUT) :: ref_count     !Reference count of object ID
+  INTEGER, INTENT(OUT) :: hdferr        ! Error code
+                                        ! 0 on success, and -1 on failure
+END SUBROUTINE h5iinc_ref_f
+
+ + +
+
@@ -304,7 +536,7 @@ And in this document, the Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0 -- cgit v0.12