Load module scanner (DFHEISUP)

The load module scanner utility can scan load libraries for the CICS® commands in load modules, and identify which modules contain specific API or SPI commands.

For example, if you know that a particular API or SPI command must be changed to take advantage of a new feature in CICS, you can use the load module scanner to identify all the load modules that contain the command. The load module scanner can look for specific commands, or options on commands, or combinations of options. It can also scan for commands where certain options are not specified.

The load module scanner is a batch utility. It locates all the EXEC CICS commands in your load modules, and then applies a filter that you create, to identify only the commands in which you are interested. It returns one of two types of report:
  • A summary report, giving a list of the modules that contain the commands that are specified by your filter, and the number of specified commands in each module.
  • A detailed report, with a list for each module to show which of the specified commands it contains, at which offsets, including EDF information if available.
Both types of report identify the language of each load module.

CICS supplies a sample job, DFHEILMS in SDFHSAMP, that you can edit and use to execute the load module scanner. On any run of the load module scanner, you can scan all the load modules in a load library (if you specify a complete PDS), or you can specify certain load modules within the library to scan. A useful technique is to run a summary scan for a particular load library to produce a list of the modules that contain the commands in which you are interested. You can place this list of modules into a data set. You can then run a detailed scan, using this data set as input, to produce a detailed report on only the modules that contain the commands in which you are interested.

You specify the commands to be reported upon as a filter input file. You can name the commands in which you are interested. You can also include or exclude commands that have certain parameters. The 'any' operator can be used to search for all parameters, or for all commands. A number of sample command lists are provided to help you. Use DFHEIDBR to search for commands that are not supported in the 3270 bridge environment. Use DFHEIDTH to search for commands that give access to shared storage, which could make a program not threadsafe. Use DFHEIDAL to search for all the basic valid commands, and use DFHEIDNT to find all non-threadsafe CICS commands (which would cause a switch to the QR TCB).

Points to bear in mind when you use the load module scanner

  • When you use the load module scanner, as with all types of scanners, it is not possible to guarantee that a hit is genuine. There might be a few false hits, because of static data in a module. The reports identify candidates that match a set of criteria (the commands and options that are specified in your filter), and the candidates that are identified might not be an exact match to your requirements.
  • The load module scanner is designed to scan up to about 100 load modules on a single run. The sample job, DFHEILMS in SDFHSAMP, specifies a region size of 512M, which is appropriate for this amount of scanning. If you need to scan more load modules on a single run, you can increase the region size. However, do not specify REGION=0M on the job to run the load module scanner, as this can lead to performance problems. If you have many load modules in a load library that you want to scan, you might prefer to copy smaller batches of the load modules into new load libraries, and scan the new load libraries.
  • To ensure sufficient storage below the 16MB line, specify the Language Environment® run time option ALL31(ON). ALL31(ON) is the default Language Environment run time option for CICS.
  • The PL/I compiler V3.6 changed the default compiler option CEESTART from CEESTART(FIRST) to CEESTART(LAST). For CEESTART(LAST), an ENTRY CEESTART card must be included when linking the MAIN routine as described in the PL/I compiler documentation. The ENTRY CEESTART card is used by DFHEISUP to find API or SPI commands. Alternatively, you can specify CEESTART(FIRST) explicitly.

Figure 1 shows how the scanner works.

Figure 1. Load module scanner with filter
The load module scanner looks at the modules that are identified in the list of modules you provided. It produces a list of all the EXEC CICS commands in the modules. Next, it looks at the filter input file you provided, which contains a list of the commands in which you are interested. It applies this filter to the list it produced, to create a filtered list of the EXEC CICS commands of interest in the modules. Finally, it produces a report showing each module that contains one or more of the commands in which you are interested, and listing the commands of interest in each of those modules.