Using Variables in a Procedure

In this section:

How to:

Reference:

Interactive variable substitution is at the heart of Dialogue Manager. 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. A variable can refer to a field, a command, descriptive text, a file name—literally anything.

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 as described in Specify Precision for Dialogue Manager Calculations.

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

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

You can query the values of each type of variable you use. For details, see Querying the Values of Variables and Parameters.

The values for variables may be supplied in a variety of ways. For details, see Supplying and Verifying Values for Variables.

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:

  • A local variable name is always preceded by an ampersand (&). The variable can be named or positional.

    A positional variable consists of a single ampersand followed by a numeric string (for example, &1). The value of a positional variable is passed to a procedure when it is executed.

  • A global variable name is always preceded by a double ampersand (&&).
  • Embedded blanks are not permitted in a variable name.
  • If a value for a variable might contain an embedded blank, comma, or equal sign, enclose the variable in single quotation marks when referred to.
  • A variable name may be any combination of the characters A through Z, 0 through 9, and the underscore. The first character of the name should be a letter.
  • You can assign a number instead of a name to a variable to create a positional variable.
  • The underscore may be included in a variable name, but the following special characters are not permitted: plus sign, minus sign, asterisk, slash, period, ampersand, and semicolon.

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 in Naming Conventions for Local and Global Variables.

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.

Global Variables

Global variables differ from local variables in that once a value is supplied, it remains current throughout the FOCUS session unless set to another value with -SET or cleared by the LET CLEAR command. For information on LET CLEAR, see Defining a Word Substitution. 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 FOCUS.

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

System Variables

Reference:

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

Reference: Summary of System Variables

A list of Dialogue Manager system variables follows:

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 Chapter 4, Describing an Individual Field, in the Describing Data 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. 

&ECHO
 
ON,OFF, ALL, or NONE

Displays command lines as they execute in order to test and debug procedures. 

&EXITRC

Any value returned by a command is valid, but zero is considered normal (successful) execution.

Return code value from execution an operating system command. Referencing &EXITRC forces the execution of all stacked commands, like the command -RUN. 

&FOCCODEPAGE
 
 

Returns the code page being used by FOCUS. 

&FOCCPU
 
milliseconds

Calculates the OS CPU time. 

&FOCEXTTRM
 
ON
OFF

Indicates the availability of extended terminal 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. 

&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
 
FOCUS 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 FOCUS 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 terminal height. (This can be any value; the examples shown are common settings.) 

&FOCTRMSW
 
80
132

Indicates terminal width. (This can be any value; the examples shown are common settings.) 

&FOCTRMTYP
 
3270
TTY
UNKNOWN

Identifies the terminal 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

Any value defined by the FOCUS command.

Any value returned by a command is valid, but zero is considered normal (successful) execution.

The one exception is the &RETCODE value of dash operating system commands, such as -DOS, -UNIX, and -WINNT, represent the success, not of the command they are running, but of the ability of the server to spawn out to the OS and run the command. In this case, the &RETCODE value is normally zero because it reflects that the spawn executes normally regardless of the results of the specific command. For this case, the amper variable &EXITRC should be used to check the command result or the non-dash version of the command should be used. 

numeric

&RETCODE executes all stacked commands, like the command -RUN. 

&SETFILE
 
alphanumeric

Contains the value from the SET FILE command. 

&TOD
 
HH.MM.SS

Returns the current time. When you enter FOCUS, 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: 

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:

Statistical Variables

Reference:

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

Reference: Summary of Statistical Variables

A list of Dialogue Manager statistical variables follows:

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 FOCUS 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. This value can be passed to the operating system with the line -QUIT FOCUS &FOCERRNUM. 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-FOCUS 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 
-QUIT
-REPTDONE
-EXIT

Special Variables

Reference:

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

Reference: Summary of Special Variables

A list of special variables follow:

Variable

Description

 
&CURSOR

Holds the cursor position. 

&CURSORAT

Reads the cursor position. 

&ECHO

Controls the display of commands for debugging purposes. 

&PFKEY

Holds the PF Key function that was pressed or entered. 

&QUIT

Controls whether the response QUIT, or PF1 in - CRTFORM, to a prompt causes an exit from the procedure. 

&STACK

Controls whether the entire procedure, or only the Dialogue Manager commands are executed. 

&WINDOWNAME

Holds the name of the last window activated by the most recently executed -WINDOW command (see Designing Windows With Window Painter). 

&WINDOWVALUE

Holds the return value of the last window activated by the most recently executed -WINDOW command (see Designing Windows With Window Painter).

Querying the Values of Variables and Parameters

How to:

Two Dialogue Manager commands enable you to:

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

For details about these commands, see Testing and Debugging With Query Commands.

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 FOCUS command line.

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 FOCUS setting that may be queried with the ? SET or ? SET ALL command. For details about these commands, see setcore111.htm#dsetcore1064926.

variablename

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

Example: Storing a Parameter Value Setting

If you enter 

-? SET ASNAMES &ABC
-TYPE &ABC

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

Information Builders