1. No category

®
IBM Software Group
How to compile and assemble programs for PD tools:
IBM Debug Tool for z/OS
IBM Fault Analyzer for z/OS
IBM Application Performance Analyzer for z/OS
© 2007 IBM Corporation
June 6, 2007
00
1
IBM Software Group
IBM trademarks
The following terms are trademarks of International Business Machines Corporation
in the United States, other countries, or both:
CICS
CICS
COBOL/370
DB2
eServer
IBM
IMS
IMS/ESA
Language Environment
MVS
MVS/ESA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
RACF
Redbooks
S/390
System/390
OS/390
VS COBOL II
VTAM
WebSphere
z/OS
zSeries
zSeries PD tools
2
2
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
3
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
25
37
50
60
76
91
106
115
128
How to use source information files in Fault Analyzer 137
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
149
3
3
Compile your programs for IBM PD tools
The IBM PD tools products are designed to use modules
and source information files produced by IBM compilers
and PD tools utilities
When your programs are compiled for the PD tools, and
you have the right source information files, then:
IBM Debug Tool and Utilities
• will let you step through statements, set breakpoints,
view and change variables, and so on
IBM Fault Analyzer
• can pinpoint the abending statement, and show all
statements and variable values
IBM Application Performance Analyzer
• can show which program statements cause the most
system resource usage, CPU time, and wait time
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
4
4
?
How do you prepare your programs
for the IBM PD tools
1. For each compiler you use, review the options described in this
presentation, and decide:
• Which types of source information files will be saved
• Which compiler options are needed
2. Change compile processes / JCL to:
• Specify the right compiler options
• Save source information files
• For Debug Tool, for some compilers/environments, link-edit a DT
start-up exit into the application load module
3. Change program promotion processes / JCL to:
• Promote source information files along with load modules (can
be either a copy or recompile)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
5
5
Who makes the changes to the program
compile and promotion processes?
Application
Developer?
Systems
Programmer?
Library
Manager?
The owner of the processes or JCL typically makes the
changes
In many organizations, a person or group is responsible for
program source management and program build processes
In some organizations, JCL is owned by each developer
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
6
6
Which source information formats should you use?
Each compiler can generate different kinds of source
information files
Each PD tools product can support different file formats for
each compiler
Select the best formats for
your combination of
compilers and PD tools
products
LOADLIB
Compiler
Program
Source
more than one kind of
source information file
Load
module
SY
SD
DDEBU
G
Sysdebug
file (PDS)
T
PRIN
SYS DD
It may be optimal to save
Link edit
IDILANGX
Compiler
listing
(PDS)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
Langx
file
(PDS)
7
7
?
What kinds of source information
files are there?
To decide which formats you should use, review the section for
each compiler in this presentation
The source information file formats:
Source Information Can be generated by:
File Type
Sysdebug file
LE COBOL (including Enterprise COBOL),
Enterprise PLI 3.5 and later
Compiler listing file
All compilers
Langx file
All compilers
Expanded source
file
Sysadata file
Enterprise PLI, C, C++
© 2007 IBM Corporation
June 6, 2007
Assembler
Preparing programs for IBM PD tools
zSeries PD tools
8
8
Source Information Files: Sysdebug files
A Sysdebug file is a special
file format that contains
program source and
symbolics information
TEST( xxx , xxx ,SEPARATE) compiler option
It is a newer format available
only in recent compilers:
LOADLIB
Compiler
Link Edit
Load
module
SY
SD
DDEBU
G
LE COBOL compilers
Enterprise PLI compiler version 3.5 and later
Sysdebug
file (PDS)
The compiler generates a sysdebug file when you specify the
TEST compiler option with SEPARATE. Examples:
COBOL:
PLI:
TEST(NONE,SYM,SEPARATE)
TEST(ALL,NOHOOK,SYM,SEPARATE)
File format:
PDSE or PDS
LRECL=(80 to 1024),RECFM=FB,BLKSIZE=(any multiple of lrecl)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
9
9
Advantages of Sysdebug files
For COBOL programs, the load module can be production-ready
COBOL can generate a fully "debuggable" module with no added run-time
overhead
Sysdebug files are smaller than compiler listings (less disk space)
You can produce a listing from a sysdebug file with the Fault Analyzer
IDILANGP utility or Debug Tool EQALANGP
The listing is similar to a compiler listing
A Sysdebug file can be located automatically
The compiler stores the name of the Sysdebug file in the load module, so
IBM PD tools know where to find it
Load
Library
Load Module ‘SAM1’
‘TEST.DBG(SAM1)’
‘TEST.LOADLIB’
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
member
‘SAM1’
Sysdebug
PDS
‘TEST.DBG’
zSeries PD tools
10
10
Source Information Files: Compiler Listings
A Compiler listing is the
report produced by a
compiler
Program
Source
SYSOUT, save it in a file
Specify compiler options that
the PD tools require
Different for each compiler
Link Edit
Load
module
NT
RI
SP D
SY D
Instead of writing it directly to
LOADLIB
Compiler
Compiler
Listing
file
(PDS)
File format:
PDSE or PDS
Each compiler may require different file attributes
It is a best practice to save compiler listings, in some form,
for all of your production programs
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
11
11
Source information files: Compiler listings
If you still have the original compiler listing for an existing load
module, can you use it?
In many cases, FA and APA can use your existing listings
They require the right compiler options, so that needed information is in
the listings
Check the required options for each compiler
For Debug Tool, probably not
For most languages, Debug Tool requires the TEST compiler parm,
which prepares the load module for debugging
Can you re-create a compiler listing for an existing load module
by recompiling the program?
You can for Fault Analyzer, if:
The source code and compiler have not changed
Not for Debug Tool
It requires an exact time stamp match (listing / module)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
12
12
Compiler listings data set attributes
To use compiler listings with PD tools, store them in a
PDS or PDSE (member name = program name)
COBOL SYSPRINT (except OS/VS COBOL):
RECFM=FBA,LRECL=133
OS/VS COBOL SYSPRINT:
RECFM=FBA,LRECL=121
PLI SYSPRINT:
RECFM=VBA,LRECL=125 minimum
Enterprise PLI SYSPRINT:
RECFM=VBA,LRECL=137 minimum
C or C++ SYSPRINT
RECFM=VB or VBA,LRECL=137 minimum, or
RECFM=FB or FBA,LRECL=133
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
13
13
Source Information Files: Langx files
A Langx file (also called a "Side File") is a special file format that is
produced by one of the PD tools xxxLANGX utility programs
They are an alternative to
storing compiler listings
Equivalent utilities are shipped
Program
Source
The utility reads a compiler listing
Load
module
NT
RI
SP D
SY D
with:
Fault Analyzer: IDILANGX
Debug Tool: EQALANGX
APA: CAZLANGX
LOADLIB
Link Edit
Compiler
IDILANGX
Compiler
Listing
or assembler sysadata file
Certain compiler options are required
Different options for each compiler
LANGX file
(PDS)
File format:
PDSE or PDS,LRECL=1562,RECFM=VB,BLKSIZE=(1566 to 32K)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
14
14
Source Information Files: Langx files
When would you use a Langx file?
For some languages, Langx files are supported by more of the PD
tools products (DT, FA, APA) than other file types.
In these cases, if you store a Langx file, you may not need to store
other types of source information files
- or -
For some languages, you can store Langx files instead of Compiler
Listings
Langx files are smaller than compiler listings (less disk space)
However, Langx files are comparable in size to Sysdebug files
You can produce a listing from a Langx file with the Fault
Analyzer IDILANGP utility
The listing is similar to a compiler listing
However, Langx files are not directly "human readable"
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
15
15
Source Information Files:
Expanded program source files
An expanded program source file is program source code that
has been expanded (preprocessed) by the compiler
It contains statements generated from PLI %include, C
#include, in-line functions, macro expansions, and so on
Advantage: Use it with PLI, C, and C++ compilers to see
complete source information in some PD tools
Preprocess
Compiler
Program
Source
Compile
LOADLIB
Link Edit
Compiler
Load
module
Expanded
source file
(PDS)
File format:
PDSE or PDS or sequential
any file attributes supported by the compiler
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
16
16
Source Information Files: Sysadata files
A Sysadata file is a special file format that is produced by
the assembler
ADATA assembler option
It can be processed directly by
Fault Analyzer or APA, or used
as input to the xxxLANGX
utility to create a Langx file
LOADLIB
Link Edit
Assembler
Program
Source
SY
SA
DD DAT
The assembler generates a sysadata file when you
specify the ADATA assembler option
Load
module
A
Sysadata
file
(PDS)
File format:
PDSE or PDS
LRECL=(8188 to 32K-4),RECFM=VB,BLKSIZE=(lrecl+4 to 32K)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
17
17
Tip: you can Print a Listing from a Sysdebug or Langx file
You can print a listing from a Sysdebug or Langx file
With the Fault Analyzer IDILANGP utility program
Or equivalent Debug Tool utility EQALANGP
The following example JCL will print a listing to SYSOUT:
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
18
18
Tip:You can View a Listing from a Sysdebug or Langx file
You
Youcan
canalso
also"View"
"View"aa
listing
directly
listing directlyfrom
fromaa
Sysdebug
or
Langx
Sysdebug or Langxfile
file
First,
First,go
gototothe
theISPF
ISPFData
DataSet
Set
List
Listutility
utility (option
(option3.4
3.4on
onmost
most
systems)
systems)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
19
19
Tip: You can View a Listing from a Sysdebug or Langx file
Display
Displayyour
yourSysdebug
Sysdebugor
or
Langx
Langxfile
fileininthe
thedata
dataset
setlist
list
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
20
20
Tip: You can View a Listing from a Sysdebug or Langx file
This
ThisisisaaSysdebug
SysdebugPDS
PDS
The
The MM command
command
displays
displaysaamember
memberlist
list
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
21
21
Tip: View a Listing from a Sysdebug or Langx file
This
Thisisisthe
themember
memberyou
youwant
wanttotoview
view
Use
Usethe
the IDILANGP
IDILANGP or
or EQALANGP
EQALANGP
command
to
run
the
utility
command to run the utility
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
22
22
Tip: View a Listing from a Sysdebug or Langx file
The
Thelisting
listingcontains
containsthe
theprogram,
program,and
and
offsets
offsetstotostatements
statementsand
andvariables
variables
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
23
23
Promote Source Information for PD tools
Retain source information throughout the program life cycle
Update your promotion processes to retain source info
As a general rule, create one source information library (PDS or
PDSE) for each load library
Sysdebug, Langx, Sysadata, Expanded source,
or Compiler Listing Libraries
LOADLIBs
PROD
PROGA
Load
module
Promote
QA
PROGA
PROGA
© 2007 IBM Corporation
June 6, 2007
PROD
Promote
PROGA
Promote
TEST
PROGA
QA
Promote
PROGA
When
WhenaaLoad
LoadModule
Module
isispromoted,
promoted,you
you
should
shouldalso
alsopromote
promote
the
thecorresponding
corresponding
source
sourceinfo
infofiles.
files.
AApromotion
promotionmay
maybe
beaa
Recompile,
Recompile,Copy,
Copy,or
orMove.
Move.
TEST
Preparing programs for IBM PD tools
zSeries PD tools
24
24
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
25
25
Enterprise COBOL and recent COBOL compilers
This topic describes how to prepare programs using:
Enterprise COBOL
IBM's latest z/OS COBOL compiler
Status:
later releases are in service
COBOL for OS/390 and VM
Status:
withdrawn from z/OS service 12/2004
COBOL for MVS and VM
Status:
withdrawn from service 12/2001
For more information on these compilers, see:
IBM COBOL Family:
http://www.ibm.com/software/awdtools/cobol/
Release history:
www.ibm.com/servers/eserver/zseries/zos/le/history/history.html
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
26
26
Enterprise COBOL and recent COBOL compilers
General recommendation for both test and production:
Create and save a Sysdebug file
In a PDSE or PDS (member name = program name)
Use the compiler parm:
TEST(NONE,SYM,SEPARATE)
Why is this the recommended method?
The sysdebug file can be used by all of the PD tools products
The load module is "production-ready"
No additional run-time overhead
It can be copied directly into production without performance concerns
The sysdebug file can be automatically located by some tools
The compiler puts the name of the sysdebug file in the module
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
27
27
Enterprise COBOL and recent COBOL compilers
Optional recommendation:
IF the load module will NOT be used in production (it will be
used for testing only), then consider using compiler parms:
TEST(ALL,SYM,SEPARATE)
NOOPTIMIZE (recommended)
Save a sysdebug file as a PDSE or PDS member with the same
member name as the program
Recompile with TEST(NONE) or NOTEST before using in
production to remove run-time overhead
When would you use this method instead of the general
recommendation?
If the Debug Tool "Dynamic Debug" facility was not installed
If you need to use Debug Tool with programs in z/OS "protected
storage"
for example, DB2 stored procedures may run protected
This is not a concern for most applications
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
28
28
Source information files supported by PD tools
LE COBOL compilers, including Enterprise COBOL
Source Info Compiler
File Type
Options
Prod
Ready
Debug
Fault
Tool Analyzer APA
Sysdebug
TEST(NONE,SYM,SEPARATE)
Sysdebug
TEST(ALL,SYM,SEP),NOOPT
Compiler
Listing
TEST(xxx,xxx,NOSEP), LIST, MAP,
SOURCE, XREF, NONUMBER
Compiler
Listing
TEST(xxx,xxx,NOSEP), LIST, MAP,
SOURCE, XREF, NUMBER
Compiler
Listing
NOTEST, LIST, MAP, SOURCE,
XREF, NONUMBER
Compiler
Listing
NOTEST, LIST, MAP, SOURCE,
XREF, NUMBER
Langx file
LIST, MAP, SOURCE, XREF
= Recommended for production and test
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
= A good option for test only
zSeries PD tools
29
29
The LE COBOL TEST Compiler Option
General recommendation: TEST(NONE,SYM,SEPARATE)
Optional recommendation for test only: TEST(ALL,SYM,SEPARATE)
NONE : will not place hooks into the program
• Dynamic debug is used by Debug Tool
• No run-time overhead when not debugging!
ALL: debug hooks are placed at all statements and path points
SYM: generate symbolics (required by the PD tools products)
SEPARATE: store symbolics information in a Sysdebug file
NOSEPARATE: store the symbolics information in the load module
• This makes the load module much larger
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
30
30
LE COBOL: Other Considerations
You must use the TEST compiler parm to use Debug Tool
The NOOPTIMIZE parm is recommended for Debug Tool
DT has some restrictions with OPTIMIZE:
The GOTO and JUMPTO commands are disabled
The SET WARN OFF setting is required before you can change
variable values
The PD tools can use Compiler Listings instead of
Sysdebug files, however:
Compiler options LIST,MAP,SOURCE,XREF are required
To use a listing, Debug Tool also requires the
TEST(xxx, xxx, NOSEPARATE) compiler option
This option makes the load module much larger
To use a compiler listing with APA, you must also use the
NONUMBER compiler option
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
31
31
LE COBOL: Other Considerations
Do you want be able to start Debug Tool automatically, using Debug Tool
menu option 6 in ISPF?
This makes starting Debug Tool very, very easy!
Strongly recommended for, at least, IMS programs and DB2 stored
procedures
Link-edit the Debug Tool LE startup exit module into your application load
module
For batch applications:
EQADBCXT
For online IMS applications: EQADICXT
For DB2 stored procedures: EQADDCXT
For CICS applications:
(do not use this method)
The exits are in the Debug Tool SEQAMOD load library
Note: The exit adds a small amount of overhead when the program starts
you may or may not consider this to be production-ready
The exit can optionally be link-edited into a copy of LE module CEEBINIT (for
or CEEPIPI (for DB2 SPs)
To avoid linking the exit into your application module
Then you can STEPLIB or JOBLIB to the LE module with the exit
batch and IMS)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
32
32
Example: Prepare an Enterprise COBOL program
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
In this example,
an Enterprise
COBOL program
is prepared for
the IBM PD tools:
DT, FA, APA
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
33
33
Example: Prepare an Enterprise COBOL program
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
Program
Programname
name
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
34
34
Example: Prepare an Enterprise COBOL program
The
Thecompiler
compiler
“TEST”
“TEST”option
optionisis
specified
specified
The
TheSYSPRINT
SYSPRINT
DD
DDisisthe
the
compiler
compilerlisting
listing
(output)
(output)
Source
Source
(input)
(input)
The
TheSYSDEBUG
SYSDEBUG
DD
DDisisthe
the
Sysdebug
Sysdebugfile
file
(output)
(output)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
35
35
Example: Prepare an Enterprise COBOL program
Optional
Optionalstep
stepto
to
copy
the
copy the
compiler
compilerlisting
listing
to
toSysout
Sysout
Load
Load
module
module
(output)
(output)
The
TheLE
LEexit
exitfor
for
Debug
DebugTool
Toolisis
optional
optional
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
36
36
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
37
37
VS COBOL II compiler
This topic describes how to prepare programs using:
VS COBOL II
Status: withdrawn from service March, 2001
The last release was v1.4.0
Information is available about IBM COBOL compilers
The Migration Guide describes how to migrate to the latest
COBOL compiler. Available at:
http://www.ibm.com/software/awdtools/cobol/zos/library/
IBM COBOL Family:
http://www.ibm.com/software/awdtools/cobol/
Release history:
www.ibm.com/servers/eserver/zseries/zos/le/history/history.html
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
38
38
VS COBOL II compiler
Recommendation for Test environments only:
Create and save a Compiler Listing
In a PDSE or PDS (member name = program name)
Use compiler parms:
TEST,LIST,MAP,SOURCE,XREF,NONUMBER
Recompile the program with different options for production
Why is this the recommended method?
The Compiler Listing can be used by all of the PD tools products
The TEST parm prepares the program for Debug Tool
Why is this typically considered a "testing-only" configuration?
A COBOL II module generated with the TEST parm has run-time
overhead:
the compiler places "debug hooks" at statements and path points
symbol tables are stored in the module, which makes it much larger
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
39
39
VS COBOL II compiler
Recommendation for Production environments:
Create and save a Compiler Listing
In a PDSE or PDS (member name = program name)
Use compiler parms:
NOTEST,LIST,MAP,SOURCE,XREF,NONUMBER
Why is this the recommended method?
With NOTEST, there is no debugging overhead in the module
The Compiler Listing can be used by all of the PD tools products
Why is this typically considered a "production-only"
configuration?
Debug Tool cannot be used with a module compiled with NOTEST
However, if you do not use Debug Tool, use this configuration for
both test and production
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
40
40
VS COBOL II compiler
Optional recommendation:
IF you want to reduce the amount of disk space needed to save
compiler listings, and
You do not plan to use Debug Tool
Then consider creating Langx files
What are the considerations for using this method instead of the
general recommendations?
Advantages:
Langx files are smaller than listings
You can reproduce a listing (similar to a compiler listing) from a
Langx file, using the IDILANGP utility
Disadvantages:
Langx files are compressed and therefore not "human-readable"
The Langx file cannot be used by Debug Tool
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
41
41
Source information files supported by PD tools
VS COBOL II
Source Info
File Type
Compiler
Listing
Compiler
Options
TEST, LIST, MAP, SOURCE,
XREF, NONUMBER
Compiler
Listing
TEST, LIST, MAP, SOURCE,
XREF, NUMBER
Compiler
Listing
NOTEST, LIST, MAP, SOURCE,
XREF, NONUMBER
Compiler
Listing
NOTEST, LIST, MAP, SOURCE,
XREF, NUMBER
Langx file
NOTEST, LIST, MAP, SOURCE,
XREF (either NUM or NONUM)
= Recommended for production
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
Prod
Ready
Debug
Fault
Tool Analyzer APA
= Recommended for test
zSeries PD tools
42
42
VS COBOL II Compiler Options
Recommendation for test:
TEST, LIST, MAP, SOURCE, XREF, NONUMBER
Recommendation for production:
NOTEST, LIST, MAP, SOURCE, XREF, NONUMBER
TEST : will prepare the program for Debug Tool
Debug hooks are placed at all statements and path points
• This adds some run-time overhead when not debugging
Symbolics information is stored in the load module
• This makes the load module much larger
LIST,MAP,SOURCE,XREF: puts information in the compiler listing
that is needed by PD tools
NONUMBER: is required by APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
43
43
VS COBOL II: Other Considerations
You must use the TEST compiler parm to use Debug Tool
The xxxLANGX utility requires compiler options:
LIST,MAP,SOURCE,XREF
To use a compiler listing with APA, you must use the
NONUMBER compiler option
Either NUMBER or NONUMBER is OK for Debug Tool and
Fault Analyzer
For Debug Tool, you must link-edit the module using the LE
run-time library, NOT the COBOL II run-time library
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
44
44
VS COBOL II: Other Considerations
Do you want be able to start Debug Tool automatically, using Debug Tool menu
option 6 in ISPF?
This makes starting Debug Tool very, very easy!
Strongly recommended for, at least, online IMS programs and DB2 stored
procedures
Link-edit the Debug Tool LE startup exit module into your application load
module
For batch applications:
EQADBCXT
For online IMS applications: EQADICXT
For DB2 stored procedures: EQADDCXT
For CICS applications:
(do not use this method)
The exits are in the Debug Tool SEQAMOD load library
Note: The exit adds a small amount of overhead when the program starts
you may or may not consider this to be production-ready
The exit can optionally be link-edited into a copy of LE module CEEBINIT (for
or CEEPIPI (for DB2 SPs)
To avoid linking the exit into your application module
Then you can STEPLIB or JOBLIB to the LE module with the exit
batch and IMS)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
45
45
Example: Prepare a COBOL II program
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
In this example, a
COBOL II
program is
prepared for the
IBM PD tools: DT,
FA, APA
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
46
46
Example: Prepare a COBOL II program
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
Program
Programname
name
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
47
47
Example: Prepare a COBOL II program
Specify
Specifyoptions
options
needed
neededby
byPD
PDtools
tools
The
TheSYSPRINT
SYSPRINT
DD
DDisisthe
the
compiler
compilerlisting
listing
(output)
(output)
Source
Source
(input)
(input)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
48
48
Example: Prepare a COBOL II program
Optional
Optionalstep
stepto
to
copy
copythe
the
compiler
compilerlisting
listing
to
toSysout
Sysout
Load
Load
module
module
(output)
(output)
The
TheLE
LEexit
exitfor
for
Debug
DebugTool
Toolisis
optional
optional
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
49
49
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
50
50
OS/VS COBOL compiler
This topic describes how to prepare programs using:
OS/VS COBOL
Status: withdrawn from service June, 1994
The last release was v1.2.4
Information is available about IBM COBOL compilers
The Migration Guide describes how to migrate to the latest
COBOL compiler. Available at:
http://www.ibm.com/software/awdtools/cobol/zos/library/
IBM COBOL Family:
http://www.ibm.com/software/awdtools/cobol/
Release history:
www.ibm.com/servers/eserver/zseries/zos/le/history/history.html
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
51
51
OS/VS COBOL compiler
General recommendation for both test and production:
Create and save a Langx file
In a PDSE or PDS (member name = program name)
Use compiler parms:
NOBATCH, NOCLIST, NOCOUNT, DMAP, NOLST, PMAP, SOURCE,
NOSYMDMP, NOTEST, VERB, XREF
Why is this the recommended method?
The Langx file can be used by all of the PD tools products
The load module is "production-ready"
No additional run-time overhead
It can be copied directly into production without performance
concerns
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
52
52
Source information files supported by PD tools
OS/VS COBOL
Source Info
File Type
Compiler
Listing
Compiler
Options
Prod
Ready
Debug
Fault
Tool Analyzer APA
DMAP, NOCLIST, NOLST, PMAP,
SOURCE, VERB, XREF
Compiler
Listing
(LIST,NOPMAP) or
(CLIST,NOPMAP) or
(CLIST,PMAP)
Langx file
NOBATCH, NOCLIST, NOCOUNT,
DMAP, NOLST, PMAP, SOURCE,
NOSYMDMP, NOTEST, VERB,
XREF
= Recommended for production and test
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
53
53
OS/VS COBOL: Other Considerations
The NOOPTIMIZE parm is recommended for Debug Tool
In some cases, it can be confusing since there may not be a
1 to 1 correlation between source statements and object code
For Debug Tool, you must link-edit the module using the LE
run-time library, NOT the OS/VS COBOL libs
For OS/VS COBOL, there is no advantage in linking the LE
exit programs into the application load module
exit programs EQADIxXt
Since OS/VS COBOL programs are not standard LE
programs, the LE initialization exit is not invoked
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
54
54
Example: Prepare an OS/VS COBOL program
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
In this example,
an OS/VS
COBOL program
is prepared for
the IBM PD tools:
DT, FA, APA
© 2007 IBM Corporation
June 6, 2007
PF8
Preparing programs for IBM PD tools
zSeries PD tools
55
55
Example: Prepare an OS/VS COBOL program
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
Program
Programname
name
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
56
56
Example: Prepare an OS/VS COBOL program
Specify
Specifyoptions
optionsneeded
needed
by
the
LANGX
by the LANGXprocessor
processor
The
TheSYSPRINT
SYSPRINT
DD
DDisisthe
the
compiler
compilerlisting
listing
(output)
(output)
Source
Source
(input)
(input)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
57
57
Example: Prepare an OS/VS COBOL program
Optional
Optionalstep
stepto
to
copy
the
copy the
compiler
compilerlisting
listing
to
toSysout
Sysout
The
ThexxxLANGX
xxxLANGX
utility
utilityreads
readsthe
the
compiler
compilerlisting
listing
and
andproduces
producesaa
Langx
Langxfile
file
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
Langx
Langx
file
file
(output)
(output)
58
58
Example: Prepare an OS/VS COBOL program
Link Edit step
You
Youmust
mustuse
use
the
theLE
LErun-time
run-time
library
library(not
(notthe
the
OS/VS
COBOL
OS/VS COBOL
libs)
libs)
© 2007 IBM Corporation
June 6, 2007
Load
Load
module
module
(output)
(output)
Preparing programs for IBM PD tools
zSeries PD tools
59
59
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
60
60
Enterprise PLI compiler v3.5 and later
This topic describes how to prepare programs using:
Enterprise PLI v3.5 and later
Status: IBM's latest z/OS PLI compiler
Information is available about IBM PLI compilers
IBM PLI Family:
http://www.ibm.com/software/awdtools/pli/
Release history:
http://www.ibm.com/servers/eserver/zseries/zos/le/history/plimvs.html
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
61
61
Enterprise PLI compiler v3.5 and later
Recommendation for Test environments (and optionally
production):
Preprocess the PLI program (perform a 2-stage compile)
In the first compile step, INCLUDEs and Macros are expanded
Note: you may have preprocessing steps for CICS, DB2, and so
on that run before stage 1
In the second compile step:
Create and save a Sysdebug file (for Debug Tool)
• In a PDSE or PDS (member name = program name)
Use compiler parms:
• For DT: TEST(ALL,SYM,NOHOOK,SEP),NOOPTIMIZE
• For Langx: AGGREGATE, ATTRIBUTES(FULL), NOBLKOFF, LIST, MAP,
NEST, NONUMBER, OPTIONS, SOURCE, STMT, XREF(FULL)
• For PD tools V6 and earlier, also: OFFSET
Create and save a Langx file (for FA and APA)
In a PDSE or PDS (member name = program name)
(continued on the next page)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
62
62
Enterprise PLI compiler v3.5 and later
Recommendation for Test environments (optionally production):
Why is this the recommended method?
This method produces the smallest module that can be used with
Debug Tool
No run-time CPU overhead is added when not debugging
because of the NOHOOK option
Can the load module be used in production?
Yes, if the following are not concerns:
The TEST parm (needed for Debug Tool) makes the module larger,
since the statement table is stored in the module
• most debug info is stored in the Sysdebug file, but some remains
• note: this is a difference between Enterprise PLI and COBOL
• Due to the increased module size you may or may not consider it to
be production-ready
The NOOPTIMIZE parm is required for Debug Tool
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
63
63
Enterprise PLI compiler v3.5 and later
Optional recommendation for Test environments only:
IF the load module will NOT be used in production (it will be
used for testing only), then consider:
Use the previous configuration, but change the TEST parm to:
TEST(ALL,SYM,HOOK,SEP)
NOPT
(hook instead of nohook)
(required for DT)
Recompile with TEST(… ,NOHOOK, …) or NOTEST before using in
production
When would you use this method instead of the general Test
recommendation?
If the Debug Tool "Dynamic Debug" facility was not installed
If you need to use Debug Tool with programs in z/OS "protected
storage"
for example, DB2 stored procedures may run protected
not a concern for most applications
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
64
64
Enterprise PLI compiler v3.5 and later
Recommendation for Production environments (and optionally Test if
you do not use Debug Tool):
Create and save a Langx file
In a PDSE or PDS (member name = program name)
Use compiler parms:
NOTEST, AGGREGATE, ATTRIBUTES(FULL), NOBLKOFF, LIST,
MAP, NEST, NONUMBER, OPTIONS, SOURCE, STMT, XREF(FULL)
• For PD tools V6 and earlier, also: OFFSET
Why is this the recommended method?
The Langx file can be used by both FA and APA
The load module is "production-ready"
No additional debbugging overhead or increased size
Why is this typically considered a "production-only" configuration?
Debug Tool cannot be used with a module compiled with NOTEST
However, if you do not use Debug Tool, use this configuration for
both test and production
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
65
65
Source information files supported by PD tools
Enterprise PLI v3.5 and later
Source Info Compiler
Prod Debug
Fault
File Type
Options
Ready Tool Analyzer APA
Preprocess (1st stage) to expand source, In note 1
Sysdebug
Sysdebug
Expanded
source file
Compiler
Listing
Langx file
compile (2nd stage):
TEST(ALL,SYM,NOHOOK,SEP), NOPT
Preprocess (1st stage) to expand source, In
compile (2nd stage):
These
Thesecan
canbe
becombined
combined(use
(useTEST)
TEST)
TEST(ALL,SYM,HOOK,SEP), NOPT
st
Preprocess (1 stage) to expand source, In
compile (2nd stage):
TEST(ALL,SYM,HOOK,SEP), NOPT
AGGREGATE, ATTRIBUTES(FULL),
NOBLKOFF, LIST, MAP, NEST, NOTEST,
NONUMBER, OFFSET, OPTIONS,
SOURCE, STMT, XREF(FULL))
= Recommended for production and test
= Recommended for test (and optionally production)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
Note 1: Module is larger than with
NOTEST parm
zSeries PD tools
66
66
Enterprise PLI compiler v3.5 and later
Considerations
If you will use both Enterprise PLI 3.5 (or later), and a previous
version (3.4 or earlier), then:
consider using the recommendations in the next topic (v3.4)
that way, source information files can be being handled the same
way for all versions of your Enterprise PLI compilers
Why do you recommend a 2-stage compile when Debug Tool will be
used?
The preprocessor (stage 1) will expand INCLUDEs and macros
If you do not, the Sysdebug file will not have this information
Also, the expanded source file is a "snapshot" of the program
So the original source can be updated, and you can still debug the
load module
You MUST use the TEST and NOOPTIMIZE compiler parms to use
Debug Tool
The TEST parm is not needed if you will not debug the program
using Debug Tool
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
67
67
Enterprise PLI compiler v3.5 and later
Other Considerations
Do you want be able to start Debug Tool automatically, using Debug Tool menu
option 6 in ISPF?
This makes starting Debug Tool very, very easy!
Strongly recommended for, at least, IMS programs and DB2 stored
procedures
Link-edit the Debug Tool LE startup exit module into your application load
module
For batch applications:
EQADBCXT
For online IMS applications: EQADICXT
For DB2 stored procedures: EQADDCXT
For CICS applications:
(do not use this method)
The exits are in the Debug Tool SEQAMOD load library
Note: The exit adds a small amount of overhead when the program starts
you may or may not consider this to be production-ready
The exit can optionally be link-edited into a copy of LE module CEEBINIT (for
or CEEPIPI (for DB2 SPs)
To avoid linking the exit into your application module
Then you can STEPLIB or JOBLIB to the LE module with the exit
batch and IMS)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
68
68
Example: Prepare an Enterprise PLI v3.5+ program
This
Thissample
sampleisisinin
the
thelab
labJCL
JCLPDS
PDS
In this example,
an Enterprise PLI
v3.5 program is
prepared for the
IBM PD tools: DT,
FA, APA
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
69
69
Example: Prepare an Enterprise PLI v3.5+ program
This
Thissample
sampleisisinin
the
thelab
labJCL
JCLPDS
PDS
Program
Programname
name
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
70
70
Example: Prepare an Enterprise PLI v3.5+ program
This
Thisstep
stepwill
will
expand
expandINCLUDEs
INCLUDEs
and
andmacros
macrosininthe
the
source
sourceprogram
program
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
71
71
Example: Prepare an Enterprise PLI v3.5+ program
Program
Programsource
source
(input)
(input)
Expanded
Expanded
source
sourcefile
file
(output)
(output)
PF8
The
Thecorrect
correct
compiler
compilerparms
parmsare
are
specified
specified
The
TheSYSPRINT
SYSPRINT
DD
DDisisthe
the
compiler
compilerlisting
listing
(output)
(output)
© 2007 IBM Corporation
June 6, 2007
Expanded
Expanded
source
sourcefile
file
(input)
(input)
Preparing programs for IBM PD tools
zSeries PD tools
72
72
Example: Prepare an Enterprise PLI v3.5+ program
The
TheSYSDEBUG
SYSDEBUG
DD
DDisisthe
the
Sysdebug
Sysdebugfile
file
(output)
(output)
Optional
Optionalstep
stepto
to
copy
copythe
the
compiler
compilerlisting
listing
to
toSysout
Sysout
The
TheIDILANGX
IDILANGX
DD
DDisisthe
the
Langx
Langxfile
file
(output)
(output)
Compiler
CompilerListing
Listing
(input)
(input)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
73
73
Example: Prepare an Enterprise PLI v3.5+ program
Some
SomePLI
PLI
programs
programsrequire
require
aapre-link
pre-linkstep
step
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
74
74
Example: Prepare an Enterprise PLI v3.5+ program
Load
Load
module
module
(output)
(output)
The
TheLE
LEexit
exitfor
for
Debug
DebugTool
Toolisis
optional
optional
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
75
75
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
76
76
Enterprise PLI compiler v3.4 and earlier
This topic describes how to prepare programs using:
Enterprise PLI v3.4 and earlier
Status:
v3.4 withdrawal from service Sept 2008
v3.3 withdrawal from service Sept 2007
Information is available about IBM PLI compilers
IBM PLI Family:
http://www.ibm.com/software/awdtools/pli/
Release history:
http://www.ibm.com/servers/eserver/zseries/zos/le/history/plimvs.html
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
77
77
Enterprise PLI compiler v3.4 and earlier
Recommendation for Test environments only
Preprocess the PLI program (perform a 2-stage compile)
In the 1st compile step, INCLUDEs and Macros are expanded
In the 2nd compile step:
Create and save an Expanded Source file (for Debug Tool)
• In a PDSE or PDS (member name = program name)
Use compiler parms:
• For DT: TEST(ALL),NOOPTIMIZE
• For Langx: AGGREGATE, ATTRIBUTES(FULL), NOBLKOFF,
LIST, MAP, NEST, NONUMBER, OPTIONS, SOURCE, STMT,
XREF(FULL)
Create and save a Langx file (for FA and APA)
In a PDSE or PDS (member name = program name)
(continued on the next page)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
78
78
Enterprise PLI compiler v3.4 and earlier
Recommendation for Test environments only
Why is this the recommended method?
This method produces a module that can be used with Debug Tool
(and the other PD tools products)
The Expanded Source file can be used by Debug Tool
The Langx file can be used by FA and APA
Why is this typically considered a "testing-only" configuration?
A module generated with the TEST parm has run-time overhead:
the compiler places "debug hooks" at statements and path points
symbol tables are stored in the module, which makes it much larger
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
79
79
Enterprise PLI compiler v3.4 and earlier
Recommendation for Production environments (and optionally Test if
you do not use Debug Tool):
Create and save a Langx file
In a PDSE or PDS (member name = program name)
Use compiler parms:
NOTEST, AGGREGATE, ATTRIBUTES(FULL), ESD, LIST, MAP,
NEST, OPTIONS, SOURCE, STMT, XREF(FULL)
Why is this the recommended method?
The Langx file can be used by both FA and APA
The load module is "production-ready"
No additional debbugging overhead or increased size
Why is this typically considered a "production-only" configuration?
Debug Tool cannot be used with a module compiled with NOTEST
However, if you do not use Debug Tool, use this configuration for
both test and production
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
80
80
Source information files supported by PD tools
Enterprise PLI v3.4 and earlier
Source Info
File Type
Expanded
source file
Compiler
Listing
Langx file
Compiler
Options
Prod
Ready
Preprocess (1st stage) to expand
source, In compile (2nd stage):
TEST(ALL),NOPT
AGGREGATE,
ATTRIBUTES(FULL), NOBLKOFF,
LIST, MAP, NEST, NOTEST,
NONUMBER, OFFSET, OPTIONS,
SOURCE, STMT, XREF(FULL))
Debug
Fault
Tool Analyzer APA
These
Thesecan
canbe
becombined
combined
(replace
(replaceNOTEST
NOTESTwith
withTEST)
TEST)
= Recommended for production and test
= Recommended for test only
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
81
81
Enterprise PLI compiler v3.4 and earlier
Considerations
Why do you recommend a 2-stage compile when Debug Tool will
be used?
The preprocessor (stage 1) will expand INCLUDEs and
macros
If you do not, the source file will not have this information
Also, the expanded source file is a "snapshot" of the program
So the original source can be updated, and you can still debug
the load module
You MUST use the TEST compiler parm to use Debug Tool
The TEST parm is not needed if you will not debug the
program using Debug Tool
You MUST use the NOOPTIMIZE compiler parm to use Debug
Tool with Enterprise PLI
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
82
82
Enterprise PLI compiler v3.4 and earlier
Do you want be able to start Debug Tool automatically, using Debug Tool menu
option 6 in ISPF?
This makes starting Debug Tool very, very easy!
Strongly recommended for, at least, online IMS programs and DB2 stored
procedures
Link-edit the Debug Tool LE startup exit module into your application load
module
For batch applications:
EQADBCXT
For online IMS applications: EQADICXT
For DB2 stored procedures: EQADDCXT
For CICS applications:
(do not use this method)
The exits are in the Debug Tool SEQAMOD load library
Note: The exit adds a small amount of overhead when the program starts
you may or may not consider this to be production-ready
The exit can optionally be link-edited into a copy of LE module CEEBINIT (for
or CEEPIPI (for DB2 SPs)
To avoid linking the exit into your application module
Then you can STEPLIB or JOBLIB to the LE module with the exit
batch and IMS)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
83
83
Enterprise PLI compiler v3.4 and earlier
For CICS applications only, will you use the DTCN transaction to
start Debug Tool ?
This is not needed if:
you are using the CADP transaction and/or
you have Enterprise PLI v3.4 or later, with PTF PK03264
applied
Link-edit the Debug Tool CICS startup exit module into your
application load module
module: EQADCCXT
The exit is in the Debug Tool load library:
hlq-for-dt.SEQAMOD
Note: The exit adds a small amount of overhead when the
program starts
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
84
84
Example: Prepare a program
with Enterprise PLI v3.4 and earlier
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
In this example,
an Enterprise PLI
v3.4 program is
prepared for the
IBM PD tools: DT,
FA, APA
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
85
85
Example: Prepare a program
with Enterprise PLI v3.4 and earlier
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
Program
Programname
name
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
86
86
Example: Prepare a program
with Enterprise PLI v3.4 and earlier
This
Thisstep
stepwill
willexpand
expand
INCLUDEs
INCLUDEsand
and
macros
macrosininthe
thesource
source
program
program
Program
Programsource
source
(input)
(input)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
87
87
Example: Prepare a program
with Enterprise PLI v3.4 and earlier
Expanded
Expanded
source
sourcefile
file
(output)
(output)
The
Thecorrect
correct
compiler
compilerparms
parmsare
are
specified
specified
PF8
Expanded
Expandedsource
source
file
file(input)
(input)
The
TheSYSPRINT
SYSPRINT
DD
DDisisthe
the
compiler
compilerlisting
listing
(output)
(output)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
88
88
Example: Prepare a program
with Enterprise PLI v3.4 and earlier
Optional
Optionalstep
stepto
to
copy
copythe
the
compiler
compilerlisting
listing
to
toSysout
Sysout
The
TheIDILANGX
IDILANGX
DD
DDisisthe
the
Langx
Langxfile
file
(output)
(output)
Compiler
CompilerListing
Listing
(input)
(input)
Some
SomePLI
PLI
programs
programsrequire
require
aapre-link
pre-linkstep
step
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
89
89
Example: Prepare a program
with Enterprise PLI v3.4 and earlier
Load
Load
module
module
(output)
(output)
The
TheLE
LEexit
exitfor
for
Debug
DebugTool
Toolisis
optional
optional
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
90
90
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
91
91
PLI for MVS and VM / OS PLI
This topic describes how to prepare programs using:
PLI for MVS and VM
Status:
in service
OS PLI for MVS and VM
Status:
withdrawn from service December 2003
the last release was v2.3
Information is available about IBM PLI compilers
IBM PLI Family:
http://www.ibm.com/software/awdtools/pli/
Release history:
http://www.ibm.com/servers/eserver/zseries/zos/le/history/plimvs.html
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
92
92
PLI for MVS and VM / OS PLI
Recommendation for Test environments only
Create and save a Compiler Listing (for Debug Tool)
In a PDSE or PDS (member name = program name)
Create and save a Langx file (for FA and APA)
In a PDSE or PDS (member name = program name)
Use compiler parms:
For DT: TEST(ALL),NOOPTIMIZE
For Langx: AGGREGATE, ATTRIBUTES(FULL), ESD, LIST, MAP,
NEST, OPTIONS, SOURCE, STMT, XREF(FULL)
(continued on the next page)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
93
93
PLI for MVS and VM / OS PLI
Recommendation for Test environments only
Why is this the recommended method?
The TEST parm prepares the program for Debug Tool
The Compiler Listing can be used by Debug Tool
The Langx file can be used by FA and APA
Why is this typically considered a "testing-only" configuration?
A module generated with the TEST parm has run-time overhead:
the compiler places "debug hooks" at statements and path points
symbol tables are stored in the module, which makes it much larger
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
94
94
PLI for MVS and VM / OS PLI
Recommendation for Production environments (and optionally Test if
you do not use Debug Tool):
Create and save a Langx file
In a PDSE or PDS (member name = program name)
Use compiler parms:
NOTEST, AGGREGATE, ATTRIBUTES(FULL), ESD, LIST, MAP, NEST,
OPTIONS, SOURCE, STMT, XREF(FULL)
Why is this the recommended method?
The Langx file can be used by both FA and APA
The load module is "production-ready"
No additional debbugging overhead or increased size
Why is this typically considered a "production-only" configuration?
Debug Tool cannot be used with a module compiled with NOTEST
However, if you do not use Debug Tool, use this configuration for
both test and production
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
95
95
Source information files supported by PD tools
PLI for MVS and VM, and OS PLI
Source Info
File Type
Compiler
Listing
Langx file
Compiler
Listing
Langx file
Compiler
Options
Prod
Ready
TEST(ALL), AGGREGATE,
ATTRIBUTES(FULL), ESD, LIST,
MAP, NEST, OPTIONS, SOURCE,
STMT, XREF(FULL)
NOTEST, AGGREGATE,
ATTRIBUTES(FULL), ESD, LIST,
MAP, NEST, OPTIONS, SOURCE,
STMT, XREF(FULL)
Debug
Fault
Tool Analyzer APA
= Recommended for production and test
= Recommended for test only
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
96
96
PLI for MVS and VM / OS PLI
Considerations
You MUST use the TEST compiler parm to use Debug Tool
The TEST parm is not needed if you will not debug the
program using Debug Tool
The NOOPTIMIZE compiler parm is recommended with
Debug Tool
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
97
97
PLI for MVS and VM / OS PLI
Do you want be able to start Debug Tool automatically, using Debug Tool menu
option 6 in ISPF?
This makes starting Debug Tool very, very easy!
Strongly recommended for, at least, online IMS programs and DB2 stored
procedures
Link-edit the Debug Tool LE startup exit module into your application load
module
For batch applications:
EQADBCXT
For online IMS applications: EQADICXT
For DB2 stored procedures: EQADDCXT
For CICS applications:
(do not use this method)
The exits are in the Debug Tool SEQAMOD load library
Note: The exit adds a small amount of overhead when the program starts
you may or may not consider this to be production-ready
The exit can optionally be link-edited into a copy of LE module CEEBINIT (for
or CEEPIPI (for DB2 SPs)
To avoid linking the exit into your application module
Then you can STEPLIB or JOBLIB to the LE module with the exit
batch and IMS)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
98
98
PLI for MVS and VM / OS PLI
For CICS applications only, will you use the DTCN
transaction to start Debug Tool ?
This is not needed if you are using the CADP
transaction
Link-edit the Debug Tool CICS startup exit module into your
application load module
module: EQADCCXT
The exit is in the Debug Tool load library:
hlq-for-dt.SEQAMOD
Note: The exit adds a small amount of overhead when the
program starts
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
99
99
Example: Prepare a program
with PLI for MVS and VM
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
In this example,
an PLI for MVS
and VM program
is prepared for
the IBM PD tools:
DT, FA, APA
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
100
100
Example: Prepare a program
with PLI for MVS and VM
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
Program
Programname
name
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
101
101
Example: Prepare a program
with PLI for MVS and VM
The
Thecorrect
correct
compiler
compilerparms
parmsare
are
specified
specified
Program
Programsource
source
(input)
(input)
PF8
The
TheSYSPRINT
SYSPRINT
DD
DDisisthe
the
compiler
compilerlisting
listing
(output)
(output)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
102
102
Example: Prepare a program
with PLI for MVS and VM
Optional
Optionalstep
stepto
to
copy
copythe
the
compiler
compilerlisting
listing
to
toSysout
Sysout
The
TheIDILANGX
IDILANGX
DD
DDisisthe
the
Langx
Langxfile
file
(output)
(output)
Compiler
CompilerListing
Listing
(input)
(input)
Some
SomePLI
PLI
programs
programsrequire
require
aapre-link
pre-linkstep
step
© 2007 IBM Corporation
June 6, 2007
PF8
Preparing programs for IBM PD tools
zSeries PD tools
103
103
Example: Prepare a program
with PLI for MVS and VM
Load
Load
module
module
(output)
(output)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
104
104
Example: Prepare a program
with PLI for MVS and VM
The
TheLE
LEexit
exitfor
for
Debug
DebugTool
Toolisis
optional
optional
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
105
105
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
106
106
Assembler
This topic describes how to prepare programs using:
The High Level Assembler
For more information about the assembler, see:
High Level Assembler (HLASM) and Toolkit Feature:
http://www.ibm.com/software/awdtools/hlasm
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
107
107
Assembler
General recommendation for both test and production:
Create and save a Langx file
In a PDSE or PDS (member = CSECT or entry point name)
Use the assembler parm:
ADATA
If you will use APA, then also save the Sysadata file
In a PDSE or PDS (member name = csect or entry point name)
Why is this the recommended method?
The Langx file can be used by DT and FA
The ADATA file can be used by FA and APA
The load module is "production-ready"
No additional run-time overhead
It can be copied directly into production without performance concerns
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
108
108
Source information files supported by PD tools
Assembler
Source Info Compiler
File Type
Options
Sysadata
file
Langx file
Prod
Ready
Debug
Fault
Tool Analyzer APA
ADATA
ADATA
= Recommended for production and test
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
109
109
The Assembler ADATA Option
ADATA : Specifies that the assembler collect associated data and
write it to the SYSADATA DD.
A Sysadata file contains source and symbolics information about the
program
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
110
110
Example: Assemble a program
This
Thissample
sampleisisinin
the
lab
the labJCL
JCLPDS
PDS
In this example,
an Assembler
program is
prepared for the
IBM PD tools: DT,
FA, APA
Program
Programname
name
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
111
111
Example: Assemble a program
This
Thissample
sampleisisinin
the
thelab
labJCL
JCLPDS
PDS
The
TheADATA
ADATAparm
parm
isisspecified
specified
Program
Programsource
source
(input)
(input)
The
TheSYSADATA
SYSADATA
DD
DDisisthe
the
PF8
sysadata
sysadatafile
file
(output)
(output)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
112
112
Example: Assemble a program
The
TheIDILANGX
IDILANGX
DD
DDisisthe
the
Langx
Langxfile
file
(output)
(output)
Sysadata
Sysadatafile
file
(input)
(input)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
113
113
Example: Assemble a program
The
ThePD
PDtools
toolsdo
do
not
notneed
needany
any
changes
changesto
tothe
the
link
linkedit
editstep
step
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
114
114
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
115
115
C and C++
This topic describes how to prepare programs using:
z/OS XL C / C++
Status:
in service
Information is available about IBM C and C++ compilers
z/OS XL C / C++:
http://www.ibm.com/software/awdtools/czos
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
116
116
C and C++
Recommendation for Test environments (and optionally
production):
Preprocess the program (perform a 2-stage compile)
In the 1st compile step, INCLUDEs and macros are expanded
Create and save an Expanded Source file (for Debug Tool)
• In a PDSE or PDS (member name = program name)
In the 2nd compile step:
Create and save a Compiler Listing (for FA and APA)
• In a PDSE or PDS (member name = program name)
Use compiler parms:
• For DT: TEST(ALL), NOOPT
• For Langx: AGGREGATE, NOIPA, LIST, NOOFFSET, SOURCE,
STMT, XREF(FULL)
(continued on the next page)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
117
117
C and C++
Recommendation for Test environments only
Why is this the recommended method?
The TEST parm prepares the program for Debug Tool
The Expanded Source file can be used by Debug Tool
The Compiler Listing can be used by FA and APA
Why is this typically considered a "testing-only" configuration?
A module generated with the TEST parm has run-time overhead:
the compiler places "debug hooks" at statements and path points
symbol tables are stored in the module, which make it much larger
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
118
118
C and C++
Recommendation for Production environments (and optionally Test if
you do not use Debug Tool):
Create and save a Compiler Listing
In a PDSE or PDS (member name = program name)
Use compiler parms:
NOTEST, AGGREGATE, NOIPA, LIST, NOOFFSET, SOURCE, STMT,
XREF(FULL)
Why is this the recommended method?
The Compiler Listing can be used by both FA and APA
The load module is "production-ready"
No additional debbugging overhead or increased size
Why is this typically considered a "production-only" configuration?
Debug Tool cannot be used with a module compiled with NOTEST
However, if you do not use Debug Tool, use this configuration for
both test and production
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
119
119
Source information files supported by PD tools
C and C++
Source Info
File Type
Expanded
source file
Compiler
Listing
Langx file
Compiler
Options
Debug
Fault
Tool Analyzer APA
TEST(ALL)
TEST(ALL), AGGREGATE,
ATTRIBUTES(FULL), ESD, LIST,
MAP, NEST, OPTIONS, SOURCE,
STMT, XREF(FULL)
Compiler
Listing
Langx file
NOTEST, AGGREGATE,
ATTRIBUTES(FULL), ESD, LIST,
MAP, NEST, OPTIONS, SOURCE,
STMT, XREF(FULL)
Dwarf file
DEBUG(FORMAT(DWARF)),
HOOK(LINE,NOBLOCK,PATH),
SYMBOL, FILE(location)
= Recommended for production
© 2007 IBM Corporation
June 6, 2007
Prod
Ready
Preparing programs for IBM PD tools
= Recommended for test only
zSeries PD tools
120
120
C and C++
Other Considerations
To use Debug Tool, you must specify parms:
TEST, or DEBUG compiler parm to use Debug Tool
DEBUG and HOOK
The NOOPTIMIZE compiler parm is recommended with Debug
Tool
Why is a 2-stage compile recommend when Debug Tool will be
used?
The preprocessor (stage 1) will expand INCLUDEs and
macros
If you do not, the source file will not have this information
The expanded source file is a "snapshot" copy of the program
So the original source can be updated, and you can still debug
the load module
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
121
121
C and C++: Other Considerations
Do you want be able to start Debug Tool automatically, using Debug Tool menu
option 6 in ISPF?
This makes starting Debug Tool very, very easy!
Strongly recommended for, at least, online IMS programs and DB2 stored
procedures
Link-edit the Debug Tool LE startup exit module into your application load
module
For batch applications:
EQADBCXT
For online IMS applications: EQADICXT
For DB2 stored procedures: EQADDCXT
For CICS applications:
(do not use this method)
The exits are in the Debug Tool SEQAMOD load library
Note: The exit adds a small amount of overhead when the program starts
you may or may not consider this to be production-ready
The exit can optionally be link-edited into a copy of LE module CEEBINIT (for
or CEEPIPI (for DB2 SPs)
To avoid linking the exit into your application module
Then you can STEPLIB or JOBLIB to the LE module with the exit
batch and IMS)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
122
122
Example: Prepare a C program
In this example, a
C program is
prepared for the
IBM PD tools: DT,
FA, APA
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
123
123
Example: Prepare a C program
The
TheSYSUT10
SYSUT10
DD
DDisisthe
the
expanded
expandedsource
source
file
file(output)
(output)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
124
124
Example: Prepare a C program
Program
Programsource
source
(input)
(input)
The
Thecorrect
correct
compiler
compilerparms
parmsare
are
specified
specified
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
125
125
Example: Prepare a C program
The
TheSYSPRINT
SYSPRINT
DD
DDisisthe
the
compiler
compilerlisting
listing
(output)
(output)
PF8
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
126
126
Example: Prepare a C program
The
Theexpanded
expanded
source
sourcefile
file(input)
(input)
Load
Load
library
library
(output)
(output)
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
127
127
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
128
128
Source mapping in Debug Tool
When you debug a program, Debug Tool uses a source
information file to:
Display program source in the source window
Locate program statements and variables in storage
A source information file is created when a program is
compiled
It contains program statements and information about statements
and variables
Debug Tool requires a source information file
Without it, you can only debug in "disassembly" mode, where
object code is displayed, but no program statements or variables
Different compilers generate different kinds of source
information files
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
129
129
Source Information Files
Debug Tool can read source information in these formats:
Compiler
Sysdebug
File
Compiler
Listing
Langx Dwarf
File
File
Expanded
Source File
LE COBOL
(incl. Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI
PL/I for MVS and VM
OS PLI
C and C++
Assembler
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
130
130
How does Debug Tool know where to find a
Source Info File?
For newer compilers, the name of the source information file
may be stored in the load module by the compiler
Debug Tool will automatically find the source file
Works with Enterprise COBOL and Enterprise PLI
For other compilers, OR if the source information file has
been renamed, you must give DT the names of the source
files
You can use any of these methods:
With either interface, point to the source information files with
an EDADEBUG DD statement
In the 3270 interface:
• Use the SET DEFAULT LISTINGS file.name command
• Use the LISTINGS command
In the WDDz or WDz interface:
• Use the “Edit Source Lookup Path” wizard
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
131
131
Compiler NOTEST Option
■
■
NOTEST is the default compiler option in COBOL, PLI, C,
and C++
You do not have to recompile ALL of your programs with
TEST, only the ones you want to debug
■
■
You may still compile some of your programs with NOTEST
When debugging, NOTEST subprograms are run normally,
but not displayed by Debug Tool
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
132
Debug Tool skips over NOTEST CU's as if they do not exist
If you have routines which are frequently used... but seldom changed.. and
which you are confident that you will not need to debug (perhaps CUs that
read a record or do some standard calculation), you could compile them
NOTEST, so that calls to them are automatically bypassed.
132
Language compilation and usage considerations
for Debug Tool
Compiler TEST parm
Debug Tool requires the TEST compiler parm for COBOL,
PLI, and C/C++
not required for OS/VS COBOL or assembler
Compiler OPTIMIZE parm
For debugging, the NOOPTIMIZE compiler parm is
recommended for all languages
It can be confusing since there may not be a 1-1 correlation
between program statements and object code
There are restrictions when the OPTIMIZE parm is used:
• JUMPTO and GOTO debugger functions are disabled
• The SET WARN OFF command / setting is required
before you can change variable values
Debug Tool requires the NOOPTIMIZE compiler parm for
Enterprise PLI
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
133
133
Language compilation and usage considerations
for Debug Tool
For non-LE programs, the supplied LE exit cannot be used
to start Debug Tool. Includes:
OS/VS COBOL
non-LE assembler
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
134
134
Language compilation and usage considerations
for Debug Tool
Is my "debuggable" load module ready for production?
With the right compiler options, you can generate a debuggable
load module with no run-time overhead for:
LE COBOL (including Enterprise COBOL), OS/VS COBOL, and
assembler
It can be OK to copy the load module into production after
debugging without performance impact
A debuggable Enterprise PLI program can optionally be
generated with:
no run-time CPU overhead, although increased module size
For other languages, it is recommended to generate a test-only
load module for debugging, and recompile with NOTEST for
production
to remove debugging overhead or symbolics information or both
from the module
Includes COBOL II, PLI for MVS and VM, OS PLI, C / C++
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
135
135
Language compilation and usage considerations
for Debug Tool
Debug Tool requires LE run-time modules
This is an issue for older compilers, especially OS/VS COBOL
and COBOL II
When the load module is link-edited, it must pull in run-time
modules from the LE libraries
Not from the OS/VS COBOL or COBOL II libraries
When the program executes, it must use the LE run-time library
Not the OS/VS COBOL or COBOL II run-time library
Running in amode 24
If your program runs in amode 24, you may need to use LE runtime options to load LE modules below the line:
ALL31(OFF),STACK(,,BELOW)
For example:
//STEP5 EXEC PGM=SAM1,REGION=4M,
//
PARM=('/TEST(,,,VTAM%USER1:),'),
//
('ALL31(OFF),STACK(,,BELOW)')
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
136
136
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
137
137
Source mapping in Fault Analyzer
Source info makes abend analysis much easier !
With a source information file, Fault Analyzer saves you time
Fault analyzer will report:
The abending program statement
Program variable values
Without a source information file:
Fault analyzer will report:
The abending machine instruction and offset (instead of the
statement)
Storage (instead of variables)
However, you can still manually determine statements and
variables if you have a compiler listing with a map
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
138
138
Source Information Files
Fault Analyzer can read source information in these formats:
Sysdebug Compiler Langx
File
Listing
File
Compiler
LE COBOL
(incl. Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI
PL/I for MVS and VM
OS PLI
C and C++
Assembler
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
Sysadata
File
139
139
How do you Make Fault Analyzer use a
Source Info File?
During interactive reanalysis, you are automatically
prompted for source information files for each program
Just type in the file names at the prompts
and / or …
Specify a list of files in your reanalysis options
The files are automatically searched during reanalysis
You are still prompted for any programs not found
and / or …
The installer/ Systems Programmer can specify a list of
files in system-wide options
Ideal when all source info is in standard libraries
Automatic search during real-time analysis and
reanalysis
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
140
140
How do you Make Fault Analyzer use a
Source Info File?
You
Youcan
canspecify
specifyFault
FaultAnalyzer
AnalyzerOPTIONS
OPTIONSto
to
list
the
names
of
your
Source
Info
list the names of your Source Infofiles.
files. IfIfyou
you
do,
do,FA
FAcan
canautomatically
automaticallyfind
findthe
thecorrect
correct
source
sourceinfo
infofor
forany
anyprogram.
program.
Or,
Or,when
whenyou
youdo
doan
anInteractive
InteractiveReanalysis,
Reanalysis,like
likethis…
this…
Enter
The I line command starts an Interactive Reanalysis session…
© 2007 IBM Corporation
zSeries PD tools
Fault Analyzer Mentor Workshop
141
June 6, 2007
141
How do you Make Fault Analyzer use a
Source Info File?
…
…ififFA
FAdoes
doesnot
notautomatically
automaticallyfind
findthe
thecorrect
correct
source
sourceinfo
infofile,
file,this
thispanel
panelisisdisplayed
displayed...
...
Prompt for Source Information
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
Enter
142
142
How do you Make Fault Analyzer use a
Source Info File?
…
…and
andyou
youcan
canspecify
specifythe
thelocation
location
of
ofaaSource
Sourceinfo
infofile.
file. ItItmay
maybe:
be:
--aaSysdebug
Sysdebugfile,
file,or
or
--aaCompiler
CompilerListing,
Listing,or
or
--aaLangx
Langxfile,
file,or
or
--aaSysadata
Sysadatafile
file
IfIfyou
youdo
donot
notalready
alreadyhave
haveaasource
sourceinfo
infofile,
file,you
you
can
cancreate
createaaCompiler
CompilerListing
Listingnow
nowbefore
beforeyou
you
continue.
continue.
Prompt for Source Information
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
143
143
Can you create a Source Information file
after the abend occurs?
Yes, when you use Compiler Listings or Langx files
Recompile the program to create a Listing / Langx file
Fault Analyzer can use the new source information file, but
only if it determines that the map matches the module
Fault Analyzer will issue a warning message in the report,
since the time stamp will not match
To make this work:
The program source code must not have changed
do not forget copybooks and include member changes
You must use the same compiler that was originally used to
generate the module
Will this work with Sysdebug files?
No, Fault Analyzer will reject a Sysdebug file if the time
stamp does not match
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
144
144
What if my Compiler Listing is NOT in a PDS?
ItItisisbest
bestto
toupdate
updateyour
yourcompile
compileprocesses
processesto
to
automatically
store
a
Source
Info
automatically store a Source Infofile
fileininaaPDS.
PDS. IfIfyou
you
have
haveaaCompiler
CompilerListing
Listingininanother
anotherformat,
format,you
youmust
must
copy
copyititto
toaaPDS
PDSfor
forFault
FaultAnalyzer.
Analyzer.
IfIfyour
yourCompiler
CompilerListing
ListingisisininSYSOUT,
SYSOUT,here
hereisisan
aneasy
easy
way
to
copy
it
to
a
PDS
using
SDSF.
way to copy it to a PDS using SDSF.
Enter
The ? line command shows SYSOUT datasets for a job
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
145
145
What if my Compiler Listing is not in a
PDS?
Compiler
CompilerListing.
Listing.
In
InSDSF,
SDSF,use
usethe
theXDC
XDCline
linecommand
command
to
copy
your
Compiler
Listing.
to copy your Compiler Listing.
Enter
The XDC command copies SYSOUT to a data set
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
146
146
What if my Compiler Listing is not in a
PDS?
In
InSDSF,
SDSF,the
theXDC
XDCline
linecommand
command
prompts
you
for
a
file
prompts you for a filename.
name. Specify
Specifythe
the
name
nameof
ofaaPDS
PDSwith
withthe
thecorrect
correct
attributes
attributesfor
forthe
thecompiler
compilerthat
thatyou
youused.
used.
Fault
FaultAnalyzer
Analyzercan
canuse
usethe
theListing
Listingthat
that
you
youcopied
copiedto
toaaPDS
PDSmember.
member.
The XDC command copies SYSOUT to a data set
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
147
147
What if there are multiple versions of
Program Source Info?
Using FA Options, multiple data sets can be searched
Test, QA, Production, and other compiler listings, Sysdebug files,
and side files can all be searched
Fault Analyzer looks for a member name that matches
1. the program’s entry point name. If not found, then …
2. the CSECT name
If multiple versions of a Sysdebug file, compile listing, or
side file are found, FA compares:
the module size and timestamp from each file
- against the module size and timestamp in the load module
the matching version of the file is used
If a match is found, but the timestamps do not match,
then:
• The file with a timestamp nearest but later than the load module timestamp is
used (except Sysdebug)
© 2007 IBM Corporation
June 6, 2007
• A warning message is written to the Analysis Report
Fault Analyzer Mentor Workshop
zSeries PD tools
148
148
Compiling and assembling programs
for IBM PD tools
About preparing your programs for IBM PD tools
Preparing programs and saving source information:
LE COBOL (including Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI V3.5 and later
Enterprise PLI V3.4 and earlier
PLI for MVS and VM, and OS/PLI
Assembler
C and C++
How to use source information files in Debug Tool
How to use source information files in Fault Analyzer
How to use source information files in APA
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
zSeries PD tools
149
149
Source mapping in APA
Source info makes performance analysis much easier !
With the right source information files, APA can report the
program source statements that:
• used the most CPU time
• caused the most CPU time in system modules
• caused the most wait time
Without source information files, APA can report:
• program offsets that used or caused CPU and wait time
© 2007 IBM Corporation
June 6, 2007
Application Performance Analyzer for z/OS Mentor Workshop
zSeries PD tools
150
150
Enabling source program mapping
To use APA's Source Program Mapping functions, you
must save program source information
Depending on the compiler, the Source Info File may be:
•
•
•
•
a Compiler Listing
a SYSDEBUG file
CAZLANGX file
an ADATA file
Save the Source information in a PDS
• The member name must be the same as the program name
© 2007 IBM Corporation
June 6, 2007
Application Performance Analyzer for z/OS Mentor Workshop
zSeries PD tools
151
151
Source information files
APA can read source information in these formats:
Sysdebug
File
Compiler
Compiler
Listing
Langx
File
Sysadata
File
LE COBOL
(incl. Enterprise COBOL)
VS COBOL II
OS/VS COBOL
Enterprise PLI
PL/I for MVS and VM
OS PLI
C and C++
Assembler
© 2007 IBM Corporation
June 6, 2007
Application Performance Analyzer for z/OS Mentor Workshop
zSeries PD tools
152
152
A01: Source Program Mapping panel
Use
Usethis
thispanel
panelto
totell
tellAPA
APAabout
about
Source
SourceInfo
Infofiles
filesfor
forprograms.
programs.
After
Afteryou
youhave
havedefined
definedaasource
sourcefile,
file,you
youcan
canuse
use
these
theseline
linecommands:
commands:
DD
Delete
Delete
LL
Load
Loadthe
thesource
sourceinfo
infofile
file
AA
Auto-load
Auto-loadthis
thissource
sourceinfo
infofile
fileififneeded
needed
© 2007 IBM Corporation
June 6, 2007
Application Performance Analyzer for z/OS Mentor Workshop
zSeries PD tools
153
153
What if my compiler listing is NOT in a PDS?
ItItisisbest
bestto
toupdate
updateyour
yourcompile
compileprocesses
processesto
to
automatically
store
a
Source
Info
automatically store a Source Infofile
fileininaaPDS.
PDS. IfIfyou
you
have
haveaacompiler
compilerlisting
listingininanother
anotherformat,
format,you
youmust
must
copy
copyititto
toaafile
filefor
forAPA.
APA.
IfIfyour
yourcompiler
compilerlisting
listingisisininSYSOUT,
SYSOUT,here
hereisisan
aneasy
easy
way
to
copy
it
to
a
PDS
using
SDSF.
way to copy it to a PDS using SDSF.
Enter
The ? line command shows SYSOUT datasets for a job
© 2007 IBM Corporation
June 6, 2007
Application Performance Analyzer for z/OS Mentor Workshop
zSeries PD tools
154
154
What if my compiler listing is not in a PDS?
Compiler
Compilerlisting.
listing.
In
InSDSF,
SDSF,use
usethe
theXDC
XDCline
linecommand
command
to
copy
your
compiler
listing.
to copy your compiler listing.
Enter
The XDC command copies SYSOUT to a data set
© 2007 IBM Corporation
June 6, 2007
Application Performance Analyzer for z/OS Mentor Workshop
zSeries PD tools
155
155
What if my compiler listing is not in a PDS?
In
InSDSF,
SDSF,the
theXDC
XDCline
linecommand
command
prompts
you
for
a
file
prompts you for a filename.
name. Specify
Specifythe
the
name
nameof
ofaaPDS
PDSwith
withthe
thecorrect
correct
attributes
attributesfor
forthe
thecompiler
compilerthat
thatyou
youused.
used.
APA
APAcan
canuse
usethe
thelisting
listingthat
thatyou
youcopied
copied
to
toaaPDS
PDSmember.
member.
The XDC command copies SYSOUT to a data set
© 2007 IBM Corporation
June 6, 2007
Application Performance Analyzer for z/OS Mentor Workshop
zSeries PD tools
156
156
Reference
© 2007 IBM Corporation
June 6, 2007
Preparing programs for IBM PD tools
zSeries PD tools
157
157
IBM PD tools manuals and information
on the Web
http://www.ibm.com/software/awdtools/deployment/
Click
Clickon
onLibrary,
Library,or…
or…
© 2007 IBM Corporation
June 6, 2007
Fault Analyzer Mentor Workshop
…
…select
selectaaproduct
product
from
fromthe
thelist.
list.
zSeries PD tools
158
158