Read or write any format of ASCII data.
| ASCIIFILE:OPEN() | file=String [comment=String] [delimiter=String] | Open an ascii file |
| ASCIIFILE/CLOSE | handle=AsciiFile | Close an open file |
| ASCIIFILE:DATA() [:RESET] |
handle=AsciiFile | Return all data currently accumulated in a workspace. |
| ASCIIFILE:LINES() | handle=AsciiFile | Return the number of data lines left to read |
| ASCIIFILE/READFIXED | handle=AsciiFile [fields=String] format=String [count=Integer] | Read fixed format data |
| ASCIIFILE/READFREE | handle=AsciiFile [fields=String] [separator=String] [count=Integer] | Read free format data |
| ASCIIFILE/SKIP | handle=AsciiFile [nlines=Integer] | Skip lines on input |
| ASCIIFILE/WRITEFREE | handle=AsciiFile comment=String separator=String gv1=Any [gv2=Any] [gv3=Any] [gv4=Any] | Write free format data |
| ASCIIFILE/REWIND | handle=AsciiFile | Close and re-open a file at the start |
example:
# Read three data arrays (in columns separated by whitespace)
# and assign to arrays in fields X, Y, and E in the new workspace.
Handle = Asciifile:Open("myilldata.dat")
wk1 = Asciifile:Readfree(Handle, "X,Y,E", $WHITESPACE, 8)
printin wk1
Workspace []
(
x = [1.0 1.1 1.2 1.3 1.4 ...] Array(8 )
y = [2.1 2.1 2.2 2.0 2.0 ...] Array(8 )
e = [0.0 0.1 0.2 0.0 0.1 ...] Array(8 )
)
Open a file and return a handle for use with other Asciifile() commands. This command must be called before any other operations can be carried out
File (String)
Name of the ascii data file to be opened, or if it does not exist, to be created.
Comment (String) [ default = "" ]
When an ASCII file is opened by Open GENIE for reading, it is possible to specify a single character which is being used in the input file as a comment character. The result of this will be to effectively ignore all lines beginning with this character up to the last instance of "Delimiter" (the Asciifile:lines() command will report only the number of non-commented lines).
Delimiter (String) [ default = "\n" (new line) ]
A single character that indicates the end of a line of input and this is configureable because different systems may terminate lines in different ways. Normally this will only be necessary if the ASCII file has come from a different operating system (for example, files from a Macintosh may require "\r" as the delimiter).
RESULT = (Asciifile)
The result of this command is a file handle variable which must be stored and passed as a parameter to any future operations on the file.
Close the file, flushing any buffers to disk.
Handle (Asciifile)
Specifies the file to close. Once a file has been closed, the "Handle" value becomes undefined and should not be used.
It is possible to read data in two ways with the Asciifile() command. The example at the begining of this command description shows how data may be read into a workspace in a single go with the /Readfree qualifier. An alternative way of reading the same data is shown below using the Asciifile:Data() command.
Asciifile/Readfree Handle "X1,Y1,E1" $WHITESPACE 4
Asciifile/Readfree Handle "X2,Y2,E2" $WHITESPACE 4
wk1 = Asciifile:data(Handle)
printn wk1
Workspace []
(
x1 = [1.0 1.1 1.2 1.3 ] Array(4 )
y1 = [2.1 2.1 2.2 2.0 ] Array(4 )
e1 = [0.0 0.1 0.2 0.0 ] Array(4 )
x2 = [1.4 1.5 1.6 1.7 ] Array(4 )
y2 = [2.0 2.0 2.0 2.0 ] Array(4 )
e2 = [0.1 0.1 0.2 0.0 ] Array(4 )
)
Using this method several different items of data may be accumulated into the workspace before it is returned.
/Reset
Clears the workspace which was previously being accumulated of all fields and gives a fresh start. Note that this does not reset any file pointers; to reset a file on reading use the /Rewind option.
Handle (Asciifile)
Specifies the file with which all the data is associated. A separate workspace may be accumulated for every open file handle.
RESULT = (Workspace)
Returns the accumulated workspace of data items.
Returns the number of data lines (i.e. non comment lines) in the file left to read. To return the total number of data lines in a file, the Asciifile:lines() command must be called before any lines of data are read in.
Handle (Asciifile)
Specifies the file to count the remaining lines in.
RESULT = (Integer)
Count of remaining lines to read.
Reads lines from an ASCII formatted file in "Fixed" format. This is similar to FORTRAN fixed format reads where data is identified exactly by position and length and there are not necessarily any spaces separating the data being read in. For example, the line below reads 50 lines out of a fixed format file consiting of two columns of real numbers in fields of width 10 each. The first character on each line is a space to be skipped before the numbers start.
wk = Asciifile:Readfixed(Handle, "x,y", " %10f%10f", 50)
/Optional
Describe only qualifiers which do not affect the parameter list here, before the parameters.
Handle (Asciifile)
Specifies the file to read data from. The current postion in the file is also remembered with the file handle.
Fields (String) [ default = "FIELD01, FIELD02, FIELD03, FIELD04, FIELD05, FIELD06" ]
Gives a list of names, separated by commas, which will be assigned to the fields of the resultant data workspace. The names will be associated, in order, with the columns of data as they are read from the input file.
If the empty string ("") is passed and the data being read is either a single value or a single column of data, a single variable or array will be returned instead of a whole workspace.
Format (String)
This is a C style sscanf expression (similar in a FORTRAN FORMAT statement in meaning). The "%" character is used to indicate the position and specific format for each data item in the line. Some examples of common formatting possibilities are given below.
| %6f | Matches a floating point number of total width 6 |
| %s | Matches a string of non-whitespace characters |
| %10c | Matches ten characters, including white space |
| %d | Matches an integer |
| %4d | Matches an integer of width 4 |
| %*f | Skips a float in the line |
| %% | Matches a % character |
| " " | (space) Skips one or more spaces |
Other sscanf formatting conventions may be used if they are supported on the host operating system.
Count (Integer) [ default = 1 ]
Number of lines to read in one operation. This effectively defines the size of the data arrays being returned for each column of data. To read to the end of the file specify -1.
RESULT = (Workspace, array or single value)
The result of an ASCII read operation depends on the amount and format of the data read, normally a workspace is returned, but for a single column of data or a single value in the file, an array or single item can be returned respectively (see the "Fields" parameter description).
Reads lines from an ASCII formatted file in "Free" format. This is similar to FORTRAN list directed read statements where data is separated, usually by spaces or commas. For example, the line below reads back a workspace with two array fields X and Y which are read from two columns in the input file where the columns are delimited by one or more "!" characters.
wk = Asciifile:Readfree(Handle, "x,y", "[!]+", 40)
Handle (Asciifile)
Specifies the file to read data from. The current postion in the file is also remembered with the file handle.
Fields (String) [ default = "FIELD01, FIELD02, FIELD03, FIELD04, FIELD05, FIELD06" ]
Gives a list of names, separated by commas, which will be assigned to the fields of the resultant data workspace. The names will be associated, in order, with the columns of data as they are read from the input file.
If the empty string ("") is passed and the data being read is either a single value or a single column of data, a single variable or array will be returned instead of a whole workspace.
Separator (String) [ default = $WHITESPACE ( one or more tabs or spaces ) ]
A single character or regular expression specifying what to expect between each item of data on a line. The definition of the default $WHITESPACE is "[ \t]+" meaning one or more space or tab characters. This default will be suitable for many cases but for example, an expression like " *, *" will delimit comma separated data. For more details of how to construct regular expressions see regular expressions in the Appendices to this manual.
Count (Integer) [ default = 1 ]
Number of lines to read in one operation. This effectively defines the size of the data arrays being returned for each column of data.
RESULT = (Workspace, array or single value)
The result of an ASCII read operation depends on the amount and format of the data read, normally a workspace is returned, but for a single column of data or a single value in the file, an array or single item can be returned respectively (see the "Fields" parameter description).
This skips "Nlines" of input data (i.e. non comment) lines in an input file.
Handle (Asciifile)
Specifies the file in which to skip the lines.
Nlines (Integer) [ default = skip 1 line ]
Number on lines in the input file to skip.
Writes Open GENIE variables into up to four free formatted columns of ASCII data. Data cannot be written to an existing file already opened for reading.
Handle (Asciifile)
Specifies the opened file to write data to.
Comment (String) [ default = "" ]
Optional user comment which will be preceded by the comment character specified with the Asciifile/Open command. If a comment character was specified for the file and nothing is specified for this parameter, Open GENIE will add its own default header.
Separator (String) [ default = " " ]
Specifies the character(s) to separate columns of output data with.
Gv1-Gv4 (Any valid Open GENIE type except workspaces)
Up to four separate GENIE data items to write out at one time. The values are written out in up to four columns. The longest data item of the four determines the length of the data added to the file. The shorter items are repeated to fill their columns.