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
|
<html xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:w="urn:schemas-microsoft-com:office:word"
xmlns:st1="urn:schemas-microsoft-com:office:smarttags"
xmlns="http://www.w3.org/TR/REC-html40">
<head>
<!--
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* Copyright by the Board of Trustees of the University of Illinois. *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the files COPYING and Copyright.html. COPYING can be found at the root *
* of the source code distribution tree; Copyright.html can be found at the *
* root level of an installed copy of the electronic HDF5 document set and *
* is linked from the top-level documents page. It can also be found at *
* http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
* access to either file, you may request a copy from help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-->
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<meta name=ProgId content=Word.Document>
<meta name=Generator content="Microsoft Word 10">
<meta name=Originator content="Microsoft Word 10">
<!-- <link rel=File-List href="Data_Transforms_Report_files/filelist.xml"> -->
<title>Arithmetic Data Transforms</title>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="date"/>
<!--[if gte mso 9]><xml>
<o:DocumentProperties>
<o:Author>install</o:Author>
<o:Template>Normal</o:Template>
<o:LastAuthor>Albert Cheng</o:LastAuthor>
<o:Revision>4</o:Revision>
<o:TotalTime>212</o:TotalTime>
<o:LastPrinted>2004-12-10T21:28:00Z</o:LastPrinted>
<o:Created>2004-12-10T22:44:00Z</o:Created>
<o:LastSaved>2004-12-16T00:13:00Z</o:LastSaved>
<o:Pages>1</o:Pages>
<o:Words>1721</o:Words>
<o:Characters>9815</o:Characters>
<o:Company>UIUC</o:Company>
<o:Lines>81</o:Lines>
<o:Paragraphs>23</o:Paragraphs>
<o:CharactersWithSpaces>11513</o:CharactersWithSpaces>
<o:Version>10.2625</o:Version>
</o:DocumentProperties>
</xml><![endif]--><!--[if gte mso 9]><xml>
<w:WordDocument>
<w:View>Print</w:View>
<w:Zoom>105</w:Zoom>
<w:PunctuationKerning/>
<w:Compatibility>
<w:BreakWrappedTables/>
<w:SnapToGridInCell/>
<w:ApplyBreakingRules/>
<w:WrapTextWithPunct/>
<w:UseAsianBreakRules/>
<w:UseFELayout/>
</w:Compatibility>
<w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
</w:WordDocument>
</xml><![endif]--><!--[if !mso]><object
classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object>
<style>
st1\:*{behavior:url(#ieooui) }
</style>
<![endif]-->
<style>
<!--
/* Font Definitions */
@font-face
{font-family:Courier;
panose-1:2 7 4 9 2 2 5 2 4 4;
mso-font-alt:"Courier New";
mso-font-charset:0;
mso-generic-font-family:modern;
mso-font-format:other;
mso-font-pitch:fixed;
mso-font-signature:3 0 0 0 1 0;}
@font-face
{font-family:SimSun;
panose-1:2 1 6 0 3 1 1 1 1 1;
mso-font-alt:\5B8B\4F53;
mso-font-charset:134;
mso-generic-font-family:auto;
mso-font-pitch:variable;
mso-font-signature:3 135135232 16 0 262145 0;}
@font-face
{font-family:"\@SimSun";
panose-1:2 1 6 0 3 1 1 1 1 1;
mso-font-charset:134;
mso-generic-font-family:auto;
mso-font-pitch:variable;
mso-font-signature:3 135135232 16 0 262145 0;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{mso-style-parent:"";
margin:0in;
margin-bottom:.0001pt;
mso-pagination:widow-orphan;
font-size:12.0pt;
font-family:"Times New Roman";
mso-fareast-font-family:"Times New Roman";
mso-fareast-language:EN-US;}
h1
{mso-style-next:Normal;
margin-top:12.0pt;
margin-right:0in;
margin-bottom:3.0pt;
margin-left:0in;
mso-pagination:widow-orphan;
page-break-after:avoid;
mso-outline-level:1;
font-size:16.0pt;
font-family:Arial;
mso-font-kerning:16.0pt;
mso-fareast-language:EN-US;}
h2
{mso-style-next:Normal;
margin-top:12.0pt;
margin-right:0in;
margin-bottom:3.0pt;
margin-left:0in;
mso-pagination:widow-orphan;
page-break-after:avoid;
mso-outline-level:2;
font-size:14.0pt;
font-family:Arial;
mso-fareast-language:EN-US;
font-style:italic;}
p.MsoFootnoteText, li.MsoFootnoteText, div.MsoFootnoteText
{mso-style-noshow:yes;
margin:0in;
margin-bottom:.0001pt;
mso-pagination:widow-orphan;
font-size:10.0pt;
font-family:"Times New Roman";
mso-fareast-font-family:"Times New Roman";
mso-fareast-language:EN-US;}
p.MsoHeader, li.MsoHeader, div.MsoHeader
{margin:0in;
margin-bottom:.0001pt;
mso-pagination:widow-orphan;
tab-stops:center 3.0in right 6.0in;
font-size:12.0pt;
font-family:"Times New Roman";
mso-fareast-font-family:"Times New Roman";
mso-fareast-language:EN-US;}
p.MsoFooter, li.MsoFooter, div.MsoFooter
{margin:0in;
margin-bottom:.0001pt;
mso-pagination:widow-orphan;
tab-stops:center 3.0in right 6.0in;
font-size:12.0pt;
font-family:"Times New Roman";
mso-fareast-font-family:"Times New Roman";
mso-fareast-language:EN-US;}
span.MsoFootnoteReference
{mso-style-noshow:yes;
vertical-align:super;}
/* Page Definitions */
@page
{mso-footnote-separator:url("Data_Transforms_Report_files/header.htm") fs;
mso-footnote-continuation-separator:url("Data_Transforms_Report_files/header.htm") fcs;
mso-endnote-separator:url("Data_Transforms_Report_files/header.htm") es;
mso-endnote-continuation-separator:url("Data_Transforms_Report_files/header.htm") ecs;}
@page Section1
{size:8.5in 11.0in;
margin:1.0in 1.25in 1.0in 1.25in;
mso-header-margin:.5in;
mso-footer-margin:.5in;
mso-even-footer:url("Data_Transforms_Report_files/header.htm") ef1;
mso-footer:url("Data_Transforms_Report_files/header.htm") f1;
mso-paper-source:0;}
div.Section1
{page:Section1;}
/* List Definitions */
@list l0
{mso-list-id:270281622;
mso-list-template-ids:-1038041382;}
@list l1
{mso-list-id:332993863;
mso-list-type:hybrid;
mso-list-template-ids:1458465098 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l1:level1
{mso-level-tab-stop:.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level2
{mso-level-tab-stop:1.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level3
{mso-level-tab-stop:1.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level4
{mso-level-tab-stop:2.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level5
{mso-level-tab-stop:2.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level6
{mso-level-tab-stop:3.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level7
{mso-level-tab-stop:3.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level8
{mso-level-tab-stop:4.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l1:level9
{mso-level-tab-stop:4.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2
{mso-list-id:550459489;
mso-list-type:hybrid;
mso-list-template-ids:1085822362 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l2:level1
{mso-level-tab-stop:.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level2
{mso-level-tab-stop:1.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level3
{mso-level-tab-stop:1.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level4
{mso-level-tab-stop:2.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level5
{mso-level-tab-stop:2.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level6
{mso-level-tab-stop:3.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level7
{mso-level-tab-stop:3.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level8
{mso-level-tab-stop:4.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l2:level9
{mso-level-tab-stop:4.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l3
{mso-list-id:756709709;
mso-list-template-ids:-1385235826;}
@list l4
{mso-list-id:1187134103;
mso-list-type:hybrid;
mso-list-template-ids:1324645902 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l4:level1
{mso-level-tab-stop:.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level2
{mso-level-tab-stop:1.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level3
{mso-level-tab-stop:1.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level4
{mso-level-tab-stop:2.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level5
{mso-level-tab-stop:2.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level6
{mso-level-tab-stop:3.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level7
{mso-level-tab-stop:3.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level8
{mso-level-tab-stop:4.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l4:level9
{mso-level-tab-stop:4.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5
{mso-list-id:1433163999;
mso-list-type:hybrid;
mso-list-template-ids:-438374070 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l5:level1
{mso-level-tab-stop:.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level2
{mso-level-tab-stop:1.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level3
{mso-level-tab-stop:1.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level4
{mso-level-tab-stop:2.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level5
{mso-level-tab-stop:2.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level6
{mso-level-tab-stop:3.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level7
{mso-level-tab-stop:3.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level8
{mso-level-tab-stop:4.0in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l5:level9
{mso-level-tab-stop:4.5in;
mso-level-number-position:left;
text-indent:-.25in;}
@list l6
{mso-list-id:1929534752;
mso-list-template-ids:-760440376;}
@list l7
{mso-list-id:2059475982;
mso-list-template-ids:658286432;}
ol
{margin-bottom:0in;}
ul
{margin-bottom:0in;}
-->
</style>
<!--[if gte mso 10]>
<style>
/* Style Definitions */
table.MsoNormalTable
{mso-style-name:"Table Normal";
mso-tstyle-rowband-size:0;
mso-tstyle-colband-size:0;
mso-style-noshow:yes;
mso-style-parent:"";
mso-padding-alt:0in 5.4pt 0in 5.4pt;
mso-para-margin:0in;
mso-para-margin-bottom:.0001pt;
mso-pagination:widow-orphan;
font-size:10.0pt;
font-family:"Times New Roman";}
</style>
<![endif]--><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="3074"/>
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1"/>
</o:shapelayout></xml><![endif]-->
</head>
<body lang=EN-US style='tab-interval:.5in'>
<div class=Section1>
<p class=MsoNormal align=center style='text-align:center'><b><span
style='font-size:16.0pt'>Arithmetic Data Transforms<o:p></o:p></span></b></p>
<p class=MsoNormal align=center style='text-align:center'>Leon Arber, Albert
Cheng, William Wendling<a style='mso-footnote-id:ftn1' href="#_ftn1"
name="_ftnref1" title=""><span class=MsoFootnoteReference><span
style='mso-special-character:footnote'><![if !supportFootnotes]><span
class=MsoFootnoteReference><span style='font-size:12.0pt;font-family:"Times New Roman";
mso-fareast-font-family:"Times New Roman";mso-ansi-language:EN-US;mso-fareast-language:
EN-US;mso-bidi-language:AR-SA'>[1]</span></span><![endif]></span></span></a></p>
<p class=MsoNormal align=center style='text-align:center'><st1:date Year="2004"
Day="10" Month="12">December 10, 2004</st1:date></p>
<h1>Purpose</h1>
<p class=MsoNormal>Data can be stored and represented in many different
ways.<span style='mso-spacerun:yes'> </span>In most fields of science, for
example, the metric system is used for storing all data.<span
style='mso-spacerun:yes'> </span>However, many fields of engineering still use
the English system.<span style='mso-spacerun:yes'> </span>In such scenarios,
there needs to be a way to easily perform arbitrary scaling of data.<span
style='mso-spacerun:yes'> </span>The data transforms provide just such
functionality.<span style='mso-spacerun:yes'> </span>They allow arbitrary
arithmetic expressions to be applied to a dataset during read and write
operations.<span style='mso-spacerun:yes'> </span>This means that data can be
stored in Celsius in a data file, but read in and automatically converted to
Fahrenheit.<span style='mso-spacerun:yes'> </span>Alternatively, data that is
obtained in Fahrenheit can be written out to the data file in Celsius.<span
style='mso-spacerun:yes'> </span></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Although a user can always manually modify the data they
read and write, having the data transform as a property means that the user
doesnt have to worry about forgetting to call the conversion function or even
writing it in the first place.</p>
<p class=MsoNormal><o:p> </o:p></p>
<h1>Usage</h1>
<p class=MsoNormal>The data transform functionality is implemented as a
property that is set on a dataset transfer property list.<span
style='mso-spacerun:yes'> </span>There are two functions available: one for
setting the transform and another for finding out what transform, if any, is
currently set.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>The function for setting the transform is:</p>
<p class=MsoNormal><span style='font-size:10.0pt;font-family:"Courier New"'>herr_t
H5Pset_data_transform(hid_t plist_id, const char* expression)<o:p></o:p></span></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><span style='font-size:10.0pt;font-family:"Courier New"'>plist_id
</span>is the identifier of the dataset transfer property list on which the
data transform property should be set.</p>
<p class=MsoNormal><span style='font-size:10.0pt;font-family:"Courier New"'>expression
</span>is a pointer to a string of the form (5/9.0)*(x-32) which describes
the transform.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>The function for getting the transform is: </p>
<p class=MsoNormal><span style='font-size:10.0pt;font-family:"Courier New"'>ssize_t
H5Pget_data_transform(hid_t plist_id, char* expression, size_t size)<o:p></o:p></span></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><span style='font-size:10.0pt;font-family:"Courier New"'>plist_id
</span>is the identifier of the dataset transfer property list which will be
queried for its data transform property.</p>
<p class=MsoNormal><span style='font-size:10.0pt;font-family:"Courier New"'>expression
</span>is either NULL or a pointer to memory where the data transform string,
if present, will be copied.</p>
<p class=MsoNormal><span style='font-size:10.0pt;font-family:"Courier New"'>size
</span>is the number of bytes to copy from the transform string into
expression. <span style='mso-spacerun:yes'></span>H5Pget_data_transform will
never copy more than the length of the transform expression.</p>
<p class=MsoNormal><o:p> </o:p></p>
<h1>Data Transform Expressions</h1>
<p class=MsoNormal>Data transforms are set by passing a pointer to a string,
which is the data transform expression.<span style='mso-spacerun:yes'>
</span>This string describes what sort of arithmetic transform should be done
during data transfer of read or write.<span style='mso-spacerun:yes'>
</span>The string is a standard mathematical expression, as would be entered
into a something like MATLAB.<span style='mso-spacerun:yes'> </span></p>
<p class=MsoNormal>Expressions are defined by the following context-free
grammar:</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>expr:=<span style='mso-spacerun:yes'> </span>term | term +
term | term - term</p>
<p class=MsoNormal>term := factor | factor * factor | factor / factor</p>
<p class=MsoNormal>factor :=<span style='mso-spacerun:yes'> </span>number |
symbol | - factor | + factor | ( expr )</p>
<p class=MsoNormal>symbol := [a-zA-Z][a-zA-Z0-9]*</p>
<p class=MsoNormal>number := INT | FLOAT</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>where INT is interpreted as a C long int and FLOAT is interpreted
as a C double</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>This grammar allows for order of operations (multiplication
and dividision take precedence over addition and subtraction), floating and
integer constants, and grouping of terms by way of parentheses.<span
style='mso-spacerun:yes'> </span>Although the grammar allows symbols to be
arbitrary strings, this documentation will always use x for symbols.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Within a transform expression, the symbol represents a
variable which contains the data to be manipulated.<span
style='mso-spacerun:yes'> </span>For this reason, the terms symbol and
variable will be used interchangeably.<span style='mso-spacerun:yes'>
</span>Furthermore, in the current implementation of data transforms, all
symbols appearing in an expression are interpreted as referring to the same
dataset.<span style='mso-spacerun:yes'> </span>So, an expression such as
alpha + 5 is equivalent to x+5 and an expression such as alpha + 3*beta +
5 is equivalent to alpha + 3*alpha + 5 which is equivalent to 4*x +
5.<span style='mso-spacerun:yes'> </span></p>
<p class=MsoNormal><o:p> </o:p></p>
<h1>Data Transform Implementation</h1>
<p class=MsoNormal>When the data transform property of a dataset transfer
property list is set, a parse tree of the expression is immediately generated
and its root is saved in the property list.<span style='mso-spacerun:yes'>
</span>The generation of the parse involves several steps.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>First, the expression is reduced, so as to simply the final
parse and speed up the transform operations.<span style='mso-spacerun:yes'>
</span>Expressions such as (5/9.0) * (x-32) will be reduced to
.555555*(x-32).<span style='mso-spacerun:yes'> </span>While further
simplification is algebraically possible, the data transform code will only
reduce simple trivial arithmetic operations.<span style='mso-spacerun:yes'>
</span></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Then, this reduced expression is parsed into a set of
tokens, from which the parse tree is generated.<span style='mso-spacerun:yes'>
</span>From the expression (5/9.0)*(x-32), for example, the following parse
tree would be created:</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><span style='mso-tab-count:4'> </span><span
style='mso-spacerun:yes'> </span>*</p>
<p class=MsoNormal><span style='mso-tab-count:4'> </span>/<span
style='mso-tab-count:1'> </span>\<span style='mso-spacerun:yes'>
</span></p>
<p class=MsoNormal><span style='mso-tab-count:3'> </span><span
style='mso-spacerun:yes'> </span>.555555<span
style='mso-spacerun:yes'> </span>-</p>
<p class=MsoNormal><span style='mso-tab-count:5'> </span>/<span
style='mso-spacerun:yes'> </span>\<span style='mso-tab-count:5'> </span></p>
<p class=MsoNormal><span style='mso-tab-count:4'> </span><span
style='mso-spacerun:yes'> </span>x<span style='mso-spacerun:yes'>
</span>32</p>
<p class=MsoNormal><span style='mso-tab-count:1'> </span></p>
<h2>HDread with Data Transform Expressions</h2>
<p class=MsoNormal>When a read is performed with a dataset transfer property
list that has the data transform property set, the following sequence of events
occurs:</p>
<p class=MsoNormal><o:p> </o:p></p>
<ol style='margin-top:0in' start=1 type=1>
<li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'>A
piece of the file is read into memory</li>
<li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'>The
data transform is performed on this piece of memory</li>
<li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'>This piece
of memory is then copied to the user</li>
<li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'>Steps
1 3 are repeated until the read is complete.</li>
</ol>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Step 2 works like this:</p>
<p class=MsoNormal><o:p> </o:p></p>
<ol style='margin-top:0in' start=1 type=1>
<li class=MsoNormal style='mso-list:l1 level1 lfo6;tab-stops:list .5in'>The
function responsible for doing the transform is passed a buffer and is
informed what type of data is inside this buffer and how many elements
there are.</li>
<li class=MsoNormal style='mso-list:l1 level1 lfo6;tab-stops:list .5in'>This
buffer is then treated as the variable in the data transform expression
and the transform expression is applied.</li>
<li class=MsoNormal style='mso-list:l1 level1 lfo6;tab-stops:list .5in'>The
transformed buffer is returned to the library.</li>
</ol>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>If the transform expression is (5/9.0)*(x-32), with the
parse tree shown above and the buffer contains [-10 0 10 50 100], then the
intermediate steps involved in the transform are:</p>
<p class=MsoNormal><o:p> </o:p></p>
<ol style='margin-top:0in' start=1 type=1>
<li class=MsoNormal style='mso-pagination:widow-orphan lines-together;
page-break-after:avoid;mso-list:l5 level1 lfo9;mso-hyphenate:none;
tab-stops:list .5in'>First, the (x-32) subexpression is evaluated.<span
style='mso-spacerun:yes'> </span>Now the buffer would contain<span
style='mso-spacerun:yes'> </span>[-42 -32 -22 18 68]</li>
<li class=MsoNormal style='mso-list:l5 level1 lfo9;tab-stops:list .5in'>Then,
the .55555 * part of the expression is evaluated.<span
style='mso-spacerun:yes'> </span>Now the buffer would contain: [-23.3333
-17.7777 -12.2222 9.9999 37.7777]</li>
<li class=MsoNormal style='mso-list:l5 level1 lfo9;tab-stops:list .5in'>Now,
the transform would be completed and the resulting buffer returned.</li>
</ol>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Note that the original data in the file was not modified. </p>
<p class=MsoNormal><o:p> </o:p></p>
<h2>HDwrite with Data Transform Expressions</h2>
<p class=MsoNormal>The process of a write works much the same way, but in the
reverse order.<span style='mso-spacerun:yes'> </span>When a file is written
out with a dataset transfer property list that has the data transform property
set:</p>
<p class=MsoNormal><span style='mso-spacerun:yes'> </span></p>
<ol style='margin-top:0in' start=1 type=1>
<li class=MsoNormal style='mso-list:l4 level1 lfo12;tab-stops:list .5in'>The
user passes a buffer to HDwrite, along with the type and number of
elements.</li>
<li class=MsoNormal style='mso-list:l4 level1 lfo12;tab-stops:list .5in'>The
data transform is performed on a copy of this piece of memory.</li>
<li class=MsoNormal style='mso-list:l4 level1 lfo12;tab-stops:list .5in'>This
copy with the transformed data is then written out to the file.</li>
</ol>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Step 2 works exactly as in the read example.<span
style='mso-spacerun:yes'> </span>Note that the users data is not modified. <span
style='mso-spacerun:yes'></span>Also, since the transform property is not
saved with the dataset, in order to recover the original data, a user must know
the inverse of the transform that was applied in order to recover it.<span
style='mso-spacerun:yes'> </span>In the case of (5/9.0)*(x-32) this inverse
would be (9/5.0)*x + 32.<span style='mso-spacerun:yes'> </span>Reading from
a data file that had previously been written out with a transform string of
(5/9.0)*(x-32) with a transform string of (9/5.0)*x + 32 would effectively
recover the original data the author of the file had been using.<a
style='mso-footnote-id:ftn2' href="#_ftn2" name="_ftnref2" title=""><span
class=MsoFootnoteReference><span style='mso-special-character:footnote'><![if !supportFootnotes]><span
class=MsoFootnoteReference><span style='font-size:12.0pt;font-family:"Times New Roman";
mso-fareast-font-family:"Times New Roman";mso-ansi-language:EN-US;mso-fareast-language:
EN-US;mso-bidi-language:AR-SA'>[2]</span></span><![endif]></span></span></a></p>
<p class=MsoNormal><o:p> </o:p></p>
<h1>Mixed Mode and Truncation</h1>
<p class=MsoNormal>Because the data transform sits and modifies data between
the file space and the memory space, various effects can occur that are the
result of the typecasting that may be involved in the operations.<span
style='mso-spacerun:yes'> </span>In addition, because constants in the data
transform expression can be either INT or FLOAT, the data transform itself can
be a source of truncation.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>In the example above, the reason that the transform
expression is always written as (5/9.0)*(x-32) is because, if it were written
without a floating point constant, it would always evaluate to 0.<span
style='mso-spacerun:yes'> </span>The expression (5/9)*(x-32) would, when
set, get reduced to 0*(x-32) because both 5 and 9 would get read as C long
ints and, when divided, the result would get truncated to 0.<span
style='mso-spacerun:yes'> </span>This resulting expression, 0*(x-32), would
cause any data read or written to be saved as an array of all 0s.<span
style='mso-spacerun:yes'> </span></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Another source of unpredictability caused by truncation
occurs when intermediate data is of a type that is more precise than the
destination memory type.<span style='mso-spacerun:yes'> </span>For example, if
the transform expression (1/2.0)*x is applied to data read from a file that
is being read into an integer memory buffer, the results can be
unpredictable.<span style='mso-spacerun:yes'> </span>If the source array is [1
2 3 4], then the resulting array could be either [0 1 1 2] or [0 0 1 1],
depending on the floating point unit of the processors.<span
style='mso-spacerun:yes'> </span>Note that this result is independent of the
source data type.<span style='mso-spacerun:yes'> </span>It doesnt matter if
the source data is integer or floating point because the 2.0 in the data
transform expression will cause everything to be evaluated in a floating-point
context.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>When setting transform expressions, care must be taken to
ensure that the truncation does not adversely affect the data.<span
style='mso-spacerun:yes'> </span>A workaround for the possible effects of a
transform such as (1/2.0) * x would be to used the transform expression
(1/2.0)*x + 0.5 instead of the original.<span style='mso-spacerun:yes'>
</span>This will ensure that all truncation rounds up, with the possible
exception of a boundary condition.</p>
<p class=MsoNormal><o:p> </o:p></p>
<h1>Data Transform Example</h1>
<p class=MsoNormal>The following code snippet shows an example using data
transform, where the data transform property is set and a write is
performed.<span style='mso-spacerun:yes'> </span>Then, a read is performed
with no data transform property set.<span style='mso-spacerun:yes'> </span>It
is assumed that <span style='font-family:Courier'>dataset </span>is a dataset
that has been opened and <span style='font-family:Courier'>windchillF </span>and
<span style='font-family:Courier'>windchillC </span>are both arrays that hold
floating point data.<span style='mso-spacerun:yes'> </span>The result of this
snippet is to fill <span style='font-family:Courier'>windchillC </span>with the
data in <span style='font-family:Courier'>windchillF</span>, converted to
Celcius.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><span style='font-family:Courier'>hid_t dxpl_id_c_to_f;<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'>const char* c_to_f =
(9/5.0)*x + 32;<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><o:p> </o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'>/* Create the dataset
transfer property list */<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><span
style='mso-spacerun:yes'> </span>dxpl_id_c_to_f =
H5Pcreate(H5P_DATASET_XFER);<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><o:p> </o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'>/* Set the data transform
to be used on the read*/<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><span
style='mso-spacerun:yes'> </span>H5Pset_data_transform(dxpl_id_c_to_f,
c_to_f);<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><o:p> </o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><span
style='mso-spacerun:yes'> </span><o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'>/*<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'>* Write the data to the
dataset using the f_to_c transform<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'>*/<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><span
style='mso-spacerun:yes'> </span>status = H5Dwrite(dataset, H5T_NATIVE_FLOAT,
H5S_ALL, H5S_ALL, dxpl_id_f_to_c, windchillF);<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><span
style='mso-spacerun:yes'> </span><o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'>/* Read the data with the
c_to_f data transform */<o:p></o:p></span></p>
<p class=MsoNormal><span style='font-family:Courier'><span
style='mso-spacerun:yes'> </span>H5Dread(dataset, H5T_NATIVE_FLOAT, H5S_ALL,
H5S_ALL, H5P_DEFAULT, windchillC);<o:p></o:p></span></p>
<p class=MsoNormal><o:p> </o:p></p>
<h1>H5Pget_data_transform Details</h1>
<p class=MsoNormal>Querying the data transform string of a dataset transfer
property list requires the use of the H5Pget_data_transform function.<span
style='mso-spacerun:yes'> </span>This function provides the ability to both
query the size of the string stored and retrieve part or all of it.<span
style='mso-spacerun:yes'> </span>Note that H5Pget_data_transform will return
the expression that was set by H5Pset_data_transform.<span
style='mso-spacerun:yes'> </span>The reduced transform string, computed when
H5Pset_data_transform is called, is not stored in string form and is not
available to the user.</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>In order to ascertain the size of the string, a NULL <span
style='font-family:Courier'>expression</span> should be passed to the
function.<span style='mso-spacerun:yes'> </span>This will make the function
return the length of the transform string (not including the terminated \0
character).</p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>To actually retrieve the string, a pointer to a valid memory
location should be passed in for <span style='font-family:Courier'>expression </span>and
the number of bytes from the string that should be copied to that memory
location should be passed in as <span style='font-family:Courier'>size</span>.</p>
<p class=MsoNormal><o:p> </o:p></p>
<h1>Further Work</h1>
<p class=MsoNormal>Some additional functionality can still be added to the data
transform.<span style='mso-spacerun:yes'> </span>Currently the most important
feature lacking is the addition of operators, such as exponentiation and the
trigonometric functions.<span style='mso-spacerun:yes'> </span>Although
exponentiation can be explicitly carried with a transform expression such as
x*x*x it may be easier to support expression like x^3. Also lacking are the
commonly used trigonometric functions, such as sin, cos, and tan.<span
style='mso-spacerun:yes'> </span></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>Popular constants could also be added, such as π or
e.<span style='mso-spacerun:yes'> </span></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>More advanced functionality, such as the ability to perform
a transform on multiple datasets is also a possibility, but is a feature is
more a completely new addition than an extension to data transforms.<span
style='mso-spacerun:yes'> </span></p>
</div>
<div style='mso-element:footnote-list'><![if !supportFootnotes]><br clear=all>
<hr align=left size=1 width="33%">
<![endif]>
<div style='mso-element:footnote' id=ftn1>
<p class=MsoFootnoteText><a style='mso-footnote-id:ftn1' href="#_ftnref1"
name="_ftn1" title=""><span class=MsoFootnoteReference><span style='mso-special-character:
footnote'><![if !supportFootnotes]><span class=MsoFootnoteReference><span
style='font-size:10.0pt;font-family:"Times New Roman";mso-fareast-font-family:
"Times New Roman";mso-ansi-language:EN-US;mso-fareast-language:EN-US;
mso-bidi-language:AR-SA'>[1]</span></span><![endif]></span></span></a> Mr.
Wendling, who involved in the initial design and implemented the expression
parser, has left NCSA.</p>
</div>
<div style='mso-element:footnote' id=ftn2>
<p class=MsoFootnoteText><a style='mso-footnote-id:ftn2' href="#_ftnref2"
name="_ftn2" title=""><span class=MsoFootnoteReference><span style='mso-special-character:
footnote'><![if !supportFootnotes]><span class=MsoFootnoteReference><span
style='font-size:10.0pt;font-family:"Times New Roman";mso-fareast-font-family:
"Times New Roman";mso-ansi-language:EN-US;mso-fareast-language:EN-US;
mso-bidi-language:AR-SA'>[2]</span></span><![endif]></span></span></a> See the
h5_dtransform.c example in the examples directory of the hdf5 library for just
such an illustration.</p>
</div>
</div>
</body>
</html>
|
