CL Programming

Defining a Qualified Name

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

Using CL or HLL for a Qualified Name

A qualified name is passed to the command processing program in the following format when using CL or HLL:
A qualified name is passed to the command processing program in this 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:
If the display station user enters NAME(USER/A) for the previously defined QUAL statements the name is passed to the command processing program.

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:
Example of what is passed if the display station user enters *NONE as the single value a 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:
A simple list of qualified names is passed to the command processing program in this 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.
The name parameter would be passed to the command processing program.

If the display station user enters the single value NAME(*NONE), the name parameter is passed as follows.
The name parameter is passed if the display station user enters the single value NAME(*NONE).

Using REXX for a Qualified Name

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)


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]