Using Dialogue Manager

In this section:

Dialogue Manager is the part of the WebFOCUS language that controls the execution of your application components and allows you to control the flow of your application with the use of commands and variables. You can dynamically control the execution of procedures, giving you flexibility in application design. Dialogue Manager also enables you to use variables in your procedures and supply values for them at run time.

The following are some of the ways you can use Dialogue Manager:

You can create Dialogue Manager IFs, GOTOs, Labels, and REPEATs. You can also open the Dialogue Manager canvas and create any of the other items manually.

Dialogue Manager Variables Overview

You can write procedures containing variables with values that are unknown until run time, allowing a user to customize the procedure by supplying different values each time it executes. Variables fall into two categories:

Dialogue Manager Processing

You can modify your application at run time with user input and environment conditions by using Dialogue Manager stored procedures, which include commands and variables.

In WebFOCUS App Studio, stored procedures are referred to as procedures.

  1. Processing begins from the command processor when a procedure is invoked for execution.
  2. The FOCEXEC Processor reads each line of the procedure. Any variables on the line are assigned the current values.
  3. All Dialogue Manager commands execute as soon as Dialogue Manager reads them.
  4. When a command line containing no Dialogue Manager commands is fully expanded with any variables resolved (through either a -SET command or prompting), it is placed onto the command execution stack.
  5. Dialogue Manager execution commands and statistical variables route all currently stacked commands to the WebFOCUS Command Processor.

By the time your procedure is ready for execution, the following has happened:

You can use the -TYPE command to send a message to the display while a procedure is processing. Typically, the message serves the following purposes:

Navigating a Procedure

In this section:

You can navigate a procedure in the following ways:

Branching Unconditionally

How to:

You can perform unconditional branching, which transfers control to a label with the -GOTO command.

The first time through a procedure, Dialogue Manager notes the addresses of all the labels so they can be found immediately, if needed again. If Dialogue Manager has not stored the address of the label in the -GOTO command, it searches forward through the procedure for the target label. If no label is found, it begins searching at the top of the procedure.

Dialogue Manager takes no action on labels that do not have a corresponding -GOTO. If a ‑GOTO does not have a corresponding label, execution halts and a message is displayed.

Syntax: How to Branch Unconditionally 

-GOTO label 
  .
  .
  .
-label [TYPE text]

where:

-label

Is a user-defined name of up to 64 characters. Do not use embedded blanks or the name of any other Dialogue Manager command. Do not use arithmetic or logical operations, words that can be confused with functions, or reserved words, such as CONTINUE.

The label text may precede or follow the -GOTO command in the procedure.

Note: When the label is specified in the -GOTO command, a dash does not precede it.

TYPE text

Sends a message to the display.

Example: Branching Unconditionally

The following example comments out all the WebFOCUS code using an unconditional branch, instead of the user typing -* in front of every line: 

-GOTO DONE
TABLE FILE SALES
PRINT UNIT_SOLD RETURNS
BY PROD_CODE,CITY
END 
-RUN 
-DONE

Branching Conditionally

How to:

Conditional branching performs a test of the values of variables and, based on the test, transfers control to a label in the procedure with the -IF... GOTO command. This helps control the execution of requests and builds a dynamic procedure by choosing to execute or not execute parts of a procedure.

For example, you can check whether an extract file was created from a production data source. If the extract file exists, the program runs a set of reports against the extract. If it does not exist, the program branches around the reports and writes a message to a log file.

Note: Generally, a -IF test does not require that each test specify a target label. However, in a compound IF test, where a series of tests are nested within each other, a specified target label is required for each test.

Syntax: How to Branch Conditionally 

-IF expression [THEN] {GOTO label1|CONTINUE} [ELSE IF...] [ELSE {GOTO label2|CONTINUE}] ;

where:

expression

Is a valid expression. Literals do not need to be enclosed in single quotation marks unless they contain embedded blanks or commas.

THEN

Is an optional word that increases readability of the command.

label1

Is a user-defined name of up to 64 characters to which to pass control if the -IF test is true. Do not use embedded blanks or the name of any other Dialogue Manager command. Do not use arithmetic or logical operations, words that can be confused with functions, or reserved words, such as CONTINUE.

The label text may precede or follow the -IF criteria in the procedure.

CONTINUE

Continues to the command that follows the semicolon (;) of the -IF command.

Note: CONTINUE cannot be used as a label in a -IF statement.

ELSE IF

Specifies a compound -IF test. The command -IF must end with a semicolon (;) to signal that all logic has been specified.

ELSE GOTO label2

Passes control to label2 when the -IF test fails.

If a command spans more than one line, continuation lines must begin with a hyphen (-) and one or more spaces.

Example: Conditional Branching Based on User Input

In the following example, the first report request or the second report request, but not both, executes. Suppose that for the procedure to run a user must supply a value for a variable named &PROC. The user may enter SALES or EMPLOYEE. 

1. -IF &PROC EQ 'EMPLOYEE' GOTO EMPLOYEE; 
2. -SALES
   TABLE FILE SALES
   SUM UNIT_SOLD
    BY PROD_CODE
   END 
3. -EXIT
   -EMPLOYEE
   TABLE FILE EMPLOYEE
   PRINT PLANT_NAME
    BY DEPARTMENT
   END

The procedure processes as follows:

  1. The user enters the value SALES for &PROC. A -IF test is done, and since the value for &PROC is not EMPLOYEE, the test fails and control is passed to the next line, -SALES.

    If the value for &PROC had been EMPLOYEE, control would pass to -EMPLOYEE.

  2. The WebFOCUS code is processed, and stacked to be executed later.
  3. -EXIT executes the stacked commands. The output is sent to the display and the procedure is terminated.

    The request under the label -EMPLOYEE is not executed.

Note: When a procedure contains global variables and is terminated by a -EXIT command, values of global variables are not recorded. Therefore, execution of subsequent procedures cannot rely on the values of the global variables being present.

Looping in a Procedure

How to:

You can perform an action repeatedly by looping in your procedure with the -REPEAT command. Looping can be used for many tasks. For example, you can populate an indexed variable using a loop or use the output of a request in a second request.

A process loop can be executed a designated number of times or until a condition is met. A loop ends when any of the following occurs:

  • It is executed in its entirety.
  • A -EXIT command is issued.
  • A -GOTO is issued to a label outside of the loop.

    Note: If you issue another -GOTO later in the procedure to return to the loop, the loop proceeds from the point at which it left off.

Note that the -SET command provides another method for implementing loops.

Tip: During loop processing, the search for labels that indicate the target of a -REPEAT or a -GOTO command takes longer in a procedure with variable, rather than fixed (80 character), record lengths. To speed execution in this situation, consider replacing loops with EX or -INCLUDE commands.

Syntax: How to Specify a Loop 

-REPEAT label n TIMES

or

-REPEAT label WHILE condition;

or

-REPEAT label FOR &variable [FROM fromval] [TO toval] [STEP s]

where:

label

Identifies the code to be repeated (the loop). A label can include another loop if the label for the second loop has a different name than the first.

n TIMES

Specifies the number of times to execute the loop. The value of n can be a local variable, a global variable, or a constant. If it is a variable, it is evaluated only once, so you cannot change the number of times to execute the loop. The loop can only be ended early using -EXIT.

WHILE condition;

Specifies the condition under which to execute the loop. The condition is any logical expression that can be true or false. The loop executes if the condition is true.

Note: The condition must be followed by a semicolon (;).

&variable

Is a variable that is tested at the start of each execution of the loop and incremented by s with each execution. It is compared with the value of fromval and toval, if supplied. The loop is executed only if &variable is greater than or equal to fromval or less than or equal to toval.

fromval

Is a constant that is compared with &variable at the start of the execution of the loop. The default value is 1.

toval

Is a value that is compared with &variable at the start of the execution of the loop. The default value is 1,000,000.

STEP s

Is a constant used to increment &variable at the end of the execution of the loop. It may be positive or negative. The default increment is 1.

Note: The parameters FROM, TO, and STEP can appear in any order.

Example: Repeating a Loop

These examples illustrate each syntactical element of -REPEAT. 

-REPEAT label n TIMES

For example: 

-REPEAT LAB1 2 TIMES
-TYPE INSIDE
-LAB1 TYPE OUTSIDE

The output is:

INSIDE
INSIDE
OUTSIDE
-REPEAT label WHILE condition;

For example: 

-SET &A = 1;
-REPEAT LABEL WHILE &A LE 2;
-TYPE &A
-SET &A = &A + 1;
-LABEL TYPE END: &A

The output is:

1
2
END: 3
-REPEAT label FOR &variable FROM fromval TO toval STEP s

For example: 

-REPEAT LABEL FOR &A STEP 2 TO 4
-TYPE INSIDE &A
-LABEL TYPE OUTSIDE &A

The output is:

INSIDE 1
INSIDE 3
OUTSIDE 5

Using Variables in a Procedure

In this section:

How to:

Reference:

Using interactive variable substitution, you can create procedures that include variables (also called amper variables) and supply values for them at run time. These variables store a string of text or numbers and can be placed anywhere in a procedure. For example, a variable can refer to a field, a command, descriptive text, or a file name.

Note: A Dialogue Manager variable contains only alphanumeric data. If a function or expression returns a numeric value to a Dialogue Manager variable, the value is truncated to an integer and converted to alphanumeric format before being stored in the variable, unless you specify the precision to use.

Variables fall into two categories:

The maximum number of local, global, system, statistical, special, and index variables available in a procedure is 1024. Approximately 40 are reserved for use by WebFOCUS.

Variables can be used only in procedures. They are ignored if you use them while creating reports live at the display.

You can query the values of each type of variable you use.

The values for variables may be supplied in a variety of ways.

Reference: Naming Conventions for Local and Global Variables

Local and global variable names are user-defined, while system and statistical variables have predefined names. The following rules apply to the naming of local and global variables:

  • A local variable name is always preceded by an ampersand (&). The variable can be named or positional.

    A positional variable consists of a single ampersand (&) followed by a numeric string (for example, &1). The value of a positional variable is passed to a procedure when it is executed.

  • A global variable name is always preceded by a double ampersand (&&).
  • A variable name can consist of up to 100 characters.
  • Embedded blanks are not permitted in a variable name.
  • If a value for a variable might contain an embedded blank, comma, or equal sign, enclose the variable in single quotation marks when referred to.
  • A variable name may be any combination of the characters A through Z, 0 through 9, and the underscore (_). The first character of the name should be a letter.
  • You can assign a number instead of a name to a variable to create a positional variable.
  • The underscore may be included in a variable name, but the following special characters are not permitted: plus sign (+), minus sign (-), asterisk (*), slash (/), period (.), ampersand (&), and semicolon (;).

Syntax: How to Specify a Variable Name 

&[&]name

where:

&

Denotes a local variable. A single ampersand (&) followed by a numeric string denotes a positional variable.

&&

Denotes a global variable.

name

Is the variable name. The name you assign must follow the rules outlined for Dialogue Manager.

Local Variables

Local variables are identified by a single ampersand (&) preceding the name of the variable. They remain in effect throughout a single procedure.

Example: Using Local Variables

Consider the following procedure, SALESREPORT, in which &CITY, &CODE1, and &CODE2 are local variables: 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
"PRODUCT CODES FROM &CODE1 TO &CODE2"
" "
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1 TO &CODE2
END

Assume you supply the following values when you call the procedure: 

EX SLRPT CITY = STAMFORD, CODE1=B10, CODE2=B20

Dialogue Manager substitutes the values for the variables as follows: 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR STAMFORD"
"PRODUCT CODES FROM B10 TO B20"
" "
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ STAMFORD
BY PROD_CODE
IF PROD_CODE IS-FROM B10 TO B20
END

After the procedure executes and terminates, the values STAMFORD, B10, and B20 are lost.

Global Variables

Global variables differ from local variables in that once a value is supplied, it remains current throughout the WebFOCUS session unless set to another value with -SET or cleared by the LET CLEAR command. Global variables are useful for gathering values at the start of a work session for use by several subsequent procedures. All procedures that use a particular global variable receive the current value until you exit from WebFOCUS.

Global variables are specified through the use of a double ampersand (&&) preceding the variable name. It is possible to have a local and global variable with the same name. They are distinct and may have different values.

Example: Using Global Variables

The following example illustrates the use of three global variables: &&CITY, &&CODE1, &&CODE2. The values are substituted in the first procedure, PROC1, and the values are retained and passed to the second procedure, PROC2. 

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &&CITY"
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &&CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &&CODE1 TO &&CODE2
END
EX PROC2
TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &&CITY AND PRODUCT &&CODE1"
PRINT UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &&CITY
IF PROD_CODE EQ &&CODE1
END

Querying the Values of Variables and Parameters

How to:

Two Dialogue Manager commands enable you to:

  • Display the values of all types of local, global, and system variables.
  • Store the value of a parameter in a variable. The stored value can then be queried with the ? SET command.

In addition, you can issue two QUERY (?) commands to display the values of:

  • Global variables. Since global variable values remain current throughout the WebFOCUS session, it is helpful to be able to display the values on demand. The syntax is: 
    ? &&
  • Statistics stored in variables. You can query the current value of all statistical variables (except &FOCDISORG and &FOCERRNUM). The syntax is:
    ? STAT

Syntax: How to Display the Value of a Variable

You can query all Dialogue Manager variables (local, global, system, and statistical) from a stored procedure. The syntax is: 

-? &[&variablename]

where:

&

Issued alone, displays variables of all types.

variablename

Is the variable name, including the ampersand (&). Only amper variables starting with the specified string are displayed.

The command displays the following message, followed by a list of currently defined amper variables and the values: 

CURRENTLY DEFINED & VARIABLES:

Since local variables do not exist outside a procedure, no similar query is available from the WebFOCUS command line.