CL Programming

Defining a Simple List

A simple list can accept one or more values of the type specified by the parameter. For example, if the parameter is for the user name, a simple list means that more than one user name can be specified on that parameter.

USER(JONES SMITH MILLER)

If a parameter's value is a simple list, you specify the maximum number of elements the list can accept using the MAX parameter on the PARM statement. For a simple list, no command definition statements other than the PARM statement need be specified.

The following example defines a parameter USER for which the display station user can specify up to five user names (a simple list).

PARM     KWD(USER) TYPE(*NAME) LEN(10) MIN(0) MAX(5) +
         SPCVAL(*ALL) DFT(*ALL)

The parameter is an optional parameter as specified by MIN(0) and the default value is *ALL as specified by DFT(*ALL).

When the elements in a simple 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 Simple Lists.

Using CL or HLL for Simple Lists

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

The number of values passed is specified by a binary value that is two characters long. This number indicates how many values were actually entered (are being passed), not how many can be specified. The values are passed by the type of parameter just as a value of a single parameter is passed (as described under "Defining Parameters"). For example, if two user names (BJONES and TBROWN) are specified for the USER parameter, the following is passed.
If two user names (BJONES and TBROWN) are specified for the USER parameter this is passed.

The user names are passed as 10-character values that are left-adjusted and padded with blanks.

When a simple list is passed, only the number of elements specified on the command are passed. The storage immediately following the last element passed is not part of the list and must not be referred to as part of the list. Therefore, when the command processing program (CPP) processes a simple list, it uses the number of elements passed to determine how many elements can be processed.

Figure 9-1 shows an example of a CL procedure using the binary built-in function to process a simple list.

Figure 9-1. Simple List Example

        PGM PARM (...&USER..)
        .
        .
        .
        /* Declare space for a simple list of up to five */
        /* 10-character values to be received            */
        DCL VAR(&USER) TYPE(*CHAR) LEN(52)
        .
        DCL VAR(&CT)    TYPE(*DEC)  LEN(3 0)
        DCL VAR(&USER1) TYPE(*CHAR) LEN(10)
        DCL VAR(&USER2) TYPE(*CHAR) LEN(10)
        DCL VAR(&USER3) TYPE(*CHAR) LEN(10)
        DCL VAR(&USER4) TYPE(*CHAR) LEN(10)
        DCL VAR(&USER5) TYPE(*CHAR) LEN(10)
        .
        .
        .
        CHGVAR  VAR(&CT) VALUE(%BINARY(&USER 1 2))
        .
        IF (&CT > 0) THEN(CHGVAR &USER1 %SST(&USER 3 10))
        IF (&CT > 1) THEN(CHGVAR &USER2 %SST(&USER 13 10))
        IF (&CT > 2) THEN(CHGVAR &USER3 %SST(&USER 23 10))
        IF (&CT > 3) THEN(CHGVAR &USER4 %SST(&USER 33 10))
        IF (&CT > 4) THEN(CHGVAR &USER5 %SST(&USER 43 10))
        IF (&CT > 5) THEN(DO)
        /*  If CT is greater than 5, the values passed     */
        /*  is greater than the program expects, and error */
        /*  logic should be performed                      */
        .
        .
        .
        ENDDO
        ELSE DO
        /* The correct number of values are passed */
        /* and the program can continue processing */
        .
        .
        .
        ENDDO
        ENDPGM

This same technique can be used to process other lists in a CL procedure or program.

For a simple list, a single value such as *ALL or *NONE can be entered on the command instead of the list. Single values are passed as an individual value. Similarly, if no values are specified for a parameter, the default value, if any is defined, is passed as the only value in the list. For example, if the default value *ALL is used for the USER parameter, the following is passed.
In this example the following is passed when the default value *ALL is used for the USER parameter.

*ALL is passed as a 10-character value that is left-adjusted and padded with blanks.

If no default value is defined for an optional simple list parameter, the following is passed:
In this example the following is passed if no default value is defined for an optional simple list parameter.

Using REXX for Simple Lists

When the same command is run, the elements in a simple list are passed to the REXX procedure in the argument string in the following format:

 . . . USER(value1 value2  . . . valueN) . . .

where valueN is the last value in the simple list.

For example, if two user names (BJONES and TBROWN) are specified for the USER parameter, the following is passed:

 . . . USER(BJONES TBROWN) . . .

When a simple list is passed, only the number of elements specified on the command are passed. Therefore, when the CPP processes a simple list, it uses the number of elements passed to determine how many elements can be processed.

The REXX example in Figure 9-2 produces the same result as the CL procedure in Figure 9-1:

Figure 9-2. REXX Simple List Example

        .
        .
        .
        PARSE ARG . 'USER(' user ')' .
        .
        .
        CT = WORDS(user)
        IF CT > 0 THEN user1 = WORD(user,1) else user1 = '
        IF CT > 1 THEN user2 = WORD(user,2) else user2 = '
        IF CT > 2 THEN user3 = WORD(user,3) else user3 = '
        IF CT > 3 THEN user4 = WORD(user,4) else user4 = '
        IF CT > 4 THEN user5 = WORD(user,5) else user5 = '
        IF CT > 5 THEN
          DO
            /* If CT is greater than 5, the values passed
               is greater than the program expects, and error
               logic should be performed */
        .
        .
        .
          END
        ELSE
          DO
            /* The correct number of values are passed
               and the program can continue processing */
          END
        EXIT

This same procedure can be used to process other lists in a REXX program.

For a simple list, a single value such as *ALL or *NONE can be entered on the command instead of the list. Single values are passed as an individual value. Similarly, if no values are specified for a parameter, the default value, if any is defined, is passed as the only value in the list. For example, if the default value *ALL is used for the USER parameter, the following is passed:

 . . . USER(*ALL) . . .

If no default value is defined for an optional simple list parameter, the following is passed:

 . . . USER() . . .

For more information about REXX procedures, see the REXX/400 Programmer's Guide Link to PDF and the REXX/400 Reference Link to PDF.


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