

<!--
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  * Copyright by The HDF Group.                                               *
  * Copyright by the Board of Trustees of the University of Illinois.         *
  * All rights reserved.                                                      *
  *                                                                           *
  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
  * terms governing use, modification, and redistribution, is contained in    *
  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
  * of the source code distribution tree; Copyright.html can be found at the  *
  * root level of an installed copy of the electronic HDF5 document set and   *
  * is linked from the top-level documents page.  It can also be found at     *
  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
  * access to either file, you may request a copy from help@hdfgroup.org.     *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 -->


<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Rcreate" -->
<hr>
<dl>

<dt><div align=right><font color=999999 size=-1><i>
    Last modified: 19 July 2013
    </i></font></div>

<dt><strong>Name:</strong> <a name="Reference-Create">H5Rcreate</a>
<dt><strong>Signature:</strong>
    <dd><em>herr_t</em> <code>H5Rcreate</code>(
        <em>void *</em><code>ref</code>,
        <em>hid_t</em> <code>loc_id</code>,
        <em>const char *</em><code>name</code>,
        <em>H5R_type_t</em> <code>ref_type</code>,
        <em>hid_t</em> <code>space_id</code>
    )

<p>
<dt><strong>Purpose:</strong>
    <dd>Creates a reference.

<p>
<dt><strong>Description:</strong>
    <dd><code>H5Rcreate</code> creates the reference, <code>ref</code>,
        of the type specified in <code>ref_type</code>, pointing to 
        the object <code>name</code> located at <code>loc_id</code>.
        <p>
        The HDF5 library maps the <em>void</em> type specified above 
        for <code>ref</code> to the type specified in <code>ref_type</code>,
        which will be one of those appearing in the first column of
        the following table.  
        The second column of the table lists the HDF5 constant associated 
        with each reference type.
        <dir>
        <table border=0>
        <tr><td><em>hdset_reg_ref_t</em>&nbsp;&nbsp;</td>
            <td><code>H5R_DATASET_REGION</code>&nbsp;&nbsp;</td>
            <td>Dataset region reference</td></tr>
        <tr><td><em>hobj_ref_t</em></td>
            <td><code>H5R_OBJECT</code></td>
            <td>Object reference</td></tr>
        </table>
        </dir>
        <p>
        The parameters <code>loc_id</code> and <code>name</code> are 
        used to locate the object.
        <p>
        The parameter <code>space_id</code> identifies the dataset region 
        that a dataset region reference points to.
        This parameter is used only with dataset region references
        and should be set to <code>-1</code> if the reference is an
        object reference, <code>H5R_OBJECT</code>.

<p>
<dt><strong>Warning:</strong>
    <dd>Neither an object reference nor a dataset region reference may
        refer to an object that must be accessed through an external link.
        <p>
        More specifically, references can refer to objects only within
        the current logical HDF5 file while external links typically 
        point to an object in a different logical HDF5 file.
        Therefore, neither an HDF5 object reference nor 
        an HDF5 dataset region reference 
        may refer to an object or to a region in any dataset, 
        respectively, that is accessed by means of an external link.

<p>
<dt><strong>Parameters:</strong>
    <dd><table>
        <tr>
            <td valign="top"><em>void *</em><code>ref</code></td>
            <td valign="top">OUT: Reference created by the function 
                call.</td></tr>
        <tr>
            <td valign="top"><em>hid_t</em> <code>loc_id</code></td>
            <td valign="top">IN: Location identifier used to locate the 
                 object being pointed to.</td></tr>
        <tr>
            <td valign="top"><em>const char *</em><code>name</code></td>
            <td valign="top">IN: Name of object at location 
                <code>loc_id</code>.</td></tr>
        <tr>
            <td valign="top"><em>H5R_type_t</em>&nbsp;<code>ref_type&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
            <td valign="top">IN: Type of reference.</td></tr>
        <tr>
            <td valign="top"><em>hid_t</em> <code>space_id</code></td>
            <td valign="top">IN: Dataspace identifier with selection. 
                Used only for dataset region references; 
                pass as <code>-1</code> if reference is an object reference,
                i.e., of type <code>H5R_OBJECT</code>.</td></tr>
    </table></dd>

<p>
<dt><strong>Returns:</strong>
    <dd>Returns a non-negative value if successful;
        otherwise returns a negative value.

<!-- NEW PAGE -->
<p>
<dt><strong>Fortran90 Interface:</strong> h5rcreate_f

    <dd>
    <p><strong>To create an object reference:</strong> 
    <br>

        <?php include("H5R/h5rcreate_object_f_F90.htm"); ?>

        </dt>

    <p>&nbsp;
    <p>
    <strong>To create a region reference:</strong>  
    <br>

        <?php include("H5R/h5rcreate_region_f_F90.htm"); ?>


<!-- NEW PAGE -->
<p>
<dt><strong>Fortran2003 Interface:</strong> h5rcreate_f
    <dd>

        <?php include("H5R/h5rcreate_f_F03.htm"); ?>

<p>
<dt><strong>History:</strong>
    <dd><table width="90%">
        <tr>
          <td valign="top" align="left" width="10%">
            <strong>Release</strong>&nbsp;&nbsp;&nbsp;&nbsp;</td>
          <td valign="top" align="left">
            <strong>Change</strong></td></tr>
        <tr>
          <td valign="top">1.8.8</td>
          <td valign="top">
            Fortran updated to Fortran2003.</td></tr>
        <tr>
          <td valign="top">1.8.0</td>
          <td valign="top">
            C function introduced in this release.</td></tr>
    </table>

</dl>

