CL Programming

Defining a Mixed List

A mixed list accepts a set of separately defined values that usually have different meanings, are of different types, and are in a fixed position in the list. For example, LOG(4 0 *SECLVL) could specify a mixed list. The first value, 4, identifies the message level to be logged; the second value, 0, is the lowest message severity to be logged. The third value, *SECLVL, specifies the amount of information to be logged (both first- and second-level messages). If a parameter's value is a mixed list, the elements of the list must be defined separately using an Element (ELEM) statement for each element.

The TYPE parameter on the associated PARM statement must have a label that refers to the first ELEM statement for the list.

         PARM    KWD(LOG)    TYPE(LOGLST) ...
 
LOGLST:  ELEM    TYPE(*INT2)      ...
         ELEM    TYPE(*INT2)      ...
         ELEM    TYPE(*CHAR)      LEN(7)

The first ELEM statement is the only ELEM statement that can have a label. Specify the ELEM statements in the order in which the elements occur in the list.

Note that when the MAX parameter has a value greater than 1 on the PARM statement, and the TYPE parameter refers to ELEM statements, the parameter being defined is a list within a list.

Parameters that you can specify on the ELEM statement include TYPE, LEN, CONSTANT, RSTD, DFT, VALUES, REL, RANGE, SPCVAL, SNGVAL, MIN, MAX, ALWUNPRT, ALWVAR, PGM, DTAARA, FILE, FULL, EXPR, VARY, PASSATR, CHOICE, CHOICEPGM, and PROMPT.

In the following example, a parameter CMPVAL is defined for which the display station user can specify a comparison value and a starting position for the comparison (a mixed list).

      PARM   KWD(CMPVAL) TYPE(CMP) SNGVAL(*ANY) DFT(*ANY) +
              MIN(0)
CMP:  ELEM   TYPE(*CHAR) LEN(80) MIN(1)
      ELEM   TYPE(*DEC) LEN(2 0) RANGE(1 80) DFT(1)

When the elements in a mixed list are passed to the command processing program, the format varies depending on whether you are using CL or HLL, or REXX. The following section describes how the elements used in the previous example are passed using CL and HLL. For an explanation of the differences when using REXX, see Using REXX for Mixed Lists.

Using CL or HLL for Mixed Lists

When a command is run using CL or HLL, the elements in a mixed list are passed to the command processing program in the following format:
When a command is run using CL or HLL, the elements in a mixed list are passed to the command processing program in the this format.

The number of values in the mixed list is passed as a binary value of length 2. This value always indicates how many values have been defined for the mixed list, not how many were actually entered on the command. This value may be 1 if the SNGVAL parameter is entered or is passed as the default value. If the user does not enter a value for an element, a default value is passed. The elements are passed by their types just as single parameter values are passed (as described under Defining Parameters). For example, if, in the previous example the user enters a comparison value of QCMDI for the CMPVAL parameter, but does not enter a value for the starting position, whose default value is 1, the following is passed.
Example of what is passed if, in the previous example the user enters a comparison value of QCMDI for the CMPVAL parameter, but does not enter a value for the starting position, whose default value is 1.

The data QCMDI is passed as an 80-character value that is left-adjusted and padded with blanks. The number of elements is sent as a binary value of length 2.

When the display station user enters a single value or when a single value is the default for a mixed list, the value is passed as the first element in the list. For example, if the display station user enters *ANY as a single value for the parameter, the following is passed.
The following is passed if the display station user enters *ANY as a single value for the parameter.

*ANY is passed as an 80-character value that is left-adjusted and padded with blanks.

Mixed lists can be processed in CL programs. Unlike simple lists, the binary value does not need to be tested to determine how many values are in the list because this value is always the same for a given mixed list unless the SNGVAL parameter was passed to the command processing program. In this case, the value is 1. If the command is entered with a single value for the parameter, only that one value is passed. To process the mixed list in a CL procedure, you must use the substring built-in function (see "CL Programming").

In one case, only a binary value of 0000 is passed as the number of values for a mixed list. If no default value is defined on the PARM statement for an optional parameter and the first value of the list is required (MIN(1)), then the parameter itself is not required; but if any element is specified the first element is required. In this case, if the command is entered without specifying a value for the parameter, the following is passed.
Example of what is passed if the command is entered without specifying a value for the parameter.

An example of such a parameter is:

      PARM  KWD(KWD1)    TYPE(E1) MIN(0)
E1:   ELEM  TYPE(*CHAR)  LEN(10)  MIN(1)
      ELEM  TYPE(*CHAR)  LEN(2)   MIN(0)

If this parameter were to be processed by a CL procedure, the parameter value could be received into a 14-character CL variable. The first 2 characters could be compared to either of the following:

Using REXX for Mixed Lists

When a command is run using REXX, the elements in a mixed list are passed to the command processing program in the following format:

 . . . CMPVAL(value1 value2  . . . valueN) . . .

where valueN is the last value in the mixed list.

If the user does not enter a value for an element, a default value is passed. For example, if in the previous example, the user enters a comparison value of QCMDI for the CMPVAL parameter, but does not enter a value for the starting position, whose default value is 1, the following is passed:

 . . . CMPVAL(QCMDI 1)  . . .

Note that trailing blanks are not passed with REXX values.

When a display station user enters a single value or when a single value is the default for a mixed list, the value is passed as the first element in the list. For example, if the display station user enters *ANY as a single value for the parameter, the following is passed:

 . . . CMPVAL(*ANY) . . .

Again note that trailing blanks are not passed with REXX values.

If no default value is defined on the PARM statement for an optional parameter and the first value of the list is required (MIN(1)), then the parameter itself is not required. But if any element is specified, the first element is required. In this case, if the command is entered without specifying a value for the parameter, the following is passed:

 . . . CMPVAL() . . .


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]