From ed5859ad80ac770b7066c6305458d03e901683b2 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Thu, 29 Oct 1998 17:35:48 -0500 Subject: [svn-r831] DDL.html References.html New User Guide documents. RM_H5I.html Identifier Interface RM_H5R.html Reference Interface Created these two sections of Reference Manual. --- doc/html/DDL.html | 208 ++++++++++++++++++ doc/html/RM_H5I.html | 136 ++++++++++++ doc/html/RM_H5R.html | 213 ++++++++++++++++++ doc/html/References.html | 558 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 1115 insertions(+) create mode 100644 doc/html/DDL.html create mode 100644 doc/html/RM_H5I.html create mode 100644 doc/html/RM_H5R.html create mode 100644 doc/html/References.html diff --git a/doc/html/DDL.html b/doc/html/DDL.html new file mode 100644 index 0000000..fcce13e --- /dev/null +++ b/doc/html/DDL.html @@ -0,0 +1,208 @@ + + + + DDL for HDF5 + + + +

DDL in BNF for HDF5

+ + +

1. Introduction

+ +This document contains the data description language (DDL) for an HDF5 file. +The description is in Backus-Naur Form. + +

2. Explanation of Symbols

+ +This section contains a brief explanation of the symbols used in the DDL. + +

+    ::=                      defined as
+    <tname>                  a token with the name tname
+    <a> | <b>                one of <a> or <b>
+    <a>opt                    zero or one occurrence of <a>
+    <a>*                     zero or more occurrence of <a>
+    <a>+                     one or more occurrence of <a>
+    TBD                      To Be Decided
+

+ +

3. The DDL

+ + +

+<file> ::= HDF5 "<file_name>" { <file_boot_block>opt <root_group> }
+
+<file_name> ::= <identifier>
+
+<file_boot_block> ::= BOOT_BLOCK { <boot_block_content> }
+
+<boot_block_content> ::= TBD
+
+<root_group> ::= GROUP "/" { <unamed_datatype>* <group_attribute>* <group_member>* }  
+
+<unamed_datatype> ::= DATATYPE "<unamed_type_name>" { <compound_type_def>+ }
+
+<unamed_type_name> ::= the assigned name for unamed type is in the form of 
+                      #oid1:oid2, where oid1 and oid2 are the object ids of the type
+
+<compound_type_def> ::=  <named_scalar_type> | <named_array_type>
+
+<named_scalar_type> ::= <scalar_type> <field_name> ;
+
+<scalar_type> ::= H5T_STD_I8BE | H5T_STD_I8LE | ...
+
+<field_name> ::= <identifier>
+
+<named_array_type> ::= <scalar_type> <field_name> <dim_sizes> ;
+
+<dim_sizes> ::= dimension sizes in the form of [dimsize1][dimzise2]..., 
+                where dimsize1, dimsize2 are integers
+
+<group_attribute> ::= <attribute> 
+
+<attribute> ::= ATTRIBUTE "<attr_name>" { <datatype>    
+                                          <dataspace>   
+                                          <data>opt  } 
+// <datatype> and <dataspace> must appear before <data>.
+
+<attr_name> ::=  <identifier>
+
+<datatype> ::= DATATYPE { <named_type> } |        
+               DATATYPE { "<scalar_type>" }  |         
+               DATATYPE { <compound_type_def>+ }
+
+<named_type> ::= <hardlink>
+
+<hardlink> ::= HARDLINK { "<abs_name>" }  
+
+<abs_name> ::= object absolute name
+
+<dataspace> ::= DATASPACE { "<dataspace_name>" } |
+                DATASPACE { ARRAY <current_dims> <max_dims> } | 
+                DATASPACE { OTHER <ds_definition>+ } 
+
+<dataspace_name> ::= <identifier>
+
+<current_dims> ::= a list of integers in the form of (i1, i2, ... ),
+                   where ik is an integer, k = 1,2,...
+
+<max_dims> ::= (i1, i2, ... ) where ik is an integer or H5S_UNLIMITED
+
+<ds_definition> ::= TBD
+
+<data> ::= data {TBD}
+
+<group_member> ::= <named_datatype> | <named_dataspace> | <group> | <dataset> | 
+                   <softlink>
+
+<named_datatype> ::= DATATYPE "<type_name>" { <compound_type_def>+ }
+
+<type_name> ::= "<identifier>"
+
+<named_dataspace> ::= DATASPACE "<dataspace_name>" { ARRAY <current_dims> <max_dims> } |
+                      DATASPACE "<dataspace_name>" { OTHER <ds_definition>+ }
+
+<group> ::= GROUP "<group_name>" { <hardlink> } |
+            GROUP "<group_name>" { <group_attribute>* <group_member>* } 
+            
+<group_name> ::= <identifier>
+
+<dataset> ::= DATASET "<dataset_name>" { <hardlink> } |
+              DATASET "<dataset_name>" { <datatype>  
+                                         <dataspace> 
+                                         <storagelayout>opt
+                                         <compression>opt
+                                         <dataset_attribute>*
+                                         <data>opt  } 
+// Tokens within {} can be in any order  as long as <data> and <dataset_attribute>
+// are after <datatype> and <dataspace>.
+
+<dataset_name> ::= <identifier>
+
+<storagelayout> :: = STORAGELAYOUT <contiguous_layout>  |  
+                     STORAGELAYOUT <chunked_layout>  | 
+                     STORAGELAYOUT <compact_layout>  | 
+                     STORAGELAYOUT <external_layout> 
+
+<contiguous_layout> ::= {CONTIGUOUS}    // default
+
+<chunked_layout> ::=  {CHUNKED <dims> }
+
+<dims> ::= (i1, i2, ... ), ik is an integer, k = 1,2,... 
+
+<compact_layout> ::= TBD           
+
+<external_layout> ::= {EXTERNAL <external_file>+ }
+
+<external_file> ::= (<file_name> <offset> <size>) 
+
+<offset> ::= an integer
+
+<size> ::= an integer
+
+<compression> :: = COMPRESSION { TBD }  
+
+<dataset_attribute> ::= <attribute> 
+
+<softlink> ::= SOFTLINK "<softlink_name>" { LINKTARGET "<target>" }
+
+<softlink_name> ::= <identifier>
+
+<target> ::= <identifier>
+
+<identifier> ::= string   
+// character '/' should be used with care. 
+
+

+ + + +

4. An Example of an HDF5 File in DDL

+ + +

+HDF5 "example.h5" {
+GROUP "/" {
+   DATASET "dset1" {
+      DATATYPE {
+         H5T_STD_I32BE int_name;
+         H5T_IEEE_F32BE float_name;
+         H5T_IEEE_F64BE double_name;
+      }
+      DATASPACE { ARRAY ( 5 ) ( 5 ) }
+      DATA {{0,0,1}, {1,1,0.5}, {2,4,0.333333}, {3,9,0.25}, {4,16,0.2}}
+   }
+   GROUP "group1" {
+      DATASET "dset2" {
+         DATATYPE {
+            HARDLINK { "/type1" }
+         }
+         DATASPACE { ARRAY ( 5 ) ( 5 ) }
+         DATA {{0,0}, {1,1.1}, {2,2.2}, {3,3.3}, {4,4.4}}
+      }
+   }
+   GROUP "group2" {
+      HARDLINK { "/group1" }
+   }
+   SOFTLINK "slink1" {
+      LINKTARGET "somevalue"
+   }
+   DATATYPE "type1" {
+      H5T_STD_I32BE int_name;
+      H5T_IEEE_F32BE float_name;
+   }
+}
+}
+

+ + +

+HDF Help Desk +

+ +Last modified: 28 October 1998 + + + diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html new file mode 100644 index 0000000..298eaea --- /dev/null +++ b/doc/html/RM_H5I.html @@ -0,0 +1,136 @@ + + +HDF5/H5I Draft API Specification + + + + +

+ +HDF5 Reference Manual +H5 +H5A +H5D +H5E +H5F +H5G +H5I +H5P +H5R +H5RA +H5S +H5T +H5Z +Tools + + +

+ + +

H5I: Identifier Interface

+ + +

Identifier API Functions

+ +This function provides a tool for working with object identifiers. +

+ + + +
+
+
H5Iget_type +
+ +
+ +
+ +
+ +
+
+ + +

Name: H5Iget_type +

Signature: +

H5I_type_t H5Iget_type(hid_t obj_id) +

Purpose: +

Retrieves the type of an object. +

Description: +

H5Iget_type retrieves the type of the object + identified by obj_id. +

+ Valid types returned by the function are + + + + + + + +
    H5I_FILE + File
    H5I_GROUP + Group
    H5I_DATATYPE + Datatype
    H5I_DATASPACE + Dataspace
    H5I_DATASET + Dataset
    H5I_ATTR + Attribute
+ If no valid type can be determined or the identifier + submitted is invalid, the function returns + + +
    H5I_BADID + Invalid identifier
+

+ This function is of particular value in determining the + type of object closing function (H5Dclose, + H5Gclose, etc.) to call after a call to + H5Rdereference. +

Parameters: +
+
hid_t obj_id +
IN: Object identifier whose type is to be determined. +
+

Returns: +

Returns the object type if successful; + otherwise H5I_BADID. +

+ + +

+ + +HDF5 Reference Manual +H5 +H5A +H5D +H5E +H5F +H5G +H5I +H5P +H5R +H5RA +H5S +H5T +H5Z +Tools + + +

+ +

+HDF Help Desk + +
+Last modified: 27 October 1998 + + + diff --git a/doc/html/RM_H5R.html b/doc/html/RM_H5R.html new file mode 100644 index 0000000..5af6fad --- /dev/null +++ b/doc/html/RM_H5R.html @@ -0,0 +1,213 @@ + + +HDF5/H5R Draft API Specification + + + + +

+ +HDF5 Reference Manual +H5 +H5A +H5D +H5E +H5F +H5G +H5I +H5P +H5R +H5RA +H5S +H5T +H5Z +Tools + + +

+ + +

H5R: Reference Interface

+ + +

Reference API Functions

+ +The Reference interface allows the user to create references +to specific objects and data regions in an HDF5 file. +

+ + + + +
+
+
H5Rcreate +
+ +
+
H5Rdereference +
+ +
+
H5Rget_region (NYI) +
+
+NYI = Not yet implemented. +
+ +

+Note: The only type of reference implemented in this release +is an object reference pointing to a dataset. +

+ +

Name: H5Rcreate +

Signature: +

herr_t H5Rcreate(href_t *ref, + hid_t loc_id, + const char *name, + H5R_type_t ref_type, + hid_t space_id + ) +

Purpose: +

Creates a reference. +

Description: +

H5Rcreate creates the reference, ref, + of the type specified in ref_type, pointing to + the object name located at loc_id. +

+ The parameters loc_id and name are + used to locate the object. +

+ The parameter space_id identifies the region + to be pointed to (for dataset region references). +

+ Note: Only object references of type H5T_STD_REF_OBJ + pointing to entire datasets are implemented at this time. +

Parameters: +
+
href_t *ref +
OUT: Reference created by the function call. +
hid_t loc_id +
IN: Location identifier used to locate the object being + pointed to. +
const char *name +
IN: Name of object at location loc_id. +
H5R_type_t ref_type +
IN: Type of reference. +
hid_t space_id +
IN: Dataspace identifier with selection. + Used for dataset region references. +
+

Returns: +

Returns a non-negative value if successful; + otherwise returns a negative value. +

+ + +

Name: H5Rdereference +
Signature: +: hid_t H5Rdereference(hid_t dataset, + H5R_type_t ref_type, + href_t *ref + ) +
Purpose: +: Opens the HDF5 object referenced. +
Description: +: Given a reference to some object, H5Rdereference + opens that object and returns an identifier. +
+ The parameter ref_type specifies the reference type + of ref. See + Reference Types in + References (H5R) + for a list of valid reference types. +
Parameters: +
+
hid_t dataset +
IN: Dataset containing reference object. +
H5R_type_t ref_type +
IN: The reference type of ref. +
void *ref +
IN: Reference to open. +
+
Returns: +: Returns valid identifier if successful; + otherwise returns a negative value. +

+ + +

Name: H5Rget_region + (Not yet implemented.) +
Signature: +: hid_t H5Rget_region(hid_t dataset, + H5R_type_t ref_type, + href_t *ref + ) +
Purpose: +: Retrieves a dataspace with the specified region selected. +
Description: +: Given a reference to an object ref, + H5Rget_region creates a copy of the dataspace + of the dataset pointed to and defines a selection in the copy + which is the region pointed to. +
+ The parameter ref_type specifies the reference type + of ref. See + Reference Types in + References (H5R) + for a list of valid reference types. +
Parameters: +
+
hid_t dataset, +
IN: Dataset containing reference object. +
H5R_type_t ref_type, +
IN: The reference type of ref. +
href_t *ref +
IN: Reference to open. +
+
Returns: +: Returns a valid identifier if successful; + otherwise returns a negative value. +

+ + +

+ + +HDF5 Reference Manual +H5 +H5A +H5D +H5E +H5F +H5G +H5I +H5P +H5R +H5RA +H5S +H5T +H5Z +Tools + + +

+ +

+HDF Help Desk + +
+Last modified: 27 October 1998 + + + diff --git a/doc/html/References.html b/doc/html/References.html new file mode 100644 index 0000000..88534e5 --- /dev/null +++ b/doc/html/References.html @@ -0,0 +1,558 @@ + + + +References + + + +

References

+ +

1. Introduction

+ +This document discusses the kinds of references implemented +(and planned) in HDF5 and the functions implemented (and planned) +to support them. + + +

2. References

+ +This section contains an overview of the kinds of references +implemented, or planned for implementation, in HDF5. + +

+ +

Object reference +

Reference to an entire object in the current HDF5 file. +
+ The only kind of reference currently implemented. +

+ An object reference points to an entire object in the + current HDF5 file by storing the relative file address + (OID) of the object header for the object pointed to. + The relative file address of an object header is + constant for the life of the object. + An object reference is of a fixed size in the file. +

Dataset region reference +

Reference to a specific dataset region. +
+ Not yet implemented. +

+ A dataset region reference points to a region of a + dataset in the current HDF5 file by storing the OID + of the dataset and the global heap offset of the + region referenced. The region referenced is located + by retrieving the coordinates of the areas in the + region from the global heap. A dataset region + reference is of a variable size in the file. +

Internal dataset region reference +

Reference to a region within the current dataset. +
+ Not yet implemented. +

+ An internal dataset region reference points to a + region of the current dataset by storing the + coordinates of the region. An internal dataset + region reference is of a fixed size in the file. +

+ + +Note: All references are treated as soft links for the +purposes of reference counting. The library does not keep track of +reference links and they may dangle if the object they refer to +is deleted, moved, or not yet available. + + +

3. Reference Types

+ +This section lists valid HDF5 reference types for use in the +H5R functions. + + + + + + + + + + + + + + + + +

Reference Type	Value	Description
`H5R_BADTYPE`	`-1`	Invalid reference type
`H5R_OBJECT`	`0`	Object reference
`H5R_DATASET_REGION`	`1`	Dataset region reference
`H5R_INTERNAL`	`2`	Internal reference

+ + + +

4. Functions

+ +Four functions, three in the H5R interface and one in the +H5I interface, have been implemented to support references. +The H5I function is also useful outside the context of references. +

herr_t H5Rcreate(href_t *reference, + hid_t loc_id, + const char *name, + H5R_type_t type, + hid_t space_id) +

H5Rcreate creates an object which is a + particular type of reference (specified with the + type parameter) to some file object and/or + location specified with the space_id parameter. + For dataset region references, the selection specified + in the dataspace is the portion of the dataset which + will be referred to. +

+ Currently only object references which point to + entire datasets can be created. +

+ +

hid_t H5Rdereference(hid_t dset, + H5R_type_t rtype, + href_t *ref) +

H5Rdereference opens the object referenced + and returns an identifier for that object. + The parameter ref specifies a reference of + type rtype that is stored in the dataset + dset. +

+ +

hid_t H5Rget_region(hid_t dataset, + H5R_type_t type, + href_t *reference) +

H5Rget_region creates a copy of dataspace of + the dataset that is pointed to and defines a selection in + the copy which is the location (or region) pointed to. + The parameter ref specifies a reference of + type rtype that is stored in the dataset + dset. +

+ This function is not yet implemented. +

+ +

H5I_type_t H5Iget_type(hid_t id) +

Returns the type of object referred to by the + identifier id. Valid return values appear + in the following list: + + + + + + + + + + + + + + + + +

`H5I_BADID`	Invalid ID
`H5I_FILE`	File objects
`H5I_GROUP`	Group objects
`H5I_DATATYPE`	Data type objects
`H5I_DATASPACE`	Dataspace objects
`H5I_DATASET`	Dataset objects
`H5I_ATTR`	Attribute objects

+ +

+ This function was inspired by the need of users to figure + out which type of object closing function + (H5Dclose, H5Gclose, etc.) + to call after a call to H5Ddereference, + but it is also of general use. +

+ + + +

5. Examples

+ +Object Reference Writing Example +
+Create a dataset which has links to other datasets as part +of its raw data and write the dataset to the file. +

+ +

+{
+    hid_t file1;
+    hid_t dataset1;
+    hid_t datatype, dataspace;
+    char buf[128];
+    href_t link;
+    href_t data[10][10];
+    int rank;
+    size_t dimsf[2];
+    int i, j;
+
+    /* Open the file */
+    file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+    /* Describe the size of the array and create the data space */
+    rank=2;
+    dimsf[0] = 10;
+    dimsf[1] = 10;
+    dataspace = H5Screate_simple(rank, dimsf, NULL); 
+
+    /* Define datatype */
+    datatype = H5Tcopy(H5T_STD_REF_OBJ);
+
+    /* Create a dataset */
+    dataset1=H5Dcreate(file1,"Dataset One",datatype,dataspace,H5P_DEFAULT);
+
+    /* Construct array of OIDs for other datasets in the file */
+    /* somewhat hokey and artificial, but demonstrates the point */
+    for(i=0; i<10; i++)
+        for(j=0; j<10; i++)
+          {
+            sprintf(buf,"/Group/Linked Set %d-%d",i,j);
+            if(H5Rcreate(&link,file1,buf,H5R_REF_OBJ,-1)>0)
+                data[i][j]=link;
+          } /* end for */
+
+    /* Write the data to the dataset using default transfer properties.  */
+    H5Dwrite(dataset, H5T_POINTER_OBJECT, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+    /* Close everything */
+    H5Sclose(dataspace);
+    H5Tclose(datatype);
+    H5Dclose(dataset1);
+    H5Fclose(file1);
+}
+

+ + +Object Reference Reading Example +
+Open a dataset which has links to other datasets as part of +its raw data and read in those links. +

+ +

+{
+    hid_t file1;
+    hid_t dataset1, tmp_dset;
+    href_t data[10][10];
+    int i, j;
+
+    /* Open the file */
+    file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+    /* Open the dataset */
+    dataset1=H5Dopen(file1,"Dataset One",H5P_DEFAULT);
+
+    /* 
+     * Read the data to the dataset using default transfer properties.
+     * (we are assuming the dataset is the same and not querying the
+     *  dimensions, etc.)
+     */
+    H5Dread(dataset, H5T_STD_REF_OBJ, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+    /* Analyze array of OIDs of linked datasets in the file */
+    /* somewhat hokey and artificial, but demonstrates the point */
+    for(i=0; i<10; i++)
+        for(j=0; j<10; i++)
+          {
+            if((tmp_dset=H5Rdereference(dataset, H5T_STD_REF_OBJ, data[i][j]))>0)
+              {
+                  
+              } /* end if */
+            H5Dclose(tmp_dset);
+          } /* end for */
+
+
+    /* Close everything */
+    H5Dclose(dataset1);
+    H5Fclose(file1);
+}
+

+ + +Dataset Region Reference Writing Example +
+Create a dataset which has links to other dataset regions +(single elements in this case) as part of its raw data and +write the dataset to the file. +

+ +

+{
+    hid_t file1;
+    hid_t dataset1, dataset2;
+    hid_t datatype, dataspace1, dataspace2;
+    char buf[128];
+    href_t link;
+    href_t data[10][10];     /* HDF5 reference type */
+    int rank;
+    size_t dimsf[2];
+    hssize_t start[3],count[3];
+    int i, j;
+
+    /* Open the file */
+    file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+    /* Describe the size of the array and create the data space */
+    rank=2;
+    dimsf[0] = 10;
+    dimsf[1] = 10;
+    dataspace1 = H5Screate_simple(rank, dimsf, NULL); 
+
+    /* Define Dataset Region Reference datatype */
+    datatype = H5Tcopy(H5T_STD_REF_DATAREG);
+
+    /* Create a dataset */
+    dataset1=H5Dcreate(file1,"Dataset One",datatype,dataspace1,H5P_DEFAULT);
+
+    /* Construct array of OIDs for other datasets in the file */
+    /* (somewhat artificial, but demonstrates the point) */
+    for(i=0; i<10; i++)
+        for(j=0; j<10; i++)
+          {
+            sprintf(buf,"/Group/Linked Set %d-%d",i,j);
+            
+            /* Get the dataspace for the object to point to */
+            dataset2=H5Dopen(file1,buf,H5P_DEFAULT);
+            dataspace2=H5Dget_space(dataspace2);
+
+            /* Select the region to point to */
+            /* (could be different region for each pointer) */
+            start[0]=5; start[1]=4; start[2]=3;
+            count[0]=2; count[1]=4; count[2]=1;
+            H5Sselect_hyperslab(dataspace2,H5S_SELECT_SET,start,NULL,count,NULL);
+
+            if(H5Rcreate(&link,file1,buf,H5R_REF_DATAREG,dataspace2)>0)
+                /* Store the reference */
+                data[i][j]=link;
+
+            H5Sclose(dataspace2);
+            H5Dclose(dataspace2);
+          } /* end for */
+
+    /* Write the data to the dataset using default transfer properties.  */
+    H5Dwrite(dataset, H5T_STD_REF_DATAREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+    /* Close everything */
+    H5Sclose(dataspace);
+    H5Tclose(datatype);
+    H5Dclose(dataset1);
+    H5Fclose(file1);
+}
+

+ + +Dataset Region Reference Reading Example +
+Open a dataset which has links to other datasets regions +(single elements in this case) as part of its raw data and +read in those links. +

+ +

+{
+    hid_t file1;
+    hid_t dataset1, tmp_dset;
+    hid_t dataspace;
+    href_t data[10][10];     /* HDF5 reference type */
+    int i, j;
+
+    /* Open the file */
+    file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+
+    /* Open the dataset */
+    dataset1=H5Dopen(file1,"Dataset One",H5P_DEFAULT);
+
+    /* 
+     * Read the data to the dataset using default transfer properties.
+     * (we are assuming the dataset is the same and not querying the
+     *  dimensions, etc.)
+     */
+    H5Dread(dataset, H5T_STD_REF_DATAREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+
+    /* Analyze array of OIDs of linked datasets in the file */
+    /* (somewhat artificial, but demonstrates the point) */
+    for(i=0; i<10; i++)
+        for(j=0; j<10; i++)
+          {
+            if((tmp_dset=H5Rdereference(dataset, H5D_STD_REF_DATAREG,data[i][j]))>0)
+              {
+                  /* Get the dataspace with the pointed to region selected */
+                  dataspace=H5Rget_space(data[i][j]);
+
+                  
+
+                  H5Sclose(dataspace);
+              } /* end if */
+            H5Dclose(tmp_dset);
+          } /* end for */
+
+
+    /* Close everything */
+    H5Dclose(dataset1);
+    H5Fclose(file1);
+}
+

+ + + +

+HDF Help Desk +

+ +Last modified: 28 October 1998 + + +

Material to Be Omitted!!!

+ +Additional material above will also need to be deleted or +commented out. +

+ +

"Kinds of Reference" Information

+ +

Dataset Offset Reference +: Reference to a specific byte sequence in a dataset (3) +
Disk Offset Reference +: Reference to a specific byte sequence in a file (3) +
External Object Reference +: Reference to an entire object in another HDF5 file (3) +
External Dataset Region Reference +: Reference an a specific dataset region in another HDF5 file (3) +
External Dataset Offset Reference +: Reference to a specific byte sequence in a dataset in + another HDF5 file (3) +
External Disk Offset Reference +: Reference to a specific byte sequence in another HDF5 file (3) +
Generic Reference +: A reference which may be any of the types defined above. (3) +

+ +Notes: +

1 - Planned for in final release. +
2 - Most useful reference types to tackle next +
3 - Optional reference types. +

+ +

Comments

+    Reference types are atomic types and may be included as fields in compound
+        data types.
+
+    There are (at least) three levels of reference strength:
+        Weak - We allow the user to store any type of reference in an array
+            of references.  (u.e., the array of references in the example above
+            could be a mix of Object, Dataset Region and Internal references)
+        Medium - We force the user to stick with a particular type of
+            reference within a dataset, but the datasets pointed to (with
+            Object and Dataset Region references) may be of any data type
+            or dataspace.
+        Strong - We force the user to stick with a particular type of
+            reference and Object and Dataset Region references must point to
+            datasets with the same data type.
+        Extra Strong - We force the user to stick with a particular type of
+            reference and Object and Dataset Region references must point to
+            datasets with the same data type _and_ dataspace.
+
+    The library is currently implemented with "medium" strength references.
+

+ + +

Reference Type

+ + + + + + +

H5R_MAXTYPE 3 Highest type in group (invalid as true type)

+ + + +

Information Regarding Specific Kinds of References

+ +

Dataset Offset Reference +: Points to a sequence of bytes within a dataset in + the current HDF5 file by storing the OID of the dataset and the byte + length and offset of the sequence within the dataset. The offset is + the logical byte offset within the dataset, meaning that the data is + de-compressed before returning the sequence of bytes requested. No + interpretation of the data at that location is provided. However, + if the dataset is extendible and the size of the dimensions are changed, + the element(s) that the sequence is located within may vary. Fixed size + in file. + +
Disk Offset Reference +: Points to a sequence of bytes in the current + HDF5 file by storing the byte length and offset of the sequence within + the file, relative to the boot-block (as are all the other high-level + addresses used in the file). The offset is the absolute byte offset + within the file, no interpretation of the data at that location is + provided. Fixed size in file. + +
External Object Reference +: Points to an entire object in another HDF5 file by + storing a global heap offset which points to the URL of the external + file and the OID of the object pointed to. Variable size in file. + +
External Dataset Region Reference +: Points to a region of a dataset in + another HDF5 file by storing a global heap offset which points to the + URL of the external file, OID of the dataset and the coordinates of the + region. Variable size in file. + +
External Dataset Offset Reference +: Points to a sequence of bytes within a + dataset in another HDF5 file by storing a global heap offset which + points to the URL of the external file, the OID of the dataset and the + byte length and offset of the sequence within the dataset. The offset + is the logical byte offset within the dataset, meaning that the data is + de-compressed before returning the sequence of bytes requested. + However, if the dataset is not stored contiguously and the size of the + dimensions are changed, the element(s) that the sequence is located + within may vary. Variable size in file. + +
External Disk Offset Reference +: Points to a sequence of bytes in another + HDF5 file by storing a global heap reference which points to the URL + of the external file and the byte length and offset of the sequence + within the file. The offset is the absolute byte offset within the + file, no interpretation of the data at that location is provided. + Variable size in file. + +
Generic Reference +: A reference which may contain any of the other + references defined above. (Mostly useful for implementing "weak" + strength pointers within the medium strength model we are using) + Variable size in file. + +

+ +

Implementation Details

+ +

File Storage +: In order to efficiently index an array, each element must be the + same size when stored in the dataset on disk. Fixed-sized references + will be stored directly in the dataset array on disk; variable-sized + references will have a fixed-size head offset stored in the array on + disk with a file heap used to store the actual variable-sized + information stored in the heap. + +
Memory Storage +: Each href_t object in memory is a struct containing + a pointer type and union of information required for each + pointer type. + Information in this structure is not designed for users to view. + Non-C APIs may have to mangle this structure in some way, in order + to provide users with access to references in a language-appropriate + way. +

+ + -- cgit v0.12

`H5I_FILE` +	File
`H5I_GROUP` +	Group
`H5I_DATATYPE` +	Datatype
`H5I_DATASPACE` +	Dataspace
`H5I_DATASET` +	Dataset
`H5I_ATTR` +	Attribute

+ + H5Rcreate + +		+ + H5Rdereference + +		+ + H5Rget_region (NYI) + +
+NYI = Not yet implemented. +