Generating call chain analysis results by using API URLs

Before you begin

If the authentication and authorization feature is enabled with the Authentication Server (DEX) installed and configured, the passwordConnector parameter must be added in the dex.yaml file. Also, a security token is needed. For more information, see step 1.4 in topic STEP 4. (Optional) Configuring Authentication Server (DEX).
If OrientDB SSL is enabled, add the following properties in file <IBM ADDI Installation Folder>/IBM AD Web Services/wlp/usr/servers/ad_server/jvm.options:
- The path of the OrientDB certificates.
- The passwords of the certificates.
Example
```
-Dclient.ssl.enabled=true
-Dclient.ssl.keyStore=C:\certificates\orientdb.ks
-Dclient.ssl.keyStorePass=password
-Dclient.ssl.trustStore=C:\certificates\orientdb.ks
-Dclient.ssl.trustStorePass=password
```
Note: You can enter an encrypted Keystore Password. For more information, see Obtaining an encrypted keystore password.
After the file is edited and saved, restart IBM® Application Discovery WebSphere® Liberty Profile Service.

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.

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.

libertyURL/callchain/

Example

http://localhost:9080/callchain/

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" : ""
        }
    ]
}

HTTP method (POST)

To conduct call chain analysis for one or more programs, you can use the following endpoint which includes the showIncludes=true query to display also the program-copybook relationship. Details can be specified in the request body.

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" : ""
		}
	]
    }

HTTP method (POST)

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.
```
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
```
HTTP method (GET)

To check the programs that access the specified copybooks, you can use the following endpoint.

libertyURL/callchain/includes

Example

http://localhost:9080/callchain/includes

Request body

{
	"$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"
	]
}

Example

{
    "prjName": "Regression",
    "depth": 2,
    "direction": "forward",
    "includes": [
        {
            "inclName": "ACP1000R",
            "inclType": ""
        }
    ]
}

HTTP method (POST)

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.
```
libertyURL/callchain/includes/withParameters?
prjName=projectName
&inclName=copybookName
&inclType=copybookType
```
Example
```
http://localhost:9080/callchain/includes/withParameters?
prjName=Regression
&inclName=ACP1000R
&depth=2
&direction=forward
```
HTTP method (GET)

To conduct call chain analysis to get the source type and path for all the involved programs, you can use the following endpoint which includes the info query parameter. You can set the value of the info to be true or false, and the default value is false.

libertyURL/callchain?info=false

Example

http://localhost:9080/callchain?info=false

Request body

{
  	"direction" : "forward",
    	"projectName" : "Regression",
    	"depth" : "3",
    	"programsList" : [
		{
		    "prgName" : "A51DBDWN",
		    "prgType" : ""
		},
		{
		    "prgName" : "D284PRI",
		    "prgType" : ""
		}
	]
    }

HTTP method (POST)

To check the source type and path 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 the path of all programs with that name (prgName) will be returned.
```
http://localhost:9088/callchain/withParameters?
direction=forward
&projName=Regression
&depth=3
&prgName=A50DBDWN
&prgType=COBOL
&info=true
```
HTTP method (GET)

Results

After the request is sent, call chain analysis results are generated and displayed. See the following example of analysis results.

Example

{
    "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"
        }
    ]
}

The call chain analysis results that are generated and displayed including program-copybook relationship are based on the following 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"
	]
}

Example result:

{
  "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"
        }
     ]	
}

The call chain copybook analysis results follow the following 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"
                                    ]
                                }
                            ]
                        },
                        "includeType": {
                            "type": "string",
                            "description": "The type of the current include/copybook."
                        },
                    },
                    "required": [
                        "allAccesses",
                        "distincPrgs",
                        "includeName",
                        "includePrgsDetails",
                        "includeType"
                    ]
                }
            ]
        },
        "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"
    ]
}

Example result:

{
    "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
}

The example of call chain analysis result that is generated by using the endpoint with info query parameter to get the source type and path for all the involved programs is as follows.

{
    "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"
        }
    ]
}