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 is 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 |
| TIMEWITHSECONDS = string token | Controls whether seconds are included with the time12 and time24 date representations; (absent, present, unchanged); default unch |
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.
The TIMEWITHSECONDS option controls whether seconds will be present or absent in output with the time12 and time24 date representations. The default is to leave the current setting unchanged.
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