Branching Techniques for Managing WebFOCUS Applications Joel Starkman Director, FOCUS Division Information Builders, Inc. October, 2011 Copyright 2011, Information Builders. Slide 1 Prepare to discuss FOC_NONE and _FOC_NULL in WebFOCUS if they come up

Managing Flow A procedure can be navigated by: Unconditional branching ( ) – transfer control to a label Conditional branching ( ) – transfer control to a label depending on the outcome of a test Looping – perform a set of commands repeatedly

‑ label [TYPE text] Branching to a Label The –label command creates a physical reference point in the code as a target of a –GOTO or –IF statement user ‑ defined name, up to 64 characters. No blanks, nor the name of any Dialogue Manager command except ‑ QUIT or ‑ EXIT Optional – sends a message to the client

Unconditional Branching An “unconditional branch” via –GOTO always transfers control to the specified label. -GOTO label.. (any executable code). (any Dialogue Manager code). -label [TYPE text].

Unconditional Branching Example Skip over the TABLE request by jumping to the –SKIPOVER label -GOTO SKIPOVER TABLE FILE SALES PRINT UNIT_SOLD RETURNS BY PROD_CODE BY CITY END ‑ RUN ‑ SKIPOVER ‑ TYPE Skipped over the report

The Plant Sales Report Management would like us to modify a report that currently allows an analyst to select the plant and a specific year. The modified report should display all years for specific plant in a sales summary report sorted by product. Before: After:

Run the Procedure The WebFOCUS Auto Prompting facility opens

Activate the Unconditional Branching Change the source code:

Activate the Unconditional Branching Change the source code:

Run the Procedure

View the DM and FOCUS Commands View the effect of the –SET &ECHO=ALL; command

View the DM and FOCUS Commands skipped

Conditional Branching expression any valid expression on which to make the decision label1 passes control to label1 when expression is true (THEN is optional) CONTINUE drops to the command after the ending semicolon (;) ELSE GOTO label2 passes control to label2 when expression is false ELSE IF/THEN/ELSE compound ‑ IF inside the outer ‑ IF ( with its own labels) -IF expression [THEN] GOTO label1|CONTINUE - [ELSE IF/THEN/ELSE[;]] - [ELSE GOTO label2|CONTINUE]; -IF expression [THEN] GOTO label1|CONTINUE - [ELSE IF/THEN/ELSE[;]] - [ELSE GOTO label2|CONTINUE]; Conditional branching transfers control to one of several labels, based on the evaluation of an expression

Conditional Branching Example ‑ 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 Pass control to ‑ PRODSALES if &OPTION equals ‘S’, otherwise pass control to the next line Not needed in this simple case

Compound –IF Example ‑ IF &OPTION EQ 'R' THEN GOTO PRODRETURNS ELSE ‑ IF (&OPTION EQ 'S') GOTO PRODSALES ELSE ‑ GOTO QUIT; ‑ * ‑ PRODRETURNS TABLE FILE SALES PRINT PROD_CODE UNIT_CODE BY STORE_CODE END ‑ GOTO QUIT ‑ PRODSALES TABLE FILE SALES SUM UNIT_SOLD BY PROD_CODE END ‑ QUIT

Compound IF Alternative Syntax The previous nested –IF expression: ‑ IF &OPTION EQ 'R' THEN GOTO PRODRETURNS ELSE ‑ IF (&OPTION EQ 'S') GOTO PRODSALES ELSE ‑ GOTO QUIT; may be written as separate expressions (clearer?): ‑ IF &OPTION EQ 'R' THEN GOTO PRODRETURNS; ‑ IF &OPTION EQ 'S' THEN GOTO PRODSALES; ‑ GOTO QUIT Semicolons end each statement Semicolons end each statement

The Branch Report Constance Paine needs our help in fixing a procedure that should allow an analyst to choose between summing sales by Store Name or by Region.

Open the Procedure Code targets for Dialogue Manager additions

Using GUI Tools for adding DM GUI tools for adding Dialogue Manager Commands

Adding Conditional Branching The Dialogue Manager -IF wizard

Adding Conditional Branching The Dialogue Manager -IF wizard

Adding a Label Add a Dialogue Manager Label

Adding Unconditional Branching Add a -GOTO

Verify Your Work The Logical View

The Plant Sales Report Management would like a report that allows an analyst to select the plant and either a specific year or all years for a sales summary report sorted by product.

Run the Procedure Need to add the ‘ALL’ option

Add the Conditional Branching Add the ALL option to &YEAR

Activate the Conditional Branching Activate the conditional branching statements

Activate Conditional Branching Add the –SET command and the page heading reference

Run the Procedure The page heading text reflects your changes

Change the Selection Criteria There were zero records for the Boston plant in 1999 You never want to see this error

Activate the Error Message Activate the Dialogue Manager commands &LINES reserved &variable (one of many) Contains number of output lines in the previous TABLE &LINES reserved &variable (one of many) Contains number of output lines in the previous TABLE -INCLUDE Inserts code from errorout.fex and executes it as if it was actually coded here -INCLUDE Inserts code from errorout.fex and executes it as if it was actually coded here

Open the Procedure The ERROROUT procedure contains HTML statements bracketed by –HTMLFORM BEGIN and –HTMLFORM END

Run the Procedure WebFOCUS now displays an error message That’s better! might want to use SET EMPTYREPORT=ON instead of a message

Looping with -REPEAT Copyright 200B, Information Builders. Slide 35

Looping A series of commands can be performed repeatedly by using looping with the ‑ REPEAT command -REPEAT has three variations: For a specific number of times While a condition is true For a calculated number of times (with a referenceable counter)

Looping Alternate Loop Control –REPEAT is a convenient substitute for using a –SET with a variable that acts like a counter to control a loop Example: -SET &N=0 ‑ START ‑ SET &N=&N+1; –TYPE REPETITION &N ‑ IF &N GT 5 GOTO NOMORE; ‑ GOTO START ‑ NOMORE TYPE EXCEEDED REPETITION LIMIT ‑ EXIT Could be written in one line: ‑ IF &N LE 5 GOTO START;

Looping a Specific Number of Times ‑ REPEAT label n TIMES end-of-loop marker the number of times to execute the loop

Looping a Specific Number of Times For example: ‑ REPEAT LAB1 2 TIMES ‑ TYPE INSIDE LOOP ‑ LAB1 -TYPE OUTSIDE LOOP The output is: INSIDE LOOP INSIDE LOOP OUTSIDE LOOP

Looping While a Condition is True ‑ REPEAT label WHILE condition end-of-loop marker condition under which to re-execute the loop each time

Looping While a Condition is True Example -SET &INPUT = ‘ ‘; -SET &GOT_ONE = 0; -SET &A = 0; ‑ REPEAT LABEL WHILE &GOT_ONE EQ 0 -SET &A = &A + 1; ‑ TYPE LOOP &A ‑ READ fromfile &INPUT.10. -SET &GOT_ONE = &IORETURN; ‑ LABEL -SET &A = &A – 1; -TYPE GOT &A RECORDS ‑ REPEAT label WHILE condition For a 2-record file, the output shows: LOOP 1 LOOP 2 LOOP 3 GOT 2 RECORDS Another reserved system & variables

Looping a Calculated Number of Times ‑ REPEAT label FOR &variable [FROM fromval] [TO toval] [STEP s] ‑ REPEAT label FOR &variable [FROM fromval] [TO toval] [STEP s] end-of-loop marker Loop counter, tested at start of each execution of the loop start value of &variable (default is 1) end value of &variable (default is 1,000,000) increments &variable by a constant ‘ s’. may be positive or negative; default increment is 1

Looping a Calculated Number of Times Example ‑ REPEAT LABEL1 FOR &A FROM 3 TO 7 STEP 2 ‑ TYPE INSIDE &A ‑ LABEL1 -TYPE OUTSIDE &A The output is: INSIDE 3 INSIDE 5 INSIDE 7 OUTSIDE 9 ‑ REPEAT label FOR &variable [FROM fromval] [TO toval] [STEP s] ‑ REPEAT label FOR &variable [FROM fromval] [TO toval] [STEP s]

Looping Prematurely Stop a Loop A loop terminates when: it is executed in its entirety a –QUIT or –EXIT command is issued a –GOTO is issued to a label outside of the loop -REPEAT LOOP 5 TIMES -TYPE HELLO -GOTO OUTSIDELOOP -LOOP -OUTSIDELOOP -TYPE AFTER LOOP See: HELLO AFTER LOOP

The Product Report Management would like a report that reads and counts the products captured in an external SAVE file. Should look like this Should look like this

The Process To accomplish this task, follow these steps: 1.Capture the report output in a SAVE file ‘PRODHOLD’ 2.Use a procedure called PRODLOOP that: loops to read data from the PRODHOLD file displays an incremental counter for each record displays the total records in the file

The SAVE File Select PRODHOLD as a SAVE file

-* File PRODLOOP.FEX -* -SET &ECHO=ALL; -INCLUDE PRODHOLD -RUN -SET &NUMPROD = &LINES; -SET &BLANK = ‘ ‘; -* -TYPE *********************************** -TYPE Total Number of Products - &NUMPROD -TYPE *********************************** -TYPE -*-EXIT -REPEAT LOOP1 FOR &CNTR TO &NUMPROD -SET &PRODCODE = ‘A234’; -SET &PRODNAME = ‘A ’; -READ PRODHOLD &PRODCODE &PRODNAME -IF &IORETURN NE 0 GOTO AFTERLOOP ; -TYPE &CNTR &BLANK &PRODCODE &PRODNAME -LOOP1 -AFTERLOOP -EXIT The PRODLOOP Procedure Generate the data extract Capture &LINES from the report Display # of lines Repeat &NUMPROD times Declare length of &var’s Read a line, 0=got one reserved &variable -SET &PRODCODE = ‘ ‘; -SET &PRODNAME = ‘ ‘; -READ PRODHOLD &PRODCODE.4. &PRODNAME.30. OR

Run the Procedure The report output Columns are not aligned properly Columns are not aligned properly

Edit the Procedure Change the procedure -* File PRODLOOP.FEX -* -SET &ECHO=ALL; -INCLUDE PRODHOLD -RUN -SET &NUMPROD = &LINES; -SET &BLANK = ‘ ‘; -* -TYPE *********************************** -TYPE Total Number of Products - &NUMPROD -TYPE *********************************** -TYPE -*-EXIT -REPEAT LOOP1 FOR &CNTR TO &NUMPROD -SET &PRODCODE = ‘A234’; -SET &PRODNAME = ‘A ’; -READ PRODHOLD &PRODCODE &PRODNAME -IF &IORETURN EQ 0 GOTO AFTERLOOP ; -SET &FIRST = IF &CNTR GT 9 THEN ‘&CNTR.EVAL’ ELSE ‘0&CNTR.EVAL’; -TYPE &FIRST &BLANK &PRODCODE &PRODNAME -LOOP1 -AFTERLOOP -EXIT -SET &FIRST = IF &CNTR GT 9 THEN ‘&CNTR.EVAL’ ELSE ‘0&CNTR.EVAL’;

Run the Procedure The columns have been aligned

Review: Managing Flow Unconditional branching, transfer control to a label –GOTO label Conditional branching, transfer control to a label based on a conditional expression –IF expression GOTO label1 ELSE [IF…] GOTO label2; Repeat a set of commands, via several looping criteria options -REPEAT label n TIMES -REPEAT label WHILE cond -REPEAT label FOR &var FROM x TO y STEP z -label

Thank You

Copyright Information Builders. Slide 54 End of presentation Press esc to exit

Copyright 200B, Information Builders. Slide 55 Conventions Used in this Workshop Business Situation Notes Key Alert Summary

The &ECHO Command &ECHO=Functionality ONDisplays FOCUS commands that are expanded and stacked for execution. ALLDisplays both Dialogue Manager and FOCUS commands that are expanded and stacked for execution. OFFSuppresses both Dialogue Manager and FOCUS commands that are expanded and stacked for execution. NONEPrevents procedure code from being displayed (echoed). Once the value of &ECHO has been set to NONE, it cannot be changed during the session or connection. {-DEFAULT| ‑ SET|EX &ECHO = {ON|ALL|OFF|NONE}

The Procedure 1.The –INCLUDE incorporates the PRODHOLD procedure, which generates the PRODHOLD external file. 2.The –SET commands assign values to the variables needed for the report. For example, &NUMPROD, which is based on &LINES (a statistical variable), the total number of output lines generated from the PRODHOLD procedure. 3.The –TYPE commands act as a page heading to display the total number of products.

View the Variables Add -? &PROD to display the variables that begin with ‘PROD’ and their corresponding values

Termination Commands CommandDescription -EXITForces a procedure to end. All stacked commands are executed and the procedure exits. If the current procedure was called by another procedure, the calling procedure continues processing. Use –EXIT for terminating a procedure after processing a final branch that completes the desired task. The last line of a procedure implies a –EXIT. –EXIT can also be inserted strategically into procedure by a developer to assist the debugging of a complicated set of instructions.

Termination Commands CommandDescription -QUITForces an immediate exit from a procedure. Remnant stacked commands are not executed. If the current procedure was called by another procedure, control returns directly to the client application, not the calling procedure. -QUIT can be the target of a branch. -QUIT FOCUS [n]Where n is the application return code value, which can be a constant or an integer value (the default value is 0). In Developer Studio, terminates the procedure without executing stacked commands, exits WebFOCUS, and returns to either the calling program or the operating system. Upon exiting WebFOCUS, the value of the return code is returned to the calling program, if one exists. This can be useful in programming since the value of the status code can be interrogated to indicate the state when WebFOCUS was exited. -QUIT FOCUS can be the target of a branch.

The PRODLOOP Procedure (continued) The –REPEAT command performs a repetitive section of code that begins with –REPEAT and ends with the –LOOP label  The section repeats for &NUMPROD times (in this case, 17)  The –SET commands define the length of the variables  The –READ command reads each line from the PRODHOLD file and the –TYPE displays each line after it has been read  The process repeats at –LOOP1 for &NUMPROD (17) times

Run the Procedure The page heading reflects the selection for ‘ALL’ INCORRECT

Testing the Attributes of a Variable (existence, type, length, pre-evaluation) ‑ IF &name.attribute expression GOTO label...; property type; one of:.EXIST the presence of a value for a variable.LENGTH the non-blank length of the variable.TYPE the formatting type of the variable (A or I).EVAL substitute the value of a variable immediately, then act on the Dialogue Manager command property type; one of:.EXIST the presence of a value for a variable.LENGTH the non-blank length of the variable.TYPE the formatting type of the variable (A or I).EVAL substitute the value of a variable immediately, then act on the Dialogue Manager command dot is required between &name and attribute dot is required between &name and attribute user-supplied variable user-supplied variable

Testing the Attributes of a Variable Examples -IF &OPTION.EXIST GOTO LAB1 ELSE GOTO… ; -IF &OPTION.LENGTH LE 3 GOTO LAB2 ELSE GOTO…; -IF &OPTION.TYPE EQ A GOTO LAB3 ELSE GOTO …; -IF &OPTION.EVAL LT 99 GOTO LAB4 ELSE GOTO …; Better use for.EVAL -SET &SKIP= IF … THEN ‘-GOTO LAB5’ ELSE ‘-*’; &SKIP &SKIP.EVAL WHY? ignored works