In this section: |
You can navigate a procedure in the following ways:
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.
-GOTO label . . . -label [TYPE text]
where:
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.
Sends a message to a client application.
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
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.
-IF expression [THEN] {GOTO label1|CONTINUE} [ELSE IF...;] [ELSE {GOTO label2|CONTINUE}];
where:
Is a valid expression. Literals do not need to be enclosed in single quotation marks unless they contain embedded blanks or commas.
Is an optional command that increases readability of the command.
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.
Continues to the command that follows the semicolon of the -IF command.
Note: CONTINUE cannot be used as a label in a -IF statement.
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.
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.
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.
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
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:
If the value for &PROC had been EMPLOYEE, control would pass to -EMPLOYEE.
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.
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.
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.
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
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:
Note: If you issue another -GOTO later in the procedure to return to the loop, the loop proceeds from the point it left off.
You can also limit the repetition of a loop by incrementing a variable with the -SET command.
-REPEAT label n TIMES
or
-REPEAT label WHILE condition;
or
-REPEAT label FOR &variable [FROM fromval] [TO toval] [STEP s]
where:
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.
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.
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 semi-colon.
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.
Is the minimum value of &variable that will execute a loop. 1 is the default value.
Is the maximum value of &variable that will execute a loop. 1,000,000 is the default value.
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.
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
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:
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.
The -INCLUDE command can be used for the following:
-INCLUDE filename
where:
Is the name of the called procedure:
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
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.
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.
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.
-INCLUDE /path/filename.ext
where:
Is the fully qualified path to the file that contains the FOCEXEC.
Is the name of the file that contains the FOCEXEC.
Is the extension of the file that contains the FOCEXEC.
-INCLUDE drive:\path\filename.ext
where:
Is the drive that contains the path to the FOCEXEC.
Is the fully qualified path to the file that contains the FOCEXEC.
Is the name of the file that contains the FOCEXEC.
Is the extension of the file that contains the FOCEXEC.
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:
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.
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.
EX[EC] procedure
where:
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.
In the following example, a procedure calls DATERPT:
-IF &OPTION EQ 'S' GOTO PRODSALES ELSE GOTO PRODRETURNS; . . . -PRODRETURNS EX DATERPT . . . -RUN
WebFOCUS |