Supplying Values for Variables

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.


Top of page

x
General Rules

The following general rules apply to values for variables:


Top of page

x
Supplying Values in the EXEC Command

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.



Example: Supplying Values With the EXEC Command

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


x
Syntax: How to Pass Keyword Parameters
EX[EC] procedurename=value[,...]

where:

procedure

Is the name of the called procedure.

name=value

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


x
Syntax: How to Pass Positional Parameters
EX[EC] procedure parm1[,...]

where:

procedure

Is the name of the called procedure.

parm1

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


Example: Combining Positional and Keyword Parameters

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


x
Syntax: How to Pass Long Parameters

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:

number

Is the number of additional lines to read as a continuation of the initial line. Break variables into 80 character lengths per line.

procedure_name

Is the name of a Dialogue Manager procedure.

value

Is the actual string being passed.



Example: Passing Long Parameters

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"

Top of page

x
Debugging Execution Flow

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.



x
Syntax: How to Display Command Lines While Executing
&ECHO = display-DEFAULTS &ECHO = ALL

Valid values are:

ON

Displays lines that are expanded and stacked for execution.

ALL

Displays Dialogue Manager commands as well as lines that are expanded and stacked for execution.

OFF

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.


Top of page

x
-DEFAULT[S] Command

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.



x
Syntax: How to Supply Values With the -DEFAULT[S] Command
-DEFAULT[S] &[&]name=value [...]

where:

&name

Is the name of the variable.

value

Is the default value assigned to the variable.



Example: Setting Default Values With the -DEFAULT[S] Command

In the following example, -DEFAULT[S] sets default values for &CITY and &REGIONMGR.

-DEFAULTS &CITY=STAMFORD, &REGIONMGR=SMITH
-TYPE Default values are Stamford, Smith.
SQL
      .
      .
      .


x
Reference: Overriding Default Values

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

Top of page

x
-SET Command

How to:

With the -SET command, assign a value computed in an expression.



x
Syntax: How to Supply Values With the -SET Command
-SET &[&]name=expression;-SET &NAME='JOHN DOE';

where:

&name

Is the name of the variable.

expression;

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.



Example: Assigning Values With the -SET Command

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

Top of page

x
-READ Command

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



x
Syntax: How to Supply Values With the -READ Command
-READ filename[,] [NOCLOSE] &name[.format.][,]...

where:

filename[,]

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.

NOCLOSE

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.

&name[,]...

Is a list of variables. For free-format files, you may optionally separate the variable names with commas.

.format.

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.



Example: Specifying Length

Instead of using .format., specify the length of a variable using -SET. For example:

-SET &CITY='        ';
-SET &CODE1='   '; 
-SET &CODE2='   ';


Example: Using the -READ Command

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