Inline Prompts |
![]() ![]() ![]() |
Inline prompts provide a means to prompt for data needed by a sentence or paragraph when it is executed. The DATA command does not affect inline prompting which always takes its response from the keyboard. There are also variants on inline prompts that retrieve data from other sources, providing a generalised way to substitute variable items into a command.
An inline prompt has the general form
<<{control,} text {, check}>>
where
The control option has two parts; the display control and the response control. Both parts are optional.
The display control may contain any of the following items. Multiple items may be concatenated, separated by commas, and are performed in the order in which they appear.
The response control consists of one of the items listed below. If omitted, the prompt is actioned only for the first occurrence of a prompt with the given text. Subsequent execution of the same inline prompt or another with the same text will not cause a prompt to be displayed but will use the response to the previous prompt. All prompt responses are discarded on return to the command prompt. The CLEAR.PROMPTS command can be used to discard all inline prompt responses from within a paragraph.
All formats of the C control code may include a default value. For example, <<C4:SALES>> The default value will be applied if the prompt would otherwise return a null string.
<<@name:value>> The default value will be applied if the prompt would otherwise return a null string.
<<$name:value>> The default value will be applied if the prompt would otherwise return a null string.
The Cn and In control codes are only useful in paragraphs. A command that references a paragraph (PA-type VOC entry) may include additional text that can be accessed using these control codes. In a command that references a stored sentence (S-type VOC entry), any additional text following the sentence name is added to the end of the sentence expansion, making effective use of these control codes impossible. There is no reason why a paragraph cannot contain only a single sentence if these control codes are to be used.
The <<@var>> construct allows @variables to be inserted into any command, simplifying paragraph structure. For example: SAVE.LIST LIST.<<@USERNO>> could be used to save a select list with a name that includes the user number to ensure uniqueness for the duration of the user's QM session.
The check code performs simple data validation and is either a pattern match template or an input conversion code. Multiple patterns can be specified separated by the word OR with a single space either side. For example,
3N'-'4N OR 4N'-'3N
would accept numbers of the form 123-4567 or 1234-567.
Input conversion codes must be enclosed in brackets. Any of the codes that can be used with the ICONV() function may be used. The check is considered successful if no conversion error occurs. The value returned by the prompt is the actual text entered, not the result of the conversion.
Entry of QUIT at the keyboard in response to an inline prompt will abort and return to the command prompt. The @ABORT.CODE variable will be set to 2 as for QUIT entered at other prompts.
Inline prompts are expanded as the first stage of processing a command. This has two important effects: An inline prompt in a comment line will be evaluated. This slightly strange effect can be useful as a means to perform all prompts at the start of the paragraph rather than as they are needed, perhaps much later. An IF command in a paragraph where the conditioned statement includes an inline prompt will display the prompt before determining whether the condition is true.
A single command may contain multiple inline prompts. These will be evaluated left to right. Nested inline prompts will be evaluated from the inside outwards.
The response to an inline prompt may not include the left or right double angle bracket symbols (<< and >>) or field marks. Entering a response containing one of these will cause the prompt to be repeated.
When used as an item to test in an IF command, the prompt will usually need to be enclosed in quotes so that a response that contains spaces or reserved keywords does not cause the command parsing to fail. For example IF <<Customer number>> = "" THEN STOP should be written as IF "<<Customer number>>" = "" THEN STOP
Examples
PA SELECT ORDERS SAVING UNIQUE CUST.NO_ WITH DATE AFTER <<Start date>> LIST CUSTOMERS NAME_ HEADING "Clients ordering after <<Start date>>"
The above paragraph uses two identical inline prompts. The first asks the user to enter a start date for a SELECT operation. The second prompt will not repeat the request as the answer is already known. Note that the prompt text can contain spaces and that the inline prompt substitution occurs even though it is part of a quoted string.
PA * <<Target file>> RUN OVN.PROCESS OVN.RPT <<Target file>>
In this example, the inline prompt is in a comment. Although the prompt will be issued at the start of the paragraph, the result is not used until the final command. If the OVN.PROCESS program takes a considerable length of time to execute, this technique allows the prompt to be answered early, without having to wait for the program to complete.
PA * <<I2,Target file>> RUN OVN.PROCESS OVN.RPT <<Target file>>
By adding the I2 control option to the previous example, the paragraph will take the target file name from the second word on the command line if present, prompting if it is not given.
PA LOOP IF <<A,Customer>> = "" THEN STOP LIST ORDERS WITH CUST.NO = <<Customer>> REPEAT
This paragraph uses a loop in which the user is prompted to enter a customer number. If this is a null string, the paragraph terminates. Otherwise it lists the ORDERS file records for this customer. Note the use of the A option on the first prompt in the loop so that it is repeated on each cycle of the loop. Without this, the paragraph would list the orders for the same customer continuously until stopped by user action.
SAVE.STACK <<@LOGNAME>> DISPLAY Domain is <<$USERDOMAIN>>
These two commands show use of the inline prompt mechanism to insert the value of system variables into commands. The first uses an internal QM @variable to retrieve the user's login name, the second accesses the operating system USERDOMAIN environment variable.
DISPLAY Licence number <<SYSTEM(31)>>
This example uses the inline prompt mechanism to access the QM licence number via the QMBasic SYSTEM() function.
See also: |