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:
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:
&[&]name&WHICHPRODUCT
where:
Is the user-defined name of a local variable. The first character of name must be A through Z.
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. |
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.
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.
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:
Is a variable.
Is a numeric or alphanumeric variable whose value is appended to &name. The period (.) is required.
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.
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.
To display the current value of a local variable, enter the following in a procedure
-? &[string]
where:
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.
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.
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
To display the current value of all global variables, enter the following command in a procedure:
? &&
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. |
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
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.
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 |