Navigating a Procedure

In this section:

You can navigate a procedure in the following ways:


Top of page

x
Performing Unconditional Branching

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 of the labels it encounters so that they can be found immediately if needed again. However, If it encounters a -GOTO command that bypasses certain labels, those labels do not go on the list. When Dialogue Manager processes a -GOTO command, it first checks its list of labels. If the target label is already on the list, control is transferred to that label. If the target label is not on the list, Dialogue Manager searches forward through the procedure for the target label. If it reaches the end without finding the label, it continues the search from the beginning 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.

Note: It is recommended that you not use Dialogue Manager commands as labels.



x
Syntax: How to Perform Unconditional Branching
-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 except -QUIT or -EXIT. 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 follows the -GOTO command, a dash does not precede it.

TYPE text

Sends a message to a client application.



Example: Performing Unconditional Branching

The following example comments out all the FOCUS code using an unconditional branch rather than -* in front of every line:

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

Top of page

x
Performing Conditional Branching

In this section:

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: An -IF test does not require that each test specify a target label.



x
Syntax: How to Perform Conditional Branching
-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 command 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 except -QUIT or -EXIT. 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.

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 Performing a Compound -IF Test.

ELSE GOTO

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: Testing 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 
-IF &LINES NE 0 GOTO PRODSALES;
-EXIT
-PRODSALES
TABLE FILE SALES
SUM UNIT_SOLD
BY PROD_CODE ACROSS CITY
END


Example: Executing Stacked Commands and Exiting the Procedure

In the following example, the first report request or the second report request, but not both, will execute. Assume the report is launched by an HTML form that uses a text input variable named &PROC to prompt the user for the procedure to run. 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 LAST_NAME
    BY DEPARTMENT
   END

The procedure processes as follows:

  1. Dialogue Manager passes SALES to &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 WebFOCUS Client application, 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.



Example: Canceling the Execution of a Procedure With Conditional Branching

The following example illustrates the use of -QUIT to cancel execution based on the results of an -IF test. Assume the report is launched by an HTML form that uses a text input variable named &SELECT to prompt the user for the procedure to run.

-IF &SELECT EQ 'DONE' GOTO QUIT;
-REPORT
   TABLE FILE SALES
   SUM UNIT_SOLD
   BY PROD_CODE
   WHERE AREA EQ '&SELECT';
   END
-RUN
-QUIT

The user can run sequential reports by hitting the Back button in the browser and entering a new value for SELECT and resubmitting the form. If a product code is selected, the procedure continues to the next line and the request executes before encountering -QUIT. When the user enters DONE, control passes to -QUIT. The procedure is exited.



x
Performing a Compound -IF Test

A compounded -IF test is a series of -IF tests nested within each other. You can use a compound -IF test if each test specifies a target label.



Example: Using a Compound -IF Test

In the following 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. Assume the report is launched by an HTML form that uses a text input variable named &OPTION to prompt the user for the procedure to run.

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

Top of page

x
Looping in a Procedure

How to:

You can perform a function repeatedly by using looping in your procedure with the -REPEAT command. Looping can be used for many tasks. For example, files can be named and renamed by embedding operating system calls within a Dialogue Manager loop. Indexed variables can also be populated using a loop, or the output of a request can be used for 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:

You can also limit the repetition of a loop by incrementing a variable with the -SET command.



x
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. It is compared with the value of fromval and toval, if supplied. The loop is executed only if &variable is less than or equal to toval when s is positive, or greater than or equal to toval when s is negative.

fromval

Is the minimum value of &variable that will execute a loop. 1 is the default value.

toval

Is the maximum value of &variable that will execute a loop. 1,000,000 is the default value.

STEP s

Increments the value of &variable by a constant, s. 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

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.

Top of page

x
Calling Another Procedure With -INCLUDE

How to:

Reference:

You can call a procedure from another procedure with the -INCLUDE command, which can incorporate a whole or partial procedure. 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 (called) has full access to variables defined in the calling procedure.

Procedures called using the -INCLUDE command must be in the search path of the WebFOCUS Reporting Server. For information about the search path, see Storing and Searching for Application Files.

In Developer Studio, the -INCLUDE command can be inserted with the Include component. For information on using the Include component, see Calling a Procedure From the Current One in the Creating Reporting Applications With Developer Studio manual.



x
Reference: Uses for -INCLUDE

The -INCLUDE command can be used for the following:



x
Syntax: How to Call Another Procedure With -INCLUDE
-INCLUDE filename

where:

filename

Is the name of the called procedure:

  • On UNIX and Windows platforms, the procedure must have the extension .fex.
  • On UNIX, filename must specify the absolute path and file name for the called procedure. For example, F:\\ibi\apps\sales\headings.fex.
  • On z/OS, the included file must reside in the EDARPC library.


Example: Calling Another Procedure With -INCLUDE

In the following example, Dialogue Manager searches for a procedure named DATERPT as specified on 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 = '&PRODUCT';
END


Example: Calling 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: Calling 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 will be dynamically included before the report request executes.



x
Syntax: How to Call Another Procedure in a Different Application

If the procedure (FOCEXEC) that is included in another procedure is in a different application, issue the command:

-INCLUDE APPNAME/FOCEXEC

Top of page

x
Using Fully Qualified Names With the -Include Command

In this section:

How to:

The -INCLUDE Dialogue Manager command can accept fully qualified file names so that files outside of the standard search path can be inserted into procedures. This technique reduces the time it takes to search for a specific procedure, providing a performance benefit.

Relative paths are not supported in the -INCLUDE command and must use the fully qualified platform-specific file name. The limit for a fully qualified platform-specific file name is defined by the operating system (as long as it is within the 32K length maximum for a FOCEXEC line).

The fully qualified name applies only to the -INCLUDE command in which it is specified. It is not inherited by other -INCLUDE commands.



x
Syntax: How to Use a Fully Qualified File Name on UNIX
-INCLUDE /path/filename.ext

where:

path

Is the fully qualified path to the file that contains the FOCEXEC.

filename

Is the name of the file that contains the FOCEXEC.

ext

Is the extension of the file that contains the FOCEXEC.



x
Syntax: How to Use a Fully Qualified File Name on Microsoft Windows
-INCLUDE drive:\path\filename.ext

where:

drive

Is the drive that contains the path to the FOCEXEC.

path

Is the fully qualified path to the file that contains the FOCEXEC.

filename

Is the name of the file that contains the FOCEXEC.

ext

Is the extension of the file that contains the FOCEXEC.



Example: Using a Fully Qualified Name in a -INCLUDE Command

Assume the FOCEXEC named HEADINGS contains the following heading text for the request:

HEADING
"THIS IS THE INCLUDED HEADING FILE"
" "

Microsoft Windows example:

TABLE FILE EMPLOYEE
-INCLUDE c:\ibi\srv55\mydataarea\headings.fex
PRINT CURR_SAL BY LAST_NAME BY FIRST_NAME
WHERE DEPARTMENT EQ 'MIS'
END

UNIX example:

TABLE FILE EMPLOYEE
-INCLUDE /u2/prog/headings.data
PRINT CURR_SAL BY LAST_NAME BY FIRST_NAME
WHERE DEPARTMENT EQ 'MIS'
END

The output is:



x
Nesting Procedures With -INCLUDE

Any number of different procedures can be invoked from a single calling procedure. You can also nest -INCLUDE commands within each other as seen here. There is no limit to the number of -INCLUDE commands that can be nested.

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


Top of page

x
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. The called procedure must be fully executable.

Procedures called using the -INCLUDE command must be in the search path of the WebFOCUS Reporting Server. For information about the search path, see Storing and Searching for Application Files.

In Developer Studio, you can insert the EXEC command with the Execute component. For details on the Execute component, see Calling a Procedure From the Current One in the Creating Reporting Applications With Developer Studio manual.



x
Syntax: How to Call a Procedure With the EXEC Command
EX[EC] procedure

where:

procedure

Is the name of the procedure.

Note: When EXEC is used in Managed Reporting, it is important to note that there is a difference between EX and EXEC. EX statements coded in a procedure are processed by the WebFOCUS Client, which looks for the procedure in the Managed Reporting repository. Procedures that are referenced with an EXEC statement are not processed by the WebFOCUS Client, they are only passed to the WebFOCUS Reporting Server for processing, and these procedures are not looked for in the Managed Reporting repository.



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

WebFOCUS