Sets details of the “environment” of a Genstat job.
Options
INPRINT = string tokens |
Printing of input as in PRINT option of INPUT (statements , macros , procedures , unchanged ); default unch |
---|---|
OUTPRINT = string tokens |
Additions to output as in PRINT option of OUTPUT (dots, page, unchanged ); default unch |
DIAGNOSTIC = string tokens |
Defines the least serious class of Genstat diagnostic which should still be generated (messages, warnings, faults, extra, unchanged ); default unch |
ERRORS = scalar |
Number of errors that a job may contain before it is abandoned (0 implies no limit); default is to leave unchanged |
FAULT = text |
Sets the Genstat fault indicator (for example, FAULT=* clears the last fault); default is to leave the indicator unchanged |
PAUSE = scalar |
Number of lines to output before pausing (interactive use only; 0 implies no pausing); default is no change |
PROMPT = text |
Characters to be printed for the input prompt; default is to leave unchanged |
NEWLINE = string token |
How to treat a new line (significant,ignored ); default is no change |
CASE = string token |
Whether lower- and upper-case (small and capital) letters are to be regarded as identical in identifiers (significant, ignored ); default is no change |
FIELDWIDTH = scalar |
Fieldwidth to be used as a default minimum by PRINT and other output commands |
SIGNIFICANTFIGURES = scalar |
Minimum number of significant figures to be supplied in the default formats determined by PRINT and other output commands |
SEEDS = pointer or scalar |
Defines the current default seeds to be used for random numbers in various parts of Genstat |
RUN = string token |
Whether or not the run is interactive (interactive, batch ); by default the current setting is left unchanged |
UNITS = identifier |
To (re)set the current units structure; default is to leave unchanged |
BLOCKSTRUCTURE = identifier |
To (re)set the internal record of the most recent BLOCKSTRUCTURE statement; default is to leave unchanged |
TREATMENTSTRUCTURE = identifier |
To (re)set the internal record of the most recent TREATMENTSTRUCTURE statement; default i s to leave unchanged |
COVARIATE = identifier |
To (re)set the internal record of the most recent COVARIATE statement; default is to leave unchanged |
ASAVE = identifier |
To (re)set the current ANOVA save structure; default is to leave unchanged |
MSAVE = identifier |
To (re)set the current save structure for multivariate analysis; default is to leave unchanged |
DSAVE = identifier |
To (re)set the current save structure for the high-resolution graphics environment; default is to leave unchanged |
RSAVE = identifier |
To (re)set the current regression save structure; default is to leave unchanged |
TSAVE = identifier |
To (re)set the current time-series save structure; default is to leave unchanged |
VSAVE = identifier |
To (re)set the current REML save structure; default is to leave unchanged |
VCOMPONENTS = identifier |
To (re)set the current REML model definitions, as specified by VCOMPONENTS and VSTRUCTURE ; default is to leave unchanged |
WORDLENGTH = string token |
Length of word (8 or 32 characters) to check in identifiers, directives, options, parameters and procedures (long , short ); default * i.e. no change |
CAPTIONS = string tokens |
Controls which captions are displayed (minor , major , meta , unchanged ); default unch |
TYPESET = string tokens |
Controls when typesetting commands within textual strings are used (output , graphics ); if unset, the existing setting is left unchanged |
CMETHOD = string token |
Controls whether number settings for colour options and parameters are interpreted as RGB values or as numbers of standard colours (rgb , standard ); if unset, the existing setting is left unchanged |
DATASPACE = scalar or variate |
Updates the current data space allocations; if unset, the existing allocations are left unchanged |
WORKINGDIRECTORY = text |
Sets the working directory; default is to leave this unchanged |
ALGORITHMS = string token |
Controls the use of enhanced computing algorithms (standard , mkl ); if unset, the existing setting is left unchanged |
ACTIONAFTERFAULT = string token |
Controls what happens after a fault (continue , stop ); if unset, the existing setting is left unchanged |
UNSETDUMMY = string token |
Controls what happens if you specify an unset dummy as the setting of an option or parameter that expects another type of data structure (fault , ignore , warn ); if unset, the existing setting is left unchanged |
LANGUAGE = text |
Text with either one or two values to specify a preferred language for output and (optionally) a second choice in case the preferred language is unavailable |
YEAR2DIGITBREAK = scalar | Controls how 2 digits can be used to specify years |
No parameters
Description
The default of SET
is to do nothing: that is, each option by default leaves the corresponding attribute of the environment unchanged. Of course you have to start somewhere, so an initial environment is defined at the start of any Genstat program; the corresponding initial settings of the options of SET
, known as the initial defaults, are described below.
The INPRINT
option controls what parts of a Genstat job supplied in the current input channel are recorded in the current output file; the input channel can be either an input file or the keyboard. Three parts are distinguished: explicit statements; statements, or parts of statements, that you have supplied in macros using either the ##
notation or the EXECUTE
directive; and statements that you have supplied in procedures. The initial default is to record nothing if the output is to the screen, otherwise to record the statements. This aspect of the environment can be modified also by the PRINT
option of the INPUT
directive and by the INPRINT
option of JOB
.
The OUTPRINT
option controls how the output from many Genstat directives starts: the output can be preceded by a move to the top of a new page, or by a line of dots beginning with the line number of the statement producing the analysis, or by both. If output is directly to the screen, no new pages are given. The initial default is to give neither if output is to the screen, otherwise to give a new page and a line of dots. Alternatively, this aspect can be modified by the PRINT
option of the OUTPUT
directive or by the OUTPRINT
option of JOB
. The lines of dots are produced by the directives for regression analysis, analysis of designed experiments, REML analysis, multivariate analysis and time series; also from the FLRV
, FSSPM
and SVD
directives. If you give an analysis statement within a FOR
loop, the line number preceding the line of dots is that of the ENDFOR
statement rather than of the analysis statement. New pages are produced with any of the above, and with the GRAPH
, HISTOGRAM
and CONTOUR
directives.
The DIAGNOSTIC
option allows you to control the level of diagnostic reporting. You might want to do this within a procedure, to prevent faults being reported to a user who does not need to know in detail what is going on inside the procedure. By initial default, all diagnostics – messages, warnings and faults – are printed. You can switch off messages by setting DIAGNOSTIC=warning
, or switch off both messages and warnings by setting DIAGNOSTIC=fault
. If you set DIAGNOSTIC=*
, then no diagnostics will appear. The extra
setting gives you extra information, in the form of a dump of the current state of the job; but this is likely to be useful only for developers of Genstat. Printing of diagnostics can also be controlled by the DIAGNOSTIC
option of JOB
.
The ERRORS
option controls what Genstat does when many faults happen within a single job while in batch mode. By initial default, up to five errors per job are reported, and successive faults will not generate diagnostic messages. This ensures, for example, that input intended to be read by a READ
statement will not generate many lines of diagnostics if execution halts because of a fault before the READ
statement. Note, however, that this option does not affect the detailed error messages printed by the READ
directive itself: these are controlled separately by the corresponding ERRORS
option of READ
. In interactive mode, the count of errors is restarted after each successful statement is issued, though the option is unlikely to be useful in this mode.
The FAULT
option is provided primarily to allow procedure writers to modify the internal record that is kept of the most recent fault indicator. Setting FAULT=*
clears the record; you can then use the GET
directive to ascertain whether a fault has occurred since the record was cleared. You can also set the fault indicator to a particular diagnostic, for example
SET [FAULT='VA4']
A subsequent DISPLAY
statement will then report the chosen fault in the standard way. The fault indicator is automatically cleared at the start of each job.
The PAUSE
option allows you to specify how many lines of output are produced at a time; you might, for example, want to read the output on a terminal screen before more output replaces it. Obviously this is relevant only in interactive mode, and may not be needed in the implementations of Genstat that provide a scrollable output window. By initial default, all output is sent to the current output channel as soon as it is available. Some computers can store the output, irrespective of whether Genstat itself has a scrollable window, and let you scroll forward and back to read it at leisure: others just provide keys to freeze the output while you are reading a section, and then to continue to the next segment of output. If you set PAUSE=n
, then after every n lines of output Genstat gives a prompt:
*Press RETURN to continue*
After you have read the displayed section of output, you can press the <RETURN>
key to get the next n lines. The counting of lines is restarted each time you give a statement from the keyboard: it is not restarted between separate statements in a macro, procedure or auxiliary input channel. If you have specified that Genstat should echo input lines, these are included among the n. Once all the output has been displayed, Genstat prompts for further statements.
The PROMPT
option specifies the characters used to prompt for interactive input. The initial default is the greater-than character followed by a space “>
“. The prompt can also be modified by the PROMPT
option of JOB
. Other prompts are used by READ
and EDIT
, and these cannot be altered.
The NEWLINE
option allows you to cancel the initial default whereby a new line () is a terminator both for strings within a string list (1.6.2) and for a statement (1.8). Thus, for example, if you specify
SET [NEWLINE=ignored]
you need no longer use a backslash (\ to continue a statement onto a new line, since is no longer interpreted as the end of a statement. But you will then have to terminate each statement explicitly with a colon.
The CASE
option specifies whether upper-case and lower-case letters are to be treated as the same in identifiers. The initial default is that upper and lower case are not the same; thus, an identifier X
is distinct from an identifier x
. If CASE
is set to ignored
, then in later statements, both x
and X
are treated as the same identifier, X
. Thus the structure with identifier x
cannot be referenced, unless CASE
is later reset to significant
.
The FIELDWIDTH
option allows you to control the minimum fieldwidth that is used as a default by PRINT
and other output commands. The initial default is 12.
In PRINT
the default number of decimal places for a numerical structure is determined by calculating the number that would be required to print its mean absolute value to at least d significant figures. The initial default for d is four, but you can redefine this using the SIGNIFICANTFIGURES
option.
The SEEDS
option specifies the default seeds to be used to generate random numbers in various areas of Genstat. You can set SEED
to a scalar to define a single seed to be used for all the areas. Alternatively, you can supply a pointer to define a different seed for each area. The elements of the pointer should be labelled to indicate the area concerned: for example 'calculate'
, and 'randomize'
for random-number functions and the RANDOMIZE
directive respectively. The easiest way to see the possibilities is to save the current seeds using the SEEDS
option of the GET
directive; this saves a pointer with elements labelled automatically. You will notice, though, that the GET
pointer represents each seed as a variate (with several values) rather than a scalar. This is because, once any randomization has been done in an area, there is too much seed information to store in a single number. Variates are equally valid for the elements of the SET
pointer. So you can save the current seeds using GET
, and then restore them by using the same pointer in SET
.
The RUN
option controls whether Genstat interprets the program as being in batch or in interactive mode; this assumed mode is independent of whether the program really is being run in batch or interactively. Initially, a program is taken to be in interactive mode only if the first input channel and the first output channel are both connected to a terminal. The setting of the assumed mode has two effects – on recovery from faults, and on how EDIT
operates.
The UNITS
option provides another way of setting the units structure in addition to the UNITS
directive. The setting can be the identifier of a variate or text structure; this will become the default labelling structure of other variates, texts or factors with the same length, in those directives that use such labels. The setting can also be a scalar to specify the default number of units. The setting of the UNITS
option is lost at the end of each job within a program.
The BLOCKSTRUCTURE
, TREATMENTSTRUCTURE
, COVARIATE
, ASAVE
, DSAVE
, MSAVE
, RSAVE
, TSAVE
, VSAVE
and VCOMPONENTS
options specify special save structures for graphical and analysis directives. You can set the options only to an identifier that you have previously established by the SPECIAL
option of the GET
directive or by the SAVE
options of the various analysis directives themselves. For example, if two sets of regression analyses are in progress in one job, the SET
directive can be used to switch between them:
MODEL [SAVE=S1] Y1
FIT X1
MODEL [SAVE=S2] Y2
FIT X1
SET [RSAVE=S1]
FIT X1,X2
This program fits the regression of Y1
on X1
, using save structure S1
, then the regression of Y2
on X1
with save structure S2.
Finally, it fits the regression of Y1
on X1
and X2
, because the current regression save structure is changed to S1
before the last FIT
statement. The settings of these options are all lost at the end of a job.
The WORDLENGTH
option controls the number of characters that are stored and checked in identifiers and names of directives, procedures, options, parameters and functions. In releases prior to 4.2 this was always eight, but from 4.2 onwards you can choose between eight (WORDLENGTH=short
) and 32 (WORDLENGTH=long
). This can also be controlled by the JOB
directive and, within a procedure, by the PROCEDURE
directive. The default is to leave the setting unchanged.
The CAPTIONS
option controls which captions are displayed by directives and procedures. This can be used inside a procedure to suppress irrelevant captions that would be produced by the procedures or directives that it calls. The setting can be restored by the RESTORE
option of the PROCEDURE
statement, or by saving the current setting using GET
, and then restoring it by using another SET
. The initial default is to display all types of caption.
The TYPESET
option controls whether typesetting commands within textual strings (see PRINT
) are recognised used in output and in labels and titles on graphs. The initial default is to use them in both.
The CMETHOD
option is useful if you have programs from Release 10 or earlier that use the old way of specifying graphics colours. Prior to Release 11, you had to use one of Genstat’s 256 standard colours, and redefine its RGB definition, if necessary, using the COLOUR
directive. In Release 11, the representation of colours was changed to allow you to use standard colour names (see PEN
for details). So virtually all options and parameters of the directives and library procedures that define colours were modified to take strings or texts as their settings. Further flexibility was given by interpreting numeric settings directly as RGB values. However, if you have a program from Release 10 or earlier that relies on the old standard colours, you can put
SET [CMETHOD=standard]
to interpret numeric settings of colour options and parameters later in your program as standard colour numbers instead of RGB values.
The DATASPACE
option allows you to increase the current data space allocations. You can set this to a variate of length three to specify a different size for each of the three types of data: real numbers (for numeric data), integers (for factors and system information) and characters (for texts). Alternatively, you can set it to a scalar to specify the same size for all three types. The sizes are measured in blocks of 32768 values. If any of the data spaces is already larger than the specified size, its size is left unchanged. This option can be useful if you know that your next analysis is likely to require lot of space – it is more efficient to reserve all the space at once, rather than leaving it to Genstat to expand each allocation every time that it becomes full.
The WORKINGDIRECTORY
option allows you to set the working directory (the default directory where Genstat will open or save files).
The ALGORITHMS
option allows you to request the use of enhanced computing algorithms. The initial default, at the start of any Genstat run, is to use only the standard algorithms. However, if you set ALGORITHMS=mkl
, it will use algorithms from the Intel® Math Kernel Library for operations such as eigenvalue decompositions and matrix inversion. These should provide much faster performance with large problems.
The ACTIONAFTERFAULT
option allows you to control what happens if a fault occurs inside a procedure or during a batch run. The initial default, at the start of any Genstat run, is that execution of the procedure or the batch script stops. However, you can set ACTIONAFTERFAULT
to continue
to request that it continues instead. The FAULT
option of GET
can be used to access the most recent fault code, so that you can make your own decision about what to do next if a fault occurs.
A dummy is a data structure that stores the identifier of a data structure. This can be useful with options and parameters that expect another type of data structure. If you supply a dummy, it will be replaced by the identifier that it stores. The UNSETDUMMY
option controls what happens if the dummy is unset. The initial default is to give a warning, and replace the dummy by the default for the option or parameter if one has been defined, or otherwise to treat the option or parameter as though it had not been set. If you set UNSETDUMMY
to ignore
, no warning is given. Finally, if you set it to fault
, unset dummies are treated as faults.
Some Genstat commands can now provide output in languages other than English. The LANGUAGE
option allows you to supply a text with either one or two values to specify your preferred language in its first value, and (optionally) your second choice in its second value. Output will then be generated in your preferred language if that is available. Otherwise it may be in your second-choice language or, if neither are available, the command will generate the ordinary English output.
The YEAR2DIGITBREAK
option controls how two digits can be used to specify years: whether thse represent years in the 1900’s or the 2000’s. YEAR2DIGITBREAK
specifies the cut-off date: dates less than this value represent years beginning 20, and two digit dates greater than or equal to this value will represent years beginning 19. For example, if it is set to 30, years in the range 00 – 29 will represent the years 2000 – 2029 and years in the range 30 – 99 represent the years 1930 – 1999. Alternatively, the value 0 ensures that all 2 digit dates belong to the 1900’s, while the value 100 means that they all belong to the 2000’s.
Options: INPRINT
, OUTPRINT
, DIAGNOSTIC
, ERRORS
, FAULT
, PAUSE
, PROMPT
, NEWLINE
, CASE
, FIELDWIDTH
, SIGNIFICANTFIGURES
, SEEDS
, RUN
, UNITS
, BLOCKSTRUCTURE
, TREATMENTSTRUCTURE
, COVARIATE
, ASAVE
, DSAVE
, MSAVE
, RSAVE
, TSAVE
, VSAVE
, VCOMPONENTS
, WORDLENGTH
, CAPTIONS
, TYPESET
, CMETHOD
, DATASPACE
, WORKINGDIRECTORY
, ALGORITHMS
, ACTIONAFTERFAULT
, UNSETDUMMY
, LANGUAGE
, YEAR2DIGITBREAK
.
Parameters: none.
See also
Directives: GET
, PROCEDURE
.
Commands for: Program control.
Example
" Example 1:1.8.2 " SET [INPRINT=statements,macros] SCALAR IDENTIFIER=X,Root; VALUE=48 TEXT [NVALUES=3] Estsqrt OPEN NAME='%GENDIR%/Examples/GuidePart1/ALG.DAT'; CHANNEL=2 READ [CHANNEL=2] STRUCTURE=Estsqrt ##Estsqrt ##Estsqrt ##Estsqrt PRINT [IPRINT=*] '3 iterations calculate the square root of 48 as',Root CLOSE 2 ENDJOB