Page tree

 

JAVA

FORTRAN

C++

C

 

Link

H5R_GET_NAME

Retrieves a name for a referenced object

Procedure:

H5R_GET_NAME (loc_id,  ref_type, ref, name,  size)

Signature:

ssize_t H5Rget_name(hid_t loc_id,
                     H5R_type_t ref_type,
                     void *ref,
                     char *name,
                     size_t size)

Fortran90 Interface: h5rget_name_object_f or h5rget_name_region_f
    
To get name of an object reference: h5rget_name_object_f

Signature:
  SUBROUTINE h5rget_name_object_f(loc_id,  ref, name, hdferr, size)
    INTEGER(HID_T)    , INTENT(IN)            :: loc_id 
    TYPE(hobj_ref_t_f), INTENT(IN)            :: ref
    CHARACTER(LEN=*)  , INTENT(OUT)           :: name
    INTEGER           , INTENT(OUT)           :: hdferr
    INTEGER(SIZE_T)   , INTENT(OUT), OPTIONAL :: size

Inputs:
  loc_id  - Identifier for the file containing the reference or
            for any object in that file.
  ref     - Object reference

Outputs:
  name    - A name associated with the referenced object or dataset region.
  hdferr  - Error code
             0 on success and -1 on failure

Optional parameters:
  size    - The size of the name buffer,
            returning 0 (zero) if no name is associated with the identifier


To get name of a region reference: h5rget_name_region_f

Signature:
  SUBROUTINE h5rget_name_region_f(loc_id, ref, name, hdferr, size)
    INTEGER(HID_T)         , INTENT(IN)            :: loc_id
    TYPE(hdset_reg_ref_t_f), INTENT(IN)            :: ref
    CHARACTER(LEN=*)       , INTENT(OUT)           :: name
    INTEGER(SIZE_T)        , INTENT(OUT), OPTIONAL :: size
    INTEGER                , INTENT(OUT)           :: hdferr

Inputs:
  loc_id  - Identifier for the file containing the reference or
            for any object in that file.
  ref     - Object reference

Outputs:
  name    - A name associated with the referenced object or dataset region.
  hdferr  - Error code
             0 on success and -1 on failure

Optional parameters:
  size    - The size of the name buffer,
            returning 0 (zero) if no name is associated with the identifier



Fortran2003 Interface: h5rget_name_f

Signature:
 SUBROUTINE h5rget_name_f(loc_id, ref_type, ref, name, hdferr, size)
   INTEGER(HID_T)  , INTENT(IN)            :: loc_id 
   INTEGER         , INTENT(IN)            :: ref_type
   TYPE(C_PTR)     , INTENT(IN)            :: ref
   CHARACTER(LEN=*), INTENT(OUT)           :: name
   INTEGER         , INTENT(OUT)           :: hdferr
   INTEGER(SIZE_T) , INTENT(OUT), OPTIONAL :: size

Inputs:
  loc_id   - Identifier for the file containing the reference or
             for any object in that file.
  ref_type - Type of reference.
  ref      - An object or dataset region reference.

Outputs:
  name     - A name associated with the referenced object or dataset ptr.
  hdferr   - Error code
              0 on success and -1 on failure

Optional parameters:
   size    - The size of the name buffer.

Parameters:
hid_t loc_idIN: Identifier for the file containing the reference or for any object in that file
H5R_type_t ref_typeIN: Type of reference
void *refIN: An object or dataset region reference
char *nameOUT: A buffer to place the name of the referenced object or dataset region. If NULL, then this call will return the size in bytes of the name.
size_t sizeIN: The size of the name buffer. When the size is passed in, the NULL terminator needs to be included.

Description:

H5R_GET_NAME retrieves a name for the object identified by ref.

loc_id is used to identify the file containing the reference. It can be the file identifier for the file containing the reference or an identifier for any object in that file.

H5R_type_t is the reference type of ref. Valid values include the following:

H5R_OBJECTObject reference
H5R_DATASET_REGION  Dataset region reference

ref is the reference for which the target object’s name is sought.

If ref is an object reference, name will be returned with a name for the referenced object. If ref is a dataset region reference, name will contain a name for the object containing the referenced region.

Up to size characters of the name are returned in name; additional characters, if any, are not returned to the user application.

If the length of the name, which determines the required value of size, is unknown, a preliminary H5R_GET_NAME call can be made. The return value of this call will be the size of the object name. That value can then be assigned to size for a second H5R_GET_NAME call, which will retrieve the actual name.

If there is no name associated with the object identifier or if the name is NULL, H5R_GET_NAME returns the size of the name buffer (the size does not include the NULL terminator).

Note that an object in an HDF5 file may have multiple paths if there are multiple links pointing to it. This function may return any one of these paths.

Returns:

Returns the length of the name if successful, returning 0 (zero) if no name is associated with the identifier. Otherwise returns a negative value.

Example:

examples / h5_ref2reg.c [132:136]  1.10/master  HDFFV/hdf5
    /*
     * Get name of the dataset the first region reference points to
     * using H5Rget_name
     */
    name_size1 = H5Rget_name(dsetr_id, H5R_DATASET_REGION, &ref_out[0], (char*)buf1, 10);

     PROGRAM COMPOUNDEXAMPLE

     USE HDF5 ! This module contains all necessary modules

     IMPLICIT NONE

     CHARACTER(LEN=11), PARAMETER :: filename = "compound.h5" ! File name
     CHARACTER(LEN=8), PARAMETER :: dsetname = "Compound"     ! Dataset name
     INTEGER, PARAMETER :: dimsize = 6 ! Size of the dataset

     INTEGER(HID_T) :: file_id       ! File identifier

History:
Release    Change
1.8.8Fortran updated to Fortran2003.
1.8.0C function introduced in this release.

--- Last Modified: September 13, 2018 | 12:48 PM