From 3e213ecf064638989c816ba3a10b3b6c6307fdad Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Tue, 14 Jul 1998 23:37:39 -0500 Subject: [svn-r502] HDF5 Reference Manual Final updates for Alpha2. All currently-implemented functions added. Technical content verified. --- doc/src/Glossary.html | 50 ++- doc/src/RM_H5.html | 220 ++++++++++++ doc/src/RM_H5A.html | 40 ++- doc/src/RM_H5D.html | 39 ++- doc/src/RM_H5E.html | 38 +- doc/src/RM_H5F.html | 241 +++++++++---- doc/src/RM_H5Front.html | 256 ++------------ doc/src/RM_H5G.html | 309 ++--------------- doc/src/RM_H5P.html | 52 ++- doc/src/RM_H5S.html | 470 ++++++++++++++++++------- doc/src/RM_H5T.html | 898 ++++++++++++++++++++++++------------------------ 11 files changed, 1456 insertions(+), 1157 deletions(-) create mode 100755 doc/src/RM_H5.html diff --git a/doc/src/Glossary.html b/doc/src/Glossary.html index 58e0b00..31b2db6 100755 --- a/doc/src/Glossary.html +++ b/doc/src/Glossary.html @@ -1,12 +1,33 @@ HDF5 Draft Glossary - + + + + +
+
+HDF5 Reference Manual   +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
+

HDF5 Glossary

-A glossary of data-types used in the HDF5 APIs. +(Under construction! + This is the bare beginning of a Glossary to accompany the HDF5 documentation; + it is by no means complete.)
  1. Basic Types @@ -51,3 +72,28 @@ the types below may change radically en route to a final API...
  2. hlen_t - (64-bit?) length on disk in bytes +
    +
    +HDF5 Reference Manual   +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    + +
    +HDF Help Desk + +
    +Last modified: 14 July 1998 + + + diff --git a/doc/src/RM_H5.html b/doc/src/RM_H5.html new file mode 100755 index 0000000..8b2ab70 --- /dev/null +++ b/doc/src/RM_H5.html @@ -0,0 +1,220 @@ + + +HDF5/H5 Draft API Specification + + + + +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    + +
    +

    H5: General Library Functions

    +
    + +These functions serve general-purpose needs of the HDF5 library +and it users. + + + +
    + +       + +       + +
    + + +
    +
    +
    Name: H5open +
    Signature: +
    herr_t H5open(void) +
    Purpose: +
    Flushes all data to disk, closes file identifiers, and cleans up memory. +
    Description: +
    H5open initialize the library. This function is + normally called automatically, but if you find that an + HDF5 library function is failing inexplicably, try calling + this function first. +
    Parameters: +
    +
    None. +
    +
    Returns: +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
    + + +
    +
    +
    Name: H5close +
    Signature: +
    herr_t H5close(void) +
    Purpose: +
    Flushes all data to disk, closes file identifiers, and cleans up memory. +
    Description: +
    H5close flushes all data to disk, + closes all file identifiers, and cleans up all memory used by + the library. This function is generall called when the + application calls exit, but may be called earlier + in event of an emergency shutdown or out of desire to free all + resources used by the HDF5 library. +
    Parameters: +
    +
    None. +
    +
    Returns: +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
    + + +
    +
    +
    Name: H5dont_atexit +
    Signature: +
    herr_t H5dont_atexit(void) +
    Purpose: +
    Instructs library not to install atexit cleanup routine. +
    Description: +
    H5dont_atexit indicates to the library that an + atexit() cleanup routine should not be installed. + The major purpose for this is in situations where the + library is dynamically linked into an application and is + un-linked from the application before exit() gets + called. In those situations, a routine installed with + atexit() would jump to a routine which was + no longer in memory, causing errors. +

    + In order to be effective, this routine must be called + before any other HDF function calls, and must be called each + time the library is loaded/linked into the application + (the first time and after it's been un-loaded). +

    Parameters: +
    +
    None. +
    +
    Returns: +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
    + + +
    +
    +
    Name: H5version +
    Signature: +
    herr_t H5version(unsigned *majnum, + unsigned *minnum, + unsigned *relnum, + unsigned *patnum + ) +
    Purpose: +
    +
    Description: +
    H5version retrieves the major, minor, release, and + patch versions of the library which is linked to the application. +
    Parameters: +
    +
    unsigned *majnum +
    The major version of the library. +
    unsigned *minnum +
    The minor version of the library. +
    unsigned *relnum +
    The release number of the library. +
    unsigned *patnum +
    The patch number of the library. +
    +
    Returns: +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
    + + +
    +
    +
    Name: H5vers_check +
    Signature: +
    herr_t H5vers_check(unsigned *majnum, + unsigned *minnum, + unsigned *relnum, + unsigned *patnum + ) +
    Purpose: +
    +
    Description: +
    H5vers_check verifies that the arguments match the + version numbers compiled into the library. This function is intended + to be called from user to verify that the versions of header files + compiled into the application match the version of the HDF5 library. +

    + Due to the risks of data corruption or segmentation faults, + H5vers_check causes the application to abort if the + version numbers do not match. +

    Parameters: +
    +
    unsigned *majnum +
    The major version of the library. +
    unsigned *minnum +
    The minor version of the library. +
    unsigned *relnum +
    The release number of the library. +
    unsigned *patnum +
    The patch number of the library. +
    +
    Returns: +
    Returns SUCCEED (0) if successful. + Upon failure, this function causes the application to abort. +
    + + +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    + +
    +HDF Help Desk + +
    +Last modified: 14 July 1998 + + + diff --git a/doc/src/RM_H5A.html b/doc/src/RM_H5A.html index a3b46c1..0c236da 100644 --- a/doc/src/RM_H5A.html +++ b/doc/src/RM_H5A.html @@ -5,6 +5,23 @@ HDF5/H5A Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5A: Attribute Interface

    @@ -55,7 +72,7 @@ is located in the group. How small is "small" is not defined by the library and is up to the user's interpretation.

    See Attributes in the -HDF5 User's Guide for further information. +HDF5 User's Guide for further information.

    @@ -458,14 +475,27 @@ See Attributes in the
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 6 July 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5D.html b/doc/src/RM_H5D.html index a9f5189..7b5263d 100644 --- a/doc/src/RM_H5D.html +++ b/doc/src/RM_H5D.html @@ -5,6 +5,23 @@ HDF5/H5D Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5D: Datasets Interface

    @@ -362,13 +379,27 @@ and set and retrieve their constant or persistent properties.
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 8 July 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html index 4c70b6a..e3c8177 100644 --- a/doc/src/RM_H5E.html +++ b/doc/src/RM_H5E.html @@ -5,6 +5,23 @@ HDF5/H5E Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5E: Error Interface

    @@ -318,14 +335,27 @@ errors within the H5E package.
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 6 July 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5F.html b/doc/src/RM_H5F.html index f8e25f4..926d7ba 100644 --- a/doc/src/RM_H5F.html +++ b/doc/src/RM_H5F.html @@ -5,6 +5,23 @@ HDF5/H5F Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5F: File Interface

    @@ -34,160 +51,250 @@ documented below. -
    +
    Name: H5Fopen
    Signature:
    hid_t H5Fopen(const char *name, - uintn flags, - hid_t access_template + unsigned flags, + hid_t access_id ) +
    Purpose: +
    Opens an existing file.
    Description: -
    This is the primary function for opening existing HDF5 files. - The flags parameter determines the file access mode. - There is no read flag, all open files are implicitily opened for - read access. - All flags may be combined with the '|' (boolean OR operator) to - change the behavior of the file open call. - The access_template parameter is a template containing - additional information required for specific methods of access, - parallel I/O for example. The paramters for access templates are - described in the H5P API documentation. +
    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 for the default I/O access + parameters. +

    + The flags argument determines whether writing + to an existing file will be allowed or not. + 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. + The more complex behaviors of a file's access are controlled + through the file-access property list. +

    + Files which are opened more than once return a unique identifier + for each H5Fopen() call and can be accessed + through all file identifiers. +

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

    Parameters:
    const char *name
    Name of the file to access. -
    uintn flags -
    File access flags: -
      -
      H5F_ACC_RDWR -
      Allow read and write access to file. -
    -
    hid_taccess_template -
    Template indicating the file access properties. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_template. Use 0 for default access template. +
    unsigned flags +
    File access flags. See the H5Fcreate + parameters list for a list of possible values. +
    hid_t access_id +
    Identifier for the file access properties list.
    Returns: -
    A file identifier if successful; +
    Returns a file identifier if successful; otherwise FAIL (-1).
    +
    Name: H5Fcreate
    Signature:
    hid_t H5Fcreate(const char *name, - uintn flags, - hid_t create_template, - hid_t access_template + unsigned flags, + hid_t create_id, + hid_t access_id ) +
    Purpose: +
    Creates HDF5 files.
    Description: -
    This is the primary function for opening and creating HDF5 files. - The flags parameter determines whether an existing - file will be overwritten or not. All newly created files are opened - for both reading and writing. - All flags may be combined with the '|' (boolean OR operator) to - change the behavior of the file open call. - The create_template and access_template - parameters are templates containing additional information required - for specific methods of access or particular aspects of the file - to set when creating a file. - The parameters for creation and access templates are - described in the H5P API documentation. +
    H5Fcreate is the primary function for creating + HDF5 files . +

    + The flags parameter determines whether an + existing file will be overwritten. All newly created files + are opened for both reading and writing. All flags may be + combined with the bit-wise OR operator (`|') to change + the behavior of the H5Fcreate call. +

    + The more complex behaviors of file creation and access + are controlled through the file-creation and file-access + property lists. The value of H5P_DEFAULT for + a template value indicates that the library should use + the default values for the appropriate template. Also see + H5Fpublic.h for the list of supported flags.

    Parameters:
    const char *name
    Name of the file to access.
    uintn flags -
    File access flags: +
    File access flags. Possible values include:
      +
      H5F_ACC_RDWR +
      Allow read and write access to file. +
      H5F_ACC_RDONLY +
      Allow read-only access to file.
      H5F_ACC_TRUNC -
      Truncate file, if it already exists. The file will - be truncated, erasing all data previously stored in - the file. +
      Truncate file, if it already exists, + erasing all data previously stored in the file. +
      H5F_ACC_EXCL +
      Fail if file already exists. +
      H5F_ACC_DEBUG +
      Print debug information. +
      H5P_DEFAULT +
      Apply default file access and creation properties.
    -
    hid_tcreate_template -
    File creation template ID, used when modifying default file meta-data -
    hid_taccess_template -
    Template indicating the file access properties. +
    hid_t create_id +
    File creation template identifier, used when modifying + default file meta-data. +
    hid_t access_id +
    File access property list identifier. If parallel file access is desired, this is a collective call according to the communicator stored in the - access_template. Use 0 for default access template. + access_template. + Use 0 for default access template.
    Returns: -
    An ID (of type hid_t) for the file upon success, - otherwise negative +
    Returns a file identifier if successful; + otherwise FAIL (-1).
    +
    Name: H5Fis_hdf5
    Signature:
    hbool_t H5Fis_hdf5(const char *name ) +
    Purpose: +
    Determines whether a file is in the HDF5 format.
    Description: -
    This function determines whether a file is in the HDF5 format. +
    H5Fis_hdf5 determines whether a file is in + the HDF5 format.
    Parameters:
    const char *name
    File name to check format.
    Returns: -
    TRUE/FALSE/negative +
    Returns TRUE or FALSE if successful. + Otherwise returns FAIL (-1).
    +
    Name: H5Fget_create_template
    Signature:
    hid_t H5Fget_create_template(hid_t file_id ) +
    Purpose: +
    Returns a file creation property list identifier.
    Description: -
    This function returns an template ID with a copy of the parameters - used to create this file. Useful for duplicating the parameters - when creating another file. +
    H5Fget_create_template returns a file creation + property list identifier identifying the creation properties + used to create this file. This function is useful for + duplicating properties when creating another file. +

    + See "File Creation Properties" in + H5P: Property List Interface + in this reference manual and + "File Creation Properties" + in Files in the + HDF5 User's Guide for + additional information and related functions.

    Parameters:
    hid_t file_id -
    File ID to get creation template of +
    Identifier of the file to get creation property list of
    Returns: -
    zero/negative +
    Returns a file creation property list identifier if successful; + otherwise FAIL (-1).
    + +
    +
    +
    Name: H5Fget_access_template +
    Signature: +
    hid_t H5Fget_access_template(hid_t file_id) +
    Purpose: +
    Returns a file access property list identifier. +
    Description: +
    H5Fget_access_template returns the + file access property list identifier of the specified file. +

    + See "File Access Properties" in + H5P: Property List Interface + in this reference manual and + "File Access Property Lists" + in Files in the + HDF5 User's Guide for + additional information and related functions. +

    Parameters: +
    +
    hid_t file_id +
    Identifier of file to get access property list of +
    +
    Returns: +
    Returns a file access property list identifier if successful; + otherwise FAIL (-1). +
    + +
    Name: H5Fclose
    Signature:
    herr_t H5Fclose(hid_t file_id ) +
    Purpose: +
    Terminates access to an HDF5 file.
    Description: -
    This function terminates access to an HDF5 file. If this is the - last file ID open for a file and if access IDs are still in use, +
    H5Fclose terminates access to an HDF5 file. + If this is the last file identifier open for a file + and if access identifiers are still in use, this function will fail.
    Parameters:
    hid_t file_id -
    File ID to terminate access to. +
    Identifier of a file to terminate access to.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1).
    -
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 29 June 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5Front.html b/doc/src/RM_H5Front.html index 374a1ad..9c4e1ce 100644 --- a/doc/src/RM_H5Front.html +++ b/doc/src/RM_H5Front.html @@ -4,6 +4,23 @@ HDF5 Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    HDF5: API Specification
    Reference Manual

    @@ -13,246 +30,43 @@ tools required to meet specific aspects of the HDF5 data-handling requirements.
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 29 June 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5G.html b/doc/src/RM_H5G.html index b4baa99..55b7d5b 100644 --- a/doc/src/RM_H5G.html +++ b/doc/src/RM_H5G.html @@ -5,6 +5,23 @@ HDF5/H5G Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5G: Group Interface

    @@ -596,287 +613,27 @@ then be trivial.
    -
    -UNUSED PORTIONS OF EMAIL NOTES. -
    -.... in left margin indicates where material was pulled out for use. -
    -
    -
    -
-Hi Elena, here's a hodgepodge of stuff from html documents and
-previous e-mails to answer your questions. Let me know if you need
-further clarification.
-
-....
-....  [H5Gmove and H5Gunlink "NYI" comments were here]
-....
-
-Elena> We need little bit more user-friendly description of the H5Gstat and
-Elena> H5Giterate functions.
-
->From a Mar 31 e-mail...
-
-Robb>
-....
-....  [H5Giterate was here]
-....
-Robb> 
-Robb> 
-Robb> Group Information Functions:
-....
-....  [H5Gstat was here]
-....
-Robb> 
-Robb> herr_t H5Gname(hid_t group_id, char *name, size_t max_name_len);
-Robb>
-Robb> This function retrieves the name of the group for a group ID.  The
-Robb> name is returned in 'name' up to the length specified in 'max_name_len'.
-Robb>
-....
-....  [H5Gget_linkval was here]
-....
-Robb> 
-Robb> H5Giterate example #1: The operator just looks at the member name and if it has an
-Robb>     `X' in it then it returns 1, otherwise return zero.  Returning 1 (or any
-Robb>     positive value) causes the iterator to immediately return that value.  If
-Robb>     none of the operators return 1 then the iterator eventually returns zero.
-Robb> 
-Robb> 1  herr_t
-Robb> 2  any_X (hid_t group_id/*unused*/,
-Robb> 4         const char *member_name,
-Robb> 5         void *op_data/*unused*/)
-Robb> 6  {
-Robb> 7      return strchr(member_name,'X') ? 1 : 0;
-Robb> 8  }
-Robb> 
-Robb> The iterator is invoked as:
-Robb> 
-Robb> 9  int elmt=0;
-Robb> 10  herr_t found = H5Giterate(file_id, "/foo", &elmt, any_X, NULL);
-Robb> 11  
-Robb> 12  if (found<0) {
-Robb> 13     printf ("Error iterating through group, at member %d\n", elmt);
-Robb> 14  } else if (found) {
-Robb> 15     printf ("Yes, member %d has an `X' in the name\n", elmt);
-Robb> 16  } else {
-Robb> 17     printf ("No member name contains an `X'\n");
-Robb> 18  }
-Robb> 
-Robb> H5Giterate example #2: An iterator to find an object whose name contains an `X'
-Robb>     This is the same as Example 1 except the operator also returns the name
-Robb>     that contains the `X'.  We do this by passing a pointer to a `char*' as the
-Robb>     operator data and the operator will initialize that `char*' by strdup'ing
-Robb>     the object name.
-Robb> 
-Robb> 1  herr_t
-Robb> 2  find_X (hid_t group_id/*unused*/,
-Robb> 4          const char *member_name,
-Robb> 5          void *op_data/*out*/)
-Robb> 6  {
-Robb> 7      if (strchr(member_name,'X')) {
-Robb> 8          *((char**)op_data) = strdup(member_name);
-Robb> 9          return 1;
-Robb> 10      }
-Robb> 11      return 0;
-Robb> 12  }
-Robb> 
-Robb> To print all the names with an `X' the iterator is invoked
-Robb> repeatedly until it returns zero.
-Robb> 
-Robb> 13  int elmt = 0;
-Robb> 14  char *name;
-Robb> 15  while (H5Giterate(file_id, "/foo", &elmt, find_X, &name)) {
-Robb> 16      puts (name);
-Robb> 17      free (name);
-Robb> 18  }
-Robb> 
-Robb> H5Giterate example #3: Print all names that contain the specified character.
-Robb>     This is the same as Example 2 except we have to pass data into the operator
-Robb>     as well as get data out.  We create a struct that contains the input data
-Robb>     (character to look for) and a slot for the output data (the name) and pass
-Robb>     that as the operator data.
-Robb> 
-Robb> 1  typedef struct {
-Robb> 2      char look_for;
-Robb> 3      char *name;
-Robb> 4  } find_char_t;
-Robb> 5  
-Robb> 6  herr_t
-Robb> 7  find_char (hid_t group_id/*unused*/,
-Robb> 9             const char *member_name,
-Robb> 10             find_char_t *op_data/*in,out*/)
-Robb> 11  {
-Robb> 13      if (strchr(member_name, op_data->look_for)) {
-Robb> 14          op_data->name = strdup (member_name);
-Robb> 15          return 1;
-Robb> 16      }
-Robb> 17      return 0;
-Robb> 18  }
-Robb> 
-Robb> To print all names that have a `Y' one would say
-Robb> 
-Robb> 19  find_char_t op_data;
-Robb> 20  int elmt = 0;
-Robb> 21  op_data->look_for = 'Y';
-Robb> 22  while (H5Giterate(file_id, "/foo", &elmt, find_X, &op_data)) {
-Robb> 23      puts (op_data->name);
-Robb> 24      free (op_data->name);
-Robb> 25  }
-Robb> 
-Robb> H5Giterate example #4: Efficient version of Example 3.
-Robb>     Examples 2 and 3 weren't too efficient because we kept interrupting the
-Robb> iterator and it had to start over, albeit from the middle of the search. If
-Robb> we could allow the iterator to go further then we wouldn't end up scanning
-Robb> through the leaf nodes of the symbol table so often (searching for a
-Robb> particular index, n, in a B-tree is an O(n) operation).
-Robb>     The H5Glist() function defined earlier returns the names of all the group
-Robb> members which belong to a certain class, H5G_ALL, H5G_DATASET, or H5G_GROUP.
-Robb> This example shows how to implement that functionality.
-Robb>     First we need a struct to describe the operator data and it's return
-Robb> value(s).  These correspond to the arguments presented for H5Glist, whose
-Robb> definition is at the end of this example. (Since most of the work is done by
-Robb> the operator we have to pass all this stuff back and forth through the
-Robb> iterator).
-Robb> 
-Robb> 1  typedef struct {
-Robb> 2      size_t     name_heap_size;
-Robb> 3      char       *name_heap;
-Robb> 4      unsigned   max_entries;
-Robb> 5      char       *names[];
-Robb> 6      int        type;
-Robb> 7      unsigned   cur_entries; /* How many names read so far */
-Robb> 8      size_t     cur_heap_size; /* How large is the heap */
-Robb> 9  } H5G_list_t;
-Robb> 
-Robb> The operator checks if an object is the right type, and if so adds it to
-Robb> the return value arrays in the op_data struct.  If the arrays become full
-Robb> then the operator returns 1 to stop the iterator. The H5*isa() functions
-Robb> return true iff the named object is of the * type (sans error handling).
-Robb> 
-Robb> 10  herr_t
-Robb> 11  H5G_list_op (hid_t grp_id, const char *memb_name,
-Robb> 12               H5G_list_t *op_data)
-Robb> 13  {
-Robb> 14      char *out_name;
-Robb> 15  
-Robb> 16      if (H5G_ALL==op_data->type ||
-Robb> 17          (H5G_DATASET==op_data->type && H5Disa(grp_id,memb_name)) ||
-Robb> 18          (H5G_GROUP==op_data->type && H5Gisa(grp_id, memb_name))) {
-Robb> 19  
-Robb> 20          /* Is there enough room for the name in the heap? */
-Robb> 21          if (op_data->cur_heap_size + strlen(memb_name) + 1 >
-Robb> 22              op_data->name_heap_size) {
-Robb> 23              return 2; /*try again later, see lines 59-62*/
-Robb> 24          }
-Robb> 25  
-Robb> 26          /* Add name to op_data return value arrays */
-Robb> 27          out_name = op_data->name_heap + op_data->cur_heap_size;
-Robb> 28          strcpy (out_name, memb_name);
-Robb> 29          op_data->names[op_data->cur_entries] = out_name;
-Robb> 30          op_data->cur_heap_size += strlen(memb_name) + 1;
-Robb> 31  
-Robb> 32          /* Is the output full? */
-Robb> 33          if (op_data->cur_entries >= op_data->max_entries) {
-Robb> 34              return 1;
-Robb> 35          }
-Robb> 36      }           
-Robb> 37      return 0;
-Robb> 38  }
-Robb> 
-Robb> And finally, the definition of H5Glist():
-Robb> 
-Robb> 39  int
-Robb> 40  H5Glist (hid_t group_id, size_t name_heap_size, char *name_heap,
-Robb> 41           int *start_idx, unsigned max_entries, char *names[],
-Robb> 42           int type)
-Robb> 43  {
-Robb> 44      H5G_list_t op_data;
-Robb> 45      herr_t status;
-Robb> 46  
-Robb> 47      op_data->name_heap_size = name_heap_size;
-Robb> 48      op_data->name_heap = name_heap;
-Robb> 49      op_data->max_entries = max_entries;
-Robb> 50      op_data->names = names;
-Robb> 51      op_data->type = type;
-Robb> 52      op_data->cur_entries = 0;
-Robb> 53      op_data->cur_heap_size = 0;
-Robb> 54  
-Robb> 55      if (0==cur_entries) return 0;
-Robb> 56      status = H5Giterate (group_id, ".", start_idx, H5G_list_op,
-Robb> 57                           &op_data);
-Robb> 58  
-Robb> 59      if (2==status && 0==op_data->cur_entries) {
-Robb> 60          return -1; /*heap not large enough for even one name*/
-Robb> 61      } else if (2==status) {
-Robb> 62          --*start_idx; /*heap overflow, try again later*/
-Robb> 63      } else if (status<0) {
-Robb> 64          return status; /*iterator or operator error*/
-Robb> 65      }
-Robb> 66      return op_data->cur_entries;
-Robb> 67  }
-Robb> 
-Robb>     The only other really interesting thing in this example are lines 23, 61,
-Robb> and 62.  We don't know if the name heap will overflow until we find a name to
-Robb> put there.  And then if it does, we need to be able to restart the iterator at
-Robb> the entry that failed instead of the following entry.
-Robb> 
-Robb> H5Giterate example #5: Print all the names of objects in a group, without any
-Robb>                         buffers.
-Robb> ---------------------
-Robb> 
-Robb> herr_t print_names (hid_t grp_id, const char *name, void *opdata)
-Robb> {
-Robb>     puts (name);
-Robb>     return 0;
-Robb> }
-Robb> 
-Robb> {
-Robb>     H5Giterate (file_id, "/foo/bar", NULL, print_names, NULL);
-Robb> }
-
-Elena> I believe there is a typo in the H5Pget_layout function in the source
-Elena> code. Second argument ( H5D_layout_t *layout is missing....)  
-
-It's returned by value, not reference.  It returns only the class of
-layout and then, based on the class, you must call some other H5Pget
-function like H5Pget_chunk() like this:
-
-	hid_t dcpl; /*dataset creation property list*/
-	hsize_t dims[32]; /*chunk dimensions*/
-	...
-	switch (H5Pget_layout(dcpl)) {
-	case H5D_CHUNKED:
-	    H5Pget_chunk(dcpl, NELMTS(dims), dims);
-	    break;
-	...
-	case H5D_LAYOUT_ERROR:
-	    ...
-	...
-	}
-
-
-Quincy and html> 
-Quincy and html> 
-....
-....  [Datatype material move to H5T.html]
-....
-Quincy and html> 
-Quincy and html> 
-
-
-
    -
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    -
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 8 July 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5P.html b/doc/src/RM_H5P.html index 90d6920..5329ec1 100644 --- a/doc/src/RM_H5P.html +++ b/doc/src/RM_H5P.html @@ -5,6 +5,23 @@ HDF5/H5P Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5P: Property List Interface

    @@ -115,19 +132,23 @@ many different parameters to be easily manipulated.
    H5P_FILE_CREATE
    Properties for file creation. - See H5F + See Files + in the HDF User's Guide for details about the file creation properties.
    H5P_FILE_ACCESS
    Properties for file access. - See H5F + See Files + in the HDF User's Guide for details about the file creation properties.
    H5P_DATASET_CREATE
    Properties for dataset creation. - See H5D + See Datasets + in the HDF User's Guide for details about dataset creation properties.
    H5P_DATASET_XFER
    Properties for raw data transfer. - See H5D + See Datasets + in the HDF User's Guide for details about raw data transfer properties.
    Parameters: @@ -1570,7 +1591,7 @@ many different parameters to be easily manipulated. property list and eventually to the file and passed to the compression functions.

    - See Compression + See Compression in the HDF5 User's Guide for further information.

    Parameters:
    @@ -1680,14 +1701,27 @@ many different parameters to be easily manipulated.
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 8 July 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5S.html b/doc/src/RM_H5S.html index 903d720..6230e56 100644 --- a/doc/src/RM_H5S.html +++ b/doc/src/RM_H5S.html @@ -5,6 +5,23 @@ HDF5/H5S Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5S: Dataspace Interface

    @@ -17,28 +34,56 @@ elements of a dataset.
                 
    +
    +
    +
    Name: H5Screate +
    Signature: +
    hid_t H5Screate(H5S_class_t type) +
    Purpose: +
    Creates a new dataspace of a specified type. +
    Description: +
    H5Screate creates a new dataspace of a particular + type. + The types currently supported are H5S_SCALAR, + H5S_SIMPLE, and H5S_NONE; + others are planned to be added later. The H5S_NONE + dataspace can only hold a selection, not an extent. +
    Parameters: +
    +
    H5S_class_t type +
    The type of dataspace to be created. +
    +
    Returns: +
    Returns a dataspace identifier if successful; + otherwise FAIL (-1). +
    + +
    Name: H5Screate_simple
    Signature: @@ -46,18 +91,22 @@ elements of a dataset. const hsize_t * dims, const hsize_t * maxdims ) +
    Purpose: +
    Creates a new simple data space and opens it for access.
    Description: -
    This function creates a new simple data space object and opens it for - access. The rank is the number of dimensions used in the - dataspace. The dims argument is the size of the simple - dataset and the maxdims argument is the upper limit on the - size of the dataset. maxdims may be the null pointer in - which case the upper limit is the same as dims. If an - element of maxdims is zero then the corresponding dimension - is unlimited, otherwise no element of maxdims should be - smaller than the corresponding element of dims. The - dataspace ID returned from this function should be released with - H5Sclose or resource leaks will occur. +
    H5Screate_simple creates a new simple data space + and opens it for access. The rank is the number of + dimensions used in the dataspace. + The dims argument is the size + of the simple dataset and the maxdims argument is + the upper limit on the size of the dataset. maxdims + may be the null pointer in which case the upper limit is the + same as dims. If an element of maxdims + is zero then the corresponding dimension is unlimited, otherwise + no element of maxdims should be smaller than the + corresponding element of dims. The dataspace + identifier returned from this function should be released with + H5Sclose or resource leaks will occur.
    Parameters:
    int rank @@ -68,224 +117,413 @@ elements of a dataset.
    An array of the maximum size of each dimension.
    Returns: -
    A dataspace ID on success, negative on failure. +
    Returns a dataspace identifier if successful; + otherwise FAIL (-1).
    +
    Name: H5Scopy
    Signature:
    hid_t H5Scopy(hid_t space_id ) +
    Purpose: +
    Creates an exact copy of a dataspace.
    Description: -
    This function copies a dataspace. The dataspace ID returned from this - function should be released with H5Sclose or resource leaks will occur. +
    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 -
    ID of dataspace to copy. +
    Identifier of dataspace to copy.
    Returns: -
    A dataspace ID on success, negative on failure. +
    Returns a dataspace identifier if successful; + otherwise FAIL (-1).
    +
    -
    Name: H5Sget_npoints +
    Name: H5Sselect_elements
    Signature: -
    hsize_t H5Sget_npoints(hid_t space_id) +
    herr_t H5Sselect_elements(hid_t space_id, + dh5s_selopt_t op, + const size_t num_elements, + const hssize_t *coord[ ] + ) +
    Purpose: +
    Selects array elements to be included in the selection for a dataspace.
    Description: -
    This function 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. +
    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. Currently, only the + H5S_SELECT_SET operator is supported, which + replaces the existing selection with the parameters from + this call. When operators other than H5S_SELECT_SET + are used to combine a new selection with an existing selection, + the selection ordering is reset to 'C' array ordering.

    Parameters:
    hid_t space_id -
    ID of the dataspace object to query +
    Identifier of the dataspace. +
    dh5s_selopt_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: -
    Number of elements in the dataspace, 0 on failure +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1).
    + + + +
    -
    Name: H5Sget_ndims +
    Name: H5Sextent_npoints
    Signature: -
    int H5Sget_ndims(hid_t space_id) +
    hsize_t H5Sextent_npoints(hid_t space_id) +
    Purpose: +
    Determines the number of elements in a dataspace.
    Description: -
    This function determines the dimensionality (or rank) of a dataspace. +
    H5Sextent_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: -
    Number of dimensions in the dataspace, negative on failure +
    Returns the number of elements in the dataspace if successful; + otherwise returns 0.
    +
    -
    Name: H5Sget_dims +
    Name: H5Sselect_npoints
    Signature: -
    int H5Sget_dims(hid_t space_id, +
    hsize_t H5Sselect_npoints(hid_t space_id) +
    Purpose: +
    Determines the number of elements in a dataspace. +
    Description: +
    H5Sselect_npoints determines the number of elements + in the current selection of a dataspace. +
    Parameters: +
    +
    hid_t space_id +
    Dataspace identifier. +
    +
    Returns: +
    Returns a dataspace identifier if successful; + otherwise FAIL (-1). +
    + + +
    +
    +
    Name: H5Sextent_ndims +
    Signature: +
    int H5Sextent_ndims(hid_t space_id) +
    Purpose: +
    Determines the dimensionality of a dataspace. +
    Description: +
    H5Sextent_ndims determines the dimensionality (or rank) + of a dataspace. +
    Parameters: +
    +
    hid_t space_id +
    Identifier of the dataspace +
    +
    Returns: +
    Returns the number of dimensions in the dataspace if successful; + otherwise FAIL (-1) +
    + + +
    +
    +
    Name: H5Sextent_dims +
    Signature: +
    int H5Sextent_dims(hid_t space_id, hsize_t *dims, hsize_t *maxdims ) +
    Purpose: +
    Retrieves dataspace dimension size and maximum size.
    Description: -
    This function returns the size of each dimension in a dataspace through - the dims parameter. +
    H5Sextent_dims returns the size and maximum sizes + of each dimension of a dataspace through the dims + and maxdims parameters.
    Parameters:
    hid_t space_id -
    ID of the dataspace object to query +
    IN: Identifier of the dataspace object to query
    hsize_t *dims -
    Pointer to array to store the size of each dimension. +
    OUT: Pointer to array to store the size of each dimension.
    hsize_t *maxdims -
    Pointer to array to store the maximum size of each dimension. +
    OUT: Pointer to array to store the maximum size of each dimension.
    Returns: -
    Number of dimensions in the dataspace, negative on failure +
    Returns the number of dimensions in the dataspace if successful; + otherwise FAIL (-1).
    +
    -
    Name: H5Sis_simple +
    Name: H5Sset_extent_simple
    Signature: -
    hbool_t H5Sis_simple(hid_t space_id) +
    herr_t H5S_set_extent_simple(hid_t space_id, + int rank, + const hsize_t *current_size, + const hsize_t *maximum_size + ) +
    Purpose: +
    Sets or resets the size of an existing dataspace.
    Description: -
    This function determines whether a dataspace object is a simple - dataspace or not. [Currently, all dataspace objects are simple - dataspaces, complex dataspace support will be added in the future] +
    H5S_set_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. +

    + 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 -
    ID of the dataspace object to query +
    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: -
    TRUE or FALSE on success, negative on failure +
    Returns a dataspace identifier if successful; + otherwise FAIL (-1).
    +
    -
    Name: H5Sset_space +
    Name: H5Sis_simple
    Signature: -
    herr_t H5Sset_space(hid_t space_id, - uint32 rank, - uint32 *dims - ) +
    hbool_t H5Sis_simple(hid_t space_id) +
    Purpose: +
    Determines whether a dataspace is a simple dataspace.
    Description: -
    This function determines the number of dimensions and the size of each - dimension for the space that a dataset is stored within. This function - only creates simple dataspace objects. Setting the rank to a - value of zero allows scalar objects to be created. Dimensions are - specified from slowest to fastest changing in the dims - array (i.e. 'C' order). Setting the size of a dimension to zero - indicates that the dimension is of unlimited size and should be allowed - to expand. Currently, only the first dimension in the array (the - slowest) may be unlimited in size. - [Currently, all dataspace objects are simple +
    H5Sis_simple determines whether a dataspace is + a simple dataspace. [Currently, all dataspace objects are simple dataspaces, complex dataspace support will be added in the future]
    Parameters:
    hid_t space_id -
    ID of the dataspace object. -
    uint32 rank -
    The number of dimensions the object is composed of. -
    uint32 * dims -
    An array of the size of each dimension. (NULL for scalar objects) +
    Identifier of the dataspace to query
    Returns: -
    zero/negative +
    Returns TRUE or FALSE if Successful; + otherwise FAIL (-1).
    +
    -
    Name: H5Sset_hyperslab +
    Name: H5Sget_class
    Signature: -
    herr_t H5Sset_hyperslab(hid_t space_id, - const hssize_t *start, - const hsize_t *count, - const hsize_t *stride - ) +
    H5S_class_t H5Sget_class(hid_t space_id) +
    Purpose: +
    Determine the current class of a dataspace.
    Description: -
    This function selects a hyperslab from a simple dataspace. The stride - array may be used to sub-sample the hyperslab chosen, a value of 1 in each - position of the stride array selects contiguous elements in the array, - a value of 2 selects every other element, etc. If the stride parameter is - set to NULL, a contiguous hyperslab is chosen. The values in the start and - count arrays may be negative, to allow for selecting hyperslabs in chunked - datasets which extend in arbitrary directions. +
    H5Sget_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, or + H5S_NONE.

    Parameters:
    hid_t space_id -
    ID of the dataspace object to set hyperslab in. -
    const hssize_t *start -
    Pointer to array of starting location for hyperslab. -
    const hsize_t *count -
    Pointer to array of magnitude of hyperslab. -
    const hsize_t *stride -
    Pointer to array of stride of hyperslab. +
    Dataspace identifier.
    Returns: -
    zero/negative +
    Returns a dataspace class name if successful; + otherwise FAIL (-1).
    +
    -
    Name: H5Sget_hyperslab +
    Name: H5Sselect_hyperslab
    Signature: -
    int H5Sget_hyperslab(hid_t space_id, - hssize_t *start, - hsize_t *count, - hsize_t *stride +
    herr_t H5Sselect_hyperslab(hid_t space_id, + h5s_selopt_top, + const hssize_t *start, + const hsize_t *stride + const hsize_t *count, + const hsize_t *block ) +
    Purpose: +
    Selects a hyperslab region to add to the current selected region.
    Description: -
    This function retrieves information about the hyperslab from a simple - dataspace. If no hyperslab has been defined then the hyperslab is the - same as the entire array. +
    H5Sselect_hyperslab selects a hyperslab region + to add to the current selected region for the dataspace + specified by space_id. +

    + The start, stride, count, + and block arrays must be the same size as the rank + of the dataspace. +

    + The selection operator op determines how the new + selection is to be combined with the already existing selection + for the dataspace. +

    + Currently, only the H5S_SELECT_SET operator is + supported; it replaces the existing selection with the + parameters from this call. Overlapping blocks are not + supported with the H5S_SELECT_SET operator. +

    +The start array determines the starting coordinates +of the hyperslab +to select. +

    +The stride array chooses array locations +from the dataspace +with each value in the stride array determining how +many elements to move +in each dimension. Setting a value in the stride +array to 1 moves to +each element in that dimension of the dataspace; setting a value of 2 in a +location in the stride array moves to every other +element in that +dimension of the dataspace. In other words, the stride +determines the +number of elements to move from the start location +in each dimension. +Stride values of 0 are not allowed. If the stride +parameter is NULL, +a contiguous hyperslab is selected (as if each value in the +stride array +was set to all 1's). +

    +The count array determines how many blocks to +select from the dataspace, in each dimension. +

    +The block array determines +the size of the element block selected from the dataspace. +If the block +parameter is set to NULL, the block size defaults +to a single element +in each dimension (as if the block array was set to all 1's). +

    +For example, in a 2-dimensional dataspace, setting +start to [1,1], +stride to [4,4], count to [3,7], and +block to [2,2] selects +21 2x2 blocks of array elements starting with location (1,1) and selecting +blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc. +

    +Regions selected with this function call default to C order iteration when +I/O is performed.

    Parameters: -
    +
    hid_t space_id -
    ID of the dataspace object to set hyperslab in. -
    hssize_t *start -
    Pointer to array to store starting location of hyperslab. -
    hsize_t *count -
    Pointer to array to store magnitude of hyperslab. -
    hsize_t *stride -
    Pointer to array to store stride of hyperslab. +
    IN: Identifier of dataspace selection to modify +
    H5S_seloper_t op +
    IN: Operation to perform on current selection. +
    const hssize_t *start +
    IN: Offset of start of hyperslab +
    const hsize_t *count +
    IN: Number of blocks included in hyperslab. +
    const hsize_t *stride +
    IN: Hyperslab stride. +
    const hsize_t *block +
    IN: Size of block in hyperslab.
    Returns: -
    Hyperslab dimensionality on success, negative on failure. +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1).
    +
    Name: H5Sclose
    Signature:
    herr_t H5Sclose(hid_t space_id ) +
    Purpose: +
    Releases and terminates access to a dataspace.
    Description: -
    This function releases a dataspace. Further access through the dataspace - ID is illegal. Failure to release a dataspace with this call will +
    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 -
    ID of dataspace to release. +
    Identifier of dataspace to release.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1).
    + +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 29 June 1998 +Last modified: 14 July 1998 diff --git a/doc/src/RM_H5T.html b/doc/src/RM_H5T.html index 4221e93..0fa5926 100644 --- a/doc/src/RM_H5T.html +++ b/doc/src/RM_H5T.html @@ -5,6 +5,23 @@ HDF5/H5T Draft API Specification +
    +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    +
    +

    H5T: Datatype Interface

    @@ -16,22 +33,17 @@ of a dataset.
    -        - -       -      
  3. H5Tget_nmembers
  4. H5Tget_member_name
  5. H5Tget_member_offset @@ -70,11 +82,16 @@ of a dataset.
  6. H5Tget_member_type
  7. H5Tinsert
  8. H5Tpack +
  9. H5Tinsert_array +

    +Conversion Functions +

  10. H5Tconvert +
  11. H5Tfind +
  12. H5Tset_overflow +
  13. H5Tget_overflow
  14. H5Tregister_hard
  15. H5Tregister_soft
  16. H5Tunregister -
  17. H5Tclose -
    18. @@ -88,18 +105,18 @@ The Datatype interface, H5T, provides a mechanism to describe the according to the data space (the H5S interface).

    -A data type is a collection of data type properties, all of +A datatype is a collection of datatype properties, all of which can be stored on disk, and which when taken as a whole, provide complete information for data conversion to or from that - data type. The interface provides functions to set and query - properties of a data type. + datatype. The interface provides functions to set and query + properties of a datatype.

    A data point is an instance of a datatype, which is an instance of a type class. We have defined a set of type classes and properties which can be extended at a later time. The atomic type classes are those which describe - types which cannot be decomposed at the data type interface + types which cannot be decomposed at the datatype interface level; all other classes are compound.

    @@ -117,13 +134,11 @@ in the HDF5 User's Guide for further information.

    Purpose:
    Opens a named datatype.
    Description: -
    From UG: H5Topen opens a named datatype at the location - specified by loc_id and returns an identifier - for the data type. The identifier should eventually be closed - by calling H5Tclose() to release resources. - loc_id is either a file or group identifier. -

    - From SC: Opens a named datatype. +

    H5Topen opens a named datatype at the location + specified by loc_id and returns an identifier + for the datatype. loc_id is either a file or + group identifier. The identifier should eventually be closed + by calling H5Tclose() to release resources.
    Parameters:
    hid_t loc_id @@ -148,13 +163,11 @@ in the HDF5 User's Guide for further information.
    Purpose:
    Commits a transient datatype to a file, creating a new named datatype.
    Description: -
    From UG: H5Tcommit commits a transient datatype (not immutable) - to a file, turned it into a named datatype. The loc_id - is either a file or group identifier which, when combined with - name, refers to a new named data type. -

    - From SC: Saves a transient data type to a file and turns - the type identifier into a named, immutable type. +

    H5Tcommit commits a transient datatype + (not immutable) to a file, turned it into a named datatype. + The loc_id is either a file or group identifier + which, when combined with name, refers to a new + named datatype.
    Parameters:
    hid_t loc_id @@ -178,24 +191,21 @@ in the HDF5 User's Guide for further information.
    Purpose:
    Determines whether a datatype is a named type or a transient type.
    Description: -
    From UG: H5Tcommitted queries a type to determine whether - it is a named type or a transient type. If this function returns +
    H5Tcommitted queries a type to determine whether + the type specified by the type identifier + is a named type or a transient type. If this function returns a positive value, then the type is named (that is, it has been committed, perhaps by some other application). Datasets which - return committed data types with H5Dget_type() are - able to share the data type with other datasets in the same file. -

    - From SC: Determines whether a data type is committed. + return committed datatypes with H5Dget_type() are + able to share the datatype with other datasets in the same file.

    Parameters:
    hid_t type
    Datatype identifier.
    Returns: -
    From UG: Returns a datatype identifier if successful; - otherwise FAIL (-1). -
    From SC: The successful returns values are TRUE if committed, - else FALSE. Otherwise returns FAIL (-1). +
    The successful return values are TRUE if committed, else FALSE. + Otherwise returns FAIL (-1).
    @@ -212,33 +222,35 @@ in the HDF5 User's Guide for further information. hid_t member_id )
    Purpose: -
    Adds a new member to a compound data type. +
    Adds an array member to a compound datatype.
    Description: -
    From SC: H5Tinsert_array adds a new member to the - compound data type parent_id. The new member's name, - name, must be unique within the compound data type. - The offset argument defines the start of - the member in an instance of the compound data type and - member_id is the type of the new member. +
    H5Tinsert_array adds a new member to the + compound datatype parent_id. The member is an array with ndims dimensionality and the size of the array is dim. - The total member size should be relatively small + The new member's name, name, must be unique + within the compound datatype. + The offset argument defines the start of the + member in an instance of the compound datatype and + member_id is the type identifier of the new member. + The total member size should be relatively small.
    Parameters:
    -
    hid_t parent_id -
    +
    hid_t parent_id +
    Identifier of the parent compound datatype.
    const char *name -
    +
    Name of new member.
    size_t offset -
    +
    Offset to start of new member within compound datatype.
    int ndims -
    +
    Dimensionality of new member.
    const size_t *dim -
    +
    Size of new member array.
    const int *perm -
    +
    Pointer to buffer to store the permutation vector of + the field.
    hid_t member_id -
    +
    Identifier of the datatype of the new member.
    Returns:
    Returns SUCCEED (0) if successful; @@ -257,25 +269,25 @@ in the HDF5 User's Guide for further information.
    Purpose:
    Finds a conversion function.
    Description: -
    From SC: H5Tfind finds a conversion function - that can handle a conversion from type src_id to - type dst_id. - The pcdata argument is a pointer - to a pointer to type conversion data which was created and - initialized by the soft type conversion function of this path - when the conversion function was installed on the path. +
    H5Tfind finds a conversion function that can + handle a conversion from type src_id to type + dst_id. + The pcdata argument is a pointer to a pointer + to type conversion data which was created and initialized + by the soft type conversion function of this path when the + conversion function was installed on the path.
    Parameters:
    hid_t src_id -
    +
    Identifier for the source datatype.
    hid_t dst_id -
    +
    Identifier for the destination datatype.
    H5T_cdata_t **pcdata -
    +
    Pointer to type conversion data.
    Returns:
    Returns a pointer to a suitable conversion function if successful. - Otherwise returns FAIL (-1). + Otherwise returns NULL.
    @@ -292,8 +304,9 @@ in the HDF5 User's Guide for further information.
    Purpose:
    Converts data from between specified datatypes.
    Description: -
    From SC: Convert nelmts elements from type - src_id to type dst_id. +
    H5Tconvert converts nelmts elements + from the type specified by the src_id identifier + to type dst_id. The source elements are packed in buf and on return the destination will be packed in buf. That is, the conversion is performed in place. @@ -307,15 +320,15 @@ in the HDF5 User's Guide for further information.
    Parameters:
    hid_t src_id -
    +
    Identifier for the source datatype.
    hid_t dst_id -
    +
    Identifier for the destination datatype.
    size_t nelmts -
    +
    Size of array buf.
    void *buf -
    +
    Array containing pre- and post-conversion values.
    void *background -
    +
    Optional background buffer.
    Returns:
    Returns SUCCEED (0) if successful; @@ -331,9 +344,9 @@ in the HDF5 User's Guide for further information.
    Purpose:
    Sets the overflow handler to a specified function.
    Description: -
    From SC: H5Tset_overflow sets the overflow handler +
    H5Tset_overflow sets the overflow handler to be the function specified by func. - func will be called for all data type conversions that + func will be called for all datatype conversions that result in an overflow.

    See the definition of H5T_overflow_t in @@ -348,7 +361,7 @@ in the HDF5 User's Guide for further information.

    Parameters:
    H5T_overflow_t func -
    +
    Overflow function.
    Returns:
    Returns SUCCEED (0) if successful; @@ -367,10 +380,10 @@ H5Tget_overflow ()
    Purpose:
    Returns a pointer to the current global overflow function.
    Description: -
    From SC: H5Tset_overflow returns a pointer +
    H5Tset_overflow returns a pointer to the current global overflow function. This is an application-defined function that is called whenever a - data type conversion causes an overflow. + datatype conversion causes an overflow.
    Parameters:
    None. @@ -392,12 +405,13 @@ H5Tget_overflow ()
    Purpose:
    Creates a new dataype.
    Description: -
    H5Tcreate creates a new dataype of the specified class with the - specified number of bytes. Currently, only the H5T_COMPOUND - datatype class is supported with this function, use H5Tcopy - to create integer or floating-point datatypes. The datatype ID - returned from this function should be released with H5Tclose or resource - leaks will result. +
    H5Tcreate creates a new dataype of the specified + class with the specified number of bytes. + Currently, only the H5T_COMPOUND datatype class is + supported with this function. Use H5Tcopy + to create integer or floating-point datatypes. + The datatype identifier returned from this function should be + released with H5Tclose or resource leaks will result.
    Parameters:
    H5T_class_t class @@ -406,7 +420,8 @@ H5Tget_overflow ()
    The number of bytes in the datatype to create.
    Returns: -
    Datatype ID on success, negative on failure. +
    Returns datatype identifier if successful; + otherwise FAIL (-1).
    @@ -414,14 +429,25 @@ H5Tget_overflow ()
    Name: H5Tcopy
    Signature: -
    hid_t H5Tcopy(hid_t type_id - ) +
    hid_t H5Tcopy(hid_t type_id)
    Purpose:
    Copies an existing datatype.
    Description: -
    H5Tcopy copies an existing datatype. The datatype ID returned - should be released with H5Tclose or resource leaks will occur. Native - datatypes supported by the library are: +
    H5Tcopy copies an existing datatype. + The returned type is always transient and unlocked. +

    + The type_id argument can be either a datatype + identifier, a predefined datatype (defined in + H5Tpublic.h), or a dataset identifier. + If type_id is a dataset identifier instead of a + datatype identifier, then this function returns a transient, + modifiable datatype which is a copy of the dataset's datatype. +

    + The datatype identifier returned should be released with + H5Tclose or resource leaks will occur. +

    Parameters:
    hid_t type_id -
    ID of datatype to copy. +
    Identifier of datatype to copy. Can be a datatype + identifier, a predefined datatype (defined in + H5Tpublic.h), or a dataset identifier.
    Returns: -
    Datatype ID on success, negative on failure. +
    Returns a datatype identifier if successful; + otherwise FAIL (-1)
    @@ -489,12 +519,14 @@ H5Tget_overflow ()
    Parameters:
    hid_t type_id1 -
    ID of datatype to compare. +
    Identifier of datatype to compare.
    hid_t type_id2 -
    ID of datatype to compare. +
    Identifier of datatype to compare.
    Returns: -
    TRUE/FALSE/negative +
    When successful, returns TRUE if the datatype identifiers + refer to the same datatype, else FALSE. + Otherwise returns FAIL (-1).
    @@ -505,19 +537,22 @@ H5Tget_overflow ()
    herr_t H5Tlock(hid_t type_id )
    Purpose: -
    Locks a type. +
    Locks a datatype.
    Description: -
    H5Tlock locks a type, making it read-only and non-destrucible. - This is normally done by the library for predefined data types so the - application doesn't inadvertently change or delete a predefined type. - Once a data type is locked it can never be unlocked. +
    H5Tlock locks the datatype specified by the + type_id identifier, making it read-only and + non-destrucible. This is normally done by the library for + predefined datatypes so the application does not + inadvertently change or delete a predefined type. + Once a datatype is locked it can never be unlocked.
    Parameters:
    hid_t type_id -
    ID of datatype to lock. +
    Identifier of datatype to lock.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1).
    @@ -528,16 +563,27 @@ H5Tget_overflow ()
    H5T_class_t H5Tget_class(hid_t type_id )
    Purpose: -
    Returns the base class of a datatype. +
    Returns the datatype class identifier.
    Description: -
    H5Tget_class returns the base class of a datatype. +
    H5Tget_class returns the datatype class identifier. +

    + Valid class identifiers, as defined in H5Tpublic.h, are: +

    • H5T_INTEGER (0) +
    • H5T_FLOAT (1) +
    • H5T_TIME (2) +
    • H5T_STRING (3) +
    • H5T_BITFIELD (4) +
    • H5T_OPAQUE (5) +
    • H5T_COMPOUND (6) +
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Non-negative type class on success, negative on failure. +
    Returns datatype class identifier if successful; + otherwise H5T_NO_CLASS (-1).
    @@ -554,10 +600,11 @@ H5Tget_overflow ()
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Positve size in bytes on success, 0 on failure. +
    Returns the size of the datatype in bytes if successful; + otherwise 0. @@ -569,27 +616,28 @@ H5Tget_overflow () size_tsize )
    Purpose: -
    Sets the total size for an atomic data type. +
    Sets the total size for an atomic datatype.
    Description: -
    H5Tset_size sets the total size in bytes for an - atomic data type (this - operation is not permitted on compound data types). If the size is - decreased so that the significant bits of the data type extend beyond +
    H5Tset_size sets the total size in bytes, + size, for an atomic datatype (this operation + is not permitted on compound datatypes). If the size is + decreased so that the significant bits of the datatype extend beyond the edge of the new size, then the `offset' property is decreased toward zero. If the `offset' becomes zero and the significant - bits of the data type still hang over the edge of the new size, then + bits of the datatype still hang over the edge of the new size, then the number of significant bits is decreased. Adjusting the size of an H5T_STRING automatically sets the precision - to 8*size. All data types have a positive size. + to 8*size. All datatypes have a positive size.
    Parameters:
    hid_t type_id -
    ID of datatype to change size. +
    Identifier of datatype to change size.
    size_t size
    Size in bytes to modify datatype.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -602,14 +650,26 @@ H5Tget_overflow ()
    Purpose:
    Returns the byte order of an atomic datatype.
    Description: -
    H5Tget_order returns the byte order of an atomic datatype. +
    H5Tget_order returns the byte order of an + atomic datatype. +

    + Possible return values are: +

      +
      H5T_ORDER_LE (0) +
      Little endian byte ordering (default). +
      H5T_ORDER_BE (1) +
      Big endian byte ordering. +
      H5T_ORDER_VAX (2) +
      VAX mixed byte ordering (not currently supported). +
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Byte order constant on success, negative on failure +
    Returns a byte order constant if successful; + otherwise H5T_ORDER_ERROR (-1). @@ -626,22 +686,23 @@ H5Tget_overflow ()
    H5Tset_order sets the byte ordering of an atomic datatype. Byte orderings currently supported are:
      -
      H5T_ORDER_LE -
      Little-endian byte ordering (default) -
      H5T_ORDER_BE -
      Big-endian byte ordering -
      H5T_ORDER_Vax -
      VAX-endianness byte ordering (not currently supported) +
      H5T_ORDER_LE (0) +
      Little-endian byte ordering (default). +
      H5T_ORDER_BE (1) +
      Big-endian byte ordering. +
      H5T_ORDER_VAX (2) +
      VAX mixed byte ordering (not currently supported).
    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    H5T_order_t order
    Byte ordering constant.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -652,18 +713,19 @@ H5Tget_overflow ()
    size_t H5Tget_precision(hid_t type_id )
    Purpose: -
    Returns the precision of an atomic data type. +
    Returns the precision of an atomic datatype.
    Description: -
    H5Tget_precision returns the precision of an atomic data type. The +
    H5Tget_precision returns the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Number of significant bits on success, 0 on failure +
    Returns the number of significant bits if successful; + otherwise 0. @@ -675,14 +737,14 @@ H5Tget_overflow () size_tprecision )
    Purpose: -
    Sets the precision of an atomic data type. +
    Sets the precision of an atomic datatype.
    Description: -
    H5Tset_precision sets the precision of an atomic data type. +
    H5Tset_precision sets the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().

    If the precision is increased then the offset is decreased and then the size is increased to insure that significant bits do not "hang - over" the edge of the data type. + over" the edge of the datatype.

    Changing the precision of an H5T_STRING automatically changes the size as well. The precision must be a multiple of 8.

    When decreasing the precision of a floating point type, set the @@ -691,12 +753,13 @@ H5Tget_overflow ()

    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    size_t precision
    Number of bits of precision for datatype.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -759,10 +822,11 @@ H5Tget_overflow ()
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Positive offset value on success, 0 on failure. +
    Returns a positive offset value if successful; + otherwise 0. @@ -826,19 +890,20 @@ H5Tget_overflow ()

    If the offset is incremented then the total size is incremented also if necessary to prevent significant bits of -the value from hanging over the edge of the data type. +the value from hanging over the edge of the datatype.

    The offset of an H5T_STRING cannot be set to anything but zero.

    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    size_t offset
    Offset of first significant bit.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -856,24 +921,27 @@ zero.
    H5Tget_pad retrieves the padding type of the least and most-significant bit padding. Valid types are:
      -
      H5T_PAD_ZERO +
      H5T_PAD_ZERO (0)
      Set background to zeros. -
      H5T_PAD_ONE +
      H5T_PAD_ONE (1)
      Set background to ones. -
      H5T_PAD_BACKGROUND +
      H5T_PAD_BACKGROUND (2)
      Leave background alone.
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    IN: Identifier of datatype to query.
    H5T_pad_t * lsb -
    Pointer to location to return least-significant bit padding type. +
    OUT: Pointer to location to return least-significant + bit padding type.
    H5T_pad_t * msb -
    Pointer to location to return most-significant bit padding type. +
    OUT: Pointer to location to return most-significant + bit padding type.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -890,24 +958,25 @@ zero.
    Description:
    H5Tset_pad sets the least and most-significant bits padding types.
      -
      H5T_PAD_ZERO +
      H5T_PAD_ZERO (0)
      Set background to zeros. -
      H5T_PAD_ONE +
      H5T_PAD_ONE (1)
      Set background to ones. -
      H5T_PAD_BACKGROUND +
      H5T_PAD_BACKGROUND (2)
      Leave background alone.
    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    H5T_pad_t lsb
    Padding type for least-significant bits.
    H5T_pad_t msb
    Padding type for most-significant bits.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -923,18 +992,19 @@ zero.
    H5Tget_sign retrieves the sign type for an integer type. Valid types are:
      -
      H5T_SGN_NONE +
      H5T_SGN_NONE (0)
      Unsigned integer type. -
      H5T_SGN_2 +
      H5T_SGN_2 (1)
      Two's complement signed integer type.
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Non-negative sign type on success, negative on failure +
    Returns a valid sign type if successful; + otherwise H5T_SGN_ERROR (-1). @@ -950,20 +1020,21 @@ zero.
    Description:
    H5Tset_sign sets the sign proprety for an integer type.
      -
      H5T_SGN_NONE +
      H5T_SGN_NONE (0)
      Unsigned integer type. -
      H5T_SGN_2 +
      H5T_SGN_2 (1)
      Two's complement signed integer type.
    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    H5T_sign_t sign
    Sign type.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -978,28 +1049,29 @@ zero. size_t * msize )
    Purpose: -
    Retrieves floating point data type bit field information. +
    Retrieves floating point datatype bit field information.
    Description:
    H5Tget_fields retrieves information about the locations of the various - bit fields of a floating point data type. The field positions are bit - positions in the significant region of the data type. Bits are + bit fields of a floating point datatype. The field positions are bit + positions in the significant region of the datatype. Bits are numbered with the least significant bit number zero. Any (or even all) of the arguments can be null pointers.
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    IN: Identifier of datatype to query.
    size_t * epos -
    Pointer to location to return exponent bit-position. +
    OUT: Pointer to location to return exponent bit-position.
    size_t * esize -
    Pointer to location to return size of exponent in bits. +
    OUT: Pointer to location to return size of exponent in bits.
    size_t * mpos -
    Pointer to location to return mantissa bit-position. +
    OUT: Pointer to location to return mantissa bit-position.
    size_t * msize -
    Pointer to location to return size of mantissa in bits. +
    OUT: Pointer to location to return size of mantissa in bits.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1018,7 +1090,7 @@ zero.
    Description:
    H5Tset_fields sets the locations and sizes of the various floating point bit fields. The field positions are bit positions in the - significant region of the data type. Bits are numbered with the least + significant region of the datatype. Bits are numbered with the least significant bit number zero.

    Fields are not allowed to extend beyond the number of bits of @@ -1026,7 +1098,7 @@ zero.

    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    size_t epos
    Exponent bit position.
    size_t esize @@ -1037,7 +1109,8 @@ zero.
    Size of mantissa in bits.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1054,10 +1127,11 @@ zero.
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Positive value on success, 0 on failure. +
    Returns the bias if successful; + otherwise 0. @@ -1075,12 +1149,13 @@ zero.
    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    size_t ebias
    Exponent bias value.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1093,23 +1168,24 @@ zero.
    Purpose:
    Retrieves mantissa normalization of a floating-point datatype.
    Description: -
    H5Tget_norm retrieves the mantissa normalization of a floating-point - datatype. Valid normalization values are: +
    H5Tget_norm retrieves the mantissa normalization of + a floating-point datatype. Valid normalization types are:
      -
      H5T_NORM_IMPLIED -
      MSB of mantissa isn't stored, always 1 -
      H5T_NORM_MSBSET +
      H5T_NORM_IMPLIED (0) +
      MSB of mantissa is not stored, always 1 +
      H5T_NORM_MSBSET (1)
      MSB of mantissa is always 1 -
      H5T_NORM_NONE +
      H5T_NORM_NONE (2)
      Mantissa is not normalized
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Non-negative normalization type on success, negative on failure +
    Returns a valid normalization type if successful; + otherwise H5T_NORM_ERROR (-1). @@ -1123,25 +1199,26 @@ zero.
    Purpose:
    Sets the mantissa normalization of a floating-point datatype.
    Description: -
    H5Tset_norm sets the mantissa normalization of a floating-point - datatype. Valid normalization values are: +
    H5Tset_norm sets the mantissa normalization of + a floating-point datatype. Valid normalization types are:
      -
      H5T_NORM_IMPLIED -
      MSB of mantissa isn't stored, always 1 -
      H5T_NORM_MSBSET +
      H5T_NORM_IMPLIED (0) +
      MSB of mantissa is not stored, always 1 +
      H5T_NORM_MSBSET (1)
      MSB of mantissa is always 1 -
      H5T_NORM_NONE +
      H5T_NORM_NONE (2)
      Mantissa is not normalized
    Parameters:
    hid_t type_id -
    ID of datatype to set. +
    Identifier of datatype to set.
    H5T_norm_t norm
    Mantissa normalization type.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1156,22 +1233,23 @@ zero.
    Description:
    H5Tget_inpad retrieves the internal padding type for unused bits in floating-point datatypes. - Valid padding values are: + Valid padding types are:
      -
      H5T_PAD_ZERO +
      H5T_PAD_ZERO (0)
      Set background to zeros. -
      H5T_PAD_ONE +
      H5T_PAD_ONE (1)
      Set background to ones. -
      H5T_PAD_BACKGROUND +
      H5T_PAD_BACKGROUND (2)
      Leave background alone.
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Non-negative padding type on success, negative on failure +
    Returns a valid padding type if successful; + otherwise H5T_PAD_ERROR (-1). @@ -1189,24 +1267,25 @@ zero. (that is, those significant bits which are not part of the sign, exponent, or mantissa), then H5Tset_inpad will be filled according to the value of the padding value property inpad. - Valid padding values are: + Valid padding types are:
      -
      H5T_PAD_ZERO +
      H5T_PAD_ZERO (0)
      Set background to zeros. -
      H5T_PAD_ONE +
      H5T_PAD_ONE (1)
      Set background to ones. -
      H5T_PAD_BACKGROUND +
      H5T_PAD_BACKGROUND (2)
      Leave background alone.
    Parameters:
    hid_t type_id -
    ID of datatype to modify. +
    Identifier of datatype to modify.
    H5T_pad_t pad
    Padding type.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1219,19 +1298,20 @@ zero.
    Purpose:
    Retrieves the character set type of a string datatype.
    Description: -
    H5Tget_cset retrieves the character set type of a string datatype. - Valid character set values are: +
    H5Tget_cset retrieves the character set type + of a string datatype. Valid character set types are:
      -
      H5T_CSET_ASCII +
      H5T_CSET_ASCII (0)
      Character set is US ASCII
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Non-negative character set type on success, negative on failure +
    Returns a valid character set type if successful; + otherwise H5T_CSET_ERROR (-1). @@ -1243,24 +1323,27 @@ zero. H5T_cset_t cset )
    Purpose: -
    +
    Sets character set to be used.
    Description: -
    HDF5 is able to distinguish between character sets of different +
    H5Tset_cset the character set to be used. +

    + HDF5 is able to distinguish between character sets of different nationalities and to convert between them to the extent possible. - Valid character set values are: + Valid character set types are:

      -
      H5T_CSET_ASCII -
      Character set is US ASCII +
      H5T_CSET_ASCII (0) +
      Character set is US ASCII.
    Parameters:
    hid_t type_id -
    ID of datatype to modify. +
    Identifier of datatype to modify.
    H5T_cset_t cset
    Character set type.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1273,21 +1356,22 @@ zero.
    Purpose:
    Retrieves the string padding method for a string datatype.
    Description: -
    H5Tget_strpad retrieves the string padding method for a string datatype. - Valid string padding values are: +
    H5Tget_strpad retrieves the string padding method + for a string datatype. Valid string padding types are:
      -
      H5T_STR_NULL +
      H5T_STR_NULL (0)
      Pad with zeros (as C does) -
      H5T_STR_SPACE +
      H5T_STR_SPACE (1)
      Pad with spaces (as FORTRAN does)
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Non-negative string padding type on success, negative on failure +
    Returns a valid string padding type if successful; + otherwise H5T_STR_ERROR (-1). @@ -1307,20 +1391,21 @@ zero. H5Tset_strpad defines the storage mechanism for the string. Valid string padding values are:
      -
      H5T_STR_NULL +
      H5T_STR_NULL (0)
      Pad with zeros (as C does) -
      H5T_STR_SPACE +
      H5T_STR_SPACE (1)
      Pad with spaces (as FORTRAN does)
    Parameters:
    hid_t type_id -
    ID of datatype to modify. +
    Identifier of datatype to modify.
    H5T_str_t strpad
    String padding type.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1337,10 +1422,11 @@ zero.
    Parameters:
    hid_t type_id -
    ID of datatype to query. +
    Identifier of datatype to query.
    Returns: -
    Number of members datatype has on success, negative on failure +
    Returns number of members datatype has if successful; + otherwise FAIL (-1). @@ -1349,25 +1435,27 @@ zero.
    Name: H5Tget_member_name
    Signature:
    char * H5Tget_member_name(hid_t type_id, - intn fieldno + int field_idx )
    Purpose: -
    Retrieves the name of a field of a compound data type. +
    Retrieves the name of a field of a compound datatype.
    Description: -
    H5Tget_member_name retrieves the name of a field of a compound data type. - Fields are stored in no particular order with numbers 0 through N-1 - where N is the value returned by H5Tget_nmembers(). The name of the - field is allocated with malloc() and the caller is responsible for - freeing the memory used by the name. +
    H5Tget_member_name retrieves the name of a field + of a compound datatype. Fields are stored in no particular + order, with indexes 0 through N-1, where N is the value returned + by H5Tget_nmembers(). The name of the field is + allocated with malloc() and the caller is responsible + for freeing the memory used by the name.
    Parameters:
    hid_t type_id -
    ID of datatype to query. -
    intn fieldno -
    Field number (indexed from 0) of the field name to retrieve. +
    Identifier of datatype to query. +
    int field_idx +
    Field index (0-based) of the field name to retrieve.
    Returns: -
    Valid pointer on success, NULL on failure +
    Returns a valid pointer if successful; + otherwise NULL. @@ -1376,30 +1464,35 @@ zero.
    Name: H5Tget_member_dims
    Signature:
    int H5Tget_member_dims(hid_t type_id, - intn fieldno, - size_t * dims, - int * perm + int field_idx, + size_t *dims, + int *perm )
    Purpose:
    Returns the dimensionality of the field.
    Description: -
    H5Tget_member_dims returns the dimensionality of the field. The dimensions - and permuation vector are returned through arguments dims - and perm, both arrays of at least four elements. Either - (or even both) may be null pointers. +
    H5Tget_member_dims returns the dimensionality of + the field. The dimensions and permuation vector are returned + through arguments dims and perm, + both arrays of at least four elements. + Either (or even both) may be null pointers.
    Parameters:
    hid_t type_id -
    ID of datatype to query. -
    intn fieldno -
    Field number (indexed from 0) of the field dims to retrieve. +
    Identifier of datatype to query. +
    int field_idx +
    Field index (0-based) of the field dims + to retrieve.
    size_t * dims
    Pointer to buffer to store the dimensions of the field.
    int * perm -
    Pointer to buffer to store the permutation vector of the field. +
    Pointer to buffer to store the permutation vector of + the field.
    Returns: -
    Number of dimensions on success, negative on failure. +
    Returns the number of dimensions, a number from 0 to 4, + if successful. + Otherwise returns FAIL (-1). @@ -1408,22 +1501,24 @@ zero.
    Name: H5Tget_member_type
    Signature:
    hid_t H5Tget_member_type(hid_t type_id, - intn fieldno + int field_idx )
    Purpose: -
    Returns the data type of the specified member. +
    Returns the datatype of the specified member.
    Description: -
    H5Tget_member_type returns the data type of the specified member. The caller +
    H5Tget_member_type returns the datatype of the specified member. The caller should invoke H5Tclose() to release resources associated with the type.
    Parameters:
    hid_t type_id -
    ID of datatype to query. -
    intn fieldno -
    Field number (indexed from 0) of the field type to retrieve. +
    Identifier of datatype to query. +
    int field_idx +
    Field index (0-based) of the field type to retrieve.
    Returns: -
    The ID of a copy of the datatype of the field, negative on failure. +
    Returns the identifier of a copy of the datatype of the field + if successful; + otherwise FAIL (-1). @@ -1437,30 +1532,32 @@ zero. hid_t field_id )
    Purpose: -
    Adds a new member to a compound data type. +
    Adds a new member to a compound datatype.
    Description: -
    H5Tinsert adds another member to the compound data type +
    H5Tinsert adds another member to the compound datatype type_id. The new member has a name which - must be unique within the compound data type. The offset - argument defines the start of the member in an instance of the compound - data type, and field_id is the type of the new member. - -

    Note: All members of a compound data type must be atomic; a - compound data type cannot have a member which is a compound data - type. + must be unique within the compound datatype. + The offset argument defines the start of the member + in an instance of the compound datatype, and field_id + is the datatype identifier of the new member. +

    + Note: All members of a compound datatype must be atomic; a + compound datatype cannot have a member which is a compound + datatype.

    Parameters:
    hid_t type_id -
    ID of compound datatype to modify. +
    Identifier of compound datatype to modify.
    const char * name
    Name of the field to insert.
    off_t offset
    Offset in memory structure of the field to insert.
    hid_t field_id -
    Datatype ID of the field to insert. +
    Datatype identifier of the field to insert.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1478,10 +1575,11 @@ zero.
    Parameters:
    hid_t type_id -
    ID of datatype to modify. +
    Identifier of datatype to modify.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1497,32 +1595,40 @@ zero.
    Purpose:
    Registers a hard conversion function.
    Description: -
    H5Tregister_hard registers a hard conversion function for a data type +
    H5Tregister_hard registers a hard conversion function for a datatype conversion path. The path is specified by the source and destination datatypes src_id and dst_id. A conversion path can only have one hard function, so func replaces any previous hard function. -

    If func is the null pointer then any hard function +

    + If func is the null pointer then any hard function registered for this path is removed from this path. The soft functions are then used when determining which conversion function is appropriate for this path. The name argument is used only for debugging and should be a short identifier for the function. -

    The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); +

    + The type of the conversion function pointer is declared as: +
    + typedef herr_t (*H5T_conv_t) (hid_t src_id, + hid_t dst_id, + H5T_cdata_t *cdata, + size_t nelmts, + void *buf, + void *bkg);

    Parameters:
    const char * name
    Name displayed in diagnostic output.
    hid_t src_id -
    ID of source datatype. +
    Identifier of source datatype.
    hid_t dst_id -
    ID of destination datatype. +
    Identifier of destination datatype.
    H5T_conv_t func
    Function to convert between source and destination datatypes.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1531,8 +1637,8 @@ zero.
    Name: H5Tregister_soft
    Signature:
    herr_t H5Tregister_soft(const char - * name, hid_t src_id, - hid_t dst_id, + * name, H5T_class_t src_cls, + H5T_class_t dst_cls, H5T_conv_t func )
    Purpose: @@ -1543,22 +1649,29 @@ zero. applicable existing conversion paths. The name is used only for debugging and should be a short identifier for the function. -

    The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); +

    + The type of the conversion function pointer is declared as: +
    + typedef herr_t (*H5T_conv_t) (hid_t src_id, + hid_t dst_id, + H5T_cdata_t *cdata, + size_t nelmts, + void *buf, + void *bkg);

    Parameters:
    const char * name
    Name displayed in diagnostic output. -
    hid_t src_id -
    ID of source datatype. -
    hid_t dst_id -
    ID of destination datatype. +
    H5T_class_t src_cls +
    Identifier of source datatype class. +
    H5T_class_t dst_cls +
    Identifier of destination datatype class.
    H5T_conv_t func
    Function to convert between source and destination datatypes.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1572,16 +1685,23 @@ zero.
    Removes a conversion function from all conversion paths.
    Description:
    H5Tunregister removes a conversion function from all conversion paths. -

    The type of the conversion function pointer is declared as: - typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, - size_t nelmts, void *buf, void *bkg); +

    + The type of the conversion function pointer is declared as: +
    + typedef herr_t (*H5T_conv_t) (hid_t src_id, + hid_t dst_id, + H5T_cdata_t *cdata, + size_t nelmts, + void *buf, + void *bkg);

    Parameters:
    H5T_conv_t func
    Function to remove from conversion paths.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1). @@ -1594,170 +1714,42 @@ zero.
    Purpose:
    Releases a datatype.
    Description: -
    H5Tclose releases a datatype. Further access through the datatype - ID is illegal. Failure to release a datatype with this call will - result in resource leaks. +
    H5Tclose releases a datatype. Further access + through the datatype identifier is illegal. Failure to release + a datatype with this call will result in resource leaks.
    Parameters:
    hid_t type_id -
    ID of datatype to release. +
    Identifier of datatype to release.
    Returns: -
    zero/negative +
    Returns SUCCEED (0) if successful; + otherwise FAIL (-1).
    -
    - -Aha!! And here is the reference to sharing and that command that had us -so buffaloed, H5Tshare!
    -To quote Quincy: "The H5Tshare() and H5Tis_shared() will be removed. Data types -will not be stored in the global heap. A new type of shared -message header will be added to the object headers that points to -another object header instead of the global heap..." - -
    -
    -UNUSED PORTIONS OF EMAIL NOTES. -
    -.... in left margin indicates where material was - pulled out for inclusion above. -
    -
    -
    -
-Elena> Datatype Interface:
-Elena> Do we have description of the named datatypes somewhere?
-
->From Datatypes.html...
-
-html> 7. Sharing Data Types among Datasets
-html> 
-html> If a file has lots of datasets which have a common data type
-html> then the file could be made smaller by having all the datasets
-html> share a single data type.  Instead of storing a copy of the data
-html> type in each dataset object header, a single data type is stored
-html> and the object headers point to it. The space savings is
-html> probably only significant for datasets with a compound data type
-html> since the simple data types can be described with just a few
-html> bytes anyway.
-html> 
-html> To create a bunch of datasets that share a single data type just
-html> create the datasets with a committed (named) data type.
-html> 
-html>  To create two datasets that share a common data type one just
-html>  commits the data type, giving it a name, and then uses that
-html>  data type to create the datasets.
-html> 
-html>  hid_t t1 = ...some transient type...;
-html>  H5Tcommit (file, "shared_type", t1);
-html>  hid_t dset1 = H5Dcreate (file, "dset1", t1, space, H5P_DEFAULT);
-html>  hid_t dset2 = H5Dcreate (file, "dset2", t1, space, H5P_DEFAULT);
-html>                
-html> 
-html>  And to create two additional datasets later which share the
-html>  same type as the first two datasets:
-html> 
-html>  hid_t dset1 = H5Dopen (file, "dset1");
-html>  hid_t t2 = H5Dget_type (dset1);
-html>  hid_t dset3 = H5Dcreate (file, "dset3", t2, space, H5P_DEFAULT);
-html>  hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT);
-html>                
-html> 
-html>                                     Example: Shared Types
-
-Mail from Quincey summarizing shared data types:
-
-Quincey> Hi Robb,
-Quincey>     Everything looks good, I just have a couple of minor comments below:
-Quincey> 
-Quincey> > A very quick data types summary (so I can remember it next week :-)
-Quincey> > 
-Quincey> >    * Handles to named types are immutable.
-Quincey> > 
-Quincey> >    * A transient type handle can be converted to a named type handle
-Quincey> >      by calling H5Tcommit().  This can only be called for transient
-Quincey> >      types which are not locked or predefined.
-Quincey> > 
-Quincey> >    * H5Topen() returns a handle to a named immutable type.
-Quincey> > 
-Quincey> >    * H5Tcopy() returns a handle to a transient type.
-Quincey>     H5Tcreate also returns a handle to a transient type.
-Quincey> 
-Quincey> >    * Using a named type in H5Dcreate() causes the dataset object
-Quincey> >      header to point to the named type (shared).  The link count on
-Quincey> >      the named type is incremented.
-Quincey> > 
-Quincey> >    * Using a transient type in H5Dcreate() causes the type to be
-Quincey> >      copied and stored in the dataset header (unshared).
-Quincey> > 
-Quincey> >    * Type handles returned from H5Dget_type() are immutable.
-Quincey> > 
-Quincey> >    * If the dataset is using a shared type (dataset object header
-Quincey> >      points to some other object header with a type message, e.g., a
-Quincey> >      named type) then H5Dget_type() returns a handle to that named
-Quincey> >      type.
-Quincey> > 
-Quincey> >    * If the dataset has a private type (data type is stored in the
-Quincey> >      dataset object header) then H5Dget_type() returns a handle to a
-Quincey> >      transient immutable type.
-Quincey> > 
-Quincey> >    * The name of a data type can be removed from a group, but unless
-Quincey> >      the reference count becomes zero the type continues to exist.
-Quincey> >      (Other objects work this way too).
-Quincey> > 
-Quincey> >    * H5Tcopy() applied to a dataset returns a transient, modifiable
-Quincey> >      copy of that dataset's data type.
-Quincey> > 
-Quincey> >    * H5Topen() applied to a dataset returns either a transient
-Quincey> >      immutable or named immutable data type depending on whether the
-Quincey> >      dataset has a shared data type.
-Quincey>     Hmm, do we want to allow this?  It makes a certain amount of sense, but
-Quincey> is a little unusual... :-)
-Quincey> 
-
-Elena, we decided not not to allow H5Topen() on a dataset.
-
-Quincey> 
-Quincey> >    * The H5Tshare() and H5Tis_shared() will be removed.  Data types
-Quincey> >      will not be stored in the global heap.  A new type of shared
-Quincey> >      message header will be added to the object headers that points to 
-Quincey> >      another object header instead of the global heap
-Quincey> 
-Quincey> >    * Still to discuss: Attributes on named data types?
-Quincey>     I think we should all them.
-Quincey> 
-
-Elena, attributes work for named data types just like they do for
-datasets.
-
-Quincey> 
-Quincey> >    * Still to discuss: compound types whose members point to other types.
-Quincey>     I like this concept a lot and this we should figure out a way to do it.
-Quincey> This allows the "is a" relationship to be used very nicely for named datatypes.
-Quincey> 
-Quincey> >    * Still to discuss: datasets that point to data types in other
-Quincey> >      files by symbolic link.
-Quincey>     Probably a good idea also, just ugly to implement.
-Quincey> 
-
-
    -
    -
    - - - - +
    +HDF5 Reference Manual  +H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5P   +H5S   +H5T   +H5Z   +Glossary +
    -Frank Baker -
    -HDF5 Documentation +HDF Help Desk
    -Last modified: 9 July 1998 +Last modified: 14 July 1998 -- cgit v0.12