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
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>IEEEIO IDL/PV-Wave Interface</title>
</head>
<body bgcolor="#F0F0F0">
<table><tr>
<td><img src="Images/info.gif"></td>
<td><h1>IDL/PV-Wave</h1></td>
</tr></table>
<hr>
<h1>Using the IDL/PV-Wave Interface</h1>
The IDL/PV-Wave interface is only for reading. In the future
file writing may be supported, but there hasn't been a need for
this as of yet. The reader is very simplistic right now so you
must convert files to native byte order using the <a
href="Utilities.html#convert2native">convert2native</a> utility
in order for this reader to understand the file. Likewise,
there is support for reading attributes but annotation reading
has been delayed due to lack of interest in the short term.<p>
The procedures are contained in the file
<a href="src/ieeereader.pro">ieeereader.pro</a>. They can be
read into IDL using the command <code>.run
ieeereader.pro</code>. You can configure this file to
autoload by breaking the routines <code>ieeeopen</code>,
<code>ieeeclose</code>, <code>ieeeread</code>, and
<code>ieeereadattr</code>
into separate files named
<i>procedurename</i><code>.pro</code>.<p>
<hr>
<UL>
<LI><a href="#Opening">Opening and Closing Datafiles using
<code>ieeeopen</code> and <code>ieeeclose</code></a>
<LI><a href="#Info">Querying the file for the number of
datasets and attributes stored using
<code>ieeendatasets</code> and <code>ieeenattribs</code></a>
<LI><a href="#Reading">Reading Datasets using <code>ieeeread</code></a>
<LI><a href="#ReadAttribs">Reading Attributes using <code>ieeereadattr</code></a>
</UL>
<hr>
<a name="Opening"><h2>Opening and Closing Files</h2></a>
Like <code>openr</code> you must open a file handle to access
the IEEEIO files in IDL.<p>
<b>IDL Function</b><br>
<code>filedescriptor=ieeeopen('filename.raw')</code><P>
This function opens a file descriptor for reading. Currently
the IDL interface is a read-only interface.<p>
To close an IEEEIO filedescriptor and reclaim its resources you
use <code>ieeeclose</code>.<p>
<b>IDL Procedure</b><br>
<code>ieeeclose,filedescriptor</code>
Closes the filedescriptor. It will also deallocate any existing
IDL handles when I get this thing converted to use dynamic
datastructures.<p>
<hr>
<a name="Info"><h2>Querying File Information</h2></a>
<b>IDL Function</b>
<code>ieeendatasets(descriptor)</code><br>
Returns number of datasets in the file<p>
<b>IDL Function</b>
<code>ieeenattribs(descriptor,datasetnumber)</code><br>
Returns number of attributes bound to a particular dataset.<p>
<hr>
<a name="Reading"><h2>Reading Datasets</h2></a>
<b>IDL Procedure</b>
<code>ieeeread,filedescriptor[,datasetnumber]</code>
<DL>
<DT>The <b>datasetnumber</b> defaults to 0 if you don't specify
<DT>Named Params
<UL>
<LI><b>RANK = </b>returns rank of dataset
<LI><b>DIMENSIONS = </b> returns dims (allocates if none specified)
<LI><b>TYPE = </b> Integer datatype...<br>
In terms of IDL datatypes
0=Byte, 1=Fix, 2=Long,3=<i>not availible in IDL</i>,
4=Float,5=Double
<LI><b>DATA = </b> Returns data. If storage is provided,
then it will
copy into that storage space. Otherwise it will
allocate.
</UL>
<DT>The following switches affect Data allocation/management
<UL>
<LI><b>/INFO</b> : Makes it skip reading the data
<LI><b>/ASSOC_1D</b> : Associates data as a sequence of 1D x-columns
(eg data=assoc(unit,xarr(dims(0)))
<LI><b>/ASSOC_2D</b> : Associates data as a sequence of 2D xy-slices
<LI><b>/ASSOC_3D</b> : Associates data as a sequence of 3D
blocks of data
(note: only block #0 is valid of course)
<LI><b>/ASSOC_ELEMENTS</b> : Associates data as a sequence of elements
<LI><b>/ALLOCATE</b> : Forces it to nuke any existing data and
allocate
new storage for the data before copying
<LI><b>/COPY</b> : Forces it to copy into preallocated data space.
This will force an error if no data is availible
or if the availible preallocated data space is too
small.
</UL>
</DL>
<hr>
<a name="ReadAttribs"><h2>Reading Attributes</h2></a>
<b>IDL Procedure</b><br>
<code>ieeereadattr,descriptor,[datasetnumber]</code>
<DL>
<DD><b>datasetnumber</b> defaults to 0 if not specified
<DD>Named parameters are
<UL>
<LI><b>NUMBER =</b>the index of the attribute (ranges from
0 to nattribs-1)<pr>
nattributes is computed per dataset.
<LI><b>NAME = </b> The name of the attribute. If you
specify a <i>NAME=</i>
without the <i>NUMBER=</i>, it will search for the attribute
based on its name. However, if you specify a number
with <i>NUMBER=</i>, it will retrieve the attribute based
on its index and replace the <i>NAME</i> parameter with
the name of the attrib it read.
<LI><b>LENGTH = </b> number of elements in the attribute
data array
<LI><b>TYPE = </b> datatype of the attribute
<LI><b>DATA = </b> The place to put the attribute data.
If the array
exists and it is the proper size, then it will copy
into the array. Otherwise it will nuke the array
and replace it with a properly sized one.
</UL>
<DD> Data reading is affected by the following flags
<UL>
<LI><b>/ASSOC_ELEMENTS</b> : Associate as an array of elements
<LI><b>/ASSOC_1D</b> : Associate as a 1D array
<LI><b>/COPY</b> : Forces an error if the DATA= you
provided is not the
correct size.
<LI><b>/ALLOCATE</b> : Forces destruction and reallocation
of the array
you provide with <i>DATA=</i>
<LI><b>/INFO</b> : Does not read data. Just for getting info.
</UL>
</DL>
<hr>
<address><a href="mailto:jshalf@suttung.aei-potsdam.mpg.de">John Shalf</a></address>
<!-- Created: Tue Apr 8 18:57:06 MDT 1997 -->
<!-- hhmts start -->
Last modified: Wed Apr 9 11:41:11 MDT
<!-- hhmts end -->
</body>
</html>
|