In the world of IBM i systems, copybooks and includes are the dynamic duo of programming, especially in the realms of RPG (Report Program Generator), CL (Control Language) and COBOL (Code Language for Old Blokes). They're like the trusty sidekicks helping coders save the day, one line of code at a time!
What is a copybook?
A copybook is a pre-written set of code that can be included in a program to perform a specific function or set of functions. Copybooks typically contain a set of definitions, such as data structures, constants, or subroutines, that can be used by multiple programs. They are often used to standardize code and reduce duplication.
In RPG and CL, copybooks are usually stored as separate source files with a .rpgleinc or .clleinc extension. These files contain the shared code that can be included in multiple programs.
How do we use copybooks?
Put simply, we just /include or /copy the shared code to suck it into our programs.
An include is a directive that tells the compiler to insert the contents of a copybook or another source file into the current program. Includes are used to incorporate the shared code from a copybook into a program.
In RPG and CL, includes are typically specified using the /COPY or /INCLUDE directive, followed by the name of the copybook or source file to be included. The compiler then inserts the contents of the specified file into the program.
For example, in RPG, a traditional LIBRARY/FILE include might look like this:
This directive tells the compiler to include the contents of the MYCOPYBOOK copybook, which is stored in the QCPYSRC source file.
Alternatively, a traditional IFS include might look like this:
This directive tells the compiler to include the contents of the a_copybook_in_the_ifs.rpgleinc copybook, which is stored in the /home/copybooks IFS folder.
In the world of IBM i programming, 'includes' are like the secret sauce. They let you sneak in copybooks and other source files—think header files or macro definitions—into your code. It's like having a library of coding shortcuts at your fingertips, ensuring everything is neat, tidy, and as standardized as grandma's secret cookie recipe.
Copybooks in VS Code for IBM i?
Since we will be using VS Code for local development on our home PC - how does it allow the references to copybooks within our project?
First, we create a folder in your workspace which will hold the copybook source files. I tend to use a standard name of 'includes' for my folder, but you can call it anything:
Note - we have a Rules.mk file in the includes folder but it is blank/empty because we do not want to compile any of these source files.
Second, we update the project Rules.mk files to add the includes folder to the folder list that it is aware of:
How does VS Code for IBM i resolve the copybook locations?
VS Code for IBM i supports the use of a "copybook repository" which is a centralized location where all the copybooks are stored. This can simplify the process of managing copybooks and make it easier to resolve copybook locations.
You define your copybook repository by adding them to your incolude paths in the Project Explorer:
You do NOT need to qualify the location of the copybooks in your CL and RPG code. You just name the copybook itself and the BOB compiler will take care of the include path being added to the copybook at time of compilation.
Next - Let's look at how to define some CL and RPGLE copybooks and include them in some code examples.