Common API programming errors

Provides information about common programming errors, as well as examples of correct and incorrect coding.

This topic contains information about common programming errors encountered when using APIs within application programs. The topic provides two program examples for each common error. The first program example is incorrectly coded and is followed by the correctly coded example. If you encounter errors or problems while working with APIs, these examples may provide ideas or solutions.

IBM grants you a nonexclusive copyright license to use all programming code examples from which you can generate similar function tailored to your own specific needs.

SUBJECT TO ANY STATUTORY WARRANTIES WHICH CANNOT BE EXCLUDED, IBM, ITS PROGRAM DEVELOPERS AND SUPPLIERS MAKE NO WARRANTIES OR CONDITIONS EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT, REGARDING THE PROGRAM OR TECHNICAL SUPPORT, IF ANY.

UNDER NO CIRCUMSTANCES IS IBM, ITS PROGRAM DEVELOPERS OR SUPPLIERS LIABLE FOR ANY OF THE FOLLOWING, EVEN IF INFORMED OF THEIR POSSIBILITY:

1. LOSS OF, OR DAMAGE TO, DATA;
2. SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES, OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES; OR
3. LOST PROFITS, BUSINESS, REVENUE, GOODWILL, OR ANTICIPATED SAVINGS.

SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO SOME OR ALL OF THE ABOVE LIMITATIONS OR EXCLUSIONS MAY NOT APPLY TO YOU.

• Use the error code parameter
  The examples in this topic present a program used for creating a user space.
• Define data structures
  When a data structure is defined for use with an API, the structure must be built to receive what the API returns.
• Examples: Define receiver variables
  When defining receiver variables, the most common error is to create them too small for the amount of data that they are to receive. Both of these example programs are coded in RPG and, when run, list all active jobs on the system.
• Define list entry format lengths
  The example programs in this topic show how to code flexibility into your program as it works its way through the formats used by an API.
• Use null pointers with OPM APIs
  Many programmers, especially those with a C programming background, view ignored parameters and NULL parameters as being the same. This expectation can lead to unexpected results when OPM-based APIs are used.
• Define byte alignment
  Correct byte alignment ensures that data used with an API is correct. Byte alignment is also essential when APIs are used to retrieve and then print or display data.
• Using offsets in a user space
  An offset indicates the point in a structure that specific information should start. When offsets are correctly used, programs can extract specific pieces of data from a structure and perform actions on that data.
• Code for new function
  The example programs in this topic create a list of all objects that adopt authority and then process the objects based on their object type.