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.

Table 1. Include files shipped with the QSYSINC library
Operating environment	Language	File name	Member name (header file)
Program-based APIs	ILE C ¹	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 ²
	ILE RPG	QRPGLESRC	Service program name or API program name ²
	ILE COBOL	QCBLLESRC	Service program name or API program name ²
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: ILE CEE APIs are included in this part of the table. The API can be either bindable when you use the service program name or callable when you use the API program name.

Besides the include files for specific APIs, the QSYSINC library also contains the following include files.

Table 2. Other include files in the QSYSINC library
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.