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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
|
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
<title>CODA IDL</title>
<link rel="stylesheet" href="../css/codadoc.css" type="text/css" />
</head>
<body>
<div class="main">
<h1>CODA IDL</h1>
<p>The CODA IDL interface consists of just a handful of IDL 'named structures' and functions. A primary design goal was to simplify, as much as possible, the number of different types and functions a user would have to master in order to effectively use the library.</p>
<h2>Contents</h2>
<ul>
<li><a href="#codadef">CODA Definition Path</a></li>
<li><a href="#named-structures">Named Structures</a>
<ul>
<li><a href="#coda_datahandle"><code>CODA_DATAHANDLE</code></a></li>
<li><a href="#coda_error"><code>CODA_ERROR</code></a></li>
<li><a href="#coda_no_data"><code>CODA_NO_DATA</code></a></li>
</ul>
</li>
<li><a href="#functions-and-procedures">Functions and Procedures</a>
<ul>
<li><a href="#coda_version"><code>CODA_VERSION</code></a></li>
<li><a href="#coda_getopt"><code>CODA_GETOPT</code></a></li>
<li><a href="#coda_setopt"><code>CODA_SETOPT</code></a></li>
<li><a href="#coda_open"><code>CODA_OPEN</code></a></li>
<li><a href="#coda_open_as"><code>CODA_OPEN_AS</code></a></li>
<li><a href="#coda_close"><code>CODA_CLOSE</code></a></li>
<li><a href="#coda_product_class"><code>CODA_PRODUCT_CLASS</code></a></li>
<li><a href="#coda_product_type"><code>CODA_PRODUCT_TYPE</code></a></li>
<li><a href="#coda_product_version"><code>CODA_PRODUCT_VERSION</code></a></li>
<li><a href="#coda_fetch"><code>CODA_FETCH</code></a>
<ul>
<li><a href="#coda_fetch_first">The first argument</a></li>
<li><a href="#coda_fetch_specification">Specification arguments</a></li>
<li><a href="#coda_fetch_return">Return type</a>
<ul>
<li><a href="#coda_fetch_simple">Fetching simple (non-composite) types</a></li>
<li><a href="#coda_fetch_record">Fetching records</a></li>
<li><a href="#coda_fetch_array">Fetching arrays</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#coda_fetch_datahandle"><code>CODA_FETCH_DATAHANDLE</code></a></li>
<li><a href="#coda_eval"><code>CODA_EVAL</code></a></li>
<li><a href="#coda_attributes"><code>CODA_ATTRIBUTES</code></a></li>
<li><a href="#coda_fieldavailable"><code>CODA_FIELDAVAILABLE</code></a></li>
<li><a href="#coda_fieldcount"><code>CODA_FIELDCOUNT</code></a></li>
<li><a href="#coda_fieldnames"><code>CODA_FIELDNAMES</code></a></li>
<li><a href="#coda_size"><code>CODA_SIZE</code></a></li>
<li><a href="#coda_description"><code>CODA_DESCRIPTION</code></a></li>
<li><a href="#coda_unit"><code>CODA_UNIT</code></a></li>
<li><a href="#coda_time_to_string"><code>CODA_TIME_TO_STRING</code></a></li>
<li><a href="#coda_is_no_data"><code>CODA_IS_NO_DATA</code></a></li>
<li><a href="#coda_is_error"><code>CODA_IS_ERROR</code></a></li>
<li><a href="#coda_unload"><code>CODA_UNLOAD</code></a></li>
</ul>
</li>
</ul>
<h2 id="codadef">CODA Definition Path</h2>
<p>Note that in order to access products whose formats are defined using .codadef files, you should let CODA now where these .codadef files are stored. By default the CODA IDL interface will look for .codadef files in a directory relative to the location of the CODA IDL DLM file (<code>../../../share/coda/definitions</code>; note that software that embed CODA may sometimes override this default location). However, this will only work if you have set the IDL_DLM_PATH environment variable as specified in the CODA installation instructions for the IDL interface (otherwise no default location will be set).</p>
<p>You can override the default location by setting the CODA_DEFINITION environment variable. This environment variable should be a ':' separated (';' on Windows) list of absolute paths to directories containing .codadef files or absolute paths to .codadef files themselves (or a mix of those).</p>
<h2 id="named-structures">Named Structures</h2>
<p>The CODA IDL interface defines three 'named structures'. This section discusses them in detail. For reference, the three types are shown in the table below.</p>
<table class="fancy">
<tr><th>name</th><th>fields</th><th>type</th><th>usage</th></tr>
<tr><td><code>CODA_DATAHANDLE</code></td><td><code>PF_ID</code><br /><code>OPAQUE</code></td><td><code>ULONG64</code><br />not user-accessible</td><td>represents a data-item in a product-file</td></tr>
<tr><td><code>CODA_ERROR</code></td><td><code>ERRNO</code><br /><code>MESSAGE</code></td><td><code>INT</code><br /><code>STRING</code></td><td>CODA call return status (can also indicate success)</td></tr>
<tr><td><code>CODA_NO_DATA</code></td><td><code>OPAQUE</code></td><td><code>BYTE</code></td><td>represents an empty data item; the <code>OPAQUE</code> field is a dummy value and should not be used</td></tr>
</table>
<h3 id="coda_datahandle">The <code>CODA_DATAHANDLE</code> named structure</h3>
<p>The <code>CODA_DATAHANDLE</code> type represents a piece of data within a currently opened product-file; internally, it maintains a pointer to a certain offset within the data product, as well as information on the type of expression residing at that offset.</p>
<p><code>CODA_DATAHANDLE</code> variables are used extensively 'under the hood' of the CODA IDL interface; however, there are two closely related cases where this type will also be visible at the IDL user level.</p>
<p>If a call to <code>CODA_FETCH</code> is made that should return an 'array of array' or 'array of record' type, the call will return an 'array of <code>CODA_DATAHANDLE</code>' instead.</p>
<p>The reason for this behavior is that the sophisticated type system supported by CODA cannot be mapped in full generality onto the IDL type system from within IDL DLMs. Within a DLM it is not posible to create IDL arrays where different elements have different storage sizes (and DLMs do not have public access to the 'pointer interface' that can be used from within IDL code). Due to the generality of the CODA interface it is currently also not possible to make an exception for the possible cases where the records/arrays might per-chance have the same storage size for each array element. For consistency, we have therefore chosen to handle all these cases uniformly, always returning an 'array of <code>CODA_DATAHANDLE</code>' when an 'array of array' or an 'array of record' is fetched. You can then manually traverse the 'array of <code>CODA_DATAHANDLE</code>', and use <code>CODA_FETCH</code> (providing a <code>CODA_DATAHANDLE</code> as first argument) to obtain the individual records or arrays represented by the <code>CODA_DATAHANDLE</code> elements.</p>
<p>Although the proper use of <code>CODA_DATAHANDLE</code>-arrays is probably the most subtle and difficult aspect of using the CODA IDL interface, it has proved to be quite easy to get used to. In fact, when used properly, the use of an 'array of <code>CODA_DATAHANDLE</code>' often improves performance as the <code>CODA_DATAHANDLE</code> elements effectively cache the information needed to access the data, thereby speeding up subsequent accesses.</p>
<p>The <code>CODA_DATAHANDLE</code> structure has two fields:</p>
<ul>
<li>The <code>PF_ID</code> is a product-file ID as returned by the <code>CODA_OPEN</code> function (see below). At the IDL user level, you are free to inspect its value. However, do not change its value.</li>
<li>The <code>OPAQUE</code> field is used internally to maintain pointer and data type information. This field should not be accessed from within IDL; most importantly, its value should not be changed.</li>
</ul>
<p>The meaning of a <code>CODA_DATAHANDLE</code> becomes undefined after the product to which it is associated is closed; You should not use it in subsequent CODA IDL interface operations. Doing so will generate an error.</p>
<h3 id="coda_error">The <code>CODA_ERROR</code> named structure</h3>
<p>The <code>CODA_ERROR</code> structure may be returned by any CODA IDL interface function, usually indicating that the operation failed for some reason. Despite the name, you should think of a <code>CODA_ERROR</code> as a 'status report' of the last CODA IDL interface call; the status may, in fact, indicate successful completion.</p>
<p>For example, the <code>CODA_CLOSE</code> function will always return a value of type <code>CODA_ERROR</code>, even when the operation succeeds.</p>
<p>The <code>CODA_ERROR</code> has two fields. The <code>ERRNO</code> field gives a numerical error code. This code is guaranteed to be either 0 (zero), indicating success, or a negative number, indicating failure.</p>
<p>The <code>MESSAGE</code> field is a STRING that provides a human-readable description corresponding to the <code>ERRNO</code> field. Some errors originate from the underlying C library that the CODA IDL interface uses, others are specific to IDL. For example, if one of the parameters you pass to a CODA IDL interface function is incorrect you will get a <code>CODA_ERROR</code> indicating the type of error.</p>
<h3 id="coda_no_data">The <code>CODA_NO_DATA</code> named structure</h3>
<p>The <code>CODA_NO_DATA</code> is used to represent unavailable record fields or zero-element arrays in IDL. CODA is capable of representing arrays that have zero indices in any dimension but such a data structure cannot be represented in IDL. Whenever CODA needs to represent a zero-element array, an instance of type <code>CODA_NO_DATA</code> is used instead.</p>
<p>The <code>CODA_NO_DATA</code> has one field. The <code>OPAQUE</code> field is present only to assure that the structure has a field (which is required by IDL). It does not contain any useful data.</p>
<h2 id="functions-and-procedures">Functions and Procedures</h2>
<h3 id="coda_version">Function <code>CODA_VERSION(): STRING</code></h3>
<p>The <code>CODA_VERSION</code> function returns a string containing the current version number of CODA. The version number is always of the format 'x.y.z', i.e., major, minor, and revision numbers, separated by dots.</p>
<h3 id="coda_getopt">Function <code>CODA_GETOPT(STRING option_name): INT</code></h3>
<p>The <code>CODA_GETOPT</code> function returns the numerical value of a CODA IDL interface option. The following options are supported:</p>
<table class="fancy">
<tr><th>option name</th><th>possible values</th><th>default value</th><th>meaning</th></tr>
<tr>
<td>FilterRecordFields</td>
<td>0 or 1</td>
<td>1</td>
<td>if set, the CODA IDL interface will skip spare fields and fields that have a fixed value (such as header labels) when retrieving records, avoiding unnecessary clutter.</td>
</tr>
<tr>
<td>PerformConversions</td>
<td>0 or 1</td>
<td>1</td>
<td>if set, CODA will perform unit/value conversions for fields that have a 'conversion' defined in the CODA product format definitions.</td>
</tr>
<tr>
<td>PerformBoundaryChecks</td>
<td>0 or 1</td>
<td>1</td>
<td>if set, CODA will perform boundary checking on array accesses. This makes CODA more robust, at the cost of some performance. It is recommended to disable boundary checks only for thoroughly tested programs; disabling boundary checks can lead to wrong results and/or IDL crashes if arrays are accessed beyond their boundaries.</td>
</tr>
<tr>
<td>SwapDimensions</td>
<td>0 or 1</td>
<td>1</td>
<td>if set, CODA will swap the dimensions of multi-dimensional arrays (i.e. performing a multi-dimensional transpose on the data) so the array dimensions that are found in e.g. the CODA format definitions can be used as-is on the data. This distinction is needed because IDL uses Fortran-style ordering for array indices whereas CODA uses C-style array dimensioning ordering as the standard. If you disable this option, CODA will no longer transpose the data itself, but will invert the ordering of the array indices you pass to e.g. CODA_FETCH and the dimension sizes that are returned by CODA_SIZE.</td>
</tr>
<tr>
<td>TimeUnitDays</td>
<td>0 or 1</td>
<td>0</td>
<td>if set, the CODA IDL interface will represent all time values as days since 1-1-2000 instead of seconds since 1-1-2000. This is true both for fetched values and for values passed to <code>CODA_TIME_TO_STRING</code>. Use of this functionality is discouraged, as this will make data exchange between programs more difficult.</td>
</tr>
<tr>
<td>UseMMap</td>
<td>0 or 1</td>
<td>1</td>
<td>By default CODA uses a technique called 'memory mapping' to open and access data from product files. Using mmap greatly outperforms the default approach of reading data using the open()/read() combination. The downside of mapping a file into memory is that it takes away valuable address space. When you run a 32-bit Operating System your maximum addressable memory range is 4GB and if you simultaneously try to keep a few large product files open your memory space can quickly become full. Opening additional files will then produce 'out of memory' errors. Note that this 'out of memory' situation has nothing to do with the amount of RAM you have installed in your computer. It is only related to the size of a memory pointer on your system, which is limited to 4GB. If you are using CODA in a situation where you need to have multiple large product files open at the same time you can turn of the use of memory mapping by disabling this option. If you change the memory mapping option, the new setting will only be applicable for files that will be opened after you changed the option. Any files that were already open will keep using the mechanism with which they were opened.</td>
</tr>
<tr>
<td>UseSpecialTypes</td>
<td>0 or 1</td>
<td>1</td>
<td>if you disable this option, CODA will use the base type of a special type (and not the special type itself) when reading data or retrieving information about a data item. See the CODA Product Format Definitions documentation for more information about special types.</td>
</tr>
<tr>
<td>Verbose</td>
<td>0 or 1</td>
<td>1</td>
<td>if set, the CODA IDL interface will echo 'error' return values to the IDL command line just before returning them to the IDL user level. This can be helpful in detecting problems.</td>
</tr>
</table>
<h3 id="coda_setopt">Function <code>CODA_SETOPT(STRING option_name, INT new_value): INT</code></h3>
<p>The <code>CODA_SETOPT</code> function is used to set the CODA IDL interface option to a new value. See the <code>CODA_GETOPT</code> description above for a list of allowed options and values, and their associated meanings.</p>
<p>The <code>CODA_SETOPT</code> function will return the <i>previous</i> value of the option.</p>
<h3 id="coda_open">Function <code>CODA_OPEN(STRING filename): ULONG64</code></h3>
<p><code>CODA_OPEN</code> will attempt to open the file (which may fail, for example, if you specify a file that does not exist).</p>
<p>If <code>CODA_OPEN</code> succeeds, it returns a unique positive 64-bit unsigned integer that can subsequently be used to identifty the file in <code>CODA_FETCH</code> and <code>CODA_CLOSE</code> calls. If it fails a <code>CODA_ERROR</code> structure is returned giving the reason for failure.</p>
<p>It is perfectly OK to have multiple files open at the same time. Still, you are advised to close files as soon as you are done with them, since each of them consumes a vital system resource: <i>address space</i>. Note that this is <i>not</i> the same as 'memory': a data product is not read in its entirety into memory. A typical opened product file should consume a couple of tens of kilobytes of memory. However, the entire product file is virtually <i>mapped into</i> memory (a well-known technique that provides high-performance I/O access to a file). On a modern 32-bit computer (e.g., an Intel x86-class computer running Linux or Windows), up to 3 gigabytes worth of files may be mapped into memory at any one point in time.</p>
<p>In the CODA IDL interface, you can have up to 100 files open simultaneously. An attempt to open more files will yield an error.</p>
<h3 id="coda_open_as">Function <code>CODA_OPEN_AS(STRING filename, STRING product_class, STRING product_type, INT version): ULONG64</code></h3>
<p><code>CODA_OPEN_AS</code> will try to open the specified file for reading similar to <code>CODA_OPEN</code>, but instead of trying to automatically recognise the applicable product class/type/version as <code>CODA_OPEN</code> does, this function will impose the format definition that is associated with the given product_class, product_type, and version parameters.</p>
<p>Note that you normally won't need this function as CODA will be able to recognize which format definition to use automatically. However, for the rare occasions where <code>CODA_OPEN</code> is not sufficient, you can use this function to force the use of a specific format definition.</p>
<p>You can specify -1 for the version to request the latest available version of the format definition.</p>
<h3 id="coda_close">Function <code>CODA_CLOSE(ULONG64 pf_id): CODA_ERROR</code></h3>
<p>The <code>CODA_CLOSE</code> function is used to release a previously-opened product file. Its one argument should be a 64-bit unsigned integer as returned by a previously executed successful <code>CODA_OPEN</code> call.</p>
<h3 id="coda_product_class">Function <code>CODA_PRODUCT_CLASS(ULONG64 pf_id): STRING</code></h3>
<p>The <code>CODA_PRODUCT_CLASS</code> function returns a string containing the product class of a product file if it has one (otherwise an empty string is returned).</p>
<h3 id="coda_product_type">Function <code>CODA_PRODUCT_TYPE(ULONG64 pf_id): STRING</code></h3>
<p>The <code>CODA_PRODUCT_TYPE</code> function returns a string containing the product type of a product file if it has one (otherwise an empty string is returned).</p>
<h3 id="coda_product_version">Function <code>CODA_PRODUCT_VERSION(ULONG64 pf_id): INT</code></h3>
<p>The <code>CODA_PRODUCT_VERSION</code> function returns an integer denoting the product format version. If the product does not have a format version number this functiion will return -1.</p>
<h3 id="coda_fetch">Function <code>CODA_FETCH(...)</code></h3>
<p>The <code>CODA_FETCH</code> function is used to fetch data from somewhere in an open product-file and turn it into an IDL variable.</p>
<h4 id="coda_fetch_first"><code>CODA_FETCH</code>: the first argument</h4>
<p>Several forms of <code>CODA_FETCH</code> exist that are distinguished by the first argument argument. Depending on the form of the call, <code>CODA_FETCH</code> will try to read data from different header-parts or datasets in the product files. This is summarized below.</p>
<table class="fancy">
<tr><th>call</th><th>Fetch-root</th></tr>
<tr><td><code>CODA_FETCH(pf_id)</code></td><td>Entire product</td></tr>
<tr><td><code>CODA_FETCH(pf_id, [, <i>what</i>, ...])</code></td><td>Data (from product root)</td></tr>
<tr><td><code>CODA_FETCH(data_handle [, <i>what</i>, ...])</code></td><td>Data described by handle</td></tr>
</table>
<p>As noted before, in some cases the <code>CODA_FETCH</code> call may return an array of <code>CODA_DATAHANDLE</code> structures. The last form of the <code>CODA_FETCH</code> call allows you to traverse such an array and fetch the data described by each of the data-handles in turn.</p>
<h4 id="coda_fetch_specification"><code>CODA_FETCH</code>: data-item specification arguments</h4>
<p>After the first argument you can specify more arguments that tell <code>CODA_FETCH</code> to retrieve only a specific part of the data pointed to by the first argument. It is possible to have more than one such 'specification argument' in case of nested data-types.</p>
<p>Three forms of 'specification arguments' exist:</p>
<ul>
<li>Array index: You need to provide an array index that has the same number of elements as there are dimensions in the array that you are referring to. So if the array is two dimensional you have to pass indices for both dimensions like <code>[4,5]</code>. If the array is one dimensional you can just provide a single index value (without the '[]') to get to the k-th element. You can use <a href="#coda_size"><code>coda_size</code></a> to check the number of dimensions of an array and the size of each dimension.</li>
<li>Field name: To go to a certain field inside the record that you are pointing to, you can provide the field name as a string.</li>
<li>Path: You can provide a string containing a path reference, such as <code>"measurements[0]/time"</code>. Using paths will also allow you to navigate to attributes by using <code>"@"</code> as a path component. For instance, '<code>"temperature", "@", "units"</code>' or <code>"temperature@units"</code> will point to the units attribute of the temperature data. Note that array indices used in these string paths need to be 0-based indices on the flattened view of an array. This means that if an array is defined as having more than one dimension then the index as used in a path expression should be between 0 and the total number of array elements (exclusive). For example, for a <code>[10,8]</code> array, the index should be >= 0 and <= 79. For, instance <code>coda_fetch(pf, 'variable', [0,0])</code> is equivalent to <code>coda_fetch(pf, 'variable[0]')</code></li>
</ul>
<p>An example will help to understand all this. Suppose we have a product that contains a dataset called 'MEASUREMENTS', having 1000 records. Each of these records contains a field called 'samples' that is a 2-dimensional 101x101 array of doubles.</p>
<p>Now suppose we want to fetch the central 'sample' contained in record #10. The following <code>CODA_FETCH</code> would do the trick:</p>
<p><code>result = CODA_FETCH(pf_id, 'MEASUREMENTS', [10], 'samples', [50,50])</code></p>
<p>Alternatively, since the '[10]' specifies the index of a one-dimensional array, we could also write</p>
<p><code>result = CODA_FETCH(pf, 'MEASUREMENTS', 10, 'samples', [50,50])</code></p>
<p>Or we could use a single string parameter to provide the full path</p>
<p><code>result = CODA_FETCH(pf, 'MEASUREMENTS[10]/samples[5100]')</code></p>
<p>For the <code>CODA_FETCH</code> and <code>CODA_FETCH_DATAHANDLE</code> functions (but not for the other CODA IDL interface functions that use data-item specification arguments) there is an additional feature. If you provide a <code>-1</code> for one or more of the dimensions of an array you will fetch all elements in this dimension. For example, with</p>
<p><code>result = CODA_FETCH(pf, 'MEASUREMENTS', -1, 'samples', [50,50])</code></p>
<p>you can fetch all central samples of all measurements into a single array. Similarly, you can use</p>
<p><code>result = CODA_FETCH(pf, 'MEASUREMENTS', 0, 'samples', [-1,0])</code></p>
<p>to fetch the first samples column of the first measurement.</p>
<p>The <code>-1</code> parameter may only be used for one array in a fetch statement (e.g. <code>CODA_FETCH(pf, 'MEASUREMENTS', 0, 'samples', [-1,-1])</code> is allowed, but <code>CODA_FETCH(pf, 'MEASUREMENTS', -1, 'samples', [-1,0])</code> is not). Also, the -1 index only works when passing it as an explicit argument (i.e. calling <code>coda_fetch(pf, "dataset[-1]/dsr_time[5100]")</code>, where the -1 index is part of a string argument, will not work; calling <code>coda_fetch(pf, "dataset", -1, "dsr_time[5100]")</code> will work).</p>
<h4 id="coda_fetch_return"><code>CODA_FETCH</code> return type</h4>
<p>The IDL type of the <code>CODA_FETCH</code> return-value depends on the CODA data type of the data item being fetched. Three cases are distinguished:</p>
<h5 id="coda_fetch_simple">Return types for simple (non-composite) types</h5>
<p>If the data item has a basic type the return type is determined according to the following table.</p>
<table class="fancy">
<tr><th>CODA read type</th><th>IDL Type</th><th>remark</th></tr>
<tr><td>int8</td><td>INT</td><td> </td></tr>
<tr><td>uint8</td><td>BYTE</td><td><i>a BYTE is unsigned in IDL</i></td></tr>
<tr><td>int16</td><td>INT</td><td> </td></tr>
<tr><td>uint16</td><td>UINT</td><td> </td></tr>
<tr><td>int32</td><td>LONG</td><td> </td></tr>
<tr><td>uint32</td><td>ULONG</td><td> </td></tr>
<tr><td>int64</td><td>LONG64</td><td> </td></tr>
<tr><td>uint64</td><td>ULONG64</td><td> </td></tr>
<tr><td>float</td><td>FLOAT</td><td> </td></tr>
<tr><td>double</td><td>DOUBLE</td><td> </td></tr>
<tr><td>char</td><td>STRING</td><td> </td></tr>
<tr><td>string</td><td>STRING</td><td> </td></tr>
<tr><td>bytes</td><td>BYTE</td><td>This will actually translate into an array of type BYTE</td></tr>
</table>
<p><b><code>CODA_FETCH</code> return types for basic data types</b></p>
<h5 id="coda_fetch_record">Return types for Record types</h5>
<p>Record types will be returned as anonymous (unnamed) IDL structures, where each field will correspond to a field in the original data set. If a field has the hidden property and if the FilterRecordFields option is set then the field will not be copied into the IDL structure.</p>
<p>For basic types, the IDL field type will be determined according to the 'basic data types' table given above. Fields that are themselves records are expanded as 'nested records'. Fields that are themselves arrays are expanded as 'array types', as discussed below.</p>
<p>If a record contains no fields (i.e. an empty record) then CODA will return a <code>CODA_NO_DATA</code> named structure instead of an empty anonymous struct.</p>
<h5 id="coda_fetch_array">Return types for Array types</h5>
<p>Array types will be returned as multi-dimensional IDL arrays, with the IDL array base-type derived from the base-type of the CODA type according to the 'basic data types' table given above. There are, however, some complications that IDL programmers need to be aware of when the base type itself is either an array or a record.</p>
<p>For array and record base-types (i.e., 'array of array', 'array of record'), there is, in general, no equivalent type in IDL. As explained in the <a href="#coda_datahandle">section about the <code>CODA_DATAHANDLE</code> structure</a> above, both these cases will yield an 'array of <code>CODA_DATAHANDLE</code>' instead.</p>
<p>If an array is empty (i.e. the size of one of its dimensions is 0) then CODA will return a <code>CODA_NO_DATA</code> named structure instead of a multi-dimensional IDL array.</p>
<h3 id="coda_fetch_datahandle">Function <code>CODA_FETCH_DATAHANDLE(...): CODA_DATAHANDLE</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it <em>always</em> returns a datahandle to the specified data (even if it would be easily representable in IDL).</p>
<h3 id="coda_eval">Function <code>CODA_EVAL(STRING expression, ...)</code></h3>
<p>This function takes a CODA expression in the form of a string and an optional product location. The product location is the same kind of argument (list) as used for <code>CODA_FETCH</code>. If the CODA expression can be evaluated statically, then the product location argument is not required, otherwise the product location argument is mandatory.</p>
<p>The syntax for the CODA expression language can be found in the <a href="../codadef/codadef-expressions.html">CODA Expressions</a> documentation. Note that evaluation of 'void' expressions is not supported.</p>
<h3 id="coda_attributes">Function <code>CODA_ATTRIBUTES(...)</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it returns a record containing all attributes of the specified data item. The record can be empty if no attributes are available.</p>
<h3 id="coda_fieldavailable">Function <code>CODA_FIELDAVAILABLE(...): INT</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it returns the availabillity of a record field. It returns 1 if it is available and 0 if it is not.</p>
<p>If the arguments to <code>CODA_FIELDAVAILABLE</code> do not point to a record, a <code>CODA_ERROR</code> structure is returned.</p>
<h3 id="coda_fieldcount">Function <code>CODA_FIELDCOUNT(...): INT</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it returns the number of fields in a record.</p>
<p>If the arguments to <code>CODA_FIELDCOUNT</code> do not point to a record, a <code>CODA_ERROR</code> structure is returned.</p>
<h3 id="coda_fieldnames">Function <code>CODA_FIELDNAMES(...): STRING-array</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it returns the field-names of the fields in a record.</p>
<p>If the arguments to <code>CODA_FIELDNAMES</code> do not point to a record, a <code>CODA_ERROR</code> structure is returned.</p>
<h3 id="coda_size">Function <code>CODA_SIZE(...): INT-array</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it returns the actual dimensionality of a multi-dimensional array.</p>
<p>If the arguments to <code>CODA_SIZE</code> do not point to an array, a <code>CODA_ERROR</code> structure is returned.</p>
<h3 id="coda_description">Function <code>CODA_DESCRIPTION(...): STRING</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it returns the description of a data item.</p>
<h3 id="coda_unit">Function <code>CODA_UNIT(...): STRING</code></h3>
<p>This function takes the same kind of argument as <code>CODA_FETCH</code>; however, instead of returning the specified data from the product, it returns the unit of a data item.</p>
<h3 id="coda_time_to_string">Function <code>CODA_TIME_TO_STRING(<i>numerical argument</i>): STRING</code></h3>
<p>CODA by default stores time values as a double denoting the number of seconds since Midnight, January 1<sup>st</sup>, 2000 UTC.</p>
<p>The <code>CODA_TIME_TO_STRING</code> function takes a <code>DOUBLE</code>-encoded time value and converts it to a human-readable string of the form "2000-01-01 00:00:00.000000"</p>
<h3 id="coda_is_no_data">Function <code>CODA_IS_NO_DATA(...): INT</code></h3>
<p>The <code>CODA_IS_NO_DATA</code> function takes one argument; it returns a value of TRUE (1) if and only if the argument is a <code>CODA_EMPTY_ARRAY</code> structure.</p>
<ul>
<li>its <code>ERRNO</code> field is not equal to zero</li>
</ul>
<h3 id="coda_is_error">Function <code>CODA_IS_ERROR(...): INT</code></h3>
<p>The <code>CODA_IS_ERROR</code> function takes one argument; it returns a value of TRUE (1) if and only if</p>
<ul>
<li>the argument is a <code>CODA_ERROR</code> structure</li>
<li>its <code>ERRNO</code> field is not equal to zero</li>
</ul>
<p>If either of these is not true, <code>CODA_IS_ERROR</code> returns FALSE (0).</p>
<p>Using <code>CODA_IS_ERROR</code>, you can make your CODA-based IDL programs robust (i.e., resistant to failures). If you test the result of any CODA IDLinterface call with <code>CODA_IS_ERROR</code>, you should be able to intercept any error.</p>
<h3 id="coda_unload">Procedure <code>CODA_UNLOAD</code></h3>
<p>The <code>CODA_UNLOAD</code> procedure will close all opened product files and unload any chached CODA product format definitions from memory.</p>
<p>The CODA product format definitions are loaded on-demand if any CODA function that needs it is invoked.</p>
<p>This function may be (slightly) useful on systems with little memory. You could open a product file, fetch the important data, close the file, and then unload the product format definitions to free extra memory before starting data-processing. Other than that, this function is of little practical use.</p>
<div class="footer">
<hr />
<p>Copyright © 2007-2022 <b>s<span class="soft-red">[</span>&<span class="soft-red">]</span>t</b>, The Netherlands.</p>
</div>
</div>
</body>
</html>
|
