Generating call chain analysis results by using API URLs

About this task

The call chain web service runs on the Liberty server. After the call chain REST API is enabled, you can run requests to generate call chain analysis results by using URLs with other tools, for example, Postman.
  • For more information about call chain analysis in IBM® AD Analyze Client, see section Miscellaneous Reports.
  • For more information about callgraph analysis in IBM AD Analyze Client, see Graphs.
Note:

In case Authentication Server (DEX) is configured and running, a token that is generated from DEX will be required to send in the header of any request that is made to the call chain REST API. The token needs to be placed in the Authorization header as Bearer <dex_token>. For example, curl -H "Authorization: Bearer YWxpY2U6c2VjcmV0" http://localhost:9080/callchain/programs?project=projectName

Procedure

Enter one of the following endpoints with the corresponding request body, and select the corresponding request method.
  • To conduct call chain analysis for one or more programs, you can use the following endpoint. Details can be specified in the request body.
    callchain (POST method)
    libertyURL/callchain/
    Example
    http://localhost:9080/callchain/
    The endpoint returns a JSON response with the call chain analysis based on a JSON that is sent in the request body as the input that follows this schema.
    {
    	"$schema": "http://json-schema.org/draft-04/schema#",
    	"description": "The programs input schema for the callchain analysis API.",
    	"type": "object",
    	"properties": {
    		"direction": {
    			"type": "string",
    			"description": "A marker that specifies if the analysis is for usages or references.",
    			"enum": [
    				"forward",
    				"backward"
    			]
    		},
    		"projectName": {
    			"type": "string",
    			"description": "The name of the project on which the analysis will be made."
    		},
    		"depth": {
    			"type": "integer",
    			"description": "The level of how far the analysis will check a program for usages/references"
    		},
    		"programsList": {
    			"type": "array",
    			"description": "An array which contains the programs for the analysis.",
    			"items": [
    				{
    					"type": "object",
    					"properties": {
    						"prgName": {
    							"type": "string",
    							"description": "The name of a program."
    						},
    						"prgType": {
    							"type": "string",
    							"description": "The type of a program."
    						}
    					},
    					"required": [
    						"prgName",
    						"prgType"
    					]
    				}
    			]
    		}
    	},
    	"required": [
    		"direction",
    		"projectName",
    		"depth",
    		"programsList"
    	]
    }
    Request body
    {
        "direction" : "forward",
        "projectName" : "Regression",
        "depth" : "3",
        "programsList" : [
            {
                "prgName" : "DACI",
                "prgType" : ""
            },
            {
                "prgName" : "ZZCU0013",
                "prgType" : "COBOL"
            },
            {
                "prgName" : "DACD",
                "prgType" : ""
            },
            {
                "prgName" : "ABDRAC01",
                "prgType" : ""
            },
            {
                "prgName" : "COBMOD1",
                "prgType" : ""
            },
            {
                "prgName" : "U11RHC",
                "prgType" : "ASSEMBLER"
            },
            {
                "prgName" : "BONOUTOT",
                "prgType" : ""
            }
        ]
    }
    
    Response
    {
        "longestChainLength": 3,
        "noOfPrgsNeverCalled": 3,
        "prgsDetails": [
            {
                "chains": [
                    "DACI<-NCP-ENTER-RP<-DAKL<-NCD-PF9-RP"
                ],
                "noOfChains": 1,
                "prgName": "DACI",
                "type": "ADS Dialog"
            },
            {
                "chains": [
                    "ZZCU0013:UTCBTRC<-ZZCU0013",
                    "ZZCU0013:UTCOTRC<-ZZCU0013",
                    "ZZCU0013:UTMSDEV<-ZZCU0013:UTCBTRC<-ZZCU0013",
                    "ZZCU0013:UTMSDEV<-ZZCU0013:UTCOTRC<-ZZCU0013",
                    "ZZCU0013:UTMSTRC<-ZZCU0013:UTCBTRC<-ZZCU0013",
                    "ZZCU0013:UTMSTRC<-ZZCU0013:UTCOTRC<-ZZCU0013"
                ],
                "noOfChains": 6,
                "prgName": "ZZCU0013",
                "type": "COBOL"
            },
            {
                "chains": [
                    "ABDRAC01<-ACRFUTST<-ZZCU0013:UTCBTRC<-ZZCU0013"
                ],
                "noOfChains": 1,
                "prgName": "ABDRAC01",
                "type": "COBOL"
            },
            {
                "chains": [
                    "U11RHC:DTGDGBI<-U11RHC:GCBIAS",
                    "U11RHC:SCAN<-U11RHC:DTGDGBI<-U11RHC:GCBIAS",
                    "U11RHC:SCAN<-U11RHC:FNDREAN"
                ],
                "noOfChains": 3,
                "prgName": "U11RHC",
                "type": "ASSEMBLER"
            }
        ]
    }
    
  • To conduct call chain analysis for one program per request, you can use the following endpoint. No request body is required. If the program type (prgType) is not specified for a program, analysis for all the programs with that name (prgName) will be returned.

    callchain/withParameters (GET method)

    libertyURL/callchain/withParameters?
    direction=callchainDirection
    &projName=projectName
    &depth=depthNumber
    &prgName=programName
    &prgType=programType
    Example
    http://localhost:9080/callchain/withParameters?
    direction=forward
    &projName=Regression
    &depth=3
    &prgName=ZZCU0013
    &prgType=COBOL
    The endpoint returns a response that follows this schema.
    {
    	"$schema": "http://json-schema.org/draft-04/schema#",
    	"description": "The output schema for the callchain analysis API.",
    	"type": "object",
    	"properties": {
    		"longestChainLength": {
    			"type": "integer",
    			"description": "The length of the longest chain."
    		},
    		"noOfPrgsNeverCalled": {
    			"type": "integer",
    			"description": "The number of programs that are never called or that are never calling other program."
    		},
    		"prgsDetails": {
    			"type": "array",
    			"description": "The result list with details for each program returned by the callchain analysis.",
    			"items": [
    				{
    					"type": "object",
    					"properties": {
    						"chains": {
    							"type": "array",
    							"description": "The list of chains returned for a program which shows the usages or references that a program has.",
    							"items": [
    								{
    									"type": "string",
    									"description": "A chain of a program."
    								}
    							]
    						},
    						"includes": {
    							"type": "array",
    							"description": "The list of accessed includes/copybooks returned for a program",
    							"items": [
    								{
    									"type": "string",
    									"description": "An include/copybook accessed by a program"
    								}
    							]
    						},
    						"noOfChains": {
    							"type": "integer",
    							"description": "The number of chains returned for a program"
    						},
    						"prgName": {
    							"type": "string",
    							"description": "The name of a program."
    						},
    						"type": {
    							"type": "string",
    							"description": "The type of a program."
    						}
    					},
    					"required": [
    						"chains",
    						"includes",
    						"noOfChains",
    						"prgName",
    						"type"
    					]
    				}
    			]
    		}
    	},
    	"required": [
    		"longestChainLength",
    		"noOfPrgsNeverCalled",
    		"prgsDetails"
    	]
    }
  • To conduct call chain analysis for one or more programs, you can use the following endpoint that includes the showIncludes=true query to display the program-copybook relationship. Details can be specified in the request body.

    callchain?showIncludes=true (POST method)

    libertyURL/callchain?showIncludes=true
    Example
    http://localhost:9080/callchain?showIncludes=true
    Request body
    {
      	"direction" : "forward",
        	"projectName" : "Regression",
        	"depth" : "3",
        	"programsList" : [
    		{
    		    "prgName" : "A51DBDWN",
    		    "prgType" : ""
    		},
    		{
    		    "prgName" : "D284PRI",
    		    "prgType" : ""
    		}
    	]
        }
    
    Response
    {
      "longestChainLength": 3,
        "noOfPrgsNeverCalled": 3,
        "prgsDetails": [
            {
                "chains": [
                    "D284PRI:D284PRI->APKDAT"
                ],
                "includes": [
                    "DTCOMM",
                    "UBLOCK",
                    "CDBZERO"
                ],
                "noOfChains": 1,
                "prgName": "D284PRI",
                "type": "ASSEMBLER"
            },
            {
                "chains": [
                    "A51DBDWN->IOMOD",
                    "A51DBDWN->ZZCANCEL",
                    "A51DBDWN->ZZDATE65",
                    "A51DBDWN->ZZDATEGT"
                ],
                "includes": [
                    "A51COMPR",
                    "ACP1000R"
                ],
                "noOfChains": 4,
                "prgName": "A51DBDWN",
                "type": "COBOL"
            }
         ]	
    }
    
  • To conduct call chain analysis to get the source type and path for all the involved programs, you can use the following endpoint that includes the info query parameter. You can set the value of the info to be true or false, and the default value is false.

    callchain?info=true (POST method)

    libertyURL/callchain?info=true
    Example
    http://localhost:9080/callchain?info=true
    The endpoint returns a response that follows this schema.
    {
    	"$schema": "http://json-schema.org/draft-04/schema#",
    	"description": "The output schema for the callchain analysis API.",
    	"type": "object",
    	"properties": {
    		"longestChainLength": {
    			"type": "integer",
    			"description": "The length of the longest chain."
    		},
    		"noOfPrgsNeverCalled": {
    			"type": "integer",
    			"description": "The number of programs that are never called or that are never calling other program."
    		},
    		"prgsDetails": {
    			"type": "array",
    			"description": "The result list with details for each program returned by the callchain analysis.",
    			"items": [
    				{
    					"type": "object",
    					"properties": {
    						"chains": {
    							"type": "array",
    							"description": "The list of chains returned for a program which shows the usages or references that a program has.",
    							"items": [
    								{
    									"type": "string",
    									"description": "A chain of a program."
    								}
    							]
    						},
    						"noOfChains": {
    							"type": "integer",
    							"description": "The number of chains returned for a program"
    						},
    						"prgName": {
    							"type": "string",
    							"description": "The name of a program."
    						},
    						"type": {
    							"type": "string",
    							"description": "The type of a program."
    						},
                                                    "path": {
                                                            "type": "string",
                                                            "description": "The location of the file where the program is defined."
                                                    },
                                                    "analysisPrgs": {
                                                            "type": "array",
    			                                "description": "The result list with details for each program (secondary nodes) involved in the callchain analysis.",
    			                                "items": [
                                                                     {
    					                                "type": "object",
    					                                "properties": {
    						                               "path": {
                                                                                          "type": "string",
                                                                                          "description": "The location of the file where the program is defined."
                                                                                   },
                                                                                   "prgName": {
                                                                                          "type": "string",
                                                                                          "description": "The name of a program involved in the analysis."
                                                                                   },
                                                                                   "type": {
                                                                                          "type": "string",
                                                                                          "description": "The type of a program involved in the analysis."
                                                                                   },
                                                                             }
                                                            ]
                                                    }
    					},
    					"required": [
    						"chains",
    						"noOfChains",
    						"prgName",
    						"type"
    					]
    				}
    			]
    		}
    	},
    	"required": [
    		"longestChainLength",
    		"noOfPrgsNeverCalled",
    		"prgsDetails"
    	]
    }
    Request body
    {
      	"direction" : "forward",
        	"projectName" : "Regression",
        	"depth" : "3",
        	"programsList" : [
    		{
    		    "prgName" : "A51DBDWN",
    		    "prgType" : ""
    		},
    		{
    		    "prgName" : "D284PRI",
    		    "prgType" : ""
    		}
    	]
        }
    
    Response
    {
        "longestChainLength": 1,
        "noOfPrgsNeverCalled": 0,
        "prgsDetails": [
            {
                "chains": [
                    "A50DBDWN->IOMOD"
                ],
                "noOfChains": 1,
                "prgName": "A50DBDWN",
                "type": "COBOL",
                "analysisPrgs": [
                    {
                        "path": "",
                        "prgName": "IOMOD",
                        "type": "COBOL"
                    }
                ],
                "path": "C:|IBM AD|Mainframe Projects|Regression|DT Cobol Pre-compiled|A50DBDWN"
            }
        ]
    }
  • To check the programs that access the specified copybooks, you can use the following endpoint.

    callchain/includes (POST method)

    libertyURL/callchain/includes
    Example
    http://localhost:9080/callchain/includes
    The endpoint returns a JSON response with the Includes -> Programs Analysis based on a JSON that is sent in the request body as the input that follows this schema.
    {
    	"$schema": "http://json-schema.org/draft-04/schema#",
    	"description": "The programs input schema for the callchain includes/copybooks analysis API.",
    	"type": "object",
    	"properties": {
    		"prjName": {
    			"type": "string",
    			"description": "The name of the project on which the analysis will be made."
    		},
    		"includes": {
    			"type": "array",
    			"description": "An array which contains the includes names for the analysis.",
    			"items": [
    				{
    					"type": "object",
    					"properties": {
    						"inclName": {
    							"type": "string",
    							"description": "The name of a copybook/include"
    						},
    						"inclType": {
    							"type": "string",
    							"description": "The source type of a copybook/include",
    							"default": ""
    						}
    					},
    					"required": [
    						"inclName"
    					]
    				}
    			]
    		}
    	},
    	"required": [
    		"prjName",
    		"includes"
    	]
    }
    
    Request body
    {
        "prjName": "Regression",
        "depth": 2,
        "direction": "forward",
        "includes": [
            {
                "inclName": "ACP1000R",
                "inclType": ""
            }
        ]
    }
    Response
    {
        "avgNoOfPrgsAccessingOneInclud": 2.0,
        "includesDetails": [
            {
                "allAccesses": 2,
                "distincPrgs": 2,
                "includeName": "ACP1000R",
                "includePrgsDetails": [
                    {
                        "occurrences": 1,
                        "prgName": "A50DBDWN",
                        "prgType": "COBOL"
                    },
                    {
                        "occurrences": 1,
                        "prgName": "A51DBDWN",
                        "prgType": "COBOL"
                    }
                ],
                "includeType": "COBOL",
                "analysisPrgs": [
                    {
                        "path": "",
                        "prgName": "IOMOD",
                        "type": "COBOL"
                    },
                    {
                        "path": "",
                        "prgName": "ZZDATEGT",
                        "type": "COBOL"
                    }
                ],
                "chains": [
                    "A50DBDWN->IOMOD",
                    "A51DBDWN->ZZDATEGT"
                ]
            }
        ],
        "maxNoOfPrgsAccessingOneInclud": 2,
        "minNoOfPrgsAccessingOneInclud": 2,
        "noOfPrgsAccessingIncludes": 2
    }
  • To check the programs that access one specified copybook per request, you can use the following endpoint. No request body is required. If the copybook type (inclType) is not specified for a copybook, analysis for all the copybooks with that name (inclName) will be returned. The parameters depth and direction are optional, and the default value for direction is forward.

    callchain/includes/withParameters (GET method)

    libertyURL/callchain/includes/withParameters?
    prjName=projectName
    &inclName=copybookName
    &inclType=copybookType
    Example
    http://localhost:9080/callchain/includes/withParameters?
    prjName=Regression
    &inclName=ACP1000R
    &inclType=COBOL
    &depth=2
    &direction=forward
    The endpoint returns a response that follows this schema.
    {
    	"$schema": "http://json-schema.org/draft-04/schema#",
    	"description": "The output schema for the Includes -> Programs analysis.",
    	"type": "object",
    	"properties": {
    		"avgNoOfPrgsAccessingOneInclud": {
    			"type": "number",
    			"description": "The average number of programs accessing one include/copybook."
    		},
    		"includesDetails": {
    			"type": "array",
    			"description": "The result list with details for each include returned by the Includes -> Programs analysis.",
    			"items": [
    				{
    					"type": "object",
    					"properties": {
    						"allAccesses": {
    							"type": "integer",
    							"description": "The total number of accesses that the current include/copybook has."
    						},
    						"distincPrgs": {
    							"type": "integer",
    							"description": "The total number of distinct programs accessing one include/copybook."
    						},
    						"includeName": {
    							"type": "string",
    							"description": "The current include/copybook name."
    						},
    						"includePrgsDetails": {
    							"type": "array",
    							"description": "The list of programs details that accesses the current include/copybook.",
    							"items": [
    								{
    									"type": "object",
    									"properties": {
    										"occurrences": {
    											"type": "integer",
    											"description": "The number of accesses that a program has for the current include/copybook."
    										},
    										"prgName": {
    											"type": "string",
    											"description": "The name of the program."
    										},
    										"prgType": {
    											"type": "string",
    											"description": "The source type of the program."
    										}
    									},
    									"required": [
    										"occurrences",
    										"prgName",
    										"prgType"
    									]
    								}
    							]
    						}
    					},
    					"required": [
    						"allAccesses",
    						"distincPrgs",
    						"includeName",
    						"includePrgsDetails"
    					]
    				}
    			]
    		},
    		"maxNoOfPrgsAccessingOneInclud": {
    			"type": "integer",
    			"description": "The maxmimum number of programs accessing on include/copybook."
    		},
    		"minNoOfPrgsAccessingOneInclud": {
    			"type": "integer",
    			"description": "The minimum number of programs accessing on include/copybook."
    		},
    		"noOfPrgsAccessingIncludes": {
    			"type": "integer",
    			"description": "The total number of programs accessing includes/copybooks."
    		}
    	},
    	"required": [
    		"avgNoOfPrgsAccessingOneInclud",
    		"includesDetails",
    		"maxNoOfPrgsAccessingOneInclud",
    		"minNoOfPrgsAccessingOneInclud",
    		"noOfPrgsAccessingIncludes"
    	]
    }
  • To conduct call chain analysis to generate the list of programs from OrientDB for a specific project, you can use the following endpoint that includes the query parameter. No request body is required.
    callchain/programs (GET method)
    libertyURL/callchain/programs?
    project=projectName
    
    Example
    http://localhost:9080/callchain/programs?
    project=Regression
    Response
    {
        "inputs": {},
        "nodes": [
            {
                "entityType": "COBOL",
                "name": "U99MOPF",
                "id": "#87:1",
                "properties": {
                    "path": ""
                }
            },
            {
                "entityType": "ASSEMBLER",
                "name": "NQACFLAG",
                "id": "#87:1",
                "properties": {
                    "path": ""
                }
            },
    		
    		.
    		.
    		.
    	],
        "edges": [],
    }
  • To conduct call chain analysis to generate a call graph, you can use the following endpoint that includes the query parameters.
    • callchain/callgraph (GET method)
      libertyURL/callchain/callgraph?
      project=projectName
      &program=programName
      &programType=programType
      &depth=depthNumber
      &direction=callchainDirection
      Example
      http://localhost:9080/callchain/callgraph?
      project=Regression
      &program=COBCOPYCALLSUB
      &programType=COBOL
      &depth=4
      &direction=backward
      Response
      {
          "inputs": {
              "depth": "4",
              "direction": "backward",
              "project": "Regression"
          },
          "nodes": [
              {
                  "entityType": "COBOL",
                  "name": "COBCOPYCALLMAIN",
                  "id": "#109:108",
                  "properties": null
              },
              {
                  "entityType": "COBOL",
                  "name": "COBCOPYCALLSUB",
                  "id": "#109:107",
                  "properties": null
              },
      		
                          .
      	            .
      	            .
          ],
          "edges": [
              {
                  "sourceId": "#109:108",
                  "targetId": "#109:107",
                  "relationName": "Program_Call"
              },
              {
                  "sourceId": "#109:107",
                  "targetId": "#109:108",
                  "relationName": "Program_Call",
              },
      		
                          .
      	            .
      	            .
          ]
      }
    • callchain/programs (POST method)
      libertyURL/callchain/callgraph?
      project=projectName
      &depth=depthNumber
      &direction=callchainDirection
      Example
      http://localhost:9080/callchain/callgraph?
      project=Regression
      &depth=4
      &direction=backward

      Request body

      Provide either name & type or identif that is a resource ID from Orient DB. The identif is optional, if it is not provided, leave "" for the input of programs.
      {
          "resources": [
              {
                  "name": "COBCOPYCALLSUB",
                  "type": "COBOL",
                  "identif": "#87:86"
              }
          ]
      }
      Response
      {
          "inputs": {
              "depth": "4",
              "direction": "backward",
              "project": "Regression"
          },
          "nodes": [
              {
                  "entityType": "COBOL",
                  "name": "COBCOPYCALLMAIN",
                  "id": "#109:108",
                  "properties": null
              },
              {
                  "entityType": "COBOL",
                  "name": "COBCOPYCALLSUB",
                  "id": "#109:107",
                  "properties": null
              },
      		
                          .
      	            .
      	            .
          ],
          "edges": [
              {
                  "sourceId": "#109:108",
                  "targetId": "#109:107",
                  "relationName": "Program_Call"
              },
              {
                  "sourceId": "#109:107",
                  "targetId": "#109:108",
                  "relationName": "Program_Call",
              },
      		
                          .
      	            .
      	            .
          ]
      }
Note: The copybooks or includes are also available in the callchain/callgraph endpoints, and the response contains the relationships between programs and other resources such as accessed files and includes.