SET directive
Sets details of the "environment" of a GenStat job.
Options
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 lets you 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 lets you 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, EDIT and QUESTION, and these cannot be altered.
The NEWLINE option allows you to cancel the initial default whereby a newline (<RETURN>) 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 <RETURN> 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 can specify a pointer containing variates, each containing four integers. These define the default seeds to be used in various areas of GenStat. 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. (Note: if the pointer has been saved by the GET directive, the variates will have been labelled automatically.) Alternatively, SEED can be set to a scalar, to define a single seed to be used for all the areas.
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.
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.
Parameters: none.
See also