CL Programming

Library Lists

For commands in which a qualified name can be specified, you can omit specifying the library name. If you do so, either of the following happens:

Library lists used by OS/400 consist of the following four parts.

System part
The system part of the library list contains objects needed by the system.

Product libraries
Two product libraries may be included in the library list. The system uses product libraries to support languages and utilities that are dependent on libraries other than QSYS to process their commands.

User commands and menus can also specify a product library on the PRDLIB parameter on the Create Command (CRTCMD) and Create Menu (CRTMNU) commands to ensure that dependent objects can be found.

The product libraries are managed by the system, which automatically places product libraries (such as QRPG) into the reserved product library position in the library list when needed. A product library may be a duplicate of the current library or of a library in the user part of the library list.

For example, assume that there is a product library in the library list when a command or menu that has a product library starts. The system will replace the product library in the library list with the new product library until the new command ends or the user leaves the new menu.

Current library
The current library can be, but does not have to be, a duplicate of any library in the library list. The value *CURLIB (current library) may be used on most commands as a library name to represent whatever library has been specified as the current library for the job. If no current library exists in the library list and *CURLIB is specified as the library, QGPL is used. You can change the current library for a job by using the Change Current Library (CHGCURLIB) or Change Library List (CHGLIBL) command.

User part
The user part of the library list contains those libraries referred to by the system's users and applications. The user part, and the product and current libraries, may be different for each job on the system. There is a limit of 250 libraries.

For a list of the libraries shipped with the system or optionally installable on the system, see Appendix C, IBM-Supplied Libraries in Licensed Programs (LP).

The following diagram shows an example of the structure of the library list:
This diagram shows an example of the structure of the library list.

Note:
The system places library QPDA in product library 1 when the source entry utility (SEU) is used. When SEU is being used to syntax check source code, a second product library can be added to product library 2. For example, if you are syntax checking RPG source, then QPDA is product library 1 and QRPG is product library 2. In most other system functions, product library 2 is not used.

Using a library list simplifies finding objects on the system. Each job has a library list associated with it. When a library list is used to find an object, each library in the list is searched in the order of its occurrence in the list until an object of the specified name and type is found. If two or more objects of the same type and name exist in the list, you get the object from the library that appears first in the library list. The following diagram shows the searches made for an object both when the library list (*LIBL) is used and when a library name is specified:

Note:
Alternatively, use *NLVLIBL instead of *LIBL to qualify any command. Enter the command from a CL program, on a command line, or anywhere you normally enter a command. The system uses *NLVLIBL to determine which libraries to search for the *CMD object. You search only the national language support libraries in the library list by specifying *NLVLIBL.

For more information on signing and verification of *CMD objects, see the Object signing and signature verification article in the Security category of information of the iSeries Information Center.


This diagram shows the searches made for an object both when the library list (*LIBL) is used and when a library name is specified.

The following diagram shows what happens when two objects of the same name but different types are in the library list. The system will search for CUSTINQ *FILE in the library list by specifying:

DSPOBJD OBJ(*LIBL/CUSTINQ) OBJTYPE(*FILE)

This diagram shows what happens when two objects of the same name but different types are in the library list.

Generally, a library list is more flexible and easier to use than qualified names. More important than the advantage of not entering the library name, is the advantage of performing functions in an application on different data simply by using a different library list without having to change the application. For example, a CL program PGMA updates a data area CHKNBR. If the library name is not specified, the program can update the data area named CHKNBR in different libraries depending on the use of the library list. For example, assume that JOBA and JOBB both call PGMA as shown in the following illustration:
In this illustration assume that JOBA and JOBB both call PGMA. Generally, a library list is more flexible and easier to use than qualified names. More important than the advantage of not entering the library name, is the advantage of performing functions in an application on different data simply by using a different library list without having to change the application. For example, a CL program PGMA updates a data area CHKNBR. If the library name is not specified, the program can update the data area named CHKNBR in different libraries depending on the use of the library list.

However, the use of a qualified name is advantageous in any of the following situations:

If, however, you call a program using a qualified name and the program attempts to open files whose names are not qualified, the files are not opened if they are not in the library list, as shown in the following example:
This example shows you can call a program using a qualified name and the program attempts to open files whose names are not qualified, the files are not opened if they are not in the library list.

The call to PGMA is successful because the program name is qualified on the CALL command. However, when the program attempts to open file ORDENTP, the open operation fails because the file is not in one of the libraries in the library list, and its name is not qualified. If library DISTLIB2 was added to the library list or a qualified file name was used, the program could open the file. Some high-level languages do not allow a qualified file name to be specified. By using an Override (OVRxxx) command, a qualified name can be specified.

A Job's Library List

Each job's library list consists of up to four parts: a system part, a user part, and the current and product libraries. Only the system part will always be included in the library list.

When the system is shipped, the system value QSYSLIBL contains the names of the libraries to become the system part of the library list. The shipped values are QSYS, QSYS2, QHLPSYS, and QUSRSYS. The system value QUSRLIBL contains the names of the libraries to become the user part of the library list.

QSYSLIBL can contain 15 library names, and QUSRLIBL can contain 250 library names. To change the system portion of a job's library list, use the Change System Library List (CHGSYSLIBL) command. To change the value of either QSYSLIBL or QUSRLIBL, use the Change System Value (CHGSYSVAL) command. A change to these system values takes effect on new jobs that are started after the system values are changed.

Changing the Library List

For a running job, you can add entries to or remove entries from the library list by using the Add Library List Entry (ADDLIBLE) command or the Remove Library List Entry (RMVLIBLE) command, or you can change the libraries in the library list by using the CHGLIBL command or the EDTLIBL command. These commands change the user part of the library list, not the system part.

The current library may be added or changed using the Change Current Library (CHGCURLIB) or CHGLIBL command. The current library can also be changed in the user's user profile, at sign-on, or on the Submit Job (SBMJOB) command. The product libraries cannot be added using a CL command; these libraries are added by the system when a command or menu using them is run. The product libraries cannot be changed with a CL command; however, they can be changed with the Change Library List (QLICHGLL) API.

When you use these commands, the change to the library list affects only the job in which the command is run, and the change is effective only as long as the job is running, or until you change the job's library list again. When the library list is changed through the use of these commands, the libraries must exist when the command is run. A library cannot be deleted if it exists on an active user's library list.

When a job is started, the user portion of the library list is determined by the values contained in the job description or by values specified on the SBMJOB command. A value of *SYSVAL can be specified, which causes the libraries specified by the system value QUSRLIBL to become the user portion of the library list. If you have specified library names in both the job description and the Batch Job (BCHJOB) or SBMJOB command, the library names specified in the BCHJOB or SBMJOB command override both the libraries specified in the job description and the system value QUSRLIBL.

The following shows the order in which the user part of the library list specified in QUSRLIBL is overridden by commands for individual jobs:

Instead of entering the CHGLIBL command each time you want to change the library list, you can place the command in a CL program:

PGM  /* SETLIBL - Set library list */
CHGLIBL LIBL(APPDEVLIB QGPL QTEMP)
ENDPGM

If you normally work with this library list, you could set up an initial program to establish the library list instead of calling the program each time:

PGM  /* Initial program for QPGMR */
CHGLIBL LIBL(APPDEVLIB QGPL QTEMP)
TFRCTL PGM(QPGMMENU)
ENDPGM

This program must be created and the user profile to which it will apply changed to specify the new initial program. Control then transfers from this program to the QPGMMENU program, which displays the Programmer Menu.

If you occasionally need to add a library to the library list specified in your initial program, you can use the ADDLIBLE command to add that library to the library list. For example, the following command adds the library JONES to the end of the library list:

ADDLIBLE LIB(JONES) POSITION(*LAST)

If part of your job requires a different library list, you can write a CL program that saves the current library list and later restores it, such as the following program.

       PGM
       DCL &LIBL *CHAR 2750
       DCL &CMD *CHAR 2760
(1)    RTVJOBA USRLIBL(&LIBL)
(2)    CHGLIBL (QGPL QTEMP)
       .
       .
       .
(3)    CHGVAR &CMD ('CHGLIBL (' *CAT &LIBL *TCAT ')')
(4)    CALL QCMDEXC (&CMD 2760)
       .
       .
       .
       ENDPGM

(1)
Command to save the library list. The library list is stored into variable &LIBL. Each library name occupies 10 bytes (padded on the right with blanks if necessary), and one blank is between each library name.

(2)
This command changes the library list as required by the following function.

(3)
The Change Variable (CHGVAR) command builds a CHGLIBL command in variable &CMD.

(4)
QCMDEXC is called to process the command string in variable &CMD. The CHGVAR command is required before the call to QCMDEXC because concatenation cannot be done on the CALL command.

Considerations for Setting Up a Library List

You should consider the following when setting up a library list and using it:


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