Special Values Special in Command creation

1. Special values are character strings that are incompatible with validity checking rules. In this example, BATCH requires a three-digit number, and *ALL does not fit that description.

PARM KWD(BATCH) +
TYPE(*DEC) LEN(3 0) +
DFT(*ALL) +
REL(*GT 0) +
SPCVAL((*ALL -1)) +
PROMPT('Batch number')</all>

2. Special values make it easier for humans to communicate with computers. Here's a logical parameter that accepts *YES and *NO. These values make more sense to humans than 1 and 0.

PARM KWD(BLANKRECS) TYPE(*LGL) +
RSTD(*YES) +
DFT(*YES) +
SPCVAL((*YES '1') (*NO '0')) +
PROMPT('Write blank records?' 5)

3. IBM's standard is that special values begin with an asterisk, but this is not a system requirement. Here ALL is a special value.

PARM KWD(BATCH) +
TYPE(*DEC) LEN(3 0) +
DFT(ALL) +
REL(*GT 0) +
SPCVAL((ALL -1)) +
PROMPT('Batch number')
</all>

4. The data type and length of a data element match the underlying values, not the special values. BATCH is defined here as a three-digit decimal number with no decimal places, not as a four-byte character variable.

PARM KWD(BATCH) +
TYPE(*DEC) LEN(3 0) +
DFT(*ALL) +
REL(*GT 0) +
SPCVAL((*ALL -1)) +
PROMPT('Batch number') </all>

5. A special value may be passed as is, or replaced by a replacement value, when passed to the command-processing program (CPP). Here *MBR is passed to the CPP.

PARM KWD(WORKMBR) TYPE(*NAME) DFT(*MBR) +
SPCVAL((*MBR)) EXPR(*YES) PMTCTL(CHANGE) +
PROMPT('Member')

But here a blank and an asterisk replace *BLANK and *AST respectively.

PARM KWD(CURRENCY) TYPE(*CHAR) LEN(1) DFT(*BLANK) +
RANGE(X'41' X'FE') +
SPCVAL((*BLANK ' ') (*AST '*')) +
EXPR(*YES) PROMPT('Currency fill character')

6. If the replacement value of special value *CURLIB is the unquoted string *CURLIB, the name of the current library is passed to the command-processing program. Otherwise, the string *CURLIB is passed to the CPP. In this example, there is no replacement value, so the string *CURLIB will be passed to the CPP.

QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) +
SPCVAL((*LIBL) (*CURLIB)) +
EXPR(*YES) +
PROMPT('Library')

But here *CURLIB is replaced with the name of the current library.

QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) +
SPCVAL((*LIBL) (*CURLIB *CURLIB)) +
EXPR(*YES) +
PROMPT('Library')

If the job has no defined current library, QGPL is passed to the CPP.

7. You can ignore errors of severity 20 and below in the compiler listing, provided that the command processing program can properly handle the invalid substitution values. The following parameter definition generates three CPF0257 errors, because the three replacement values are not valid dates. However, because the CPP must define date fields as seven-byte character variables, the replacement values are appropriate ones.

PARM KWD(DATE) TYPE(*DATE) +
DFT(TODAY) +
SPCVAL((TODAY 2222222) (YESTERDAY 3333333) (TOMORROW 4444444)) +
EXPR(*YES) +
PROMPT('Cutoff date')

8. You may list up to 300 special values in the SPCVAL parameter. This PARM defines three special values.

PARM KWD(SPLNBR) TYPE(*INT4) +
DFT(*ONLY) +
RANGE(1 999999) +
SPCVAL((*ONLY 0) (*LAST -1) (*ANY -2)) +
EXPR(*YES) +
PROMPT('Spooled file number' 4)

9. Special values may be used in PARM, ELEM and QUAL statements. I've already shown several PARM examples, so here is an example of a qualified parameter that accepts special values.

PARM KWD(TEMPLATE) TYPE(FILE1) MIN(1) +
PROMPT('Template' 1)

FILE1: ELEM TYPE(QUALFILE1) MIN(1) PROMPT('File')
ELEM TYPE(*NAME) LEN(10) DFT(*FIRST) +
SPCVAL((*FIRST)) EXPR(*YES) PROMPT('Member')

QUALFILE1: QUAL TYPE(*NAME) LEN(10) MIN(1) EXPR(*YES)
QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) +
SPCVAL((*LIBL) (*CURLIB)) EXPR(*YES) +
PROMPT'Library')

10. Special values are not allowed when a parameter returns a value to the caller. (That is, the RTNVAL keyword has the value *YES.) This restriction is not a hardship, because it is hard to imagine a reason why a person would want to define input values for an output parameter.