Using Variables

In this section:

This section describes how to use variables in a procedure.

Variables fall into two categories:

The following features apply to all variables:


Top of page

x
Naming Conventions

How to:

This section describes how to use variables in a procedure.

Variables fall into two categories:

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 Use Variables in a Procedure
&[&]name&WHICHPRODUCT

where:

&name

Is the user-defined name of a local variable. The first character of name must be A through Z.

&&name

Is the user-defined name of a global variable. The first character of name must be A through Z.

The following variables are properly named:

&WHICHPRODUCT
&WHICH_CITY
'&CITY'
&&CITY

The following variables are improperly named for the reason given:

Invalid

Reason

&CORPORATECITY

Too long (exceeds 12 characters).

&WHICH CITY

Contains embedded blank.

&WHICH-CITY

Contains a hyphen (-).

WHICHCITY

Leading ampersand(s) is missing.



x
Local Variables

Once supplied, values for local variables remain in effect throughout a single procedure. The values are lost after the procedure finishes processing and are not passed to other procedures that contain the same variable name.



Example: Using Local Variables

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

  .
  .
  .
SQL
SELECT SUM (UNIT_SOLD),
       SUM (RETURNS)
FROM SALES
WHERE CITY = '&CITY'
AND PROD_CODE >= '&CODE1'
AND PROD_CODE <= '&CODE2'
  .
  .
  .

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

CITY=STAMFORD, CODE1=B10, CODE2=B20

Dialogue Manager substitutes the values for the variables as follows:

  .
  .
  .
SQL
SELECT SUM (UNIT_SOLD),
       SUM (RETURNS), CITY
FROM SALES
WHERE CITY = STAMFORD
AND PROD_CODE >= B10
AND PROD_CODE <= B20
GROUP BY CITY, PROD_CODE
  .
  .
  .

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



Example: Creating an Indexed Variable

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

If the index 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 is used as a counter; it is set, incremented, and tested in a procedure.

You create an indexed variable with the command -SET

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

[.&index...]

Represents any number of indices. 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. See Creating Expressions for information on the kinds of expressions allowed.

An indexed variable is 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 increases the index by increments each time the procedure goes through a 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 does not change.

Indexed variables are included in the system limit of 994.



Example: Displaying the Value of Local Variables

To display the current value of a local variable, enter the following in a procedure

-? &[string]

where:

string

Is an optional 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.


Top of page

x
Global Variables

Once a value is supplied for a global variable, it remains in effect throughout the session of a processing service, unless cleared by the server. All procedures that contain the same global variable name receive the supplied value until you terminate the session.



Example: Using Global Variables

The following example illustrates the use of three global variables: &&CITY, &&CODE1, &&CODE2.

  .
  .
  .
SQL
SELECT SUM (UNIT_SOLD),
       SUM (RETURNS)
FROM SALES
WHERE CITY = &&CITY
AND PROD_CODE >= &&CODE1
AND PROD_CODE <= &&CODE2
  ;
TABLE
ON TABLE PCHOLD
END


Example: Displaying the Value of Global Variables

To display the current value of all global variables, enter the following command in a procedure:

? &&

Top of page

x
System Variables

The table in this section describes commonly used run time system variables that you can use in a procedure. Dialogue Manager automatically supplies values for these variables whenever the variables are encountered. Additionally, other variables do exist for other specific features and are documented within those features.

Unless otherwise noted in the table, you may override run time values by replacing or adding the parameter values specified:

System Variable

Description

Format or Value

&APPROOT

Physical location of the APPROOT directory.

Directory name.

&DATE

Current date.

MM/DD/YY 
&DATEfmt

Current date.

fmt is any combination of YYMD, MDYY, and so on.

&MDY

Current date. Useful for numerical comparisons.

MMDDYY 
&MDYY

Current date (four-digit year).

MMDDCCYY 
&DMY

Current date.

DDMMYY 
&DMYY

Current date (four-digit year).

DDMMCCYY
&YMD

Current date.

YYMMDD 
&YYMD

Current date (four-digit year).

CCYYMMDD
&FOCFOCEXEC

Current running procedure.

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

&FOCINCLUDE

Current included procedure.

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

&ECHO

Current echo tracing value.

ON, OFF, or ALL 
&FOCMODE

Operating environment.

AS/400
CMS
CRJE
MSO
DOS
TSO
UNIX
VMS
WINNT 
&FOCPRINT

Current print setting.

ONLINE
OFFLINE 
&FOCREL

Source code release number.

Release number (for example, R720530B).

&IORETURN

Value returned after the last Dialogue Manager -READ or -WRITE operation.

0 Successful operation.

1 End or failure.

&RETCODE

Return code value from execution of a server or operating system command.

Referencing &RETCODE forces the execution of all stacked commands, like the command -RUN.

Any value returned by a command is valid (for example, CALLPGM flag values), but zero is considered normal (successful) execution.

The one exception is the &RETCODE value of dash operating system commands, such as -DOS, -UNIX, -VMS, -AS/400, 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.

&EXITRC

Return code value from execution of an operating system command.

Referencing &EXITRC forces the execution of all stacked commands, like the command -RUN.

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

&TOD

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

HH.MM.SS
&FOCNET

Environment.

CLIENT, SERVER

You cannot override the system-supplied value.

&SETFILE

Value of SET FILENAME = setting. Not normally set, so normally blank.

String, such as CAR.

&FOCCODEPAGE

Code page of the server when NLS is configured else varies by platform when not configured.

Numeric, such as 297, not changeable.

&FOCLANGCODE

Language of the server when NLS is configured, else blank.

String, such as FRE, not changeable.

&LINES

Number of lines printed in last TABLE.

Numeric, not changeable.

&RECORDS

Number of records retrieved for last TABLE/GRAPH.

Numeric, not changeable.

&TRANS

Number of transactions processed.

Numeric, not changeable.

&ACCEPTS

Accepted transactions.

Numeric, not changeable.

&NOMATCH

Nomatch rejects.

Numeric, not changeable.

&FORMAT

Format errors.

Numeric, not changeable.

&INVALID

Invalid conditions.

Numeric, not changeable.

&DUPLS

Duplicates rejected.

Numeric, not changeable.

&INPUT

Segments input.

Numeric, not changeable.

&CHNGD

Values updated.

Numeric, not changeable.

&DELTD

Segments deleted.

Numeric, not changeable.

&RETCODE

Value after DOS command.

Numeric, not changeable.

&BASEIO

Number of input/output operations.

Numeric, not changeable.

&READS

Read operations from external file.

Numeric, not changeable.

&REJECTS

Number of rejected transactions.

Numeric, not changeable.



Example: Using Run Time System Variables

The following example incorporates the system variable &DATE into an SQL request, testing a user-supplied variable (IDATE) against it.

SQL
 SELECT '&DATE',IDATE
 FROM filename 
 WHERE IDATE < '08/08/2004'
-EXIT

Top of page

x
Variables and Command Structures

A variable refers to a command, a database field, a verb, or a phrase. In this way, the command structure of a procedure is determined by the value of the variable.



Example: Using Variables to Alter Commands

In the following example, the variable &FIELD determines which field to SELECT in the SQL request. For example, &FIELD could have the value RETURNS, DAMAGED, or UNIT_SOLD from a database named SALES.

SQL
 .
 .
 .
SELECT &FIELD
ORDER BY PROD_CODE
 .
 .
 .

iWay Software