An OPENAPI program,
although freed from the constraints imposed by the QR TCB, nevertheless does
have obligations both to the CICS® system as a whole and to future users of the L8
or L9 TCB it is using. An L8 or L9 TCB is dedicated for use by the CICS task to
which it is allocated, but once the CICS task has completed, the TCB is returned
to the dispatcher-managed pool of such TCBs, provided it is still in a clean
state (An unclean TCB in this context means that the task using the L8 or
L9 mode TCB suffered an unhandled abend in an OPENAPI program. It does not
mean that the program has broken the threadsafe restrictions, which CICS would not
detect). Note that the TCB is not dedicated for use by a particular
OPENAPI program, but is used by all OPENAPI programs and OPENAPI TRUEs invoked
by the CICS task
to which the L8 mode TCB is allocated. Also, if an application program invoking
an OPENAPI program is coded to threadsafe standards, and defined to CICS as threadsafe,
it continues to execute on the L8 mode TCB on return from the program.
- Threadsafe restrictions:
An OPENAPI program must not treat the executing open TCB environment
in such a way that it causes problems for:
- Application program logic that could run on the open TCB
- OPENAPI TRUEs called by the same task
- Future tasks that might use the open TCB
- CICS management
code.
At your own risk, if your OPENAPI program decides to use other (non CICS)
APIs, you must be aware of the following:
- When invoking CICS services, or when returning to CICS, an OPENAPI
program must ensure it restores the MVS™ programming environment as it was on
entry to the program. This includes cross-memory mode, ASC mode, request block
(RB) level, linkage stack level, TCB dispatching priority, in addition to
cancelling any ESTAEs added.
- At CICS task
termination, an OPENAPI program must ensure it leaves the open TCB in a state
suitable to be reused by another CICS transaction. In particular, it must
ensure that all non-CICS resources acquired specifically on behalf of the
terminating task are freed. Such resources might include:
- Dynamically allocated data sets
- Open ACBs or DCBs
- STIMERM requests
- MVS managed
storage
- ENQ requests
- Attached subtasks
- Loaded modules
- Owned data spaces
- Added access list entries
- Name/token pairs
- Fixed pages
- Security settings (TCBSENV must be set to zero)
- An OPENAPI program must not use the following MVS system services that will affect overall CICS operation:
- CHKPT
- ESPIE
- QEDIT
- SPIE
- STIMER
- TTIMER
- XCTL / XCTLX
- Any TSO/E services.
- An OPENAPI program must not invoke under the L8 or L9 mode TCB a Language Environment® program that is using MVS Language Environment services,
because L8 and L9 mode TCBs are initialized for Language Environment using CICS services.