Opens files.
No options
Parameters
NAME = texts |
External names of the files |
---|---|
CHANNEL = scalars |
Channel number to be used to refer to each file in other statements (numbers for each type of file are independent); if this is set to a scalar containing a missing value, the first available channel of the specified type is opened and the scalar is set to the channel number |
FILETYPE = string tokens |
Type of each file (input, output, unformatted, backingstore, procedurelibrary, graphics ); default inpu |
WIDTH = scalars |
Maximum width of a record in each file; default 80 |
INDENTATION = scalar |
Number of spaces to leave at the start of each line; default 0 |
PAGE = scalars |
Number of lines per page (relevant only for output files) |
ACCESS = string token |
Allowed type of access (readonly, writeonly, both ); default both |
STYLE = string token |
Style in which to write to an output file (plaintext , html , latex , rtf ); default plai |
HTMLHEAD = texts |
Text structures containing custom content for the header of an HTML document |
†UNICODE = string token |
Content of an input file is Unicode (no , yes ); default no |
Description
Genstat makes use of various types of file. These are classified according to the information that they store. The files are accessed via channels. For each type there is a set of numbered channels that can be used to reference different files in the relevant directives. For example, there are five input channels, numbered 1 up to 5. Likewise, there are five output channels. Genstat distinguishes between the different types of channel, so you can have one file attached to output channel 3 and a different file simultaneously attached to backing store channel 3. Then, setting the option CHANNEL=3
in PRINT
and STORE
statements will send the different kinds of output to the appropriate files. With backing-store files, there are six channels, numbered 0 to 5, but channel 0 is reserved for the backing-store workfile. Similarly, there are six channels, numbered 0 to 5, for unformatted files. For procedure libraries there are three channels, numbered 1 to 3. For graphics files, each channel is used for output in a particular graphics format, corresponding to the number of the device selected by the DEVICE
directive.
When you run Genstat it starts taking input from input channel 1 and produces output on output channel 1. In an interactive run, these will be keyboard and screen, while in a batch run they will be files on the computer. Another file that is attached automatically is the start-up file of instructions that are executed at the outset of each job; this is attached to input channel 5. The start-up file may attach other files. For example, if you are working interactively, the standard start-up file arranges for output channel 5 to store a transcript of your output. (This is done using the COPY
directive.) The command that you use to run Genstat may allow you to arrange for other files to be attached when Genstat starts running. Alternatively, within Genstat, you can use the OPEN
directive.
Usually you need specify only the name of the file, the channel number and type of file, and leave the other parameters to take their default settings. For example, the following statements attach a file called WEATHER.DAT
to the second input channel, and then read data from it.
OPEN 'WEATHER.DAT'; CHANNEL=2; FILETYPE=input
READ [CHANNEL=2] Rain,Temperature,Sunshine
The file name can be anything that is acceptable to your computer system. You should, however, check for any constraints: for example, plotting software may require HPGL graphics files to have the extension .HPGL
. You should check in your local documentation for information regarding any features that are specific to your computer or version of Genstat. For example, logical or symbolic names may be automatically translated by Genstat before files are accessed; upper and lower case characters may be significant, as on Unix systems. The file name may involve characters that have special meaning within Genstat. For example, the character \may be required to specify directories and sub-directories on a PC. This character needs to be duplicated in a string to avoid Genstat interpreting it as the continuation symbol: for example
OPEN 'C:\\RES\\WEATHER.DAT'; CHANNEL=2; FILETYPE=input
to open the file 'C:\RES\WEATHER.DAT'
. As a more convenient alternative, the PC version of Genstat allows you to use /
instead.
You are free to choose which channels you want to use (within the range available for the specified type of file), apart from input and output channel 1 which are “reserved” for use by the files specified on the command line. As already mentioned, input channel 5 is used for the start-up file, and this may arrange for output channel 5 to store a transcript of your output. However, you can use the CLOSE
directive to disconnect these files if you want to use the channels for some other purpose. The backing-store and unformatted work files are attached to channel 0, and this channel cannot be used in OPEN
or CLOSE
. Graphics files must be opened on the channel corresponding to the device number.
Obviously you cannot open more than one file on a channel, so if you wish to open a file on a channel that is currently in use you must first close that channel. Sometimes, in general programs or procedures, you may not know which channels are available. You can then let OPEN
find a free channel: if CHANNEL
is set to a scalar containing a missing value, the file is opened on the next available channel of the appropriate type, and the scalar is set to the number of the channel. The scalar need not be declared in advance; if CHANNEL
is set to an undeclared structure, this will be defined as a scalar automatically.
SCALAR FreeChan
OPEN 'WEATHER.DAT'; CHANNEL=FreeChan; FILETYPE=input
READ [CHANNEL=FreeChan] Rain,Temperature,Sunshine
Another constraint is that you cannot open the same file on more than one channel at once.
Input files must already exist when they are opened, whereas output files will be created by Genstat. If an output file with the specified name exists already, Genstat may create an extra “version” of the file, or report a fault, or cause the file to be overwritten, depending on the usual conventions on your type of computer. Your local documentation will describe what rules apply in this situation, and should also explain if there are any system variables you can set to control this action.
The STYLE
parameter controls the style to be used to represent the information in an output file. The default is to use plain text, which assumes that all characters occupy an equal width. So, for example, columns are aligned by use of space characters and captions are highlighted by underlining them by rows of equal signs or minuses. However, you can also choose HTML (as used for example by web browsers), RTF (as used by word processors such as Microsoft Word) or LaTeX.
When you open a file for use by backing store or unformatted input and output, you can both read from it and send output to it, unless you set the ACCESS
parameter (see below). Procedure libraries are a special type of backing-store file.
The WIDTH
parameter sets the maximum number of characters per line for input and output files. It is ignored for other types of file. The default values for WIDTH
are designed to be appropriate for each implementation of Genstat and may differ between input and output; details will be found in your local documentation. For input and output with screen displays that use windows WIDTH
may be set automatically from the size of the appropriate window.
For input files the default is normally 80, reflecting the size of most screen displays. You can change this if necessary, to read either fewer characters from each line, or longer lines. If the WIDTH
is set to be too small any extra characters will be lost, which may cause unexpected action or syntax errors. Remember that if you use READ
with LAYOUT=fixed
to read fixed-format data, short lines are extended with spaces up to the WIDTH
setting. If you want to read data from a file with, say, 64 characters per line, setting WIDTH=64
when you open the file may make the format specification easier (rather than taking the default width of 80 and having to remember to skip 16 characters at the end of each line).
For output files, the default is the largest number of characters that can usually be displayed in a single line. This number is typically 80 for terminals but for files it is likely to be either 80, 120 or 132, depending on the type of computer. You can use the WIDTH
parameter to restrict the number of output characters to a smaller number, or to a larger number up to 200.
The PAGE
parameter specifies the size of page in output, affecting directives like GRAPH
. For output to files, the default value of PAGE
is designed to be suitable for printers. For windowed displays Genstat will, if possible, detect the size of the window and set the page size appropriately. You can also set option OUTPRINT=page
in either JOB
or SET
to ensure that graphs and statistical analyses each start on a new page.
The INDENTATION
parameter can be used to leave a specified number of blank characters to the left of each line of an output file, so that printed output can be bound for example. The indentation is subtracted from the WIDTH
setting, so if you set WIDTH=80
and INDENTATION=10
then only 70 characters will be printed on each line of output.
The ACCESS
parameter is used to control the way in which unformatted and backing-store files can be accessed, on computers that allow this.
The HTMLHEAD
parameter allows you to supply additional markup content for the document header of an HTML file, to be inserted between the and
tags. It can be set either to a text containing all the HTML markup or to the name of a file containing that information. It is intended primarily for inserting CSS style information, for example:
<style>
h1 { color: black; background-color: red !important; }
h2 { color: white; background-color: green !important; }
</style>
but can also be used to set any other valid header content. Additional CSS content can also be loaded via a link tag, e.g.
<link rel="styleSheet" type="text/css" href="genstat.css">
By default, the header contains a title and some standard meta data. These tags can be overwritten by specifying these tags in the inserted header data. The tags that are treated in this way are:
<title>
<meta name="description"
<meta name="keywords"
<meta name="author"
All other content of the text is inserted verbatim and assumed to be valid HTML. If HTMLHEAD
is not set, Genstat inserts the content of the file Genstat.css
which is supplied with the Genstat installation in the Source
directory. This defines a number of classes which are used at various points in the Genstat output (for example to define styles used for output from CAPTION
). The file can be used as a template from which to derive a local variation redefining basic elements of output.
Some Windows text files may be in Unicode format, where pairs of bytes give a single Unicode character. Often these files are marked with a Unicode “beginning of file marker” (BOM) which consists of the two bytes 0xFF and 0xFE in either order. The ordering of these bytes indicates the endian order of the Unicode characters. If an input file has a Unicode BOM header, it will be automatically detected as a Unicode file when opened, and converted to the UTF-8 format that Genstat uses internally. If a Unicode file lacks the BOM marker, you can set parameter UNICODE=yes
to force the conversion of the file to UTF-8 format.
Options: none.
Parameters: NAME
, CHANNEL
, FILETYPE
, WIDTH
, INDENTATION
, PAGE
, ACCESS
, STYLE
, HTMLHEAD
, UNICODE
.
See also
Directives: CLOSE
, ENQUIRE
, FCOPY
, FDELETE
, FRENAME
, READ
, PRINT
, INPUT
, STORE
, RETRIEVE
, RECORD
, RESUME
.
Procedure: SETDEVICE
.
Commands for: Input and output.
Example
" Example DCON-1: Draw a contour plot" MATRIX [ROW=16; COLUMNS=18] M OPEN '%gendir%/examples/DCON-1.DAT'; CHANNEL=data1; WIDTH=200 READ [CHANNEL=data1] M CLOSE data1 DCONTOUR [TITLE='Contour'] M