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.

Parameters can be:

• Required: All of the parameters in the specified order
• Optional: All or none of the parameters within the optional group. You must either include or exclude the entire group; you cannot use just one of these parameters by itself. In addition, you must include all preceding parameters.
• Omissible: The parameters can be omitted. When these parameters are omitted, you must pass a null pointer.

For OPM and ILE APIs, the values for all parameters that identify objects on the system must be in *NAME (basic name) format, left-justified, uppercase, and with valid special characters. (The *NAME format is a character string that must begin with an alphabetic character (A through Z, $, #, or @) followed by up to 9 characters (A through Z, 0 through 9, $, #, @, ), or _). The system uses an object name as is, and it does not change or check the object name before locating the object. This improves the performance of the API. An incorrect name usually results in an Object not found error.

• Passing parameters
  In an OPM or ILE call, a parameter is an expression that represents a value that the calling application passes to the API specified in the call.
• Input and output parameters
  API parameters can be used for input or output. Some parameters contain both input and output fields; these are identified as input/output (I/O) parameters in the API parameter tables.
• Offset values and lengths
  You can make use of the offset values and lengths returned by the API to step through the list when using an API.
• Offset versus displacement considerations for structures
  You will find the terms offset and or displacement in some of the APIs. For example, the Retrieve Data Queue Message (QMHRDQM) API uses offset; the List Objects (QUSLOBJ) API uses displacement.
• Error code parameter
  An API error code parameter is a variable-length structure that is common to all of the system APIs.