|
|
|
|
Defining a Multistep ASCII Description File
Note: The following description assumes you are familiar with the definition of AVS/Express data using ASCII description files. For more information see, Read Field.
To support multistep data, AVS/Express changes the ASCII description file in the following ways:
A new token, nstep, has been added to the file header. The value of nstep is the number of steps defined in the file. Note : It can be omitted when DO~ENDDO is not defined.
Following the header information, coord or variable specifications are defined for each step. Only the elements that will change in the steps need to be specified. For example, if the coordinates do not change, the coord specifications only need to be given once.
The specifications for each step must be separated from the next by the token EOT on a line by itself. This token must also be included after the last step.
Each step can include a time token. The value of the time token is a string that can be specified directly in the step specification or read in from a separate file. The string is read by Read Field and output as a renderable object. You can use the time token to display the time stamp for the step, or to otherwise label the step in the view.
The close token can be included in each variable, coord, or time specification. It specifies whether the file being read for the current specification should be closed or left open when the information is read.
If close = 1, which is also the default, the file being read for the information supplied by the specification is closed after reading the record. In this case, the next specification for this information must include skip and/or stride values that locate the information from the beginning of the file.
If close = 0, AVS/Express will preserve the file pointer at the end of the information pointed to by the current specification. The next specification for this information begins reading from this point. If your data is stored consecutively in a single file, you can use this token to avoid specifying the location of each record, and the data may be read in more quickly as well. The file pointer for the current specification is maintained independently from any other specification. I.e. each variable and coord are processed seperately.
If you have close = 0 at the end of "coord 1" and close = 0 at the end of "coord 2" the
two positions will both be saved independently.
For step =1, skips for time, node and coordinate data are absolute from the starting of the file even when close=0. For the second and subsequent time steps the value of close value in previous step is used to interpret the behavior of skip forward of that particular data. I e. the close and skip values of the same step in any data specification do not interact.
You can repeat a step or group of steps by enclosing them between DO on a line by itself and ENDDO on a line by itself. The step or steps between the DO and the ENDDO are repeated until the number of steps specified by nstep has been completed.
The following figure illustrates the structure of a field file with multiple steps. The new tokens are explained in detail below.
nstep = value (optional)Defines the number of steps. This is necessary when DO ~ ENDDO is defined. It can be omitted when DO~ENDDO is not defined. As long nstep is defined in the header portion, its actual position within the header can be anywhere.
time file = filespec filetype = type skip = n offset = m close = 0/1 or time value = string (optional)
Defines a string (time, step number etc.) that labels the step. If the string is defined in a separate file, then time file = is used. If the comment is defined directly then time value = is used. If the file in which the comment is stored is of type ASCII, then any character string can be read in. Note that there is no stride parameter.
Note: close is used not only for time specifications, but also for variable and coord. The default value is 1. When close = 1, the file is closed after reading the step. To read the next step, it is necessary to use descriptions such as skip and stride to define the position at which the next step begins from the beginning of the file. When close = 0, then the file is not closed after reading the current step. Instead the file pointer is preserved at the current location, and the location of the next step is specified relative to the position of this pointer.
Note: The close attribute only affect the time, variable, or coord specification in which it is given, even if all the information is stored in the same file. For example, if time and variable 1 for all steps is defined in the same file and close is set to 0 in both cases, then variable 1 is read relative to the last position of variable 1 in the previous step.
This token is required at the end of each step, including the last. This can be omitted if the number of steps is 1. Note: Here EOT is in upper-case characters but it is possible to use lower-case also. Other than the filename, the rest of the description is not case-sensitive.
A block of data enclosed in a DO - ENDDO pair is repeated until nstep steps are completed. Consequently, it is not possible to define another step after ENDDO. The nstep value must be defined in this case. You can enclose multiple steps in a DO - ENDDO block.
A set of data and the field file to read it is given below (filename: /tmp/sample.data):
The following example illustrates the file specification to read the data given above when close = 1. (Note that close = 1 is the default and could be omitted from the specifications.)
time file=/tmp/sample.data filetype=ascii skip=1 close=1
variable 1 file=/tmp/sample.data filetype=ascii skip=2 offset=0 stride=4 close=1
coord 1 file=/tmp/sample.data filetype=ascii skip=2 offset=1 stride=4 close=1
coord 2 file=/tmp/sample.data filetype=ascii skip=2 offset=2 stride=4 close=1
coord 3 file=/tmp/sample.data filetype=ascii skip=2 offset=3 stride=4 close=1
time file=/tmp/sample.data filetype=ascii skip=10 close=1
variable 1 file=/tmp/sample.data filetype=ascii skip=11 offset=0 stride=4 close=1
coord 1 file=/tmp/sample.data filetype=ascii skip=11 offset=1 stride=4 close=1
coord 2 file=/tmp/sample.data filetype=ascii skip=11 offset=2 stride=4 close=1
coord 3 file=/tmp/sample.data filetype=ascii skip=11 offset=3 stride=4 close=1
time file=/tmp/sample.data filetype=ascii skip=19 close=1
variable 1 file=/tmp/sample.data filetype=ascii skip=20 offset=0 stride=4 close=1
coord 1 file=/tmp/sample.data filetype=ascii skip=20 offset=1 stride=4 close=1
coord 2 file=/tmp/sample.data filetype=ascii skip=20 offset=2 stride=4 close=1
coord 3 file=/tmp/sample.data filetype=ascii skip=20 offset=3 stride=4 close=1
The following example illustrates the file specification to read the data given above when close=0. This example also uses a DO loop.
time file=/tmp/sample.data filetype=ascii skip=2 offset=0 stride=4 close=0
time file=/tmp/sample.data filetype=ascii skip=2 offset=1 stride=4 close=0
time file=/tmp/sample.data filetype=ascii skip=2 offset=2 stride=4 close=0
time file=/tmp/sample.data filetype=ascii skip=2 offset=3 stride=4 close=0
time file=/tmp/sample.data filetype=ascii skip=8 close=0
variable 1 file=/tmp/sample.data filetype=ascii skip=1 offset=0 stride=4 close=0
coord 1 file=/tmp/sample.data filetype=ascii skip=1 offset=1 stride=4 close=0
coord 2 file=/tmp/sample.data filetype=ascii skip=1 offset=2 stride=4 close=0
coord 3 file=/tmp/sample.data filetype=ascii skip=1 offset=3 stride=4 close=0
|
|
|
|