Executing and Terminating a Procedure

In this section:

You can use Dialogue Manager commands to manage the execution and termination of a procedure. The commands used for these purposes are EXEC, -RUN, -EXIT, -QUIT, and -QUIT FOCUS.

Executing Procedures

How to:

Procedures are generally initiated from the FOCUS prompt (>). Type the EXEC command followed by the name of the procedure to run.

If you wish to supply arguments for the procedure, see Supply a Variable Value on the Command Line.

You can execute a single procedure or call and execute one procedure from within another one. For details, see Calling Another Procedure With EXEC.

Syntax: How to Execute a Procedure 

EX[EC] procedure

where:

procedure

Is the name of the procedure.

Example: Executing a Procedure

To summon a procedure named SLRPT for execution, enter either: 

EXEC SLRPT

or

EX SLRPT

Executing Stacked Commands and Continuing the Procedure

You can execute stacked commands and continue the procedure with the -RUN command.

The -RUN command causes immediate execution of all stacked commands and closes any external files opened with -READ or -WRITE. For related information, see Reading Variable Values From and Writing Variable Values to an External File.

Following execution of the stacked commands, processing of the procedure continues with the line that follows -RUN.

Example: Executing Stacked Commands and Continuing the Procedure

The following illustrates the use of -RUN to execute stacked code and then return to the procedure. The numbers to the left correspond to the notes explaining the code. 

1. TABLE FILE SALES
    PRINT PROD_CODE UNIT_SOLD
    BY CITY
   END 
2. -RUN
   TABLE FILE EMPLOYEE
    PRINT LAST_NAME FIRST_NAME
    BY DEPARTMENT
   END

The procedure processes as follows:

  1. The first four lines are the report request. Each line is placed on a stack to be executed later.
  2. -RUN causes the stacked commands to be executed and the output returned to the terminal. Processing continues with the line following -RUN.

Executing Stacked Commands and Exiting the Procedure

You can execute stacked commands then exit a procedure with the -EXIT command. -EXIT forces the execution of stacked commands as soon as it is encountered.

-EXIT closes all external files, terminates the procedure, and returns to the FOCUS prompt unless the procedure was called by another procedure, in which case control returns to the calling procedure. For related information, see Calling Another Procedure With EXEC.

Example: Executing Stacked Commands and Exiting the Procedure

In this example, the first report request or the second report request executes, but not both. 

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

The procedure processes as follows:

  1. Dialogue Manager assigns SALES to &PROC.
  2. 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.

  3. The FOCUS code is processed, and stacked to be executed later.
  4. -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.

This example also illustrates an implicit exit. If the value of &PROC was EMPLOYEE, control would pass to the label -EMPLOYEE after the -IF test, and the procedure would never encounter -EXIT. The TABLE FILE EMPLOYEE request would execute and the procedure would automatically terminate.

Canceling the Execution of a Procedure

How to:

You can cancel the execution of a procedure with the -QUIT command. -QUIT cancels execution of any stacked commands and causes an immediate exit from the procedure. Control returns directly to the application regardless of whether the procedure was called by another procedure.

This command is useful if tests or computations generate results that make additional processing unnecessary.

You can use a variation, -QUIT FOCUS, to cancel the execution of a procedure and terminate the FOCUS session. It returns you to the operating system and sets a return code.

Syntax: How to Cancel the Execution of a Procedure 

-QUIT

Syntax: How to Cancel the Execution of a Procedure and Exit FOCUS 

-QUIT FOCUS [n|8]

where:

n

Is the operating system return code number. It can be a constant or variable. A variable should be an integer. If you do not supply a value or if you supply a non-integer value, the return code posted to the operating system is 8 (the default).

A major function of user-controlled return codes is to detect processing problems. The return code value determines whether to continue or terminate processing. This is particularly useful for batch processing. For related information, see Testing the Status of a Query.

Example: Canceling the Execution of a Procedure

The following example illustrates the use of -QUIT to cancel execution based on the results of an -IF test: 

1. -DEFAULT &CODE='B11'; 
2. -IF &CODE EQ '0' OR &CODE EQ 'DONE' GOTO QUIT; 
3. TABLE FILE SALES 
   SUM UNIT_SOLD
   WHERE PROD_CODE EQ &CODE
   END  
4. -QUIT

The procedure processes as follows:

  1. The -DEFAULT command sets the default value for &CODE to B11.
  2. The value B11 is passed to &CODE.
  3. The FOCUS code is processed, and stacked to be executed later.
  4. -QUIT cancels the execution of stacked commands and exits the procedure.

Locking Procedure Users Out of FOCUS

How to:

Users can respond to a Dialogue Manager value request with QUIT and return to the FOCUS command level or the prior procedure. In situations where it is important to prevent users from entering native FOCUS or QUIT from a particular procedure, the environment can be locked and QUIT deactivated.

Syntax: How to Lock Procedure Users Out of FOCUS

Enter the following command within the procedure: 

-SET &QUIT=OFF;

With QUIT deactivated, any attempt to return to native FOCUS produces an error message indicating that "quit" is not a valid value. The user is prompted for another value.

A user can terminate the FOCUS session from inside a locked procedure by responding to a prompt with 

QUIT FOCUS

to return to the operating system, not the FOCUS command level.

Note: The default value for &QUIT is ON.

Information Builders