API Call/Macro Extensibility

The Extensibility - API feature allows customers to access an analysis that reflects their usage of in-house or 3rd party APIs, by using a configuration file, instead of waiting for development support. Using JSON configuration files, the user describes how each API\Macro call is interpreted by IBM® AD.

IBM AD Build Client supports API calls only for:
  • COBOL and PL/I programs
  • JCL jobs

For more information about the JCL jobs, see section JCL Call Extensibility Examples in Appendix 4.

API call events can be handled as one of the following types of calls:
  • Data access calls
  • Inner application program calls
  • Cross application calls
Important: The JCL call events can be handled only as inner application program calls.
The following statements are supported for API calls:
  • CALL PROGRAM
  • EXEC CICS LINK PROGRAM
  • EXEC CICS XCTL
  • EXEC PGM (supported only for JCL calls)

To enable the API macro extensibility feature, click Project > Settings > Extensibility, and then select the Enable API/Macro handling by using a configuration file check box. After you click OK, a folder with the name API Config is created.

In the API Config folder, three types of JSON configuration files can be added:
API Config
Specifies the API calls to be analyzed, the API call parameters, and for which one of these parameters, the values are needed.
User Exits Config
Contains a list of API calls and the path to a user exit.

The user exit is a JSON file or a utility that you must create. It contains new resolutions for the API calls. For more information about the user exit JSON files, see section API/Macro Call Extensibility Examples in Appendix 4.

API Dependency
Allows the user to specify a new type of API extension that can be triggered regardless of any source code. By using dependency, the following mappings can be defined:
  • a mapping between programs and generic transactions
  • a mapping between programs and generic maps
For more information about the API Dependency, see section Dependency Extensibility Examples in Appendix 4.

The resolution of the API calls is made by using a module that is called the API Resolver, which uses the User Exists Config JSON configuration file.

Note:
  • After each compilation, a JVME_Post_Compiler.log file is created in directory C:\Users\User_Name\AD\comp\log.
  • The API Config configuration file is validated before each build event and in case errors are found, an error message is displayed and the build stops.

The folder is added as an option after the project is created, so users that do not use the API Macro feature will not get confused.

Annotations

Starting with IBM AD V5.1.0 release, the API Resolver can add annotations on resolutions. The annotations are present in the resolution.json file. For more information, see JCL Call Extensibility Examples and Dependency Extensibility Examples.
Note: Make sure that Annotations Database configurations from IBM AD Configuration Server are set.
Examples of annotations that are added by using the "annText" and "annKeyword" parameters:
  • "annText": "ANNOTATION2" - specifies the text that users want to add as annotation.
  • "annKeyword" : "API_RESOLUTION" - specifies the annotation keyword used by the user to identify specific annotations.

Error Cases Behavior

For any project that contains COBOL sources, before any Build, Build Selection or Make processes, the configuration file validation starts automatically. You can also manually start the validation sequence, by right click JSON file > Validate.

  1. If the JSON file is valid, the following message is displayed:
    Validation of the configuration file from 'API Config' folder has succeeded.
  2. If the user tries to upload more than one API Config type file, the following error message is displayed:
    Only one configuration file of each type can exist in "API Config" folder.
  3. If the JSON file is not valid, an error message is displayed. The error message varies, depending on the error type:
    1. If an empty JSON file is added to the project, the error message is:
      Error parsing data for API Configuration file. Reason: The configuration file from 'API Config' folder is empty.
    2. If the JSON file has a syntactical error in its structure (ex: a missing bracket, an extra comma, and so on) the following error message is displayed :
      Error parsing data for API Configuration file. Reason: At line (line number), column (column number)
      Note: Depending on the syntactical error, Reason can be: not a value, not an array, not an object, not a pair, no colon in pair, not a string.
    3. If one of the keys of the JSON file or their values are incorrect, the following error message is displayed:
      Error parsing data for API Configuration file. Reason: Key '%s' is invalid or has invalid value.
    4. If any mandatory key is missing for the JSON file or its value is unsupported, the following error message is displayed:
      Error parsing data for API Configuration file. Reason: Key '%s' does not exist or has unsupported value.
    5. If the Api/Macro feature is enabled, but no JSON file is added to the project, the following error message is displayed:
      Error parsing data for API Configuration file. Reason: The configuration file from 'API Config' folder is missing.
    6. If the user sets same values for more than one apiKey, the following error message is displayed:
      Error parsing data for API Configuration file. Reason: The key has a duplicated value.
      Note: Same behavior occurs for setting same values for more than one Program "Name" or Parameters "label".
    7. If an error that is not covered by the previously documented situations is encountered, the following default error message is displayed:
      Unknown error type.