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.
- COBOL and PL/I programs
- JCL jobs
For more information about the JCL jobs, see section JCL Call Extensibility Examples in Appendix 4.
- Data access calls
- Inner application program calls
- Cross application 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 , 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.
- 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
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.
- 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
"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 .
- If the JSON file is valid, the following message is
displayed:
Validation of the configuration file from 'API Config' folder has succeeded.
- 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.
- If the JSON file is not valid, an error message is
displayed. The error message varies, depending on the error type:
- 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.
- 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. - 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.
- 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.
- 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.
- 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". - If an error that is not covered by the previously documented situations is encountered, the
following default error message is displayed:
Unknown error type.
- If an empty JSON file is added to the project, the
error message
is: