Inline Prompts

Inline Prompts

Top  Previous  Next

 

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

 

controldetermines the way in which the prompt is displayed and how it is actioned on subsequent execution of the same statement or another with the same text. Control codes are generally case insensitive. A single inline prompt may have multiple comma separated control elements or none.

 

textis the prompt text to be displayed. An equals sign is automatically added to the end of the prompt text. The text should be enclosed in single quotes, double quotes or backslashes if it contains characters that might otherwise lead to mishandling of the prompt such as a comma.

 

checkis used to check whether the response to the prompt is valid. If omitted, no checking is performed.

 

 

The control options are of two types; display controls and response controls. Both are optional and may be intermixed.

 

 

A 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.

 

@(col, row)specifies the display position for the prompt text. The QMBasic @() function variants with a negative value for the first (or only) argument are also supported.

 

@(BELL)sounds the audible warning. The BELL OFF command will suppress this action.

 

@(CLR)Clears the display.

 

@(TOF)Positions to the top left of the display. This is equivalent to use of @(0,0).

 

 

A 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 exactly 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.

 

AAlways prompt. This is usually needed on the first occurrence of each prompt in a loop so that each iteration of the loop prompts again.

 

CnUsed in paragraphs to take the n'th token of the sentence that started the paragraph as the response to the prompt. No prompt text will appear unless the implicit response fails to meet the check conditions. The C control code has several extended forms:
Cm-nReturns tokens m to n.
Cn+Returns tokens n onwards.
C#Returns the number of tokens in the command line.

All formats of the C control code except C# may include a default value. For example,

<<C4:SALES>>

The default value will be applied if the prompt would otherwise return a null string.

 

CHANGE(str, old, new)Change all occurrences of substring old in str with new. Argument values may be enclosed in quotes if necessary to avoid any syntactic ambiguity.

 

F(file, key {,field {, value {, subvalue}}})Use record key of the data portion of the named file as the response to the prompt. The optional field, value and subvalue allow extraction of a particular part of the record.

 

ICONV(str, code)Apply input conversion code to str. Argument values may be enclosed in quotes if necessary to avoid any syntactic ambiguity.

 

InUsed in paragraphs to take the n'th token of the sentence that started the paragraph as the response to the prompt. If this is a null string or the implicit response fails to meet the check conditions, an input prompt appears.

 

LnExtracts the next item from select list n. If n is omitted, it defaults to zero. When the select list is exhausted, a null string is returned. This control code does not need to be used with the A control code in a loop as it always reads the next list entry.

 

OCONV(str, code)Apply output conversion code to str. Argument values may be enclosed in quotes if necessary to avoid any syntactic ambiguity.

 

RPrompt repeatedly for input, concatenating data with an intervening space until a blank line is entered.

 

R(string)Prompt repeatedly for input, concatenating the responses with string between responses until a blank line is entered. The string may not include field mark characters. An abort will occur if a field mark is specified as part of string.

 

SnTake the n'th token of the sentence entered at the command prompt as the response to the prompt. If this is a null string or the implicit response fails to meet the check conditions, an input prompt appears.

 

SUBR(name)Execute catalogued QMBasic function name, returning the result of this function as the value of the inline prompt.

 

SUBR(name, arg1, arg2)Execute catalogued QMBasic function name, passing in the given arguments and returning the result of this function as the value of the inline prompt. Up to 254 arguments may be specified. These may be enclosed in quotes if necessary to avoid any syntactic ambiguity.

 

SYSTEM(n)Returns the value of the QMBasic SYSTEM(n) function.

 

UConverts the data entered in the response to the prompt to uppercase. Note that this control must appear before any other control options to which it is to apply.

 

@varThe name of an @-variable, including user defined names (see the SET command), may be used to retrieve the value of the given variable. A default value may be applied by use of a prompt of the form:

<<@name:value>>

The default value will be applied if the prompt would otherwise return a null string.

 

$varThe name of an operating system environment variable may be used to retrieve the value of the given variable. A default value may be applied by use of a prompt of the form:

<<$name:value>>

The default value will be applied if the prompt would otherwise return a null string.

 

 

Note: The C and S control may appear to be backwards. The C control bases its result on the content of the @SENTENCE variable and the S control bases its result on the content of the @COMMAND variable. These control elements were originally defined in another multivalue product and QM preserves this apparently incorrect implementation for compatibility.

 

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. The paragraph can always be structured in a way to avoid this behaviour.

 

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.

 

 

PA

LOOP

  IF <<L,ID>> = "" THEN STOP

  MYPROG <<ID>>

REPEAT

 

This paragraph uses a loop to walk through the default select list, executing MYPROG for each entry taken from the list.

 

 

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. Note the use of quotes in the first command to allow for the possibility of the user name containing a space.

 

 

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:

CLEAR.PROMPTS