KnowledgeBase 00036: Inline Prompts

Inline prompts are a feature of the "Information style" multivalue products
that allow data to be inserted into a command line within a stored sentence,
paragraph or menu. Although they get their name from the ability to prompt the
user to type in the data to be inserted such as a file name, there are many
other items that can be inserted using this mechanism.

Use of inline prompts in paragraphs can be far easier to develop and maintain
than the equivalent operations performed in a Proc.

This article gives a general overview of inline prompts. For full details,
see the product documentation.

The General Form of an Inline Prompt

An inline prompt consists of a construct that, in its most general form, can be
written as

<<control,prompt,check>>

This can appear anywhere in a command executed from a paragraph, a sentence, a
menu or even (though of limited use) from the command prompt.

The control element determines how, when and where the prompt is
actioned. An inline prompt construct may contain multiple comma separated
control elements. Very often there is no control element at all in which case
the comma before the prompt element is also omitted.

The prompt element is the prompt text to appear on the screen. Some
control elements do not cause a prompt to be displayed in which case the prompt
text is ignored but still forms a useful comment.

The check element, again optional, applies validation to the data entered by the user
in response to the prompt.

Simple Inline Prompt Examples

LIST <<Filename>&gt

The above example will prompt the user to enter a filename which is then
substituted into the command.

LIST SALES WITH DATE = "<<Date>&gt" HEADING "Sales on <<Date>&gt"

The above example contains two inline prompts with identical prompt
text. In this situation the command processor will only prompt once, using the
same response in both substitutions.

Getting Information from the Command Line

It is often useful in a paragraph to insert items from the command line that
started the paragraph into commands within it. This can be done with the
Cn option that substitutes the n'th token from the command line,
for example,

LIST <<C2,File>&gt

In this example, the prompt text "File" is not needed but forms a useful
comment to anyone reading the paragraph.

Using the I control code will insert an item from the command line in the
same way as the C control code except that a prompt appears if the item is not
present in the command line. This allows the user to supply data on the command
line but, if perhaps they cannot remember what is required, to be prompted.

LIST <<I2,File>&gt

This time the prompt text "File" is needed.

Getting Information from a File

Sometimes it is useful to insert data from a file. This might be, for
example, a tax rate stored centrally within the application.

LIST SALES EVAL "PRICE * <<F(VOC,TAX.RATE,2)>&gt"

In this example, the inline prompt reads the TAX.RATE record from the VOC and
inserts the content of field 2 into the command line.

Validation

The optional check element of the inline prompt applies validation to the data
entered by the user. It is either a conversion code enclosed in round brackets
or a pattern match template. If the validation is unsuccessful, the prompt is
repeated.

Use with a conversion code verifies that the data can be converted but the
substituted value of the inline prompt is still the data as entered by the
user. Because it is possible for a developer to create their own conversion
codes, it is possible to validate against any criteria in this way.

Use with a pattern match template provides simply validation that the entered
data has a specific form. The template may be formed from multiple
alternatives, including constants, separated by "OR". For example,

LIST SALES <<LPTR for printer,'LPTR' OR ''>>

Other Control Elements

There are other control elements that allow construction of lists from a
repeated prompt (R), forcing a prompt to occur every time around a loop (A),
etc.

There are also additional control elements for performing very basic terminal
screen formatting such as positioning the cursor.

The Strange Behaviour of Comments

Because inline prompts are handled as the first stage of parsing a command,
they are evaluated even when they appear in comments. At first sight this
appears to be very strange behaviour but it allows a paragraph to prompt for
data early on that it will not use until much later.

QM Extensions

QM introduces many extensions to the inline prompt mechanism. The examples
below show how some of these could be used.

Insert command line items 2 to 4:

<<C2-4>>

Insert command line items 3 onwards:

<<C3+>>

Insert item 3, defaulting to SALES if not in the command line.

<<C3:SALES>>

Process items from a select list, returning a blank response on reaching
the end of the list:

<<L>>

Calling a QMBasic subroutine, substituing the value returned by the first
argument to this subroutine into the command. Additional arguments can be
included in the SUBR element:

<<SUBR(name)>>

Substitute the value of the QMBasic SYSTEM() function for a given key:

<<SYSTEM(91)>>

Substitute an @variable, for example the user's login name:

<<@LOGNAME>>

Substitute an operating system environment variable:

<<$TERM>>

There are several more extensions described in the user documentation.