User-Exit Program for Schema and Subschema Compiler › 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 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 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 compilers. For exits to be used with the batch compilers, the only CA IDMS/DC macros supported are: #WTL, #ABEND, #GETSTG, #FREESTG, #LOAD, and #DELETE; under z/VSE, 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 applicable 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 points

  The user exit invoked by each compiler has a unique entry point name.

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 schema or subschema compilers, 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 applicable online compiler require a user-exit interface, written in Assembler with an entry point appropriate to the compiler for which it is to be invoked. This interface should issue a #LINK to the COBOL program (with an entry point other than IDMSCHDC or IDMSUBDC) to isolate it from IDMSCHDC or IDMSUBDC, which is storage-protected.

• Register conventions

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

  R15        Entry point of 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 applicable 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 separately later in this appendix.

• Information modification

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

• Return codes

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