Run unit (program) initialization

The next stage prior to run unit (program) invocation is the run unit initialization. This is requested by CICS® through the run unit initialization call after loading the run unit (Language Environment-enabled PPT module) and prior to control being passed to it. Run unit load point, entry point, parameter list as well as the Language Environment thread token are provided in this call. If the run unit can not be initialized, CICS abends the task. Run unit initialization occurs at:
  • CICS task attachment
  • EXEC CICS LINK or EXEC CICS XCTL commands

Syntax

Call CEECCICS (30, rsncode, syseib, preasa, ptoken, ttoken, rtoken, pgminfo1, pgminfo2, ioinfo, runinfo, retoken) Retcode (rc)

rsncode (output)
A fullword integer in nnnffrr format to contain one of the following Language Environment reason codes:
13000
Invalid parameter was passed
13010
No run unit work area was passed
13040
No application program argument list was passed
13200
Invalid parameter was passed when the direct invoke bit is set
13210
No run unit work area was passed when the direct invoke bit is set
13230
Language-specific run unit invocation failed when the direct invoke bit is set
13240
No application program argument list was passed when the direct invoke bit is set
syseib
The system EXEC interface block, as defined by CICS. This control block contains information about running the CICS commands issued by Language Environment. There is no need to save and restore the user EIB around the commands issued by Language Environment. The system EIB address is above 16M.
Note: The user EIB, which is different than the system EIB, is passed to the application program in the application program argument list.
preasa
A preallocated save area passed to Language Environment by CICS. 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 (output)
A doubleword value to contain the Language Environment run unit token.
pgminfo1
The structure of information supplied by CICS to Language Environment is shown in Figure 1.
Figure 1. Structure of information supplied to Language Environment by CICS
DCL 1 PGMINFO1,                       /* Data from CICS to Lang Env    */
      2 STRUC_LENGTH   FIXED BIN(31), /*+00 pgminfo1 structure length  */
      2 RULANG,                       /*+04 Run unit's "main" program 
                                            language defined in PPT as */
        3 ASSEMBLER    BIT(1),        /*+04.0 LANG=ASSEMBLER           */
        3 C370         BIT(1),        /*+04.1 LANG=C/370               */
        3 COBOL        BIT(1),        /*+04.2 LANG=COBOL II            */
        3 PLI          BIT(1),        /*+04.3 LANG=PL/I                */
        3 RPG          BIT(1),        /*+04.4 LANG=RPG                 */
        3 NOTAPPLIC    BIT(1),        /*+04.5 LANG=NOTAPPLIC or blank  */
        3 *            BIT(2),        /*    Reserved                   */
      2 FLAGS,                        /*+05 Additional Flags           */
        3 OPEN_PROGRAM BIT(1),        /*+05.0 1 = Program runs only on
                                                  OTE TCB and can use 
                                                  Open C functions    
                                              0 = Program may run on  
                                                  OTE or QR TCB        */
        3 *            BIT(7),        /*    Reserved                   */
      2 RULOADMOD,                                                    
        3 RULOADA      POINTER,       /*+08 Run unit load module addr  */
        3 RULOADL      FIXED BIN(31), /*+0C Run unit load module length */
      2 ENTRY_STATIC,                                                 
        3 RUENTRY      POINTER,       /*+10 Run unit Entry Point Addr  */
        3 RUSTATIC     POINTER,       /*+14 Run unit Static Address    */
      2 PREARWA_31     POINTER,       /*+18 Preallocated run unit work */
                                      /*    area above 16Meg           */
      2 PREARWA_24     POINTER,       /*+1C Preallocated run unit work */
                                      /*    area below 16Meg           */
      2 APAL           POINTER,       /*+20 Application Pgm Arg List   */
      2 RTOPTS         POINTER,       /*+24 Runtime options string    */
                                      /*    specified during debugging */
      2 RTOPTSL        FIXED BIN(31), /*+28 Runtime opts string length */
      2 RULOAD_NAMEA   POINTER,       /*+2C Address of the run unit    */
                                      /*    load module name           */
      2 *              POINTER,       /*+30 Reserved                   */
      2 RUDEBUGA       POINTER,       /*+34 Address of the run unit    */
                                      /*    Debug Info Block           */
struc_length
A fullword value containing the pgminfo1 structure length.
rulang
A fullword binary value indicating the language type of the run unit (main program) as defined in PPT. In PPT, LANG=NOTAPPLIC can be used for Language Environment-enabled application programs. For bit definitions, see above.
ruloada
A fullword value containing the load address of the run unit. This address in conjunction with the entry point address is used to access run unit prolog information (PPA1, PPA2) when necessary.
ruloadl
A fullword value containing the load module length of the run unit. This value is used to validate the addresses accessed through the run unit prolog information (PPA1, PPA2) when necessary.
ruentry
A fullword value containing the entry point address of the run unit. This address is given control at the run unit begin invocation call for Language Environment-enabled programs. The run unit entry is established at link-edit time. The high-order bit indicates the AMODE of the run unit.
rustatic
A full word passed in R0 to the main program at the run unit begin invocation call.
prearwa_31
A fullword value containing the address of the preallocated run unit work area above 16M. The length of this preallocated work area was passed back to CICS at establish ownership type call prior to run unit initialization call. This work area can be initialized to contain CAA, HEAP, ISA and other Language Environment control blocks.
prearwa_24
A fullword value containing the address of the preallocated run unit work area below 16M. The length of this preallocated work area was passed back to CICS at establish ownership type call prior to run unit initialization call. This work area can be initialized to contain control blocks that have to be below 16M.
apal
A fullword value containing the address of the application program argument list. This argument list contains the address of the user EIB and the address of a COMMAREA.
rtopts
A fullword value containing the address of the runtime options string passed to CICS during debugging with CICS EXEC Debugging Facility (EDF). For example, CEDF terminal-ID,ON,'runtime options'.
rtoptsl
A fullword value containing the length of the runtime options string.
When EDF is invoked in the following fashion:
CEDF term,ON,INSPECT
a special character string is passed to Language Environment during run unit initialization in the rtopts parameter. The following string is passed:
TEST,TERM=xxxx
where xxxx is the terminal identifier for the terminal where debugging information should be communicated. (This can either be information for a 3270-type terminal or communication to/from a workstation.) Language Environment detects this string, and internally initializes as if the options string TEST was passed. Also, Language Environment passes the terminal identifier to IBM Debug for z/OS as a new, fifth parameter of the external entries debugger event.
ruload_namea
A fullword address that points to the load module name. The load module name is 8-bytes long and is padded with blanks.
rudebuga
A fullword address that points to the run unit degug info block. The debug info block is 8-bytes long and is padded with blanks.
pgminfo2
The structure of information described at establish ownership type call.
ioinfo (output)
A structure that contains the standard input/output and error file information (transient data queue names or spool file classes). The structure declaration is in Figure 2.
Figure 2. Structure of standard I/O information provided to Language Environment by CICS
DCL 1 IOINFO,                           /* I/O Information Structure   */
                                        /*                             */
      2 STD_IN,                         /* Standard input file         */
        3 QORS_IN      CHAR(1),         /* - either                    */
                                        /*   'Q', transient data queue */
                                        /*   'S', spoolfile            */
        3 TDQN_IN      CHAR(4),         /* - queue name                */
        3 SPOC_IN      CHAR(1),         /* - spool class               */
                                        /*                             */
      2 STD_OUT,                        /* Standard output file        */
        3 QORS_OUT     CHAR(1),         /* - either                    */
                                        /*   'Q', transient data queue */
                                        /*   'S', spoolfile            */
        3 TDQN_OUT     CHAR(4),         /* - queue name                */
        3 SPOC_OUT     CHAR(1),         /* - spool class               */
                                        /*                             */
      2 STD_ERR,                        /* Standard error file         */
        3 QORS_ERR     CHAR(1),         /* - either                    */
                                        /*   'Q', transient data queue */
                                        /*   'S', spoolfile            */
        3 TDQN_ERR     CHAR(4),         /* - queue name                */
        3 SPOC_ERR     CHAR(1),         /* - spool class               */
runinfo (input)
Address of a fullword containing information about how the run unit should be initialized and whether it should be immediately invoked after initialization. See Figure 3.
Figure 3. Run information supplied to Language Environment by CICS
DCL 1 RUNINFO      BIT(32),             /* Run Information              */
      2 INVOKE     BIT(1),              /* Call Lan Env Begin Invocation*/
                                        /* after initialization?        */
                                        /*  0 - Return after init       */
                                        /*  1 - Call Begin Invocation   */
      2 RWA_REUSE  BIT(1),              /* RWA candidate for reuse?     */
                                        /*  0 - No                      */
                                        /*  1 - Yes                     */
      2 *          BIT(30),             /* Reserved                     */
retoken (input)
A doubleword value to contain the run-unit token of the most recently invoked JVM in the chain (or zero if none exists). The presence of a n address tells Language Environment there is a JVM reusable enclave as a parent.
Note: The run unit initialization process operates as follows, resulting in shortened path lengths and improved performance:
  1. The INVOKE bit is tested and if on, run unit initialization calls run unit begin invocation directly using the registers/parmlist passed by CICS for the run unit initialization call.
  2. The RWA_REUSE bit is tested in run unit initialization and a new bit, CEEEDB_CICS_RUNREUSE, is turned on to indicate that the run work area may be reused.