IDD User-Exit Program › Rules for Writing the User-exit Program

Rules for Writing the User-exit Program

This section describes the rules that apply to writing the user-exit program.

Language

You can write the user-exit module in any language that supports OS calling conventions. However, it is recommended that you write user-exit modules in Assembler to allow the online DDDL compiler to remain reentrant.

Note: User-exit modules cannot be CA ADS dialogs.

Versions

You can code and maintain separate versions of user-exit modules for the batch and online DDDL compilers, or you can code modules that can be executed both in batch mode and online.

Macros

The user-exit facility supports all CA IDMS/DC macros for exits to be used with the online DDDL compiler. For exits to be used with the batch DDDL compiler, the only CA IDMS/DC macros supported are: #WTL, #ABEND, #GETSTG, #FREESTG, #LOAD, and #DELETE; under VSE/ESA, the only valid form of #DELETE is EPADDR=.

Run units

You can start a run unit within an exit, however you should ensure that the run unit does not deadlock with the DDDL compiler run unit. If a user-exit run unit will access a dictionary area, the run unit should ready the object area in a retrieval usage mode.

Entry point

The entry point of the user exit invoked by the batch and online compilers differ.

Although each exit has a unique entry point name, you can use the same exit code for more than one compiler by assigning multiple entry point names to the same set of code.

Interface

User exits written in COBOL to run under the online DDDL compiler require a user-exit interface, written in Assembler with an entry point of IDDUXITO, to be link edited with IDMSUXIT. This interface should issue a #LINK to the COBOL program (with an entry point other than IDMSDDDC) to isolate it from IDMSDDDC, which is storage protected.

Register Conventions

User-exit modules are called using the following OS register conventions:

R15        Entry point of module IDDUXIT

R14        Return address

R13        18 fullword SAVEAREA

R1         Fullword parameter list

Parameters 3 and 4

For all four types of user exits, parameter 1 points to a user-exit control block and parameter 2 points to a SIGNON element block. The information addressed in parameters 3 and 4 varies based on the type of user exit, as follows:

• For the SIGNON/SIGNOFF/COMMIT and end-of-conversation exits, parameter 3 points to a SIGNON block.
• For the major command user exit, parameter 3 points to an entity control block.
• For the card-image user exit, parameter 3 points to a card-image control block.
• For all user exits except the card-image user exit, parameter 4 is reserved for use by IDD and should be defined as a PIC X(80) field in the user-exit module.
• For the card-image user exit, parameter 4 points to the input card image, which is defined as a PIC X(80) field.

The user-exit control blocks are described separately later in this appendix.

Information Modification

With the exception of the fields identified within the user-exit control block described below, a user-exit module should not modify any of the information passed.

Return Codes

On return from a user-exit module, the user must set a return code and, optionally, specify a message ID and message text to be issued by the DDDL compiler, as follows: