API concepts

Describes the underlying concepts that you need to understand to work effectively with APIs. Among the concepts covered are basic concepts, programming considerations, and terminology.

An application programming interface (API) is defined as 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.

APIs allow you to:

• Provide better performance when getting system information or when using system functions provided by control language (CL) commands or file support.
• Use system information and functions that are not available through CL commands.
• Use calls from high-level languages to these interfaces.
• Access to system functions at a lower level than what was initially provided on the system.

Finally, data is often easier to work with when returned to you by an API.

For information about using APIs, see the following:

• About application programming interfaces (APIs)
  Describes most of the iSeries™ application programming interfaces (APIs), as well as some APIs for related products that can be used on iSeries™ servers.
• API terminology
  Before using the iSeries™ APIs, you should be familiar with several terms. These terms refer to i5/OS™ objects.
• Generic library names
  These special values refer to i5/OS™ libraries, and you can often use them in API calls in place of specific library names.
• OPM and ILE API verbs and abbreviations
  The two to three letters following the APIs make up an internal component identifier. The last part of the API name identifies the action or function of the API. The information after the component ID is an abbreviation of the verb that describes the function of the API.
• Language selection considerations
  You can use APIs with all the languages available on iSeries™ business computing systems, except for the ILE APIs.
• API environments
  This topic introduces the operating environments that i5/OS™ APIs exist on a system.
• API information format
  API names contain verbs that are similar to the i5/OS™ licensed program: change, create, remove, and retrieve.
• API parameters
  After you have found the API that you want to use, you need to code a call to an API and pass to the API the required set of parameters appropriate for that API.
• Include files and the QSYSINC library
  The QSYSINC (system include) library provides all source includes for APIs shipped with i5/OS™.
• Internal object types
  This topic provides the i5/OS™ internal object types and their corresponding predefined values.
• Data types
  APIs support character data and binary data.
• Internal identifiers
  You know of jobs, spooled files, and so forth, by their names. The system uses an ID that is associated with the name. The ID is assigned based on usage.
• User spaces and receiver variables
  APIs that return information to a caller generally return the information in a user space (used by list APIs) or a receiver variable (used by retrieve APIs).
• Continuation handle
  Some APIs that return information offer a continuation handle.
• List APIs overview
  List APIs return a list unique to a given API. The section discusses the characteristics of a list API and provides information that you should be aware of when you use list APIs.
• Domain concepts
  All objects are assigned a domain attribute when they are created.
• Exit programs
  Exit programs are called and given control by an application program or system program. They can be used to customize particular functions to your needs. An exit program is a program to which control is passed from a calling program.
• User index considerations
  The performance of a user index is much better than that of a database file. However, before using a user index, you must know the functional differences between a user index and a database file.
• Performance considerations
  The retrieve APIs allow you to control the performance cost for information you retrieve.
• APIs and internal system objects
  APIs retrieve information from internal 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 path name format is common across application programming interfaces that work with objects that are supported across file systems. These APIs require a path name to identify the object with which the API will work.