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.
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.
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.
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.
*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:
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
and the REXX/400 Reference
.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.