System definition preprocessor overview

Use the IMS system definition preprocessor to ensure that stage 1 input does not include duplicate resource names, such as transaction codes, LTERMs, and system names.

IMS provides a preprocessor that you can use to check the stage 1 input for duplicate names among the names you have defined. The preprocessor also ensures that the names are of the correct length and format. Assigned names are checked across resource types, too, so that transaction codes, LTERMs, and IMS system names (used for multiple systems coupling) do not contain duplications. The preprocessor helps maintain the integrity of the stage 1 input stream.

Figure 1. The preprocessor stage of the system definition process
The preprocessor takes IMS macro statements as input and generates a listing of input and errors as output.

The system definition preprocessor is optional.

If the IMSCTRL NAMECHK=NO option is selected for IMS system definition, run the system definition preprocessor.

Stage 1 source statements are used as input and can include copy statements. However, they cannot include inline copies of IMS macros from the stage 1 input, inline user macros, user macro calls, or conditional assembler statements.

The preprocessor locates, reads, and processes copy statements by using the copy members as input. The order of search, which conforms to z/OS® standards, depends upon the order in which you have concatenated the libraries. Copy members are retrieved from the data sets specified by SYSLIB DD statements. The preprocessor scans the input for the following IMS macros:

The preprocessor does not recognize keywords that are split across continuation statements. The related parameters associated with these keywords generate error messages from the preprocessor.

After scanning for macros, the preprocessor builds resource name tables for each resource name type. It then performs the following verification steps:
  • Within each resource type, the preprocessor verifies that no resources of that type have duplicate names. The following types of resource names are verified:
    • DBD names
    • PSB names
    • VTAM® node names
    • MS link names
    • Logical terminal names
    • Transaction codes
    • Routing codes
    • Subpool names
    • MSLINK partner IDs
    • MSPLINK physical link names
    • Remote system VTAM node names
  • These resource names are checked to ensure that they are of the appropriate length and are alphanumeric.
  • The names specified for transactions, logical terminals, and multiple systems are cross-checked to ensure that no duplicate names exist across these three resource types.
Also see the following sections of this overview of the systems definition preprocessor:

Estimating storage requirements for the preprocessor

The preprocessor uses the default values to reserve an initial amount of storage for each resource name table (RNT). If this storage is insufficient, the preprocessor dynamically expands the table until all extended private storage is exhausted. Resource names not added to the appropriate RNT are ignored and excluded from further processing.

Additional space is required if the number of errors for any given resource name exceeds 50, or if the number of nested copy statements exceeds 50. For most cases, this additional storage is accounted for in the base system storage number.

The storage size is the minimum region size that can be specified on preprocessor invocation JCL.

The preprocessor also requires 1 MB of private storage below the 16 MB line.

Standard system definition:

The storage estimate is for extended private storage. The storage requirement is the sum of:
  1. 1000 KB for the base system.
  2. Space needed for exit routines DFSPRE60 and DFSPRE70, if they are loaded.
  3. Table space in excess of the default. For each of the following resource types that exceeds 5120, determine the amount of storage from Table 1.
    • APPLCTN
    • DATABASE
    • NAME
    • RTCODE
    • SUBPOOL
    • TERMINAL (VTAM)
    • TRANSACT
Table 1. Resource name table storage
Resource range Storage amount in K bytes
5120 to 10,240   80
10,240 to 20,480   240
20,480 to 41,060   560
41,060 to 82,120   1200
82,120 to 164,240   2480
164,240 to 328,480   5040
328,480 to 656,960   10,160
656,960 to 1,313,920   20,400

Preprocessor exit routines

You can develop exit routines that gain control during the execution of the preprocessor. You can use one or both of the following exit routines:
  • Exit DFSPRE60

    This routine gains control after each record in the stage 1 input is read, but before any other processing takes place. It can modify the contents of the record and can even submit further statements to the preprocessor for checking. Any changes made by this routine are not permanent, nor are these changes automatically passed to stage 1.

  • Exit DFSPRE70

    This routine gains control when all cross-checking has been completed. It has access to all the tables of resource names. The routine can then format these tables as part of a documentation effort.

Sample JCL to execute the preprocessor

To execute the preprocessor, you must provide JCL as shown in the following example. 
//         JOB
//         EXEC PGM=DFSPRE00,REGION=32M,PARM='xxx' 1
//STEPLIB  DD   DSN=IMS.SDFSRESL,DISP=SHR 2
//         DD   DSN=USER.EXITLIB,DISP=SHR 3
//SYSLIB   DD   DSN=USER.MACLIB,DISP=SHR 4
//         DD   DSN=IMS.SDFSMAC,DISP=SHR 4
//SYSPRINT DD   SYSOUT=A
//SYSIN    DD   * 5
Notes:
  1. The region size indicated is the size required to execute the preprocessor on a z/OS system. Guidelines for determining the region sizes are in Estimating storage requirements for the preprocessor.

    The PARM field is specified only if the default exit routine indicators should be overridden.

  2. This DD statement should specify the library containing the preprocessor version that you want to execute. Different versions can exist because of SMP maintenance.
  3. This concatenated DD statement is required only if exit routines are requested.
  4. The SYSLIB DD statement should point to a library that contains the copy members. This DD statement is required if stage 1 source COPY statements exist.
  5. You can also use the statement:
    //SYSIN DD  DSN=....,DISP=SHR

The PARM field on the EXEC statement is specified as follows:PARM='a,b'

The parameters specified are positional and are specified as follows:
a
Indicates whether (Y) or not (N) exit routine DFSPRE60 is to be used during this invocation of the preprocessor. If DFSPRE60 is to be used, it must reside on the libraries pointed to by the STEPLIB DD statement. The default is N.
b
Indicates whether (Y) or not (N) exit routine DFSPRE70 is to be used during this invocation of the preprocessor. If DFSPRE70 is to be used, it must reside on the libraries pointed to by the STEPLIB DD statement. The default is N.