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.
- 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:
a special character string is passed to Language Environment during run unit initialization in the rtopts parameter. The following string is passed:CEDF term,ON,INSPECT
whereTEST,TERM=xxxx
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 stringTEST
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.
- 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.
- 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:
- 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.
- 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.