API concepts

An application programming interface (API) is a functional interface supplied by the operating system or a separately orderable licensed program that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program.

Some APIs provide the same functions as control language (CL) commands and output file support. Some APIs provide functions that CL commands do not. Most APIs work more quickly and use less system overhead than the CL commands.

API use has the following advantages:

APIs provide better performance when getting system information or when using system functions that are provided by CL commands or output file support.
APIs provide system information and functions that are not available through CL commands.
You can use calls from high-level languages to APIs.
You can access system functions at a lower level than what was initially provided on the system.
Data is often easier to work with when returned by an API.

API terminology
Before using the IBM i APIs, you need to understand several terms that refer to IBM i objects.
Generic library names
These special values refer to IBM i libraries. You can often use them in API calls in place of specific library names.
API naming conventions
Program-based APIs and service-program-based APIs follow similar naming conventions.
Language selection considerations
You can directly use APIs, other than service-program-based APIs, with all the languages that are available with the IBM i operating system.
Types of APIs
IBM i APIs exist in several operating environments on a system.
API information format
The format of the IBM i API information includes sections such as parameters, authorities and locks, required parameter group, format, field descriptions, and error messages.
API parameters
After you decide which API to use, you need to code a call to the API and pass to the API the set of parameters that are appropriate for it.
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.
Internal object types
Internal objects are used to store the information needed to perform some system functions. The table shows the predefined values for all the IBM i internal object types.
Data types and APIs
APIs support character data and binary data.
Internal identifiers
Several APIs either require or allow you to use an internal identifier (ID) to identify an external name. When you use an internal ID, the processing can be faster because the system does not need to convert the external name to the internal ID.
User spaces and receiver variables
List APIs return information to user spaces, and retrieve APIs return information to receiver variables.
Continuation handle
When a call to an API is made and the API has more information to return than what can fit in the receiver variable or the user space, the API returns a continuation handle, which is used to mark the last value put in the receiver variable or the user space.
List APIs overview
List APIs return a list of information. They use a common generic header to provide information such as the number of list entries and the size of a list entry. The content of the list is unique to each API.
Domains
A domain is a characteristic of an object that controls how programs can access the object. All objects are assigned a domain attribute when they are created.
Exit programs
An exit program is a program to which control is passed from a calling application program or system program. Exit programs can be used to customize particular functions to your needs.
User index considerations
In IBM i APIs, a user index is an object that provides a specific order for byte data according to the value of the data. A user index has better performance than a database file. However, before using a user index, you must know its functional differences from a database file.
Performance considerations
The format specified for an API influences the performance cost of the API. In general, when more information is returned, the performance is slower.
APIs and system objects
APIs retrieve information from system objects.
Open list information format
The format of the open list information is common across many of the open list APIs.
Path name format
The APIs that work with objects supported across file systems use a common path name format to identify the objects.

Parent topic: Application programming interfaces