Good Afternoon 👋

I wanted to take this opportunity today to share details about a COBOL runtime feature which was initially released with IBM Enterprise COBOL for z/OS 6.4 and then recently updated through APAR PH61133 in June 2024 COBOL runtime PTF. You can read more about this APAR by clicking here. With IBM Enterprise COBOL for z/OS 6.4, the COBOL program report feature aims to enhance debugging and reporting capabilities of COBOL programs compiled with Enterprise COBOL 5 and later releases.

Feature Overview:
The IGZPROUT ddname allows users to generate a report of COBOL programs compiled with Enterprise COBOL 5 or later. This program report provides detailed information on all active and cancelled programs at termination to help programmers debug using program attributes and SERVICE string information. For instance, if a COBOL subprogram with a JSON PARSE statement is unexpectedly ABENDing, the programmer can use this report to quickly determine if the subprogram was compiled with the correct compiler version that supports JSON, rather than manually analyzing and debugging the JCL or COBOL caller or callee codes. Additionally, this report can provide efficient administration and compliance verification of a large number of COBOL programs. It serves as a centralized solution, enabling COBOL programmers to ensure that all programs are consistently compiled with a specific version or release, in line with team or company policies. For instance, if a company upgrades from Enterprise COBOL 6.3 to Enterprise COBOL 6.4 and requires all programs to be compiled with Enterprise COBOL 6.4, this report helps programmers verify compliance effortlessly.

What's in the Report:

1. Program Details: The report includes the ID, Program Name, Compiler Version, Compilation Time and Date, and SERVICE information for each COBOL program.

2. Programs called Dynamically, Statically and via DLL: These are listed under the COBOL ACTIVE PROGRAMS heading if they are active at program termination.

3. Cancelled Programs: Dynamically called programs that have been cancelled are listed under the CANCELLED PROGRAMS heading.

4. Main Program Identifier: Each main program, which calls other subprograms is marked by printing 'M' preceding the unique 6-digit ID. This makes it easy to parse or spot the main program on the report.

5. Long Program Names and Service Strings: If a program name or service string is too long, an asterisk (*) will precede it in the main section of the report. The full program name or service string will be printed separately in the report with their corresponding IDs.

What's NOT in the Report:

1. 64-bit COBOL programs: Programs compiled with LP(64) are not included in the report.

2. Load libraries: Details about relevant load libraries are not included in the report

3. Non-COBOL Programs: Any non-COBOL caller or callee programs are not included in the report.

4. Programs compiled with Enterprise COBOL 4 and earlier: Programs compiled with IBM Enterprise COBOL for z/OS 4.2 and earlier are not included in the report.

Key Points to Remember:

1. Initial Release with Enterprise COBOL 6.4: This feature was first released with Enterprise COBOL 6.4. Initially, the report had a different layout and included only dynamically called programs compiled with Enterprise COBOL 5 or later releases, without SERVICE string information. The latest version, released with APAR 61133, retains the attributes of the previous version while introducing a new layout, SERVICE string information, long program name and service string support, and details about programs called statically and via DLL linkage.

2. Update with APAR PH61133: To make full use of this feature's functionality, make sure the COBOL runtime PTF for APAR PH61133 is installed on your system.

3. Main Program Exclusion: If the main program is written in a non-COBOL language like C or assembly, the identifier 'M' will not appear in the report since non-COBOL programs are not included.

4. Service String Length: The maximum length of a service string is 64 characters. For additional details, check out the IBM documentation here.

5. Program Name Length:

1. Static and DLL Programs: The maximum length of a program name can be up to 160 characters depending on the compiler option used. If a program name is 160 characters long, 70 characters will be printed on one line and will wrap onto the next line until the full name is printed. For more details, refer to the IBM documentation on the PROGRAM-ID paragraph here.

2. Dynamic Programs: Dynamic program names can be a maximum of 8 characters.

Here is an example of a sample program report output:

Understanding the sample program report output:

1. The report has four sections: "COBOL ACTIVE PROGRAMS," "CANCELLED PROGRAMS," "LONG PROGRAM NAME LIST," and "LONG SERVICE STRING LIST." The "COBOL ACTIVE PROGRAMS" section is always printed by default. The other three sections are printed only if specific conditions are met. These conditions are discussed in bullet points 5, 6, 8, and 9.

2. Each program is assigned a unique ID to help reference specific programs through the report. In this example, PROG1 is assigned ID of 000001.

3. The character 'M' appended before ID value 000006 of PROG8 identifies the main program. PROG8 is the caller program that calls other COBOL programs either dynamically, statically or via DLL linkage.

4. The total number of programs can be tallied by identifying the largest ID value, this can be either the last program in the "COBOL ACTIVE PROGRAM" section or "CANCELLED PROGRAMS" section depending on if there are cancelled programs or not.

5. The "CANCELLED PROGRAMS" section lists information for all programs that were dynamically called and then cancelled using the CANCEL statement. You can read more about the CANCEL statement here.

6. IBM uses a "VRM" naming convention to refer to compiler release information, where:

1. 'V' stands for the compiler version.

2. 'R' stands for the compiler release.

3. 'M' stands for the compiler modification.

7. The report output, the version is represented by a 6-digit code:

1. Digits 1 and 2 identify the compiler version.

2. Digits 3 and 4 identify the compiler release.

3. Digits 5 and 6 identify the compiler modification.

8. In the example, the main program, PROG8 is compiled with IBM Enterprise COBOL for z/OS 6.2 on March 20th, 2024.

9. The "NAME" column prints the COBOL PROGRAM-ID and can display up to 8 characters in the "COBOL ACTIVE PROGRAM" section. If the program name exceeds 8 characters, an asterisk (*) appears before the name, indicating it is a long name. The full program name is listed separately in the "LONG PROGRAM NAME LIST" section with its corresponding ID. For example, program ID 000004 has a name longer than 8 characters. The first 8 characters, "PROG4LON," are shown with an asterisk, and the full name is printed in the "LONG PROGRAM NAME LIST" section.

10. In the "LONG PROGRAM NAME LIST" section, program names are printed with a maximum of 70 characters per line before wrapping to the next line. For example, program ID 000005 has a name with 160 characters. The first 70 characters are printed on the first two lines, and the remaining 20 characters on the third line. There is no special character indicating the name wrapping to the next line.

11. The "SERVICE" column displays the SERVICE string associated with each program and can show up to 10 characters in the "COBOL ACTIVE PROGRAM" or "CANCELLED PROGRAMS" section. If the string exceeds 10 characters, an asterisk (*) appears before it, indicating a long SERVICE string. The full SERVICE string is listed separately in the "LONG SERVICE STRING LIST SECTION" with its corresponding ID. For example, program ID 000008, named PROG8, was cancelled at termination. Since its SERVICE string was longer than 10 characters, the first 10 characters are printed in the "CANCELLED PROGRAMS" section, and the full string is printed in the "LONG SERVICE STRING LIST" section.

This feature boosts the user's ability to debug and manage COBOL programs. You can get the latest version of the report by installing the IBM Enterprise COBOL Runtime May 2024 PTF's V2R4: UI96917 / V2R5: UI96918 / V3R1: UI96919 through IBM Shopz. To access IBM Shopz, please follow the instructions provided here.

If you have any questions or would like to share your experiences using this program report, please join the discussion! 🙂

------------------------------
Suhaib Saleem
------------------------------