Invoking a user program from DFHCSDUP

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.

Writing a program to 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

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]
GROUP
selects only those resource definitions within the named group. You can specify a generic group name, as on the DFHCSDUP LIST command.
LIST
selects only those resource definitions within the groups contained in the named list. You can specify a generic list name only if you do not specify the OBJECTS option.
OBJECTS
returns the detail of each resource definition. You can extract resource definition data at two levels of detail:
  1. If you omit the OBJECTS option, the command extracts one of the following:
    • The names of all the resource definitions within the specified group
    • The names of all the groups within the specified list.
  2. If you specify the OBJECTS option, all the attributes of the resource definitions are also extracted.
USERPROGRAM
is the name of the user-written program that is to process the data retrieved by the EXTRACT command. You must supply a USERPROGRAM value.

When the user program is invoked

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:

  1. At the beginning of EXTRACT processing. This is to allow for activities such as file opening and storage acquisition.
  2. At the beginning of LIST processing, but only if you have specified a LIST value on the EXTRACT command.
  3. At the start of every group being processed by the EXTRACT command.
  4. At the start of each object (that is, resource type--TERMINAL, PROGRAM, and so on) that is being processed, to allow for selection on an object or group basis.
    Note:
    If you have specified LIST but not OBJECTS on the EXTRACT command, this invocation does not occur.
  5. For every keyword (attribute) in the extracted object, but only if you have specified OBJECTS on the EXTRACT command. This is to allow for the detailed processing that may be necessary for cross-referencing.
  6. At the end of every object--that is, when all of the keywords within an object have been processed. This is to allow for the processing of data built up from the detailed items, and it occurs once for each object.
  7. At the end of every group, to allow for processing of the accumulated data.
  8. At the end of LIST processing, if you have specified a LIST value on the EXTRACT command.
  9. When EXTRACT processing is complete, to allow for closing of files, release of storage, and so on.

Parameters passed from DFHCSDUP to the user program

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:

Function Type Ptr
The address of a halfword field that contains a code defining the point in EXTRACT processing reached.

The function codes are as follows:

0    Initial call
2    List start call
4    Group start call
6    Object start call
8    Keyword detail call
10    Object end call
12    Group end call
14    List end call
16    Final call.
Workarea Ptr
This is the address of a field containing the address of a fullword to be used by the user application to store the address of any user-acquired work area.
Back translated command Ptr
The address of a fullword that contains the address of a 75-byte area of storage that contains the EXTRACT command that is being processed.
List name Ptr
The address of an 8-byte field that identifies the RDO list from which the current object is taken. This value is set only on the ‘list start’ and ‘list end’ calls.
Group name Ptr
The address of an 8-byte field that identifies the RDO group from which the current object is taken. This value is set on the ‘group start’, ‘group end’, ‘object start’, ‘object end’, and ‘keyword’ calls.
Object type Ptr
The address of a 12-byte field that identifies the type of object (such as TRANSACTION, PROGRAM, and so on), and is set only on the ‘object start’, ‘object end’, and ‘keyword’ calls.
Object name Ptr
The address of an 8-byte field that contains the name of the object, and is set only on the ‘object start’, ‘object end’, and ‘keyword’ calls.
Keyword name Ptr
The address of a 12-byte field that contains the name of the keyword being processed, and is set only on ‘keyword’ calls.
Keyword length Ptr
The address of a halfword field that contains the length of the value associated with the keyword, and is set only on ‘keyword’ calls.
Keyword Value Ptr
The address of the storage area that contains the value associated with the keyword, and is set only on ‘keyword’ calls.
Note:
Fields not set with a pointer value contain a null value.

The sample EXTRACT programs

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.

Table 47. Sample EXTRACT user programs for the DFHCSDUP utility program
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:

CRFOUT
CSD cross-referencing program
FOROUT
DB2 formatting program
CBDOUT
CSD backup utility program.

The sample programs are discussed in the next three sections.

The CSD cross-referencing program

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):

PROGRAM
TRANSACTION
TYPETERM
DSNAME

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 DB2 formatting program

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 CSD backup utility program

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:

Assembling and link-editing EXTRACT programs

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.

Note:
DFHCSDUP user programs should not be translated, or unpredictable results could occur.

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.

An assembler-language version

The sample job in Figure 111 shows the link-edit statements you need for an assembler-language version of a DFHCSDUP user program.

Figure 111. Link-edit control statements for a DFHCSDUP user program (assembler-language)
//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:

CREFCSD
The CSECT name in DFH$CRFA, the cross-reference listing user program.
FORMCSD
The CSECT name in DFH$FORA, the DB2-formatting user program.

 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.

A Language Environment version

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.

Figure 112. Link-edit control statements for a DFHCSDUP user program (Language Environment)
//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.

Related concepts
An overview of DFHCSDUP
DFHCSDUP as a part of the resource definition process
Related tasks
Invoking DFHCSDUP from a user program
Related reference
The user exit points in DFHCSDUP
The sample program, DFH$CUS1

16.
The RENT compiler attribute prevents an abend C03 ('Dataset was not closed properly') occurring after the sample program receives an abend such as B37 ('Dataset size is smaller than output').

[[ Contents Previous Page | Next Page Index ]]