Components of an API
Each API has a library, a parameter definition, and an execute subroutine.
-
A library contains the call to the API. For the APIs described in this manual, the library is usually defined in a procedure division library (pdlib) file.
-
A parameter definition contains the definition of the parameters that the API uses. For most of the APIs in this manual, the parameters are defined in the working storage (wslib) source file.
-
An execute subroutine is the procedure name of the API performed by the program that requests the API.
Each API has input and output parameters. The input and output parameter specification consists of a field name, a field type, and a description.
-
The Field Name value is the parameter name that the called program recognizes.
-
The Type field lists the parameter field type, followed by the parameter field size. The parameter field size includes the field length, the number of decimal positions, and a sign indicator.
-
The Description field describes the field, has a value list, and indicates if the field is required.
The following sections provide details of the conventions used in the API descriptions.
Field Type Conventions
The following table defines the types of fields allowed in an API.
| A field type of | Means the field is |
|---|---|
| N | Numeric |
| A | Alphanumeric |
Field Size Conventions
The following table defines the conventions used to specify a field size for an API.
| A field size of | Means the field is |
|---|---|
| 3 | 3 characters long. |
| 7,5 | 7 characters long; 5 of the 7 characters are decimal positions. |
| S15,2 | 15 characters long, 2 of the 15 characters are decimal positions, and a sign is allowed, which means the field can be positive or negative. |
Field Examples
The following table lists examples of field specifications for APIs.
| A field value of | Means the field is |
|---|---|
| A 5 | Alphanumeric; 5 characters long |
| N 4 | Numeric; 4 characters long; no decimal positions |
| N 5,5 | Numeric; 5 characters long; all are decimal positions |
| N S15,2 | Numeric; 15 characters long; 2 of the 15 characters are decimal positions; the field can be positive or negative. |