Enhancements for Open Transaction Environment

1. Enhancements for Open Transaction Environment Takahiro Ishiwatari ishwtari@jp.ibm.com

2. Enhancements for OTE - Notes This presentation will describe the capabilities provided by Open Transaction Environment (OTE) Stage 3 in CICS Transaction Server 3.1.

3. Acknowledgements • The following are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM, CICS, CICS/ESA, CICS TS, CICS Transaction Server, DB2, MQSeries, OS/390, S/390, WebSphere, z/OS, zSeries, Parallel Sysplex. • Java, and all Java-based trademarks and logos, are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. • Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. • Other company, product, and service names and logos may be trademarks or service marks of others.

4. Enhancements for OTE - Notes This page intentionally left blank.

5. Agenda • OTE Stage 3 • Full OTE exploitation • XPLink for C/C++ applications • New threadsafe APIs

6. Enhancements for OTE - Notes There are three major enhancements in the Open Transaction Environment area. First is the full OTE exploitation, which allows non CICS-DB2 applications to run on open TCBs. The second is for C/C++ applications using the XPLink compile option. It is implemented by executing those programs on open TCBs. The last is support for additional threadsafe APIs.

7. Open Transaction Environment • Enables applications to run on their own TCB • Benefits • Possible throughput increase by • utilizing multiple processor environments • reducing CPU costs with fewer TCB switches in CICS-DB2 applications • relieving QR TCB from CPU intensive workloads • reduce contention on QR TCB

8. Enhancements for OTE - Notes OTE enables applications to run on their own TCBs other than the main CICS TCB (the quasi-reentrant or QR TCB). These TCBs are called open TCBs. Using open TCBs, transactions can execute concurrently with other transactions, utilizing multiple processor environments. It can reduce TCB switches in CICS-DB2 applications lowering CPU costs. CPU intensive workloads can be moved off of the QR TCB, reducing contention of the QR TCB. The capabilities of OTE can provide improved performance of the CICS system.

9. History of Open Transaction Environment • Stage 1 : CICS TS V1.3 • Java application running on open TCBs • JVM programs on J8 TCBs • executed in CICS key (key-8) • Java program objects (HPJ programs)on H8 TCBs • some CICS APIs made threadsafe • Stage 2 : CICS TS V2 • CICS-DB2 applications can run on open TCBs • COBOL, PL/I, C/C++, Assembler programs with DB2 access • runs on L8 TCBs • move to L8 TCB initiated by SQL requests • CICS-DB2 attachment exploiting OPENAPI support for TRUEs • CONCURRENCY(THREADSAFE) in PROGRAM definition • J9 TCBs for USER key java applications • more APIs made threadsafe

10. Enhancements for OTE - Notes The OTE has been implemented in stages. It was first introduced in CICS TS 1.3. It allowed java applications run on their own TCB. Java transactions which run on a Java virtual machine uses J8 TCBs. Subsequently, support was added for hot-pooled HPJ programs (programs compiled from byte code to executable code with the High Performance Java compiler) to run on H8 TCBs. In CICS TS 1.3, some of the APIs and SPIs were made threadsafe, and enabled those commands to execute on open TCBs. In CICS TS V2.2, OPENAPI support for task related user exits (TRUEs) were added. CICS-DB2 attachment exploited this support, enabling CICS-DB2 applications to run on open TCBs. When an program issued an EXEC SQL request, it would switch to L8 TCBs and execute the SQL request. After completion of the SQL request, the program will stay on the L8 TCB and execute its logic. If another SQL request is issued, there will be no TCB switching. It will return to the QR TCB when the program issues a non-threadsafe EXEC CICS command. The CONCURRENCY(THREADSAFE) in the program definition indicates that the program is eligible for execution on the open TCB. In CICS TS V2.3, EXECKEY(USER) was honored for java applications. Those programs would run on J9 TCBs. Additionally, EXEC CICS ASKTIME, FORMATTIME and DOCUMENT APIs were made threadsafe.

11. TCB switching in CICS TS V2 QR TCB L8 TCB QR TCB L8 TCB Program start Program start EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS threadsafe EXEC SQL EXEC SQL EXEC SQL EXEC SQL EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS non-threadsafe EXEC CICS non-threadsafe EXEC SQL EXEC SQL EXEC SQL EXEC SQL EXEC RETURN EXEC RETURN CONCURRENCY(THREADSAFE) CONCURRENCY(QUASIRENT)

12. Enhancements for OTE - Notes This is an example of the TCB switching in CICS TS V2. When the program is defined as CONCURRENCY(QUASIRENT), the program will start on the QR TCB and run until an EXEC SQL command. The program will switch to an L8 TCB, execute the SQL request and then return back to the QR TCB. Each SQL request will have two TCB switches. When the program is defined as CONCURRENCY(THREADSAFE), the program will start on the QR TCB and run until an EXEC SQL command. The program will switch to an L8 TCB, execute the SQL request but will stay on the L8 TCB after completion. Application logic will run on the L8 TCB and when there is another SQL request there will be no TCB switching. Threadsafe EXEC CICS command will run on L8 TCB. Issuing non-threadsafe EXEC CICS commands will take the application back to the QR TCB. It will stay on the QR TCB until another SQL request is issued, and then switch to the L8 TCB again. With CONCURRENCY(THREADSAFE), the number or TCB switches will decrease saving processor time, and providing increased performance.

13. Threadsafe programs • capable of being invoked on multiple TCBs concurrently • uses serialization techniques to access shared resource • serialization techniques in CICS • Compare and Swap instruction • Issue ENQ on the resource • LINK to a QUASIRENT program • use TRANCLASS definition MAXACTIVE(1) • Preparing for threadsafe applications • Compile and link-edit with RENT option • Run DFHEISUP to detect possible unthreadsafe resource usage • DFHEIDTH • EXTRACT EXIT GASET, ADDRESS CWA, GETMAIN SHARED • DFHEIDNT • use of non-threadsafe APIs • Serialize access to shared resource • Check that Exits and URMs are also threadsafe • For more information • Redbook : Threadsafe Considerations for CICS (SG24-6351)

14. Enhancements for OTE - Notes • In order to take advantage of OTE, the programs must be threadsafe. Threadsafe programs are programs that are capable of being invoked on multiple TCBs concurrently. When the program accesses shared resource such as CWA and GETMAIN SHARED, the program needs to be sure that those resources are accessed in a serialized manner. If they are not serialized, there will be a risk of losing integrity. Some of the serialization techniques in CICS are using compare and swap instructions, issuing EXEC CICS ENQ before accessing the resource, LINK to a QUASIRENT program, and using MAXACTIVE(1) in the TRANCLASS definition. • To make applications threadsafe you should - Compile and link-edit with the RENT option - Run the load module scanner to detect possible non-threadsafe resource usage - Serialize access to shared resource - Check that exits and URMs are also threadsafe • Redbook “Threadsafe considerations for CICS” has detailed information about exploiting OTE and making applications threadsafe.

15. CICS TS V3.1 : Full OTE exploitation (Stage 3) • Applications can run on open TCBs from the start • Benefits • More application logic to move off of QR TCB, exploit OTE • non CICS-DB2 applications • CPU intensive applications • Application logic before the first SQL call • TCB switch to L8 or L9 on invocation • New L9 TCB for USER key programs • L8, L9 TCBs controlled by MAXOPENTCBS SIT parameter • use of non threadsafe APIs will switch to QR TCB and back • switch back from QR TCB on completion of request • New API attribute in PROGRAM definition • API ( CICSAPI | OPENAPI ) • CICSAPI : program starts on QR TCB • OPENAPI : program starts on L8 or L9 TCB • OPENAPI implies CONCURRENCY(THREADSAFE) • Applications need to be threadsafe! • FORCEQR will not effect OPENAPI programs

16. Enhancements for OTE - Notes With OTE Stage 3, you can make applications run on open TCBs from the start. This will enable more application logic to move off of the QR TCB, such as non-CICS-DB2 applications, CICS-DB2 applications that have a large amount of work before the first SQL, applications that are CPU intensive. The TCBs that are used will be L8 or L9 TCB. L8 TCB, which was introduced in CICS TS V2.2, will run programs that are defined as CICS key. L9 TCB, which is a new TCB, will run programs that are defined as USER key. Both L8 and L9 TCBs will be controlled in the same TCB pool, and the maximum number of TCBs in the pool can be specified with MAXOPENTCBS parameter in the SIT. The difference with previous open TCB usage is that when the program is running on L8 or L9 TCB and issues a non-threadsafe API, CICS will switch to the QR TCB to execute the non-threadsafe API, and when the API processing is complete the program will be switched back to the L8 or L9 TCB which it was running on. To enable this, there will be a new attribute in the PROGRAM definition called API. It can have values of CICSAPI or OPENAPI. For API(CICSAPI), the program will start on the QR TCB. The processing will be the same as in previous releases. For API(OPENAPI), the program will start on L8 or L9 TCB depending on the EXECKEY setting. Specifying OPENAPI will enforce CONCURRENCY(THREADSAFE). Applications running with OPENAPI must be coded to threadsafe standards. The FORCEQR=YES specification in SIT will not have an effect on OPENAPI programs.

17. TCB switching enhancements in CICS TS V3 QR TCB L8 TCB QR TCB L8 TCB Program start Program start EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS threadsafe EXEC SQL EXEC SQL EXEC SQL EXEC SQL EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS non-threadsafe EXEC CICS non-threadsafe EXEC CICS threadsafe EXEC SQL EXEC SQL EXEC SQL EXEC SQL EXEC RETURN EXEC RETURN THREADSAFE with CICSAPI THREADSAFE with OPENAPI

18. Enhancements for OTE - Notes This shows the TCB switching with OTE stage 3. The left diagram shows the TCB switching with CONCURRENCY(THREADSAFE) and API(CICSAPI). This is the same as the CONCURRENCY(THREADSAFE) in previous releases. The right diagram shows the TCB switching with CONCURRENCY(THREADSAFE) and API(OPENAPI). The program will switch to L8 or L9 TCB on invocation, in this case L8 TCB, meaning the program specified EXECKEY(CICS). Threadsafe APIs will run on the L8 TCB, and SQL requests will also run on the L8 TCB without having any TCB switching. When the program issues a non threadsafe API, the TCB will switch to QR TCB and process the API. On completion of the API the TCB will be switched back to the L8 TCB.

19. Considerations • Use of non-CICS APIs • considered to be unsupported • “Use of other (non CICS) APIs within CICS is entirely at the discretion and risk of the user. No testing of other (non CICS) APIs within CICS has been undertaken and use of such APIs is not supported by IBM Service. ” (Release Guide) • TCB switching • SQL requests will process on L8 TCBs • For EXECKEY(CICS) programs • no TCB switching will occur • For EXECKEY(USER) programs • TCB will switch from L9 to L8 • will return to L9 on completion of the SQL request • Non-threadsafe API calls • many non-threadsafe calls may degrade performance when running with OPENAPI • compared to CICSAPI threadsafe programs

20. Enhancements for OTE - Notes Use of other (non CICS) APIs in OPENAPI programs is possible. This is because, if an open TCB is blocked by an operating system wait, then only the single application is affected not the whole of CICS. Such OPENAPI programs are not permitted to execute on the QR TCB precisely because of this risk of blocking the TCB by an operating system wait and thus affecting the whole of CICS. Nevertheless OPENAPI programs still have obligations to the CICS system as a whole. See Obligations of OPENAPI programs in the Application Programming Guide. Use of other (non CICS) APIs within CICS is entirely at the discretion and risk of the user. No testing of other (non CICS) APIs within CICS has been undertaken and use of such APIs is not supported by IBM Service. When an application issues an SQL request, the TCB switching activity will depend on whether the program is running on L8 or L9 TCB. When a program is defined as EXECKEY(CICS), the program will be running on L8 TCB and SQL requests will be executed on the same L8 TCB. There will be no TCB switching. When a program is defined as EXECKEY(USER), the program will be running on L9 TCB. SQL requests need to execute on L8 TCBs, thus there will be a TCB switch from L9 TCB to L8 TCB. On completion of the SQL request, the TCB will switch back to L9 TCB. Non threadsafe APIs will need to execute on the QR TCB and will have 2 TCB switches for each request. This will mean that if there are many non threadsafe API calls, it may be better to specify CICSAPI rather than OPENAPI, to prevent having too many TCB switches and degrading performance.

21. TCB switching – USER key programs L8 TCB QR TCB L9 TCB Program start EXEC CICS non-threadsafe EXEC CICS threadsafe EXEC SQL EXEC SQL EXEC CICS threadsafe EXEC CICS non-threadsafe EXEC SQL EXEC SQL EXEC RETURN

22. Enhancements for OTE - Notes This is an example of an OPENAPI program running with EXECKEY(USER). The program will start on an L9 TCB. Each non-threadsafe API and SQL request will have a pair of TCB switches, non-threadsafe APIs switching to/from QR TCB, SQL reqeusts switching to/from L8 TCB.

23. TCB switching – many non-threadsafe commands QR TCB L8 TCB QR TCB L8 TCB Program start Program start EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS non-threadsafe EXEC CICS non-threadsafe EXEC SQL EXEC SQL EXEC SQL EXEC SQL EXEC CICS threadsafe EXEC CICS threadsafe EXEC CICS non-threadsafe EXEC CICS non-threadsafe EXEC CICS non-threadsafe EXEC CICS non-threadsafe EXEC SQL EXEC SQL EXEC SQL EXEC SQL EXEC RETURN EXEC RETURN THREADSAFE with CICSAPI THREADSAFE with OPENAPI

24. Enhancements for OTE - Notes This shows an example of having many non threadsafe APIs in the program. With CICSAPI, there are only three TCB switches before EXEC CICS RETURN. With OPENAPI, although the program runs on L8 TCB and SQL request will have no TCB switches, the non threadsafe APIs will incur two TCB swiches each, and will have a total of six TCB switches. The increase in TCB switches will require more processor time to execute the program.

25. Decisions for OPENAPI • Candidates for CICSAPI with THREADSAFE • SQL programs with some/many non-threadsafe APIs • SQL programs with USER key • Candidates for OPENAPI with THREADSAFE • programs with threadsafe APIs only • SQL programs with CICS key • CPU intensive programs

26. Enhancements for OTE - Notes As we have seen in previous pages, not all programs benefit from specifying OPENAPI. CICS-DB2 programs that have some or many non threadsafe API is likely to perform better with CICSAPI. CICS-DB2 programs that have EXECKEY(USER) is also likely to perform better with CICSAPI because it will have 2 TCB switches for each SQL requests. A good candidate for OPENAPI are programs that doesn’t contain any non threadsafe APIs, CICS-DB2 programs that have EXECKEY(CICS) and programs that are CPU intensive.

27. Other changes • CEMT/SPI • New APIST keyword • INQUIRE PROGRAM • CREATE PROGRAM • Exits • New indicator for L9 TCB • for parameter UEPGIND in GLUEs, UEPTIND in TRUEs • XPI • INQUIRE_PROGRAM returns a value for the API attribute • Monitoring and statistics • monitoring field L9CPUT • CPU time on L9 TCB • monitoring field DSCHMDLY • wait time after a Dispatcher change TCB mode request • L9 TCB information in Dispatcher stats

28. Enhancements for OTE - Notes The INQUIRE PROGRAM command will now return a new attribute APIST, identifying the API attribute setting in the PROGRAM definition. Similarly, the CREATE PROGRAM command will also have a new attribute APIST. There is a change in the exit parameter list. The UEPGIND parameter in global user exits and UEPTIND parameter in task related user exits will have a new indicator for L9 TCB. For the exit programming interface (XPI), a new API attribute will be returned with INQUIRE_PROGRAM function. There is a new monitoring field L9CPUT to record CPU usage on the L9 TCB. DSCHMDLY will include dispatch wait time after TCB switches to/from L9 TCBs. Dispatcher statistics will also have information about L9 TCBs.

29. Sample DFH$MOLS report PROGRAM with CONCURRENCY(THREADSAFE) API(OPENAPI) EXECKEY(USER) issuing threadsafe & non- threadsafe & SQL commands DFHTASK C001 TRAN D6E3C5F3 OTE3 DFHTERM C002 TERM F0F0F1F6 0016 DFHCICS C089 USERID C3C9C3E2 E4E2C5D9 CICSUSER DFHTASK C004 TTYPE E3D60000 TO DFHCICS T005 START BC69722DD667AD0E 2005/01/13 03:52:51.113594 DFHCICS T006 STOP BC69722DF0DDC24E 2005/01/13 03:52:51.221980 … DFHDATA A180 DB2REQCT 00000003 3 DFHTASK A251 TCBATTCT 00000001 1 DFHTASK A252 DSTCBHWM 00000002 2 ... DFHTASK S007 USRDISPT 0000191D00000016 00:00:00.10286 22 DFHTASK S008 USRCPUT 0000011600000016 00:00:00.00444 22 DFHTASK S014 SUSPTIME 0000015900000016 00:00:00.00552 22 DFHTASK S102 DISPWTT 0000002900000015 00:00:00.00065 21 DFHTASK S255 QRDISPT 000001C00000000A 00:00:00.00716 10 DFHTASK S256 QRCPUT 000000310000000A 00:00:00.00078 10 DFHTASK S257 MSDISPT 000005CF00000001 00:00:00.02379 1 DFHTASK S258 MSCPUT 0000002F00000001 00:00:00.00075 1 DFHTASK S269 RODISPT 000005CF00000001 00:00:00.02379 1 DFHTASK S270 ROCPUT 0000002F00000001 00:00:00.00075 1 DFHTASK S262 KY8DISPT 000010DF00000005 00:00:00.06910 5 DFHTASK S263 KY8CPUT 0000009600000005 00:00:00.00240 5 DFHTASK S264 KY9DISPT 000000AF00000006 00:00:00.00280 6 DFHTASK S265 KY9CPUT 0000002000000006 00:00:00.00051 6 DFHTASK S259 L8CPUT 0000009600000005 00:00:00.00240 5 DFHTASK S266 L9CPUT 0000002000000006 00:00:00.00051 6 ... DFHTASK S249 QRMODDLY 0000000C00000009 00:00:00.00019 9 ... DFHTASK S247 DSCHMDLY 0000003200000012 00:00:00.00080 18 … DFHTASK S170 RMITIME 000010DD00000007 00:00:00.06907 7 ... DFHSYNC S173 SYNCTIME 0000033F00000001 00:00:00.01329 1 Number of open TCBs CPU time for QR TCB CPU time for L8 TCB CPU time for L9 TCB Dispatch wait after TCB switch

30. Enhancements for OTE - Notes This shows an example output of DFH$MOLS, for a transaction running with OPENAPI and EXECKEY(USER). The transaction issues both threadsafe and non-threadsafe commands and SQL request. You can see that both L8 and L9 TCBs are being used.

31. XPLink • Extra Performance Linkage (XPLink) • introduced in OS/390 V2.10 • provides high performance subroutine call and return mechanism • feature of z/OS • supported by C/C++ compiler of z/OS • Specified by C/C++ compiler option XPLINK • Previously not supported in CICS • documents on XPLink • Redbook: XPLink: OS/390 Extra Performance Linkage (SG24-5991) • z/OS C/C++ Programming Guide (SC09-4765)

32. Enhancements for OTE - Notes Extra performance linkage (XPLink), provides a highly optimized subroutine call and return mechanism. It is a feature of z/OS, and is supported by the C/C++ compiler. The traditional z/OS linkage was not designed to handle a large number of function calls with a small function body; the overhead of function calling is relatively expensive. XPLink was designed to bring performance improvement opportunities to applications that are call-intensive with a small function body, typical of the newer workloads written in C and C++ being ported to z/OS. XPLink achieves this by changing register conventions and the layout of the stack. Using XPLink, it will increase performance for C/C++ applications that have are call intensive. It is enabled by specifying the XPLINK compiler option in C/C++. Redbook “XPlink: OS/390 Extra Performance Linkage” provides detailed information about this feature. The C/C++ Programming Guide is also a good source for information.

33. XPLink support in CICS TS V3.1 • Allows C/C++ applications to be compiled with XPLINK option • benefit from the high performance linkage • common modules or DLLs shared by CICS, Batch, USS • fully utilize the C++ Standard Template Library • XPLink C/C++ applications will run on open TCB • Benefits • Move C/C++ applications off of QR TCB, exploit OTE • New X8 and X9 TCB introduced • MAXXPTCBS in SIT to control maximum number • FORCEQR will not effect X8/X9 TCBs • Application needs to be threadsafe • must specify CONCURRENCY(THREADSAFE) in PROGRAM definition

34. Enhancements for OTE - Notes CICS TS V3.1 enables the use of XPLink in C/C++ applicatoins. It can increase performance for C/C++ applications running in CICS. It enables CICS to fuly utilize the C++ standard template library and programs can be shared or reused between USS and batch environments. XPLink support in CICS exploits the Open Transaction Environment. These applications will run on their own open TCB. X8 TCB is used for CICS key XPLink applications and X9 TCB is used for USER key XPlink applications. The X8 and X9 TCBs will be managed in a TCB pool called XP TCB pool. The maximum number of TCBs can be controlled with the MAXXPTCBS parameter in the SIT. The FORCEQR=YES in SIT will not effect XPLink programs. C/C++ applications with XPlink needs to be threadsafe, and CONCURRENCY(THREADSAFE) is required in the program definition.

35. Characteristics of XPLink in CICS • C/C++ programs with XPLink signatures will start on X8 / X9 TCBs • depending on the EXECKEY settings • XPLink uses Batch LE • LE enclave for each TCB • Storage are still allocated from CICS storage • DFHAPXPO can be used to change runtime options • TCB switching will occur when • using non-threadsafe CICS APIs • issuing SQL calls • LINK to a different program

36. Enhancements for OTE - Notes XPLink programs will have a signature that indicates that it has been compiled with the XPLINK option. When CICS recognizes the program as XPLink, it will start the program on X8 or X9 TCB, depending on the EXEC key settings. There will be no need to issue SQL requests to move to the open TCB. The runtime will be batch LE, much like the Java programs running on J8 and J9 TCBs. An LE enclave will be created for each X8 and X9 TCB, although, the storage for XPlink applications will be allocated from EDSA instead of MVS storage. The LE runtime options are predefine, but user replaceable module DFHAPXPO allows users to override some of the options. There will be TCB switching in the following cases. - Using non-threadsafe API calls - Issuing SQL calls - LINKing to a different program, including other XPLink programs

37. TCB switching L8 TCB QR TCB X8 TCB Program start EXEC CICS non-threadsafe EXEC CICS threadsafe EXEC SQL EXEC SQL EXEC CICS threadsafe EXEC CICS non-threadsafe EXEC SQL EXEC SQL EXEC RETURN

38. Enhancements for OTE - Notes This diagram shows the TCB switching for XPLink programs. XPLink programs will start on X8 or X9 TCB. Non-threadsafe commands will switch to the QR TCB, on completion it will swich back to the X8 or X9 TCB. Threadsafe commands will continue to run on the X8 or X9 TCB. For SQL requests, it will switch to L8 TCBs and return back on completion.

39. Characteristics of XPLink in CICS • Programming Considerations • CICS C++ Foundation classes • provides non-XPLink version • Multithreading • should not make use of multithreading such as fork() or pthreads • considered to be unsupported • exception handling • HANDLE ABEND PROGRAM is supported • EXEC CICS LINK • if target is XPLink program, • run on a new X8 or X9 TCB - nesting of LINKs to XPLink programs may deplete the TCB pool • If target is non-XPLink program, • run on QR or L8/L9 TCB - start on QR TCB if API(CICSAPI) / CONCURRENCY(THREADSAFE) - run on L8/L9 TCB if API(OPENAPI)

40. Enhancements for OTE - Notes • The CICS C++ foundation class is the C++ class equivalent of EXEC CICS commands. There will only be a non-XPLink version of the foundation class. It should be noted that calling non-XPLink classes from an XPLink program, will not have the high performance subroutine call advantage. Also, calling XPLink program from a non-XPLink program is not supported • Applications should not make use of multithreading techniques such as fork(), pthreads, etc. They are considered to be unsupported by CICS. • Considerations for exception handling is the same for all C/C++ programs. Except for EXEC CICS HANDLE ABEND PROGRAM command, all EXEC CICS HANDLE commands are not supported. • When LINKing to another XPLink program, the target program will not run on the same X8 or X9 TCB but will run on a different X8 or X9 TCB. This means that nesting LINKs for XPLink programs could deplete the TCB pool. • for non-XPlink programs including COBOL, PL/I and assemblers, those will switch and run on the QR TCB when CICSAPI is specified, or it will run to L8/L9 TCB when OPENAPI is specified.

41. Preparing XPLink applications • Steps for XPLink • Develop threadsafe C/C++ applications • Compile with compiler option XPLINK • Sample procedures provided • DFHYITFL, DFHYITGL in SDFHPROC • Output dataset needs to be PDSE • Define and install program as CONCURRENCY(THREADSAFE) • Other considerations • Exits, URMs,

42. Enhancements for OTE - Notes To prepare XPLink C/C++ applications, first the program needs to be developed strictly adhering to threadsafe programming principles and techniques. It will then be compiled using the XPLINK compiler option turned on. There are sample procedures in SDFHPROC to translate/compile/link-edit XPLink programs. DFHYITFL is for C programs, DFHYITGL is for C++ programs. The output module needs to be in PDSE library. Lastly, the PROGRAM definition needs to be specified and installed into CICS as CONCURRENCY(THREADSAFE).

43. other changes • CEMT/SPI • INQUIRE PROGRAM • new XPLINK cvda-value returned on RUNTIME attribute • INQUIRE DISPATCHER • new attributes MAXXPTCBS, ACTXPTCBS • Exits • XPCTA will be passed a new flag stating that resume is not supported • XPCFTCH will be passed a new flag stating that an alternate entry point is not supported • Monitoring & Statistics • Monitoring fields X8CPUT, X9CPUT, MAXXTDLY • CPU time on X8, X9 TCB, TCB wait by MAXXPTCBS • monitoring field DSCHMDLY • wait time after a Dispatcher change TCB mode request • X8/X9 TCB information in Dispatcher stats

44. Enhancements for OTE - Notes • INQUIRE PROGRAM will return XPLINK on the RUNTIME attribute if it is an XPlink program. • INQUIRE DISPATCHER will return the maximum number of X8/X9 TCBs allowed on MAXXPTCBS attribute, and the actual TCB count will be returned on ACTXPTCBS attribute. The MAXXPTCBS can be changed using the SET DISPATCHER command. • Exit XPCTA which is invoked on abends will have a new flag passed which will indicate that the program is an XPLink program and setting resume address is not supported. • Exit XPCFTCH which is used to change the program entry point before starting the program, will have a new flag passed which will indicate that the program is an XPLink program and setting alternate entry points is not supported. • There are new monitoring fields X8CPUT and X9CPUT to record CPU usage on the X8 and X9 TCB. DSCHMDLY will include dispatch wait time after TCB switches to/from X8 and X9 TCBs. • Dispatcher statistics will also have information about X8 and X9 TCBs.

45. Statistics sample - CICS TCB Mode Statistics + ________________________ 0 TCB TCB < TCBs Attached > <- TCBs In Use -> TCB Detached Detached Detached Detached TCB TCB Mode Open Pool Current Peak Current Peak Attaches Unclean Stolen Excess Other Steals Mismatches + ________________________________________________________________________________________________________________________________ 0 QR No N/A 1 1 1 1 0 0 0 0 0 0 0 RO No N/A 1 1 1 1 0 0 0 0 0 0 0 CO Unk N/A 0 0 0 0 0 0 0 0 0 0 0 SZ Unk N/A 0 0 0 0 0 0 0 0 0 0 0 RP Unk N/A 0 0 0 0 0 0 0 0 0 0 0 FO No N/A 1 1 1 1 0 0 0 0 0 0 0 SL No N/A 1 1 1 1 0 0 0 0 0 0 0 SO No N/A 1 1 1 1 0 0 0 0 0 0 0 SP No N/A 1 1 1 1 0 0 0 0 0 0 0 D2 No N/A 1 1 1 1 0 0 0 0 0 0 0 JM No N/A 0 0 0 0 0 0 0 0 0 0 0 S8 Unk N/A 0 0 0 0 0 0 0 0 0 0 0 L8 Yes Open 1 1 0 1 0 0 0 0 0 0 0 L9 Yes Open 1 1 0 1 1 0 0 0 0 0 0 J8 Unk N/A 0 0 0 0 0 0 0 0 0 0 0 J9 Unk N/A 0 0 0 0 0 0 0 0 0 0 0 X8 Yes XP 1 1 0 1 1 0 0 0 0 0 0 X9 Unk N/A 0 0 0 0 0 0 0 0 0 0 0 + ________________________________________________________________________________________________________________________________ Totals 10 7 2 0 0 0 0 0 0 - TCB < TCBs Attached > TCB Attach MVS Accum Time Accum Time Accum CPU Mode Current Peak Attaches Failures Waits in MVS wait Dispatched Time / TCB + ___________________________________________________________________________________________________ 0 QR 1 1 0 0 49754 12:52:54.2141 00:00:05.8767 00:00:05.6531 RO 1 1 0 0 16 18:38:00.5042 00:00:00.6680 00:00:00.0303 CO 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 SZ 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 RP 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 FO 1 1 0 0 41 20:43:12.6051 00:00:01.8068 00:00:00.0594 SL 1 1 0 0 25 13:06:25.9195 00:00:00.0004 00:00:00.0005 SO 1 1 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 SP 1 1 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 D2 1 1 0 0 1539 12:53:15.5380 00:00:00.0182 00:00:00.0198 JM 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 S8 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 L8 1 1 0 0 13 20:27:06.4818 00:00:00.0799 00:00:00.0000 L9 1 1 1 0 6 00:00:00.0628 00:00:00.0031 00:00:00.0000 J8 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 J9 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 X8 1 1 1 0 21 00:00:00.5228 00:00:00.0218 00:00:00.0000 X9 0 0 0 0 0 00:00:00.0000 00:00:00.0000 00:00:00.0000 + ___________________________________________________________________________________________________ Totals 10

46. Statistics sample… - CICS TCB Pool Statistics + ________________________ 0 TCB Pool. . . . . . . . . . . . . . . . . . . . : OPEN 0 Current TCBs attached in this TCB Pool. . . . . : 2 Current TCBs in use in this TCB Pool. . . . . . : 0 Peak TCBs attached in this TCB Pool . . . . . . : 2 Peak TCBs in use in this TCB Pool . . . . . . . : 2 0 Max TCB Pool limit (MAXOPENTCBS). . . . . . . . : 10 Times at Max TCB Pool Limit (MAXOPENTCBS) . . . : 0 0 Total Requests delayed by Max TCB Pool Limit. . : 0 Total Number of TCB Mismatch waits. . . . . . . : 0 Total Max TCB Pool Limit delay time . . . . . . : 00:00:00.0000 Total TCB Mismatch wait time. . . . . . . . . . : 00:00:00.0000 0 Current Requests delayed by Max TCB Pool Limit. : 0 Current TCB Mismatch waits. . . . . . . . . . . : 0 Current Max TCB Pool Limit delay time . . . . . : 00:00:00.0000 Current TCB Mismatch wait time. . . . . . . . . : 00:00:00.0000 Peak Requests delayed by Max TCB Pool Limit . . : 0 Peak TCB Mismatch waits . . . . . . . . . . . . : 0 0 Requests Delayed by MVS storage constraint. . . : 0 Total MVS storage constraint delay time . . . . : 00:00:00.0000 +____________________________________________________________________________________________________________________________________ 0 TCB Pool. . . . . . . . . . . . . . . . . . . . : XP 0 Current TCBs attached in this TCB Pool. . . . . : 1 Current TCBs in use in this TCB Pool. . . . . . : 0 Peak TCBs attached in this TCB Pool . . . . . . : 1 Peak TCBs in use in this TCB Pool . . . . . . . : 1 0 Max TCB Pool limit (MAXXPTCBS). . . . . . . . . : 10 Times at Max TCB Pool Limit (MAXXPTCBS) . . . . : 0 0 Total Requests delayed by Max TCB Pool Limit. . : 0 Total Number of TCB Mismatch waits. . . . . . . : 0 Total Max TCB Pool Limit delay time . . . . . . : 00:00:00.0000 Total TCB Mismatch wait time. . . . . . . . . . : 00:00:00.0000 0 Current Requests delayed by Max TCB Pool Limit. : 0 Current TCB Mismatch waits. . . . . . . . . . . : 0 Current Max TCB Pool Limit delay time . . . . . : 00:00:00.0000 Current TCB Mismatch wait time. . . . . . . . . : 00:00:00.0000 Peak Requests delayed by Max TCB Pool Limit . . : 0 Peak TCB Mismatch waits . . . . . . . . . . . . : 0 0 Requests Delayed by MVS storage constraint. . . : 0 Total MVS storage constraint delay time . . . . : 00:00:00.0000 0------------------------------------------------------------------------------------------------------------------------------------

47. New threadsafe commands • WEB API’s made threadsafe • Programs used in CICS Web Support • WEB READ • WEB WRITE • WEB SEND • WEB RECEIVE • WEB RETRIEVE • WEB STARTBROWSE • WEB READNEXT • WEB ENDBROWSE • WEB EXTRACT • DOCUMENT APIs were made threadsafe in CICS TS V2.3

48. Enhancements for OTE - Notes There are new threadsafe commands in CICS TS V3.1. All the EXEC CICS Web API commandshave been made threadsafe. These are WEB READ, WEB WRITE, WEB SEND, WEBRECEIVE, WEB RETRIEVE, WEB STARTBROWSE, WEB READNEXT, WEB ENDBROWSE, WEB EXTRACT, EXTRACT WEB, EXTRACT TCPIP, and EXTRACT CERTIFICATE. This removes the requirement for CICS to return to the QR TCB to execute these commands, so applications (both Java and non-Java) that use these commands should be able to obtain the performance improvements resulting from reduced TCB switching.

49. List of threadsafe APIs

50. Enhancements for OTE - Notes This is a list of threadsafe APIs and the releases it was made threadsafe.