Element Definition (ELEM)

The Element (ELEM) command definition statements are used to define the elements of a mixed list parameter on a command. A list parameter is a parameter that accepts multiple values that are passed together as consecutive values pointed to by a single parameter. The values are preceded by a 2-byte binary value that indicates the number of elements defined for the parameter.

A list item is the value that represents one value among a group of values organized in a specific order in a list. If all of the list elements are not of the same type, one ELEM statement must be used for each element that appears in the list being defined. If all the elements are of the same type (a simple list), individual ELEM statements are not required. For a simple list, all that is necessary is to specify the number of elements in the list on the Maximum values allowed (MAX) parameter of the PARM statement.

The order in which the ELEM statements are entered into the source file determines their positional order in the list. The first ELEM statement (for the first list item) must have a statement label that matches the statement label on the Type of value (TYPE) parameter of the PARM or ELEM statements for the same list. The remaining ELEM statements in the list must be unlabeled. Lists of elements having different values can be nested to the depth of three levels, including the highest level. A maximum of 300 elements can be included in one list.

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

Parameters

Keyword Description Choices Notes
TYPE Type of value Simple name, *DEC, *CHAR, *LGL, *NAME, *VARNAME, *INT2, *GENERIC, *INT4, *DATE, *TIME, *ZEROELEM, *HEX, *SNAME, *PNAME, *UINT2, *UINT4, *X, *CNAME Required, Positional 1
LEN Value length Values (up to 3 repetitions): Integer Optional, Positional 2
CONSTANT Constant value Character value Optional
RSTD Restricted values *YES, *NO 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 Character value
RANGE Range of values Element list Optional
Element 1: Lower value Character value
Element 2: Upper value 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 ELEM a program *NO, *YES Optional
DTAARA Is ELEM a data area *NO, *YES Optional
FILE If a file parameter, how used *NO, *IN, *OUT, *UPD, *INOUT, *UNSPFD Optional
FULL Full field required *YES, *NO 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 *YES, *NO Optional
CASE Case of value *MONO, *MIXED Optional
CCSID CCSID of value *JOB, *UTF16 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
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 text or message ID Character value, *NONE Optional

Type of value (TYPE)

Specifies the type of list item being defined. The element can be an integer, a decimal or logical value, or a quoted or not quoted character string that can be a name, label, date, or time.

*DEC
The list item is a packed decimal number.
*LGL
The list item is a logical value, either a one ('1') or a zero ('0').
*CHAR
The list item 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 number of bytes that can be in the character string is 5000 if *JOB is specified for the CCSID parameter and 10000 if *UTF16 is specified for the CCSID parameter.
*NAME
The list item 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 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 list item 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 list item 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 #. If a special value is used (as in *LIBL or *NONE), it must be specified on the Special values (SPCVAL) parameter.
*PNAME
The list item 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 list item 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.
*DATE
The list item 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 CPP, 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 ELEM statement, it must be specified without quotation marks in one of the following formats: mmddyy, mmddyyyy, or Cyymmdd. If the user enters a date when the command is run, 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 list item 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 list item 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 with zeros. If the value is enclosed in apostrophes, an even number of digits is required. If the value is not enclosed in apostrophes, the number of digits can be odd or even.
*ZEROELEM
The list item 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 an element that is a list even though the CPP expects one. An element for which *ZEROELEM is specified is not prompted for, although the other elements in the parameter are prompted and are passed to the CPP as a list.
*X
(For IBM-supplied commands) The list item 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 list item is an integer that is passed as a 2-byte signed binary number.
*INT4
The list item is an integer that is passed as a 4-byte signed binary number.
*UINT2
The list item is an integer that is passed as a 2-byte unsigned binary number.
*UINT4
The list item is an integer that is passed as a 4-byte unsigned binary number.
*VARNAME
(For IBM-supplied commands) The list item value is a CL variable name that is passed as a character string.
statement-label
The list item accepts a qualified list name or a mixed list of values. The statement label specified here by the TYPE parameter is the statement label that identifies the first of a series of QUAL or ELEM statements that further describe the qualified list name or the mixed list being defined. The label must be the same as the label specified by statement label on the Type of value (TYPE) parameter on the PARM statement for this list.

Value length (LEN)

Specifies the length of the list item 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             |
------------------------------------------------

Constant value (CONSTANT)

Specifies that a value is passed to the CPP as a constant for the list item when the command being defined is processed; the element is not to appear externally on the command. If specified, the value 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. This parameter is not valid in the following cases:

If a constant is specified for the element being defined, no prompt text can be specified for the Prompt text or message ID (PROMPT) parameter. However, the other elements of the list parameter (of which this list item is a part) are still prompted, and their values along with this constant value are still passed to the CPP as a list.

Variables cannot be coded for this parameter.

Restricted values (RSTD)

Specifies whether the value entered for the list item (specified in the ELEM 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 if the value can be any value that satisfies the requirements specified by the following parameters:

*NO
The value entered for the list item defined by this ELEM statement can be anything that matches 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)
*YES
The value entered for the list item in this ELEM statement is restricted to one of the values in the Valid values (VALUES) parameter, or to one of the from-values in the Special values (SPCVAL) parameter, or the Single values (SNGVAL) parameter. *YES cannot be specified if a statement label or *ZEROELEM is specified on the Type of value (TYPE) parameter.

Default value (DFT)

Specifies the default value that is assigned to the list item if the user does not specify a value. That is, the default value is used as the value of the list item if the user omits the parameter that represents this list item, or specifies *N for the element, while coding or entering the command. The default value must satisfy one of the following:

This parameter is valid only if the Minimum values required (MIN) parameter is 0, which means the element defined by this ELEM statement for this list is optional. This parameter is not allowed if the Constant value (CONSTANT) parameter is specified. A default cannot be specified if *ZEROELEM is specified for the Type of value (TYPE) parameter; in that case, an assumed default is passed.

An assumed default value is not displayed by the command prompt; a blank input field is shown instead. If a default is specified in this parameter, 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 specified as the value of the list item. 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. Specify up to 300 constants that can be specified as the value of the list item. This parameter is not valid if a statement label or *ZEROELEM is specified for the TYPE parameter;

If this ELEM statement is defining the first element in a list, the value specified for this parameter cannot be the same as the value specified in the Single values (SNGVAL) parameter on either the PARM or ELEM statement that points to this ELEM statement.

Relational expression (REL)

Specifies the relationship between the list item value and the value of another parameter or constant. The value associated with the referred to keyword is the value passed to the CPP, not the user-specified value. To specify the relationship, enter one of the following relational operators followed by a constant or the value of another parameter.

*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

This parameter is not valid if *LGL, *VARNAME, *ZEROELEM, or a statement label is specified for the Type of value (TYPE) parameter, or if either the Range of values (RANGE) parameter or the Valid values (VALUES) parameter is specified. If *CHAR (character type) is specified by 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.

Range of values (RANGE)

Specifies the range, or the limits, for the value of the list item. The list item 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. The value tested is the value sent to the CPP, not the user-specified value.

For nonnumeric data types, such as *CHAR, the range of values and the data specified will be 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.

This parameter is not valid if either the Relational expression (REL) parameter or the Valid values (VALUES) parameter is specified, or if *LGL, *VARNAME, *ZEROELEM, or statement label is specified on the Type of value (TYPE) parameter. Character constants specified in this parameter can be no longer than 32 bytes.

Special values (SPCVAL)

Specifies a list of up to 300 entries that define special values that can be entered for the element defined by this ELEM statement. Each entry specifies a character string (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 a statement label or *ZEROELEM is specified for the Type of value (TYPE) parameter.

If a to-value of *CURLIB is specified, the name of the current library is passed to the CPP rather than the value *CURLIB. 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.

The from-value is a character string, but the to-value can be anything that is passable. However, if *DATE is specified for the Type of value (TYPE) parameter, the to-value must be specified not quoted in one of the following formats: mmddyy, mmddyyyy, or cyymmdd.. If a CL variable is used for the from-value, its type must be *CHAR. If this ELEM statement is defining the first element in a list, the value specified for the from-value cannot be the same as the value specified in the Single values (SNGVAL) parameter on either the PARM or ELEM statement that points to this ELEM statement.

The to-value must be no longer than is 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 a character type (such as *CHAR, *LGL, or *DATE) is specified for the Type of value (TYPE) parameter, 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.

Variables cannot be coded for this element.

Single values (SNGVAL)

Specifies a list of up to 300 single values that can be specified for an element being defined as a statement label, or that is to have two or more list items in its nested list (defined by the Maximum values allowed (MAX) parameter). Any one of the single values can be used instead of a nested list of values or a qualified name that the element is defined to accept. Each entry specifies a character string (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 (CPP) without further checking. If the to-value is omitted, the from-value is passed to the CPP. If this ELEM statement is defining the first element in a list, the value specified for the from-value cannot be the same as the value specified in the Single values (SNGVAL) parameter on either the PARM or ELEM statement that points to this ELEM statement.

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 one or if a statement label is specified for the Type of value (TYPE) parameter. It is not valid if *ZEROELEM is specified for the Type of value (TYPE) parameter. Each single value can only substitute for a list of values or a qualified name; it cannot be a list item or qualifier. It is passed as the first element of the list.

If a to-value of *CURLIB is specified, the name of the current library is passed to the CPP rather than the value *CURLIB. 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.

Minimum values required (MIN)

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

For an element that allows multiple like values (because a value greater than one is specified in the Maximum values allowed (MAX) parameter), zero (0) indicates that no values must be entered; therefore, it is an optional element. A value of one (1) or greater than one indicates the minimum number of values that must be entered for the element, and therefore it is a required element. The value specified for this parameter cannot exceed the value specified for the Maximum values allowed (MAX) parameter. The number specified tells how many list items are required in another list. If this parameter is not specified, zero (0) is assumed, which means that the element is optional.

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

Maximum values allowed (MAX)

Specifies, if this ELEM statement is defining a simple list item, the maximum number of elements that this list item can have in its nested list. If a value greater than 1 is specified, the element is capable of accepting multiple like values (that is, a simple nested list). All values entered for this element (at the time the command is run) must satisfy the validity checking requirements specified by the other parameter values on this ELEM statement.

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

1
The list item accepts only one value; there is no nested list.
maximum-number
Specify the maximum number of elements that the list item 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 statement or another ELEM statement is not specified for the Type of value (TYPE) parameter, the parameter, which is also an element, is a simple list of like values (that is, each element in the list has the same requirements, such as type and length). If a statement label is specified for the Type of value (TYPE) parameter, and it points to the label of a QUAL statement or another ELEM statement, this parameter should only be specified greater than 1 if a list of lists or a list of qualified names is to be accepted. A maximum greater than 1 is not valid if the Constant value (CONSTANT) parameter is also specified.

Allow unprintable characters (ALWUNPRT)

Specifies whether this ELEM statement should accept the hexadecimal value X'FF' and those hexadecimal values in the range X'00' to X'3F'. This parameter is valid only if *CHAR or *X is specified for the Type of value (TYPE) parameter.

*YES
Any hexadecimal values can be sent to the display or printer.
*NO
Unprintable characters cannot be passed to the command processing program.

Allow variable names (ALWVAR)

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

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

Is ELEM a program (PGM)

Specifies whether this 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. The specification of *YES on this parameter does not have any effect on the element being defined by the ELEM statement; it only indicates to the compiler that the value for this element 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 element (defined in this ELEM statement) is not a program name.
*YES
The element is a program name.

Is ELEM a data area (DTAARA)

Specifies whether the element 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. The specification of *YES on this parameter does not have any effect on the element being defined by the ELEM statement; it only indicates to the compiler that the value for this element 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 element (defined in this ELEM statement) is not a data area name.
*YES
The element is a data area name.

If a file parameter, how used (FILE)

Specifies whether if the list item is a file name and the expected use of the file. The element 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. This parameter is valid only if a statement label, *CHAR, *NAME, *SNAME, *CNAME, or *GENERIC value is specified for the Type of value (TYPE) parameter. The specification in this parameter does not have any effect on the list item being defined by the ELEM statement; it only indicates to the compiler that the value for this element is a file name and what type of file it is. This information is stored so that it can be included in the output of the DSPPGMREF (Display Program References) command. One of the following types of files can be specified:

*NO
The list item (defined in this ELEM statement) is not a file name.
*IN
The list item is an input file name.
*OUT
The list item is an output file name.
*UPD
The list item is an update file name.
*INOUT
The list item value is the name of a file that is to be used for both input and output.
*UNSPFD
The list item value is the name of a file, but its use cannot be specified.

Full field required (FULL)

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

*NO
The number of bytes in the list item value can be less than that specified by the LEN parameter.
*YES
The number of bytes in the list item value must equal the number specified by the LEN parameter, or the default length for that type. The exact length is valid only for the following types on the Type of value (TYPE) parameter: *LGL, *CHAR, *NAME, *SNAME, *CNAME, *GENERIC, *VARNAME, and *HEX.

Value an expression (EXPR)

Specifies whether the element can accept an expression containing a character concatenation.

*NO
The element value cannot be a concatenation expression.
*YES
The element value can be a concatenation expression. *YES is not valid if a value is specified for the Constant value (CONSTANT) parameter.

Varying length (VARY)

Specifies whether the list item value that is passed to the CPP is preceded by a length value that indicates the number of bytes entered for the element's value.

Single values

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

Element 1: Return length value

*YES
The element 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, and *VARNAME. *YES must be specified if PASSATR(*YES) and RTNVAL(*YES) are specified.

Note: The length value is the actual number of bytes entered for the list item 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 variables. The length value defines how many bytes in the character string data field 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 element value. This could be up to twice the number specified for the Value length (LEN) parameter because the element 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.

Element 2: Value length

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

Pass attribute byte (PASSATR)

Specifies whether an attribute byte is to be passed to the command processing program (CPP) with the list item data. This parameter is not valid if a statement label or *ZEROELEM is specified for the Type of value (TYPE) parameter.

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

*NO
No attribute byte is passed with the list item.
*YES
An attribute byte is passed with the list item.

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

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 element value is changed from lowercase to uppercase. Parameters enclosed with apostrophes preserve the case whether or not this value is specified.
*MIXED
The element value is preserved in the case specified on the command parameter. The value can be specified only for *CHAR and *PNAME parameter types.

CCSID of value (CCSID)

Specifies the coded character set identifier (CCSID) to use when passing the element 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 element 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 element.
*UTF16
The element 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 element value will be performed. Otherwise, the command string is assumed to already be in the CCSID of the job, and the element 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.

Display input (DSPINPUT)

Identifies if the keyword value is to be 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 will be shown on the prompt display and in the job log.
*PROMPT
The response *PROMPT indicates that the parameter value will be shown on the prompt display but not in the job log.
*NO
The response *NO indicates that the parameter values will not be 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.

Initial prompt length (INLPMTLEN)

Specifies the length of the input field initially displayed for the element 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, or *HEX. 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 text or message ID (PROMPT)

Specifies the prompt text, if any, is that used for the list item (defined in this ELEM statement). The prompt text gives a short description of the element which appears next to the element input field when the command is prompted. Prompt text cannot be specified if *ZEROELEM is specified for the Type of value (TYPE) parameter, or if a constant value is specified for the Constant value (CONSTANT) parameter.

*NONE
No prompt text is displayed for the list item defined by this ELEM statement. This list item is still prompted by an input field, but no text is displayed with it.
message-identifier
Specify the message identifier that specifies the message containing the prompt text of up to 30 bytes that is displayed when the program is prompting for the list item. If a message having the specified identifier cannot be found in the message file specified in 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 displayed when the program is prompting for the list item. The text must be a character string of no more than 30 bytes, enclosed in apostrophes.

Examples

Example 1: Define a Parameter with Two Different Types of Elements 

       PARM   KWD(JOBDESC)  TYPE(L1)  MIN(1)
L1:    ELEM   TYPE(*NAME)  LEN(10)  MIN(1)
       ELEM   TYPE(*DEC)  LEN(2)  MIN(1)  REL(*LE 60)

The parameter named JOBDESC is required and has two elements which must both be specified. The first element is a ten-character name, and the second element is a 2-digit number that is less than or equal to 60.

Example 2: Define a Parameter with Similar Elements 

       PARM   KWD(RANGE)  TYPE(L1) MIN( DFT(*SAME) +
              SNGVAL((*SAME 101))
L1:    ELEM   TYPE(*DEC)  MIN(1)  REL(*LE 100)
       ELEM   TYPE(*DEC)  MIN(1)  REL(*LE 100)

The parameter named RANGE can be omitted, but, if present, it must be a list of two numbers, neither of which can be greater than 100. To allow the command processing program to determine whether the value passed is a user-specified value or the *SAME single value, *SAME is mapped to 101 which is outside the normal range of values being checked for.

Error messages

None