The library list

Libraries are one level deep and do not contain other libraries. The obvious question follows: how does a program find a file if nobody tells it which library it is in?

The answer is the library list: an ordered list of libraries belonging to the job, not to the program. When an object is named without saying where it lives, the system looks through the libraries in the list, one after another, stopping at the first that contains it.

This is where the hierarchy that seemed to be missing went. It is also the origin of nearly every problem that starts with "it works in my environment".

The four parts

The list is not flat: it has four sections, always in this order.

1. System portion. Starts with QSYS and holds the operating system libraries. It is the same for every job and is governed by the system value QSYSLIBL.
2. Product libraries. Up to two, managed by the system when needed. Not yours to touch.
3. Current library. Exactly one, and it is where objects created without saying where end up. Set with CHGCURLIB or from the profile.
4. User portion. The list proper, where the application libraries sit. The default for new jobs is the system value QUSRLIBL, but it is almost always overridden by the job description.

To see your own job's:

DSPLIBL

And any other job's, which is the one you actually need when investigating: WRKJOB on the job, option 2, and there it is.

Where it comes from

And here is where the misunderstandings live. A job does not inherit the library list of whoever launched it. It takes it from its own job description, the *JOBD, and from nowhere else.

So:

• an interactive session has the list its JOBD gives it, often edited by hand during the day with ADDLIBLE;
• a job submitted with SBMJOB takes the one named in the command's JOBD, which is not necessarily the one belonging to the session submitting it;
• a scheduled job takes the one from the schedule entry's JOBD, which nobody ever looks at until something goes wrong.

There is a way to leave nothing to chance, and that is declaring the list on the command that submits:

SBMJOB CMD(CALL PGM(PRODLIB/CLOSE))  +
       JOB(CLOSE)                     +
       JOBD(PRODLIB/BATCHJOBD)        +
       INLLIBL(PRODLIB DATALIB QGPL QTEMP)

The ambiguity risk

If two libraries in the list contain an object with the same name, the first one wins. Silently: no warning, no trace in the job log, no way to notice unless you go looking.

This is how the worst incidents start, because the symptom is not an error but a wrong result. A test file left in a library put at the top of the list "just for a moment" makes the month-end close run against test data, and the program has no way of knowing.

Changing it

For the current job only:

ADDLIBLE LIB(TESTLIB) POSITION(*FIRST)
RMVLIBLE LIB(TESTLIB)
CHGCURLIB CURLIB(MYLIB)

Permanently, by changing the job description jobs take it from:

CHGJOBD JOBD(PRODLIB/BATCHJOBD) +
        INLLIBL(PRODLIB DATALIB QGPL QTEMP)

The limit

The user portion has a limit on the number of libraries, raised across releases to a figure that is generous today. It is not a constraint you meet in practice, and in any case a long list is a problem in its own right: it lengthens the search for every object and multiplies the chances of ambiguity.