This topic describes how to enable IP CICS® sockets applications to exploit the Open Transaction Environment (OTE) through threadsafe programming.

The IP CICS socket interface manages the process of transferring to TCP/IP and returning control to the application program when EZASOKET processing is complete.

When the IP CICS sockets configuration option is specified as OTE=NO, then the IP CICS sockets task-related user exit operates as a quasi-reentrant task-related user exit program. It runs on the CICS main TCB (the QR TCB) and uses its own MVS™ subtask TCB to process the EZASOKET request. However, when the IP CICS sockets configuration option is specified as OTE=YES, then the IP CICS socket interface exploits the Open Transaction Environment (OTE) to enable the IP CICS sockets task-related user exit to invoke and return from TCP/IP without switching TCBs. In the OTE, the IP CICS sockets task-related user exit operates as a threadsafe and open API task-related user exit program; it is automatically enabled using the OPENAPI option on the ENABLE PROGRAM command during connection processing. This enables it to receive control on an open L8 mode TCB.

In the OTE, if the user application program that invoked the task-related user exit conforms to threadsafe coding conventions and is defined to CICS as threadsafe, it can also run on the L8 TCB. Before its first EZASOKET request, the application program runs on the CICS main TCB, the QR TCB. When it makes an EZASOKET request and invokes the task-related user exit, control passes to the L8 TCB, and IP CICS sockets processing is carried out. On return from TCP/IP, if the application program is threadsafe, it continues to run on the L8 TCB.

When the correct conditions are met, the use of open TCBs for IP CICS sockets applications decreases usage of the QR TCB, and avoids TCB switching. An ideal IP CICS sockets application program for the open transaction environment is a threadsafe program, containing only threadsafe EXEC CICS commands, and using only threadsafe user exit programs. An application like this moves to an L8 TCB when it makes its first EZASOKET request, and then continues to run on an L8 TCB through any amount of IP CICS sockets requests and application code, requiring no TCB switching. This situation produces a significant performance improvement where an application program issues multiple EZASOKET calls. The gains are also significant when making a DB2® request because the DB2 task-related user exit also operates as threadsafe and exploits the open transaction environment. If the application program does not issue many EZASOKET calls, the performance benefits might not be as significant.

If the execution of a user application involves any actions that are not threadsafe, CICS switches back to the QR TCB. Such actions are non-threadsafe CICS requests issued by the program, the use of non-threadsafe task-related user exits, and the involvement of non-threadsafe global user exits. Switching back and forth between the open TCB and the QR TCB is detrimental to the application's performance.

See http://www-01.ibm.com/software/htp/cics/library/ for information about how to make application programs and user exit programs threadsafe. By defining a program to CICS as threadsafe, you are specifying that only the application logic is threadsafe, not that all the EXEC CICS commands included in the program are threadsafe. CICS can ensure that EXEC CICS commands are processed safely by switching to the QR TCB for those commands not yet converted that must be quasi-reentrant. To permit your program to run on an open TCB, CICS requires you to verify that your application logic is threadsafe.

See http://www-01.ibm.com/software/htp/cics/library/ for more information about the EXEC CICS commands that are threadsafe and do not involve TCB switching.

If a user application program in the open transaction environment is not threadsafe, the IP CICS sockets task-related user exit still runs on an L8 TCB, but the application program runs on the QR TCB throughout the task. Every time the program makes an EZASOKET request, CICS switches from the QR TCB to the L8 TCB and back again, so the performance benefits of the open transaction environment are negated.

Table 1 shows what happens when application programs with different concurrency attributes invoke the IP CICS sockets task-related user exit.

If you define a program with CONCURRENCY(THREADSAFE), then all routines that are statically or dynamically called from that program (for example, COBOL routines) must also be coded to threadsafe standards.

When an EXEC CICS LINK command is used to link from one program to another, the program link stack level is incremented. However, a routine that is statically called, or dynamically called, does not involve passing through the CICS command level interface, and does not cause the program link stack level to be incremented. With COBOL routines, for a static call, a simple branch and link is used when an address is resolved by the Linkage Editor. For a dynamic call, although there is a program definition involved, this is required only so Language Environment® can load the program. After the load, a simple branch and link is executed. When a routine is called by either of these methods, CICS does not regard this as a change of program. The program that called the routine is still considered to be executing, and the program definition for that program is still considered to be the current one.

If the program definition for the calling program states CONCURRENCY(THREADSAFE), then the called routine must also comply with this specification. Programs with the CONCURRENCY(THREADSAFE) attribute remain on an open API TCB until they return from a EZASOKET call, and this is not appropriate for a program that is not threadsafe. For example, consider the situation where the initial program of a transaction, program A, issues a dynamic call to program B, which is a COBOL routine. Because the CICS command level interface was not involved, CICS is unaware of the call to program B, and considers the current program to be program A. Program B further issues a EZASOKET call. On return from the EZASOKET call, CICS needs to determine whether the program can remain on the open API TCB, or whether the program must switch back to the QR TCB to ensure threadsafe processing. To do this, CICS examines the CONCURRENCY attribute of what it considers to be the current program, which is program A. If program A is defined as CONCURRENCY(THREADSAFE), then CICS allows processing to continue on the open API TCB. In fact program B is executing, so if processing is to continue safely, program B must be coded to threadsafe standards.

In summary, to gain the performance benefits of the open transaction environment:

1. IP CICS sockets must be configured to use the open transaction environment by the use of the OTE=YES configuration option.
2. FORCEQR must be set to NO.
3. The IP CICS sockets application must have threadsafe application logic (that is, the native language code in between the EXEC CICS commands must be threadsafe), use only threadsafe EXEC CICS commands, and be defined to CICS as threadsafe. If the application program is not defined as threadsafe, and so must operate on the CICS QR TCB, TCB switching occurs for every EZASOKET request, even if the task-related user exit is running on an open TCB. If the application program is defined as threadsafe but uses non-threadsafe EXEC CICS commands, TCB switching occurs for every non-threadsafe EXEC CICS commands.
4. The IP CICS sockets application must use only threadsafe task-related user exits and global user exits. If any non-threadsafe exits are used, this forces a switch back to the QR TCB. If application programs are defined to CICS as CONCURRENCY(THREADSAFE) and they contain non-threadsafe code, unpredictable results can occur.