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
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>The Data Type Interface (H5T)</title>
</head>
<body>
<h1>The Data Type Interface (H5T)</h1>
<h2>1. Introduction</h2>
<p>The data type interface provides a mechanism to describe the
storage format of individual data points of a data set and is
hopefully designed in such a way as to allow new features to be
easily added without disrupting applications that use the data
type interface. A dataset (the H5D interface) is composed of a
collection or raw data points of homogeneous type organized
according to the data space (the H5S interface).
<p>A data type is a collection of data type properties, all of
which can be stored on disk, and which when taken as a whole,
provide complete information for data conversion to or from that
data type. The interface provides functions to set and query
properties of a data type.
<p>A <em>data point</em> is an instance of a <em>data type</em>,
which is an instance of a <em>type class</em>. We have defined
a set of type classes and properties which can be extended at a
later time. The atomic type classes are those which describe
types which cannot be decomposed at the data type interface
level; all other classes are compound.
<h2>2. General Data Type Operations</h2>
<p>The functions defined in this section operate on data types as
a whole. New data types can be created from scratch or copied
from existing data types. When a data type is no longer needed
its resources should be released by calling <code>H5Tclose()</code>.
<p>Data types come in two flavors: named data types and transient
data types. A named data type is stored in a file while the
transient flavor is independent of any file. Named data types
are always read-only, but transient types come in three
varieties: modifiable, read-only, and immutable. The difference
between read-only and immutable types is that immutable types
cannot be closed except when the entire library is closed (the
predefined types like <code>H5T_NATIVE_INT</code> are immutable
transient types).
<dl>
<dt><code>hid_t H5Tcreate (H5T_class_t <em>class</em>, size_t
<em>size</em>)</code>
<dd>Data types can be created by calling this
function, where <em>class</em> is a data type class
identifier. However, the only class currently allowed is
<code>H5T_COMPOUND</code> to create a new empty compound data
type where <em>size</em> is the total size in bytes of an
instance of this data type. Other data types are created with
<code>H5Tcopy()</code>. All functions that return data type
identifiers return a negative value for failure.
<br><br>
<dt><code>hid_t H5Topen (hid_t <em>location</em>, const char
*<em>name</em>)</code>
<dd>A named data type can be opened by calling this function,
which returns a handle to the data type. The handle should
eventually be closed by calling <code>H5Tclose()</code> to
release resources. The named data type returned by this
function is read-only or a negative value is returned for
failure. The <em>location</em> is either a file or group
handle.
<br><br>
<dt><code>herr_t H5Tcommit (hid_t <em>location</em>, const char
*<em>name</em>, hid_t <em>type</em>)</code>
<dd>A transient data type (not immutable) can be committed to a
file and turned into a named data type by calling this
function. The <em>location</em> is either a file or group
handle and when combined with <em>name</em> refers to a new
named data type.
<br><br>
<dt><code>hbool_t H5Tcommitted (hid_t <em>type</em>)</code>
<dd>A type can be queried to determine if it is a named type or
a transient type. If this function returns a positive value
then the type is named (that is, it has been committed perhaps
by some other application). Datasets which return committed
data types with <code>H5Dget_type()</code> are able to share
the data type with other datasets in the same file.
<br><br>
<dt><code>hid_t H5Tcopy (hid_t <em>type</em>)</code>
<dd>This function returns a modifiable transient data type
which is a copy of <em>type</em> or a negative value for
failure. If <em>type</em> is a dataset handle then the type
returned is a modifiable transient copy of the data type of
the specified dataset.
<br><br>
<dt><code>herr_t H5Tclose (hid_t <em>type</em>)</code>
<dd>Releases resources associated with a data type. The data
type identifier should not be subsequently used since the
results would be unpredictable. It is illegal to close an
immutable transient data type.
<br><br>
<dt><code>hbool_t H5Tequal (hid_t <em>type1</em>, hid_t
<em>type2</em>)</code>
<dd>Determines if two types are equal. If <em>type1</em> and
<em>type2</em> are the same then this function returns
<code>TRUE</code>, otherwise it returns <code>FALSE</code> (an
error results in a negative return value).
<br><br>
<dt><code>herr_t H5Tlock (hid_t <em>type</em>)</code>
<dd>A transient data type can be locked, making it immutable
(read-only and not closable). The library does this to all
predefined types to prevent the application from inadvertently
modifying or deleting (closing) them, but the application is
also allowed to do this for its own data types. Immutable
data types are closed when the library closes (either by
<code>H5close()</code> or by normal program termination).
</dl>
<h2>3. Properties of Atomic Types</h2>
<p>An atomic type is a type which cannot be decomposed into
smaller units at the API level. All atomic types have a common
set of properties which are augmented by properties specific to
a particular type class. Some of these properties also apply to
compound data types, but we discuss them only as they apply to
atomic data types here. The properties and the functions that
query and set their values are:
<dl>
<dt><code>H5T_class_t H5Tget_class (hid_t <em>type</em>)</code>
<dd>This property holds one of the class names:
<code>H5T_INTEGER, H5T_FLOAT, H5T_TIME, H5T_STRING,
H5T_BITFIELD</code>, or <code>H5T_OPAQUE</code>. This
property is read-only and is set when the datatype is
created or copied (see <code>H5Tcreate()</code>,
<code>H5Tcopy()</code>). If this function fails it returns
<code>H5T_NO_CLASS</code> which has a negative value (all
other class constants are non-negative).
<br><br>
<dt><code>size_t H5Tget_size (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_size (hid_t <em>type</em>, size_t
<em>size</em>)</code>
<dd>This property is total size of the datum in bytes, including
padding which may appear on either side of the actual value.
If this property is reset to a smaller value which would cause
the significant part of the data to extend beyond the edge of
the data type then the <code>offset</code> property is
decremented a bit at a time. If the offset reaches zero and
the significant part of the data still extends beyond the edge
of the data type then the <code>precision</code> property is
decremented a bit at a time. Decreasing the size of a data
type may fail if the precesion must be decremented and the
data type is of the <code>H5T_OPAQUE</code> class or the
<code>H5T_FLOAT</code> bit fields would extend beyond the
significant part of the type. Adjusting the size of an
<code>H5T_STRING</code> automatically adjusts the precision
as well. On error, <code>H5Tget_size()</code> returns zero
which is never a valid size.
<br><br>
<dt><code>H5T_order_t H5Tget_order (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_order (hid_t <em>type</em>, H5T_order_t
<em>order</em>)</code>
<dd>All atomic data types have a byte order which describes how
the bytes of the data type are layed out in memory. If the
lowest memory address contains the least significant byte of
the datum then it is said to be <em>little-endian</em> or
<code>H5T_ORDER_LE</code>. If the bytes are in the oposite
order then they are said to be <em>big-endian</em> or
<code>H5T_ORDER_BE</code>. Some data types have the same byte
order on all machines and are <code>H5T_ORDER_NONE</code>
(like character strings). If <code>H5Tget_order()</code>
fails then it returns <code>H5T_ORDER_ERROR</code> which is a
negative value (all successful return values are
non-negative).
<br><br>
<dt><code>size_t H5Tget_precision (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_precision (hid_t <em>type</em>, size_t
<em>precision</em>)</code>
<dd>Some data types occupy more bytes than what is needed to
store the value. For instance, a <code>short</code> on a Cray
is 32 significant bits in an eight-byte field. The
<code>precision</code> property identifies the number of
significant bits of a datatype and the <code>offset</code>
property (defined below) identifies its location. The
<code>size</code> property defined above represents the entire
size (in bytes) of the data type. If the precision is
decreased then padding bits are inserted on the MSB side of
the significant bits (this will fail for
<code>H5T_FLOAT</code> types if it results in the sign,
mantissa, or exponent bit field extending beyond the edge of
the significant bit field). On the other hand, if the
precision is increased so that it "hangs over" the edge of the
total size then the <code>offset</code> property is
decremented a bit at a time. If the <code>offset</code>
reaches zero and the significant bits still hang over the
edge, then the total size is increased a byte at a time. The
precision of an <code>H5T_STRING</code> is read-only and is
always eight times the value returned by
<code>H5Tget_size()</code>. <code>H5Tget_precision()</code>
returns zero on failure since zero is never a valid precision.
<br><br>
<dt><code>size_t H5Tget_offset (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_offset (hid_t <em>type</em>, size_t
<em>offset</em>)</code>
<dd>While the <code>precision</code> property defines the number
of significant bits, the <code>offset</code> property defines
the location of those bits within the entire datum. The bits
of the entire data are numbered beginning at zero at the least
significant bit of the least significant byte (the byte at the
lowest memory address for a little-endian type or the byte at
the highest address for a big-endian type). The
<code>offset</code> property defines the bit location of the
least signficant bit of a bit field whose length is
<code>precision</code>. If the offset is increased so the
significant bits "hang over" the edge of the datum, then the
<code>size</code> property is automatically incremented. The
offset is a read-only property of an <code>H5T_STRING</code>
and is always zero. <code>H5Tget_offset()</code> returns zero
on failure which is also a valid offset, but is guaranteed to
succeed if a call to <code>H5Tget_precision()</code> succeeds
with the same arguments.
<br><br>
<dt><code>herr_t H5Tget_pad (hid_t <em>type</em>, H5T_pad_t
*<em>lsb</em>, H5T_pad_t *<em>msb</em>)</code>
<dt><code>herr_t H5Tset_pad (hid_t <em>type</em>, H5T_pad_t
<em>lsb</em>, H5T_pad_t <em>msb</em>)</code>
<dd>The bits of a datum which are not significant as defined by
the <code>precision</code> and <code>offset</code> properties
are called <em>padding</em>. Padding falls into two
categories: padding in the low-numbered bits is <em>lsb</em>
padding and padding in the high-numbered bits is <em>msb</em>
padding (bits are numbered according to the description for
the <code>offset</code> property). Padding bits can always be
set to zero (<code>H5T_PAD_ZERO</code>) or always set to one
(<code>H5T_PAD_ONE</code>). The current pad types are returned
through arguments of <code>H5Tget_pad()</code> either of which
may be null pointers.
</dl>
<h3>3.1. Properties of Integer Atomic Types</h3>
<p>Integer atomic types (<code>class=H5T_INTEGER</code>)
describe integer number formats. Such types include the
following information which describes the type completely and
allows conversion between various integer atomic types.
<dl>
<dt><code>H5T_sign_t H5Tget_sign (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_sign (hid_t <em>type</em>, H5T_sign_t
<em>sign</em>)</code>
<dd>Integer data can be signed two's complement
(<code>H5T_SGN_2</code>) or unsigned
(<code>H5T_SGN_NONE</code>). Whether data is signed or not
becomes important when converting between two integer data
types of differing sizes as it determines how values are
truncated and sign extended.
</dl>
<h3>3.2. Properties of Floating-point Atomic Types</h3>
<p>The library supports floating-point atomic types
(<code>class=H5T_FLOAT</code>) as long as the bits of the
exponent are contiguous and stored as a biased positive number,
the bits of the mantissa are contiguous and stored as a positive
magnitude, and a sign bit exists which is set for negative
values. Properties specific to floating-point types are:
<dl>
<dt><code>herr_t H5Tget_fields (hid_t <em>type</em>, size_t
*<em>spos</em>, size_t *<em>epos</em>, size_t
*<em>esize</em>, size_t *<em>mpos</em>, size_t
*<em>msize</em>)</code>
<dt><code>herr_t H5Tset_fields (hid_t <em>type</em>, size_t
<em>spos</em>, size_t <em>epos</em>, size_t <em>esize</em>,
size_t <em>mpos</em>, size_t <em>msize</em>)</code>
<dd>A floating-point datum has bit fields which are the exponent
and mantissa as well as a mantissa sign bit. These properties
define the location (bit position of least significant bit of
the field) and size (in bits) of each field. The bit
positions are numbered beginning at zero at the beginning of
the significant part of the datum (see the descriptions of the
<code>precision</code> and <code>offset</code>
properties). The sign bit is always of length one and none of
the fields are allowed to overlap. When expanding a
floating-point type one should set the precision first; when
decreasing the size one should set the field positions and
sizes first.
<br><br>
<dt><code>size_t H5Tget_ebias (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_ebias (hid_t <em>type</em>, size_t
<em>ebias</em>)</code>
<dd>The exponent is stored as a non-negative value which is
<code>ebias</code> larger than the true exponent.
<code>H5Tget_ebias()</code> returns zero on failure which is
also a valid exponent bias, but the function is guaranteed to
succeed if <code>H5Tget_precision()</code> succeeds when
called with the same arguments.
<br><br>
<dt><code>H5T_norm_t H5Tget_norm (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_norm (hid_t <em>type</em>, H5T_norm_t
<em>norm</em>)</code>
<dd>This property determines the normalization method of the
mantissa.
<ul>
<li>If the value is <code>H5T_NORM_MSBSET</code> then the
mantissa is shifted left (if non-zero) until the first bit
after the radix point is set and the exponent is adjusted
accordingly. All bits of the mantissa after the radix
point are stored.
<li>If its value is <code>H5T_NORM_IMPLIED</code> then the
mantissa is shifted left (if non-zero) until the first bit
after the radix point is set and the exponent is adjusted
accordingly. The first bit after the radix point is not stored
since it's always set.
<li>If its value is <code>H5T_NORM_NONE</code> then the fractional
part of the mantissa is stored without normalizing it.
</ul>
<br><br>
<dt><code>H5T_pad_t H5Tget_inpad (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_inpad (hid_t <em>type</em>, H5T_pad_t
<em>inpad</em>)</code>
<dd>If any internal bits (that is, bits between the sign bit,
the mantissa field, and the exponent field but within the
precision field) are unused, then they will be filled
according to the value of this property. The <em>inpad</em>
argument can be <code>H5T_PAD_ZERO</code> if the internal
padding should always be set to zero, or <code>H5T_PAD_ONE</code>
if it should always be set to one.
<code>H5Tget_inpad()</code> returns <code>H5T_PAD_ERROR</code>
on failure which is a negative value (successful return is
always non-negative).
</dl>
<h3>3.3. Properties of Date and Time Atomic Types</h3>
<p>Dates and times (<code>class=H5T_TIME</code>) are stored as
character strings in one of the ISO-8601 formats like
"<em>1997-12-05 16:25:30</em>"; as character strings using the
Unix asctime(3) format like "<em>Thu Dec 05 16:25:30 1997</em>";
as an integer value by juxtaposition of the year, month, and
day-of-month, hour, minute and second in decimal like
<em>19971205162530</em>; as an integer value in Unix time(2)
format; or other variations.
<p>I'm deferring definition until later since they're probably not
as important as the other data types.
<h3>3.4. Properties of Character String Atomic Types</h3>
<p>Fixed-length character string types are used to store textual
information. The <code>offset</code> property of a string is
always zero and the <code>precision</code> property is eight
times as large as the value returned by
<code>H5Tget_size()</code> (since precision is measured in bits
while size is measured in bytes). Both properties are
read-only.
<dl>
<dt><code>H5T_cset_t H5Tget_cset (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_cset (hid_t <em>type</em>, H5T_cset_t
<em>cset</em>)</code>
<dd>HDF5 is able to distinguish between character sets of
different nationalities and to convert between them to the
extent possible. The only character set currently supported
is <code>H5T_CSET_ASCII</code>.
<br><br>
<dt><code>H5T_str_t H5Tget_strpad (hid_t <em>type</em>)</code>
<dt><code>herr_t H5Tset_strpad (hid_t <em>type</em>, H5T_str_t
<em>strpad</em>)</code>
<dd>The method used to store character strings differs with the
programming language: C usually null terminates strings while
Fortran left-justifies and space-pads strings. This property
defines the storage mechanism and can be
<p>
<dl>
<dt><code>H5T_STR_NULLTERM</code>
<dd>A C-style string which is guaranteed to be null
terminated. When converting from a longer string the
value will be truncated and then a null character
appended.
<br><br>
<dt><code>H5T_STR_NULLPAD</code>
<dd>A C-style string which is padded with null characters
but not necessarily null terminated. Conversion from a
long string to a shorter <code>H5T_STR_NULLPAD</code>
string will truncate but not null terminate. Conversion
from a short value to a longer value will append null
characters as with <code>H5T_STR_NULLTERM</code>.
<br><br>
<dt><code>H5T_STR_SPACEPAD</code>
<dd>A Fortran-style string which is padded with space
characters. This is the same as
<code>H5T_STR_NULLPAD</code> except the padding character
is a space instead of a null.
</dl>
<p><code>H5Tget_strpad()</code> returns
<code>H5T_STR_ERROR</code> on failure, a negative value (all
successful return values are non-negative).
</dl>
<h3>3.5. Properties of Bit Field Atomic Types</h3>
<p>Converting a bit field (<code>class=H5T_BITFIELD</code>) from
one type to another simply copies the significant bits. If the
destination is smaller than the source then bits are truncated.
Otherwise new bits are filled according to the <code>msb</code>
padding type.
<h3>3.6. Properties of Opaque Atomic Types</h3>
<p>Opaque atomic types (<code>class=H5T_OPAQUE</code>) act like
bit fields except conversions which change the precision are not
allowed. However, padding can be added or removed from either
end and the bytes can be reordered. Opaque types can be used to
create novel data types not directly supported by the library,
but the application is responsible for data conversion of these
types.
<h2>4. Properties of Compound Types</h2>
<p>A compound data type is similar to a <code>struct</code> in C
or a common block in Fortran: it is a collection of one or more
atomic types or small arrays of such types. Each
<em>member</em> of a compound type has a name which is unique
within that type, and a byte offset that determines the first
byte (smallest byte address) of that member in a compound datum.
A compound data type has the following properties:
<dl>
<dt><code>H5T_class_t H5Tget_class (hid_t <em>type</em>)</code>
<dd>All compound data types belong to the type class
<code>H5T_COMPOUND</code>. This property is read-only and is
defined when a data type is created or copied (see
<code>H5Tcreate()</code> or <code>H5Tcopy()</code>).
<br><br>
<dt><code>size_t H5Tget_size (hid_t <em>type</em>)</code>
<dd>Compound data types have a total size in bytes which is
returned by this function. All members of a compound data
type must exist within this size. A value of zero is returned
for failure; all successful return values are positive.
<br><br>
<dt><code>int H5Tget_nmembers (hid_t <em>type</em>)</code>
<dd>A compound data type consists of zero or more members
(defined in any order) with unique names and which occupy
non-overlapping regions within the datum. In the functions
that follow, individual members are referenced by an index
number between zero and <em>N</em>-1, inclusive, where
<em>N</em> is the value returned by this function.
<code>H5Tget_nmembers()</code> returns -1 on failure.
<br><br>
<dt><code>char *H5Tget_member_name (hid_t <em>type</em>, int
<em>membno</em>)</code>
<dd>Each member has a name which is unique among its siblings in
a compound data type. This function returns a pointer to a
null-terminated copy of the name allocated with
<code>malloc()</code> or the null pointer on failure. The
caller is responsible for freeing the memory returned by this
function.
<br><br>
<dt><code>size_t H5Tget_member_offset (hid_t <em>type</em>, int
<em>membno</em>)</code>
<dd>The byte offset of member number <em>membno</em> with
respect to the beginning of the containing compound datum is
returned by this function. A zero is returned on failure
which is also a valid offset, but this function is guaranteed
to succeed if a call to <code>H5Tget_member_dims()</code>
succeeds when called with the same <em>type</em> and
<em>membno</em> arguments.
<br><br>
<dt><code>int H5Tget_member_dims (hid_t <em>type</em>, int
<em>membno</em>, int <em>dims</em>[4], int
<em>perm</em>[4])</code>
<dd>Each member can be a small array of up to four dimensions,
making it convenient to describe things like transposition
matrices. The dimensionality of the member is returned (or
negative for failure) and the size in each dimension is
returned through the <em>dims</em> argument. The
<em>perm</em> argument describes how the array's elements are
mapped to the linear address space of memory with respect to
some reference order (the reference order is specified in
natural language documentation which describes the compound
data type). The application which "invented" the type will
often use the identity permutation and other applications will
use a permutation that causes the elements to be rearranged to
the desired order. Only the first few elements of
<em>dims</em> and <em>perm</em> are initialized according to
the dimensionality of the member. Scalar members have
dimensionality zero.
<b>The only permutations supported at this
time are the identity permutation and the transpose
permutation (in the 4d case, {0,1,2,3} and {3,2,1,0}).</b>
<br><br>
<dt><code>hid_t H5Tget_member_type (hid_t <em>type</em>, int
<em>membno</em>)</code>
<dd>Each member has its own data type, a copy of which is
returned by this function. The returned data type identifier
should be released by eventually calling
<code>H5Tclose()</code> on that type.
</dl>
<p>Properties of members of a compound data type are
defined when the member is added to the compound type (see
<code>H5Tinsert()</code>) and cannot be subsequently modified.
This makes it imposible to define recursive data structures.
<a name="DTypes-PredefinedAtomic">
<h2>5. Predefined Atomic Data Types</h2>
</a>
<p>The library predefines a modest number of data types having
names like <code>H5T_<em>arch</em>_<em>base</em></code> where
<em>arch</em> is an architecture name and <em>base</em> is a
programming type name. New types can be derived from the
predifined types by copying the predefined type (see
<code>H5Tcopy()</code>) and then modifying the result.
<p>
<center>
<table align=center width="80%">
<tr>
<th align=left width="20%">Architecture Name</th>
<th align=left width="80%">Description</th>
</tr>
<tr valign=top>
<td><code>IEEE</code></td>
<td>This architecture defines standard floating point
types in various byte orders.</td>
</tr>
<tr valign=top>
<td><code>STD</code></td>
<td>This is an architecture that contains semi-standard
datatypes like signed two's complement integers,
unsigned integers, and bitfields in various byte
orders.</td>
</tr>
<tr valign=top>
<td><code>UNIX</code></td>
<td>Types which are specific to Unix operating systems are
defined in this architecture. The only type currently
defined is the Unix date and time types
(<code>time_t</code>).</td>
</tr>
<tr valign=top>
<td><code>C<br>FORTRAN</code></td>
<td>Types which are specific to the C or Fortran
programming languages are defined in these
architectures. For instance, <code>H5T_C_STRING</code>
defines a base string type with null termination which
can be used to derive string types of other
lengths.</td>
</tr>
<tr valign=top>
<td><code>NATIVE</code></td>
<td>This architecture contains C-like data types for the
machine on which the library was compiled. The types
were actually defined by running the
<code>H5detect</code> program when the library was
compiled. In order to be portable, applications should
almost always use this architecture to describe things
in memory.</td>
</tr>
<tr valign=top>
<td><code>CRAY</code></td>
<td>Cray architectures. These are word-addressable,
big-endian systems with non-IEEE floating point.</td>
</tr>
<tr valign=top>
<td><code>INTEL</code></td>
<td>All Intel and compatible CPU's including 80286, 80386,
80486, Pentium, Pentium-Pro, and Pentium-II. These are
little-endian systems with IEEE floating-point.</td>
</tr>
<tr valign=top>
<td><code>MIPS</code></td>
<td>All MIPS CPU's commonly used in SGI systems. These
are big-endian systems with IEEE floating-point.</td>
</tr>
<tr valign=top>
<td><code>ALPHA</code></td>
<td>All DEC Alpha CPU's, little-endian systems with IEEE
floating-point.</td>
</tr>
</table>
</center>
<p>The base name of most types consists of a letter, a precision
in bits, and an indication of the byte order. The letters are:
<p>
<center>
<table border align=center width="40%">
<tr>
<td align=center width="30%">B</td>
<td width="70%">Bitfield</td>
</tr>
<tr>
<td align=center>D</td>
<td>Date and time</td>
</tr>
<tr>
<td align=center>F</td>
<td>Floating point</td>
</tr>
<tr>
<td align=center>I</td>
<td>Signed integer</td>
</tr>
<tr>
<td align=center>R</td>
<td>References</td>
</tr>
<tr>
<td align=center>S</td>
<td>Character string</td>
</tr>
<tr>
<td align=center>U</td>
<td>Unsigned integer</td>
</tr>
</table>
</center>
<p>The byte order is a two-letter sequence:
<p>
<center>
<table border align=center width="40%">
<tr>
<td align=center width="30%">BE</td>
<td width="70%">Big endian</td>
</tr>
<tr>
<td align=center>LE</td>
<td>Little endian</td>
</tr>
<tr>
<td align=center>VX</td>
<td>Vax order</td>
</tr>
</table>
</center>
<p>
<center>
<table align=center width="80%">
<tr>
<th align=left><br><br>Example</th>
<th align=left><br><br>Description</th>
</tr>
<tr valign=top>
<td><code>H5T_IEEE_F64LE</code></td>
<td>Eight-byte, little-endian, IEEE floating-point</td>
</tr>
<tr valign=top>
<td><code>H5T_IEEE_F32BE</code></td>
<td>Four-byte, big-endian, IEEE floating point</td>
</tr>
<tr valign=top>
<td><code>H5T_STD_I32LE</code></td>
<td>Four-byte, little-endian, signed two's complement integer</td>
</tr>
<tr valign=top>
<td><code>H5T_STD_U16BE</code></td>
<td>Two-byte, big-endian, unsigned integer</td>
</tr>
<tr valign=top>
<td><code>H5T_UNIX_D32LE</code></td>
<td>Four-byte, little-endian, time_t</td>
</tr>
<tr valign=top>
<td><code>H5T_C_S1</code></td>
<td>One-byte, null-terminated string of eight-bit characters</td>
</tr>
<tr valign=top>
<td><code>H5T_INTEL_B64</code></td>
<td>Eight-byte bit field on an Intel CPU</td>
</tr>
<tr valign=top>
<td><code>H5T_CRAY_F64</code></td>
<td>Eight-byte Cray floating point</td>
</tr>
<tr valign=top>
<td><code>H5T_STD_ROBJ</code></td>
<td>Reference to an entire object in a file</td>
</tr>
</table>
</center>
<p>The <code>NATIVE</code> architecture has base names which don't
follow the same rules as the others. Instead, native type names
are similar to the C type names. Here are some examples:
<p>
<center>
<table align=center width="80%">
<tr>
<th align=left><br><br>Example</th>
<th align=left><br><br>Corresponding C Type</th>
</tr>
<tr>
<td><code>H5T_NATIVE_CHAR</code></td>
<td><code>char</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_SCHAR</code></td>
<td><code>signed char</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_UCHAR</code></td>
<td><code>unsigned char</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_SHORT</code></td>
<td><code>short</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_USHORT</code></td>
<td><code>unsigned short</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_INT</code></td>
<td><code>int</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_UINT</code></td>
<td><code>unsigned</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_LONG</code></td>
<td><code>long</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_ULONG</code></td>
<td><code>unsigned long</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_LLONG</code></td>
<td><code>long long</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_ULLONG</code></td>
<td><code>unsigned long long</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_FLOAT</code></td>
<td><code>float</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_DOUBLE</code></td>
<td><code>double</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_LDOUBLE</code></td>
<td><code>long double</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_HSIZE</code></td>
<td><code>hsize_t</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_HSSIZE</code></td>
<td><code>hssize_t</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_HERR</code></td>
<td><code>herr_t</code></td>
</tr>
<tr>
<td><code>H5T_NATIVE_HBOOL</code></td>
<td><code>hbool_t</code></td>
</tr>
</table>
</center>
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: A 128-bit
integer</h4></caption>
<tr>
<td>
<p>To create a 128-bit, little-endian signed integer
type one could use the following (increasing the
precision of a type automatically increases the total
size):
<p><code><pre>
hid_t new_type = H5Tcopy (H5T_NATIVE_INT);
H5Tset_precision (new_type, 128);
H5Tset_order (new_type, H5T_ORDER_LE);
</pre></code>
</td>
</tr>
</table>
</center>
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: An 80-character
string</h4></caption>
<tr>
<td>
<p>To create an 80-byte null terminated string type one
might do this (the offset of a character string is
always zero and the precision is adjusted
automatically to match the size):
<p><code><pre>
hid_t str80 = H5Tcopy (H5T_C_S1);
H5Tset_size (str80, 80);
</pre></code>
</td>
</tr>
</table>
</center>
<h2>6. Defining Compound Data Types</h2>
<p>Unlike atomic data types which are derived from other atomic
data types, compound data types are created from scratch. First,
one creates an empty compound data type and specifies it's total
size. Then members are added to the compound data type in any
order.
<p>Usually a C struct will be defined to hold a data point in
memory, and the offsets of the members in memory will be the
offsets of the struct members from the beginning of an instance
of the struct.
<dl>
<dt><code>HOFFSET(s,m)</code>
<dd>This macro computes the offset of member <em>m</em> within
a struct <em>s</em>.
<dt><code>offsetof(s,m)</code>
<dd>This macro defined in <code>stddef.h</code> does
exactly the same thing as the <code>HOFFSET()</code> macro.
</dl>
<p>Each member must have a descriptive name which is the
key used to uniquely identify the member within the compound
data type. A member name in an HDF5 data type does not
necessarily have to be the same as the name of the member in the
C struct, although this is often the case. Nor does one need to
define all members of the C struct in the HDF5 compound data
type (or vice versa).
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: A simple struct</h4></caption>
<tr>
<td>
<p>An HDF5 data type is created to describe complex
numbers whose type is defined by the
<code>complex_t</code> struct.
<p><code><pre>
typedef struct {
double re; /*real part*/
double im; /*imaginary part*/
} complex_t;
hid_t complex_id = H5Tcreate (H5T_COMPOUND, sizeof tmp);
H5Tinsert (complex_id, "real", HOFFSET(complex_t,re),
H5T_NATIVE_DOUBLE);
H5Tinsert (complex_id, "imaginary", HOFFSET(complex_t,im),
H5T_NATIVE_DOUBLE);
</pre></code>
</td>
</tr>
</table>
</center>
<p>Member alignment is handled by the <code>HOFFSET</code>
macro. However, data stored on disk does not require alignment,
so unaligned versions of compound data structures can be created
to improve space efficiency on disk. These unaligned compound
data types can be created by computing offsets by hand to
eliminate inter-member padding, or the members can be packed by
calling <code>H5Tpack()</code> (which modifies a data type
directly, so it is usually preceded by a call to
<code>H5Tcopy()</code>):
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: A packed struct</h4></caption>
<tr>
<td>
<p>This example shows how to create a disk version of a
compound data type in order to store data on disk in
as compact a form as possible. Packed compound data
types should generally not be used to describe memory
as they may violate alignment constraints for the
architecture being used. Note also that using a
packed data type for disk storage may involve a higher
data conversion cost.
<p><code><pre>
hid_t complex_disk_id = H5Tcopy (complex_id);
H5Tpack (complex_disk_id);
</pre></code>
</td>
</tr>
</table>
</center>
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: A flattened struct</h4></caption>
<tr>
<td>
<p>Compound data types that have a compound data type
member can be handled two ways. This example shows
that the compound data type can be flattened,
resulting in a compound type with only atomic
members.
<p><code><pre>
typedef struct {
complex_t x;
complex_t y;
} surf_t;
hid_t surf_id = H5Tcreate (H5T_COMPOUND, sizeof tmp);
H5Tinsert (surf_id, "x-re", HOFFSET(surf_t,x.re),
H5T_NATIVE_DOUBLE);
H5Tinsert (surf_id, "x-im", HOFFSET(surf_t,x.im),
H5T_NATIVE_DOUBLE);
H5Tinsert (surf_id, "y-re", HOFFSET(surf_t,y.re),
H5T_NATIVE_DOUBLE);
H5Tinsert (surf_id, "y-im", HOFFSET(surf_t,y.im),
H5T_NATIVE_DOUBLE);
</code></pre>
</td>
</tr>
</table>
</center>
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: A nested struct</h4></caption>
<tr>
<td>
<p>However, when the <code>complex_t</code> is used
often it becomes inconvenient to list its members over
and over again. So the alternative approach to
flattening is to define a compound data type and then
use it as the type of the compound members, as is done
here (the typedefs are defined in the previous
examples).
<p><code><pre>
hid_t complex_id, surf_id; /*hdf5 data types*/
complex_id = H5Tcreate (H5T_COMPOUND, sizeof c);
H5Tinsert (complex_id, "re", HOFFSET(complex_t,re),
H5T_NATIVE_DOUBLE);
H5Tinsert (complex_id, "im", HOFFSET(complex_t,im),
H5T_NATIVE_DOUBLE);
surf_id = H5Tcreate (H5T_COMPOUND, sizeof s);
H5Tinsert (surf_id, "x", HOFFSET(surf_t,x), complex_id);
H5Tinsert (surf_id, "y", HOFFSET(surf_t,y), complex_id);
</code></pre>
</td>
</tr>
</table>
</center>
<h2>7. Sharing Data Types among Datasets</h2>
<p>If a file has lots of datasets which have a common data type
then the file could be made smaller by having all the datasets
share a single data type. Instead of storing a copy of the data
type in each dataset object header, a single data type is stored
and the object headers point to it. The space savings is
probably only significant for datasets with a compound data type
since the simple data types can be described with just a few
bytes anyway.
<p>To create a bunch of datasets that share a single data type
just create the datasets with a committed (named) data type.
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: Shared Types</h4></caption>
<tr>
<td>
<p>To create two datasets that share a common data type
one just commits the data type, giving it a name, and
then uses that data type to create the datasets.
<p><code><pre>
hid_t t1 = ...some transient type...;
H5Tcommit (file, "shared_type", t1);
hid_t dset1 = H5Dcreate (file, "dset1", t1, space, H5P_DEFAULT);
hid_t dset2 = H5Dcreate (file, "dset2", t1, space, H5P_DEFAULT);
</code></pre>
<p>And to create two additional datasets later which
share the same type as the first two datasets:
<p><code><pre>
hid_t dset1 = H5Dopen (file, "dset1");
hid_t t2 = H5Dget_type (dset1);
hid_t dset3 = H5Dcreate (file, "dset3", t2, space, H5P_DEFAULT);
hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT);
</code></pre>
</td>
</tr>
</table>
</center>
<a name="Datatypes-DataConversion">
<h2>8. Data Conversion</h2>
</a>
<p>The library is capable of converting data from one type to
another and does so automatically when reading or writing the
raw data of a dataset, attribute data, or fill values. The
application can also change the type of data stored in an array.
<p>In order to insure that data conversion exceeds disk I/O rates,
common data conversion paths can be hand-tuned and optimized for
performance. The library contains very efficient code for
conversions between most native data types and a few non-native
data types, but if a hand-tuned conversion function is not
available, then the library falls back to a slower but more
general conversion function. The application programmer can
define additional conversion functions when the libraries
repertoire is insufficient. In fact, if an application does
define a conversion function which would be of general interest,
we request that the function be submitted to the HDF5
development team for inclusion in the library.
<p><b>Note:</b> The HDF5 library contains a deliberately limited
set of conversion routines. It can convert from one integer
format to another, from one floating point format to another,
and from one struct to another. It can also perform byte
swapping when the source and destination types are otherwise the
same. The library does not contain any functions for converting
data between integer and floating point formats. It is
anticipated that some users will find it necessary to develop
float to integer or integer to float conversion functions at the
application level; users are invited to submit those functions
to be considered for inclusion in future versions of the
library.
<p>A conversion path contains a source and destination data type
and each path contains a <em>hard</em> conversion function
and/or a <em>soft</em> conversion function. The only difference
between hard and soft functions is the way in which the library
chooses which function applies: A hard function applies to a
specific conversion path while a soft function may apply to
multiple paths. When both hard and soft functions apply to a
conversion path, then the hard function is favored and when
multiple soft functions apply, the one defined last is favored.
<p>A data conversion function is of type <code>H5T_conv_t</em>
which is defined as:
<p>
<code><pre>
typedef herr_t (*H5T_conv_t)(hid_t <em>src_type</em>,
hid_t <em>dest_type</em>,
H5T_cdata_t *<em>cdata</em>,
size_t <em>nelmts</em>,
void *<em>buffer</em>,
void *<em>background</em>);
</pre></code>
<p>The conversion function is called with the source and
destination data types (<em>src_type</em> and
<em>dst_type</em>), path-constant data (<em>cdata</em>), the
number of instances of the data type to convert
(<em>nelmts</em>), a buffer which initially contains an array of
data having the source type and on return will contain an array
of data having the destination type (<em>buffer</em>), and a
temporary or background buffer (<em>background</em>). Functions
return a negative value on failure and some other value on
success.
<p>The <code>command</code> field of the <em>cdata</em> argument
determines what happens within the conversion function. It's
values can be:
<dl>
<dt><code>H5T_CONV_INIT</code>
<dd>This command is to hard conversion functions when they're
registered or soft conversion functions when the library is
determining if a conversion can be used for a particular path.
The <em>src_type</em> and <em>dst_type</em> are the end-points
of the path being queried and <em>cdata</em> is all zero. The
library should examine the source and destination types and
return zero if the conversion is possible and negative
otherwise (hard conversions need not do this since they've
presumably been registered only on paths they support). If
the conversion is possible the library may allocate and
initialize private data and assign the pointer to the
<code>priv</code> field of <em>cdata</em> (or private data can
be initialized later). It should also initialize the
<code>need_bkg</code> field described below. The <em>buf</em>
and <em>background</em> pointers will be null pointers.
<br><br>
<dt><code>H5T_CONV_CONV</code>
<dd>This command indicates that data points should be converted.
The conversion function should initialize the
<code>priv</code> field of <em>cdata</em> if it wasn't
initialize during the <code>H5T_CONV_INIT</code> command and
then convert <em>nelmts</em> instances of the
<em>src_type</em> to the <em>dst_type</em>. The
<em>buffer</em> serves as both input and output. The
<em>background</em> buffer is supplied according to the value
of the <code>need_bkg</code> field of <em>cdata</em> (the
values are described below).
<br><br>
<dt><code>H5T_CONV_FREE</code>
<dd>The conversion function is about to be removed from some
path and the private data (the
<code><em>cdata</em>->priv</code> pointer) should be freed and
set to null. All other pointer arguments are null, the
<em>src_type</em> and <em>dst_type</em> are invalid
(negative), and the <em>nelmts</em> argument is zero.
<br><br>
<dt><em>Others...</em>
<dd>Other commands might be implemented later and conversion
functions that don't support those commands should return a
negative value.
</dl>
<p>Whether a background buffer is supplied to a conversion
function, and whether the background buffer is initialized
depends on the value of <code><em>cdata</em>->need_bkg</code>
which the conversion function should have initialized during the
H5T_CONV_INIT command. It can have one of these values:
<dl>
<dt><code>H5T_BKG_NONE</code>
<dd>No background buffer will be supplied to the conversion
function. This is the default.
<br><br>
<dt><code>H5T_BKG_TEMP</code>
<dd>A background buffer will be supplied but it will not be
initialized. This is useful for those functions requiring some
extra buffer space as the buffer can probably be allocated
more efficiently by the library (the application can supply
the buffer as part of the dataset transfer property list).
<br><br>
<dt><code>H5T_BKG_YES</code>
<dd>An initialized background buffer is passed to the conversion
function. The buffer is initialized with the current values
of the destination for the data which is passed in through the
<em>buffer</em> argument. It can be used to "fill in between
the cracks". For instance, if the destination type is a
compound data type and we are initializing only part of the
compound data type from the source type then the background
buffer can be used to initialize the other part of the
destination.
</dl>
<p>The <code>recalc</code> field of <em>cdata</em> is set when the
conversion path table changes. It can be used by conversion
function that cache other conversion paths so they know when
their cache needs to be recomputed.
<p>Once a conversion function is written it can be registered and
unregistered with these functions:
<dl>
<dt><code>herr_t H5Tregister(H5T_pers_t <em>pers</em>, const
char *<em>name</em>, hid_t <em>src_type</em>, hid_t
<em>dest_type</em>, H5T_conv_t <em>func</em>)</code>
<dd>Once a conversion function is written, the library must be
notified so it can be used. The function can be registered as
a hard (<code>H5T_PERS_HARD</code>) or soft
(<code>H5T_PERS_SOFT</code>) conversion depending on the value
of <em>pers</em>, displacing any previous conversions for all
applicable paths. The <em>name</em> is used only for
debugging but must be supplied. If <em>pers</em> is
<code>H5T_PERS_SOFT</code> then only the type classes of the
<em>src_type</em> and <em>dst_type</em> are used. For
instance, to register a general soft conversion function that
can be applied to any integer to integer conversion one could
say: <code>H5Tregister(H5T_PERS_SOFT, "i2i", H5T_NATIVE_INT,
H5T_NATIVE_INT, convert_i2i)</code>. One special conversion
path called the "no-op" conversion path is always defined by
the library and used as the conversion function when no data
transformation is necessary. The application can redefine this
path by specifying a new hard conversion function with a
negative value for both the source and destination data types,
but the library might not call the function under certain
circumstances.
<br><br>
<dt><code>herr_t H5Tunregister (H5T_pers_t <em>pers</em>, const
char *<em>name</em>, hid_t <em>src_type</em>, hid_t
<em>dest_type</em>, H5T_conv_t <em>func</em>)</code>
<dd>Any conversion path or function that matches the critera
specified by a call to this function is removed from the type
conversion table. All fields have the same interpretation as
for <code>H5Tregister()</code> with the added feature that any
(or all) may be wild cards. The
<code>H5T_PERS_DONTCARE</code> constant should be used to
indicate a wild card for the <em>pers</em> argument. The wild
card <em>name</em> is the null pointer or empty string, the
wild card for the <em>src_type</em> and <em>dest_type</em>
arguments is any negative value, and the wild card for the
<em>func</em> argument is the null pointer. The special no-op
conversion path is never removed by this function.
</dl>
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: A conversion
function</h4></caption>
<tr>
<td>
<p>Here's an example application-level function that
converts Cray <code>unsigned short</code> to any other
16-bit unsigned big-endian integer. A cray
<code>short</code> is a big-endian value which has 32
bits of precision in the high-order bits of a 64-bit
word.
<p><code><pre>
1 typedef struct {
2 size_t dst_size;
3 int direction;
4 } cray_ushort2be_t;
5
6 herr_t
7 cray_ushort2be (hid_t src, hid_t dst,
8 H5T_cdata_t *cdata,
9 size_t nelmts, void *buf,
10 const void *background)
11 {
12 unsigned char *src = (unsigned char *)buf;
13 unsigned char *dst = src;
14 cray_ushort2be_t *priv = NULL;
15
16 switch (cdata->command) {
17 case H5T_CONV_INIT:
18 /*
19 * We are being queried to see if we handle this
20 * conversion. We can handle conversion from
21 * Cray unsigned short to any other big-endian
22 * unsigned integer that doesn't have padding.
23 */
24 if (!H5Tequal (src, H5T_CRAY_USHORT) ||
25 H5T_ORDER_BE != H5Tget_order (dst) ||
26 H5T_SGN_NONE != H5Tget_signed (dst) ||
27 8*H5Tget_size (dst) != H5Tget_precision (dst)) {
28 return -1;
29 }
30
31 /*
32 * Initialize private data. If the destination size
33 * is larger than the source size, then we must
34 * process the elements from right to left.
35 */
36 cdata->priv = priv = malloc (sizeof(cray_ushort2be_t));
37 priv->dst_size = H5Tget_size (dst);
38 if (priv->dst_size>8) {
39 priv->direction = -1;
40 } else {
41 priv->direction = 1;
42 }
43 break;
44
45 case H5T_CONV_FREE:
46 /*
47 * Free private data.
48 */
49 free (cdata->priv);
50 cdata->priv = NULL;
51 break;
52
53 case H5T_CONV_CONV:
54 /*
55 * Convert each element, watch out for overlap src
56 * with dst on the left-most element of the buffer.
57 */
58 priv = (cray_ushort2be_t *)(cdata->priv);
59 if (priv->direction<0) {
60 src += (nelmts - 1) * 8;
61 dst += (nelmts - 1) * dst_size;
62 }
63 for (i=0; i<n; i++) {
64 if (src==dst && dst_size<4) {
65 for (j=0; j<dst_size; j++) {
66 dst[j] = src[j+4-dst_size];
67 }
68 } else {
69 for (j=0; j<4 && j<dst_size; j++) {
70 dst[dst_size-(j+1)] = src[3-j];
71 }
72 for (j=4; j<dst_size; j++) {
73 dst[dst_size-(j+1)] = 0;
74 }
75 }
76 src += 8 * direction;
77 dst += dst_size * direction;
78 }
79 break;
80
81 default:
82 /*
83 * Unknown command.
84 */
85 return -1;
86 }
87 return 0;
88 }
</pre></code>
<p>The <em>background</em> argument is ignored since
it's generally not applicable to atomic data types.
</td>
</tr>
</table>
</center>
<p>
<center>
<table border align=center width="100%">
<caption align=bottom><h4>Example: Soft
Registration</h4></caption>
<tr>
<td>
<p>The convesion function described in the previous
example applies to more than one conversion path.
Instead of enumerating all possible paths, we register
it as a soft function and allow it to decide which
paths it can handle.
<p><code><pre>
H5Tregister(H5T_PERS_SOFT, "cus2be",
H5T_NATIVE_INT, H5T_NATIVE_INT,
cray_ushort2be);
</pre></code>
<p>This causes it to be consulted for any conversion
from an integer type to another integer type. The
first argument is just a short identifier which will
be printed with the data type conversion statistics.
</td>
</tr>
</table>
</center>
<p><b>NOTE:</b> The idea of a master soft list and being able to
query conversion functions for their abilities tries to overcome
problems we saw with AIO. Namely, that there was a dichotomy
between generic conversions and specific conversions that made
it very difficult to write a conversion function that operated
on, say, integers of any size and order as long as they don't
have zero padding. The AIO mechanism required such a function
to be explicitly registered (like
<code>H5Tregister_hard()</code>) for each an every possible
conversion path whether that conversion path was actually used
or not.
<hr>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
</address>
<!-- Created: Thu Dec 4 14:57:32 EST 1997 -->
<!-- hhmts start -->
Last modified: Wed Dec 16 13:04:58 EST 1998
<!-- hhmts end -->
</body>
</html>
|
