A qualified name is the name of an object preceded by the name of the library in which the object is stored. If a parameter value or list item is a qualified name, you must define the name separately using Qualifier (QUAL) statements. Each part of the qualified name must be defined with a QUAL statement. The parts of a qualified name must be described in the order in which they occur in the qualified name. You must specify *NAME or *GENERIC in the first QUAL statement. The associated PARM or ELEM statement must identify the label that refers to the first QUAL statement for the qualified name.
The following command definition statements define the most common
qualified name. A qualified object consists of the library name which
contains an object followed by the name of the object itself. The QUAL
statements must appear in the order in which they are to occur in the
qualified name.
Many of the parameters that can be specified for the QUAL statement are the same as those described for the PARM statement (see Defining Parameters). However, only the following values can be specified for the TYPE parameter:
When a qualified name is passed to the command processing program, the format varies depending on whether you are using CL or HLL, or REXX. The following section describes how qualified names are passed using CL and HLL. For an explanation of the differences when using REXX, see Using REXX for a Qualified Name.
A qualified name is passed to the command processing program in the
following format when using CL or HLL:
For example, if the display station user enters NAME(USER/A) for
the previously defined QUAL statements, the name is passed to the command
processing program as follows:
Qualifiers are passed to the command processing program consecutively by their types and length just as single parameter values are passed (as described under Defining Parameters). The separator characters (/) are not passed. This applies regardless of whether a single parameter, an element of a mixed list, or a simple list of qualified names is passed.
If the display station user enters a single value for a qualified name, the
length of the value passed is the total of the length of the parts of the
qualified name. For example, if you define a qualified name with two
values each of length 10, and if the display station user enters a single
value, the single value passed is left-adjusted and padded to the right with
blanks so that a total of 20 characters is passed. If the display
station user enters *NONE as the single value, the following 20-character
value is passed:
Qualified names can be processed in CL programs using the Substring built-in function as shown in the following example.
The substring built-in function (%SUBSTRING or %SST) is used to separate the qualified name into two values.
PGM PARM(&QLFDNAM) DCL &QLFDNAM TYPE(*CHAR) LEN(20) DCL &OBJ TYPE(*CHAR) LEN(10) DCL &LIB TYPE(*CHAR) LEN(10) CHGVAR &OBJ %SUBSTRING(&QLFDNAM 1 10) /* First 10 */ CHGVAR &LIB %SST(&QLFDNAM 11 10) /* Second 10 */ . . . ENDPGM
You can then specify the qualified name in the proper CL syntax. For example, OBJ(&LIB/&OBJ).
You can also separate the qualified name into two values using the following method:
PGM PARM(&QLFDNAM) DCL &QLFDNAM TYPE(*CHAR) LEN(20) CHKOBJ (%SST(&QLFDNAM 11 10)/%SST(&QLFDNAM 1 10)) *PGM . . . ENDPGM
A simple list of qualified names is passed to the command processing
program in the following format:
For example, assume that MAX(3) were added as follows to the PARM statement for the NAME parameter.
PARM KWD(NAME) TYPE(NAME1) SNGVAL(*NONE) MAX(3) NAME1: QUAL TYPE(*NAME) QUAL TYPE(*NAME)
If the display station user enters the following:
NAME(QGPL/A USER/B)
then the name parameter would be passed to the command processing program
as follows.
If the display station user enters the single value NAME(*NONE), the name
parameter is passed as follows.
When a command is run using REXX, a qualified name is passed to the command processing program just as the value is entered for the parameter. Trailing blanks are not passed.
For example, if a display station user enters the following for the QUAL statements defined previously in this section:
NAME(USER/A)
the qualified name is passed to the command processing program in the following format:
NAME(USER/A)
Qualifiers are passed to the command processing program consecutively by their types and length just as single parameter values are passed (as described under Defining Parameters).
If the display station user enters *NONE as the single value, the following 20-character value is passed:
NAME(*NONE)
The following example shows how a display station user would enter a simple list of qualified names:
NAME(QGPL/A USER/B)
Using REXX, the name parameter would be passed to the command processing program as the following:
NAME(QGPL/A USER/B)
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.