The library list controls how IBM i resolves unqualified object names. If a program says CUSTOMER instead of PRODLIB/CUSTOMER, the job’s library list decides which object is found first. That makes the list part of runtime behavior, not just an operator convenience.
This page is a command lookup for inspecting and changing the current job’s list. For the broader concept, read IBM i Libraries, Objects, and Members Explained.
Quick command map
| Task | Command | Changes something? |
|---|---|---|
| Display the current library list | DSPLIBL | No |
| Add one library | ADDLIBLE | Yes, current job |
| Remove one library | RMVLIBLE | Yes, current job |
| Replace the user library list | CHGLIBL | Yes, current job |
| Edit the user library list interactively | EDTLIBL | Yes, current job |
| Change the current library | CHGCURLIB | Yes, current job |
| Retrieve library-list attributes in CL | RTVJOBA | No |
IBM documentation distinguishes the user part, system part, current library and product libraries. The commands here mainly affect the current job.
DSPLIBL
Use DSPLIBL first.
DSPLIBL
Check the order, not just the presence of a library. If TESTLIB appears before PRODLIB, an unqualified lookup can find the test object first.
ADDLIBLE
ADDLIBLE adds a library to the user portion of the current job’s library list.
ADDLIBLE LIB(APPDEVLIB) POSITION(*LAST)
ADDLIBLE LIB(TESTLIB) POSITION(*FIRST)
Use *FIRST only when you really want that library to override objects with the same name in later libraries. You need authority to the library being added.
RMVLIBLE
RMVLIBLE removes a library from the user portion of the current job’s list.
RMVLIBLE LIB(TESTLIB)
If the library is not in the user portion, the command cannot remove it. Removing a library from your interactive job does not remove it from another active job.
CHGLIBL
CHGLIBL replaces the user part of the library list.
CHGLIBL LIBL(APPDEVLIB QGPL QTEMP)
This is common in job setup CL programs because it makes the intended order explicit. It is also easy to overuse: replacing the entire list can remove a library that an earlier setup step added deliberately.
EDTLIBL
EDTLIBL opens an interactive display for the user portion of the list.
EDTLIBL
Use it for investigation and one-time interactive work. For repeatable batch setup, prefer explicit CL such as CHGLIBL or ADDLIBLE.
CHGCURLIB
The current library affects unqualified create commands and some lookups.
CHGCURLIB CURLIB(APPDEVLIB)
Do not confuse current library with the user library list. A job can have a current library and still have many user libraries in order.
Save a list before a temporary change
Use RTVJOBA to retrieve the current user library list before a temporary change.
DCL VAR(&LIBL) TYPE(*CHAR) LEN(2750)
RTVJOBA USRLIBL(&LIBL)
CHGLIBL LIBL(APPDEVLIB QGPL QTEMP)
/* run the work */
This is a CL procedure fragment, not a complete save-and-restore program. DCL and RTVJOBA require a CL program or procedure context; do not paste the fragment into an interactive command line. The 2750-character variable accommodates 250 library names, each in an eleven-character field.
Restoration requires building a CHGLIBL command string and processing it with QCMDEXC, including an error path that restores the list. If you also change the current library, save and restore that attribute too. Follow IBM’s complete save-and-restore example and test the wrapper in a non-production job before using it.
Troubleshooting wrong objects
| Symptom | Check |
|---|---|
| Interactive test works but batch fails | Compare the interactive and batch job library lists |
| Program uses test data in production | Look for test libraries before production libraries |
| Object not found | Confirm library is on the job’s list and the job has authority |
| Wrong file format or level check | Find duplicate file names with WRKOBJ and inspect order |
| Command works from command line but not CL | The CL job may have a different current library or list |
Use IBM i Object and Library Commands Reference to find duplicates and object details.
Common mistakes
- Changing your interactive library list and expecting a running batch job to change.
- Adding a library at
*FIRSTand shadowing production objects. - Replacing the whole list with
CHGLIBLwhen oneADDLIBLEwould be safer. - Forgetting the current library when creates go to the wrong place.
- Testing with qualified names while production uses unqualified names.
Batch job checklist
When a batch job behaves differently from an interactive test, inspect the batch job itself.
| Check | Command path |
|---|---|
| Actual job identity | WRKACTJOB or the submitted job message |
| Job library list | WRKJOB JOB(...) OPTION(*LIBL) |
| Current library | DSPJOB or WRKJOB job attributes |
| Job description | DSPJOBD for the submitted job’s job description |
| Duplicate object names | WRKOBJ OBJ(*ALL/object) OBJTYPE(type) |
Do not fix a batch problem by changing your own session only. Put repeatable setup into the submitting CL program, job description or initial program. Follow your site’s standard for where library-list control belongs.
Where to make a permanent change
| Situation | Better place to change it |
|---|---|
| One interactive test | Your current job |
| One CL wrapper | The CL program before the call |
| Every job submitted through a job description | The job description, after review |
| A sign-on environment | The initial program or user profile design |
| One emergency investigation | The current job, then revert or sign off |
Prefer the narrowest permanent change. A library-list change in a job description can affect many batch jobs, while a CL wrapper change affects only the workload that calls it.
FAQ
Does ADDLIBLE change every job?
No. It changes the library list for the job where the command runs. Another active job keeps its own list.
Is the current library the first library in the list?
No. It is a separate job attribute. It matters especially for unqualified create commands and some lookup behavior.
Why does object order matter?
IBM i searches the library list in order for unqualified names. If two libraries contain an object with the same name and type, the earlier library wins.
Should production programs use qualified names?
Qualified names are clearer for fixed dependencies. Many IBM i applications still rely on library lists for environment switching, so the standard must match the application design.
Summary
- Use
DSPLIBLbefore changing anything. ADDLIBLE,RMVLIBLE,CHGLIBL,EDTLIBLandCHGCURLIBaffect the current job.- Library order matters as much as library presence.
- Batch jobs have their own library lists; inspect the actual job when troubleshooting.