Run unit (program) end invocation

The Language Environment-CICS interface routine is called for run unit end invocation as a result of a normal return (with language terminating statements) from the run unit begin invocation or as a result of a CICS® terminating command from the application program or Language Environment.

If the program undergoes normal termination through the language statements such as COBOL's STOP RUN, PL/I's END or RETURN or SIGNAL FINISH, Language Environment termination imminent condition is raised by the program load module. After this condition is handled by the Language Environment exception handler, control is returned to the Language Environment run unit begin invocation routine with the return address (R14) originally stored in the first save area of the program work area. Language Environment run unit begin invocation routine then returns to CICS. Next, the Language Environment-CICS interface routine expects a call for run unit end invocation to do the invocation-based clean ups.

If the program undergoes termination (normal or abnormal) as a result of running the EXEC CICS XCTL, RETURN, or SEND PAGE RELEASE commands or from an abend (program check or EXEC CICS ABEND command), the Language Environment-CICS interface module is driven by CICS. The run unit end invocation call receives the run unit token to identify the Language Environment run unit that is being terminated. A program termination block (PTB, the TERMINFO structure) is also provided by CICS to describe the termination situation (normal or abnormal). This call notifies Language Environment that one of the resources for which it is responsible is terminating due to some reason that might not yet be known.

Restrictions on the Language Environment run unit end invocation routine are:

It must always return to the address in R14
It must not issue EXEC CICS ABEND (it can issue any other EXEC CICS command that does not raise a subsequent error)

Syntax

Call CEECCICS (33, rsncode, syseib, preasa, ptoken, ttoken, rtoken, pgminfo1, pgminfo2, ptb) Retcode (rc)

rsncode (output)

A fullword integer that contains one of the following Language Environment reason codes:

13300: Invalid parameter was passed
13310: Wrong thread token was passed
13320: No PTB was passed

syseib

The system EXEC interface block, as defined by CICS for use by Language Environment and language-specific interface routines. The system EIB address is above 16M.

preasa

A fullword value containing the preallocated save area address to be used by Language Environment to issue the last EXEC CICS FREEMAIN command. The size of this save area is 248 bytes.

ptoken

A doubleword value containing the Language Environment partition token established at partition initialization.

ttoken

A doubleword value containing the Language Environment thread token established at thread initialization.

rtoken

A doubleword value containing the Language Environment run unit token established at run unit initialization.

pgminfo1

The structure of information supplied by CICS to Language Environment, as shown in Figure 1; this is the same structure as in the run unit begin call.

pgminfo2

The structure of information supplied by CICS to Language Environment, as shown in the example here; this is the same structure as in the run unit begin call.

ptb

A fullword value containing the address of the program termination block, the TERMINFO structure. This structure contains information regarding the normal and abnormal termination of a run unit. For abnormal termination, information such as PSW, general purpose registers, floating-point registers and access registers at the time of interrupt are provided. A retry mechanism is also provided. A declaration of the PTB is shown in Figure 1.

Figure 1. Program termination block (PTB) declaration

DCL 1 TERMINFO,                  /* Program Termination Block       */ 
      2 TERMCODE BIT(32),        /* Termination Code - see below    */ 
        3 ABNORM       BIT(1),   /* .00 Abnormal Termination        */  
        3 NORMCEL      BIT(1),   /* .01 Normal Termination (LE)     */
        3 NORMRET      BIT(1),   /* .02 Normal Termination (return) */
        3 NORMASM      BIT(1),   /* .03 Normal Termination (ASM)    */  
        3 ABNPCHK      BIT(1),   /* .04 Abnormal Term (PGM Check)   */
        3 ABNOTHER     BIT(1),   /* .05 Abnormal Term (ABEND)       */
        3 ABNLINK      BIT(1),   /* .06 Abnormal Term (lower level) */  
        3 HANDELAB     BIT(1),   /* .07 User HANDLE ABEND pending   */
        3 PTBINUSE     BIT(1),   /* .08 PTB is busy                 */
        3 PSWCICS      BIT(1),   /* .09 PSW is in CICS code         */  
        3 NODUMP       BIT(1),   /* .10 CICS specified nodump       */
        3 CANCEL       BIT(1),   /* .11 CICS specified cancel       */
        3 PCHKGR64     BIT(1),   /* .12 CICS supplying 64-bit regs  */
        3 PCHKAR       BIT(1),   /* .13 CICS supplying access regs  */  
        3 PCHKFR16     BIT(1),   /* .14 CICS supplying 16 FPRs, FPC */
        3 *            BIT(17),  /*     reserved                    */
      2 ABCODE CHAR(4),          /* CICS Abend Code                 */ 
      2 PCHK,                    /* Program Check Information       */ 
        3 PCHK_PSW CHAR(16),     /* - PSW                           */ 
        3 PCHK_INT,              /*   - Interrupt Data              */ 
          4 PCHK_ILC CHAR(2),    /*   - Instruction Length Code     */ 
          4 PCHK_INC CHAR(2),    /*   - Interruption Code           */ 
          4 PCHK_EAD CHAR(4),    /*   - Exception Address           */ 
        3 PCHK_GR POINTER,       /* - General Registers (32-bit or  */
                                 /*   64-bit registers)             */ 
        3 PCHK_FR POINTER,       /* - floating-point Registers      */
                                 /*   (4 FPRs or 16 FPRs and FPC    */
                                 /*    register)                    */ 	
        3 PCHK_AR POINTER,       /* - Access Registers (if present) */ 
      2 COMMREGS POINTER,        /* Registers at last CICS command  */ 
                                 /* (Appl or library -- 32-bit or   */ 
                                 /* 64-bit registers)               */ 
      2 CONTCODE BIT(32),        /* Continuation Code (receiver)    */ 
        3 TERM         BIT(1),   /* .00 Continue RU termination     */  
        3 EXEC         BIT(1),   /* .01 Resume at RTRY_GR R15       */
        3 RTRY         BIT(1),   /* .02 Resume at RTRY_AD           */
        3 TERMOTETCB   BIT(1),   /* .03 Terminate the OTE TCB       */  
        3 *            BIT(1),   /*     reserved                    */
        3 RTRYGR64     BIT(1),   /* .05 Retry with 64-bit registers */
        3 RTRYAR       BIT(1),   /* .06 Retry with access registers */
        3 RTRYFR16     BIT(1),   /* .07 Retry with 16 FPRs and FPC  */
        3 *            BIT(24),  /*      reserved                   */
      2 RTRY,                    /* Retry Information (receiver)    */ 
        3 RTRY_AD POINTER,       /* - Resume Address                */ 
        3 RTRY_PM POINTER,       /* - Program Mask                  */ 
        3 RTRY_GR POINTER,       /* - General Registers (32-bit or  */ 
                                 /*   64-bit registers)             */
        3 RTRY_FR POINTER,       /* - floating-point Registers      */
                                 /*   (4 FPRs or 16 FPRs and FPC    */
                                 /*    register)                    */
        3 RTRY_AR POINTER,       /* - Access Registers (if present) */ 
      2 * POINTER,                 /* Reserved                        */

termcode

A fullword binary value that contains bit settings to indicate the nature, the cause and the location of the run unit end invocation. The following table describes each of the bit settings:

Bit setting	Description
Bit0 (abnorm)	Indicates an abnormal termination. It indicates a normal termination when it is off.
Bit1 (normcel)	Indicates that a normal termination is caused by a CICS command in a Language Environment-enabled run unit. Notice that the caller does not get control back after an EXEC CICS RETURN in a called (link-edited) routine.
Bit2 (normret)	Indicates that a normal termination is caused by a BR 14 from the run unit begin invocation (program has ended with a language statement).
Bit3 (normasm)	Indicates that a normal termination is caused by a CICS command in a called (link-edited) assembler routine.
Bit4 (abnpchk)	Indicates that an abnormal termination is caused by a program check (abend ASRA) in a run unit.
Bit5 (abnother)	Indicates that an abnormal termination is caused by an abend. See the ABCODE.
Bit6 (abnlink)	Indicates that the lower level (linked to) run unit has terminated abnormally.
Bit7 (handleab)	Indicates that a user HANDLE ABEND routine is pending. The Language Environment exception manager should not handle the exception.
Bit8 (input/output) (ptbinuse)	Indicates that this PTB is busy. It is set by Language Environment during the exception handling to avoid recursion. It is turned off by Language Environment when the exception handling completes.
Bit9 (pswcics)	Indicates that the PSW is in the CICS code.
Bit10 (nodump)	Indicates that CICS specified nodump.
Bit11 (cancel)	Indicates that CICS specified cancel.
Bit12 (pchkgr64)	Indicates that CICS is supplying 64-bit registers 0-15 rather than 32-bit registers 0-15 in the areas pointed to by PCHK_GR and COMMREGS. This bit is valid only if both the CICS_EXT_REG and LE_EXT_REG flags in the Partition Init flags are 1. If CICS_EXT_REG or LE_EXT_REG is 0, Bit12 is not valid and is assumed to be 0.
Bit13 (pchkar)	Indicates that CICS is supplying the access registers in the area pointed to by pchk_ar. If Bit13 is 0, no access registers are supplied. This bit is valid only if both CICS_EXT_REG and LE_EXT_REG flags in the Partition Init flags are 1. If CICS_EXT_REG or LE_EXT_REG is 0, Bit13 is not valid and is assumed to be 0.
Bit14 (pchkfr16)	Indicates that CICS is supplying all 16 floating-point registers and the floating-point control register in the area pointed to by pchk_fr, rather than just the 4 floating-point registers (0, 2, 4, 6). This bit is valid only if both CICS_EXT_REG and LE_EXT_REG flags in the Partition Init flags are 1. If CICS_EXT_REG or LE_EXT_REG is 0, Bit14 is not valid, and is assumed to be 0.

abcode

A 4-byte character string that identifies the abend code for the abnormal termination.

pchk

A structure that contains the program check information for the abnormal termination.

pchk_psw: An 8-byte field containing the Program Status Word (PSW). Notice that the first word of the PSW contains information such as the condition code and program mask at the time of interrupt and the second word of the PSW contains the address and the AMODE of the instruction after the instruction which caused the program check.
pchk_int: An 8-byte field containing the instruction length code (2 bytes), interruption code (2 bytes) and the exception address (4 bytes).
pchk_gr: If TERMCODE Bit12 is 0, pchk_gr points to a 64-byte storage area that contains the 32-bit registers (R0-R15) at the time of the program check. If TERMCODE Bit12 is 1, and both CICS_EXT_REG and LE_EXT_REG in the Partition Init flags are 1, pchk_gr points to a 128-byte storage area that contains the 64-bit registers (R0-R15) at the time of the program check.
pchk_fr: If TERMCODE Bit14 is 0, pchk_fr points to a 32-byte storage area that contains the floating-point registers F0, F2, F4, and F6 at the time of the program check. If TERMCODE Bit14 is 1, and both CICS_EXT_REG and LE_EXT_REG in the Partition Init flags are 1, pchk_fr points to a 132-byte storage area that contains all 16 floating-point registers and the floating-point control (FPC) register at the time of the program check. The register values are saved in the order: F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, FPC register. pchk_fr might point to the same area as rtry_fr.
pchk_ar: If TERMCODE Bit13 is 1, and both CICS_EXT_REG and LE_EXT_REG in the Partition Init flags are 1, pchk_ar points to a 64-byte storage area that contains access registers (AR0-AR15) at the time of the program check. If TERMCODE Bit13 is 0, pchk_ar is not valid. pchk_ar might point to the same area as rtry_ar.

commregs

If TERMCODE Bit12 is 0, commregs points to a 64-byte storage area that contains the 32-bit registers (R0-R15) at the time of the last CICS command. If TERMCODE Bit12 is 1, and both CICS_EXT_REG and LE_EXT_REG in the Partition Init flags are 1, commregs points to a 128-byte storage area that contains the 64-bit registers (R0-R15) at the time of the last CICS command. In either case, the CICS command could have been issued from an application program or a library routine.

contcode (output)

A fullword binary value to contain bit settings to indicate if the run unit end invocation should continue.

Bit setting	Description
Bit0 (term)	Set by Language Environment when normal or abnormal run unit end invocation is considered complete. CICS continues its run unit end invocation process without calling Language Environment for the run unit end invocation of the same run unit again.
Bit1 (exec)	Set by Language Environment to have CICS continue running the run unit at the retry address in R15 in the rtry_gr field. If contcode bit 5 is set, only the lower 31 bits of the 64-bit R15 value are used as the retry address. CICS sets up all the 32-bit or 64-bit registers from the retry structure before resuming the program with a branch on R15. The retry PSW (RTRY_AD) is ignored. Language Environment is recalled for the run unit end invocation later for this run unit. Note: The termination routine can change a normal termination into an abnormal termination by setting Bit1 of CONTCODE and making the retry point the address of an EXEC CICS ABEND.
Bit2 (rtry)	Set by Language Environment to have CICS continue running the run unit at the retry PSW (RTRY_AD) with the retry registers (RTRY_GR, RTRY_FR, and RTRY_AR if contcode Bit6 is on) set by Language Environment. CICS resumes using a method that allows all resume registers and the resume PSW to be set to the requested values as control is passed to the resume point. Language Environment is called for the run unit end call for this run unit later.
Bit3 (termotetcb)	CICS must terminate the OTE TCB.
Bit5 (rtrygr64)	Indicates that Language Environment is returning 64-bit registers 0-15 rather than 32-bit registers 0-15 in the area pointed to by rtry_gr. This bit is valid only if both CICS_EXT_REG and LE_EXT_REG flags in the Partition Init flags are 1. If CICS_EXT_REG is 0 or LE_EXT_REG is 0, Bit5 is not valid and is assumed to be 0.
Bit6 (rtryar)	Indicates that Language Environment is returning access registers AR0-AR15 in the area pointed to by pchk_ar. If Bit5 is 0, no access registers are being returned. This bit is valid only if both CICS_EXT_REG and LE_EXT_REG flag in the Partition Init flags are 1. If CICS_EXT_REG is 0 or LE_EXT_REG is 0, Bit6 is not valid and is assumed to be 0.
Bit7 (rtryfr16)	Indicates that Language Environment is returning all 16 floating-point registers (F0-F15) and the floating-point control register (FPC) in the area pointed to by rtry_fr, rather than just the 4 floating-point registers (F0, F2, F4, F6). This bit is valid only if both CICS_EXT_REG and LE_EXT_REG flag in the Partition Init flags are 1. If CICS_EXT_REG is 0 or LE_EXT_REG is 0, Bit7 is not valid, and is assumed to be 0.

rtry (input/output)

A pointer structure. The retry pointers address areas into which Language Environment places the retry information when the run unit might be continued at some point in the code. Before calling Language Environment, CICS sets these pointers to address the same areas as are used to hold the registers at program check or abend (PCHK) details. When a retry has been requested, Language Environment will reset these variables to the value in the resume cursor.

rtry_ad: The retry address desired by Language Environment. CICS uses this address to build the retry PSW or load it into R15 (depending upon the CONTCODE) before continuing to run.
rtry_pm: A pointer to a one byte field to contain the retry condition code (Bits 2 and 3) and program mask (Bits 4-7). Bits 0 and 1 are not used.
rtry_gr: If CICS_EXT_REG in the Partition Init flags is 0, rtry_gr points to a 64-byte storage area. If CICS_EXT_REG in the Partition Init flags is 1, rtry_gr points to a 128-byte storage area. When Language Environment returns to CICS, contcode Bit5 determines the contents of the area pointed to by rtry_gr. When contcode Bit5 is 0, this area contains 32-bit general registers R0-R15. When contcode Bit5 and LE_EXT_REG are 1, this area contains 64-bit general registers R0-R15.
rtry_fr: If CICS_EXT_REG in the Partition Init flags is 0, rtry_fr points to a 32-byte storage area. If CICS_EXT_REG in the Partition Init flags is 1, rtry_fr points to a 132-byte area. When Language Environment returns to CICS, contcode Bit7 determines the contents of the area pointed to by rtry_fr. When contcode Bit7 is 0, this area contains floating-point registers 0, 2, 4, and 6 for the retry. When contcode Bit7 and LE_EXT_REG are 1, this area contains floating-point registers 0-15 and the floating-point control (FPC) register. The register values are saved in the order: F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, FPC register. rtry_fr might point to the same area as pchk_fr.
rtry_ar: If CICS_EXT_REG in the Partition Init flags is 1, rtry_ar points to a 64-byte storage area. If CICS_EXT_REG in the Partition Init flags is 0, rtry_ar is not valid. When Language Environment returns to CICS, contcode Bit6 determines the contents of the area pointed to by rtry_fr. When contcode Bit6 is 0, the contents of this area is undefined. When contcode Bit6 and LE_EXT_REG are 1, the area pointed to by rtry_ar contains access registers AR0-AR15 for the retry. rtry_ar might point to the same area as pchk_ar.

If the program is terminated with the following commands, CICS requests the Language Environment-CICS interface routine through the run unit end invocation call to terminate the run unit invocation:

EXEC CICS XCTL
EXEC CICS RETURN
EXEC CICS SEND PAGE RELEASE

Bit1 or Bit3 (normal termination due to a CICS command) of TERMCODE are ON at this call. The Language Environment-CICS interface routine performs run unit end invocation activities, set Bit0 of CONTCODE to indicate that CICS should continue run unit end invocation without reentering the Language Environment-CICS interface routine and return to CICS. Notice that the termination imminent condition is not raised in this case. The termination imminent condition is raised if Language Environment is not terminating for cleanup purposes and one or more of the following conditions are true:

A user handler is active
A PL/I finish on_unit is active
The debug handler is active
Runtime option TEST(ALL,,) is specified

For any other case, there is no handler that may take action, so termination imminent is not raised to improve performance.

If the program is terminated with one of the following methods, CICS requests the Language Environment-CICS interface routine through the run unit end invocation call to terminate the run unit invocation:

EXEC CICS ABEND command
Program Check (abend ASRA by CICS)

Bit0 (abnormal termination) of TERMCODE is ON at this call. If TRAP runtime option is in effect, the Language Environment-CICS interface routine calls the Language Environment exception handler. Otherwise, it returns to CICS.

When Language Environment is called for run unit end invocation again after the exception handling, it performs all the run unit end invocation activities and return to CICS. After control is returned to CICS by Language Environment run unit end invocation, CICS can drive Language Environment run unit termination to do the run unit clean up.

Due to the nature of the activities in the run unit end invocation (for example, storages are not freed and loaded routines are not released), there is no requirement for language-specific run unit end invocation.