Using Dialogue Manager

In this section:

Reference:

Dialogue Manager is the part of the WebFOCUS language that controls the execution of your application components and allows you to control the flow of your application with the use of commands and variables. You can dynamically control the execution of procedures, giving you flexibility in application design. Dialogue Manager also enables you to use variables in your procedures and supply values for them at run time.

The following are some of the ways you can use Dialogue Manager:

You can create Dialogue Manager IFs, GOTOs, Labels, and Repeats. You can also open the Dialogue Manager canvas and create any of the other items manually.


Top of page

x
Reference: Overview of Dialogue Manager Commands

For descriptions and syntax, see Dialogue Manager Quick Reference.

Command

Description

-*

Is a comment line and it has no action.

‑CLOSE ddname

Closes the specified ‑READ or ‑WRITE file.

-CLOSE *

Closes all -READ and -WRITE files currently open.

-DEFAULT
-DEFAULTS

Presets initial values for variable substitution.

-EXIT

Executes stacked commands and returns to the WebFOCUS prompt.

-GOTO

Establishes an unconditional branch.

-HTMLFORM

For use with the web interface to WebFOCUS.

-IF

Tests and branches control based on test results.

-INCLUDE

Dynamically incorporates one procedure in another.

-label

User-supplied name identifying the target for -GOTO or -IF.

-PASS

Sets password directly.

-READ

Reads records from a sequential file.

-READFILE

Reads fields based on a Master File into Dialogue Manager variables.

-REPEAT

Executes a loop.

-RUN

Executes all stacked WebFOCUS commands and returns to procedure for further processing.

-SET

Assigns a value to a variable.

-TYPE

Types informative message to screen or other output device.

-WRITE

Writes a record to a sequential file.

-? SET parameter 
&myvar

Captures the value of a settable parameter in &myvar.

-? &[variablename]

Displays the values of currently defined amper variables.



x
Dialogue Manager Variables Overview

You can write procedures containing variables with values that are unknown until run time, allowing a user to customize the procedure by supplying different values each time it executes. Variables fall into two categories:


Top of page

x
Dialogue Manager Processing

You can modify your application at run time with user input and environment conditions by using Dialogue Manager stored procedures, which include commands and variables.

In App Studio, stored procedures are referred to as procedures.

  1. Processing begins from the command processor when a procedure is invoked for execution.
  2. The FOCEXEC Processor reads each line of the procedure. Any variables on the line are assigned the current values.
  3. All Dialogue Manager commands execute as soon as Dialogue Manager reads them.
  4. When a command line containing no Dialogue Manager commands is fully expanded with any variables resolved (through either a -SET command or prompting), it is placed onto the command execution stack (FOCSTACK).
  5. Dialogue Manager execution commands (for example, -RUN) and statistical variables flush the FOCSTACK and route all currently stacked commands to the WebFOCUS Command Processor.

By the time your FOCSTACK is ready for execution, the following has happened:

Note: Any WebFOCUS command can be placed in a procedure, including the EXEC command. When an EXEC command is processed in a procedure, the commands from the new procedure are first stacked and then executed.


Top of page

x
Creating a Procedure

In this section:

Reference:

You can use the WebFOCUS integrated text editor, TED, or invoke your system editor from WebFOCUS with the IEDIT command to create procedures that contain Dialogue Manager functionality. IEDIT is especially useful with variable length files or those whose record lengths are greater than 80 characters.

TED and IEDIT have two valuable features for creating and editing procedures:

These options complement the FILE and SAVE options that are common to other editors.

In addition to Dialogue Manager commands and variables that directly affect an application's flow of control, you can use commands to:

You can also create a profile procedure that defines startup conditions and can include Dialogue Manager commands.



x
Reference: Rules for Creating Procedures

When creating procedures:



x
Including Comments in a Procedure

It is recommended that you use comments in a procedure heading to supply the date, the version, and other relevant information. A hyphen and an asterisk (-*) mark the beginning of a comment.

Comments are visible only when viewing the contents of the procedure through the editor and are strictly for the benefit of the developer.



x
Syntax: How to Add a Comment in a Procedure
  1. Begin the comment line with the command:
    -*
  2. Type the comment text after the command, optionally with a space before the text.

You can place a comment at the beginning or end of a procedure or in between commands. A comment cannot be on the same line as a command.

The following entry is valid:

.
.
.
-*Version 2 06/10/00
-RUN

The following is invalid:

-RUN -*Version 2 06/10/00


Example: Placing a Comment in a Procedure

The following example places a comment at the beginning of a procedure.

-* Version 1  08/26/02  HRINFO  Procedure
TABLE FILE CENTHR
   .
   .
   .


x
Sending a Message to the User

You can use the -TYPE command to send a message to the display while a procedure is processing. Typically, the message serves the following purposes:



x
Syntax: How to Send a Message to the User

-TYPE sends the message to the display as soon as it is encountered in the processing of a procedure. The syntax is

-TYPE[+|0|1] text						

or

-label TYPE text						

where:

text

Is the message to be sent. The message is sent to the screen, followed by a line feed. It remains on screen until scrolled off or replaced by a new screen.

If you include quotation marks around the text, they are displayed as part of the message. (This differs from the use of TYPE in MODIFY, where quotation marks are used as delimiters and must enclose informative text.)

-label

Is the target of a -GOTO or -IF.

+|0|1

Are optional entries that pass printer control characters to the output device. They are particularly useful for character printers. Options + and 1 do not work on IBM 3270-type displays.

+ suppresses the line feed following the printing of text.

0 forces a line feed before the message text is displayed.

1 forces a page eject before the message text is printed.

If supplied, these values must follow -TYPE without a space.



Example: Sending a Message

The following example illustrates the use of -TYPE to inform a user about the content of a report:

-* Version 1  06/26/00  SLRPT  Procedure
-* Component of Retail Sales Reporting Module
-TYPE This report calculates percentage of returns.
TABLE FILE SALES
 .
 .
 .
END


x
Controlling User Access to Data

You can issue and control passwords with the -PASS command. This is especially useful for specifying a password for a particular file or set of files that a given user can read from or write to. Passwords have detailed sets of functions associated with them through the DBA facility.

The procedure that sets passwords can be encrypted so that it and the passwords that it sets cannot be typed and made known.

A variable can also be associated with -PASS so that you can prompt for and assign a password value. You can also check the value of the password and skip or execute a portion of the procedure depending on the value.



x
Syntax: How to Set a Password in a Procedure
-PASS password						

where:

password

Is a password or a variable containing a password.

Since -PASS is a Dialogue Manager command, it executes immediately and is not sent to the FOCSTACK. This means that the user need not issue the password with the SET command.


Top of page

x
Navigating a Procedure

In this section:

You can navigate a procedure in the following ways:



x
Branching Unconditionally

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 has not 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.



x
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. 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 is specified in the -GOTO command, a dash does not precede it.

TYPE text

Sends a message to the display.



Example: Branching Unconditionally

The following example comments out all the WebFOCUS code using an unconditional branch, instead of the user typing -* in front of every line:

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


x
Branching Conditionally

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.



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

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.

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

    The request under the label -EMPLOYEE is not executed.



x
Looping in a Procedure

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.

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.



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

Note: The condition must be followed by a semi-colon.

&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 WebFOCUS 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.


x
Incorporating Another Procedure With -INCLUDE

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:



x
Syntax: How to Incorporate a File
-INCLUDE filename [filetype]

where:

filename

Is the name of a WebFOCUS procedure.

filetype

Is the DDNAME of the procedure. 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.



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



x
Calling Another Procedure With EXEC

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.



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

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

Top of page

x
Using Variables in a Procedure

In this section:

How to:

Reference:

Using interactive variable substitution, you can create procedures that include variables (also called amper variables) and supply values for them at run time. These variables store a string of text or numbers and can be placed anywhere in a procedure. For example, a variable can refer to a field, a command, descriptive text, or a file name.

Note: A Dialogue Manager variable contains only alphanumeric data. If a function or expression returns a numeric value to a Dialogue Manager variable, the value is truncated to an integer and converted to alphanumeric format before being stored in the variable, unless you specify the precision to use.

Variables fall into two categories:

The maximum number of local, global, system, statistical, special, and index variables available in a procedure is 1024. Approximately 40 are reserved for use by WebFOCUS.

Variables can be used only in procedures. They are ignored if you use them while creating reports live at the display.

You can query the values of each type of variable you use.

The values for variables may be supplied in a variety of ways.



x
Reference: Naming Conventions for Local and Global Variables

Local and global variable names are user-defined, while system and statistical variables have predefined names. The following rules apply to the naming of local and global variables:



x
Syntax: How to Specify a Variable Name
&[&]name

where:

&

Denotes a local variable. A single ampersand followed by a numeric string denotes a positional variable.

&&

Denotes a global variable.

name

Is the variable name. The name you assign must follow the rules outlined for Dialogue Manager



x
Local Variables

Local variables are identified by a single ampersand (&) preceding the name of the variable. They remain in effect throughout a single procedure.



Example: Using Local Variables

Consider the following procedure, SALESREPORT, in which &CITY, &CODE1, and &CODE2 are local variables:

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
"PRODUCT CODES FROM &CODE1 TO &CODE2"
" "
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1 TO &CODE2
END

Assume you supply the following values when you call the procedure:

EX SLRPT CITY = STAMFORD, CODE1=B10, CODE2=B20

Dialogue Manager substitutes the values for the variables as follows:

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR STAMFORD"
"PRODUCT CODES FROM B10 TO B20"
" "
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ STAMFORD
BY PROD_CODE
IF PROD_CODE IS-FROM B10 TO B20
END

After the procedure executes and terminates, the values STAMFORD, B10, and B20 are lost.



x
Global Variables

Global variables differ from local variables in that once a value is supplied, it remains current throughout the WebFOCUS session unless set to another value with -SET or cleared by the LET CLEAR command. Global variables are useful for gathering values at the start of a work session for use by several subsequent procedures. All procedures that use a particular global variable receive the current value until you exit from WebFOCUS.

Global variables are specified through the use of a double ampersand (&&) preceding the variable name. It is possible to have a local and global variable with the same name. They are distinct and may have different values.



Example: Using Global Variables

The following example illustrates the use of three global variables: &&CITY, &&CODE1, &&CODE2. The values are substituted in the first procedure, PROC1, and the values are retained and passed to the second procedure, PROC2.

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &&CITY"
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &&CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &&CODE1 TO &&CODE2
END
EX PROC2
TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &&CITY AND PRODUCT &&CODE1"
PRINT UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &&CITY
IF PROD_CODE EQ &&CODE1
END


x
System Variables

WebFOCUS automatically substitutes values for system variables encountered in a Dialogue Manager request. For example, you can use the system variable &DATE to automatically incorporate the system date in your request.

System-supplied variables should not be overridden. To avoid this possibility, user-supplied variables should not be given system variables names.



x
Reference: Summary of System Variables

The following table describes the Dialogue Manager system variables.

Variable

Format or Value

Description

&DATE
MM/DD/YY

Returns the current date.

&DATEfmt											
&DATXfmt											

Returns the current date or date-time value, where fmt can be any valid date or date-time format. &DATEfmt retains trailing blanks in the returned value. &DATXfmt suppresses trailing blanks in the returned value.

Note: Using the concatenation symbol (|) to remove punctuation between components is not supported. To return a value without punctuation between the components, use &YYMD or &DATEHYYMDN.

For information about date and date-time formats, see Describing an Individual Field in the Describing Data With WebFOCUS Language manual.

Returns the current date or date-time value, where fmt can be any valid date or date-time format. Because many date format options can be appended to the prefix DATE to form one of these variable names, you should avoid using DATE as the prefix when creating a variable name.

&DMY
DDMMYY

Returns the current date.

&DMYY
DDMMCCYY

Returns the current (four-digit year) date.

&FOCCODEPAGE
 

Returns the code page being used by WebFOCUS.

&FOCCPU
milliseconds

Calculates the OS CPU time.

&FOCEXTTRM
ON
OFF

Indicates the availability of extended display attributes.

&FOCFEXNAME
 

Returns the name of the FOCEXEC running even if it was executed using an EX command or a ‑INCLUDE command from within another FOCEXEC. This variable differs from the &FOCFOCEXEC variable because &FOCFOCEXEC returns the name of the calling FOCEXEC only.

&FOCFIELDNAME
NEW
OLD
NOTRUNC

Returns a string indicating whether long and qualified field names are supported. A value of OLD means that they are not supported, NEW means that they are supported, and NOTRUNC means that they are supported, but unique truncations of field names cannot be used.

&FOCFOCEXEC

 

Manages reporting operations involving many similarly named requests that are executed using EX. &FOCFOCEXEC enables you to easily determine which procedure is running. &FOCFOCEXEC can be specified within a request or in a Dialogue Manager command to display the name of the currently running procedure.

&FOCINCLUDE

 

Manages reporting operations involving many similarly named requests that are included using -INCLUDE. &FOCINCLUDE can be specified within a request or in a Dialogue Manager command to display the name of the current included procedure.

&FICLANGCODE

Holds the three-character language code. For example, GER for GERMAN or FRE for FRENCH. This variable is blank when the language is English, either AME or ENG.

 

&FOCMODE
CRJE
MSO
OS
TSO

Identifies the operating environment.

&FOCNEXTPAGE

 

Establishes consecutive page numbering across multiple reports. When a report is processed, the variable &FOCNEXTPAGE is set to the number following the last page number in the report. This value can then be used as the first page number in a subsequent report, making the report output from multiple requests more useful and readable.

&FOCPRINT
ONLINE
OFFLINE

Returns the current print setting.

&FOCPUTLVL
WebFOCUS PUT level number.

For example, 9306 or 9310.

&FOCPUTLVL is no longer supported.

&FOCQUALCHAR
.
:
!
%
|
\

Returns the character used to separate the components of qualified field names.

&FOCREL
release number

Identifies the WebFOCUS Release number. For example, 6.5 or 6.8.

&FOCSBORDER
ON
OFF

Whether solid borders are used in full-screen mode.

&FOCTRMSD
24
27
32
43

Indicates display height. (This can be any value. The examples shown are common settings.)

&FOCTRMSW
80
132

Indicates display width. (This can be any value. The examples shown are common settings.)

&FOCTRMTYP
3270
TTY
UNKNOWN

Identifies the display type.

&FOCUSER

 

Returns the connected user ID. Similar to the GETUSER function.

&HIPERFOCUS
ON
OFF

Returns a string showing whether HiperFOCUS is on.

&IORETURN

 

Returns the code set by the last Dialogue Manager -READ or -WRITE operation. (0 = successful; 1= unsuccessful.)

&MDY
MMDDYY

Returns the current date. The format makes this variable useful for numerical comparisons.

&MDYY
MMDDCCYY

Returns the current (four-digit year) date.

&RETCODE
numeric

Returns the return code set upon execution of an operating system command. Executes all WebFOCUS commands in the FOCSTACK just as the -RUN command would.

&SETFILE
alphanumeric

Contains the value from the SET FILE command.

&TOD
HH.MM.SS

Returns the current time. When you enter WebFOCUS, this variable is updated to the current system time only when you execute a MODIFY, SCAN, or FSCAN command. To obtain the exact time during any process, use the HHMMSS function.

&YMD
YYMMDD

Returns the current date.

&YYMD
CCYYMMDD

Returns the current (four-digit year) date.



Example: Retrieving the Date Using the System Variable &DATE

The following example incorporates the system variable &DATE into a request. The footing uses the system variable &DATE to insert the current system date at the bottom of the report.

TABLE FILE SALES
SUM UNIT_SOLD
BY PROD_CODE
FOOTING 
"CALCULATED AS OF &DATE"
END


Example: Retrieving the Procedure Name Using the System Variable &FOCFOCEXEC

This example illustrates how to use the system variable &FOCFOCEXEC in a request to display the name of the currently running procedure:

TABLE FILE EMPLOYEE
"REPORT: &FOCFOCEXEC -- EMPLOYEE SALARIES"
PRINT CURR_SAL BY EMP_ID
END

If the request is stored as a procedure called SALPRINT, when executed it produces the following output.

REPORT: SALPRINT -- EMPLOYEE SALARIES
EMP_ID            CURR_SAL
------            --------
071382660       $11,000.00
112847612       $13,200.00
117593129       $18,480.00
119265415        $9,500.00
119329144       $29,700.00
123764317       $26,862.00
126724188       $21,120.00
219984371       $18,480.00
326179357       $21,780.00
451123478       $16,100.00
543729165        $9,000.00
818692173       $27,062.00

&FOCFOCEXEC and &FOCINCLUDE can also be used in -TYPE commands. For example, you have a procedure named EMPNAME that contains the following:

-TYPE &|FOCFOCEXEC is: &FOCFOCEXEC

When EMPNAME is executed, the following output is produced:

&FOCFOCEXEC IS: EMPNAME


Example: Displaying a Date Using the System Variable &YYMD

You can display a date variable containing a 4-digit year without separators. The variables are &YYMD, &MDYY, and &DMYY.

The following example shows a report using &YYMD:

TABLE FILE EMPLOYEE
HEADING
"SALARY REPORT RUN ON DATE &YYMD"
"  "
PRINT DEPARTMENT CURR_SAL
BY LAST_NAME BY FIRST_NAME
END

The resulting output for May 19, 1999 is shown in the following image.



x
Statistical Variables

WebFOCUS posts many statistics concerning overall operations while a procedure executes in the form of statistical variables. As with system variables, WebFOCUS automatically supplies values for these variables on request.



x
Reference: Summary of Statistical Variables

The following table describes the Dialogue Manager statistical variables.

Variable

Description

&ACCEPTS

Indicates the number of transactions accepted. This variable applies only to MODIFY requests.

&BASEIO

Indicates the number of input/output operations performed.

&CHNGD

Indicates the number of segments updated. This variable applies only to MODIFY requests.

&DELTD

Indicates the number of segments deleted. This variable applies only to MODIFY requests.

&DUPLS

Indicates the number of transactions rejected as a result of duplicate values in the data source. This variable applies only to MODIFY requests.

&FOCDISORG

Indicates the percentage of disorganization for a WebFOCUS file. You can use the ? FILE command to display or test this variable, even if the value is less than 30% (the level at which ? FILE displays the amount of disorganization).

&FOCERRNUM

Indicates the last error number, in the format FOCnnnn, displayed after the execution of a procedure. If more than one occurred, &FOCERRNUM holds the number of the most recent error. If no error occurred, &FOCERRNUM has a value of 0. It can also be used to control branching from a procedure to execute an error-handling routine.

&FORMAT

Indicates the number of transactions rejected as a result of a format error. This variable applies only to MODIFY requests.

&INPUT

Indicates the number of segments added to the data source. This variable applies only to MODIFY requests.

&INVALID

Indicates the number of transactions rejected as a result of an invalid condition. This variable applies only to MODIFY requests.

&LINES

Indicates the number of lines printed in last report. This variable applies only to report requests.

&NOMATCH

Indicates the number of transactions rejected as a result of not matching a value in the data source. This variable applies only to MODIFY requests.

&READS

Indicates the number of records read from a non-WebFOCUS file.

&RECORDS

Indicates the number of records retrieved in last report. This variable applies only to report requests.

&REJECTS

Indicates the number of transactions rejected for reasons other than the ones specifically tracked by other statistical variables. This variable applies only to MODIFY requests.

&TRANS

Indicates the number of transactions processed. This variable applies only to MODIFY requests.



Example: Controlling Execution of a Request With the Statistical Variable &LINES

In the following example, the system calculates the value of the statistical variable &LINES. If &LINES is 0, control passes to the TABLE FILE EMPLOYEE request identified by the label ‑RPT2. If the value is not 0, control passes to the label ‑REPTDONE, and processing is terminated.

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY CITY
IF CITY EQ &CITY
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1 TO &CODE2
END
-RUN 
-IF &LINES EQ 0 GOTO RPT2 ELSE GOTO REPTDONE;
-RPT2
TABLE FILE EMPLOYEE
   .
   .
   .
END
-RUN 
-REPTDONE
-EXIT


x
Special Variables

WebFOCUS provides special variables that apply to the cursor, function keys, windows, and other features.





x
Querying the Values of Variables and Parameters

Two Dialogue Manager commands enable you to:

In addition, you can issue two QUERY (?) commands from the WebFOCUS prompt to display the values of:



x
Syntax: How to Display the Value of a Variable

You can query all Dialogue Manager variables (local, global, system, and statistical) from a stored procedure. The syntax is

-? &[&variablename]

where:

&

Issued alone, displays variables of all types.

variablename

Is a complete amper variable or a partial string of up to 12 characters. Only amper variables starting with the specified string are displayed.

The command displays the following message, followed by a list of currently defined amper variables and the values:

CURRENTLY DEFINED & VARIABLES:

Since local variables do not exist outside a procedure, no similar query is available from the WebFOCUS command line.



x
Syntax: How to Store Parameter Value Settings

You can store the current value of a SET parameter in a variable and use the value in a procedure. The syntax is

-? SET parameter &[&]variablename						

where:

parameter

Is any valid WebFOCUS setting that may be queried with the ? SET or ? SET ALL command.

variablename

Is the name of the variable where the value is to be stored.



Example: Storing a Parameter Value Setting

If you enter the following, the value stored in &ABC becomes the value of ASNAMES.

-? SET ASNAMES &ABC
-TYPE &ABC

If you omit &ABC from the command, then a variable called &ASNAMES is created that contains the value of ASNAMES.


Top of page

x
Supplying and Verifying Values for Variables

In this section:

Reference:

When you design a Dialogue Manager procedure with variables, you must decide how the variables in the procedure acquire values at run time. You can use or combine the following techniques.

You can supply variable values directly in procedures, without prompting users for input, using the following methods:

Verifying user input: For values supplied by users, you can also verify input by comparing it against:



x
Reference: Rules for Supplying Variable Values

The following rules apply to values for variables:



Example: Supplying Variable Values in a Procedure

This example illustrates the use of the -DEFAULT and -SET commands to supply values for variables. The end user supplies the value B10 for &CODE1, B20 for &CODE2, and SMITH for &REGIONMGR, as prompted by Dialogue Manager.

The numbers to the left of the example apply to the notes that follow:

1. -DEFAULT &VERB=SUM 
2. -SET &CITY=IF &CODE1 GT 'B09' THEN 'STAMFORD' ELSE 'UNIONDALE'; 
3. -TYPE REGIONAL MANAGER FOR &CITY
    SET PAGE=OFF 
5.     TABLE FILE SALES
       HEADING CENTER
       "MONTHLY REPORT FOR &CITY"
       "PRODUCT CODES FROM &CODE1 TO &CODE2"
       " "
       &VERB UNIT_SOLD AND RETURNS AND COMPUTE
       RATIO/D5.1 = 100 * (RETURNS/UNIT_SOLD);
       BY PROD_CODE
       IF PROD_CODE IS-FROM &CODE1 TO &CODE2
       FOOTING CENTER 
4.     "REGION MANAGER: &REGIONMGR"
       "CALCULATED AS OF &DATE"
       END 
6. -RUN

The procedure executes as follows:

  1. The -DEFAULT command sets the value of &VERB to SUM.
  2. The -SET command supplies the value for &CITY depending on the value the end user entered in the form for &CODE1. Because the end user entered B10 as the value for &CODE1, &CITY becomes STAMFORD.
  3. When the user runs the report, WebFOCUS writes a message that incorporates the value for &CITY:
    REGIONAL MANAGER FOR STAMFORD
  4. The user supplied the value for &REGIONMGR in response to an implicit prompt. WebFOCUS supplies the current data at run time.
  5. The WebFOCUS stack contains the following lines:
    TABLE FILE SALES
    HEADING CENTER
    "MONTHLY REPORT FOR STAMFORD"
    "PRODUCT CODES FROM B10 TO B20"
    " "
    SUM UNIT_SOLD AND RETURNS AND COMPUTE
    RATIO/D5.1 = 100 * (RETURNS/UNIT_SOLD);
    BY PROD_CODE
    IF PROD_CODE IS-FROM B10 TO B20
    FOOTING CENTER
    "REGION MANAGER: SMITH"
    "CALCULATED AS OF 06/11/03"
    END
  6. The -RUN command causes execution of all commands in the stack. The output from the report request is as follows:
        MONTHLY REPORT FOR STAMFORD
       PRODUCT CODES FROM B10 TO B20
     
    PROD_CODE  UNIT_SOLD  RETURNS  RATIO
    ---------  ---------  -------  -----
    B10              103       13   12.6
    B12               69        4    5.8
    B17               49        4    8.2
    B20               40        1    2.5
     
           REGION MANAGER: SMITH
         CALCULATED AS OF 06/11/03


x
Supplying a Default Variable Value

-DEFAULT commands set default values for local or global variables. This technique ensures that a value is passed to a variable so that the user is not prompted for the value.

You can issue multiple -DEFAULT commands for a variable. If the variable is global, these -DEFAULT commands can be issued in separate FOCEXECs. At any point before another method is used to establish a value for the variable, the most recently issued ‑DEFAULT command will be in effect.

However, as soon as a value for the variable is established using any other method (for example, by issuing a ‑SET command, retrieving a value input by the user, or reading a value from a file), subsequent ‑DEFAULT commands issued for that variable are ignored.

Note that -DEFAULTS and -DEFAULTH are synonyms for -DEFAULT.



x
Syntax: How to Supply a Default Value
-DEFAULT[S|H] &[&]name=value [...] [;]

where:

name

Is the name of the variable.

value

Is the default value assigned to the variable.

;

Is an optional punctuation character.

Note: -DEFAULTS and -DEFAULTH are synonyms for -DEFAULT.



Example: Supplying a Default Value

In the following example, -DEFAULT sets the default value for &PLANT to Boston (BOS):

-DEFAULT &PLANT=BOS
TABLE FILE CENTHR
     .
     .
     .


x
Supplying Variable Values in an Expression

You can assign a value to a variable by computing the value in an expression or assigning a literal value to a variable with the -SET command. You can also use the IN FILE phrase to test whether a character value exists in a file and populate a variable with the result. The value of the variable is set to 1 if the test value exists in the file and 0 (zero) if it does not.

You can use this technique to supply dates to Dialogue Manager as variable values. A date supplied to Dialogue Manager in a variable cannot be more than 20 characters long, including spaces. Dialogue Manager variables only accept full-format dates (that is, MDY or MDYY, in any order).

If you are working with cross-century dates that do not include a four-digit year, you can use the SET parameters DEFCENT and YRTHRESH variables to identify the century.

If you want to set a variable value to a number, the only supported characters you can use are numeric digits, a leading minus sign, and a period to represent following decimal places. These are the only valid characters that Dialogue Manager supports in a number, regardless of EDIT options or the value of CDN.



x
Syntax: How to Assign a Value in an Expression
-SET &[&]name= {expression|value};
-SET &[&]var3= &var1 IN FILE filename1 [OR &var2 IN FILE filename2 ...];

where:

name

Is the name of the variable.

expression

Is a valid expression. Expressions can occupy several lines, so you must end the command with a semicolon.

value

Is a literal value, or arithmetic or logical expression assigned to the variable. If the literal value contains commas or embedded blanks, you must enclose the value in single quotation marks.

&[&]var3

Is a variable that is populated with the value 1 if the result of the expression on the right side of the equal sign is true, or with the value 0 if the result is false.

&var1

Is the variable that contains the value to be searched for in filename1.

&var2

Is the variable that contains the value to be searched for in filename2.



x
Reference: Usage Notes for IN FILE
  • The result of the IN FILE phrase is an alphanumeric value (1 or 0) that can be used in a logical expression connected with AND and OR operators within same –SET command. This value cannot be used as an argument in an alphanumeric operation, such as concatenation within the same -SET command.
  • In order for IN FILE to return the value 1, the values in the file and the search string must match exactly, starting with the leftmost byte in the file.
  • The file can be in any order and have duplicate values. The search stops when either the first match is found or the end of the file is reached. If the file is allocated but does not exist, the value 0 is returned. If the file is not allocated, a FOC351 message displays.
  • The length of the variable used in the IN FILE phrase determines the number of bytes from the beginning of each record in the file used for comparison. Only an exact match on that number of bytes will return a 1. Trailing blanks in the variable will require the same number of trailing blanks in the file in order to match. For example, the following will match only the value 'ABC ' (ABC with three trailing blanks):
    -SET &VAR1 = 'ABC   ';
    -SET &VAR2 = &VAR1 IN FILE FILE1;


x
Syntax: How to Specify Precision for Dialogue Manager Calculations

The DMPRECISION setting enables Dialogue Manager -SET commands to calculate accurate numeric variable values without using the FTOA function.

Without this setting, results of numeric calculations are returned as integer numbers, although the calculations themselves employ double-precision arithmetic. To return a number with decimal precision without this setting, you have to enter the calculation as input into subroutine FTOA, where you can specify the number of decimal places returned.

The SET DMPRECISION command gives users the option of either accepting the default truncation of the decimal portion of output from arithmetic calculations, or specifying up to nine decimal places for rounding.

SET DMPRECISION = {OFF|n}

where:

OFF

Specifies truncation without rounding after the decimal point. OFF is the default value.

n

Is a positive number from 0-9, indicating the point of rounding. Note that n=0 results in a rounded integer value.

  • When using SET DMPRECISION, you must include -RUN after the SET DMPRECISION command to ensure that it is set prior to any numeric -SET commands.
  • As the actual conversion to double precision follows the rules for the operating system, the values may vary from platform to platform.


Example: Setting Precision for Dialogue Manager Calculations

The following table below shows the result of dividing 20 by 3 with varying DMPRECISION (DMP) settings:

SET DMPRECISION =

Result

OFF

6

0

7

1

6.7

2

6.67

9

6.666666667



Example: Setting a Variable Value in an Expression

In the following example, -SET assigns the value 14Z or 14B to the variable &STORECODE, as determined by the logical IF expression. The value of &CODE is supplied by the user.

-SET &STORECODE = IF &CODE GT C2 THEN '14Z' ELSE '14B';
   TABLE FILE SALES
   SUM UNIT_SOLD AND RETURNS
   BY PROD_CODE
   IF PROD_CODE GE &CODE
   BY STORE_CODE
   IF STORE_CODE IS &STORECODE
   END


Example: Setting a Literal Value

The use of single quotation marks around a literal is optional unless the literal contains embedded blanks, commas, or equal signs. In these cases, you must include them as illustrated below:

-SET &NAME='JOHN DOE';


Example: Setting the Difference Between Two Dates

This example supplies dates to Dialogue Manager as variables. The variable &DELAY is set to the difference in days between &LATER and &NOW.

-SET &NOW = 'JUN 30 2002';
-SET &LATER = '2002 25 AUG';
-SET &DELAY = &LATER - &NOW;
-TYPE &DELAY


Example: Testing Whether a Variable Value Is in a File

The following FOCEXEC creates an alphanumeric HOLD file called COUNTRY1 with the names of countries from the CAR file. It then sets the variable &C equal to FRANCE. The IN FILE phrase returns the value 1 to &IN1 if FRANCE is in the HOLD file and 0 if it is not:

TABLE FILE CAR                                   
PRINT COUNTRY                                    
ON TABLE HOLD AS COUNTRY1 FORMAT ALPHA           
END                                              
-RUN                                             
-SET &C = 'FRANCE';                              
-SET &IN1 = &C IN FILE COUNTRY1;                
-TYPE THE VALUE IS &IN1                     

The output shows that FRANCE is in the file COUNTRY1:

THE VALUE IS 1 


Example: Initializing a Variable to a Long String

To set the value of a variable with -SET, you need to specify a character string on the right side of the SET command. Since the character string cannot span multiple lines, if necessary, you can concatenate shorter strings or variables to compose the long string.

The following procedure creates a variable named &LONG that contains a long string:

-SET &LONG = 'THIS IS A LONG AMPER VARIABLE. NOTE THAT IN ORDER '
-  |'TO SET ITS VALUE USING -SET, YOU MUST CONCATENATE SHORTER STRINGS, '
-  |'EACH OF WHICH MUST FIT ON ONE LINE.';
-TYPE &LONG
END

The output is:

THIS IS A LONG AMPER VARIABLE.NOTE THAT IN ORDER TO SET ITS VALUE USING 
-SET, YOU MUST CONCATENATE SHORTER STRINGS, EACH OF WHICH MUST FIT ON ONE 
LINE.


x
Reading Variable Values From and Writing Variable Values to an External File

You can read variable values from an external file, or write variable values to an external file with the -READ and -WRITE commands.

The external file can be a fixed-format file (in which the data is in fixed columns) or a free-format file (in which the data is comma delimited).

You can also read a file using the -READFILE command. The -READFILE command reads a file by first reading its Master File and creating Dialogue Manager amper variables based on the ACTUAL formats for each field in the Master File. It then reads the file and, if necessary, converts the fields from numeric values to alphanumeric strings before returning them to the created variables. Display options in the USAGE formats are not propagated to the variables. The names of the amper variables are the field names prefixed with an ampersand (&).



x
Syntax: How to Retrieve a Variable Value From an External File
-READ ddname[,] [NOCLOSE] &name[.format.][,] ...

where:

ddname

Is the logical name of the file as defined to WebFOCUS using ALLOCATE or DYNAM ALLOCATE.

A space after the ddname denotes a fixed format file while a comma denotes a comma-delimited file.

NOCLOSE

Indicates that the file should be kept open even if a -RUN is encountered. The file is closed upon completion of the procedure or when a -CLOSE or subsequent -WRITE command is encountered.

name

Is the variable name. You may specify more than one variable. Using commas to separate variables is optional.

If the list of variables is longer than one line, end the first line with a comma and begin the next line with a dash followed by a blank (- ) for comma-delimited files or a dash followed by a comma followed by a blank (-, ) for fixed format files. For example:

Comma-delimited files

-READ EXTFILE, &CITY,&CODE1,
- &CODE2

Fixed format files

-READ EXTFILE &CITY.A8. &CODE1.A3.,
-, &CODE2.A3
format

Is the format of the variable. It may be Alphanumeric (A) or Numeric (I). Note that format must be delimited by periods. The format is ignored for comma-delimited files.

Note: -SET provides an alternate method for defining the length of a variable using the corresponding number of characters enclosed in single quotation marks ('). For example, the following command defines the length of &CITY as 8:

-SET &CITY='        ';


Example: Reading a Value From an External File

Assume that EXTFILE is a fixed-format file containing the following data:

STAMFORDB10B20

To detect the end of a file, the following code tests the system variable &IORETURN. When no records remain to be read, a value equal to zero is not found.

-READ EXTFILE &CITY.A8. &CODE1.A3. &CODE2.A3.
-IF &IORETURN NE 0 GOTO RESUME;
    TABLE FILE SALES
    SUM UNIT_SOLD
    BY CITY
    IF CITY IS &CITY
    BY PROD_CODE
    IF PROD_CODE IS-FROM &CODE1 TO &CODE2
    END
-RESUME
 .
 .
 .


x
Syntax: How to Write a Variable Value to an External File
-WRITE ddname [NOCLOSE] text						

where:

ddname

Is the logical name of the file as defined to WebFOCUS using ALLOCATE or DYNAM ALLOCATE.

NOCLOSE

Indicates that the file should be kept open even if a -RUN is encountered. The file is closed upon completion of the procedure or when a -CLOSE or subsequent -READ command is encountered.

text

Is any combination of variables and text. To write more than one line, end the first line with a comma (,) and begin the next line with a hyphen followed by a space (-).

-WRITE opens the file to receiving the text and closes it upon exit from the procedure. When the file is reopened for writing, the new material overwrites the old. To reopen to add new records instead of overwriting existing ones, use the attribute DISP MOD when you define the file to the operating system.



Example: Writing to a File

The following example reopens the file PASS to add new text:

DYNAM ALLOC DD PASS DA USER1.PASS.DATA MOD
-WRITE PASS &DIV &RED &TEST RESULT IS,
- &RECORDS AT END OF RUN


x
Syntax: How to Read Master File Fields Into Dialogue Manager Variables
-READFILE [app/]mastername

where:

app

Is the application directory in which the file resides.

mastername

Is the name of the Master File to be read.



x
Reference: Usage Notes for -READFILE
  • A -RUN command does not close the file. You must issue a -CLOSE command to close the file. You must be careful not to delete, change, or re-allocate the file before closing it.
  • If multiple fields have the same field name, only one variable is created, and it contains the value of the last field in the Master File.
  • -READFILE does not work if the Master File contains DBA restrictions. The following message is generated:
    (FOC339) DIALOGUE MANAGER -READ FAILED: CHECK FILEDEF OR ALLOCATION FOR: -READFILE filename								
  • -READFILE is not supported with text fields. The following message is generated:
    (FOC702) THE OPTION SPECIFIED IS NOT AVAILABLE WITH TEXT FIELDS: fieldname


Example: Reading Fields From a Data Source Into Dialogue Manager Variables Using -READFILE

The following request creates a binary HOLD file, then uses -READFILE to read the first record from the HOLD file and type the values that were retrieved into Dialogue Manager variables. Note that the names of the variables are the field names prefixed with an ampersand:

TABLE FILE EMPLOYEE                           
PRINT LAST_NAME FIRST_NAME DEPARTMENT CURR_SAL
BY EMP_ID                                     
ON TABLE HOLD AS READF1 FORMAT BINARY         
END                                           
-RUN                                          
-READFILE READF1                              
-TYPE LAST_NAME  IS &LAST_NAME                
-TYPE FIRST_NAME IS &FIRST_NAME               
-TYPE DEPARTMENT IS &DEPARTMENT               
-TYPE CURR_SAL   IS &CURR_SAL                 
-TYPE EMP_ID     IS &EMP_ID

The output is:

>   NUMBER OF RECORDS IN TABLE=       12  LINES=     12 
                                                        
 HOLDING BINARY FILE...                                             
LAST_NAME  IS STEVENS                                   
FIRST_NAME IS ALFRED                                    
DEPARTMENT IS PRODUCTION                                
CURR_SAL   IS     11000.00                              
EMP_ID     IS 071382660


x
Syntax: How to Close an External File

The -CLOSE command closes an external file opened with the -READ or -WRITE command. The NOCLOSE option keeps a file open even when -RUN is encountered.

-CLOSE {ddname|*}

where:

ddname

Is the ddname of the open file described to WebFOCUS using an allocation.

*

Closes all -READ and -WRITE files that are currently open.



x
Supplying Variable Values on the Command Line

When a user knows the values required by a procedure, some or all of the values can be typed on the command line using the EXEC command following the name of the procedure. This saves time since WebFOCUS now has values to pass to each local or global variable so the user is not prompted to supply them.



x
Syntax: How to Supply a Variable Value on the Command Line
EX[EC] procedure [[&&][variable=]value, ...]

where:

procedure

Is the name of the procedure that contains the name and value values.

variable

Is the name of the variable for which you are supplying a value. Omit for a positional variable.

For a local variable, do not include the ampersand in the variable name.

For a global amper variable, you must supply the double ampersand in the variable name:

EX SLRPT &&GLOBAL=value, CITY = STAMFORD, CODE1=B10, CODE2=B20
value

Is the value you are giving to the variable.

Name and value pairs must be separated by commas.

When the list of values to be supplied exceeds the width of the display, insert a comma as the last character on the line and enter the balance of the list on the following lines, as shown:

EX SLRPT AREA=S, CITY = STAMFORD, VERB=COUNT, FIELDS = UNIT_SOLD, CODE1=B10, CODE2=B20


x
Reference: Rules for Using Named and Positional Variables With EXEC

You can mix named and positional variables freely in the EXEC command. Positional variables are unnamed values passed to a procedure when it is invoked.

Follow these rules:

  • Names must be associated with values for named variables.

    It is not necessary to enter the name=value pairs in the order encountered in the procedure.

  • Values for positional variables must be supplied in the order that those variables are numbered within the procedure.

    If the variable is positional (it is a numbered variable), you do not need to specify the variable name in the EXEC command. WebFOCUS matches the EXEC values to the positional variables as they are encountered in the procedure.



Example: Supplying Values on the Command Line

Consider the following procedure named SLRPT:

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY PROD_CODE
IF PROD_CODE IS-FROM &CODE1 TO &CODE2
BY CITY
IF CITY EQ &CITY
END

You can supply values for the variables as parameters using the EX command as follows:

EX SLRPT CITY=STAMFORD, CODE1=B10, CODE2=B20


Example: Using Positional Variables

Consider the following example:

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &1"
SUM UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY PROD_CODE
IF PROD_CODE IS-FROM &2 TO &3
BY CITY
IF CITY EQ &1
END

The EX command that calls the procedure is as follows:

EX SLRPT STAMFORD, B10, B20

This command substitutes STAMFORD for the first positional variable, B10 for the second, and B20 for the third.



Example: Mixing Named and Positional Variables

The report request SLRPT includes named and positional variables:

TABLE FILE SALES
HEADING CENTER
"MONTHLY REPORT FOR &CITY"
&VERB UNIT_SOLD AND RETURNS AND COMPUTE
RATIO/D5.2 = 100 * (RETURNS/UNIT_SOLD);
BY PROD_CODE
IF PROD_CODE IS-FROM &1 TO &2
BY CITY
IF CITY EQ &CITY
END

The following EX command executes SLRPT and populates the named and positional variables:

EX SLRPT CITY=STAMFORD, B10, B20, VERB=COUNT

&CITY is a named variable whose value is STAMFORD.

&1 is a positional variable whose value is B10.

&2 is a positional variable whose value is B20.

&VERB is a named variable whose value is COUNT.



x
Verifying User-Supplied Values Against a Set of Format Specifications

You can specify variables with format conditions against which entered values can be compared. If the entered values do not have the specified format, WebFOCUS prints error messages and prompts the user again for the values.



x
Reference: Format Specifications for Variables

Alphanumeric formats are described by the letter A followed by the number of characters. The number of characters can be from 1 to 3968.

Numeric formats are described by the letter I, followed by the number of digits to be entered. The number of digits can be from 1 to 10 (value must be less than 231-1), and the value supplied for the number can contain a decimal point.

The description of the format must be enclosed by periods.

If you test field names against input variable values, specify formats of the input variables. If you do not, and the supplied value exceeds the format specification from the Master File, the procedure is ended and error messages are displayed. To continue, the procedure must be executed again. However, if you do include the format, and the supplied value exceeds the format, Dialogue Manager rejects the value and the user is prompted again.

Note: WebFOCUS internally stores all Dialogue Manager variables as alphanumeric codes. To perform arithmetic operations, Dialogue Manager converts the variable value to double-precision floating point decimal and then converts the result back to alphanumeric codes, dropping the decimal places. For this reason, do not perform tests that look for the decimal places in the numeric codes.



Example: Using a Format Specification to Verify User Input

Consider the following format specification:

&STORECODE.A3.

No special message is sent to the screen detailing the specified format. However, if in the above example the user enters more than three alphanumeric characters, the value is rejected, the error message FOC291 is displayed and the user is prompted again.


Top of page

x
Manipulating and Testing Variables

In this section:

You can use a variety of techniques to manipulate and test Dialogue Manager variables.



x
Testing Variables for Length, Type, and Existence

To ensure that a supplied value is valid and being used properly in a procedure, you can test it for presence, type, and length. For example, you would not want to perform a numerical computation on a variable for which alphanumeric data has been supplied.



x
Syntax: How to Screen a Variable Value for Length and TYPE
-IF &name{.LENGTH|.TYPE} rest_of_expression GOTO label...;

where:

&name

Is a user-supplied variable.

.LENGTH

Tests for the length of a value. If a value is not present, a zero (0) is passed to the expression. Otherwise, the number of characters in the value is passed.

.TYPE

Tests for the type of a value. The letter N (numeric) is passed to the expression if the value can be interpreted as a number up to 231-1 and stored in four bytes as a floating point format. In Dialogue Manager, the result of an arithmetic operation with numeric fields is truncated to an integer after the whole result of an expression is calculated. If the value could not be interpreted as numeric, the letter A (alphanumeric) is passed to the expression. If the value is not defined, the letter U is passed to the expression.

rest_of_expression

Is the remainder of an expression that uses &name with the specified suffix.

GOTO label

Specifies a label to branch to.



Example: Testing for Variable Length

If the length of &OPTION is more than one character, control passes to the label -FORMAT, which informs the client application that only a single character is allowed.

-IF &OPTION.LENGTH GT 1 GOTO FORMAT ELSE
-GOTO PRODSALES;
      .
      .
      .
-PRODSALES
    TABLE FILE SALES
      .
      .
      .
    END
-EXIT
-FORMAT
-TYPE ONLY A SINGLE CHARACTER IS ALLOWED.


Example: Storing the Length of a Variable

The following example sets the variable &WORDLEN to the length of the string contained in the variable &WORD.

&WORD.ENTER WORD.
-SET &WORDLEN = &WORD.LENGTH;

You can use this technique when you want to use one variable to populate another.



Example: Testing for Variable Type

If &OPTION is not alphanumeric, control passes to the label -NOALPHA, which informs the client application that only alphanumeric characters are allowed.

-IF &OPTION.TYPE NE A GOTO NOALPHA ELSE
- GOTO PRODSALES;
       .
       .
       .
-PRODSALES
    TABLE FILE SALES
       .
       .
       .
    END
-EXIT
-NOALPHA
-TYPE ENTER A LETTER ONLY.


x
Syntax: How to Test for the Presence of a Variable Value
-IF &name.EXIST GOTO label...;

where:

&name

Is a user-supplied variable.

.EXIST

Tests for the presence of a value. If a value is not present, a zero (0) is passed to the expression. Otherwise, a non-zero value is passed.

GOTO label

Specifies a label to branch to.



Example: Testing for the Presence of a Variable

If no value is supplied, &OPTION.EXIST is equal to zero and control is passed to the label ‑CANTRUN. The procedure sends a message to the client application and then exits. If a value is supplied, control passes to the label ‑PRODSALES.

-IF &OPTION.EXIST GOTO PRODSALES ELSE GOTO CANTRUN;
      .
      .
      .
-PRODSALES
    TABLE FILE SALES
      .
      .
      .
    END
-EXIT
-CANTRUN
-TYPE TOTAL REPORT CAN'T BE RUN WITHOUT AN OPTION.
-EXIT


x
Replacing a Variable Immediately

The .EVAL operator enables you to replace a variable with its value immediately, making it possible to change a procedure dynamically. The .EVAL operator is useful in modifying code at run time.



x
Syntax: How to Replace a Variable Immediately
[&]&variable.EVAL

where:

variable

Is a local or global variable.

When the command procedure is executed, the expression is replaced with the value of the specified variable before any other action is performed. The command that contains this value is then re-evaluated.

Without the .EVAL operator, a variable cannot be used in place of some commands.



Example: Replacing a Variable Immediately

The following example illustrates how to use the .EVAL operator in a record selection expression. The numbers to the left apply to the notes that follow the procedure:

1. -SET &R='IF SALARY GT 100000'; 
2. -IF &Y EQ 'YES' THEN GOTO START; 
3. -SET &R = '-*';
   -START 
4.   TABLE FILE CENTHR
     SUM SALARY 
     BY PLANT 
5.   &R.EVAL
     END

The procedure executes as follows:

  1. The procedure sets the value of &R to 'IF SALARY GT 100000'.
  2. If &Y is YES, the procedure branches to the START label, bypassing the second -SET command.
  3. If &Y is NO, the procedure continues to the second -SET command, which sets &R to '-*', which is a comment.

    The report request is stacked.

  4. The procedure evaluates the value of &R. If the end user wanted a record selection test, the value of &R is 'IF SALARY GT 100000' and this line is stacked.
  5. If the end user does not want a record selection test, the value of &R is '-*' and this line is ignored.


Example: Using .EVAL to Interpret a Variable

Without .EVAL, Dialogue Manager interprets a variable only once. Therefore, in the following example,

-SET &A='-TYPE';
&A HELLO

Dialogue Manager does not recognize that &A is the -TYPE command so it does not display the word HELLO and generates the error message:

UNKNOWN WebFOCUS COMMAND -TYPE

Appending the .EVAL operator to the &A variable enables Dialogue Manager to interpret the variable correctly. The code

-SET &A='-TYPE';
&A.EVAL HELLO

produces the following output:

HELLO
>>


x
Concatenating Variables

You can append a variable to a character string or combine two or more variables and/or literals. See the Creating Reports With WebFOCUS Language With WebFOCUS Language manual for complete information on concatenation.

Note: When using variables, separate each variable from the concatenation symbol (||) with a space.



x
Syntax: How to Concatenate Variables
-SET &name3 = &name1 || &name2;

where:

&name3

Is the name of the concatenated variable.

&name1 || &name2

Are the variables, separated by a space and the concatenation symbol.

Note: The example shown uses strong concatenation, indicated by the || symbol. Strong concatenation moves any trailing blanks from &name1 to the end of the result. Conversely, weak concatenation, indicated by the symbol |, preserves any trailing blanks in &name1.



x
Creating an Indexed Variable

You can append the value of one variable to the value of another variable, creating an indexed variable. This feature applies to both local and global variables.

If the indexed value is numeric, the effect is similar to that of an array in traditional computer programming languages. For example, if the value of index &K varies from 1 to 10, the variable &AMOUNT.&K refers to one of ten variables, from &AMOUNT1 to &AMOUNT10.

A numeric index can be used as a counter; it can be set, incremented, and tested in a procedure.



x
Syntax: How to Create an Indexed Variable
-SET &name.&index[.&index...] = expression;

where:

&name

Is a variable.

.&index

Is a numeric or alphanumeric variable whose value is appended to &name. The period is required.

When more than one index is used, all index values are concatenated and the string appends to the name of the variable.

For example, &V.&I.&J.&K is equivalent to &V1120 when &I=1, &J=12, and &K=0.

expression

Is a valid expression. For information on the kinds of expressions you can write, see the Creating Reports With WebFOCUS Language manual.



Example: Using an Indexed Variable in a Loop

An indexed variable can be used in a loop. The following example creates the equivalent of a DO loop used in traditional programming languages:

-SET &N = 0;
-LOOP
-SET &N = &N+1;
-IF &N GT 12 GOTO OUT;
-SET &MONTH.&N=&N;
-TYPE &MONTH.&N 
-GOTO LOOP
-OUT

In this example, &MONTH is the indexed variable and &N is the index. The value of the index is supplied through the command -SET. The first -SET initializes the index to 0, and the second -SET increments the index each time the procedure goes through the loop.

If the value of an index is not defined prior to reference, a blank value is assumed. As a result, the name and value of the indexed variable do not change.

Indexed variables are included in the system limit of 1024, which includes variables reserved by WebFOCUS.



x
Creating a Standard Quote-Delimited String

Character strings must be enclosed in single quotation marks to be handled by most database engines. In addition, embedded single quotation marks are indicated by two contiguous single quotation marks. WebFOCUS and iWay require quotes around variables containing delimiters, which include spaces and commas.

The QUOTEDSTRING suffix on a Dialogue Manager variable applies the following two conversions to the contents of the variable:

Dialogue Manager commands differ in their ability to handle character strings that are not enclosed in single quotation marks and contain embedded blanks. An explicit or implied ‑PROMPT command can read such a string. The entire input string is then enclosed in single quotation marks when operated on by .QUOTEDSTRING.

Note: When using the -SET command to reference a character string, ensure the character string is enclosed in single quotes to prevent errors.



x
Syntax: How to Create a Standard Quote-Delimited Character String
&var.QUOTEDSTRING

where:

&var

Is a Dialogue Manager variable.



Example: Creating a Standard Quote-Delimited Character String

The following example shows the results of the QUOTEDSTRING suffix on input strings.

-SET &A = ABC;
-SET &B = 'ABC';
-SET &C = O'BRIEN;
-SET &D = 'O'BRIEN';
-SET &E = 'O''BRIEN';
-SET &F = O''BRIEN;
-SET &G = OBRIEN';
-TYPE  ORIGINAL = &A QUOTED = &A.QUOTEDSTRING
-TYPE  ORIGINAL = &B QUOTED = &B.QUOTEDSTRING
-TYPE  ORIGINAL = &C QUOTED = &C.QUOTEDSTRING
-TYPE  ORIGINAL = &D QUOTED = &D.QUOTEDSTRING
-TYPE  ORIGINAL = &E QUOTED = &E.QUOTEDSTRING
-TYPE  ORIGINAL = &F QUOTED = &F.QUOTEDSTRING
-TYPE  ORIGINAL = &G QUOTED = &G.QUOTEDSTRING

The output is:

ORIGINAL = ABC        QUOTED = 'ABC'
ORIGINAL = ABC        QUOTED = 'ABC'
ORIGINAL = O'BRIEN    QUOTED = 'O''BRIEN'
ORIGINAL = O'BRIEN    QUOTED = 'O''BRIEN'
ORIGINAL = O'BRIEN    QUOTED = 'O''BRIEN'
ORIGINAL = O''BRIEN   QUOTED = 'O''''BRIEN'
ORIGINAL = OBRIEN'    QUOTED = 'OBRIEN'''
ORIGINAL = ABC        QUOTED = 'ABC'
ORIGINAL = ABC        QUOTED = 'ABC'
ORIGINAL = O'BRIEN    QUOTED = 'O''BRIEN'
ORIGINAL = O'BRIEN    QUOTED = 'O''BRIEN'
ORIGINAL = O'BRIEN    QUOTED = 'O''BRIEN'
ORIGINAL = O''BRIEN   QUOTED = 'O''''BRIEN'
ORIGINAL = OBRIEN'    QUOTED = 'OBRIEN''' 

Note: The -SET command will remove single quotes around a string. Notice in the example above that the result of -SET &B = 'ABC' was changed to ORIGINAL = ABC (as shown in the output), prior to the QUOTEDSTRING conversion.



x
Reference: Usage Notes for Quote-Delimited Character Strings
  • An unmatched single quotation mark at the beginning of a character string is treated as invalid input and generates the following message:
    (FOC257) MISSING QUOTE MARKS:  value;


x
Performing a Calculation on a Variable

You can use -SET to define a value for a substituted variable based on the results of a logical or arithmetic expression or a combination.



x
Syntax: How to Perform a Calculation on a Variable
-SET &name = expression;

where:

&name

Is a user-supplied variable that has its value assigned with the expression.

expression

Is an expression following the rules outlined in the Creating Reports With WebFOCUS Language manual, but with limitations as defined in this topic. The semicolon after the expression is required to terminate the -SET command.



x
Extracting Characters From a Variable Value With the EDIT Function

You can use the mask option of the EDIT function with amper variables. You can insert characters into an alphanumeric value, or extract certain characters from the value.



x
Removing Trailing Blanks From Variables With the TRUNCATE Function

The Dialogue Manager TRUNCATE function removes trailing blanks from Dialogue Manager amper variables and adjusts the length accordingly.

The Dialogue Manager TRUNCATE function has only one argument, the string or variable to be truncated. If you attempt to use the Dialogue Manager TRUNCATE function with more than one argument, the following error message is generated:

(FOC03665) Error loading external function 'TRUNCATE'

This function can only be used in Dialogue Manager commands that support function calls, such as -SET and -IF commands. It cannot be used in -TYPE commands or in arguments passed to stored procedures.

Note: A user-written function of the same name can exist without conflict.



x
Syntax: How to Remove Trailing Blanks From Variables
-SET &var2 = TRUNCATE(&var1);

where:

&var2

Is the Dialogue Manager variable to which the truncated string is returned. The length of this variable is the length of the original string or variable minus the trailing blanks. If the original string consisted of only blanks, a single blank, with a length of one is returned.

&var1

Is a Dialogue Manager variable or a literal string enclosed in single quotation marks. System variables and statistical variables are allowed, as well as user-created local and global variables.



Example: Removing Trailing Blanks

The following example shows the result of truncating trailing blanks:

-SET &LONG = 'ABC   ' ;
-SET &RESULT =  TRUNCATE(&LONG);
-SET &LL = &LONG.LENGTH;
-SET &RL = &RESULT.LENGTH;
-TYPE LONG   =  &LONG  LENGTH =  &LL
-TYPE RESULT =  &RESULT LENGTH =  &RL

The output is:

LONG   =  ABC     LENGTH =  06
RESULT =  ABC LENGTH =  03

The following example shows the result of truncating a string that consists of all blanks:

-SET &LONG = '      ' ;
-SET &RESULT =  TRUNCATE(&LONG);
-SET &LL = &LONG.LENGTH;
-SET &RL = &RESULT.LENGTH;
-TYPE LONG   =  &LONG  LENGTH =  &LL
-TYPE RESULT =  &RESULT LENGTH =  &RL

The output is:

LONG   =          LENGTH =  06
RESULT =    LENGTH =  01

The following example uses the TRUNCATE function as an argument for EDIT:

-SET &LONG = 'ABC   ' ;
-SET &RESULT =  EDIT(TRUNCATE(&LONG)|'Z','9999');
-SET &LL = &LONG.LENGTH;
-SET &RL = &RESULT.LENGTH;
-TYPE LONG   =  &LONG  LENGTH =  &LL
-TYPE RESULT =  &RESULT LENGTH =  &RL

The output is:

LONG   =  ABC     LENGTH =  06
RESULT =  ABCZ LENGTH =  04


x
Calling a Function

Any function name encountered in a Dialogue Manager expression that is not recognized as a system standard name or WebFOCUS function is assumed to be a function. These functions are externally programmed by users and stored in a library that is available at the time referenced. One or more arguments are passed to the user program, which performs an operation or calculation and returns a single value or character string.

Dialogue Manager variables can receive the values from functions through the -SET command.

Note:



x
Syntax: How to Set a Variable Value Based on the Result From a Function
-SET &name = routine(argument,...,'format');

where:

name

Is the name of the variable in which the result is stored.

routine

Is the name of the function.

argument

Represents the arguments that must be passed to the function. Numeric arguments are converted to double-precision (D) format.

format

Is the predefined format of the result. This is used to convert numeric results back to character representation. It must be enclosed in single quotation marks.



x
Using Variables to Alter Commands

A variable can refer to a WebFOCUS command or to a particular field. Therefore, the command structure of a procedure can be determined by the value of the variable.



Example: Using a Variable to Control What the TABLE Command Prints

In this example, the variable &FIELD determines the field to print in the TABLE request.

In the file named SALES, the variable &FIELD can display the values RETURNS, DAMAGED, or UNIT_SOLD.

TABLE FILE SALES
 .
 .
 .
PRINT &FIELD
BY PROD_CODE
 .
 .
 .

Top of page

x
Using Numeric Amper Variables in Functions

In this section:

WebFOCUS stores all amper variables as strings in alphanumeric format whether they contain alphanumeric or numeric data or a mixture of the two. There are only two data types available to amper variables: alphanumeric and numeric.



x
Determining Amper Variable Data Type

Data typing for amper variables is determined by the data content only. As a result, using quotation marks around a numeric value in a -SET command has no effect on the data type of the amper variable.

For example, the following request stores numeric data in variables &A, &B, and &C:

-SET &A=12345;
-SET &B='12345';
-SET &C=123.45
-TYPE &A &B &C
-TYPE &A.TYPE &B.TYPE &C.TYPE

The output shows that &A, &B, and &C all have the numeric data type:

12345 12345 123.45
N  N  N


x
Manipulating Amper Variables

When an amper variable is displayed, substituted, concatenated, or appended, there is no transformation of the value contained in the amper variable.

Substitution

-SET &C=123.45
IF RETAIL_COST EQ &C  

becomes

IF RETAIL_COST EQ 123.45

Also, consider the following:

-SET &D= &C;
-TYPE &D &D.TYPE

The output shows that &D has the same value as &C and is also numeric:

123.45  N

Concatenation

The amper variable &F is created by concatenating &A and &C:

-SET &F =  &A | &C;
-TYPE &F &F.TYPE

The output shows that the value of &F is the value of &A followed by the value of &C, and that the type is numeric:

12345123.45  N

The following example creates the amper variable &E by embedding an ampersand in the string. The ampersand is not recognized as the start of a variable name and is treated as an alphanumeric symbol in a string:

-SET &E = 1234&C;
-TYPE &E &E.TYPE

The output shows that the variable is of type alphanumeric, not numeric. It is not the concatenation of the string '1234' with the variable &C:

1234&C  A

This same behavior can be produced with concatenation:

-SET &G = AT&|T;
-TYPE &G &G.TYPE

The output is:

AT&T  A


x
Using an Amper Variable in an Expression

When an amper variable is used in an expression, conversion may be required in order to process the expression. The amper variable used in the expression is generally seen as a literal, and its value is substituted in before the expression is processed. Under these circumstances, data conversion necessary to process the expression is performed. Numerics contained in amper variables are seen as integers. If the expression can be evaluated as integer, it will be.

In the following example, &C is set to 123.55. Then an expression creates &D by adding 100 to &C :

-SET &C=123.55;
-SET &D=&C + 100;
-TYPE &D &D.TYPE

The output shows that &D is numeric and its value is 123.55+100 truncated to the integer 223 because integer arithmetic is used:

223  N

The following expression requires conversion to double precision, as the numeric literal (100.49) in the expression is not an integer:

-SET &C=123.55;
-SET &D=&C + 100.49;
-TYPE &D &D.TYPE

The output shows that while the arithmetic was done by converting the value of &C to double precision, the result is truncated before being returned to &D:

224  N

If you want the result to retain the decimal places, you can set the DMPRECISION parameter to the number of decimal places you want returned to the resulting amper variable.

For example:

SET DMPRECISION=2
-RUN
-SET &C=123.55;
-SET &D=&C + 100.49;

Now the result retains the decimal places:

224.04 N


x
Using Amper Variables as Subroutine Parameters

How you treat numeric amper variables when passing them to a subroutine depends on the data type of the subroutine parameter.



x
Using a Numeric Amper Variable as a Numeric Subroutine Parameter

When using a numeric amper variable as a numeric parameter in a subroutine call, the amper variable is treated as a field. Since as a field, it has no specified type in either the Master File or the FOCEXEC, it takes the default data type of double precision.

Note that when the result is returned to an output variable, its type is determined by its content. If it has only numbers and a decimal point, it is numeric. If it contains other symbols, it is alphanumeric.

For example, the FTOA subroutine converts a double or single precision number (D or F) to an alphanumeric string with the format specified within the parentheses of the second parameter:

FTOA (number_to_convert, '(format)', 'alpha_output_format' )

The following example sets &C to 123.55 and passes it to the FTOA subroutine to be converted to an alphanumeric string with a dollar sign:

-SET &C=123.55;
-SET &G=FTOA(&C,'(D7.2M)','A11');  
-TYPE &G &G.TYPE

The output shows that the string $123.55 has been returned to &G. Since it has a symbol other than numeric digits and a decimal point, its type is alphanumeric:

$123.55    A

In the following example, the format returned does not specify a dollar sign:

-SET &A=12345;                       
-SET  &G=FTOA(&A/100,'(D7.2)','A11');
-TYPE &G &G.TYPE                     

Since the returned string contains only numeric digits and a decimal point, its type is numeric:

123.45    N

Note that if the number had another digit, it would be returned with a comma, and its type would be alphanumeric:

-SET &A=123456;                       
-SET  &G=FTOA(&A/100,'(D7.2)','A11');
-TYPE &G &G.TYPE                     

The output is:

1,234.56    A


x
Using a Numeric Amper Variable as an Alphanumeric Subroutine Parameter

When using a numeric amper variable as an alphanumeric parameter in a subroutine call, you must convert the numeric value to an alphanumeric string before using it in order to avoid failure due to a format error. You can do this using one of the subroutines designed to convert numerics to alphanumeric, or you can concatenate an alphanumeric character to the numeric value in order to assign it an alphanumeric data type.

For example, the following converts &C to a string and returns the string to the variable &G. It then passes &G to the RJUST subroutine, which right justifies the value and returns it to the variable &H:

-SET &C=123.55;                   
-SET  &G=FTOA(&C,'(D7.2M)','A11');
-SET &H = RJUST(11,&G,'A11');    
-TYPE &G &G.TYPE                  
-TYPE &H &H.TYPE                  

The output is:

$123.55   A
  $123.55 A

Top of page

x
Debugging a Procedure

How to:

Reference:

You can test and debug your procedure with the following.



x
Syntax: How to Display Command Lines as They Execute
{-DEFAULT|-SET|EX} &ECHO = {ON|ALL|OFF|NONE}

where:

ON

Displays WebFOCUS commands that are expanded and stacked for execution.

ALL

Displays Dialogue Manager commands and WebFOCUS commands that are expanded and stacked for execution.

OFF

Suppresses the display of both stacked commands and Dialogue Manager commands. This value is the default.

NONE

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

By default, any procedure that does not explicitly set the &ECHO variable executes with the value OFF. You can change this default value for &ECHO with the SET DEFECHO command.



x
Syntax: How to Establish a Default Value for the &ECHO Variable
SET DEFECHO = {OFF|ON|ALL|NONE}

where:

OFF

Establishes OFF as the default value for &ECHO. OFF is the default value.

ON

Establishes ON as the default value for &ECHO. Displays WebFOCUS commands that are expanded and stacked for execution.

ALL

Establishes ALL as the default value for &ECHO. ALL displays Dialogue Manager commands and WebFOCUS commands that are expanded and stacked for execution.

NONE

Prevents procedure code from being displayed (echoed). Once the value of DEFECHO or &ECHO has been set to NONE, it cannot be changed during the session or connection.



x
Reference: Usage Notes for SET DEFECHO = NONE


Example: Preventing Procedure Code From Being Displayed

The following procedure queries the value of the DEFECHO parameter and issues a TABLE request against the EMPLOYEE data source:

? SET DEFECHO 
-RUN   
-TYPE ECHO = &ECHO         
TABLE FILE EMPLOYEE        
PRINT CURR_SAL CURR_JOBCODE
BY LAST_NAME BY FIRST_NAME 
END                        
-RUN

The query command output shows that DEFECHO is OFF (the default value):

 DEFECHO                  OFF

The -TYPE command shows that the value of &ECHO is OFF (the default):

ECHO = OFF

Because &ECHO is OFF the TABLE commands do not display as the procedure executes:

 NUMBER OF RECORDS IN TABLE=       12  LINES=     12
                                                    
 PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY    
PAGE     1                                                
                                                          
LAST_NAME        FIRST_NAME         CURR_SAL  CURR_JOBCODE
---------        ----------         --------  ------------
BANNING          JOHN             $29,700.00  A17         
BLACKWOOD        ROSEMARIE        $21,780.00  B04         
CROSS            BARBARA          $27,062.00  A17         
GREENSPAN        MARY              $9,000.00  A07         
IRVING           JOAN             $26,862.00  A15         
JONES            DIANE            $18,480.00  B03         
MCCOY            JOHN             $18,480.00  B02         
MCKNIGHT         ROGER            $16,100.00  B02         
ROMANS           ANTHONY          $21,120.00  B04         
SMITH            MARY             $13,200.00  B14         
                 RICHARD           $9,500.00  A01         
STEVENS          ALFRED           $11,000.00  A07         
                                                          
                                                          
                                                          
                                                          
                                                          
                                                          
                               END OF REPORT

Now, set DEFECHO=ON and re-run the procedure.

The query command output shows that DEFECHO is ON:

 DEFECHO                  ON

The -TYPE command shows that the value of &ECHO has been changed to ON:

ECHO = ON

Because &ECHO is ON, the TABLE commands display as the procedure executes:

TABLE FILE EMPLOYEE                                 
PRINT CURR_SAL CURR_JOBCODE                         
BY LAST_NAME BY FIRST_NAME                          
END

The output displays next:

 NUMBER OF RECORDS IN TABLE=       12  LINES=     12
                                                    
 PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY    
PAGE     1                                                
                                                          
                                                          
LAST_NAME        FIRST_NAME         CURR_SAL  CURR_JOBCODE
---------        ----------         --------  ------------
BANNING          JOHN             $29,700.00  A17         
BLACKWOOD        ROSEMARIE        $21,780.00  B04         
CROSS            BARBARA          $27,062.00  A17         
GREENSPAN        MARY              $9,000.00  A07         
IRVING           JOAN             $26,862.00  A15         
JONES            DIANE            $18,480.00  B03         
MCCOY            JOHN             $18,480.00  B02         
MCKNIGHT         ROGER            $16,100.00  B02         
ROMANS           ANTHONY          $21,120.00  B04         
SMITH            MARY             $13,200.00  B14         
                 RICHARD           $9,500.00  A01         
STEVENS          ALFRED           $11,000.00  A07         
                                                          
                                                          
                                                          
                                                          
                                                          
                                                          
                               END OF REPORT

Now, issue the SET DEFECHO = NONE command and rerun the procedure:

SET DEFECHO = NONE

The query command output shows that the value of DEFECHO has been changed to NONE:

 DEFECHO                 NONE

The -TYPE command shows that the value of &ECHO is NONE:

ECHO = NONE

Because DEFECHO has the value NONE, the TABLE commands do not display as the procedure executes. The output is:

 NUMBER OF RECORDS IN TABLE=       12  LINES=     12
                                                    
 PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY    
PAGE     1                                                
                                                          
                                                          
LAST_NAME        FIRST_NAME         CURR_SAL  CURR_JOBCODE
---------        ----------         --------  ------------
BANNING          JOHN             $29,700.00  A17         
BLACKWOOD        ROSEMARIE        $21,780.00  B04         
CROSS            BARBARA          $27,062.00  A17         
GREENSPAN        MARY              $9,000.00  A07         
IRVING           JOAN             $26,862.00  A15         
JONES            DIANE            $18,480.00  B03         
MCCOY            JOHN             $18,480.00  B02         
MCKNIGHT         ROGER            $16,100.00  B02         
ROMANS           ANTHONY          $21,120.00  B04         
SMITH            MARY             $13,200.00  B14         
                 RICHARD           $9,500.00  A01         
STEVENS          ALFRED           $11,000.00  A07         
                                                          
                                                          
                                                          
                                                          
                                                          
                                                          
                               END OF REPORT

Once the value of DEFECHO has been set to NONE, it cannot be changed. The following SET command attempts to change the value to ON, but the query command output shows that it is still NONE:

SET DEFECHO=ON          
? SET DEFECHO           
 DEFECHO                 NONE


x
Syntax: How to Test Dialogue Manager Command Logic
{-DEFAULT|-SET|EX procname} &STACK = {ON|OFF}

where:

procname

Is the procedure to execute.

ON

Executes stacked commands normally. This value is the default.

OFF

Prevents the execution of stacked commands. In addition, system variables (for example, &RECORDS or &LINES) are not set. Dialogue Manager commands are executed so you can test the logic of the procedure.

Note: &STACK is usually used with &ECHO = ALL for debugging purposes. The display displays both the Dialogue Manager commands, as well as the WebFOCUS commands with the supplied values. You can view the logic of the procedure.



Example: Using the &RETCODE Variable to Test the Result of a Command

If you are using Simultaneous Usage (SU), you must know if the WebFOCUS Database Server is available before beginning a particular procedure. The following procedure tests whether SINK1 is available before launching PROC1.

? SU SINK1
-RUN
-IF &RETCODE EQ 16 GOTO BAD;
-INCLUDE PROC1
-BAD
-EXIT


x
Reference: Testing the Status of a Query

The system variable &RETCODE returns a code after a query is executed. If the query results in a normal display, the value of &RETCODE is 0. If a display error occurs, or no display results (as can happen when the query finds no data), the value of &RETCODE is 8. (If the error occurs on a ? SU, the value of &RETCODE is 16.)

The value of &RETCODE is set following the execution of any of these queries:

Command

NORMAL

NODISPLAY

ERROR

? HOLD

0

8

 

? SU* 

0

8

16

? JOIN

0

8

 

? COMBINE

0

8

 

? DEFINE

0

8

 

? USE

0

8

 

? LOAD

0

8

 

*The &RETCODE value of ? SU means: 0 indicates that the WebFOCUS Database Server (formerly called the sink machine) is up with one or more users, 8 indicates that the WebFOCUS Database Server is up with no users, and 16 indicates that there is an error in communicating to the WebFOCUS Database Server.

You can test the status of any of these queries by checking the &RETCODE variable and providing branching instructions in your procedure.



x
Issuing an Operating System Command

How to:

You can issue an operating system command to set up an environment in which a request must run. For example, a program may allocate files, rename files, copy files, or perform other operations before executing a request.



x
Syntax: How to Execute an Operating System Command
op_system command

where:

op_system

Specifies the operating system.

command

Is an operating system command.


Top of page

x
Dialogue Manager Quick Reference

In this section:

 

This topic provides an alphabetical list of all Dialogue Manager commands, including a description of functions and syntax.

It also provides a grouped list of Dialogue Manager defaults and limits.

Note that this information is also presented throughout the chapter in the context of the task to which it applies.



x
-* Command

The command -* signals the beginning of a comment line.

Any number of comment lines can follow one another, but each must begin with -*. A comment line may be placed at the beginning or end of a procedure, or in between commands. However, it cannot be on the same line as a command.

Use comment lines liberally to document a procedure so that its purpose and history are clear to others.

The syntax is

-* text				

where:

text

Is a comment. A space is not required between -* and text.



x
? Command

The command -? displays the current value of a local variable.

The syntax is

-? &[variablename]

where:

variablename

Is a variable name of up to 12 characters. If this parameter is not specified, the current values of all local, global, and defined system and statistical variables are displayed.



x
-CLOSE Command

-CLOSE closes an external file opened with the -READ or -WRITE NOCLOSE option. The NOCLOSE option keeps a file open until the -READ or -WRITE operation is complete.

The syntax is

-CLOSE {ddname|*}

where:

ddname

Is the ddname of the open file described to WebFOCUS using an allocation.

*

Closes all -READ and -WRITE files that are currently open.



x
-DEFAULT[S|H] Command

DEFAULT commands set default values for local or global variables. ‑DEFAULT guarantees that the variables are always given a value and helps ensure that it executes correctly.

You can issue multiple -DEFAULT commands for a variable. If the variable is global, these ‑DEFAULT commands can be issued in separate FOCEXECs. At any point before another method is used to establish a value for the variable, the most recently issued ‑DEFAULT command will be in effect.

However, as soon as a value for the variable is established using any other method, subsequent -DEFAULT commands issued for that variable are ignored.

You can override -DEFAULT values by supplying values for the variables on the command line, or by supplying a value with -SET subsequent to -DEFAULT.

Default values are provided in other WebFOCUS modules to anticipate user needs and reduce the need for keystrokes in situations where most users desire a predefined outcome.

The syntax is

-DEFAULT[S|H] &[&]name=value [...]

where:

&name

Is the name of the variable.

value

Is the default value assigned to the variable.



x
-EXIT Command

-EXIT forces a procedure to end. All stacked commands are executed and the procedure exits. If the procedure was called by another one, 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 is an implicit -EXIT.

The syntax is

-EXIT


x
-GOTO Command

-GOTO transfers control to a specified label.

If Dialogue Manager finds the label, processing continues with the line following it. If Dialogue Manager does not find the label, processing ends and an error message is displayed.

The syntax is

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

where:

label

The label in the -label command Is a user-defined name of up to 12 characters that specifies the target of the -GOTO action.

Do not use embedded blanks or the name of any other Dialogue Manager command except -EXIT. Do not use words that can be confused with functions, arithmetic and logical operations, and so on.

TYPE text

Optionally sends a message to the client application.



x
-IF Command

-IF routes execution of a procedure based on the evaluation of the specified expression.

An -IF without an explicitly specified ELSE whose expression is false continues processing with the line immediately following it.

The syntax is

-IF expression [THEN] GOTO label1 
[- ELSE GOTO label2]
[- ELSE IF...];

where:

label

Is a user-defined name of up to 12 characters that specifies the target of the GOTO action.

Do not use embedded blanks or the name of any other Dialogue Manager command except -EXIT. Do not use words that can be confused with functions, arithmetic or logical operations, and so on.

expression

Is a valid expression. Literals need not be enclosed in single quotation marks unless they contain embedded blanks or commas.

THEN

Is an optional keyword that increases readability of the command.

ELSE GOTO

Passes control to label2 when the -IF test fails.

ELSE IF

Specifies a compound -IF test.

The semicolon is required at the end of the command, and continuation lines must begin with a hyphen.



x
-INCLUDE Command

-INCLUDE specifies another procedure to be incorporated and executed at run time, as if it were part of the calling procedure. The specified procedure may comprise either a fully developed or partial procedure. Note that a partial procedure does not execute if called outside of the procedure containing -INCLUDE.

When using -INCLUDE, you may not branch to a label outside of the specified procedure.

A procedure may contain more than one -INCLUDE. Any number of -INCLUDEs may be nested, but recursive -INCLUDEs are limited to four levels.

You may use any valid command in a -INCLUDE.

EXEC may also be used to execute a procedure inside another procedure.

The syntax is

-INCLUDE filename [filetype]

where:

filename

Is the procedure to be incorporated in the calling procedure.

filetype

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



x
-label Command

The label specified in the -label command Is the target of a -GOTO command or -IF criteria.

The syntax is

-label [TYPE message]

where:

label

Is a user-supplied name of up to 12 characters that identifies the target for a branch.

Do not use embedded blanks or the name of any other Dialogue Manager command except -EXIT. Do not use words that can be confused with functions, arithmetic or logical operations, and so on.

TYPE message

Sends a message to the client application.



x
-PASS Command

-PASS directly issues and controls passwords. This feature is especially useful for specifying a particular file or set of files that a given user can read or write. Passwords have detailed sets of functions associated with them through DBA module.

The procedure that sets passwords should be encrypted so that it and the passwords that it sets cannot be typed and made known.

A variable can be associated with -PASS so that you can prompt for and assign a password value.

The PASS command provides the same function at the command level, as does the PASS parameter of the SET command.

The syntax is

-PASS password				

where:

password

Is a literal WebFOCUS password or a variable containing a password.



x
-READ Command

Reads data from an external (non-WebFOCUS) file. -READ can access data in either fixed or free form.

The syntax is

-READ ddname[,] [NOCLOSE] &name[.format.][,] ...

where:

ddname

Is the logical name of the file as defined to WebFOCUS using ALLOCATE or DYNAM ALLOCATE. A space after the ddname denotes a fixed format file while a comma denotes a comma-delimited file.

NOCLOSE

Indicates that the ddname should be kept open even after a -RUN is executed. The ddname is closed upon completion of the procedure or when a -CLOSE or subsequent -WRITE command is encountered.

name

Is the variable name. You may specify more than one variable. Using a comma to separate variables is optional.

If the list of variables is longer than one line, end the first line with a comma and begin the next line with a dash followed by a blank (-) for comma-delimited files or a dash followed by a comma followed by a blank (-,) for fixed format files. For example:

Comma-delimited files

-READ EXTFILE, &CITY,&CODE1,- &CODE2

Fixed format files

-READ EXTFILE &CITY.A8. &CODE1.A3.,-, &CODE2.A3
format

Is the format of the variable. It may be Alphanumeric (A) or Integer (I). Note that format must be delimited by periods. The format is ignored for comma-delimited files.



x
-READFILE Command

-READFILE reads a Master File, then reads values from a file into variables based on the fields listed in the Master File.

-READFILE [app/]mastername

where:

app

Is the application directory in which the file resides.

mastername

Is the name of the Master File to be read.



x
-REMOTE Command

-REMOTE passes execution of the commands within a -REMOTE BEGIN and -REMOTE END command to a server.

The syntax is

-REMOTE BEGIN
commands
-REMOTE END


x
-REPEAT Command

-REPEAT allows looping in a procedure.

A loop ends when any of the following occurs:

The syntax is

-REPEAT label n TIMES
-REPEAT label WHILE condition; 
-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 from 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 -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 is run if the condition is true.

Note: The condition must be followed by a semi-colon.

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



x
-RUN Command

-RUN causes immediate execution of all stacked WebFOCUS commands.

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

-RUN is commonly used to do the following:

The syntax is

-RUN


x
-SET Command

-SET assigns a literal value, or a value that is computed in an arithmetic or logical expression, to a variable.

Single quotation marks around a literal value are optional unless it contains an embedded blank, comma, or equal sign, in which case you must include them.

The syntax is

-SET &[&]name= {expression|value};

where:

&name

Is the name of the variable.

expression

Is a valid expression. Expressions can occupy several lines, so you should end the command with a semicolon.

value

Is a literal value, or arithmetic or logical expression assigned to the variable. If the literal value contains commas or embedded blanks, you must enclose the value in single quotation marks.



x
-TYPE Command

Transmits informative messages to the user at the display. Any number of -TYPE lines may follow one another but each must begin with -TYPE.

Substitutable variables may be embedded in text. The values currently assigned to each variable is displayed in the assigned position in the text.

-TYPE1 and TYPE+ are not supported by IBM 3270-type displays.

TYPE is used in a variety of ways in WebFOCUS to send informative messages to the screen. A TYPE command may appear on the same line as a label in Dialogue Manager. In MODIFY, TYPE is used to print messages at the start and end of processes, at selected positions in MATCH or NOMATCH, NEXT or NONEXT, and to send a message after an INVALID data condition.

The syntax is

-TYPE[+] text 
-TYPE[0] text 
-TYPE[1] text				

where:

-TYPE1

Sends the text after issuing a page eject.

-TYPE0

Sends the text after skipping a line.

-TYPE+

Sends the text but does not add a line feed.

text

Is a character string that fits on a line.



x
-WRITE Command

-WRITE writes data to a sequential file.

If the command continues over several lines, put a comma at the end of the line and a hyphen at the beginning of each subsequent line.

Unless you specify the NOCLOSE option, an opened file is closed upon termination of the procedure with -RUN or -EXIT.

In TABLE, WRITE is a synonym for SUM; functionally it is quite different from ‑WRITE.

The syntax is

-WRITE ddname [NOCLOSE] text				

where:

ddname

Is the logical name of the file as defined to WebFOCUS using ALLOCATE or DYNAM ALLOCATE.

NOCLOSE

Indicates that the file should be kept open even if a -RUN is encountered. The file is closed upon completion of the procedure or when a -CLOSE or subsequent -READ command is encountered.

text

Is any combination of variables and text. To write more than one line, end the first line with a comma (,) and begin the next line with a hyphen followed by a space (-).



x
Dialogue Manager Defaults and Limits

This topic provides you with an easier way of locating default values, operating system and WebFOCUS limits, summary tables, general rules, and tips for ease-of-use.

General rules to follow when you are creating procedures:

General rules for supplying values for variables:

Operating system default values, limits, and format specifications.


WebFOCUS