From 038c920c9f767d9be17cc6df0eb53a70bc71c557 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Tue, 7 Oct 2003 14:50:38 -0500 Subject: [svn-r7566] Purpose: Aphabetic sort of RM function entries Integrated Fortran90 APIs -- h5acreate_f and h5aclose_f Platforms tested: IE 5, Safari --- doc/html/RM_H5A.html | 520 ++++++++++++++++++++++++++++----------------------- 1 file changed, 284 insertions(+), 236 deletions(-) diff --git a/doc/html/RM_H5A.html b/doc/html/RM_H5A.html index 5422661..11b8cc6 100644 --- a/doc/html/RM_H5A.html +++ b/doc/html/RM_H5A.html @@ -25,6 +25,7 @@ HDF5/H5A API Specification +
@@ -60,8 +61,7 @@ And in this document, the -
-
+

H5A: Attribute Interface

@@ -104,39 +104,45 @@ and information about attributes. + +
+        +        +
-

+
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 @@ -144,6 +150,7 @@ 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. +
@@ -189,15 +196,61 @@ library and is up to the user's interpretation. See Attributes in the HDF5 User's Guide for further information. + + + +
+
+
Name: H5Aclose +
Signature: +
herr_t H5Aclose(hid_t attr_id) +
Purpose: +
Closes the specified attribute. +
Description: +
H5Aclose terminates access to the attribute + specified by attr_id by releasing the identifier. +

+ Further use of a released attribute identifier is illegal; + a function using such an identifier will fail. +

Parameters: +
+
hid_t attr_id +
IN: Attribute to release access to. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Fortran90 Interface: h5aclose_f +
+ 
+SUBROUTINE h5aclose_f(attr_id, hdferr) 
+  IMPLICIT NONE
+  INTEGER(HID_T), INTENT(OUT) :: attr_id  ! Attribute identifier 
+  INTEGER, INTENT(OUT) :: hdferr       ! Error code
+                                       ! 0 on success and -1 on failure
+END SUBROUTINE h5aclose_f	
+
+ + + +
+ + +
Name: H5Acreate
Signature: -
hid_t H5Acreate(hid_t loc_id, +
hid_t H5Acreate(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, - hid_t create_plist + hid_t create_plist )
Purpose:
Creates a dataset as an attribute of another group, dataset, @@ -224,107 +277,82 @@ See Attributes in the is currently unused; it may be used in the future for optional attribute properties. At this time, H5P_DEFAULT is the only accepted value. -

+

The attribute identifier returned from this function must be released with H5Aclose or resource leaks will develop.
Parameters:
-
hid_t loc_id -
IN: Object (dataset, group, or named datatype) to be attached to. -
const char *name -
IN: Name of attribute to create. -
hid_t type_id -
IN: Identifier of datatype for attribute. -
hid_t space_id -
IN: Identifier of dataspace for attribute. -
hid_t create_plist +
hid_t loc_id
+
IN: Object (dataset, group, or named datatype) to be attached to.
+
const char *name
+
IN: Name of attribute to create.
+
hid_t type_id
+
IN: Identifier of datatype for attribute.
+
hid_t space_id
+
IN: Identifier of dataspace for attribute.
+
hid_t create_plist
IN: Identifier of creation property list. (Currently unused; - the only accepted value is H5P_DEFAULT.) + the only accepted value is H5P_DEFAULT.)
Returns:
Returns an attribute identifier if successful; otherwise returns a negative value. -
Non-C API(s): -
- + +
Fortran90 Interface: h5acreate_f +
+ 
+SUBROUTINE h5acreate_f(obj_id, name, type_id, space_id, attr_id, & hdferr, creation_prp) 
+  IMPLICIT NONE
+  INTEGER(HID_T), INTENT(IN) :: obj_id    ! Object identifier 
+  CHARACTER(LEN=*), INTENT(IN) :: name    ! Attribute name
+  INTEGER(HID_T), INTENT(IN) :: type_id   ! Attribute datatype identifier 
+  INTEGER(HID_T), INTENT(IN) :: space_id  ! Attribute dataspace identifier
+  INTEGER(HID_T), INTENT(OUT) :: attr_id  ! Attribute identifier 
+  INTEGER, INTENT(OUT) :: hdferr       ! Error code:
+                                       ! 0 on success and -1 on failure
+  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: creation_prp
+                                       ! Attribute creation property 
+                                       ! list identifier 
+END SUBROUTINE h5acreate_f
+
- + +
-
Name: H5Aopen_name +
Name: H5Adelete
Signature: -
hid_t H5Aopen_name(hid_t loc_id, +
herr_t H5Adelete(hid_t loc_id, const char *name )
Purpose: -
Opens an attribute specified by name. +
Deletes an attribute from a location.
Description: -
H5Aopen_name opens an attribute specified by - its name, name, which is attached to the - object specified with loc_id. - The location object may be either a group, dataset, or - named datatype, which may have any sort of attribute. - The attribute identifier returned from this function must - be released with H5Aclose or resource leaks - will develop. +
H5Adelete removes the attribute specified by its + name, name, from a dataset, group, or named datatype. + This function should not be used when attribute identifiers are + open on loc_id as it may cause the internal indexes + of the attributes to change and future writes to the open + attributes to produce incorrect results.
Parameters:
hid_t loc_id -
IN: Identifier of a group, dataset, or named datatype - atttribute to be attached to. +
IN: Identifier of the dataset, group, or named datatype + to have the attribute deleted from.
const char *name -
IN: Attribute name. -
-
Returns: -
Returns attribute identifier if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- - -
-
-
Name: H5Aopen_idx -
Signature: -
hid_t H5Aopen_idx(hid_t loc_id, - unsigned int idx - ) -
Purpose: -
Opens the attribute specified by its index. -
Description: -
H5Aopen_idx opens an attribute which is attached - to the object specified with loc_id. - The location object may be either a group, dataset, or - named datatype, all of which may have any sort of attribute. - The attribute specified by the index, idx, - indicates the attribute to access. - The value of idx is a 0-based, non-negative integer. - The attribute identifier returned from this function must be - released with H5Aclose or resource leaks will develop. -
Parameters: -
-
hid_t loc_id -
IN: Identifier of the group, dataset, or named datatype - attribute to be attached to. -
unsigned int idx -
IN: Index of the attribute to open. +
IN: Name of the attribute to delete.
Returns: -
Returns attribute identifier if successful; +
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- + +
-
Name: H5Awrite +
Name: H5Aget_name
Signature: -
herr_t H5Awrite(hid_t attr_id, - hid_t mem_type_id, - const void *buf +
ssize_t H5Aget_name(hid_t attr_id, + size_t buf_size, + char *buf )
Purpose: -
Writes data to an attribute. +
Gets an attribute name.
Description: -
H5Awrite writes an attribute, specified with - attr_id. The attribute's memory datatype - is specified with mem_type_id. The entire - attribute is written from buf to the file. -

- Datatype conversion takes place at the time of a read or write - and is automatic. See the - Data Conversion - section of The Data Type Interface (H5T) in the - HDF5 User's Guide for a discussion of - data conversion, including the range of conversions currently - supported by the HDF5 libraries. +

H5Aget_name retrieves the name of an attribute + specified by the identifier, attr_id. + Up to buf_size characters are stored in + buf followed by a \0 string + terminator. If the name of the attribute is longer than + (buf_size -1), the string terminator is stored in the + last position of the buffer to properly terminate the string.
Parameters:
hid_t attr_id -
IN: Identifier of an attribute to write. -
hid_t mem_type_id -
IN: Identifier of the attribute datatype (in memory). -
const void *buf -
IN: Data to be written. +
IN: Identifier of the attribute. +
size_t buf_size +
IN: The size of the buffer to store the name in. +
char *buf +
IN: Buffer to store name in.
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. +
Returns the length of the attribute's name, which may be + longer than buf_size, if successful. + Otherwise returns a negative value.
Non-C API(s): -
- + +
-
Name: H5Aread +
Name: H5Aget_num_attrs
Signature: -
herr_t H5Aread(hid_t attr_id, - hid_t mem_type_id, - void *buf - ) +
int H5Aget_num_attrs(hid_t loc_id)
Purpose: -
Reads an attribute. +
Determines the number of attributes attached to an object.
Description: -
H5Aread reads an attribute, specified with - attr_id. The attribute's memory datatype - is specified with mem_type_id. The entire - attribute is read into buf from the file. -

- Datatype conversion takes place at the time of a read or write - and is automatic. See the - Data Conversion - section of The Data Type Interface (H5T) in the - HDF5 User's Guide for a discussion of - data conversion, including the range of conversions currently - supported by the HDF5 libraries. +

H5Aget_num_attrs returns the number of attributes + attached to the object specified by its identifier, + loc_id. + The object can be a group, dataset, or named datatype.
Parameters:
-
hid_t attr_id -
IN: Identifier of an attribute to read. -
hid_t mem_type_id -
IN: Identifier of the attribute datatype (in memory). -
void *buf -
OUT: Buffer for data to be read. +
hid_t loc_id +
IN: Identifier of a group, dataset, or named datatype.
Returns: -
Returns a non-negative value if successful; +
Returns the number of attributes if successful; otherwise returns a negative value.
Non-C API(s): -
- + +
Name: H5Aget_space @@ -452,7 +464,8 @@ See Attributes in the -->
- + +
Name: H5Aget_type @@ -488,78 +501,8 @@ See Attributes in the -->
- -
-
-
Name: H5Aget_name -
Signature: -
ssize_t H5Aget_name(hid_t attr_id, - size_t buf_size, - char *buf - ) -
Purpose: -
Gets an attribute name. -
Description: -
H5Aget_name retrieves the name of an attribute - specified by the identifier, attr_id. - Up to buf_size characters are stored in - buf followed by a \0 string - terminator. If the name of the attribute is longer than - (buf_size -1), the string terminator is stored in the - last position of the buffer to properly terminate the string. -
Parameters: -
-
hid_t attr_id -
IN: Identifier of the attribute. -
size_t buf_size -
IN: The size of the buffer to store the name in. -
char *buf -
IN: Buffer to store name in. -
-
Returns: -
Returns the length of the attribute's name, which may be - longer than buf_size, if successful. - Otherwise returns a negative value. -
Non-C API(s): -
- -
- - -
-
-
Name: H5Aget_num_attrs -
Signature: -
int H5Aget_num_attrs(hid_t loc_id) -
Purpose: -
Determines the number of attributes attached to an object. -
Description: -
H5Aget_num_attrs returns the number of attributes - attached to the object specified by its identifier, - loc_id. - The object can be a group, dataset, or named datatype. -
Parameters: -
-
hid_t loc_id -
IN: Identifier of a group, dataset, or named datatype. -
-
Returns: -
Returns the number of attributes if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- - + +
Name: H5Aiterate @@ -631,36 +574,80 @@ See Attributes in the -->
+ + +
+
+
Name: H5Aopen_idx +
Signature: +
hid_t H5Aopen_idx(hid_t loc_id, + unsigned int idx + ) +
Purpose: +
Opens the attribute specified by its index. +
Description: +
H5Aopen_idx opens an attribute which is attached + to the object specified with loc_id. + The location object may be either a group, dataset, or + named datatype, all of which may have any sort of attribute. + The attribute specified by the index, idx, + indicates the attribute to access. + The value of idx is a 0-based, non-negative integer. + The attribute identifier returned from this function must be + released with H5Aclose or resource leaks will develop. +
Parameters: +
+
hid_t loc_id +
IN: Identifier of the group, dataset, or named datatype + attribute to be attached to. +
unsigned int idx +
IN: Index of the attribute to open. +
+
Returns: +
Returns attribute identifier if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
+ +
-
Name: H5Adelete +
Name: H5Aopen_name
Signature: -
herr_t H5Adelete(hid_t loc_id, +
hid_t H5Aopen_name(hid_t loc_id, const char *name )
Purpose: -
Deletes an attribute from a location. +
Opens an attribute specified by name.
Description: -
H5Adelete removes the attribute specified by its - name, name, from a dataset, group, or named datatype. - This function should not be used when attribute identifiers are - open on loc_id as it may cause the internal indexes - of the attributes to change and future writes to the open - attributes to produce incorrect results. +
H5Aopen_name opens an attribute specified by + its name, name, which is attached to the + object specified with loc_id. + The location object may be either a group, dataset, or + named datatype, which may have any sort of attribute. + The attribute identifier returned from this function must + be released with H5Aclose or resource leaks + will develop.
Parameters:
hid_t loc_id -
IN: Identifier of the dataset, group, or named datatype - to have the attribute deleted from. +
IN: Identifier of a group, dataset, or named datatype + atttribute to be attached to.
const char *name -
IN: Name of the attribute to delete. +
IN: Attribute name.
Returns: -
Returns a non-negative value if successful; +
Returns attribute identifier if successful; otherwise returns a negative value.
Non-C API(s): -
- + +
-
Name: H5Aclose +
Name: H5Aread
Signature: -
herr_t H5Aclose(hid_t attr_id) +
herr_t H5Aread(hid_t attr_id, + hid_t mem_type_id, + void *buf + )
Purpose: -
Closes the specified attribute. +
Reads an attribute.
Description: -
H5Aclose terminates access to the attribute - specified by attr_id by releasing the identifier. +
H5Aread reads an attribute, specified with + attr_id. The attribute's memory datatype + is specified with mem_type_id. The entire + attribute is read into buf from the file.

- Further use of a released attribute identifier is illegal; - a function using such an identifier will fail. + Datatype conversion takes place at the time of a read or write + and is automatic. See the + Data Conversion + section of The Data Type Interface (H5T) in the + HDF5 User's Guide for a discussion of + data conversion, including the range of conversions currently + supported by the HDF5 libraries.

Parameters:
hid_t attr_id -
IN: Attribute to release access to. +
IN: Identifier of an attribute to read. +
hid_t mem_type_id +
IN: Identifier of the attribute datatype (in memory). +
void *buf +
OUT: Buffer for data to be read.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
+ + +
+
+
Name: H5Awrite +
Signature: +
herr_t H5Awrite(hid_t attr_id, + hid_t mem_type_id, + const void *buf + ) +
Purpose: +
Writes data to an attribute. +
Description: +
H5Awrite writes an attribute, specified with + attr_id. The attribute's memory datatype + is specified with mem_type_id. The entire + attribute is written from buf to the file. +

+ Datatype conversion takes place at the time of a read or write + and is automatic. See the + Data Conversion + section of The Data Type Interface (H5T) in the + HDF5 User's Guide for a discussion of + data conversion, including the range of conversions currently + supported by the HDF5 libraries. +

Parameters: +
+
hid_t attr_id +
IN: Identifier of an attribute to write. +
hid_t mem_type_id +
IN: Identifier of the attribute datatype (in memory). +
const void *buf +
IN: Data to be written. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
@@ -733,14 +780,15 @@ And in this document, the

-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -
- -Last modified: 6 June 2001 +
-- cgit v0.12