Differences between program-based APIs and service-program-based APIs

Program-based APIs and service-program-based APIs are different in API names, parameters, error conditions, and pointer use.

APIs based on service programs include the UNIX-type APIs and the ILE Common Execution Environment (CEE) APIs. You must have the ILE language compiler on your system to develop applications that use any bindable APIs.

The following table shows the differences between program-based APIs and service-program-based APIs.

Table 1. Comparison of program-based and service-program-based APIs
Description	Program APIs	Bindable APIs
API name	Maximum number of characters: 8. Not case sensitive.	Maximum number of characters: 30. Case sensitive.
Required parameters¹	Displayed in the parameter box.	Displayed in the parameter box.
Optional parameters	Can include optional parameters. The optional parameters form a group. You must either include or exclude the entire group.	No optional parameters.
Omitted parameters	No omitted parameters.	Can include omitted parameters. When these parameters are omitted, you must pass a null pointer.
Error conditions²	The error code parameter is common to most of the program-based APIs. It is used to return error codes and exception data to the application. The errors that are returned for a given API are in the form of an error message and a 7-character message identifier.	The error code parameter is common to most of the bindable APIs whose names start with the letter Q. The ILE CEE APIs use feedback codes and conditions. The UNIX-type APIs generally use errnos to provide error-related information.
Pointers	Can be used, but are used less frequently than with the bindable APIs.	Because of the greater availability of pointer support in ILE languages, there is a much greater use of pointers in the bindable APIs. The use of pointers can provide a performance advantage.
Notes: The UNIX-type APIs include parameters in a syntax box. Error conditions The UNIX-type APIs use errnos and return values. The Dynamic Screen Manager (DSM) supports returned values in addition to the error code parameter. The errnos are provided as include files in the QSYSINC library.

In the examples that follow, a program-based API and a service-program-based API are used to perform similar functions (log or report software errors). The bindable API uses pointers while the program API does not. Both APIs log software errors by using first-failure data capture (FFDC).