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

Top

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 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 characters.

*NAME

The parameter value is a character string that represents a name. The maximum length of the name is 256 characters. 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 characters. 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 Special values (SPCVAL) parameter.

*CNAME

The parameter value is a character string that represents a name. The maximum length of the name is 256 characters. 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 Special values (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 characters.

*GENERIC

The parameter value is a character string that represents a generic name. A generic name contains a maximum of 255 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. This parameter is not allowed if *INT2, *INT4, *UINT2, *UINT4, *DATE, *TIME, *CMD, *ZEROELEM, *NULL, or a statement label is specified for the Type of value (TYPE) parameter. With other values specified for the Type of value (TYPE) parameter, this parameter has the following applications:

• If *DEC is specified for the Type of value (TYPE) parameter, the decimal length is specified in the form (length1 length2), where length1 specifies the total number of digits in the value (including the decimal portion), and length2 specifies the number of allowable decimal digits to the right of the decimal point. The value for length2 is optional. Zero is assumed if it is not entered.
• If *CHAR, *NAME, *SNAME, *CNAME, *CMDSTR, or *VARNAME is specified for the Type of value (TYPE) parameter, only length1 is specified. It identifies the number of characters passed.
• If *HEX is specified for the Type of value (TYPE) parameter, only length1 is specified. This length specifies the number of characters passed after the hexadecimal digits have been converted to character digits. Because 2 hexadecimal digits are converted to 1 decimal digit, the number of hexadecimal digits converted is twice the value of this length.
• If *X is specified for the Type of value (TYPE) parameter, the LEN parameter is used as follows:
  • For character data, length1 specifies the minimum length to be passed. If a longer value is entered, the entire value is passed.
  • For decimal data, length2 and length3 specify the length and decimal positions for a constant value. If a variable is entered, it is passed according to the variable attributes.
  • For a logical value, length1 specifies the length of the value, which is always 1.

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)

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:

• Type of value (TYPE parameter)
• Value length (LEN parameter)
• Valid values (VALUES parameter)
• Relational expression (REL parameter)
• Range of values (RANGE parameter)
• Special values (SPCVAL parameter)
• Full field required (FULL parameter)

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

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:

• *CMD, *NULL, or *ZEROELEM specified for the Type of value (TYPE) parameter
• A value greater than 1 specified for the Maximum values allowed (MAX) parameter
• The Default value (DFT) parameter
• *YES specified for the Return value (RTNVAL) parameter
• *YES specified for the Value an expression (EXPR) parameter

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:

• 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)

*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:

• It must match the requirements specified by the following parameters.
  • Type of value (TYPE parameter)
  • Value length (LEN parameter)
  • Relational expression (REL parameter)
  • Range of values (RANGE parameter)
  • Full field required (FULL parameter)
• It must be one of the from-values in the Special values (SPCVAL) parameter, or the Single values (SNGVAL) parameter.
• If the default is a character constant, it can have no more than 32 characters.
• If *YES is specified on the Restricted values (RSTD) parameter, it must be in the list of values in the Valid values (VALUES) parameter, or in the list of from-values of either the Special values (SPCVAL) parameter or the Single values (SNGVAL) parameter.
• It must be a from-value on the Single values (SNGVAL) parameter if the parameter being defined is a list of unlike values or it is a qualified name. This is true when a statement label is specified for Type of value (TYPE) parameter; the label is used to identify a QUAL or ELEM statement.

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:

• *YES is specified on the, Restricted values (RSTD) parameter.
• Both the Range of values (RANGE) parameter and the Relational expression (REL) parameter are not specified.
• Each constant matches the attributes specified by the following parameters.
  • Type of value (TYPE parameter)
  • Value length (LEN parameter)
  • Full field required (FULL parameter)

Character constants specified in this parameter can be no longer than 32 characters. 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 *YES is specified on the Return value (RTNVAL) parameter.
• If either the Range of values (RANGE) parameter or the Valid values (VALUES) parameter is specified.
• If *LGL, *VARNAME, *CMD, *CMDSTR, *X, *ZEROELEM, *NULL, or a statement label is specified for the Type of value (TYPE) parameter.

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 characters.

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:

• If *YES is specified on the Return value (RTNVAL) parameter.
• If either the Relational expression (REL) parameter or the Valid values (VALUES) parameter is specified.
• If *LGL, *VARNAME, *CMD, *CMDSTR, *X, *ZEROELEM, *NULL, or a statement label is specified for the Type of value (TYPE) parameter.

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

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 characters. 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 characters. 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 PARM statement accepts the hexadecimal characters above X'FF' or those 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 characters in the parameter 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 characters in the parameter can be less than that specified by the Value length (LEN) parameter.

*YES

The number of characters in the parameter 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, *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 value that is passed to the command processing program is preceded by a length value that indicates the number of characters entered for the command parameter.

Note: The length value is the actual number of characters 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 characters in the character string data field were actually entered for the command parameter.

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 characters 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 value is an integer passed as a 2-byte signed binary number.

*INT4

The parameter 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.

*JOB

If the command string was originally in Unicode, the value will be converted to the job CCSID. If the original command string was not in Unicode, the job CCSID is assumed and no conversion is done.

*UTF16

The parameter value is converted to UTF16. If the original input was not in Unicode it is assumed to be in the job CCSID. This value can be specified only on *CHAR and *PNAME parameter types.

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.

*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 characters 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 characters, 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