Application Delivery Foundation for z/OS

You can use Application Delivery Foundation for z/OS® (ADFz) on ABO generated modules.

Find out more about Application Delivery Foundation for z/OS at https://www.ibm.com//products/app-delivery-foundation-for-zos.

The following Application Delivery Foundation for z/OS family of problem determination tools can be used on ABO generated COBOL modules:

Developer for z/OS Enterprise Edition, which includes IBM® Debug for z/OS
Fault Analyzer for z/OS (FA)
Application Performance Analyzer for z/OS (APA)

Creating a LANGX side file

For ABO optimized programs originally compiled with COBOL 4 and earlier releases, you need to produce a LANGX side file for each optimized program to use with the ADFz tools. IBM Debug for z/OS, FA, and APA use the LANGX side file to provide a better experience for users. For example, source-level debugging is provided with Debug for z/OS when a LANGX side file is provided. Without this LANGX side file, source-level debugging is not possible.

IPVLANGO is a tool provided with IBM Problem Determination Tools Common Component for z/OS V1.7, which is shared by the Application Delivery Foundation for z/OS tools. IPVLANGO combines the SYSDEBUG data set or compiler listing or the LANGX side file of the original compiled program along with the ABO listing transform to produce a new LANGX side file appropriate for the ABO generated module. Use the new LANGX file when you use DT, FA, or APA on the ABO generated module.

Producing DWARF diagnostic information

For modules compiled with COBOL 5 and later releases, the LANGX side file is not necessary. Instead, for modules that were compiled with TEST or with NOTEST(DWARF), ABO will itself produce the updated DWARF diagnostic information for the optimized module either within the module itself (NOSEPARATE) or within a separate side file (SEPARATE).

For TEST(NOSEPARATE), no further configuration of ABO is required. When ABO optimizes the module, it will also update the DWARF information within the optimized module to be applicable to that module.

For TEST(SEPARATE), the OPTDEBUG DD is specified to determine where the updated DWARF side files will be written.

Under DSNAME, this is the only requirement. The original COBOL DWARF will be read from the original side file using the dataset name that was stored into original COBOL module at compilation (but see below for an alternative location), Table 1 shows how the updated DWARF side file name is determined. Specify the updated DWARF side file name as shown below:

//OPT EXEC PGM=BOZOPT,REGION=0M
...
//OPTDEBUG DD DSN=updated-dwarf-library,DISP=SHR

Under NODSNAME (or under DSNAME when the original COBOL DWARF is to be read from another location), the additional DD statement, SYSDEBUG DD, is specified for the location storing the original COBOL DWARF. The updated DWARF will be written as given in Table 2. This emulates behaviour under the sample user exit IGZIUXB/IGZIUXC. If the user has used their own custom user exit at COBOL runtime, then the user will need to adapt this exit to relocate the DWARF input file to a file location that will be accepted under Table 2. Specify the original and updated DWARF side file names as shown below:

//OPT EXEC PGM=BOZOPT,REGION=0M
...
//OPTDEBUG DD DSN=updated-dwarf-library,DISP=SHR
//SYSDEBUG DD DSN=original-dwarf-library,DISP=SHR

Under the above options, the optimized module will appear to have been compiled with the TEST options of the original module. However, if for any reason ABO determines that it cannot generate valid DWARF the optimized module will still be generated, but it will appear to have been compiled with NOTEST(NODWARF). In this case one or more warning (return code 4) messages will issued and the updated DWARF information will not be generated. Note that under TEST(NOSEPARATE) the original DWARF will remain in the optimized module but will not be used by the ADFz tools.

Under TEST(SEPARATE) it is possible if required to bypass the generation of updated DWARF; if the OPTDEBUG DD is not specified, then ABO will behave as though it cannot generate valid DWARF, but in this case, no warning messages are shown, and normal optimization will proceed at return code 0.

Table 1. Determination of Updated Side File Name under TEST(SEPARATE(DSNAME))
Input DWARF Type	Output DWARF (OPTDEBUG DD)	Output DWARF Type (OPTDEBUG DD)
Sequential Dataset	DD:OPTDEBUG(`csect`¹).	PDS or PDSE directory
PDS or PDSE member	DD:OPTDEBUG(`member`) where `member` is the member of the input DWARF.
HFS file	DD:OPTDEBUG(`csect`¹).

Table 2. Determination of Updated Side File Name when SYSDEBUG is specified. ²
Input DWARF Type of SYSDEBUG DD	Valid or not	Input DWARF (SYSDEBUG DD)	Output DWARF (OPTDEBUG DD)	Output DWARF Type (OPTDEBUG DD)
Sequential Dataset	Not valid	N/A	N/A	N/A
PDS or PDSE directory	Valid	DD:SYSDEBUG(`name`³)	DD:OPTDEBUG(`name`³)	PDS or PDSE directory
HFS	Not valid	N/A	N/A	N/A

Notes:

csect is the csect name. When csect is used as the member of a PDS or PDSE directory, then it is upper cased and truncated to 8 characters, as per the SYSPRINT DD or LIST options.
This emulates behaviour under the sample user exit IGZIUXB/IGZIUXC.
name is:
- csect if debugFileName is empty;
- the member name of debugFileName if debugFileName is a PDS or PDSE member;
- invalid otherwise
where debugFileName is empty under NODSNAME or it is the the dataset name that was stored into original module under DSNAME.

For logical record length and block size of datasets in OPTDEBUG and SYSDEBUG other than HFS files, see Logical record length and block size in the Enterprise COBOL for z/OS Programming Guide.