JCL Call Extensibility Examples
JCL Call Extensibility Use Cases
The purpose of this chapter is to help users understand how the Configuration files must be created in order to integrate their business-specific cases in the analysis.
Case 1. When parameter value is received from DD cards
The purpose of this chapter is to help users understand how the Configuration files must be created in order to integrate their business-specific cases in the analysis.
This use case is created to cover the situation when a JCL Call to an API program is translated
into calls to other programs, based on the parameter value received by the API program in DD cards.
The following represents the JOBSAMPLE JCL
job:
//JOBSAMPLE JOB ,'SAMPLE JCL JOB',
// CLASS=C,
// MSGCLASS=P,
// COND=(4,LT),
// REGION=4096K
//STP010 EXEC PGM=APIJCL
//DDOUT1 DD DSN=PJ.ABC.DATASET1,
// UNIT=(MTLIB,,DEFER),
// DISP=(NEW,KEEP),
// DCB=TRTCH=C,
// LABEL=(,SL),
// VOL=SER=DXXXXX
//APIPARAM DD *
1111 ABC --TEST-- VALUE
//The JOBSAMPLE JCL job contains a call to a specific API program named APIJCL.
To resolve the Call to
"APIJCL", the JCL_Config.json file
specifies that it is necessary to resolve the value of the APIPARAM
parameter.Note: This JSON contains as parameters the corresponding name of the JCL DD card used in
the JCL Call.
{
"info": {
"version": "5.0.4"
},
"extensions":
[
{
"apiKey":"a1",
"name": "APIJCL",
"type": "JclPgmCall",
"parameters":
[
{
"name": "APIPARAM",
"label": "param1",
"resolve": true
}
]
}
]
}The ue-config.json file specifies the type of user exit file and the path
where the user exit file for a certain API is located.
{
"schemaVersion":"1.0.1",
"documentVersion":"1.0.1",
"ueConfig" :[
{"name": "uejson",
"type":"jcl-file-json",
"location":"<C:/IBM AD/Mainframe Projects/DOC_JCL_DEP/API Config/Resolutions/>resolutionJCL.json",
"appliesTo":["a1"]
}
]
}<C:/IBM AD/Mainframe Projects/DOC_JCL_DEP/API
Config/Resolutions/> is the path where the resolutionJCL.json
file is saved. You need to replace it with the actual path where your
resolutionJCL.json file is saved.
The resolutionJCL.json file specifies that, if the value of the received
parameter is "1111 ABC--TEST--VALUE", the JCL Call to
"APIJCL"
is replaced with calls to PROGRAM1 and PROGRAM2 COBOL programs.Note:
- The values of the parameters present in the resolutionJCL.json file must be identical to the values of the corresponding DD cards in the JCL, considering a maximum of 71 characters on the line.
- The values of the DD cards can come either inline
DD *or from a controlled fileDD DSN=<file path>.
The following annotations are present in the resolutionJCL.json file:
- For PROGRAM1 - annotation
"annText": "ANNOTATION1"and annotation keyword"annKeyword" : "API_RESOLUTION". - For PROGRAM2 - annotation
"annText": "ANNOTATION2"and annotation keyword"annKeyword" : "API_RESOLUTION".{ "schemaVersion": "1.0", "documentVersion": "1.0", "entries": [{ "input": { "apiKey": "a1", "apiText": "APIJCL", "params": [{ "value": "1111 ABC --TEST-- VALUE" } ] }, "resolutions": [{ "action": "call", "target": { "resourceType": "CobolProgram", "value": "PROGRAM1", "read": true, "annText": "ANNOTATION1", "annKeyword" : "API_RESOLUTION" }}, { "action": "call", "target": { "resourceType": "CobolProgram", "value": "PROGRAM2", "read": true, "annText": "ANNOTATION2", "annKeyword" : "API_RESOLUTION" }}] } ] }
Case 2. When parameter value is received from PARM attribute
This use case is created to cover the situation when a JCL Call to an API program is translated
into calls to other programs, based on the parameter value received by the API program in the PARM
attribute. The following represents the JOBSAMPLE JCL
job:
//JOBSAMPLE JOB ,'SAMPLE JCL JOB',
// CLASS=C,
// MSGCLASS=P,
// COND=(4,LT),
// REGION=4096K
//STP040 EXEC PGM=APIJCL2,REGION=0M,
// PARM='COBOLPGM1,100,1'
//SYSUT1 DD DSN=ABC.TST,
// DISP=(OLD,KEEP)The JOBSAMPLE JCL job contains a call to a specific API program named APIJCL2.
To resolve the Call to
"APIJCL2", the JCL_Config.json file
specifies that it is necessary to resolve the value of the parameter in the first position from the
PARM attribute of the EXEC statement.{
"info": {
"version": "5.0.4"
},
"extensions":
[
{
"apiKey":"a1",
"name": "APIJCL2",
"type": "JclPgmCallParm",
"parameters":
[
{
"position":1,
"label": "param1",
"resolve": true
}
]
}
]
}The ue-config.json file specifies the type of user exit file and the path
where the user exit file for a certain API is
located.
{
"schemaVersion":"1.0.1",
"documentVersion":"1.0.1",
"ueConfig" :[
{"name": "uejson",
"type":"jcl-file-json",
"location":"<C:/IBM AD/Mainframe Projects/DOC_JCL_DEP/API Config/Resolutions/>resolutionJCL.json",
"appliesTo":["a1"]
}
]
}<C:/IBM AD/Mainframe Projects/DOC_JCL_DEP/API
Config/Resolutions/> is the path where the resolutionJCL.json
file is saved. You need to replace it with the actual path where your
resolutionJCL.json file is saved. The resolutionJCL.json file specifies that, if the value of the received
parameter is COBOLPGM1, the JCL Call to
"APIJCL2" is replaced
with calls to COBOLPGM1 COBOL program.Note: The values of the parameters
present in the resolutionJCL.json file must be identical to the value of the
corresponding parameter in the PARM attribute.
For COBOLPGM1, the
"annText": "JCL1PARM" annotation and
"annKeyword" : "activityJCL" annotation keyword are present in the
resolutionJCL.json
file:{
"schemaVersion": "1.0",
"documentVersion": "1.0",
"entries": [{
"input": {
"apiKey": "a1",
"apiText": "APIJCL2",
"params": [{
"value":"COBOLPGM1"
}
]
},
"resolutions": [{
"action": "call",
"target": {
"resourceType": "CobolProgram",
"value": "COBOLPGM1",
"read": true,
"annText": "JCL1PARM",
"annKeyword" : "activityJCL"
}}]
}
]
}JSON Schemas
The API_Config.json schema, present in API/Macro Call Extensibility Examples introduces a new API type
"type":"JclPgmCall".
The ue-config.json schema, present in API/Macro Call Extensibility Examples introduces a new API type
"type":"jcl-file-json".
Schema for JCL
resolutionJCL.json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"version": "1.0.0",
"type": "object",
"description": "The json schema for a jcl-json based AD resolutions.",
"properties": {
"schemaVersion": {
"description": "This json schema version.",
"$ref": "#/definitions/versionDef"
},
"documentVersion": {
"description": "The user exit json file version.",
"$ref": "#/definitions/versionDef"
},
"entries": {
"type": "array",
"description": "An array containing the user exit content.",
"items": {
"type": "object",
"description": "A user exit content object.",
"properties": {
"resolutions": {
"type": "array",
"description": "An array which contains the user exit resolution objects.",
"items": { "$ref": "#/definitions/callLocalResolutionDef" }
},
"input": {
"type": "object",
"description": "An object which contains the inputs for the user exit.",
"properties": {
"apiKey": {
"type": "string",
"description": "The parameter key as defined in the JCLAPI config json."
},
"apiText": {
"type": "string",
"description": "The name of the API program as defined in the JCLAPI config json."
},
"params": {
"type": "array",
"description": "An array of 'value' objects definitions. The number and the order of the items MUST be the same with the number and the order of the parameters defined in the API config json",
"items": {
"anyOf": [
{
"$ref": "#/definitions/paramValue"
},
{
"$ref": "#/definitions/directValue"
}
]
}
}
},
"required": [
"apiKey",
"params"
],
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"resolutions",
"input"
]
}
}
},
"required": [
"entries",
"schemaVersion",
"documentVersion"
],
"definitions": {
"versionDef": {
"type": "string",
"description": "A schema/document versioning pattern.",
"pattern": "^[0-9]{1,3}\\.[0-9]{1,3}(\\.[0-9]{1,3})?$"
},
"paramValue": {
"type": "object",
"description": "A generic 'value' object which allows the user exit to define values for the resolution or the input values with references to the paramKey.",
"properties": {
"paramKey": {
"type": "string",
"description": "The parameter key as defined in the API config json file."
},
"paramMode": {
"type": "string",
"description": "A marker which defines how the parameter value is read by the resolver.",
"enum": [
"byValue",
"byRef"
]
}
},
"additionalProperties": false,
"required": [
"paramKey",
"paramMode"
]
},
"directValue": {
"type": "object",
"description": "A generic 'value' object which allows the user exit to define values for the resolution or the input values without referering to a specific paramKey.",
"properties": {
"value": {
"type": "string",
"description": "The value for this 'value' object."
}
},
"additionalProperties": false,
"required": [
"value"
]
},
"resourceTypeDef": {
"type": "object",
"description": "An object which will contain a resource type definition for resolutions.",
"properties": {
"read": {
"type": "boolean",
"description": "A marker for the resource behavior (true: the resource is read, false - the resource is written.)"
},
"resourceType": {
"type": "string",
"description": "The resource type",
"enum": [
"CobolProgram",
"PL/1Program",
"AssemblerProgram"
]
},
"paramKey": {
"type": "string",
"description": "The parameter key as defined in the JCLAPI config json file."
},
"paramMode": {
"type": "string",
"description": "A marker which defines how the parameter value is read by the resolver.",
"enum": [
"byValue",
"byRef"
]
},
"qualifiers": {
"type": "array",
"description": "An array of strings. The strings will be used to qualify the resource.",
"items": {
"type": "string",
"description": "A string qualifier."
}
},
"value": {
"type": "string",
"description": "A string value for the resource type."
},
"annText": {
"type": "string",
"description": "A string which defines the key of the annotation."
},
"annKeyword": {
"type": "string",
"description": "A string which defines the text of the annotation."
}
},
"additionalProperties": false
},
"targetDef": {
"description": "The targeted resource (if any). Will be deprecated in the next versions.",
"$ref": "#/definitions/resourceTypeDef"
},
"callLocalResolutionDef": {
"properties": {
"action": {
"enum": [
"call"
]
},
"target": {
"$ref": "#/definitions/targetDef"
}
},
"additionalProperties": false,
"required": [
"action",
"target"
]
}
}
}