OPTION directive

Defines the options of a GenStat procedure with information to allow them to be checked when the procedure is executed.


No options


Parameters

NAME = texts
Names of the options

MODE = strings
Mode of each option (e, f, p, t, v, as for unnamed structures); default p

NVALUES = scalars or variates
Specifies allowed numbers of values

VALUES = variates or texts
Defines the allowed values for a structure of type variate or text

DEFAULT = identifiers
Default values for each option

SET = strings
Indicates whether or not each option must be set (yes, no); default no

DECLARED = strings
Indicates whether or not the setting of each option must have been declared (yes, no); default no

TYPE = texts
Text for each option, whose values indicate the types allowed (ASAVE, datamatrix {i.e. pointer to variates of equal lengths as required in multivariate analysis}, diagonalmatrix, dummy, expression, factor, formula, LRV, matrix, pointer, RSAVE, scalar, SSPM, symmetricmatrix, table, text, tree, TSAVE, TSM, variate, VSAVE); default * meaning no limitation

COMPATIBLE = texts
Defines aspects to check for compatibility with the first parameter of the directive or procedure (nvalues, nlevels, nrows, ncolumns, type, levels, labels {of factors or pointers}, mode, rows, columns, classification, margins, associatedidentifier, suffixes {of pointers}, restriction)

PRESENT = strings
Indicates whether or not each structure must have values (yes, no); default no

LIST = strings
Whether to allow a list of identifiers (MODE=p) or of values (MODE=v or t) instead of just one (yes, no); default no

INPUT = string
Whether the option only supplies input information to the procedure (yes, no); default no


Description

The OPTION directive is used at the start of the definition of a GenStat procedure (initiated by the PROCEDURE directive) to define the options of the procedure. The NAMES parameter defines the names of the options. Each name also defines the identifier of a data structure that should be used, within the procedure itself, to refer to the information transmitted by the relevant option. When you use the procedure, you have the choice of typing each name in capital letters, or in small letters, or in any mixture of the two; this corresponds to the rules for the names of options and parameters of directives. Within the procedure, however, you need to be more precise, but the exact form of the identifiers will depend upon whether the GenStat environment was set to use short or long "wordlengths" when the procedure was defined. (This is controlled by the WORDLENGTH option of the JOB, SET and PROCEDURE directives.) With long wordlengths, the identifier should be exactly the same as the option name up to the 32nd character; any characters beyond the 32nd are ignored. Alternatively, if short wordlengths have been selected, GenStat forms each identifier by truncating the corresponding option name to no more than eight characters and then converting it into capital letters.

   The MODE parameter tells GenStat whether the setting of each option is to be a number (v), or an identifier of a data structure (p), or a string (t), or an expression (e), or a formula (f). These codes are exactly the same as those that indicate the mode of the values to appear within the brackets containing an unnamed structure.

   The type of the structure used to represent an option of the procedure depends on the MODE and LIST parameters of the OPTION directive.

   For anything other than mode p, the structure will be a dummy. This will point to an expression for mode e, a formula for mode f, and a text for mode t. With mode v, it will point to a scalar if the corresponding setting of the LIST parameter is no, and a variate if LIST=yes.

   For mode p and LIST=no, the structure is a dummy, which will point to whichever structure is supplied for the option when the procedure is called; alternatively, when LIST=yes, it is a pointer which will store the list of structures that are supplied. For example, suppose that procedure ALLPOSS which contains the option definitions

          OPTION \

            NAMES='EXP','FORM','VLN','VLY','TLN','TLY','PLN','PLY'; \

            MODE= e, f, v, v, t, t, p, p;\

            LIST= no, no, no, no, yes, yes, no, yes

is called with these options settings:

ALLPOSS [EXP=LOG10(X+1); FORM=Variety*Nitrogen; VLN=2; \

  VLY=1,3,5,7; TLN=oneval; TLY=one,two,three; \

  PLN=A; PLY=B,C,D]

Inside the procedure it will be as though the identifiers had been defined as follows:

DUMMY [VALUE=!E(LOG10(X+1))] EXP

& [VALUE=!F(Variety*Nitrogen)] FORM

& [VALUE=2] VLN

& [VALUE=!(1,3,5,7)] VLY

& [VALUE='oneval'] TLN

& [VALUE=!T(one,two,three)] TLY

& [VALUE=A] PLN

POINTER [VALUE=B,C,D] PLY

   The other parameters allow the settings that are supplied, when the procedure is called, to be checked automatically.

   The NVALUES parameter indicates how many values the structures that are supplied for an option of mode p may contain. For example,

OPTION NAME='X','Y'; NVALUES=3,!(3,4); TYPE='variate'

indicates that the variates supplied for X must be of length 3, while those supplied for Y can be of length 3 or 4.

   The VALUES parameter can be used with modes t and v to specify an allowed set of values against which those supplied for the option will be checked. In this example, the values allowed for METHOD are LOGIT, COMPLOGLOGOG or ANGULAR.

OPTION NAME='METHOD'; MODE=t; \

  VALUES=!t(LOGIT,COMPLOGLOG,ANGULAR); \

  DEFAULT='LOGIT'

The allowed values for mode t can be up to 32 characters in length; characters 33 onwards are ignored and the values are converted to upper case. When the procedure is used, GenStat will check the specified string against those in the VALUES list, using the same abbreviation rules as for options or parameters of the ordinary GenStat directives. Thus, for example, to request an angular transformation we need merely put METHOD=A as the first letter A is sufficient to distinguish ANGULAR from LOGIT and COMPLOGLOG. Within the procedure, GenStat then sets METHOD to the full string in capitals, ANGULAR, and this greatly simplifies its subsequent use. However, if short wordlengths have been requested, the name is truncated to eight characters, so COMPLOGLOG would become COMPLOGL.

   As an example of mode v, this specification would ensure that the numbers supplied for an option NV were all odd integers between one and nine

          OPTION NAME='NV'; MODE=v; VALUES=!(1,3,5,7,9)

   The DEFAULT parameter specifies default values to be used if the option or parameter or option is not set. Above METHOD will be set by default to 'LOGIT'.

   The SET parameter indicates whether or not an option must be set. The DECLARED parameter specifies whether or not the structures to which options of mode p are set must already have been declared. The TYPE parameter can be used to specify a text to indicate the allowed types of the structures to which an option of mode p is set. The COMPATIBLE parameter can be used to specify compatibility checks to be made for the setting of an option against the first parameter of the procedure. (The parameters are specified using the PARAMETER directive.) The PRESENT parameter allows you to indicate that the structure to which an option is set must have values. Finally, the INPUT parameter allows you to indicate that the option will be used only to provide input to the procedure, and will not be used to output any results. It is not essential to set this parameter but its use can improve efficiency.

   For example, here the options PERCENT and RESULT can be can be either scalars, variates, tables or any type of matrix (rectangular, symmetric or diagonal). Structures to which the PERCENT option is set must have been declared, but for the RESULTS option they need not have been. Likewise the PERCENT option must have values, but the RESULTS option need not.

OPTION NAME='PERCENT','RESULT'; \

  MODE=p; SET=yes; DECLARED=yes,no; \

  TYPE=!t(scalar,variate,matrix,symmetric,diagonal,table); \

  PRESENT=yes,no

 

Options: none.

Parameters: NAME, MODE, NVALUES, VALUES, DEFAULT, SET, DECLARED, TYPE, COMPATIBLE, PRESENT, LIST, INPUT.