IBM i does not organize its data and programs as a tree of folders and files. It uses an object-based model in which every item on the system is an object of a specific type, and objects live in libraries. Once this model is clear, commands, security, backups and SQL naming all make more sense.
The Three Terms
- A library is an object of type
*LIBthat holds other objects. It is the main way work is grouped: application programs, production data, test data and utilities usually live in different libraries. - An object is any named item the system manages: a program (
*PGM), a file (*FILE), a data area (*DTAARA), a data queue (*DTAQ), a command (*CMD), an output queue (*OUTQ), a job queue (*JOBQ), a user space (*USRSPC) and many more. Every object has a name, a library and a type, and the type decides which operations are allowed on it. - A member is a named part of a physical file. A source physical file holds one member per source program. A data physical file normally has a single member that holds the records.
A full object name is therefore LIBRARY/OBJECT, and the type matters: the library ORDERS can hold a *FILE called CUSTOMER and a *PGM called CUSTOMER at the same time.
Libraries Are Not Folders
A library looks like a folder at first, but there are differences that matter in practice:
- Libraries are flat. A library cannot contain another library (the exception is the system library
QSYS, which holds all the others). - Names are short: up to 10 characters.
- A library carries authority, a description and a default for new objects, which affects security.
- Programs find objects through the library list rather than through a path.
Some libraries are supplied by IBM and should be left alone, for example QSYS (system objects), QGPL (general purpose objects), and QTEMP, a private temporary library that exists for each job and disappears when the job ends.
Members and Source Files
A source file is a physical file whose records are lines of source, and each source member is one program’s source:
/* A library, a source file and a member for an RPG program */
CRTLIB LIB(DEMOLIB) TEXT('Demo library')
CRTSRCPF FILE(DEMOLIB/QRPGLESRC) RCDLEN(112) TEXT('RPG source')
ADDPFM FILE(DEMOLIB/QRPGLESRC) MBR(HELLO) SRCTYPE(RPGLE) TEXT('Hello program')
Source files are conventionally called QRPGLESRC (RPG), QCLLESRC (CL), QDDSSRC (DDS) and so on, and the member’s source type (RPGLE, CLLE, PF) tells editors and compilers what the code is. Compiling the member DEMOLIB/QRPGLESRC,HELLO creates a program object, DEMOLIB/HELLO of type *PGM. The member and the program are different things: the member is the source, and the object is what runs.
Modern teams increasingly keep source as stream files in the IFS under Git, but source physical files and members are still everywhere in existing systems.
The Library List
When a command or program refers to an object without a library, IBM i searches the library list for it. The list is per job and has four parts: the system part, the product part, the current library, and the user part.
/* Show the library list of this job */
DSPLIBL
/* Put DEMOLIB at the front of the user part */
ADDLIBLE LIB(DEMOLIB) POSITION(*FIRST)
/* Set the current library, where new objects are created by default */
CHGCURLIB CURLIB(DEMOLIB)
Because the first match wins, library list order decides which version of an object runs. Two classic production problems are a test library ahead of the production library, and an object that exists in two libraries. Qualify the library (CALL PGM(PRODLIB/ORDENTRY)) when it matters.
Finding Things
CL commands:
/* Work with objects in a library */
WRKOBJ OBJ(DEMOLIB/*ALL) OBJTYPE(*ALL)
/* Describe one object, including its size, owner and creation date */
DSPOBJD OBJ(DEMOLIB/HELLO) OBJTYPE(*PGM) DETAIL(*FULL)
/* Print every object in a library */
DSPOBJD OBJ(DEMOLIB/*ALL) OBJTYPE(*ALL) OUTPUT(*PRINT)
SQL, through IBM i services, is easier to filter and save:
-- The objects in a library, with their types
SELECT OBJNAME, OBJTYPE, OBJOWNER, OBJCREATED
FROM TABLE (QSYS2.OBJECT_STATISTICS('DEMOLIB', '*ALL')) AS X
ORDER BY OBJTYPE, OBJNAME;
-- This job's library list
SELECT ORDINAL_POSITION, SCHEMA_NAME, TYPE
FROM QSYS2.LIBRARY_LIST_INFO
ORDER BY ORDINAL_POSITION;
How SQL Sees the Same Things
Db2 for i is built into the same object model, so SQL words map onto objects:
| SQL | IBM i |
|---|---|
| Schema or collection | Library |
| Table | Physical file |
| View, index | Logical file |
| Row | Record |
| Column | Field |
A table created with CREATE TABLE is a *FILE object in a library, and you can list it with WRKOBJ or DSPOBJD.
Why It Matters
- Security is applied per object, so knowing the object and its library is the first step to fixing “not authorized” problems.
- Backups are organized by library and object (
SAVLIB,SAVOBJ). - Deployments move objects between libraries, and the library list decides which one a job uses.
- Troubleshooting often means asking “which library did this resolve to?”
A Worked Example: “Which Program Is Running?”
A frequent support question is “I changed the program, but the old behaviour is still there.” The object model gives a method for answering it:
- Check the library list of the job that ran the program with
DSPLIBL, or from SQL withQSYS2.LIBRARY_LIST_INFO. - Find every copy of the object with
WRKOBJ OBJ(*ALL/ORDENTRY) OBJTYPE(*PGM). It lists the same program name in every library the user may see. - Compare their creation dates with
DSPOBJD OBJ(PRODLIB/ORDENTRY) OBJTYPE(*PGM) DETAIL(*FULL)and the same for the other library. - Look at the order of the libraries in the list. The first library that holds a
*PGMnamedORDENTRYis the one that runs.
The fix is either to compile into the right library, to remove the stale copy, or to change the library list the job uses (often set in the user’s job description, JOBD, as the initial library list). Qualifying the call, CALL PGM(PRODLIB/ORDENTRY), removes the ambiguity but hides the underlying drift, so find the second copy as well.
The same method applies to files. A program that reads CUSTOMER through the library list reads the first CUSTOMER file it finds, which is why test programs sometimes read production data and the reverse.
Naming Habits That Help
- Keep application code, data and utilities in separate libraries, so each can be saved, secured and replaced on its own.
- Use a consistent prefix, for example
APPfor programs andAPPDTAfor data, so a library name tells you what it holds. - Keep source and objects in different libraries from production data, and copy objects between libraries as part of a deployment.
- Avoid depending on
QGPLfor application objects. It is shared and is replaced during some system upgrades.
Common Mistakes
- Treating a library as a folder and creating deep hierarchies in it. Use several libraries instead.
- Forgetting the library list when a program “works in test but not in production”.
- Confusing a source member with the compiled program object.
- Putting application work in
QGPLorQTEMPon purpose rather than by accident.
Summary
An IBM i library is a flat container for objects, every object has a type that decides what you can do with it, and members are the named parts of physical files, most visibly source members. Programs find objects through the library list, and Db2 for i uses the same objects under SQL names. Learn the five commands DSPLIBL, ADDLIBLE, WRKOBJ, DSPOBJD and CRTLIB, and the OBJECT_STATISTICS service, and most “which object is this?” questions answer themselves.
Next Steps
The same object model carries over to the Integrated File System, which holds stream files and directories next to the library-based file system. For the language that works on these objects day to day, read CL Programming Explained, and for the data inside them, Db2 for IBM i Explained.