This section refers to DFHCSDUP as a batch program. It describes the DFHCSDUP EXTRACT command, and the three sample programs that can be invoked during EXTRACT processing.
The DFHCSDUP LIST command produces reports about the current status of the CSD file that vary only according to the input parameters you provide. Another DFHCSDUP command, EXTRACT, causes the CSD data you select to be passed unformatted to a user program. The user program can then create reports of the CSD data that meet local requirements. For example, you could cross-refer related definitions (such as TERMINALs and TYPETERMs), or you could sort the data by attribute values, such as security keys or processing priorities. The user program could also write the requested resource attributes to a data set to be used as input to a database product, such as SQL, DB2®, or the Data Extract program product.
The user progrm must be linked RMODE(24). It receives control in 24-bit primary-space translation mode. (For information about translation modes, see the IBM® ESA/370 Principles of Operation manual.) The contents of the access registers are unpredictable. The program must return control in 24-bit primary-space translation mode, and it must restore any access registers that it modifies (in addition to restoring the general purpose registers).
There are three sample programs that can be invoked from DFHCSDUP during EXTRACT processing. The sample programs, and how to replace them with your own versions, are described in topic The sample EXTRACT programs.
The EXTRACT command takes requested data from the CSD and passes it to a user program for processing. The command has the following format:
EXTRACT {GROUP(name)|LIST(name)} USERPROGRAM(name) [OBJECTS]
The user program can be invoked at nine different points during the processing of the EXTRACT command by DFHCSDUP. However, your program is invoked at all of these points only if you specify both LIST and OBJECTS on the EXTRACT command. The invocation points are as follows:
On every invocation of the user program, DFHCSDUP passes a parameter list addressed by general register 1. The parameter list consists of a series of fullwords that address the fields described in more detail below. The addresses set in the parameter list vary, depending on the point that EXTRACT processing has reached.
The parameter list contains the following fields:
The function codes are as follows:
There are three CICS-supplied sample programs that can be invoked during DFHCSDUP EXTRACT processing. Two of these are provided in COBOL, PL/I, and assembler language, and the third is provided in COBOL only. They are outlined in Table 47.
Program names | Languages | Description |
---|---|---|
DFH$CRFA
DFH0CRFC DFH$CRFP |
Assembler
COBOL PL/I |
Produces a cross-reference listing of the resource definitions defined in the group or list you specify on the EXTRACT command. |
DFH$FORA
DFH0FORC DFH$FORP |
Assembler
COBOL PL/I |
Formats the group or list of resource definitions you specify on the EXTRACT command into a form suitable for the DB2 table load utility. |
DFH0CBDC | COBOL | Writes the list or group of resource definitions you specify on the EXTRACT command in the form of DEFINE commands, suitable for use as a backup copy of the resources extracted. |
You can use the sample programs as supplied, or as models on which to base your own programs.
The assembler-language and COBOL versions of the CSD cross-referencing program, DFH$CRFA and DFH0CRFC respectively, are supplied in executable form in CICSTS31.CICS.SDFHLOAD. The PL/I version, DFH$CRFP, is supplied in source form only.
The assembler-language and COBOL versions of the DB2 formatting program, DFH$FORA and DFH0FORC respectively, are supplied in executable form in CICSTS31.CICS.SDFHLOAD. The PL/I version, DFH$FORP, is supplied in source form only.
The CSD backup utility program, DFH0CBDC, is supplied in executable form in CICSTS31.CICS.SDFHLOAD.
The source statements of all versions of all the sample programs are supplied in CICSTS31.CICS.SDFHSAMP.
The CICS-supplied sample DB2 formatting programs (DFH$FORx) cannot be used when the CSD compatibility option (COMPAT) is specified on the DFHCSDUP utility program. The output from the CSD cross-reference listing and CSD backup utility programs depends on whether the compatibility option is specified. If the compatibility option is specified, the output includes obsolete keywords from releases before CICS® Transaction Server for z/OS®, Version 3 Release 1; if the option is not specified, only keywords from CICS Transaction Server for z/OS, Version 3 Release 1 are output. For further information about running the DFHCSDUP utility program with the compatibility option, see the the CICS Resource Definition Guide.
Note that the sample programs require you to specify the OBJECTS keyword on the DFHCSDUP EXTRACT command.
The output data definition names (ddnames) for the sample programs are as follows:
The sample programs are discussed in the next three sections.
The CICS-supplied sample CSD cross-referencing program produces a cross-reference listing of objects and keywords on the CSD. The data gathered by the EXTRACT command is passed to the sample program, where it is saved in a cross-reference table. On the final call to this sample program, the contents of the table are printed in collating sequence.
The program must be run against an EXTRACT command of the form:
EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name)
or:
EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name)
Note that the sample program requires you to specify the OBJECTS keyword.
For this program only, in addition to the EXTRACT command, you must define, in a sequential data set, the objects and keywords for which you want a cross-reference listing. The data set is read by the sample program using the ddname CRFINPT.
CRFINPT is a sequential file containing 80-byte records. Each record contains one object or keyword to be cross-referenced. You can cross-reference any valid resource type or attribute known to CEDA. For example, your CRFINPT file may contain the following entries (one per line):
For each record in the file, a report is produced detailing the different values assigned to the keyword, where they are defined, and where they are used. Note that keyword values longer than 44 characters are truncated.
You should define the DCB subparameters for CRFINPT as DSORG=PS, RECFM=F, LRECL=80, and BLKSIZE=80.
The CICS-supplied sample DB2 formatting program organizes the CSD data passed to it from DFHCSDUP into a format suitable for the DB2 table load utility. The data is organized into columns that correspond to the columns defined in the load utility’s input. Each selected resource causes a record to be written to this program’s output file, with the first 4 characters identifying the resource type.
The program must be run against an EXTRACT command of the form:
EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name)
or:
EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name)
Note that the sample program requires you to specify the OBJECTS keyword.
The CICS-supplied sample CSD backup utility program produces a file of DFHCSDUP DEFINE control statements. The file can be used:
The program must be run against an EXTRACT command of the form:
EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name)
or:
EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name)
Note that the sample program requires you to specify the OBJECTS keyword.
Note the following points when using DFH0CBDC:
You must assemble (or compile) and link-edit DFHCSDUP user programs as batch programs, not as CICS applications, and you need link-edit control statements appropriate to the language in which they are written.
When you compile the COBOL versions of the sample programs, you must specify the compiler attributes RENT and NORES. 16
When you link-edit the programs, you must specify the following link-edit control statements:
When you link-edit the COBOL versions of the sample programs, you must specify RMODE(24).
These requirements are explained in more detail for each of the languages (assembler, COBOL, and PL/I ) shown in the following sample job streams.
The sample job in Figure 111 shows the link-edit statements you need for an assembler-language version of a DFHCSDUP user program.
//DFHCRFA JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid
//* .
//* Assembler job step here
//* .
//LINK EXEC PGM=IEWL,PARM='XREF,LIST,LET'
//OBJLIB DD DSN=object.module.library,DISP=SHR
//SYSLIB DD DSN=CICSTS31.CICS.SDFHLOAD,DISP=SHR
//SYSLMOD DD DSN=user.library,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(1024,(100,10))
//SYSPRINT DD SYSOUT=A
//SYSLIN DD *
ENTRY DFHEXTRA 1
CHANGE EXITEP(csectname) 2
INCLUDE SYSLIB(DFHEXAI) 3
INCLUDE OBJLIB(obj-name) 4
NAME progname(R) 5
Notes for the assembler job:
1 Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXAI. (See 3 .)
2 The CICS-supplied stub, DFHEXAI, is generated with a link to the user program using a dummy CSECT name (EXITEP). Use the link-edit CHANGE statement to change the CSECT name from EXITEP to the name of the CSECT in the user program. In the two CICS-supplied assembler-language sample programs, these names are:
3 Include DFHEXAI in any assembler-language user program that you write for use with the DFHCSDUP EXTRACT command. DFHEXAI is the interface stub between DFHCULIS, a module in DFHCSDUP, and the user program.
4 obj-name is the name of the library member that contains the assembled object module.
5 progname is the name you want to call the load module; this is the name that you specify on the USERPROGRAM parameter of the EXTRACT command.
The sample job in Figure 112 shows the link-edit statements you need for a DFHCSDUP user program written in a Language Environment®-conforming high-level language.
//DFHCRFA JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid
//* .
//* Compile job step here
//* .
//LINK EXEC PGM=IEWL,PARM='XREF,LIST,LET'
//SYSLIB DD DSN=PP.ADLE370.OS39025.SCEELKED
//CICSLIB DD DSN=CICSTS31.CICS.CICS.SDFHLOAD,DISP=SHR
//OBJLIB DD DSN=object.module.library,DISP=SHR
//SYSLMOD DD DSN=user.library,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(1024,(100,10))
//SYSPRINT DD SYSOUT=A
//SYSLIN DD *
ENTRY DFHEXTRA 1
CHANGE EXITEP(prof-id) 2
INCLUDE CICSLIB(DFHEXLE) 3
INCLUDE OBJLIB(obj-prog) 4
NAME progname(R) 5
Notes for the Language Environment job:
1 Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXLE (see 3 ).
2 The CICS-supplied stub, DFHEXLE, is generated with a link to the user program using a dummy CSECT name (EXITEP). Use the link-edit CHANGE statement to change the CSECT name from EXITEP to the name specified on the PROC statement in the user program.
3 Include DFHEXLE in any LE-conforming user program that you write for use with the DFHCSDUP EXTRACT command. DFHEXLE is the interface stub between DFHCULIS, a module in DFHCSDUP, and the Language Environment user program.
4 obj-prog is the name of the object program.
5 progname is the name you want for the load module; this is the name that you specify on the USERPROGRAM parameter of the EXTRACT command.