1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.10.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: HDF5 Java API Package</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="hdf5doxy.css" rel="stylesheet" type="text/css">
<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/>
-->
<script type="text/javascript" src="hdf5_navtree_hacks.js"></script>
</head>
<body>
<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a>
 <span id="projectnumber">1.15.0.2908dd1</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('_h_d_f5_l_i_b.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">HDF5 Java API Package</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This class is the Java interface for the HDF5 library. </p>
<p>This code is the called by Java programs to access the entry points of the HDF5 library. Each routine wraps a single HDF5 entry point, generally with the arguments and return codes analogous to the C interface. </p>
<p>For details of the HDF5 library, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_r_m.html">HDF5 Reference Manual</a> <hr />
</dd></dl>
<p><b>Mapping of arguments for Java</b></p>
<p>In general, arguments to the HDF Java API are straightforward translations from the 'C' API described in the <a class="el" href="_r_m.html">HDF5 Reference Manual</a>.</p>
<table border="1">
<caption><b>HDF5 C types to Java types</b> </caption>
<tr>
<td><b>HDF5</b> </td><td><b>Java</b> </td></tr>
<tr>
<td><a class="el" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a> </td><td>int, Integer </td></tr>
<tr>
<td><a class="el" href="group___p_d_t_n_a_t.html#gae0625357fa121eca117f7fa9c4701810">H5T_NATIVE_SHORT</a> </td><td>short, Short </td></tr>
<tr>
<td><a class="el" href="group___p_d_t_n_a_t.html#gae2523b63144b498f555fa4d04f59ee1c">H5T_NATIVE_FLOAT</a> </td><td>float, Float </td></tr>
<tr>
<td><a class="el" href="group___p_d_t_n_a_t.html#ga087f3b793a299e416bd68678c2ef7c09">H5T_NATIVE_DOUBLE</a> </td><td>double, Double </td></tr>
<tr>
<td><a class="el" href="group___p_d_t_n_a_t.html#ga7439560bc4ef6d995a4e35b30262e660">H5T_NATIVE_CHAR</a> </td><td>byte, Byte </td></tr>
<tr>
<td><a class="el" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a> </td><td>java.lang.String </td></tr>
<tr>
<td>void * <br />
(i.e., pointer to ‘Any’) </td><td>Special – see <a class="el" href="_h_d_f_a_r_r_a_y.html">Java Array Conversion</a> </td></tr>
</table>
<p><b>General Rules for Passing Arguments and Results</b> </p>
<p>In general, arguments passed <b>IN</b> to Java are the analogous basic types, as above. The exception is for arrays, which are discussed below. </p>
<p>The <em>return value</em> of Java methods is also the analogous type, as above. A major exception to that rule is that all HDF Java functions will raise an exception upon failure in the Java version, rather than just return <em>int</em> as in the C. Functions that return a value are declared equivalent to the C function. However, in most cases the Java method will raise an exception instead of returning an error code. </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_e_r_r_o_r_s.html">Errors and Exceptions</a>. </dd></dl>
<p>Java does not support pass by reference of arguments, so arguments that are returned through <b>OUT</b> parameters must be wrapped in an object or array. The Java API for HDF consistently wraps arguments in arrays. Where possible the Java function may return the OUT parameter as an object or basic type. </p>
<p>For instance, a function that returns two integers declared as:</p>
<pre>
h_err_t HDF5dummy( int *a1, int *a2)
</pre><p>For the Java interface, this would be declared:</p>
<pre>
public synchronized static native int HDF5dummy(int args[]);
</pre><p> OR </p><pre>
public synchronized static native int[] HDF5dummy();
</pre><p>where <em>a1</em> is <em>args[0]</em> and <em>a2</em> is <em>args[1]</em>, and would be invoked:</p>
<pre>
H5.HDF5dummy(a);
</pre><p> OR </p><pre>
a = H5.HDF5dummy();
</pre><p>All the routines where this convention is used will have specific documentation of the details, given below. </p>
<p><b><a class="el" href="_h_d_f_a_r_r_a_y.html">Java Array Conversion</a></b> </p>
<p>HDF5 needs to read and write multi-dimensional arrays of any number type (and records). The HDF5 API describes the layout of the source and destination, and the data for the array passed as a block of bytes, for instance,</p>
<div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c">H5Dread</a>(<span class="keywordtype">long</span> fid, <span class="keywordtype">long</span> filetype, <span class="keywordtype">long</span> memtype, <span class="keywordtype">long</span> memspace, <span class="keywordtype">void</span> *data);</div>
<div class="ttc" id="a_h5public_8h_html_a3b079ecf932a5c599499cf7e298af160"><div class="ttname"><a href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a></div><div class="ttdeci">int herr_t</div><div class="ttdef"><b>Definition</b> H5public.h:235</div></div>
<div class="ttc" id="agroup___h5_d_html_ga8287d5a7be7b8e55ffeff68f7d26811c"><div class="ttname"><a href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c">H5Dread</a></div><div class="ttdeci">herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf)</div><div class="ttdoc">Reads raw data from a dataset into a provided buffer.</div></div>
</div><!-- fragment --><p>where <code>void *'' means that the data may be any valid numeric type, and is a contiguous block of bytes that is the data for a multi-dimensional array. The other parameters describe the dimensions, rank, and datatype of the array ondisk (source) and in memory (destination). <p> For Java, this</code>ANY'' is a problem, as the type of data must always be declared. Furthermore, multidimensional arrays are definitely <em>not</em> laid out contiguously in memory. It would be infeasible to declare a separate routine for every combination of number type and dimensionality. For that reason, the <a class="el" href="_h_d_f_a_r_r_a_y.html">Java Array Conversion</a> <b><a class="el" href="classhdf_1_1hdf5lib_1_1_h_d_f_array.html">HDFArray</a></b> class is used to discover the type, shape, and size of the data array at run time, and to convert to and from a contiguous array of bytes in synchronized static native C order. </p>
<p>The upshot is that any Java array of numbers (either primitive or sub-classes of type <b>Number</b>) can be passed as an `‘Object’', and the Java API will translate to and from the appropriate packed array of bytes needed by the C library. So the function above would be declared:</p>
<div class="fragment"><div class="line"><span class="keyword">public</span> <span class="keyword">synchronized</span> <span class="keyword">static</span> <span class="keywordtype">int</span> <a class="code hl_function" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c">H5Dread</a>(<span class="keywordtype">long</span> dataset_id, <span class="keywordtype">long</span> mem_type_id, <span class="keywordtype">long</span> mem_space_id,</div>
<div class="line"> <span class="keywordtype">long</span> file_space_id, <span class="keywordtype">long</span> xfer_plist_id, Object obj,</div>
<div class="line"> <span class="keywordtype">boolean</span> isCriticalPinning)</div>
<div class="line"> <span class="keywordflow">throws</span> HDF5Exception, HDF5LibraryException, NullPointerException;</div>
</div><!-- fragment --><p>and the parameter <em>data</em> can be any multi-dimensional array of numbers, such as float[][], or int[][][], or Double[][]. </p>
<p><b><a class="el" href="_h_d_f5_c_o_n_s_t.html">Constants and Enumerated Types</a></b> </p>
<p>The HDF5 API defines a set of constants and enumerated values. Most of these values are available to Java programs via the class <a class="el" href="_h_d_f5_c_o_n_s_t.html">Constants and Enumerated Types</a> <b><a class="el" href="classhdf_1_1hdf5lib_1_1_h_d_f5_constants.html">HDF5Constants</a></b>. For example, the parameters for the h5open() call include two numeric values, <b><em>HDFConstants.H5F_ACC_RDWR</em></b> and <b><em><a class="el" href="classhdf_1_1hdf5lib_1_1_h_d_f5_constants.html#a90bd58cb8e9d2bbd2d491707a5971410">HDF5Constants.H5P_DEFAULT</a></em></b>. As would be expected, these numbers correspond to the C constants <b><em><a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a></em></b> and <b><em><a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a></em></b>. </p>
<p>The HDF5 API defines a set of values that describe number types and sizes, such as "H5T_NATIVE_INT" and "hsize_t". These values are determined at run time by the HDF5 C library. To support these parameters, the Java HDFConstants class looks up the values when initiated. The values can be accessed as public variables of the Java class, such as:</p>
<div class="fragment"><div class="line"><span class="keywordtype">long</span> data_type = HDFConstants.H5T_NATIVE_INT;</div>
</div><!-- fragment --><p>The Java application uses both types of constants the same way, the only difference is that the <b><em>HDFConstants</em></b> may have different values on different platforms. </p>
<p><b><a class="el" href="_e_r_r_o_r_s.html">Errors and Exceptions</a></b> </p>
<p>The HDF5 error API (<a class="el" href="group___h5_e.html">Error Handling (H5E)</a>) manages the behavior of the error stack in the HDF5 library. This API is omitted from the JHI5. Errors are converted into Java exceptions. This is totally different from the C interface, but is very natural for Java programming. </p>
<p>The exceptions of the JHI5 are organized as sub-classes of the class <a class="el" href="_e_r_r_o_r_s.html">Errors and Exceptions</a> <b>HDF5Exception</b>. There are two subclasses of <b>HDF5Exception</b>, <a class="el" href="_e_r_r_o_r_s_l_i_b.html">HDF5 Library Errors and Exceptions</a> <b>HDF5LibraryException</b> and <a class="el" href="_e_r_r_o_r_s_j_a_v_a.html">Java Wrapper Errors and Exceptions</a> <b>HDF5JavaException</b>. The sub-classes of the former represent errors from the HDF5 C library, while sub-classes of the latter represent errors in the JHI5 wrapper and support code. </p>
<p>The super-class <b><em>HDF5LibraryException</em></b> implements the method '<b><em>printStackTrace()</em></b>', which prints out the HDF5 error stack, as described in the HDF5 C API <em><b><a class="el" href="group___h5_e.html#gaa7e93cb96b399e5853721258872435a8">H5Eprint()</a></b>.</em> This may be used by Java exception handlers to print out the HDF5 error stack. </p><hr />
<dl class="section version"><dt>Version</dt><dd>HDF5 1.15.0 <br />
<b>See also: </b> <a class="el" href="_h_d_f_a_r_r_a_y.html">Java Array Conversion</a> <a class="el" href="classhdf_1_1hdf5lib_1_1_h_d_f_array.html">hdf.hdf5lib.HDFArray</a><br />
<a class="el" href="_h_d_f5_c_o_n_s_t.html">Constants and Enumerated Types</a> <a class="el" href="classhdf_1_1hdf5lib_1_1_h_d_f5_constants.html">hdf.hdf5lib.HDF5Constants</a><br />
<a class="el" href="_e_r_r_o_r_s.html">Errors and Exceptions</a> hdf.hdf5lib.HDF5Exception<br />
<a href="https://hdfgroup.org/HDF5/">HDF5</a></dd></dl>
<p>For details of the HDF5 library, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_r_m.html">HDF5 Reference Manual</a> </dd></dl>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.10.0 </li>
</ul>
</div>
</body>
</html>
|
