Object Type:
diskio
Description:
The diskio object can be used to open/create a binary format
on disk (specified with -fileformat option)
that can be then used to read/write data or metadata from/to
child objects, 'variable' or 'metadata' respectively in this
library.
Unlike disk_out/disk_in, the reading and writing actions are
into this one new object.
file
it with
same
combined
For purposes of backwards compatibility (BC), diskio responds to the
set of messages that disk_out and disk_in respond to at a minimum, and
allows the user to read/write files directly from/to the disk at every
time-step of the clock which is assigned. It also allows the "replay" of
the results of a simulation through the xview and xgraph widgets in
XODUS.
Currently, it only supports files in the Network Common Data
Format (netcdf), a portable, network transparent, public domain binary
format.
Netcdf interfaces to various popular analysis/signal-processing tools
including
MATLAB are available in the public domain. Specifically,
* MEXCDF
WEB: http://crusty.er.usgs.gov/mexcdf.html
FTP: crusty.er.usgs.gov (128.128.19.19) or contact
Rich Signell at rsignell@crusty.er.usgs.gov.
* MexEPS
WEB: http://www.pmel.noaa.gov/epic/mexeps.html
FTP: ftp.pmel.noaa.gov/epic/mexeps/
* fanmat
WEB: http://www.unidata.ucar.edu/packages/netcdf/contrib.html
FTP: ftp.unidata.ucar.edu/pub/netcdf/contrib/fanmat.taz
are freely avaible packages that allow MATLAB to read/write/visualize
netcdf
data.
The implementation of the diskio library and the diskio, metadata, and
variable objects makes use of netcdf - version 2.4.3 which is Copyright
1993-1997 by University Corporation for Atmospheric Research/Unidata.
the
netcdf library is provided as per the terms of the UCAR/Unidata license,
described in genesis/src/diskio/interface/netcdf-2.4.3/src/COPYRIGHT.
Author:
V.Jagadish, Caltech (9/96)
-----------------------------------------------------------------------------
ELEMENT PARAMETERS
DataStructure: Gen_Diskio_Type
Size:
[in src/diskio/diskio_struct.h]
144 bytes + allocation for arrays and interpols
Fields:
accessmode Mode with which the file is accessed
- 'r', 'w' or 'a' (Read/Write/Append)
- Read-only field specifiable on the command
line using the -accessmode option but
cannot
be set/unset subsequently using setfield
- Defaults to 'r' (Read mode) as this is the
most non-destructive
- Append 'a' mode is not supported currently
- BC NOTE: Due to the default mode being
readonly 'r', it is not sufficient to
merely replace creation-lines of
disk_out with diskio but
to add the option "-accessmode w" as well.
cf. See Examples.
filename
Data file name to read from or write into
- Defaults to name of object if not specified
- Can be set/unset as required : The old file
will have data and metadata written into it
till that point in time, if the accessmode
was 'w' (write).
fileformat Format of the data file
- Unlike disk_out it is a character string
field but allows numerical setting for BC.
("1" => netcdf)
- Defaults to netcdf if not specified
- Subsequent setting/unsetting of this field
is allowed only to preserve BC with disk_out/
disk_in. This is effectively a NOP as far as
the physical file is concerned. Only the
the value of the field changes to reflect
the setting.
append
Flag: 1 => data should be appended after
RESET
is_open
Read-only flag: is file currently open?
is_writable Read-only flag:
is file writable?
val
2D array of input values
nx
x dimension of input val array
ny
y dimension of input val array
xpts,ypts,zpts
Interpols used for storing coordinate
information when the binary file is read
flush
Dummy field to retain BC with disk_out
leave_open Dummy field to retain BC with disk_out
----------------------------------------------------------------------------SIMULATION PARAMETERS
Function:
Gen_Diskio
[in src/diskio/gen_diskio.c]
Classes:
output
Actions:
CREATE PROCESS SET ADDMSGIN DELETEMSGIN SHOW
RESET:
It is essential that the RESET action be called
on the diskio object for allocating and filling the
"xpts ypts zpts" interpol arrays before using
them to render/replay data graphically on the
xview objects.
cf. Example: Scripts/examples/diskiolib/replayview.g
QUIT:
FLUSH:
UPDATE: when called on the diskio object, allows the user
to commit any changes done interactively
or in the process of running a simulation or script,
to the file on disk. This allows another diskio
object to simultaneously access updated data from the
same file.
DELETE: also commits changes but with the usual effect of
deleting the object and all its children. Please note
that this action does not delete the physical file on
disk.
GENERAL NOTE:
The process of committing changes to disk is
time-consuming. This is inherent in the
implementation of the netcdf library. So
please expect delays after you quit or do a
delete or call one of the above 4 actions on
the diskio object. In general, the netcdf
library provides its portability across
architectures at the cost of efficiency in
speed. Therefore, performance-wise one will
notice diskio is slower than disk_out/disk_in.
Messages:
SAVE data
IMPORTANT BACKWARDS COMPATIBILITY (BC) NOTES:
---------------------------------------------
As previously mentioned, diskio responds to the same set of
messages that disk_out and disk_in respond to as a minimum, for
purposes of BC.
Since the actual data is encapsulated within the variable
object and the design eventually envisages the exclusive
use of this child object to manipulate data, any incoming SAVE
messages to the diskio object (thro the addmsg command) will
result in the automatic creation of child variables and the
forwarding of the message to them. So the data will be stored
and manipulated via these child variables, while letting the user
transparently deal only with the diskio object as was done
previously
with disk_out/disk_in.
For every SAVE message there will be a specially named child
variable object - 'autoSAVE_diskio[i]', where i is the index of
the element and that corresponds to the number of the message.
The indices will be reused if any messages are deleted and added
later.
Also, for every SAVE message, the 3-D position coords of the source
element needs to be stored for possible future replay via graphical
objects like xview. This is done through the automatic creation of
specially named indexed metadata children - 'auto3DPosSAVE_diskio[i]'.
So in applications where diskio is intended to be used
as a replacement for disk_out/disk_in, these variables & metadata
will be automatically created in the hierarchy for every SAVE
message
to the object. Directly manipulating these child objects should be
avoided, since it would essentially change the contents of the
file,
if committed.
Example:
* Run Scripts/examples/diskiolib/diskio/generate.g
* genesis> le /diskio
----------------------------------------------------------------------------Notes:
As a departure from the disk_out/disk_in objects, this object internally
just serves to interface (open/create/close) with a binary file on disk.
The actual data in the file can be more flexibly managed using the child
'variable' objects in this library.
For purposes of backwards compatibility, however, the diskio object will
respond to the same messages as the disk_out and disk_in objects at a
minimum
to actively write/read data to/from the file during a simulation run.
Some binary file formats notably netcdf (which this library supports)
allow
descripive data (metadata) to be stored in them along with the actual
data.
Child 'metadata' objects in this library allow the user to manipulate the
metadata content in these files.
Use asc_file for writing data in ASCII format.
Examples:
1. create diskio /dout -filename testfile.nc -fileformat netcdf accessmode w
2. call /dout UPDATE
3. delete /dout
4. Also, please see Scripts/examples/diskiolib/diskio/
- generate.g
- replayview.g
- replaygraph.g
_________________________________________________________________________
_____
See also:
variable, metadata, disk_out, disk_in, asc_file