Text to be used as final prompt; the default prompt specifies the mode of response and lists the default values (if any), in brackets, followed by ">"

Structure to store response; default * allows a menu to be saved without being executed

Mode of response (e, f, p, t, v); default p

Response to be assumed if just <RETURN> is given; default is to repeat the prompt until a response is obtained

Whether a list of responses, rather than a single response, is valid (yes, no); default no

Whether identifiers must already be declared (yes, no); default no

Allowed types for identifiers (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

Whether the identifier must have values (yes, no); default no

Lower limit for numbers; default *, meaning no check

Upper limit for numbers; default *, meaning no check

Text to be used in response to a general query for the question; default *

Saves or reinputs the specification of the menu (which is then used for any options or parameters not redefined)

Parameters

Possible codes for MODE t; (no default for MODE t; not relevant for others)

Text giving explanation of each letter code; (no default for MODE t; not relevant for others)

Text to be used in response to a specific query for a code; default *

Description

The QUESTION directive displays a GenStat menu and obtains a response when in interactive mode. In batch, the directive does nothing. Here is a simple example that asks the user to provide the identifier of a variate structure.

The PREAMBLE option specifies a text structure, whose contents are printed at the beginning of the menu. Following this is the prompt: by default, this consists of a reminder of what type of answer is expected, followed by the greater-than symbol (>). However, there is a PROMPT option that allows any text to be printed instead, before the greater-than symbol.

The RESPONSE option specifies a dummy identifier that will point to the answer given by the user. Menus can request information in one of five modes; the default is Mode p (pointer), as here, and expects a response to consist of an identifier; but the MODE option can also be set to v (variate), t (text), e (expression) or f (formula). When a correct answer has been received, an unnamed structure of the relevant type (pointer, variate, or whatever, but see later for text mode) is set up, and the dummy in the RESPONSE option is set to point at this unnamed structure.

Thus, if you give the identifier Y in response to the question above, the dummy _yvar will store the identifier of a pointer containing the single identifier Y. So the QUESTION statement could be followed by

to do an analysis-of-variance of Y. The hash (#) is needed here to substitute the values of the unnamed pointer that is stored in the dummy structure _yvar.

By default, a question will expect to receive a single item of the specified mode: identifier, number, string, expression or formula. However, if the option LIST is set to yes for modes p, v or t, then a list of items is expected. The unnamed structure set up to store the answer will then contain as many values as there are items in the list.

The other three options in the example above specify restrictions on the answer that will be accepted. The DECLARED option specifies that the identifier must be of a structure that has already been declared. If a previously unused identifier is given, the QUESTION statement will print a warning, and issue the prompt again. Similarly, the TYPE option specifies what type of structure is acceptable; the setting may be a list of types if relevant. The PRESENT option specifies that the structure must already have values. Two further options, LOWER and UPPER, can be used to specify limits for numbers given in response to questions of mode v.

Menus of mode t resemble more closely what most people think of as a menu than the example above. These menus require extra information to be specified using parameters of the QUESTION directive. The VALUES parameter should be set to a list of text structures, each of which stores a single string that is acceptable as an answer to the question. The CHOICE parameter should be set to another list of text structures, each storing a single string to be displayed by the side of the corresponding code in the menu to explain it. This example shows a question from procedure AGDESIGN.

The codes must obey the rules for unquoted strings: that is, they must start with a letter and consist only of letters and digits. Only the first eight characters will be displayed, and only the first eight characters of the answer will be checked - all eight must match. Usually, of course, it is convenient to use single-letter codes.

Note that mode t cannot be used to ask the user for an arbitrary string, for example to provide a label for output. To request such information, you must use mode p, and set TYPE=text; the user must then supply the string in quotes, or supply the identifier of a text structure that already stores the string.

The response to a question of mode t is stored not as a text, but as a variate each value of which is the number of the corresponding code as listed in the VALUES parameter. Usually, of course, a menu of mode t will be set with LIST=no, the default, and so the variate will contain only a single number. This can be used to control subsequent action in the menu system, for example with a CASE statement.

The DEFAULT option specifies a default answer to be used if the user just types RETURN, and can be set for any mode of question. The HELP option and parameter of the QUESTION directive allow you to provide help text to guide the person answering the question. The SAVE option allows you to declare a menu without executing it, and also to execute a menu that has already been stored.

Options: PREAMBLE, PROMPT, RESPONSE, MODE, DEFAULT, LIST, DECLARED, TYPE, PRESENT, LOWER, UPPER, HELP, SAVE.