SYSGEN 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 SYSGEN 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 SYSGEN 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/DB macros for exits to be used with the online SYSGEN compiler. For exits to be used with the batch SYSGEN compiler, the only CA IDMS/DB macros supported are: #WTL, #ABEND, #GETSTG, #FREESTG, #LOAD, and #DELETE; under DOS/VS(E), 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 SYSGEN compiler run unit. If a user-exit run unit accesses 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.

Enabling a compiler exit

To enable a user exit for the system generation compiler, link your exit module with IDMSUXIT.

Note: For more information on how to enable user exits by linking them with IDMSUXIT, refer to the "User Exits" section in the CA IDMS Systems Operations Guide.

Interface

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

Register conventions

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

R15        Entry point of user exit module
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 the SYSGEN compiler 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 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 system generation compiler, as follows: