APIs for the service-program-based environment

APIs based on service programs are called as procedures exported from ILE service programs (*SRVPGM).

Bindable procedure APIs, exported from ILE service programs (*SRVPGM), are independent of the high-level languages. This can be useful when mixed languages are involved.

Here are some of the functions provided by the service-program-based APIs:

  • Dynamic screen management (DSM)
  • National language support
  • Mail server framework
  • Problem management
  • Programming and control language (CL)
  • Registration facility
  • Source debugger

APIs based on service programs that are defined by IBM use the following naming conventions:

  • Start with the letter Q.
  • Are followed by a 2-, 3-, or 4-character internal component identifier.
  • Can be up to 30 characters.
  • Are case sensitive.

APIs based on service programs that are defined by industry standards follow the industry naming conventions.

ILE service programs (*SRVPGM) use the following naming conventions:

  • Start with the letter Q.
  • Are followed by a 2-, 3-, or 4-character internal component identifier.
  • Are limited to 8 characters.
  • Are uppercase.

Bindable APIs are contained within service programs to which the calling program binds. Some bindable APIs provide a program interface for the original program model (OPM) languages. You can usually distinguish between the *SRVPGM interface and the *PGM interface by the name of the API. For example, the registration facility APIs provide both a program and a service program entry point (procedure) interface. For the Register Exit Point API, the service program entry point interface is named QusRegisterExitPoint and the program interface is named QUSRGPT. A bindable procedure name can be up to 30 characters and mixed uppercase and lowercase. A program interface name can be up to 8 characters and is all uppercase.

A binding directory is used for APIs that are contained in service programs. A binding directory is a list of names of modules and service programs that provides a reference by name and type. Service programs that export bindable APIs are in the QUSAPIBD binding directory. This binding directory is implicitly used by ILE compilers to resolve the bindable API references; therefore, it is not necessary to explicitly name the service program or the API binding directory when you create programs that use bindable APIs. If you provide your own APIs with the same name, make sure that you also provide your own binding directory or service program.

Most APIs (program-based and service-program-based) have a header file supplied by the IBM i operating system. These header files reside in the optionally installable library QSYSINC. The header files provide the prototypes for the API and define any structures that are used by the API. The QSYSINC library is used by the ILE C compiler to search for header files; therefore, it is not necessary to specify a library qualifier for any header files that reside in the QSYSINC library. When you code in ILE C, remember to enclose the header file name in less-than (<) and greater-than (>) symbols because this affects how the library list is processed in locating the header file.

It is typical for an API that is not retrieving information not to return any output to the caller other than the error code parameter. If no errors occur when APIs are used, the requested function is completed successfully.