Changes to the application programming interface

This topic deals with:

Obligations of OPENAPI programs

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.

Restrictions when using EDF

OPEN TCBs and EDF

Even if your program would normally run using an OPEN TCB (L8, L9, X8, or X9) CEDF forces the program to run on the QR TCB, because CEDF itself is not threadsafe.