Analyzing the programs by using the CICS load module scanner

If you do not have CICS® Interdependency Analyzer, you can use the CICS-supplied batch utility DFHEISUP, the load module scanner, to perform basic analysis. The load module scanner can identify programs in the application containing EXEC CICS commands that are never threadsafe or not always threadsafe, and it can identify programs containing application logic that accesses shared resources and therefore might not be threadsafe.

1. In TSO, locate the sample job DFHEILMS, which is in the CICS-supplied SDFHSAMP library, and copy the file into one of your own libraries so that you can edit it.
2. Referring to the instructions in Creating a summary report using the load module scanner, edit the statements in the job to request a summary report.
   On this run, we will use the CICS-supplied filter file DFHEIDTH to produce a list of modules in the load library that contain CICS commands that give access to shared storage.
   Although some of these commands are themselves threadsafe, they all give access to global storage areas, so the program logic (that is, the native language code) that follows these commands and uses the global storage areas must be checked to see whether it is threadsafe.
   To produce a summary report, you need to make the following changes in the JCL:
   1. Verify that the PARM statement specifies SUMMARY,DETAILMODS.
   2. Change the high level qualifier in the STEPLIB statement to point to the CICS-supplied DFHLOAD library where DFHEISUP is installed.
   3. Change the DFHFLTR statement to point to the DFHEIDTH filter file, which is in the CICS-supplied SDFHSAMP library.
   4. Change the DFHDTL statement to specify the name of a sequential data set that the load module scanner can create to hold the list of identified modules.
   5. Change the DFHIN statement to specify the name of the load library that contains the application programs that you want to scan.
3. Save your edited JCL, and submit the job to send the summary report to your SYSOUT destination.
4. View the summary report to see the programs that were identified by the load module scanner.
   The report lists the programs and the number of commands from the filter file that they each contain.
   Any programs in the load library that were not identified by the load module scanner do not access shared storage, and are therefore threadsafe.
5. Make a copy of the job you produced in Step 2. Referring to the instructions in Creating a detailed report using the load module scanner, edit the statements in the job to request a detailed report.
   On this run, we will apply the CICS-supplied filter file DFHEIDTH to the programs that were identified in the summary report, to produce a detailed report of the commands in each program that access shared storage.
   You need to make the following changes in the JCL:
   1. Change the PARM statement to specify DETAIL.
   2. Use the DFHLIST statement to specify the name of the sequential data set containing the list of modules that was created by the summary scan.
   Leave the STEPLIB, DFHFLTR, and DFHIN statements as they were for the summary report.
6. Save your edited JCL, and run the job to send the detailed report to your SYSOUT destination.
7. View the detailed report to see the CICS commands in each program that access shared storage.
   For each command, check that the program includes synchronization logic to guard against concurrent update of the shared storage.
   For more information about appropriate threadsafe processing techniques for accessing shared resources, see Making applications threadsafe.
   If the program does access shared resources correctly, its program logic is threadsafe.
8. You can now put together a list of the application programs that have threadsafe program logic, which are as follows:
   • Any programs in the load library that were not listed by the load module scanner in the original summary report using the DFHEIDTH filter file. These programs do not access shared storage, and are therefore threadsafe.
   • Any programs that you analyzed using the information from the detailed report, and for which you established that the program uses appropriate serialization techniques when handling shared storage.
   Programs that have threadsafe logic can be defined to CICS as threadsafe. However, you should first check whether the programs contain any EXEC CICS commands that are not threadsafe. Programs can be defined to CICS as threadsafe when they have threadsafe program logic but contain EXEC CICS commands that are not threadsafe, because CICS switches back from the open TCB to the QR TCB when necessary to ensure that the commands are processed safely. However, TCB switching can affect the performance of the application. For optimal performance, only define programs as threadsafe when they have threadsafe program logic and use only threadsafe CICS commands.
9. Make a copy of the job you produced in Step 2 to create a summary report.
   On this run, we will use the CICS-supplied filter file DFHEIDNT to produce a list of modules in the load library that contain EXEC CICS commands that are never threadsafe or not always threadsafe.
   Make the following changes in the JCL:
   1. Change the DFHFLTR statement to point to the DFHEIDNT filter file, which is in the CICS-supplied SDFHSAMP library.
   2. Change the DFHDTL statement to specify the name of a different sequential data set that the load module scanner can create to hold the new list of identified modules.
10. Save your edited JCL, and submit the job to send the summary report to your SYSOUT destination.
11. View the summary report to see the programs that were identified by the load module scanner.
    The report lists the programs and the number of commands from the filter file that they each contain.
    Any programs in the load library that were not identified by the load module scanner contain only threadsafe EXEC CICS commands.
    Note: The DFHEIDNT filter file includes the EXEC CICS commands that are not threadsafe under any circumstances, but also the EXEC CICS commands that are threadsafe in some situations and not in others. For example, the load module scanner has identified any programs that contain the EXEC CICS READ command. This command is threadsafe when it refers to a local file, or a file accessed by function shipping over an IPIC connection. However, the command is not threadsafe for files accessed over other types of connection. You can now use the load module scanner to produce a detailed report to see exactly what commands are in which program, and enable you to check whether or not the commands are threadsafe in the context of the application.
12. Optional: To carry out a more targeted analysis, you can create your own filter file of commands for the load module scanner, and specify it instead of the DFHEIDNT filter file.
    For example, you could create a list of commands that have been made threadsafe since the CICS release from which you last upgraded, and run a summary scan to specifically identify programs with these commands. This scan would identify programs containing commands that would in the past have caused TCB switching from the open TCB to the QR TCB, but are now threadsafe so do not cause TCB switching. The CICS Upgrading documentation lists the CICS API and SPI commands that have been made threadsafe since the CICS release from which you last upgraded.
    The CICS-supplied filter file DFHEIDAL contains the filter set for all possible commands, and you can edit this file to include only the commands you want.
    If you want to try this, follow the instructions in Creating a filter input file for the load module scanner.
13. Make a copy of the job you produced in Step 5 to create a detailed report.
    On this run, we will apply the CICS-supplied filter file DFHEIDNT, or your own filter file, to the programs that were identified in the summary report, to produce a detailed report of the commands in each program that need further investigation.
    Make the following changes in the JCL:
    1. Change the DFHFLTR statement to point to the DFHEIDNT filter file or your own filter file.
    2. Change the DFHLIST statement to specify the name of the sequential data set containing the list of modules that was created by the summary scan using DFHEIDNT or your filter file.
14. Save your edited JCL, and run the job to send the detailed report to your SYSOUT destination.
15. View the detailed report to see the EXEC CICS commands that were identified in each scanned program, with some of the parameters from the command.
    You can use this information to analyze the programs to see whether the commands are threadsafe in the context of the application.
    To check the exact circumstances in which each EXEC CICS command is and is not threadsafe, see Threadsafe commands.
16. You can now put together a list of the application programs that contain only threadsafe EXEC CICS commands, which are as follows:
    • Any programs in the load library that were not listed by the load module scanner in the original summary report using the DFHEIDNT filter file or your own filter file.
    • Any programs that you analyzed using the information from the detailed report, and for which you established that the identified commands were threadsafe in the context of the application.
    You can compare this list to your list of application programs that have threadsafe program logic.