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 hasn't 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 an error message is displayed.

Syntax: How to Branch Unconditionally 

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

where:

-label

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

Note: The word CONTINUE can be used as a label in a -GOTO that is not part of a -IF command, but CONTINUE will not be recognized as a label in a -IF command, where it always transfers to the command immediately following the -IF.

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

Example: Branching Unconditionally

The following example "comments out" all the FOCUS code using an unconditional branch. This is more efficient that placing -* 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, an -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 12 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 except -QUIT or -EXIT. Do not use arithmetic or logical operations, words that can be confused with functions, or reserved words. The word CONTINUE can be used as a label in a -GOTO that is not part of a -IF command, but CONTINUE will not be recognized as a label in a -IF command, where it always transfers to the command immediately following the -IF.

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. For more information see Conditional Branching Based on a Compound -IF Test.

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: Performing Conditional Branching

The following example passes control to the label -PRODSALES if &OPTION is equal to S. Otherwise, control passes to the label -PRODRETURNS, the next line in the procedure. 

-IF &OPTION EQ 'S' GOTO PRODSALES;
-PRODRETURNS
TABLE FILE SALES
PRINT PROD_CODE UNIT_SOLD
BY STORE_CODE
END
-EXIT
-PRODSALES
TABLE FILE SALES
SUM UNIT_SOLD
BY PROD_CODE
END
-EXIT

The following command specifies both transfers explicitly: 

-IF &OPTION EQ 'S' GOTO PRODSALES ELSE
- GOTO PRODRETURNS;

Notice that the continuation line begins with a hyphen and includes a space after the hyphen.

Example: Conditional Branching Based on Testing of System and Statistical Variables

In the following example, if data (&LINES) is retrieved with the request, then the procedure branches to the label -PRODSALES; otherwise, it terminates. 

TABLE FILE SALES
SUM UNIT_SOLD
BY PROD_CODE BY CITY
WHERE TOTAL UNIT_SOLD GE 50
ON TABLE HOLD
END 
-RUN
-IF &LINES NE 0 GOTO PRODSALES;
-EXIT
-PRODSALES
TABLE FILE SALES
SUM UNIT_SOLD
BY PROD_CODE ACROSS CITY
END

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. An -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 FOCUS code is processed, and stacked to be executed later.
  3. -EXIT executes the stacked commands. The output is sent to the terminal and the procedure is terminated.

    The request under the label -EMPLOYEE is not executed.

Example: Conditional Branching Based on a Compound -IF Test

A compound -IF test is a series of nested -IF tests nested. In a compound -IF test, each test must specify a target label.

In this example, if the value of &OPTION is neither R nor S, the procedure terminates (-GOTO QUIT). -QUIT serves both as a target label for the GOTO and as an executable command. For the procedure to run, a user must supply a value for a variable named &OPTION. 

-IF &OPTION EQ 'R' THEN GOTO PRODRETURNS ELSE IF
- &OPTION EQ 'S' THEN GOTO PRODSALES ELSE
- GOTO QUIT;
-PRODRETURNS
TABLE FILE SALES
PRINT PROD_CODE UNIT_CODE
BY STORE_CODE
END
-EXIT
-PRODSALES
TABLE FILE SALES
SUM UNIT_SOLD
BY PROD_CODE
END
-RUN
-QUIT

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:

Note that the -SET command provides another method for implementing loops. See Controlling Loops With -SET.

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. See Incorporating Another Procedure With ‑INCLUDE and Calling Another Procedure With EXEC.

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 -QUIT or -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.

&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

Example: Controlling Loops With -SET

The following example illustrates the use of -SET to control a loop: 

1. -DEFAULT &N=0 
2. -START 
3. -SET &N=&N+1; 
4.   EX SLRPT
   -RUN 
5. -IF &N GT 5 GOTO NOMORE; 
6. -GOTO START 
5. -NOMORE TYPE EXCEEDING REPETITION LIMIT
   -EXIT

The procedure executes as follows:

  1. The -DEFAULT command gives &N the initial value of 0.
  2. -START begins the loop. This is also the target of an unconditional -GOTO.
  3. The -SET command increments the value of &N by one each time the loop executes.
  4. The FOCUS command EX SLRPT is stacked. -RUN then executes the stacked command.
  5. The -IF command tests the current value of the variable &N. If the value is greater than 5, control passes to the label -NOMORE, which displays a message for the end user and forces an exit. If the value of &N is 5 or less, control goes to the next Dialogue Manager command.
  6. -GOTO passes control to the -START label, and the loop continues.

Incorporating Another Procedure With -INCLUDE

How to:

You can insert a whole or partial procedure in another procedure with the -INCLUDE command. A partial procedure might contain heading text, or code that should be included at run time based on a test in the calling procedure. It executes immediately when encountered.

A calling procedure cannot branch to a label in a called procedure, and vice versa. When a procedure is included using the -INCLUDE command, the procedure being included has full access to variables defined in the calling procedure.

The -INCLUDE command can be used for the following:

Syntax: How to Incorporate a File 

-INCLUDE filename [filetype]

where:

filename

Is the name of a FOCUS procedure.

filetype

Is the procedure's DDNAME. If none is included, FOCEXEC is assumed.

Example: Incorporating Another Procedure With -INCLUDE

In the following example, Dialogue Manager searches for a procedure named DATERPT as specified by the -INCLUDE command. 

-IF &OPTION EQ 'S' GOTO PRODSALES ELSE GOTO PRODRETURNS;
   .
   .
   .
-PRODRETURNS
-INCLUDE DATERPT
-RUN 
   .
   .
   .

Assume that DATERPT contains the following code, which Dialogue Manager incorporates into the original procedure. Dialogue Manager substitutes a value for the variable &PRODUCT as soon as the -INCLUDE is encountered. -RUN executes the request. 

TABLE FILE SALES
PRINT PROD_CODE UNIT_SOLD
WHERE PROD_CODE EQ '&PRODUCT';
END

Example: Incorporating a Procedure With a Heading

The following incorporates a heading, which is stored as a procedure: 

TABLE FILE SALES
-INCLUDE SALEHEAD
SUM UNIT_SOLD AND RETURNS AND COMPUTE
   .
   .
   .

The file SALEHEAD contains:

HEADING
"THE ABC CORPORATION"
"RETAIL SALES DIVISION"
"MONTHLY SALES REPORT"

This heading is included in the report request.

Example: Incorporating a Procedure for a Virtual Field

The following incorporates a virtual field from a procedure: 

-INCLUDE DEFRATIO
   TABLE FILE SALES
-INCLUDE SALEHEAD
   SUM UNIT_SOLD AND RETURNS AND RATIO
   BY CITY
   .
   .
   .

The file DEFRATIO creates a virtual field:

DEFINE FILE SALES
RATIO/D5.2=(RETURNS/UNIT_SOLD);
END

This virtual field is dynamically included before the report request executes.

Nesting Procedures With -INCLUDE

Any number of different procedures can be invoked from a single calling procedure.

You can also nest a procedure within itself, or recursively. Recursive -INCLUDE commands cannot exceed four levels. For non-recursive -INCLUDE commands, the level of nesting is limited only by the available memory.

Files 1 through 4 are incorporated into the original procedure. All of the included files are viewed as part of the original procedure.

A procedure cannot branch to a label in an included file.

Calling Another Procedure With EXEC

How to:

You can call a procedure from another procedure with the EXEC command. The called procedure must be fully executable. It behaves as a completely separate procedure with its own content. It cannot use any local variables (&variables) defined by the calling procedure (unless they are explicitly passed to the called procedure on the command line). However, the executed (called) procedure can use any global variables (&&variables) that have been defined in the calling procedure.

When an EXEC command is encountered, it is stacked and executed when the appropriate Dialogue Manager command is encountered.

Syntax: How to Call a Procedure With the EXEC Command 

EX[EC] procedure

where:

procedure

Is the name of the procedure.

You can include arguments for the procedure. See Supplying Variable Values on the Command Line.

Note: This syntax is identical to execution syntax for any stored procedure. However, in this context the EXEC command is included within another procedure.

Example: Calling a Procedure With EXEC

In the following example, a procedure calls DATERPT: 

-IF &OPTION EQ 'S' GOTO PRODSALES ELSE GOTO PRODRETURNS;
    .
    .
    .
-PRODRETURNS
    EX DATERPT
    .
    .
    .
-RUN

Note: If the last executable command in the called procedure is a -CRTFORM, control is not returned to the calling procedure unless another Dialogue Manager command is included to terminate the -CRTFORM, such as -RUN or a -label.

Developing an Open-Ended Procedure

A file of stored FOCUS commands without variables looks and executes exactly as though it had been typed interactively into FOCUS from the terminal. However, if there is an error in your procedure file, it will be rejected. If you make an error while typing interactively from the terminal, FOCUS issues prompts to help you correct the error.

If you store a procedure without the END command, you can execute all of the procedure lines. The terminal opens to allow interactive completion of the procedure. You can add additional command lines and enter the END command from the terminal to complete the procedure.

Note that you cannot use amper variables when typing online at a terminal. Open-ended procedures do not support variable substitution in lines entered after the terminal is opened. Variable substitution is supported in the stored portion of the procedure.

Example: Developing and Running an Open-Ended Procedure

Assume the following open-ended procedure is stored as SLRPT: 

-TYPE ENTER REST OF PROCEDURE
 TABLE FILE SALES
 HEADING CENTER
 "MONTHLY REPORT"
 SUM UNIT_SOLD AND RETURNS AND COMPUTE
 RATIO/D5.2 = 100 * RETURNS/UNIT_SOLD;

You can invoke the procedure by typing EX SLRPT. It executes normally but fails to encounter an END command in the file. It then opens up the terminal displaying the FOCUS prompt. You could supply: 

BY STORE_CODE
END

Or, alternatively:

IF CITY IS STAMFORD
BY STORE_CODE
END
 Information Builders