Introduction to source program mapping
- The common data set list
- If the Common Data Store (CDS) is enabled during installation of Application Performance Analyzer, users have the ability to create and maintain a common list of source information data sets (for languages other than Java) that is unique to each instance of Application Performance Analyzer. The common data set list is shareable by all users of the Application Performance Analyzer instance. It is accessed from the ‘A05: Source Mapping Common List’ panel. All users may view the common list and authorized users may update the common list. When Application Performance Analyzer is searching for program source, it will search the user’s personal list as defined in the ‘A04: Source Mapping Dataset List’ panel first, and if not found, then search the common list.
- For languages other than Java
- When you specify source program mapping files, many reports allow you to enter a “P” line command to view the program source associated with that entry in the report. The “P” line command is available on many object types: CSECTs, DB2® SQL statements, CICS® commands, etc. The data is displayed in the P01: Source Program Attribution report. This report can also be included in a print request.
- The ‘P’ line command
- When you enter the ‘P’ line command, Application Performance Analyzer first
checks if the source is loaded. If it is, the source is displayed
in the P01: Source Program Attribution report.
If the source is not loaded, your A04: Source Mapping Dataset List is searched for the source member. If no source member is found in any of the data sets, the common list as defined in A05: Source Mapping Common List is searched. If no source member is found in any of the data sets in the list, the A01: Source Program Mapping panel is displayed, allowing you to enter the source mapping information for the current observation session.
When one or more source members are found in your A04: Source Mapping Dataset List or the A05: Source Mapping Common List, the behavior of Application Performance Analyzer depends on whether or not you requested to match the compile date and time. When you request to not match the compile date and time, the first instance of a source member is loaded regardless of its date and time and the source is displayed in the P01: Source Program Attribution report.
When you request to match the compile date and time, the first source member found that matches the load module compile date and time is loaded and the source is displayed in the P01: Source Program Attribution report.
If none of the source members match the compile date and time, a pick list of datasets that contain the source member is displayed in the A011: Source Programming Mapping Pick List panel. When you select one of these source members, it is loaded and you are returned to the report from which you entered the ‘P’ line command. You must then re-enter the ‘P’ line command to display in the P01: Source Program Attribution report.
- The ‘P’ line command for COBOL with DWARF
- When a COBOL program is compiled with the TEST option, the DWARF
debugging information (which includes the source) is embedded in the
load module. When you enter the ‘P’ line command against
such a program, Application Performance Analyzer recognizes
that the DWARF debugging information is available in the load module,
and loads the source directly from that load module. The source is
displayed in the P01: Source Program Attribution report.
This feature requires READ access to the dataset in which the corresponding load module resides. The Common Data Store is not used for COBOL with DWARF, nor is the A01 Source Program Mapping panel. As an alternative to DWARF, the COBOL compile listing may be used for source mapping in the usual manner.
This feature requires access to the TZ environment variable. The CONFIG BASIC TZ setting must be configured with appropriate values during the installation of Application Performance Analyzer. Contact your system programmer to verify the TZ environment variable is configured in Application Performance Analyzer.
- The ‘P’ line command for C/C++ (without timestamp match)
- When you enter the ‘P’ line command, Application Performance Analyzer first
checks if the source is loaded. If it is, the source is displayed
in the P01: Source Program Attribution report.
Typically, source mapping for C/C++ programs is dependent on an exact match between the listing timestamp and the CSECT timestamp generated at compile time. A recompiled C/C++ source listing cannot be loaded directly from the A01, A04 or A11 panels. In some cases, this function is required when the source listing that matches the compiled program is not available. To accommodate this situation, Application Performance Analyzer will allow a listing to be loaded for a specific CSECT with no timestamp matching. You must enter the ‘P’ line command on a CSECT in one of the supporting reports. You are then directed to the A01: Source Program Mapping panel where you specify the listing to be loaded. This listing will then be loaded and related to the CSECT selected, without timestamp checking, and you are returned to the report. You must then re-enter the ‘P’ line command to display the P01: Source Program Attribution report.
- For Java
- When you specify source program mapping files for Java, the program source is viewed in the detail windows in the Java reports, rather than by using the “P” line command. The detail window from a Java Line Number contains Java source mapping information. This detail window is displayed by entering the “++” command (or the Enter key) on the Java Line Number.
- Using DWARF debug files
- If C/C++ programs are compiled with DWARF,
you can source map the programs by using DWARF debug files. To
source map, you need to specify the "P" line command on a CSECT object
in the various CPU reports. This displays the P04: DWARF Source
Lines report. In the P04 report, you can use the "P" line command
again on a source line object in order to display the P03: DWARF Source Program Attribution report.
You can also go directly to the P03 DWARF Source Program Attribution report (without going through the P04 report), by using the “P” line command on an object code address report line in the C03 report, or an attribution offset line in the W03 report.
The debug file is located within the CSECT for the compiled program. Application Performance Analyzer can extract the debug file name from the executable program during sampling. Therefore, you do not need to identify the debug file via the A01 panel for source mapping. However, Application Performance Analyzer can only extract information from an executable USS file if Application Performance Analyzer can locate the file during sampling. If the USS program is executed by using a relative path name, you must specify the directory in which the executable program can be found. You specify the directory in the Options panel (panel 2) when you create the request.