Include files and the QSYSINC library
An Include file is a text file that contains declarations that are used by a group of functions, programs, or users. The system include (QSYSINC) library provides all source include files for APIs that are included with the IBM i operating system.
The QSYSINC library is optionally installed. It is fully supported, which means that you can write an authorized program analysis report (APAR) if you find an error in an include file.
You can install the QSYSINC library by using the GO LICPGM functions of the IBM i operating system. Select the Install Licensed Programs option on the Work with Licensed Programs display and the IBM i System Openness Includes option on the Install Licensed Programs display.
The terms include file and header file are interchangeable and pertain to the contents of the QSYSINC library. These files are intended to be compatible with future releases.
The naming conventions for the include files are the same as either the API program name or the ILE service program name. If both exist, the include file has both names.
The following table lists the include files that are shipped with the QSYSINC library.
Operating environment | Language | File name | Member name (header file) |
---|---|---|---|
Program-based APIs | ILE C 1 | H | API program name |
RPG | QRPGSRC | API program name or API program name with the letter E replacing the initial letter Q for members that contain array definitions | |
ILE RPG | QRPGLESRC | API program name | |
COBOL | QLBLSRC | API program name | |
ILE COBOL | QCBLLESRC | API program name | |
Service-program-based APIs | ILE C | H | Service program name or API program name 2 |
ILE RPG | QRPGLESRC | Service program name or API program name 2 | |
ILE COBOL | QCBLLESRC | Service program name or API program name 2 | |
UNIX-type APIs | ILE C | ARPA | Industry defined |
ILE C | H | Industry defined | |
ILE C | NET | Industry defined | |
ILE C | NETINET | Industry defined | |
ILE C | NETNS | Industry defined | |
ILE C | SYS | Industry defined | |
Notes:
|
Besides the include files for specific APIs, the QSYSINC library also contains the following include files.
File name | Description |
---|---|
QLIEPT and QUSEPT | Allows C language application programs to call program-based APIs directly through the system entry point table. |
QUSGEN | Defines the generic header for the list APIs. |
QUSEC | Contains the structures for the error code parameter. |
Qxx | Provides common structures that are used by multiple APIs (where the xx is the component identifier, for example, QMH, QSY, and so forth). |
The include files that are included with the system define only the fixed portions of the formats. You must define the varying-length fields. The QSYSINC include files are read-only files. If you use a structure that contains one or more varying-length fields, you have two options for defining these varying-length fields. You can copy the include file to your own source file and edit your copy. Uncomment the varying-length fields in your copy of the include file, and specify the actual lengths you want.
Alternatively, if you develop with an ILE language, you can reference the QSYSINC definitions using ILE RPG LIKEDS or ILE COBOL TYPEDEF support in order to define both the fixed- and varying-length portions of structures. When you use a structure as input to an API, initialize the structure in its entirety (typically to x'00', but refer to the specific API documentation for the correct value) before setting specific field values within the structure. This saves you from initializing reserved fields by name because the reserved field name might change in future releases.
An exit program has an include file only when it contains a structure. The member names for exit programs start with the letter E. Except for RPG array definitions for APIs that also start with E, any member names in the QSYSINC library that start with the letter E are include files for exit programs. The QSYSINC member name of these include files is provided in the parameter box for the applicable exit programs.
For development of client-based applications, integrated-file-system symbolic links to QSYSINC openness includes are also provided in the /QIBM/include path.
All source physical files are included with read capabilities only; changes cannot be made to the QSYSINC library. All these files are built with a CCSID of 00037. When you compile a program in a specific CCSID, any QSYSINC include file is converted to the program CCSID.
If you are coding in ILE C, the header files in the QSYSINC library are considered system include files. You should use the < and > symbols on the #include statement; this affects how the library list is used to search for header files.
If you are developing applications on a release n system that will run on a release n-1 system, you might want to copy the include files of each release to user source libraries. This minimizes the impact of include file changes when APIs are enhanced over time with additional fields.