Obtains a response using a Genstat menu (S.A. Harding & R.W. Payne).
Options
PREAMBLE = text |
Text posing a question; (no default) |
|---|---|
PROMPT = text |
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 “>“ |
RESPONSE = identifier |
Structure to store response; default * allows a menu to be saved without being executed |
MODE = string token |
Mode of response (p, t, v); default p |
DEFAULT = identifier |
Response to be assumed if just |
LIST = string token |
Whether a list of responses, rather than a single response, is valid (yes, no); default no |
DECLARED = string token |
Whether identifiers must already be declared (yes, no); default no |
TYPE = string tokens |
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 |
PRESENT = string token |
Whether the identifier must have values (yes, no); default no |
LOWER = scalar |
Lower limit for numbers; default *, meaning no check |
UPPER = scalar |
Upper limit for numbers; default *, meaning no check |
HELP = text |
Text to be used in response to a general query for the question; default * |
SAVE = pointer |
Previously allowed you to save or reinput the specification of the menu, but is now no longer supported |
Parameters
VALUES = texts |
Possible codes for MODE t; (no default for MODE t; not relevant for others) |
|---|---|
CHOICE = texts |
Text giving explanation of each letter code; (no default for MODE t; not relevant for others) |
HELP = texts |
Text to be used in response to a specific query for a code; default * |
Description
The QUESTION directive was replaced in the 16th Edition by the QDIALOG directive, with updated facilities appropriate to the more recent computing environments. This procedure uses QDIALOG to duplicate most of the facilities of the directive, so that existing programs can still run. The main difference is that the SAVE option and the option settings MODE=e and MODE=f are no longer supported.
So QUESTION displays a Genstat menu and obtains a response when in interactive mode. In batch, the procedure does nothing. Here is a simple example that asks the user to provide the identifier of a variate structure.
QUESTION [PREAMBLE=!t('Y-VARIATE Menu (from ANOVA Menu)',*,\
'What is the variate to be analysed ?'); RESPONSE=_yvar;\
DECLARED=yes; TYPE=variate; PRESENT=yes]
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) or t (text). The earlier MODE settings of e (expression) and f (formula) are now faulted. 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
ANOVA #_yvar
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 procedure. 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.
QUESTION [PREAMBLE='Do you want to print the design?';\
RESPONSE=pdes; MODE=t; DEFAULT='n'; LIST=no]\
VALUES='n','y'; CHOICE='no','yes'
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 procedure allow you to provide help text to guide the person answering the question.
The SAVE option, which allowed you to declare a menu without executing it or to execute a menu that has already been stored, is no longer supported.
Options: PREAMBLE, PROMPT, RESPONSE, MODE, DEFAULT, LIST, DECLARED, TYPE, PRESENT, LOWER, UPPER, HELP, SAVE.
Parameters: VALUES, CHOICE, HELP.
See also
Directive: QDIALOG.
Commands for: Program control, Calculations and manipulation.
Example
CAPTION 'QUESTION example'; STYLE=meta
" Ability to speak the official languages of the European Union."
TEXT [VALUES=Bulgarian,Czech,Danish,Dutch,English,\
Estonian,Finnish,French,German,Greek,\
Hungarian,Irish,Italian,Latvian,Lithuanian,\
Maltese,Polish,Portuguese,Romanian,Slovak,\
Slovene,Spanish,Swedish] Languages
TEXT [VALUES=A,D,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W] Codes
QUESTION [PREAMBLE='What languages do you speak (check all that apply)?';\
RESPONSE=Responses; MODE=t; LIST=yes;\
HELP='Check the box for each language, and then click on OK'];\
VALUES=#Codes; CHOICE=#Languages
FACTOR [LABELS=Languages; VALUES=#Responses] Reply
PRINT Reply