Customizing with user-replaceable programs

A user-replaceable program is a CICS-supplied program that is always invoked at a particular point in CICS® processing, as if it were part of the CICS code. You can modify the supplied program by including your own logic, or replace it with a version that you write yourself.

When creating your own versions of user-replaceable programs, you must follow this guidance:
  • You can code user-replaceable programs in any of the languages supported by CICS (that is, in assembler language, COBOL, PL/I, or C). An assembler-language version of most programs is provided, in source form, in the CICSTS55.CICS.SDFHSAMP library. COBOL, PL/I, or C versions are provided for some programs. The description of each program lists the sample programs, copy books, and macros supplied in each case.
  • You can trap an abend in a user-replaceable program by making the program issue an EXEC CICS HANDLE ABEND command. However, if no HANDLE ABEND is issued, CICS does not abend the task but returns control to the CICS module that called the program. The action taken by the CICS module depends on the user-replaceable program concerned.
  • Upon return from any user-replaceable program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers restored (except for those which provide return codes or linkage information).

    For information about translation modes, see z/Architecture Principles of Operation.

  • In z/OS®, do not install SVCs or PC routines that return control to their caller in any authorized mode: that is, in supervisor state, system PSW key, or APF-authorized. Doing so is contrary to the z/OS Statement of Integrity. If you invoke such services from CICS, you might compromise your system integrity, and any resultant problems will not be resolved by IBM® Service.
  • User-replaceable programs, and any programs invoked by user-replaceable programs, can be RMODE ANY but must be AMODE 31.
  • You must ensure that user-replaceable programs are defined as local. User-replaceable programs cannot be run in a remote region. This rule applies to all user-replaceable programs, including the autoinstall control program and the dynamic routing program.
  • User-replaceable programs produce only system dumps when a program check occurs; they do not produce transaction dumps.
  • You can use the CICS Execution Diagnostic Facility (EDF) to test user-replaceable programs. However, EDF does not work if the initial transaction is a CICS-supplied transaction.