WebFOCUS and Auto-Prompting

By Art Greenhaus

Many users who have experience with character-based FOCUS question the behavior of WebFOCUS auto-prompting. That's because a different mechanism is used to prompt the user for values between the two products. This article will attempt to explain the differences, so users understand what is happening.

With character-based FOCUS, prompting is done during execution when needed. What this means is that when a variable is encountered while a procedure is running, if it has no value, or an explicit –PROMPT for that variable has been encountered, then a prompt is issued to the user, asking to have the value provided. The value may have been set with a '–DEFAULT' control statement, a '–SET' statement or a ‘-? SET’ statement (storing the value of a previous SET parameter). A value may also have been established by reading from an external file (-READ).

The prompt text used to ask the user for the value is determined by how the variable is specified. If only a variable name is used (&VAR), then the default prompt text ('PLEASE SUPPLY VALUES REQUESTED') is printed, followed by the name of the variable being requested. A user supplied prompt and/or format/value list can also be specified, allowing the designer of the code to control how a user is prompted, and what responses are valid. A prompt may be specified with the following format:

&variable[[.{format}].prompt text.]

The '{format}' can be either alpha (Axx), or numeric (Ixx). It can also be a list of possible responses, comma separated, enclosed in parentheses. Thus, the following are valid:

&VAR - (take whatever is supplied by the user)
&VAR.I5. - (up to five characters, numeric including optional decimal point
and optional leading minus sign)
&VAR.ENTER VALUE. - ('ENTER VALUE' is the prompt)
&VAR.(1,2,3).  - (only values 1, 2, or 3 can be supplied)
&VAR.I5.NUMBER. - ('NUMBER' is the prompt, and up to five numeric characters
may be supplied)

Note that character-based FOCUS prompting is done at execution. Physical placement of code is not important. It's the order in which code is executed that determines what, and when, to prompt.

Autoprompting for WebFOCUS is done a bit differently. With WebFOCUS, there's a non-persistent connection. This means, once any response is provided, the connection between the client (user) and server is terminated. A valid response to the user is a prompt for values. Thus, under the current implementation of auto-prompting, the user is prompted only once for any variables which that exist in a procedure.

Whether to prompt for undeclared variables is a function of how the WebFOCUS variable WFDESCRIBE is set. This variable can have one of four values:

OFF (default) - An error message is displayed, indicating variable(s) are
unresolved

XML - An XML document will be returned, showing collected information on
variables

XMLRUN - If all variables have values (potentially through –DEFAULT), then run the
procedure, otherwise prompt for unresolved variables

XMLPROMPT - If all variables have values, through a –SET or as system or statistical
variables, then run the procedure, otherwise prompt for unresolved variables. The values from –DEFAULTS are displayed as the'default'
values in the prompt.

To determine for which variables prompting must be done, the procedure is scanned, line by line. Any ‘–INCLUDEd’ named procedures are also scanned. Since there is no execution, such Dialogue Manager constructs as '.EVAL'  or –READ have no effect. Also, a procedure invoked by an ‘EX’ or ‘EXEC’ is not scanned, since that would required execution of the ‘EX’ command.

This is also why an –INCLUDEd procedure must be named; if the included procedure is a variable, there's no way to determine what the value would be at execution time. Note that this is physically how the lines appear in the procedure, not how they are executed. Any variable is assumed to have a value if it was established. Once the determination is made that a variable has no value, or is explicitly to be prompted for via a –PROMPT, then, based on the value of WFDESCRIBE (above), the appropriate action is taken.

To add functionality to the auto-prompting, additional options exist for the {format} mentioned previously. These are only available through WebFOCUS auto-prompting. For {format}, you can also specify:

(FIND field IN file) For example: &COU.(FIND COUNTRY IN CAR). Select COUNTRY.

This runs a TABLE, and produces a dropdown, of all distinct values of ‘field’ in file ‘file’.

 

(ACCEPT field FROM file) For example: &SEATS.(ACCEPT SEATS FROM CAR). Choose a seat.

This produces a dropdown of all the values in the ACCEPT list for field ‘field’ in file ‘file’.

 

(FROM x TO y) For example: &SEATS.(FROM 2 TO 4).Choose a seat.

For numeric responses, this only allows values within the specified range.