10 Facts You Should Know about Special Values

Published: October 26, 2011

by Ted Holt

Imagine not being allowed to code *FIRST in the MBR parameter of the Override with Database File (OVRDBF) command. Horrible thought, isn't it? Special values make commands more sensible and easy to use. Here are 10 facts every IBM i developer should know in order to effectively use special values in his own commands.

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.

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot