In this section: |
You must supply values for variables in a procedure even if the value is a blank. For instance, some server commands are invalid without values but process normally with blanks.
Supply values for variables in the following ways:
This section describes the second method, within the procedure itself.
The following general rules apply to values for variables:
How to: |
The command EXEC enables you to call one procedure from another and set values for variables in the called procedure, using:
A parameter list specified on the command line has a maximum string length of up to 4096 bytes including the "EX" and file name portions. A string of this length is typically built using concatenation of values.
Note: EX lines have special treatment. Normally, all other lines are limited to 80 characters.
Consider the following procedure named SLRPT:
. . . SQL SELECT SUM(UNIT_SOLD),SUM(RETURNS),PROD_CODE,CITY FROM SALES WHERE PROD_CODE BETWEEN '&CODE1' AND '&CODE2' AND CITY = '&CITY' GROUP BY PROD_CODE,CITY . . .
This procedure is called by another procedure using EXEC, with the values for &CODE1, &CODE2, and &CITY supplied on the command line as keyword parameters:
EXEC SLRPT CODE1=A,CODE2=D,CITY=NYC
EX[EC] procedurename=value[,...]
where:
Is the name of the called procedure.
Is a keyword parameter.
If value contains an embedded comma, blank, or equal sign, it must be enclosed in single quotation marks. For example:
EX SLRPT AREA=S, CITY='NY, NY'
Name=value pairs must be separated by commas. You do not need to enter pairs in the order in which they are encountered in the procedure.
If the list of parameters exceeds the width of the command line, insert a comma as the last character on the line and enter the rest of the list on the following line, as shown here:
EX SLRPT AREA=S,CITY=STAMFORD,VERB=COUNT, FIELDS=UNIT_SOLD,CODE1=B10,CODE2=B20
EX[EC] procedure parm1[,...]
where:
Is the name of the called procedure.
Is a positional parameter. You do not need to specify the number in the parameter list. Dialogue Manager matches the values, one by one, to the positional variables as they are encountered in the called procedure.
However, you must specify the parameters in the order in which to be used in the called procedure.
Consider the following called procedure:
. . . SQL SELECT SUM(UNIT_SOLD),SUM(RETURNS),RETURNS/UNIT_SOLD FROM SALES WHERE PROD_CODE BETWEEN '&1' AND '&2' AND CITY = '&3' . . .
The calling procedure would issue:
EX SLRPT B10,B20,STAMFORD
Consider the following procedure named PPARM1:
SQL SELECT &1, &2, &field1, &3 FROM CAR;
It is called by another procedure using EXEC, with the values MODEL, MPG, field1=CAR, and COUNTRY supplied on the command line as parameters:
EXEC PPARM1 MODEL,MPG,field1=CAR,COUNTRY
Note: As of release 5.3, the line length limit has been increased to 32K, so large parameters can be directly passed. The method described below continues to be supported, but there is little reason to use this method in coding new applications.
Individual parameter keyword value pairs that are longer than 80 characters (the limit of a physical line) must use special syntax to describe how many lines to read.
EX[EC] - LINES numberprocedure_name=value[,...]
where:
Is the number of additional lines to read as a continuation of the initial line. Break variables into 80 character lengths per line.
Is the name of a Dialogue Manager procedure.
Is the actual string being passed.
The following is an example of a server procedure passing the maximum parameter of 32,000 bytes:
"EX -LINES 401 CPG32000=LINE000000000000000000000000000000000000000000001 " "LINEOFINFORMATION1111111111111111111111111111111111111111111111111111111111111" "LINEOFINFORMATION2222222222222222222222222222222222222222222222222222222222222" "LINEOFINFORMATION4004004004004004004004004004004004004004004004004004004004004" . . . "LASTLINETOTAL32000BYTESTHEENDXX"
How to: |
Dialogue Manager implements IF THEN ELSE and other flow logic such as -GOTO. Dynamically display the flow of execution using the &ECHO variable.
&ECHO = display-DEFAULTS &ECHO = ALL
Valid values are:
Displays lines that are expanded and stacked for execution.
Displays Dialogue Manager commands as well as lines that are expanded and stacked for execution.
Suppresses display of both stacked lines and Dialogue Manager commands. OFF is the default value.
Set &ECHO through -DEFAULTS, -SET, or on the command line. For example, set ECHO to ALL for the execution of the procedure SLRPT using any of the following commands:
-DEFAULTS &ECHO = ALL
or
-SET &ECHO = ALL;
or
EX SLRPT ECHO = ON
If you use -SET or -DEFAULTS in the procedure, display begins from that point in the procedure and is turned off and on again at any other point.
Note that if the procedure is encrypted, &ECHO automatically receives the value OFF, regardless of the value that is assigned explicitly.
How to: Reference: |
The Dialogue Manager command -DEFAULTS supplies an initial (default) value for a variable that had no value before the command was processed. It ensures that values are passed to variables whether or not they are provided elsewhere.
-DEFAULT[S] &[&]name=value [...]
where:
Is the name of the variable.
Is the default value assigned to the variable.
In the following example, -DEFAULT[S] sets default values for &CITY and ®IONMGR.
-DEFAULTS &CITY=STAMFORD, ®IONMGR=SMITH -TYPE Default values are Stamford, Smith. SQL . . .
Override default values by supplying new values:
For example, if you issued the following EXEC command, the specified value for REGIONMGR (JONES) would override the value SMITH in the previous example:
EX SLRPT REGIONMGR=JONES
How to: |
With the -SET command, assign a value computed in an expression.
-SET &[&]name=expression;-SET &NAME='JOHN DOE';
where:
Is the name of the variable.
Is a valid expression. Expressions occupy several lines, so end the command with a semicolon (;).
You can assign a literal value to a variable. Single quotation marks around the literal value are optional unless it contains embedded blanks or commas, in which case you must include single quotation marks:
-SET &NAME='JOHN DOE';
To assign a literal value that includes a single quotation mark, place two single quotation marks where you want one to appear:
-SET &NAME='JOHN O''HARA';
The length of a literal value is limited by how the value is constructed. A single simple value (such as the 'JOHN DOE' example) is limited to the line length limit, which was 80 but is now 32K as of release 5.3. Using concatenation, several lines of separate values may be joined together to form longer variables, which is the method used for older releases. For example,
-SET &LONG = 'xxxxx...';
-SET &LONGER = &LONG|&LONG|&LONG;
-SET &VERYLONG = &LONGER|&LONGER;
The maximum length of a variable is 32K, however, this is further limited if the variable is to participate in a calculation or concatenation.
Through the technique of building strings above, the total maximum length is 4K (2K to the right of the equal sign and 2K to the left of the equal sign). In the case of an expression, the left side of the equal sign could be of a minimal length, with the remainder of the length on the right side of the equal sign but the total maximum is 415.
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.
-TYPE THIS REPORT IS FOR &CODE. -SET &STORECODE = IF &CODE GT C2 THEN '14Z' ELSE '14B'; SQL SELECT SUM(UNIT_SOLD),SUM(RETURNS),RETURNS/UNIT_SOLD FROM SALES WHERE PROD_CODE BETWEEN '&CODE1' AND '&CODE2' AND STORE_CODE = '&STORECODE' GROUP BY PROD_CODE,STORECODE . . .
How to: |
With the -SET command, assign a value computed in an expression.
Supply values for variables by reading each from an external file. The file is fixed format (the data is in fixed columns) or free format (the data is delimited by commas).
-READ filename[,] [NOCLOSE] &name[.format.][,]...
where:
Is the name of the external file, which must be defined to the operating system. A space after filename denotes a fixed-format file, while a comma denotes a free-format file. For more information, see Platform-Specific Commands and Features.
Optionally keeps the external file open until the -READ operation is complete. Files kept open with NOCLOSE are closed using the command -CLOSE filename.
Note: The -RUN command does not close an external file if NOCLOSE is specified.
Is a list of variables. For free-format files, you may optionally separate the variable names with commas.
Is the format of the variable. For free-format files, you do not have to specify this value, but you may. For fixed-format files, format is the length or the length and type of the variable (A is the default type). The value of format must be delimited by periods. See Specifying Length.
If the list of variables is longer than one line, end the first line with a comma (,) and begin the next line with a hyphen (-) when you are reading a free-format file:
-READ EXTFILE, &CITY, &CODE1, - &CODE2
When you are reading a fixed-format file, begin the next line with a hyphen and comma (-,):
-READ EXTFILE &CITY.A8. &CODE1.A3., -, &CODE2.A3.
The line immediately following a -READ is typically a check of &IORETURN for end of file, as shown in the example shown in Using the -READ Command.
Instead of using .format., specify the length of a variable using -SET. For example:
-SET &CITY=' '; -SET &CODE1=' '; -SET &CODE2=' ';
The file name parameter is a symbolic name for a physical file known to the server operating system. Each operating system has its own method for associating a symbolic name with a physical file.
For instance, under MVS, the DYNAM command is used:
DYNAM ALLOC FILE EXTFILE DSNAME EDAUSER.EXTFILE.DATA SHR
On UNIX, Windows, OpenVMS, and IBMÂ i platforms, the FILEDEF command is used. For example, on UNIX:
FILEDEF MYFILE DISK /home/edauser/extfile.dat
where the data file portion would use the actual native file name convention of the platform.
Assume that EXTFILE is a fixed-format file containing the data:
STAMFORDB10B20
To detect the end of file, the following code tests the system variable &IORETURN. When no records remain to be read, its value is not equal to zero.
-READ EXTFILE &CITY.A8. &CODE1.A3. &CODE2.A3. -IF &IORETURN NE 0 GOTO RUN; SQL SELECT SUM(UNIT_SOLD),SUM(RETURNS) FROM SALES WHERE PROD_CODE BETWEEN '&CODE1' AND '&CODE2' AND CITY = '&CITY' GROUP BY PROD_CODE,CITY -RUN
iWay Software |