Application Discovery

Module 3 –
Detailed Analysis Reports
© 2019 IBM Corporation

1
Company Trademarks and Copyrights
© Copyright IBM Corporation 2008 through 2019.

All rights reserved – including the right to use these materials for instructional
purpose.

The information contained in these materials is provided for informational purposes only, and is
provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible
for any damages arising out of the use of, or otherwise related to, these materials. Nothing
contained in these materials is intended to, nor shall have the effect of, creating any warranties
or representations from IBM or its suppliers or licensors, or altering the terms and conditions of
the applicable license agreement governing the use of IBM software. References in these
materials to IBM products, programs, or services do not imply that they will be available in all
countries in which IBM operates.

This information is based on current IBM product plans and strategy, which are subject to change
by IBM without notice. Product release dates and/or capabilities referenced in these materials
may change at any time at IBM’s sole discretion based on market opportunities or other factors,
and are not intended to be a commitment to future product or feature availability in any way.

IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and other IBM
Rational products and services are trademarks or registered trademarks of the International
Business Machines Corporation, in the United States, other countries or both. Other company,
product, or service names may be trademarks or service marks of others.

2
The IBM Application Discovery Curriculum

▪ Module 1 – Product Overview, Terms, Concepts and Vocabulary

▪ Module 2 – Eclipse Navigation and Introduction to Call Graphs
▪ Module 3 – AD Detailed Analysis Reports
▪ Module 4 – Resource Usage (Where Used) and Text Search

3
Course Contributing Authors

Thanks to the following individuals, for assisting with the

materials in this course:
Russ Courtney – IBM/Application Discovery Technical Specialist
David Lawrence – IBM/Application Discovery Technical Specialist
David Hawreluk – IBM/Application Discovery Technical Specialist
Dave Baxandall – IBM/Application Discovery Senior Technical Specialist
Russell Bonner – IBM/Application Discovery Technical Specialist

4
Topics in this module
After completing this module you will be able to:
Launch AD and navigate within the product running under Eclipse
Invoke some of the AD Mainframe Reports – and be able to interpret the
information presented in the reports

Complexity Reports
▪ Statistically analyse your COBOL, PL/I and Assembler programs for complexity
and maintain-ability
Datasets Reports
▪ Track data values from the context of the files they are read from and written
to
Dead Code Reports
▪ Discover orphaned programs within a project – and unreferenced/unused
routines (paragraphs/sections and PROCS) in programs
Impact Reports
▪ Analyze the effects of changes to program variables and DB2 table columns –
across all resources in your Project
▪ Paths through Jobs – defined CA7 scripts
Inventory Reports
▪ A detailed list of all the DDCL elements in the current project as well as details about
each element. Includes missing inventory (COPYBOOKS/INCLUDES not found, Called
programs not found etc.
Miscellaneous Reports
▪ Job triggers and Paths through Jobs – defined in CA-7 scripts
▪ Forward and Backward Call Chains for modules and DB2 tables
Where Used Reports
▪ Where Used Reports show all the places within the application where specific
resources are referenced.

5
UNIT AD for ISPF Developers
Topics:
▪ AD Detailed Analysis Reports
▪ Labs & Module Review

6
Review – Eclipse Terms, Concepts and Navigation
 Back Button

AD Project Explore view

AD Graph Overview view  Menu bar
 Search area
 Projects

We will use the same workflow

AD Graph Inventory view introduced in the previous
 Tabs

module:
1. Select a Project
2. Select a Report to run against
the project
Content 

Reports
Properties view
Outline, Problems,
Help System
Error Log views

Reports are a set of hardcopy (electronic-print-able) documents that

provide detailed information about a diverse group of analytic topics

7
Review – AD Tools/Functionality and Report Categories

8
Complexity Reports – 1 of 4
Select the Project 
Double-Click a report

▪ You will see a Filterable list of Cyclomatic (McCabe) Report –

COBOL, PL/I and Assembler programs measures the number of linearly
independent paths through a
program module.

Halstead Report – measures

complexity by calculating data -
variables & operators – both defined
Program and in use.
Type
Filters
Program
Name Heuristic Report – measures
Filter complexity by identifying types of
Report statements and assigning a weight
Generation to each.
Options

Maintainability Index – Combines

Cyclomatic and Halstead and defines
a threshold for rewriting program code
9
Complexity Reports – 2 of 4

Save
and/or
Export to
PDF, DocX.

Cyclomatic Report

Cyclomatic (McCabe) Report –

measures the number of linear
independent paths through a program.

All of these print-able Reports have the

same layout/navigation tools – as well as
tools to zoom-in and zoom-out of the
detailed information.
 And there are graphical summary charts.

10
Complexity Reports – Heuristics – 3 of 4
Heuristic Report – measures
▪ An Assembler program and a COBOL complexity by identifying types of
program’s Heuristics metrics statements in values are customized
in the report properties files during
installation.

You can assign your own weighting

factors; COBOL: Go_TO = 10

The default value of the Go To metric

is low without your customization of
the statement weights. See the IBM
Application Discovery for IBM Z Batch
Server Configuration Guide for
further details.

11
Complexity Reports – 4 of 4 https://en.wikipedia.org/wiki/Halstead_complexity_measures

Maintainability Index Halstead Report

https://www.cachequality.com/docs/metrics/sei-maintanability-index

Combines Cyclomatic and Halstead metrics, Measures complexity by calculating data -

and defines a threshold for rewriting variables & operators – both defined and in
program code. For more on this metric: use throughout the program.
12
 Customizing Complexity Report Weights & Values
Right-click on a Complexity Report to customize
the algorithmic properties and weighting values

Customizing individual Removing specific

COBOL statement weights CICS APIs from the
for the Heuristic Report Halstead Analysis
Report Settings

Report customizations are local

changes on the client. They persist
until changed again or reset to the
13
Customizing a Report Cover Page

You can add:

▪ Your company
logo – to replace
the IBM logo on
the Report
Header pages
▪ Your name,
company and
department
information to the
Report Cover
page
Header image file options
also include *.gif files

14
Reading the details of a report – zoom-in/zoom-out
On the top of the Reports view, next to the paging controls you will find
zoom controls – that may make reading report details simpler

Toolbar icons alter report reading resolution

15
Datasets Reports – Data Flow
Through Datasets – 1 of 3
Select the Project then…
Double-Click Data Flow Through Datasets

▪ You will see a Filterable list

of Datasets (DSNs)

Data Flow Through Datasets shows

the data flow within a batch process,
starting with a physical dataset that
can be either at the start of the
process (forward data flow) or at the
end of the data flow (backward data
flow) or in the middle of it (backward
16
and forward data flow).
Datasets Reports – Data Flow
Through Datasets – 2 of 3

From PATMASTR.TEST Program[JobNameJobStepLine# in JCL]

…to BNCHMRK2.PATEDIT.WEEKLY
…to BNCHMRK2.PATSORT.WEEKLY
…to BNCHMRK2.PATSRCH.WEEKLY
…to BNCHMRK2.PATSRT2.WEEKLY
…to BNCHMRK2.PATERR.WEEKLY

Program[JobNameJobStepLine# in JCL]

Program[JobNameJobStepLine# in JCL]

Program[JobNameJobStepLine# in JCL]

The Data Flow Reports track variables within

the context of files – as the data is
Generated T-O-C with links to Read/Into and Written/From files to
File/Report details 17 programs – which are executed by Job steps
Datasets Reports – Data Flow
Through Datasets – 3 of 3

Clicking flowgraph opens a

Dataset Graph in a separate
un-docked window
Program
Type
Filters
Program
Name
Filter
Report
generation
options

18
Dead Code Reports – Unreferenced Programs – 1 of 2

Select the Project then,

Double-Click Unreferenced Programs

Unreferenced Programs are source

files in your Project that are never
referenced in JCL or Transactions –
or referenced through program
CALL statements.

Program
Type
Filters

Program Name Filter

Report Generation
Options

Select programs and specify

19
Report generation characteristics
Dead Code Reports – Unreferenced Programs – 2 of 2

A statistical summary
graphic showing:
▪ Programs in a Project
that are executed
(Batch or Online)
▪ Programs that are
never executed

▪ The report also lists all

programs found in a
Project

Be sure that programs are not

referenced because you have failed
to spot an API routing program, or
because the programs are missing
one-or-more source components 20
Dead Code Reports – Unused Routines Within Programs – 1 of 2

Select the Project, then…

Double-click Unused Routines Within Programs

Unused Routines are COBOL

Paragraphs/Sections or PL/I PROCs
that are never executed through a
program’s processing logic

Select programs and specify

Report generation characteristics

21
Dead Code Reports – Unused Routines Within Programs – 2 of 2

And a separate list of named

There is s statistical summary graphic routines broken out by Program

Cyclomatic Report

22
 Field Expansion – 1 of 4
Field Expansion – documents the impact on
programs, variables, copybooks, DB2 tables and
Select the Project files in your Project affected by enlarging the
Double-click Field Expansion Report definition of a single variable or DB2 column

Select whether the field resides in a

program, copybook or DB2 table
Further refine your Field selection
Optionally choose to limit the levels of
depth analyzed for affected resources 23
Field Expansion – 2 of 4

Select a program or copybook

There is NO option to exclude variables
from the Field Expansion report
Select a variable from the
report input list
24
Field Expansion – 3 of 4

Select programs
and specify
Report
Impact generation
analysis reports likeoptions
Field
expansion in medium-sized or large
projects can take a while to produce.
Note that there are 137 pages in this report

Programs affected by expanding the field 25

Field Expansion – 4 of 4

Variables affected by expanding the field –

and the procedural logic behind the analysis

Double-Clicking a variable
in the report opens to the
variable definition in the
source code.

26
 Field Usage – 1 of 3
Field Usage – documents the
Select the Project relationships among the resources of an
Double-click Field Usage Report application so that the impact of renaming a
field can be understood.

Select whether the field resides in a

program, copybook or DB2 table

Note: No option for limiting report depth Further refine your Field selection
27
Field Usage – 2 of 3

Select a program or copybook

There is no option to
exclude variables from
Field Usage reports
Select a variable from the
report input list
28
Field Usage – 3 of 3

Statement type and program source lines

affected by renaming the field

Field Usage documents a single variable’s

references throughout the application source
code in the AD Project. The report does not
29
document related fields and their use.
 Impact Analysis – 1 of 4
Impact Analysis - allows you to
Select the Project understand the consequences of modifying
a program/copybook variable or DB2 column.
Double-click Impact Analysis Report The report determines what other resources
use the variable or DB2 column.

Select whether the field resides in a program, copybook

or DB2 table/column**

Further refine your analysis processing:

• Impacts that occur forward from the first reference to your
selected variable in processing sequence of backward
• Impact analysis – like Field expansion results in an extensive
search – and can be resource-intensive & time consuming.
Limiting the search “depth” can be a practical 1 st step

** If you select a table field, the report is

generated on a variable that is mapped to the
field and not on the table field (DDL) per se’
30
Impact Analysis – 2 of 4

Select a program or copybook

There is an option to exclude
variables from Impact Analysis
Select a variable from the
report input list
31
Impact Analysis – 3 of 4

Variables affected by expanding the field –

and the procedural logic behind the analysis

32
Impact Analysis – 4 of 4

Interpretation

PATIENT-ID is child (bytes 16) of PATIENT-MASTER-REC

PATIENT-MASTER-REC is moved to …to LN-MESSAGE
LN-MESSAGE is a child (bytes 7883) of LN-MQPUTSUB-PARM
The program MQPUTSUB is called using LN-MQPUTSUB-PARM

Double-Clicking a variable in the

report opens to the variable
definition in the source code.

33
 Summary of this module…
In this module you learned how to:
Launch AD and navigate within the product running under Eclipse
Invoke the Mainframe Reports against an AD Project
Utilize the filter dialogs to zero in on specific Points-of-Interest
Interpret the summary & detail information presented in the reports – following
report flows and interpreting the semantics presented

Complexity Reports
▪ Statistically analyse your COBOL, PL/I and Assembler programs for complexity
and maintain-ability
Datasets Reports
▪ Track data values from the context of the files they are read from and written
to
Dead Code Reports
▪ Discover orphaned programs within a project – and unreferenced/unused
routines (paragraphs/sections and PROCS) in programs
Impact Reports
▪ Analyze the effects of changes to program variables and DB2 table columns –
across all resources in your Project
▪ Paths through Jobs – defined CA7 scripts
Inventory Reports
▪ A detailed list of all the DDCL elements in the current project as well as details about
each element. Includes missing inventory (COPYBOOKS/INCLUDES not found, Called
programs not found etc.
Miscellaneous Reports
▪ Job triggers and Paths through Jobs – defined in CA-7 scripts
▪ Forward and Backward Call Chains for modules and DB2 tables
Where Used Reports
▪ Where Used Reports show all the places within the application where specific
resources are referenced.
34
 Summary of the Impact Reports
Field Expansion and Impact Analysis utilize a
Byte/Displacement tracing algorithm – i.e.
Trace the movement of bytes 1216 in a given
record, throughout the source files in an AD Project

Direct & Indirect References + COPYBOOKS + Comparisons

Use Cases ------------------

0. Rename a field: Field Usage
1. Enlarge a field definition: Field Expansion Direct References Only
2. Decrease a field definition: Impact Analysis
3. Update the PIC Clause without changing field definition size: Impact Analysis
4. Delete a field: Field Expansion
5. Modify a Group/Copybook: Field Expansion
6. Understand a given data flow backwards from a variable -- In order to trace variable values
backwards & solve ABENDs: Field Expansion
35
UNIT AD for ISPF Developers
Topics:
▪ Detailed Analysis Reports
▪ Labs and Module Review

36
Review – Match the Report Name to its Description
Report Name Report Description
Impact Analysis__ 1. Documents the impact on programs, variables and files in your Project
affected by enlarging the definition of a single variable or DB2 column
Unreferenced Programs__ 2. COBOL Paragraphs/Sections or PL/I PROCs that are never executed through
a program’s processing logic
Maintainability Index__ 3. Measures complexity by identifying types of statements in the programs and
assigning a weight to each type.
Field Usage__ 4. Measures the number of linearly independent paths through a program
module.
Heuristic Report__ 5. Measures complexity by calculating data - variables & operators – both
defined and in use
Unused Routines__ 6. Combines Cyclomatic and Halstead and defines a threshold for rewriting
program code
Field Expansion__ 7. Shows the data flow within a batch process, starting with a physical dataset
that can be either at the start of the process or at the end of the data flow or in
the middle of it
Cyclomatic (McCabe) 8. Source programs in your Project that are never referenced in JCL or
Report__ Transactions, or referenced through program-to-program CALL statements.

Halstead Report 9. Documents the relationships among the resources of an application so that
the impact of renaming a field can be understood
Data Flow Through 10. Allows you to understand the consequences of modifying a variable or DB2
Datasets__ column. The report also determines what other resources use the variable or
DB2 column that would be affected by a change.
37
Hands-on Workshops – 1 of 8 Complexity Reports
Log into your AD Analysis Server:
 If you are using zTrial - Login to the zTrial machine and launch AD
 If you are using your own AD Server – launch AD

Having logged into AD –– do the following with the tools and source Projects stored in the AD
Repository. Close each of the Reports views after you’ve finished the respective Use Cases:

Complexity Reports
1. Select an AD Project. Expand Mainframe Reports and expand Complexity Reports
2. Double-click (launch) a Cyclomatic Report
3. Filter programs to run the reports against, using: Program Type and/or Program Name
4. In Report Generation Options show the appendix
5. Read through information produced by the report: Graphical summary & Detailed information
6. Return to step 2 (above). Launch each of the other Complexity Reports (one at a time) and
follow steps 3  5
1. Halstead Report
2. Heuristic Report
3. Maintainabiliy Index
7. Experiment with changing default Report algorithms & weights:
1. Heuristic Complexity
2. Halstead Report
Refer to the slide in this module if you need a reminder of how to customize
the weights and settings for the reports
38
Hands-on Workshops – 2 of 8 Dataset Reports
Dataset Reports
1. Select an AD Project.
2. Expand Dataset Reports
3. Double-click (launch) Data Flow Through Datasets
4. Filter the Available Datasets and select one or more files to run the report against
5. In Report Generation Options: Show the appendix
6. Experiment with Limit data flow and Data flow direction
7. Read through the information produced by the report:
1. Use the TOC to link to a file’s chain(s)
2. Follow the data flow in Report Details for one or more files
3. Example……………………………….

8. From Report Details, click the hyper-link for:

1. Flowgraph
2. Forward chains
39
Hands-on Workshops – 3 of 8 Dead Code Reports
Dead Code: Unreferenced Programs
1. Select an AD Project.
2. Expand Dead Code Reports
3. Double-click (launch) Unreferenced Programs
4. Try the following options – where applicable – and generate the Report
▪ Filter the Project on program type
▪ Filter on program name
▪ Check the box for ✓ Show appendix
5. Review the report summary – and the text answers

Dead Code: Unused Routines Within Programs

1. Select an AD Project.
2. Expand Dead Code Reports
3. Double-click (launch) Unused Routines Within Programs
4. Try the following – where applicable – and generate the report
▪ Filter the Project on program type
▪ Filter on program name
▪ Check the box for ✓ Show appendix
5. For each program that ends up in the report due to dead-date
▪ Review both of the report summary results – and the list of routines broken out by programs

40
Hands-on Workshops – 4 of 8 Field Usage
Before tackling the workshop, review the slides that cover the Field
Usage Report creation process, options and report nuances
Workshops Steps:
1. Select an AD Project.
2. Expand Impact Reports
3. Double-click (launch) Field Usage Report
4. Depending on whether you’re using the zTrial Repository or your own, proceed
through the wizard and set – or select:
▪ Target selection If you are using zTrial consider:
• Locate variables
▪ Expansion depth • Include
▪ Type of source • PATMSTR
• PATIENT-ID
▪ Single include selection
▪ Select report inputs
5. Generate the report and review the report summary:
1. Review the Outline report
2. Choose one of the variables and mentally trace the logic (Impact analysis of variable)
3. Click a variable and open the source file to the line that produced the impact trace
analysis
Field Usage – documents the relationships among
the resources of an application so that the impact of
renaming a field can be understood. 41
Hands-on Workshops – 5 of 8 Field Expansion
Before tackling the workshop, review the slides that cover Field Expansion
Workshops Steps:
1. Select an AD Project.
2. Expand Impact Reports
3. Double-click (launch) Field Expansion Report
4. Depending on whether you’re using the zTrial Repository or your own, proceed
through the wizard and set – or select:
▪ Target selection
▪ Expansion depth If you are using zTrial consider:
▪ Type of source • Locate variables
• Include
▪ Single include selection • PATMSTR
▪ Select report inputs • PATIENT-ID

5. Generate the report*** and review the summary and detailed information:
1. Browse the programs
2. Choose one of the variables and mentally trace the logic (Impact analysis of variable).
Note that this detailed discovery and documentation aspect of Field Expansion
represents one of the primary value propositions of the AD Tool
3. Click a variable and open the source file to the line that produced the point-of-interest

***Note: If you do not limit the

Expansion depth it may take
awhile to produce this report 42
Hands-on Workshops – 6 of 8 Impact Analysis
Before tackling the workshop, review the slides that cover Impact Analysis
Workshops Steps:
1. Select an AD Project and expand Impact Reports
2. Double-click (launch) Impact Analysis Report
3. Depending on whether you’re using the zTrial Repository
or your own, proceed through the wizard and set, or select:
▪ Target selection – Impact direction – Expansion depth
▪ Single include selection – Select report inputs
– Optionally Exclude one or more variables from the report
4. Generate the report*** Review the summary and detailed information:
1. Read through the Report summary and Variables summary information
2. Starting with a specific program, trace (be able to interpret) the:
1. Variable flow analytics – Points-of-interest
2. Data flow analytics – Files and database data flow
3. Call/Calling chain analytics
3. Click a variable and open the source file to the line that produced the point-of-
interest
If you are using zTrial consider
***Note: If you do not limit the using:
Expansion depth it may take • PATMSTR
awhile to produce this report 43 • PATIENT-ID
Hands-on Workshops – 7 of 8 – Open Ended Labs
There are a number of additional AD Reports that were
not covered in this module – but adhere to the basic
workflow discussed. Through trial-and-error and product
experimentation, run reports that provide answers to the
following:
▪ A CICS system subroutine has been changed IBM (CEEDAYS) – what
call chains must be researched before implementing the change?
▪ Before starting production use of a static-analysis product, you will
need an accounting of missing source components. Generate a report
for the Hospital Project to find missing programs
▪ Generate an inventory report, that consolidates and lists; Programs,
Function points, Calls, Includes (copybooks) & File access
▪ Generate a report that aggregates data files and the
copybooks/includes (schema) they are accessed through
▪ A Copybook (Include) needs to be changed. What report lists
programs that will need to be recompiled and/or analyzed?
▪ Generate a report that lists all of the resources in an AD Project –
broken down by resource type
44
Hands-on Workshops – 8 of 8 - Where Used
Cross-Reference Reports
Experiment with as many
of the Where Used Reports
as you have time for
during class.

Note that your AD Project

might not contain
resources for all Report
types (DAL, MQueues, etc.)

The Where Used Reports provide detailed

cross-reference information – breaking AD
Project elements down into
element/relationship – and providing
graphical summaries and appendices. 45
UNIT AD for ISPF Developers
Topics:
▪ Detailed Analysis Reports
▪ Labs and Module Review
▪ Backup Slides and Answers to Review Questions

46
AD Asset Partitioning

AD Repository
(Default DB2 Database == DMHDB)

 Site – equivalent to an environment or LPAR

 Application –  Application –
An AD organizational An AD organizational
construct equivalent to a construct equivalent to a
business application business application

Source code Assets: Source code Assets:

Batch jobs, CICS, IMS, Batch jobs, CICS, IMS,
DB2, Programs, Literals, DB2, Programs, Literals,
Datasets, etc. Datasets, etc.

47
AD Tools: Graphs, Reports and Usage

AD Tools
Graphs

COBOL
Program

Usage Application Reports

Tools
Artifact

48
Chalkboard/Discussion
Application Analysis Tasks Current methods and tools?

Project scoping

Task complexity analysis

Detailed logic analysis

Impact analysis/Where used

Analyze an application

Study a batch job

Trace a transaction’s flow

Understand a program’s semantics

49
Answers to Review Questions – Match the Report Name to its Description
Report Name Report Description
Impact Analysis_10_ 1. Documents the impact on programs, variables and files in your Project
affected by enlarging the definition of a single variable or DB2 column
Unreferenced Programs_8_ 2. COBOL Paragraphs/Sections or PL/I PROCs that are never executed
through a program’s processing logic
Maintainability Index_6_ 3. Measures complexity by identifying types of statements in the programs and
assigning a weight to each type.
Field Usage_9_ 4. Measures the number of linearly independent paths through a program
module.
Heuristic Report_3_ 5. Measures complexity by calculating data - variables & operators – both
defined and in use
Unused Routines_2_ 6. Combines Cyclomatic and Halstead and defines a threshold for rewriting
program code
Field Expansion_1_ 7. Shows the data flow within a batch process, starting with a physical dataset
that can be either at the start of the process or at the end of the data flow or in
the middle of it
Cyclomatic (McCabe) 8. Programs in your Project that are never referenced in JCL or Transactions,
Report_4_ or referenced through program CALL statements.

Halstead Report_5_ 9. Documents the relationships among the resources of an application so that
the impact of renaming a field can be understood
Data Flow Through 10. Allows you to understand the consequences of modifying a variable or DB2
Datasets_7_ column. The report also determines what other resources use the variable or
DB2 column that would be affected by a change.
50
AD Analysis Project – Review
What is an AD “Analysis Project”?
▪ AD calls physical groupings of parsed programs and other application source code
components “Analysis Projects” – or just “Projects”
Component Types
z/OS Application

51
Summary of the Impact Reports
Field Expansion – documents the impact on
programs, variables and files in your Project affected
by enlarging the definition of a single variable or DB2
Table or View column

Field Usage – documents the relationships

among the resources of an application so that the
impact of renaming a field can be understood.

Impact Analysis - allows you to understand

the consequences of modifying a variable or DB2
Table or View column. The report determines what
other resources use the variable or DB2 column.

52