Qualifier Definition (QUAL)

The Qualifier (QUAL) command definition statement describes one part of a qualified name. If a name is the allowable value of a parameter or list item defined in a PARM or ELEM statement, it can be changed to a qualified name by using a QUAL statement for each qualifier used to qualify the name.

The order in which the QUAL statements are entered into the source file determines the positional order in which the qualifiers must be specified and passed to the validity checker and the command processing program. The first qualification of a qualified name must be either a simple name, a generic name, or a defined special value.

The QUAL statement (or only the first QUAL statement if there are more than one) must have a statement label that matches the statement label value that must be specified in a PARM or ELEM statement for which the qualifier is being defined. The qualifiers for the parameter or list item are then entered on the command in the form: value3/value2/value1, where values 1 through 3 are qualifiers that are each described by a QUAL statement. The values are passed to the command processing program in the same order, with the periods removed, and with each value padded to its maximum length.

Note: The QUAL 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
TYPE	Type of value	NAME, GENERIC, CHAR, INT2, INT4, SNAME, CNAME, UINT2, UINT4, CNAME	Required, Positional 1
LEN	Length specification	Element list	Optional, Positional 2
LEN	Element 1: Value length	Integer	Optional, Positional 2
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	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
MIN	Minimum values required	0, 1	Optional
ALWUNPRT	Allow unprintable characters	YES, NO	Optional
ALWVAR	Allow variable names	YES, NO	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
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

Top

Type of value (TYPE)

Specifies the type of qualifier used to qualify a parameter name or list element name. The qualifier can be a name or generic name, a quoted or not quoted character string, or an integer. Enter one of the following options to specify the type of qualifier. The first qualifier for any qualified name must have a type of name (*NAME) or generic name (*GENERIC).

*NAME: The qualifier 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 qualifier 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 qualifier 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.
*GENERIC: The qualifier is a character string that represents a generic name. A generic name contains a maximum of 255 characters followed by an asterisk (*); 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.
*CHAR: The qualifier 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.
*INT2: The qualifier is an integer that is passed as a 2-byte signed binary number.
*INT4: The qualifier is an integer that is passed as a 4-byte signed binary number.
*UINT2: The qualifier is an integer that is passed as a 2-byte unsigned binary number.
*UINT4: The qualifier is an integer that is passed as a 4-byte unsigned binary number.

Constant value (CONSTANT)

Specifies that a value is passed to the command processing program as a constant for the qualifier when the command being defined is processed; the qualifier is not to appear externally on the command. If specified, the value must satisfy the requirements specified by the following parameters:

Type of value (TYPE parameter)
Length specification (LEN parameter)
Valid values (VALUES parameter)
Relational expression (REL parameter)
Range of values (RANGE parameter)
Special values (SPCVAL parameter)

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

If a constant is specified in this QUAL statement and other QUAL statements immediately follow it, they must also be defined as constants, unless a label precedes one of them. A label indicates the beginning of a new group of QUAL statements, which can be defined differently.

Also, if a constant is specified for the qualifier being defined, no prompt text can be specified for the Prompt text or message ID (PROMPT) parameter of this QUAL statement. However, any other qualifiers or groups of qualifiers are still prompted, and their values are still passed to the command processing program as a qualified name.

This parameter is not valid if the Default value (DFT) parameter is specified or if *YES is 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 qualifier is restricted to only one of the values given in the Valid values (VALUES) parameter or the Single values (SNGVAL) parameter, or whether any value can be used that satisfies the requirements specified by the following parameters:

Type of value (TYPE parameter)
Length specification (LEN parameter)
Relational expression (REL parameter)
Range of values (RANGE parameter)
Special values (SPCVAL parameter)

*NO

The value entered for the qualifier defined by this QUAL statement can be anything that satisfies the requirements specified by the following parameters:

Type of value (TYPE parameter)
Length specification (LEN parameter)
Relational expression (REL parameter)
Range of values (RANGE parameter)
Special values (SPCVAL parameter)

*YES

The value entered for the qualifier in this QUAL 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.

Default value (DFT)

Specifies the default value assigned to the qualifier if a value is not specified by the user. The default value must satisfy one of the following:

It must match the qualifier requirements specified by the following parameters:
- Type of value (TYPE parameter)
- Length specification (LEN parameter)
- Relational expression (REL parameter)
- Range of values (RANGE parameter)
It must be one of the from-values in the Special values (SPCVAL) parameter.
If *YES is specified for 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 in the Special values (SPCVAL) parameter.
If the default is a character constant, it can have no more than 32 characters.

This parameter is valid only if the Minimum values required (MIN) parameter is 0, which means the qualifier defined by this QUAL statement for this list is optional. A default is not meaningful on this QUAL statement if it is the first one (defining the first part) for a qualified name and if a default is specified on the PARM or ELEM statement that this QUAL statement further defines. If this parameter is not specified, it has a default of its own: the default is blank if *CHAR, *NAME, *SNAME, *CNAME, or *GENERIC is specified for the Type of value (TYPE) parameter. The default is zero (0) if *INT2, *INT4, *UINT2 or *UINT4 is specified for the Type of value (TYPE) parameter. 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.

The DFT parameter is not valid if the Constant value (CONSTANT) parameter is 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 or the Special values (SPCVAL) 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 qualifier. This parameter is valid only if all of the following are true:

*YES is specified for the Restricted values (RSTD) parameter.
Both the Range of values (RANGE) parameter, and the Relational expression (REL) parameter are not specified,
The constant matches the attributes specified by the Type of value (TYPE) parameter, and the Length specification (LEN) parameter in this QUAL statement.

Character constants specified in this parameter can be no longer than 32 characters. Specify the constants (not more than 300) that can be entered as the value of the qualifier.

Relational expression (REL)

Specifies the relationship between the qualifier value and the value of another parameter or constant. 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 either the Valid values (VALUES) parameter or the Range of values (RANGE) parameter is specified. If *CHAR (character type) is specified by 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.

Range of values (RANGE)

Specifies the range, or limits, for the value of the qualifier. The qualifier 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 nonnumeric data types, such as *CHAR, the range of values and the data specified is 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 Valid values (VALUES) parameter, or the Relational expression (REL) parameter is specified. Character constants specified in this parameter can be no longer than 32 characters.

Special values (SPCVAL)

Specifies a list of up to 300 entries that define special values that can be entered on the parameter named in the Keyword (KWD) parameter on the PARM statement. 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 without further checking. If the to-value is omitted, the from-value is passed to the command processing program. The from-value is a character string, but the to-value can be anything that is passable. If a CL variable is used for the from-value, its type must be *CHAR. However, the first qualifier can only have special to-values with the from-values that are a name, a generic name, or an asterisk (*) followed by a name such as *ALL.

Each to-value must be passable to the command processing program. The to-value must be no longer than is specified on the Length specification (LEN) parameter and, if *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 or *NAME) 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 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 is passed to the command processing program 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 command processing program.

Variables cannot be coded for this value.

Full field required (FULL)

Specifies whether the number of characters in the qualifier value must be exactly the same as the number specified in the Length specification (LEN) parameter (if specified) or its default length (if LEN is not specified).

*NO: The number of characters in the qualifier value can be less than that specified by the. Length specification (LEN) parameter.
*YES: The number of characters in the qualifier value must equal the number specified by the Length specification (LEN) parameter or the default length for that type. The exact length is valid only if *CHAR, *NAME, or *GENERIC is specified for the Type of value (TYPE) parameter.

Varying length (VARY)

Specifies whether the qualifier value that is passed to the command processing program is preceded by a length value that indicates the number of characters entered for the qualifier's value.

Single values

*NO: The qualifier value is not preceded by a length value.

Element 1: Return length value

*YES: The qualifier value passed to the command processing program is preceded by a binary length field that indicates the number of characters actually specified for the qualifier. *YES is valid only if *CHAR, *NAME, *SNAME, *CNAME, or *GENERIC is specified for the Type of value (TYPE) parameter. *YES must be specified if PASSATR(*YES) and RTNVAL(*YES) are specified.
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.

Element 2: Value length

*INT2: The qualifier value is an integer passed as a 2-byte signed binary number.
*INT4: The qualifier 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 with the qualifier. The attribute byte precedes the qualifier data.

*NO

No attribute byte is passed with the qualifier.

*YES

An attribute byte is passed with the qualifier.

The attribute byte has two fields:

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.

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

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 qualifier 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 *NAME, *SNAME, *CNAME, *GENERIC, or *CHAR. 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, 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, that is used for the qualifier (defined in this QUAL statement). This parameter is not allowed for the first qualifier or for a qualifier for which the Constant value (CONSTANT) parameter is specified. The prompt text for the first qualifier comes from the PROMPT parameter of the PARM or ELEM statement pointing to the qualifier. The prompt text gives a short description of the qualifier which appears next to the qualifier input field when the command is prompted.

*NONE: No prompt text is shown for the qualifier defined by this QUAL statement. This qualifier is still prompted by an input field, but no text is shown with it.
message-identifier: Specify the message identifier that specifies the message containing the prompt text of up to 30 characters that is shown when the program is prompting the qualifier. 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 shown when the program is prompting the qualifier. The text must be a character string of no more than 30 characters, enclosed in apostrophes.

Examples

Example 1: Qualified Job Name as One Element

       PARM   KWD(SPLFILE)  TYPE(L1)  DFT(*)  SNGVAL(*)
L1:    ELEM   TYPE(*NAME)  MIN(1)    /* For file name  */
       ELEM   TYPE(Q1)
Q1:    QUAL   TYPE(*NAME)  MIN(1)    /* For job name   */
       QUAL   TYPE(*NAME)            /* For user name  */
       QUAL   TYPE(*CHAR)  LEN(6)    /* For job number */

The SPLFILE parameter is optional and, if not specified, defaults to an asterisk (*). Otherwise, the value consists of a two-element list. The first element is a file name and it is required. The second element is a qualified job name. The first qualifier is required; the last two qualifiers are optional. The following are some examples of valid SPLFILE parameter syntax:

SPLFILE(*)
SPLFILE(MYSPLFILE MYJOB)
SPLFILE(MYSPLFILE 123456/USERA/MYJOB)

Example 2: List of Qualified Object Names as One Element

       PARM   KWD(DTAMBRS)  TYPE(L1)  DFT(*ALL)  MAX(32) +
              SNGVAL(*ALL)
L1:    ELEM   TYPE(Q1)  MIN(1)
       ELEM   TYPE(*NAME)  MIN(0)  MAX(32)  SPCVAL(*NONE) +
              DFT(*NONE)
Q1:    QUAL   TYPE(*NAME)  MIN(1)
       QUAL   TYPE(*NAME)  DFT(*CURRENT)  SPCVAL(*CURRENT)

The parameter named DTAMBRS is optional and, if not specified, defaults to *ALL. Otherwise, the value consists of a list, each element of which is itself a list. Each sublist consists of a qualified file name optionally followed by one or more member names. If no member name is specified, *NONE is taken as the default. If no library qualifier is specified for the file, *CURRENT is taken as the default. Each sublist can contain one file name and up to 32 member names. Up to 32 such sublists can appear as the value of DTAMBRS. The following are some examples of valid DTAMBRS parameter syntax:

DTAMBRS(*ALL)
DTAMBRS((PFILE1 *NONE))
DTAMBRS((LIB1/PFILE1 (MBR1 MBR2)))
DTAMBRS((*CURRENT/PFILE1 (MBR1 MBR2 MBR3)) (LIB2/PFILE2 (MBRA MBRB)))