The user exit points in DFHCSDUP

There are five user exit points in DFHCSDUP. By specifying the appropriate entry parameters, you can cause DFHCSDUP to pass control to an exit routine at any of these points.

None of the user exits supports XPI calls.

Parameters passed to the user exit routines

The address of a parameter list is passed to the user exit routine in register 1. The list contains some standard parameters that are passed to all of the exit routines, and may also contain some exit-specific parameters that are unique to the exit point from which the exit routine is being invoked.

The standard parameter list is different from that used by CICS® global user exits. The following DFHUEXIT DSECT maps the standard parameter list used by DFHCSDUP and the sample program DFH$CUS1. (The UEPCMDA and UEPCMDL fields are are used only by the get-command exit.)

DFHUEXIT DSECT                                                 
UEPEXN   DS    A                ADDRESS OF EXIT NUMBER         
UEPGAA   DS    A                ADDRESS OF GLOBAL AREA         
UEPGAL   DS    A                ADDRESS OF GLOBAL AREA LENGTH  
UEPCRCA  DS    A                ADDRESS OF CURRENT RETURN-CODE 
UEPTCA   DS    A                ADDRESS OF TCA                 
UEPCSA   DS    A                ADDRESS OF CSA                 
UEPHMSA  DS    A                ADDRESS OF SAVE AREA USED BY HOST 
UEPSTACK DS    A                ADDRESS OF KERNEL STACK ENTRY  
UEPXSTOR DS    A                ADDRESS OF STORAGE OF XPI PARMS
UEPTRACE DS    A                ADDRESS OF TRACE FLAG          
*                                                              
UEPCMDA  DS    A                ADDRESS OF UTILITY COMMAND     
UEPCMDL  DS    A                ADDRESS OF LENGTH OF UTILITY   
*                               COMMAND                        

Explanations of the exit-specific parameters are included in the descriptions of the individual exits, which follow.

The initialization exit

The initialization exit is invoked once during DFHCSDUP initialization. Its purpose is to allow a routine to perform exit-related initialization. For example, the routine may obtain its own global work area and save its address in UEPGAA and its length in the halfword pointed to by UEPGAL. These values are retained by DFHCSDUP and become available at the other exit points.

When invoked
Invoked once, on entry to DFHCSDUP.
Exit-specific parameters
None.
Return codes
UERCNORM (X'00')
Continue processing.
UERCERR
Irrecoverable error. This causes DFHCSDUP to terminate with a return code of ‘8’.
XPI calls
Must not be used.

The get-command exit

The purpose of the get-command exit is to read in command lines. If it is specified, no commands are read from SYSIN.

On invocation, your exit routine must supply the address and length of a complete command. It must return control with either the normal return code ‘UERCNORM’ or with the code ‘UERCDONE’, signifying that it has no more commands to pass. After it has processed each command, DFHCSDUP reinvokes the exit until return code ‘UERCDONE’ is received.

When invoked
Invoked multiple times, at the point where DFHCSDUP would otherwise read commands from SYSIN.
Exit-specific parameters
UEPCMDA
Pointer to the address of a command.
UEPCMDL
Address of a halfword containing the length of the command text. The maximum length that can be specified is 1536 bytes.
Return codes
UERCNORM (X'00')
Continue processing.
UERCDONE (X'04')
No more commands to process. (This is equivalent to reaching end-of-file on the SYSIN file.)
UERCERR
Irrecoverable error. This causes DFHCSDUP to terminate with a return code of ‘8’.
XPI calls
Must not be used.

The extract exit

The extract exit is invoked at various points during processing of the EXTRACT command. The points are listed in When the user program is invoked.

Notes:
  1. If you do not specify an EXTRACT user exit routine on the entry linkage to DFHCSDUP, or on the USERPROGRAM keyword, a syntax error occurs.
  2. A user exit routine specified on the USERPROGRAM keyword is used in preference to one specified on the entry linkage.

When invoked
Invoked multiple times during processing of the EXTRACT command.
Exit-specific parameters
EXTRACT_FUNCTION_CODE_PTR
Address of a halfword containing a code that defines the point in EXTRACT processing reached. The EXTRACT function codes are listed in EXTRACT function codes.
EXTRACT_WORK_AREA_PTR
Address of a fullword containing the address of the EXTRACT work area.
EXTRACT_BACKTRAN_COMMAND_PTR
Address of a fullword containing the address of the EXTRACT command being processed.
EXTRACT_CSD_LIST_NAME_PTR
Address of an 8-byte field containing the name of the list whose data is being extracted. This value is set only on ‘list start’ and ‘list end’ calls.
EXTRACT_CSD_GROUP_NAME_PTR
Address of an 8-byte field containing the name of the group whose data is being extracted. This value is set on ‘group start’, ‘group end’, ‘object start’, ‘object end’, and ‘keyword’ calls.
EXTRACT_CSD_OBJECT_TYPE_PTR
Address of a 12-byte field that identifies the type of object (such as TRANSACTION, PROGRAM, and so on). This value is set only on ‘object start’, ‘object end’, and ‘keyword’ calls.
EXTRACT_CSD_OBJECT_NAME_PTR
Address of an 8-byte field containing the name of the object. This value is set only on ‘object start’, ‘object end’, and ‘keyword’ calls.
EXTRACT_KEYWORD_NAME_PTR
Address of an 12-byte field containing the name of the keyword being processed. This value is set on ‘keyword’ calls only.
EXTRACT_KEYWORD_LENGTH_PTR
Address of a halfword containing the length of the value associated with the keyword. This value is set on ‘keyword’ calls only.
EXTRACT_KEYWORD_VALUE_PTR
Address of a character string which contains the value associated with the keyword. This value is set on ‘keyword’ calls only.

Note that these parameters are similar to those passed when DFHCSDUP is invoked as a batch program. (See Parameters passed from DFHCSDUP to the user program.) However, when DFHCSDUP is invoked from a user program, the parameter list also includes the standard parameters mentioned under Parameters passed to the user exit routines.

Return codes
UERCNORM (X'00')
Continue processing.
UERCERR
Irrecoverable error. This causes DFHCSDUP to terminate with a return code of ‘8’.
XPI calls
Must not be used.

The put-message exit

The put-message exit is invoked whenever a message is to be issued. If you are running under TSO, you could use this exit to terminate DFHCSDUP after the operator inputs an ATTENTION interrupt. (See Invoking DFHCSDUP from a user program.) Or you could use it to provide messages in the operator’s national language.

Even if this exit is supplied, messages are always additionally written to the default output file (that is, to SYSPRINT, or to the replacement ddname specified on the entry linkage to DFHCSDUP).

When invoked
Invoked when a message is to be issued.
Exit-specific parameters
UEPMNUM
Address of a 4-character field containing the message number
UEPMDOM
Reserved
UEPINSN
Address of a 2-byte field containing the number of insert fields
UEPINSA
Address of the following message structure:
                DS  F    Reserved
 INS_1_TEXT_PTR  DS  A    Address of insert 1
 INS_1_LEN_PTR   DS  A    Address of a fullword containing
                          the length of insert 1
                 DS  F    Reserved
                 DS  F    Reserved
 INS_2_TEXT_PTR  DS  A    Address of insert 2
 INS_2_LEN_PTR   DS  A    Address of a fullword containing
                          the length of insert 2
                 DS  F    Reserved
                 ...
                 DS  F    Reserved
 INS_n_TEXT_PTR  DS  A    Address of insert n
 INS_n_LEN_PTR   DS  A    Address of a fullword containing
                          the length of insert n
                 DS  F    Reserved
 

The exit-specific parameters provide a message number and insert fields only, to enable you to provide messages in the language of your TSO operators. The structure pointed to by UEPINSA is repeated as many times as UEPINSN requires.

Return codes
UERCNORM (X'00')
Continue processing.
UERCERR
Irrecoverable error. This causes DFHCSDUP to terminate with a return code of ‘8’.
XPI calls
Must not be used.

The termination exit

The purpose of the termination exit is to allow you to perform final housekeeping duties. It is invoked before a normal or an abnormal termination of DFHCSDUP.

When invoked
Invoked once, before termination of DFHCSDUP.
Exit-specific parameters
UEPTRMFL
Address of a 1-byte field that indicates the mode of termination. Its possible values are:
X'00'
Normal termination
X'F0'
Abnormal termination.

Your exit program cannot reset the value in this field.

Return codes
UERCNORM (X'00')
Continue processing.
UERCERR
Irrecoverable error. This causes DFHCSDUP to terminate with a return code of ‘8’.
XPI calls
Must not be used.

Related concepts
An overview of DFHCSDUP
DFHCSDUP as a part of the resource definition process
Related tasks
Invoking a user program from DFHCSDUP
Invoking DFHCSDUP from a user program
Related reference
The sample program, DFH$CUS1
[[ Contents Previous Page | Next Page Index ]]