Parameter Definition (PARM)

The Parameter (PARM) command definition statement defines a parameter of a command being created. A parameter is the means by which a value is passed to the command processing program. One PARM statement must be used for each parameter that appears in the command being defined. The order in which the PARM statements are entered into the source file determines the order in which the parameters must be specified when the command is entered in positional form and the order in which they are passed to the validity checker and the command processing program. A maximum of 99 parameters can be defined for one command. A command with a large number of parameters will require more processing time before the command processing program is called, regardless of how many parameters are actually coded.

Note: The PARM statement contains certain parameters and predefined values that can be used only when IBM-supplied command processing programs are called by the command being defined. Because of limitations in some high-level languages, these values may not be useful in the definition statements of user-defined commands. These parameters and values are identified by the phrase (For IBM-supplied commands) that immediately follows the parameter keyword (if the entire parameter is for IBM-supplied commands only) or the predefined value to which it applies.

Parameters

Keyword Description Choices Notes
KWD Keyword Simple name Required, Positional 1
TYPE Type of value Simple name, *DEC, *LGL, *CHAR, *INT2, *INT4, *NAME, *GENERIC, *VARNAME, *DATE, *TIME, *CMD, *X, *HEX, *ZEROELEM, *NULL, *CMDSTR, *PNAME, *UINT2, *UINT4, *SNAME, *CNAME Required, Positional 2
LEN Value length Values (up to 3 repetitions): Integer Optional, Positional 3
RTNVAL Return value *NO, *YES Optional
CONSTANT Constant value Character value Optional
RSTD Restricted values *NO, *YES Optional
DFT Default value Character value Optional
VALUES Valid values Values (up to 300 repetitions): Character value Optional
REL Relational expression Element list Optional
Element 1: Relational operator *GT, *EQ, *GE, *NL, *LT, *NE, *LE, *NG
Element 2: Value or keyword reference Character value
RANGE Range of values Element list Optional
Element 1: Lower value or keyword ref Character value
Element 2: Upper value or keyword ref Character value
SPCVAL Special values Values (up to 300 repetitions): Element list Optional
Element 1: From value Character value
Element 2: To replacement value Character value
SNGVAL Single values Values (up to 300 repetitions): Element list Optional
Element 1: From value Character value
Element 2: To replacement value Character value
MIN Minimum values required 0-300, 0 Optional
MAX Maximum values allowed Integer, 1 Optional
ALWUNPRT Allow unprintable characters *YES, *NO Optional
ALWVAR Allow variable names *YES, *NO Optional
PGM Is PARM a program name *NO, *YES Optional
DTAARA Is PARM a data area name *NO, *YES Optional
FILE If a file parameter, how used *NO, *IN, *OUT, *UPD, *INOUT, *UNSPFD Optional
FULL Full field required *NO, *YES Optional
EXPR Value an expression *NO, *YES Optional
VARY Varying length Single values: *NO
Other values: Element list		 Optional
Element 1: Return length value *YES
Element 2: Value length *INT2, *INT4
PASSATR Pass attribute byte *NO, *YES Optional
PASSVAL Value to pass if unspecified *DFT, *NULL Optional
CASE Case of value *MONO, *MIXED Optional
CCSID CCSID of value *JOB, *UTF16 Optional
LISTDSPL List displacement *INT2, *INT4 Optional
DSPINPUT Display input *YES, *PROMPT, *NO Optional
CHOICE Choice text Character value, *VALUES, *NONE, *PGM Optional
CHOICEPGM Choice program Single values: *NONE
Other values: Qualified object name		 Optional
Qualifier 1: Choice program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
PMTCTL Prompt control Simple name, *NONE, *PMTRQS Optional
PMTCTLPGM Prompt control program Single values: *NONE
Other values: Qualified object name		 Optional
Qualifier 1: Prompt control program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
KEYPARM Key parameter *NO, *YES Optional
INLPMTLEN Initial prompt length *CALC, *PWD, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 17, 25, 32, 50, 80, 132, 256, 512 Optional
PROMPT Prompt specifications Single values: *NONE
Other values: Element list		 Optional
Element 1: Prompt text or message ID Character value
Element 2: Order prompt is displayed Integer

Keyword (KWD)

Specifies the keyword name of the parameter being defined. Every CL command parameter has an associated keyword name. Command parameters specified using the parameter keyword can be specified in any order. Parameters may be specified in positional form (without a keyword name) up to the positional limit specified by the MAXPOS parameter on the Create Command (CRTCMD) command.

simple-name
Specify a keyword name for the parameter. The name can be up to ten alphanumeric characters. The first character must be alphabetic.

Type of value (TYPE)

Specifies the type of the value that can be specified for the parameter named in Keyword (KWD). The value can be an integer, a decimal, hexadecimal, or logical value, or a character string (optionally enclosed in apostrophes) that can be a name, date, or time. The value can also be a command. Type one of the following options to specify the parameter type:

*DEC
The parameter value is a packed decimal number.
*LGL
The parameter value is a logical value of one ('1') or zero ('0').
*CHAR
The parameter value is a character string that can optionally be enclosed in apostrophes. If the character string contains any special characters (not including an asterisk (*)), it must be enclosed in apostrophes. The maximum length of the character string is 5000 bytes if *JOB is specified for the CCSID parameter, or 10000 bytes if *UTF16 is specified for the CCSID parameter.
*NAME
The parameter value is a character string that represents a name. The maximum length of the name is 256 bytes. The first character must be alphabetic or one of the special characters, $, @, or #. The remaining characters can be alphanumeric, a period, an underscore, or one of special characters, $, @, or #. The name can also be a string of characters starting and ending with double quotation marks (") or enclosed in parentheses. If a special value is used (as in *LIBL or *NONE), it should be specified on the Special values (SPCVAL) parameter.
*SNAME
The parameter value is a character string that represents a name. The maximum length of the name is 256 bytes. The first character must be alphabetic or one of the special characters $, @, or #. The remaining characters can be alphanumeric, an underscore, or one of the special characters $, @, or #). The character string can be enclosed in parentheses. If a special value is used (as in *LIBL or *NONE), it must be specified on the SPCVAL parameter.
*CNAME
The parameter value is a character string that represents a name. The maximum length of the name is 256 bytes. The first character must be alphabetic or one of the special characters, $, @, or #. The remaining characters can be alphanumeric or one of special characters, $, @, or #. The character string can be enclosed in parentheses. If a special value is used (as in *LIBL or *NONE), it must be specified on the SPCVAL parameter.
*PNAME
The parameter value is a character string that represents a path name string. Optionally the path name string may be enclosed in apostrophes. If the path name string contains any special characters (not including an asterisk (*)), it must be enclosed in apostrophes. The maximum length of the path name string is 5000 bytes if *JOB is specified for the CCSID parameter, or 10000 bytes if *UTF16 is specified for the CCSID parameter.
*GENERIC
The parameter value is a character string that represents a generic name. A generic name contains one or more characters followed by an asterisk (*) and must conform to the rules for generic names. The name identifies a group of objects whose names all begin with the characters preceding the asterisk (*). If an asterisk (*) is not included, the system assumes that the generic name is a complete object name.
*CMDSTR
The parameter value is a command that will be checked for validity by the system. It is passed to the command processing program as a command string.

The command analyzer rebuilds the command string when it checks it for validity. When the command is rebuilt, keywords are added to parameters that were specified positionally, parameters can be reordered, and parameters that contain characters that cannot be printed (X'FF' and X'00 - X'3F') are converted to hexadecimal notation. As a result, the rebuilt command string may be substantially longer than the original command string. If the length of the rebuilt command is longer than the allowed length specified with the LEN keyword, the command will fail.

Note: Selective prompting is not allowed with the *CMDSTR parameter.

*DATE
The parameter value is a character string that represents a date. When entering the command, the year may be specified with either 2 digits or 4 digits. If a 2-digit year is specified, the date is assumed to be in the range of January 1, 1940 through December 31, 2039. If a 4-digit year is specified, the date may be in the range of August 24, 1928 through May 9, 2071. When it is passed to the command processing program, it is always passed in the format Cyymmdd, where C = century, yy = year, mm = month, and dd = day. The century digit is set to 0 (zero) for years 19xx, and it is set to 1 (one) for years 20xx. When a date value is specified in this PARM statement, it must be specified in one of the following formats mmddyy, mmddyyyy, or Cyymmdd. When a user types a date in the command at run time, it must be specified in the job-date format. The job date separator may be used when the date is entered. If the separator character is used, the date must be enclosed in apostrophes.
*TIME
The parameter value is a character string that represents a time. It is passed to the command processing program in a 6-byte character string as hhmmss., where hh = hours, mm = minutes, and ss = seconds. Values specified in this statement must be in the format hhmmss When a user types a time in the command at run time, it must be specified in the format hhmmss. The job time separator may be used when the time is entered. If the separator character is used, the time must be enclosed in apostrophes.
*HEX
The parameter value is hexadecimal in form. The specified characters must be 0 through F. They are converted to hexadecimal (EBCDIC) characters (2 hex digits per byte), right-justified, and padded on the left with zeros. If the value is enclosed in apostrophes, an even number of digits is required. If the value is not enclosed in apostrophes, an even number of digits is not required.
*ZEROELEM
The parameter is always considered as a list of zero elements, for which no value can be specified in the command. It is used to prevent a value from being entered for a parameter that is a list even though the command processing program expects one. For example, if two commands use the same command processing program, one command could pass a list for a parameter and the other command may not have any values to pass. The second command would be coded with *ZEROELEM specified for this parameter.
*X
(For IBM-supplied commands) The parameter value is a character string, variable name, or numeric value. The value is passed as a numeric value if it contains only digits, a + or - sign, or a decimal point; otherwise, it is passed as a character string.
*INT2
The parameter value is an integer that is passed as a 2-byte signed binary number.
*INT4
The parameter value is an integer that is passed as a 4-byte signed binary number.
*UINT2
The parameter value is an integer that is passed as a 2-byte unsigned binary number.
*UINT4
The parameter value is an integer that is passed as a 4-byte unsigned binary number.
*VARNAME
(For IBM-supplied commands) The parameter value is a CL variable name that is passed as a character string.
*CMD
(For IBM-supplied commands) The parameter value is a command. For example, the IF command has a parameter called THEN whose value must be another command. The command is checked for validity by the system.
*NULL
The parameter value is a null pointer, which can be used as a constant place-holder. A DEP statement or the REL and RANGE keywords of other PARM statements may not refer to the value of a parameter defined with *NULL specified for this parameter.
statement-label
Specify a qualified name or a mixed list of values. The statement label specified here is the statement label that identifies the first of a series of QUAL or ELEM statements that further describe the qualified name or the mixed list being defined by this PARM statement.

Value length (LEN)

Specifies the length of the parameter value that is passed to the command processing program (CPP). Depending on the value specified for the Type of value (TYPE) parameter, the LEN parameter may allow up to three length values to be specified.

If the LEN parameter is allowed but not specified, a default length will be used based on the value specified for the TYPE parameter. The following table shows the default length value for each TYPE and the maximum value that can be specified for the LEN parameter. 

------------------------------------------------
| TYPE       | Default Length | Maximum Length |
|------------|----------------|----------------|
| *DEC       | (15  5)        | (24  9)        |
|------------|----------------|----------------|
| *LGL       | 1              | 1              |
|------------|----------------|----------------|
| *CHAR      | 32             | 5000           |
|------------|----------------|----------------|
| *NAME      | 10             | 256            |
|------------|----------------|----------------|
| *GENERIC   | 10             | 256            |
|------------|----------------|----------------|
| *SNAME     | 10             | 256            |
|------------|----------------|----------------|
| *CNAME     | 10             | 256            |
|------------|----------------|----------------|
| *PNAME     | 32             | 5000           |
|------------|----------------|----------------|
| *HEX       | 1              | 256            |
|------------|----------------|----------------|
| *X         | (1  15  5)     | (256  24  9)   |
|------------|----------------|----------------|
| *VARNAME   | 11             | 11             |
|------------|----------------|----------------|
| *CMDSTR    | 256            | 20000          |
------------------------------------------------

Return value (RTNVAL)

Specifies whether a value is returned by the command processing program through the parameter being defined in this PARM statement.

*NO
No value can be returned in the parameter being defined. The parameter is an input parameter only.
*YES
A value is to be returned by the command processing program in the parameter. A CL variable name must be specified (on the CALL command) to receive the value. *YES is valid only if *DEC, *CHAR, *LGL, *INT2, *INT4, *UINT2, *UINT4, or *X is specified for the Type of value (TYPE) parameter. Also, *YES is valid only on commands that are limited to CL programs. That is, if either *BPGM or *IPGM is specified in the Create Command (CRTCMD) command that uses the source file containing this PARM statement, *YES can be specified here. *YES must be specified on the Varying length (VARY) parameter, if *YES is specified here and on the Pass attribute byte (PASSATR) parameter. If *NO is specified for the Allow variable names (ALWVAR) parameter, or if the Maximum values allowed (MAX) parameter has a value of greater than 1, *YES is not valid. *YES is also not valid with the following parameters:
  • Constant value (CONSTANT parameter)
  • Default value (DFT parameter)
  • Restricted values (RSTD parameter)
  • Valid values (VALUES parameter)
  • Relational expression (REL parameter)
  • Range of values (RANGE parameter)
  • Special values (SPCVAL parameter)
  • Single values (SNGVAL parameter)
  • If a file parameter, how used (FILE parameter)
  • Full field required (FULL parameter)
  • Value an expression (EXPR parameter)
  • CCSID of value (CCSID parameter)

Constant value (CONSTANT)

Specifies that a value is passed to the command processing program as a constant when the command being defined is processed; the parameter does not appear externally on the command. The value specified in this parameter (if any) must satisfy the requirements specified by the following parameters:

If a character constant is specified in this parameter, it can be no longer than 32 bytes.

If a constant is specified for the parameter being defined, no prompt text can be specified for the Prompt specifications (PROMPT) parameter because the parameter will not be prompted.

This parameter is not valid for the following:

Variables cannot be coded for this parameter.

Restricted values (RSTD)

Specifies whether the value entered for the parameter (specified in the PARM statement) is restricted to only one of the values given in the Valid values (VALUES) parameter, the Special values (SPCVAL) parameter, or the Single values (SNGVAL) parameter, or whether the value can be any value that satisfies the requirements specified by the following parameters:

*NO
The value entered for the parameter specified by the Keyword (KWD) parameter can be anything that matches the requirement specified by the following parameters in this PARM statement:
  • Type of value (TYPE parameter)
  • Value length (LEN parameter)
  • Relational expression (REL parameter)
  • Range of values (RANGE parameter)
  • Special values (SPCVAL parameter)
  • Single values (SNGVAL parameter)
  • Full field required (FULL parameter)
*YES
The value entered for the parameter specified by KWD in this PARM statement is restricted to one of the values in the Valid values (VALUES) parameter, or to one of the from-values in either the Special values (SPCVAL) parameter or the Single values (SNGVAL) parameter. *YES cannot be specified if a statement label, *CMD, *NULL, or *ZEROELEM is specified for the Type of value (TYPE) parameter, or if *YES is specified for the Return value (RTNVAL) parameter.

Default value (DFT)

Specifies the default value that is assigned to the parameter if a value is not specified by the user. That is, the default value is used as the value of the parameter if the user omits the parameter while entering the command or if the user specifies *N as the parameter value. The default value must satisfy one of the following:

This parameter is not valid if the Constant value (CONSTANT) parameter is specified. This parameter is valid only if 0 is specified for the Minimum values required (MIN) parameter, which means the parameter named in the Keyword (KWD) parameter is optional. No default can be specified if RTNVAL(*YES) is specified on the Return value (RTNVAL) parameter; instead, a null pointer is passed for the default. A default cannot be specified if *CMD, *ZEROELEM, or *NULL is specified on the Type of value (TYPE) parameter. If *VARNAME is specified on the Type of value (TYPE) parameter, a default special value can be specified; a default variable name cannot be specified.

An assumed default value is not displayed by the command prompt; a blank input field is shown instead. If a default is specified, it is displayed by the prompt exactly as specified.

value
Specify the default value that meets the specified requirements or that is one of the values specified in the Valid values (VALUES) parameter, the Special values (SPCVAL) parameter, or the Single values (SNGVAL) parameter.

Variables cannot be coded for this value.

Valid values (VALUES)

Specifies a list of up to 300 constants (fixed values) from which one constant can be entered as the value of the parameter named on the Keyword (KWD) parameter. This parameter is valid only if all of the following are true:

Character constants specified in this parameter can be no longer than 32 bytes. Type the constants (not more than 300) that can be specified as the value of the parameter. This parameter is not valid if *CMD, *CMDSTR, *X, *NULL, statement label, *VARNAME, or *ZEROELEM is specified on the Type of value (TYPE) parameter, or if *YES is specified on the Return value (RTNVAL) parameter.

Relational expression (REL)

Specifies the relationship between the parameter value of this parameter and the value of a constant or another parameter. If a keyword is specified, it must be preceded by an ampersand (&) to indicate that it is the value of the keyword that is to be tested. The value associated with the referred to keyword is the value passed to the command processing program, not the user-specified value. If the relationship is with another parameter whose value is a list of values or a qualified name, the first value only is used in the comparison.

To specify the relationship, enter one of the following relational operators followed by either a constant or the keyword name of the other parameter (which must be preceded by an &).

*LT
less than
*LE
less than or equal to
*EQ
equal to
*GE
greater than or equal to
*GT
greater than
*NL
not less than
*NE
not equal to
*NG
not greater than

The REL parameter is not valid in the following cases:

If a *CHAR (character type) is specified on the Type of value (TYPE) parameter, the EBCDIC value of the character string is used as an unsigned integer in the comparison. If a character constant is specified in this parameter, it can be no longer than 32 bytes.

Variables can be coded for this element.

Range of values (RANGE)

Specifies the range, or limits, for the parameter value. The parameter value must be greater than or equal to the lower limit value specified, and it must be less than or equal to the upper limit value specified. For example, 15 would be valid if RANGE was specified as (0 16).

For nonnumeric data types, such as character, the range of values and the data specified are right-justified and padded on the left with blanks. A numeric range should not be used to define an interval for nonnumeric data unless leading zeros are specified or the data is only 1 character in length.

Variables can be coded for this element.

The upper and lower limits of the range can be specified either by a keyword representing the value or by the value itself. If a keyword is specified, it must be preceded by an ampersand (&) to indicate that the value of the keyword is to be tested. The value of its parameter at the time of the check is used to determine the range. The value that is tested is the value passed to the command processing program, not the user-specified value. If the keyword identifies a list of values or a qualified name, only the first value is used as the range limit. A keyword may not refer to a parameter that is defined with *NULL specified on the Value to pass if unspecified (PASSVAL) parameter. This parameter is not valid with *NULL specified on the Value to pass if unspecified (PASSVAL) parameter.

This parameter is also not valid in the following cases:

Character constants specified in this parameter can be no longer than 32 bytes.

Variables can be coded for this element.

Special values (SPCVAL)

Specifies a list of up to 300 entries that define special values that can be entered on the parameter. Each entry specifies a character string (a from-value) that can be entered even though it may not meet all validity checking requirements. If the entered character string matches the from-value of one of the entries, and the to-value is specified, the string is replaced with the to-value and is then passed to the command processing program (CPP) without further checking. If the to-value is omitted, the from-value is passed to the CPP. This parameter is not valid if *YES is specified on the Return value (RTNVAL) parameter, or if *CMD, *CMDSTR, *X, *ZEROELEM, *NULL, or a statement label is specified for the Type of value (TYPE) parameter.

The from-value is a character string, but the to-value can be anything that is passable. However, for TYPE(*DATE) the to-value must be specified not quoted in the mmddyy, mmddyyyy, or the Cyymmdd format. If a CL variable is used for the from-value, its type must be *CHAR. The to-value must be no longer than specified on the Value length (LEN) parameter, and, if *DEC, *INT2, *INT4, *UINT2 or *UINT4 is specified for the Type of value (TYPE) parameter, the type of the to-value must be the same. If the Type of value (TYPE) parameter is a character type (such as *CHAR, *LGL or *DATE), the to-value must be a character string. Character constants specified in this parameter can be no longer than 32 bytes. If a to-value is not specified, the from-value must be passable.

If a to-value of *CURLIB is specified, the name of the current library, rather than the value *CURLIB, is passed to the CPP. If the from-value is *CURLIB and no to-value is specified, or if the to-value is *CURLIB and it is enclosed in apostrophes, the value *CURLIB is passed to the CPP.

Variables cannot be coded for this element.

Single values (SNGVAL)

Specifies a list of up to 300 single values that can be specified for a parameter being defined as a mixed list or as a qualified name, when a statement label is specified for the Type of value (TYPE) parameter, or specifies that it is to accept two or more values as defined by the Maximum values allowed (MAX) parameter. Any one of the single values can be entered instead of a list of values or a qualified name that the parameter is defined to accept. Each entry specifies a character string (a from-value) that can be entered. If an entered character string matches the from-value of one of the entries and the to-value is specified, the data is replaced with the to-value and is then passed to the command processing program without further checking. If the to-value is omitted, the from-value is passed to the command processing program.

The to-value (or the from-value, if the to-value is omitted) must be passable, as specified in the Special values (SPCVAL) parameter. Character constants specified in this parameter can be no longer than 32 bytes. This parameter can be specified only if the Maximum values allowed (MAX) parameter is greater than 1 or if TYPE is specified as a statement label of a QUAL or ELEM statement. Each single value can only be substituted for a list of values or a qualified name; it cannot be a list item or qualifier. It is passed as the first and only element of the list.

This parameter is not valid if *YES is specified on the Return value (RTNVAL) parameter, or if *CMD, *CMDSTR, *X, *ZEROELEM, *NULL, or a statement label is specified for the Type of value (TYPE) parameter.

If a to-value of *CURLIB is specified, the name of the current library, rather than the value *CURLIB, is passed to the command processing program. If the from-value is *CURLIB and no to-value is specified, or if the to-value is *CURLIB and it is enclosed in apostrophes, the value *CURLIB is passed to the command processing program.

Variables cannot be coded for this element.

Minimum values required (MIN)

Specifies the minimum number of values that must be entered for the parameter being defined. For a parameter that does not allow multiple like values, only zero (0) for optional and 1 for required can be specified as the minimum number of values.

Note: Required parameter statements must precede optional statements. If required parameter statements are not specified first, the system assumes that the specified parameter is optional, and the minimum number of values for required parameters is ignored.

For a parameter that allows multiple like values, because a value greater than 1 is specified for the Maximum values allowed (MAX) parameter, zero (0) indicates that no values need be entered; therefore, it is an optional parameter. A value of 1 or greater than 1 indicates the minimum number of values that must be entered for the parameter, and, therefore, it is a required parameter. The value cannot exceed 1 if *NULL is specified for the Type of value (TYPE) parameter.

0
The parameter is optional; it does not have to be entered.
minimum-number
Specify the minimum number of elements that must be specified for this parameter. If 1 is the assigned value, it specifies that at least one value is required for the parameter. If a number greater than 1 is specified, the parameter is a list that must have at least as many elements as the number specified.

Maximum values allowed (MAX)

Specifies, if this PARM statement is defining a simple list parameter, the maximum number of list items that this list parameter can contain. If a value greater than 1 is specified, the parameter is capable of accepting multiple like values (that is, a simple list). This support is primarily intended for IBM-supplied commands. All values entered for this parameter (at the time the command is run) must satisfy the validity checking requirements specified by the other parameter values on this PARM statement.

Note: The values for a list parameter are passed consecutively, preceded by a 2-byte binary value that indicates the number of values entered in the parameter by the user. CL programs do not support the handling of binary values in variables.

1
The parameter accepts only one value; the parameter is not a list parameter.
maximum-number
Specify the maximum number of elements that the list parameter can accept. The specified maximum must be greater than or equal to the value specified in the Minimum values required (MIN) parameter, and less than or equal to 300. If the maximum is greater than 1 and a statement label that identifies a QUAL or ELEM statement is not specified for the Type of value (TYPE) parameter, the parameter is a simple list of like elements (that is, each element in the list has the same requirements, such as type and length). If a statement label is specified and it points to the label of an ELEM or QUAL statement, a number greater than 1 should only be specified for this parameter if a list of lists or a list of qualified names is accepted. A maximum greater than 1 is not valid if *CMD, *CMDSTR, or *NULL is specified for the Type of value (TYPE) parameter, or if *YES is specified for the Return value (RTNVAL) parameter, or if the Constant value (CONSTANT) parameter is specified.

Allow unprintable characters (ALWUNPRT)

Specifies whether this parameter will accept the hexadecimal character X'FF' or those hexadecimal characters in the range of X'00' through X'3F'. This parameter is valid only if *CHAR or *X is specified for the Type of value (TYPE) parameter.

*YES
Characters can be passed to the command processing program and sent to the display or printer.
*NO
Unprintable characters cannot be passed to the command processing program.

Allow variable names (ALWVAR)

Specifies whether to allow variable names for the parameter. *NO is not allowed on this parameter if *VARNAME, *ZEROELEM, *NULL, or a statement label is specified on the Type of value (TYPE) parameter.

*YES
Variable names can be used for the parameter.
*NO
Variable names cannot be used for the parameter.

Is PARM a program name (PGM)

Specifies whether this parameter element is a program name. *YES is valid only if a statement label, *CHAR, *NAME, *SNAME, *CNAME, or *GENERIC is specified for the Type of value (TYPE) parameter. Specifying *YES here does not have any effect on the parameter element being defined by the PARM statement; it only indicates to the compiler that the value for this parameter is a program name. This information is stored so that it can be included in the output of the Display Program References (DSPPGMREF) command.

*NO
The parameter defined in this PARM statement is not a program name.
*YES
The parameter defined in this PARM statement is a program name.

Is PARM a data area name (DTAARA)

Specifies whether the parameter is a data area name. *YES is valid only if a statement label, *CHAR, *NAME, *SNAME, *CNAME, or *GENERIC is specified for the Type of value (TYPE) parameter. Specifying *YES here does not have any effect on the parameter being defined by the PARM statement; it only indicates to the compiler that the value for this parameter is a data area. This information is stored so that it can be included in the output of the Display Program References (DSPPGMREF) command.

*NO
The parameter defined in this PARM statement is not a data area name.
*YES
The parameter defined in this PARM statement is a data area name.

If a file parameter, how used (FILE)

Specifies the expected use of the file and whether the parameter is a file name. The parameter can be specified as the name of a file that has a specific use so that, at compile time, the names can be used to get file reference information about where the files are used. The specification in this parameter does not have any effect on the operation of the parameter being defined; it only indicates to the compiler that the value for this parameter is a file name and what type of file it is. This information is stored so it can be included in the output of the Display Program References (DSPPGMREF) command. This parameter is valid only if a statement label, *CHAR, *NAME, *SNAME, *CNAME, or *GENERIC is specified for the Type of value (TYPE) parameter. It is not valid if *YES is specified on the Return value (RTNVAL) parameter.

*NO
The parameter is not a file name.
*IN
The parameter value is an input file name.
*OUT
The parameter value is an output file name.
*UPD
The parameter value is an update file name.
*INOUT
The parameter value is the name of a file that is used for both input and output.
*UNSPFD
The parameter value is the name of a file, but its use cannot be specified.

The use of the file must match the type of file specified. For example, if *IN is specified, the file can be used only for input; if *UPD is specified, it can be used only to update existing records.

Full field required (FULL)

Specifies whether the number of bytes in the parameter value must be exactly the same as the number specified on the Value length (LEN) parameter (if specified) or its default length (if LEN is not specified).

*NO
The number of bytes in the parameter value can be less than that specified by the LEN parameter.
*YES
The number of bytes in the parameter value must equal the number specified by LEN or the default length for that type. The exact length is valid only if *LGL, *CHAR, *NAME, *SNAME, *CNAME, *PNAME, *GENERIC, *VARNAME, or *HEX is specified for the Type of value (TYPE) parameter. Specifying *YES here is valid with *YES specified on the Return value (RTNVAL) parameter.

Value an expression (EXPR)

Specifies whether the parameter named in the KWD parameter can accept an expression containing a character concatenation or a built-in function (%SUBSTRING or %BIN).

Restrictions: Expressions are not allowed on parameters where *CMD, *ZEROELEM, *NULL, or a statement label is specified for the Type of value (TYPE) parameter.

*NO
The parameter value cannot be a concatenation expression or a built-in function.
*YES
The parameter value can be a concatenation expression or a built in function.

Varying length (VARY)

Specifies whether the parameter value that is passed to the command processing program is preceded by a length value that indicates the number of bytes entered for the command parameter.

Note: The length value is the actual number of bytes entered for the command parameter, with trailing blanks removed. The length value passed may be different than the defined parameter length or the declared variable length. The length of the field containing the character string data is determined by the defined length for the parameter or the declared LEN for CL program variables. The length value defines how many bytes were actually entered for the command parameter. If *PNAME or *CHAR is specified for the TYPE parameter and *UTF16 is specified for the CCSID of value (CCSID) parameter, the length value passed to the command processing program represents the number of bytes for the parameter value. This could be up to twice the number specified for the Value length (LEN) parameter because the parameter value will be converted to UTF16 format and most UTF16 characters require two bytes. See the description of the CCSID and LEN parameters for more information related to handling values in UTF16 format.

Single values

*NO
The parameter value is not preceded by a length value.

Element 1: Return length value

*YES
The parameter value passed to the CPP is preceded by a field that indicates the number of bytes actually specified for the parameter. *YES is valid only for the following parameter types: *CHAR, *NAME, *SNAME, *CNAME, *PNAME, *GENERIC, *LGL, *VARNAME, *CMD, *CMDSTR, and *X. *YES must be specified if PASSATR(*YES) and RTNVAL(*YES) are specified.

Element 2: Value length

*INT2
The parameter length value is an integer passed as a 2-byte signed binary number.
*INT4
The parameter length value is an integer passed as a 4-byte signed binary number.

Pass attribute byte (PASSATR)

Specifies whether an attribute byte is passed to the command processing program with the parameter data.

The attribute byte precedes the parameter data. If the parameter allows multiple values to be specified, an attribute byte precedes each value.

*NO
An attribute byte is not passed with the parameter.
*YES
An attribute byte is passed with the parameter.

The attribute byte has two fields:

  1. The leftmost bit of the attribute byte indicates whether or not a value was specified. If the leftmost bit is '0'B, the value passed to the command processing program is a default value and was not specified in the command string. If the leftmost bit is '1'B, the value passed to the command processing program was specified in the command string.
  2. The remaining seven bits describe the value passed to the command processing program when *CHAR is specified for the Type of value (TYPE) parameter. 

    Attribute    Description
----------   --------------------------------------
'0000010'B   Meets *NAME rules, like A_B
'0000100'B   Meets *GENERIC rules, like AB*
'1000101'B   Quoted character string, like 'A B'
'0000101'B   Unquoted character string, like 5A
'1001000'B   Logical constant, '0' or '1'
'0001100'B   Hexadecimal value, like X'C1C2'
'0100001'B   Unsigned numeric value, like 5
'0101001'B   Unsigned numeric with decimal point,
             like 5.2
'0110001'B   Signed numeric value, like -5
'0111001'B   Signed numeric with decimal point,
             like -5.2

Value to pass if unspecified (PASSVAL)

Specifies whether a value is passed to the command processing program for this parameter. *NULL is not valid if the parameter is a constant parameter (a parameter in which a value has been specified for the Constant value (CONSTANT) parameter, or a parameter for which *ZEROELEM or *NULL has been specified for the Type of value (TYPE) parameter, or a list/qualified name defined by all constant ELEM or QUAL statements). *NULL also is not valid if *YES has been specified on the Return value (RTNVAL) parameter, or if the value specified for the Minimum values required (MIN) parameter is greater than zero. A DEP statement or the REL and RANGE keywords of other PARM statements may not refer to the value of a parameter defined with *NULL.

*DFT
The default value is always passed to the command processing program.
*NULL
A null pointer is passed to the command processing program if the parameter is not specified.

Case of value (CASE)

Specifies whether the value that is passed to the CPP is changed from lowercase to uppercase, or is preserved in the case specified on for the command parameter.

*MONO
The parameter value is changed from lowercase to uppercase. Parameters enclosed with apostrophes preserve the case whether or not this value is specified.
*MIXED
The parameter value is preserved in the case specified on the command parameter. This value can be specified only on *CHAR and *PNAME parameter types.

CCSID of value (CCSID)

Specifies the coded character set identifier (CCSID) to use when passing the parameter value to the command processing program.

Note: If the command string is run in batch using the Start Database Reader (STRDBRDR) or Submit Database Jobs (SBMDBJOB) command from a source file created with a CCSID of 1208 (UTF8) or was compiled from a CL source file created with a CCSID of 1208 or is being run using the QCAPCMD API and specifies that the CCSID of the command is either 1200 (UTF16) or 1208, the command string is assumed to be in Unicode format.

*JOB
If the command string is in Unicode format, the value for this parameter will be converted to the job CCSID before it is passed to the command processing program. Otherwise, the command string is assumed to already be in the CCSID of the job and no conversion is done for this parameter.
*UTF16
The parameter value will be passed as a UTF16 string to the command processing program (CPP). UTF16 is a Unicode format which is the same as CCSID 1200. In UTF16 format, most characters require two bytes (16 bits). If the command string is in a supported Unicode CCSID (1208 or 1200), little or no conversion of the parameter value will be performed. Otherwise, the command string is assumed to already be in the CCSID of the job, and the parameter value will be converted from the CCSID of the job to CCSID 1200 (UTF16).

If the parameter is optional and no value is specified in the command string, the defined default value will be converted to UTF16 format before it is passed to the CPP. If the parameter is a constant, the defined constant value will be converted to UTF16 format before it is passed to the CPP. If the parameter value is specified as a hexadecimal literal in the command string, the hexadecimal string is first converted to a character string using the CCSID of the job and the resulting character string is converted to UTF16 format before it is passed to the CPP.

*UTF16 is only allowed if *CHAR or *PNAME was specified for TYPE.

See the description of the Value length (LEN) parameter and Varying length (VARY) parameter for more information related to handling values in UTF16 format.

List displacement (LISTDSPL)

Specifies whether the displacement to a list within a list is 2-bytes or 4-bytes long. These displacements are generated when a parameter being passed to a CPP has a list within a list. This parameter is ignored if the value being built for the CPP does not contain a list within a list.

*INT2
The displacement value is an integer passed as a 2-byte signed binary number.
*INT4
The displacement value is an integer passed as a 4-byte signed binary number.

Display input (DSPINPUT)

Specifies whether the keyword value is shown in the job log or in a prompt display.

Note: The DSPINPUT parameter has no effect on the job log entries for a database reader job, for imbedded commands (for example, a command submitted on the SBMJOB command), or for commands run using the QCAPCMD, QCMDEXC or QCAEXEC APIs.

*YES
The default response, *YES, indicates that the parameter value is shown on the prompt display and in the job log.
*PROMPT
The response *PROMPT indicates that the parameter value is shown on the prompt display but not in the job log.
*NO
The response *NO indicates that the value is not shown on either the prompt display or in the job log.

Choice text (CHOICE)

Specifies the choices text that is displayed to the right of the input field on the prompt screen. Up to 30 characters of text can be displayed.

*VALUES
The choices text is generated based on the values specified for the TYPE, RSTD, RANGE, SNGVAL, SPCVAL, and VALUES parameters. If constants are specified for the RANGE parameter, the choices text begins with the minimum value and the maximum value separated by a hyphen. If RANGE is not specified with constants as the minimum and maximum values, and RSTD(*NO) is specified, the choices text begins with a short description of the parameter type based on the value specified for the TYPE parameter. Values specified for the SNGVAL parameter are added to the choices text, in the order the values are defined in the command definition source and separated by a comma and a blank. The last entries added to the choices text are values specified for the SPCVAL or VALUES parameter, in the order the values are defined in the command definition source and separated by a comma and a blank. If there are too many values to fit in 30 characters, the last value is followed by three periods.

The following are examples of possible choices text generated by CHOICE(*VALUES):

  • If TYPE(*DEC) and RANGE(1.0 999.9) and SPCVAL((*NOMAX -1)) are specified, the choices text will be: 

    1.0-999.9, *NOMAX

  • If TYPE(*NAME) and RSTD(*NO) and SNGVAL(*ALL) and SPCVAL(*LIBL *CURLIB) are specified, the choices text will be: 

    Name, *ALL, *LIBL, *CURLIB

  • If RSTD(*YES) and SNGVAL(*ALL) and SPCVAL(*ALRTBL *BNDDIR *CHTFMT *CLD *CLS *CMD) are specified, the choices text will be: 

    *ALL, *ALRTBL, *BNDDIR...

*NONE
No values are displayed.
*PGM
A program that is called determines the values that are displayed. The program that is called is identified in Choice program (CHOICEPGM) parameter of the PARM statement.
message-identifier
Specify the message ID of the message used to retrieve the message containing the text for the possible values field. The message file specified on the Message file for prompt text (PMTFILE) parameter of the Create Command (CRTCMD) command is used to find the message.
'choices-text'
Specify no more than 30 characters, enclosed in apostrophes.

Choice program (CHOICEPGM)

Specifies the program to be called during command prompting to fill in the possible choices text and the permissible values. This parameter must be specified if *PGM is specified on the Choice text (CHOICE) parameter and may not be specified otherwise.

Single values

*NONE
No program is identified to fill in the possible choices text and permissible values.

Qualifier 1: Choice program

name
Specifies the name of the program to be called during prompting to fill in the possible choices text or permissible values. If an exception occurs when the program is called, no possible choices text is left blank, and the list of permissible values is taken from the command.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the program. If no library is specified as the current library for the job, QGPL is used.
name
Specify the name of the library where the program is located.

Prompt control (PMTCTL)

Specifies how prompting is be controlled for this parameter. Prompting may be controlled by another parameter, specified by a Prompt Control (PMTCTL) statement referred to by label in this parameter, or by user request by pressing the F10 key.

*NONE
The parameter is always prompted, unless it is omitted due to selective prompting.
*PMTRQS
The parameter is not prompted unless:
  • The user requests optional parameters to be prompted.
  • A value was entered for the parameter before the prompt was called.
  • The parameter was selected by selective prompt characters.
statement-label
Specify the label of the Prompt Control (PMTCTL) statement that is used to determine whether this parameter is prompted. The parameter is not prompted unless:
  • The conditions specified on the referred to PMTCTL statement have been met.
  • A value was entered for the parameter before the prompt was called.
  • The parameter was selected by selective prompt characters.

Prompt control program (PMTCTLPGM)

Specifies the program to be called to convert the value specified for the parameter into a value used on a Prompt Control (PMTCTL) statement. This parameter is valid only on parameters that are referred to in the Controlling keyword (CTL) parameter of a PMTCTL statement.

Single values

*NONE
No program is to be called to convert the parameter value for prompt control statements. If the parameter is specified in a Prompt Control (PMTCTL) statement, the actual value is compared in that PMTCTL statement.

Qualifier 1: Prompt control program

name
Specify the name of the program to be called to convert the parameter value.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the program. If no library is specified as the current library for the job, QGPL is used.
name
Specify the name of the library where the program is located.

Key parameter (KEYPARM)

Specifies that this parameter is initially displayed when the command is prompted and a prompt override program was specified when the command was created or changed. If no prompt override program is specified, KEYPARM(*NO) is assumed for all parameters.

*NO
The parameter is not displayed initially.
*YES
The parameter is displayed initially.

Initial prompt length (INLPMTLEN)

Specifies the length of the input field initially displayed for the parameter when the command is prompted. The user can extend the field to a maximum length of 512 bytes by entering an ampersand (&) in the first position of the field, followed by a blank. INLPMTLEN is valid only if TYPE is specified as *CHAR, *NAME, *SNAME, *CNAME, *PNAME, *GENERIC, *CMDSTR, *HEX, *X, or *CMD. If FULL(*YES), RSTD(*YES), or CONSTANT are specified, INLPMTLEN(*CALC) must be specified or defaulted.

*CALC
The prompter will determine the length of the prompt field based on the type and length of the parameter.
*PWD
If the current value of system value QPWDLVL is '0' or '1', the prompt field will be 10 bytes long. Otherwise, the length of the prompt field will be determined by the length of the parameter. INLPMTLEN(*PWD) is valid only if TYPE is specified as *CHAR, *NAME, *SNAME, *PNAME, or *CNAME.
initial-prompt-length
Specify the initial length in bytes. Valid values are 1-12, 17, 25, 32, 50, 80, 132, 256, and 512.

Prompt specifications (PROMPT)

Specifies what prompt text is used for the parameter. The prompt text gives a short description of the parameter which appears next to the parameter keyword and input field when the command is prompted. Prompt text cannot be specified if *ZEROELEM or *NULL is specified for the Type of value (TYPE) parameter, or if a constant value is specified in the Constant value (CONSTANT) parameter.

Single values

*NONE
No prompt text is shown for the parameter defined by this PARM statement. This parameter is still prompted by its keyword name, but no prompt text is shown beside the keyword name.

Element 1: Prompt text or message ID

message-identifier
Specify the message identifier that specifies the message containing the prompt text of up to 30 bytes that is shown when the parameter is prompted. If a message having the specified identifier cannot be found in the message file specified on the Message file for prompt text (PMTFILE) parameter of the Create Command (CRTCMD) command, the message identifier itself is used as the prompt text.
'prompt-text'
Specify the prompt text that is shown when the parameter is prompted. The text must be a character string of no more than 30 bytes, enclosed in apostrophes.

Element 2: Order prompt is displayed

relative-prompt-number
A relative prompt number may be specified for the parameter. The relative prompt number specifies the order in which parameter keywords are prompted. This order affects only the order of prompting, not the order in which the parameters are passed to the command processing program. Parameters having prompt numbers are prompted before parameters having no prompt numbers.

Examples

Example 1: Define a Numeric Parameter 

PARM   KWD(X)  TYPE(*DEC)  LEN(2)  MIN(1)  REL(*GT 5)

The value for the parameter named X, a 2-digit decimal number, must be entered. The value must be greater than 5.

Example 2: Define a Parameter with Restricted Values 

PARM   KWD(CLASS)  TYPE(*CHAR)  LEN(1)  DFT(A) +
       VALUES(A B C)  RSTD(*YES)

The value of the parameter named CLASS must be A, B, or C, if specified. If CLASS is not specified, the default value passed to the command processing program will be A.

Example 3: Define a Parameter with Range of Valid Values 

PARM   KWD(MAXREC)  TYPE(*DEC)  LEN(3 0)  MIN(1) +
       RANGE(&MINREC 500)

The value of the MAXREC parameter must be entered as a decimal number of 3 digits or less, with no digits to the right of the decimal point. The value must be greater than or equal to the value entered (or defaulted) for parameter MINREC and also must be less than or equal to 500.

Example 4: Define a Simple List Parameter 

PARM   KWD(FILES)  TYPE(*NAME)  MIN(2)  MAX(5)

The FILES parameter is a homogeneous list that contains a minimum of two names and a maximum of five names.

Example 5: Define a List Parameter with Restricted Values 

PARM   KWD(INVFNAME)  TYPE(*NAME)  DFT(*ALL) +
       SNGVAL((*ALL XXX))  VALUES(DEPT1 DEPT2 DEPT3) +
       FILE(*UPD)  MIN(0)  MAX(3)  RSTD(*YES) +
       PROMPT(USR0002 1)

The value of the parameter named INVFNAME can be a list of up to three file names of which DEPT1, DEPT2, DEPT3, and *ALL are the valid choices. If *ALL is entered, no other values can be entered for the parameter. If this parameter is omitted, file name XXX is passed to the command processing program. If this parameter is entered through a command prompter, the prompt text for this parameter will be retrieved from message identifier USR0002 of the message file specified for the PMTFILE parameter on the Create Command (CRTCMD) command when the command is created. *ALL will be shown as the default parameter value.

Error messages

None