CICS® Transaction Server for OS/390® IBM CICS Transaction Affinities Utility Guide Release 3 SC33-1777-02
CICS® Transaction Server for OS/390® IBM CICS Transaction Affinities Utility Guide Release 3 SC33-1777-02
Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page vii. Third edition (March 1999) This edition applies to Release 3 of CICS Transaction Server for OS/390, program number 5655-147, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product.
Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . viii Preface . . . . . . . . . . . . . . What this book is about . . . . . . . . Who this book is for. . . . . . . . . What you need to know to understand this How to use this book . . . . . . . . Determining if a publication is current . . Notes on terminology . . . . . . . . . . . . . . book . . . . . . . . . . . . . . . . . . . . Bibliography . . . . . . . . . . .
Creating the VSAM files . . . . . . . Estimating the size of the MVS data space Defining the VSAM files to CICS . . . . Tailoring your CICS startup job. . . . . Restarting your CICS region . . . . . Chapter 4. Running the Scanner Creating a summary report . . . Creating a detailed report . . . Contents of a detailed report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 21 22 23 23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reporter output . . . . . . . . . . . . . . . . . . . . . . . . 71 Scanner output . . . . . . . . . . . . . . . . . . . . . . . . 71 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 71 Appendix C. Useful tips when analyzing Transaction Affinities Utility reports . . . . . . . . . . . . . . . . . . . . . . . COBOL affinities . . . . . . . . . . . . . . . . . . . . . LOGON or SYSTEM when PCONV expected . . . . . . . . . . Unrecognized Transids . . . . . . . . . . . . . . . . . . . . . . . . . . .
vi CICS Transaction Affinities Utility Guide
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Programming License Agreement, or any equivalent agreement between us.
Preface What this book is about This book describes the affinity utility program. It explains what the utility does, how to install it, and how to run the various components of the utility. Who this book is for This book is for CICS system programmers who may be planning to use CICS dynamic routing for workload balancing, and need to determine whether any of the transactions in their CICS applications use programming techniques that cause inter-transaction affinity.
usually in step. However, due to the time required to print and distribute hardcopy books, the BookManager version is more likely to have had last-minute changes made to it before publication. Subsequent updates will probably be available in softcopy before they are available in hardcopy. This means that at any time from the availability of a release, softcopy versions should be regarded as the most up-to-date.
Bibliography CICS Transaction Server for OS/390 CICS CICS CICS CICS CICS CICS Transaction Transaction Transaction Transaction Transaction Transaction Server Server Server Server Server Server for for for for for for OS/390: Planning for Installation OS/390 Release Guide OS/390 Migration Guide OS/390 Installation Guide OS/390 Program Directory OS/390 Licensed Program Specification GC33-1789 GC34-5352 GC34-5353 GC33-1681 GI10-2506 GC33-1707 CICS books for CICS Transaction Server for OS/390 General CICS
CICSPlex SM books for CICS Transaction Server for OS/390 General CICSPlex SM Master Index CICSPlex SM Concepts and Planning CICSPlex SM User Interface Guide CICSPlex SM View Commands Reference Summary Administration and Management CICSPlex SM Administration CICSPlex SM Operations Views Reference CICSPlex SM Monitor Views Reference CICSPlex SM Managing Workloads CICSPlex SM Managing Resource Usage CICSPlex SM Managing Business Applications Programming CICSPlex SM Application Programming Guide CICSPlex SM App
Summary of changes The affinity utility program is an integral part of CICS Transaction Server for OS/390 and is for use only with the CICS Transaction Server for OS/390. To use the utility on CICS for MVS/ESA 4.1 and earlier releases of CICS, install the IBM CICS Transaction Affinities Utility MVS/ESA (program number 5696-582). Changes for the CICS Transaction Server for OS/390 Release 3 edition This book is based on the CICS Transaction Server for OS/390, release 2, edition, SC33-1777-01.
xiv CICS Transaction Affinities Utility Guide
Chapter 1. Introducing transaction affinities | | This chapter provides a brief introduction to the concept of transaction affinities and the associated CICS programming techniques, and highlights the significance of transaction affinities in a dynamic routing (known in previous releases of CICS as dynamic transaction routing) environment. For more information about transaction affinities, see the CICS Application Programming Guide.
| | CICS Transaction Server for OS/390 Release 3 introduces extended dynamic routing facilities, that allow the dynamic routing of: | | | v Transactions initiated at a terminal v EXEC CICS START requests that are associated with a terminal v EXEC CICS START requests that are not associated with a terminal | | | | | | | v Dynamic program link (DPL) requests that are received using: – The CICS Web support – The CICS Transaction Gateway – External CICS interface (EXCI) client programs – Any CICS client wo
The benefits of dynamic routing Being able to route transactions to target regions dynamically offers many benefits in an online transaction processing (OLTP) system. The user can achieve: v Improved performance v Improved availability v Simplified systems management What does dynamic routing cost? | | | | | | | | | Of course, the CICS-supplied code cannot determine where to send a transaction, this depends on your CICS environment and routing policies.
Note that, if you are dynamically routing non-terminal-related START and DPL requests, you should review your application to determine whether or not the application is suitable for dynamic routing. The Transaction Affinities Utility cannot detect affinities in these circumstances. | | | | Inter-transaction affinity Inter-transaction affinity is an affinity between two or more CICS transactions.
Userid A group of transactions where all instances of the transactions that are initiated from a terminal and executed on behalf of the same userid must execute in the same target region for the lifetime of the affinity. The affinity lifetime for userid relations can be pseudoconversation, signon, system, or permanent. | Affinity lifetimes | The affinity lifetime determines when the affinity is ended.
Safe programming techniques The programming techniques in the safe category are the use of: v The communication area (COMMAREA) on CICS RETURN commands v A terminal control table user area (TCTUA) optionally available for each terminal defined to CICS v ENQMODEL definitions to give sysplex-wide scope to ENQs and DEQs | Unsafe programming techniques The programming techniques in the unsafe category are the use of: v Long-life shared storage: – The common work area (CWA) – GETMAIN SHARED storage – Storage o
Protecting applications from one another The transaction isolation function offers storage protection between application programs, ensuring that one application does not accidentally overwrite the storage of another. Transaction isolation ensures that user-key programs1 execute in their own subspace, with appropriate access to any shared storage, or to CICS storage. Thus a user transaction is limited to its own view of the address space.
What next? This chapter has briefly summarized the techniques and commands that can cause transaction affinity. “Chapter 2. Introducing the Transaction Affinities Utility” on page 9 gives an overview of the Transaction Affinities Utility, and details of all the commands and command sequences that the Transaction Affinities Utility looks for.
Chapter 2.
Figure 2 shows the affinity utility program. Each of the four components is described in more detail in the rest of this chapter. AOR or TOR/AOR App li ca tion 1. Lo ad L ib ra ry 2. Scanner Detector User Repor t Collected Affi nity Data 4. 3. Builder Reporter Basi c Affi nity Transaction Groups Combined Affini ty Transaction Groups To CICSPlex SM Figure 2.
Commands detected by the Transaction Affinities Utility You can use the Transaction Affinities Utility to detect instances of the EXEC CICS commands listed in Table 1. Table 1.
The Scanner component The Scanner is a batch utility that scans a load module library to detect those programs in the library that issue EXEC CICS commands that may cause transaction affinity. It examines the individual object programs looking for patterns matching the argument zero 3 format for the commands in question. The Scanner detects the use of the EXEC CICS commands listed in Table 1 on page 11, and MVS POST requests.
Data space Collected affinity data XEIOUT TRUE XMEOUT CAFB XICEXP XBADEACT Exit programs CAFF CICS AOR or TOR/AOR User Collected affinity data Figure 3. Detector components You are recommended to run the Detector on stable CICS regions only. Do not apply maintenance to application programs while the Detector is running. Such maintenance may introduce or remove affinities, thus rendering collected data inaccurate.
v Log offs and sign offs by intercepting messages DFHSN1200, DFHZC3462, and DFHZC5966. v Completion of CICS BTS activities and processes. For more information, see “Appendix A. Details of what is detected” on page 65. Worsening of transaction affinities relations In some cases, the Detector may not detect enough occurrences (at least 10) of an affinity command to be sure that the affinity is definitely with a terminal (LUNAME), userid (USERID), or CICS BTS process (BAPPL).
| | | | v Command is a non-terminal-related START or a DPL v ENQ or DEQ commands that specify a resource name for which an appropriate ENQMODEL definition is enabled, and that ENQMODEL has a non—blank ENQSCOPE The Detector does not detect CICS macro-level commands, MVS POST calls, or the hand posting of ECBs. If you continue a pseudoconversation by setting a transid in the TIOA (rather than by using RETURN TRANSID), the Detector cannot detect PCONV lifetimes.
2. There is an affinity table for each of the following command groups that cause transaction-system affinity: v INQUIRE, SET, ENABLE, DISABLE, EXTRACT, COLLECT STATS, PERFORM, DISCARD, CREATE, and RESYNC commands v CICS BTS BROWSE commands are treated as inquire commands v WAITCICS, WAIT EVENT, and WAIT EXTERNAL commands 3. There are two affinity tables that are used as aids to searching some of the other tables.
The affinity data VSAM files The Detector uses three non-recoverable VSAM KSDS to hold saved affinity data. Ensure the files are big enough to hold the maximum amount of affinity data that might be collected. Three are required because of the wide range of key lengths that the different tables have. KSDS files are used because the Detector and the Reporter need keyed access to the data. The files are not recoverable because of the large amount of data that needs to be written.
Detector performance The Detector is intended to be run against production CICS regions. However, over the period when the Detector is running, the CICS region suffers a performance degradation (dependent on the workload and number of affinities) equivalent to the performance impact of vendor monitor products that use the same user exits. The Detector is intended to be used over limited periods.
The basic groups are combined because of a CICSPlex SM rule stating that a given tranid may appear only in a single transaction group. It is quite possible that a tranid may appear in more than one basic group, and so these must be combined to form larger groups that satisfy CICSPlex SM. Chapter 2.
20 CICS Transaction Affinities Utility Guide
Chapter 3. Preparing to use the affinity utility program This chapter describes what needs to be done before you can use the affinity utility program.
#transids is the number of transaction identifiers in the CICS region. #termids is the number of terminal identifiers in the CICS region. Note: The amount of storage needed in the data space for the Builder is about 25% of the storage needed for the Detector. The algorithm assumes that all affinities are represented, and that all transactions participate in all affinities, and that all transactions run at all terminals (the worst possible scenario). This gives a worst case figure.
v For file CAUCNTL only, if recovery is not required ensure that RECOVERY(NONE) and FWDRECOVLOG(NO) are specified. 3. INSTALL group mygroup to make these definitions known to CICS. Tailoring your CICS startup job To enable the Transaction Affinities Utility to be run against your CICS region, take account of the following when setting up your CICS startup job: v The Transaction Affinities Utility sends messages to the transient data destination CAFF.
24 CICS Transaction Affinities Utility Guide
Chapter 4. Running the Scanner This chapter describes how to run the Scanner that scans load modules for instances of API commands that could cause inter-transaction affinity and transaction-system affinity. You can run the Scanner to produce either a summary report and module list to identify suspect modules or a detailed report of modules that contain possible affinity-causing EXEC CICS commands or MVS POST calls.
v The AFFMOD DD statement Specify the name of the sequential data set where the list of modules with potential transaction affinities is to be sent. You can edit the data set to alter the list of modules to be scanned before running the Scanner to produce a detailed report. v The DETAIL DD statement (dummy) You do not need this for a summary run.
CICS TRANSACTION AFFINITIES UTILITY LOAD MODULE SCANNER - SUMMARY LISTING OF CICSTEST.LOAD Module Module Module Affinity MVS POSTs Comment Name Length Language Statements -------- -------- --------- ----------------------------------------ACSA1 00000198 ASSEMBLER 3 0 Possible affinity commands. AFFYIC 00000308 0 0 AFFYTS 00000628 0 0 COBACSA 000008B8 COBOL II 4 0 Possible affinity commands.
v The STEPLIB DD statement Specify the name of the Transaction Affinities Utility load library in which you have installed the Scanner program, CAULMS. v The INPUT DD statement Specify the name of the load library to be scanned. v The SYSPRINT DD statement Specify the destination for the detailed report. v The AFFMOD DD dummy statement You do not need this for a detailed run. v The DETAIL DD statement Specify the name of the data set containing the list of modules to be scanned.
v A summary report of the modules, giving: – The total possible affinity commands – The total possible MVS post commands v Library totals, as for the summary report, but for only those modules selected for the detailed run. Figure 5 is an example of a detailed report produced by the Scanner. CICS TRANSACTION AFFINITIES UTILITY 1995/11/24 Page 1 LOAD MODULE SCANNER - DETAILED LISTING OF CICSTEST.
30 CICS Transaction Affinities Utility Guide
Chapter 5. Running the Detector This chapter describes how to run the Detector that runs in a CICS region looking for instances of API commands that could cause transaction affinity.
Displaying the Detector control screen To display the control screen that you can use to run the Detector at a CICS terminal, first type the transaction identifier CAFF, then press Enter. In response, the Detector control screen, CAFF01 (shown in Figure 6), is displayed. You can use this screen to review and change the state of the Detector, or to display the Detector options screen, CAFF02 (shown in Figure 7 on page 36). To refresh the values displayed on the screen at any time, press Enter.
5 The total number of affinity records in the affinity data VSAM files. If the Detector was stopped by CICS crashing, and was in the middle of saving affinity data, this figure may be inaccurate. However, the figure is corrected the next time the Detector is started. 6 The date and time when the Detector was last started, data was saved, and a change was made to an affinity table. The date is given in the format specified by the DATFORM system initialization parameter.
Each time the Detector is started, a new data space is created. For help with calculating the likely data space storage requirement, see “Estimating the size of the MVS data space and VSAM files” on page 21. You specify this size on the Detector options screen, CAFF02. You can also specify that data from affinity data VSAM files (for example, from previous Transaction Affinities Utility runs) is to be loaded into the data space when it is created.
Table 5. Methods for resuming data collection by the Detector Where used Command or function key Control display, CAFF01 F8 function key 3270 terminal CAFF CONTINUE Console F cicsjob, CAFF CONTINUE 1 Application program EXEC CICS START TRANSID(’CAFF’) FROM(’CONTINUE’) Note: 1 cicsjob is the name of your CICS startup job. Using one of the methods listed in Table 5 causes the Detector to continue recording any transaction affinities in the CICS region, until you pause or stop data collection.
Note: If there are a large number of data records to be saved, the CAFF screen may be frozen for some appreciable time, until the records have been saved. You may want to stop the Detector when it has detected all affinities. This is indicated by the “Date/time of last change” field changing very infrequently and, if the optional periodic saves are performed, the “Records written last save” field being consistently near zero.
The Detector options screen, CAFF02, shows the options available to you. You can change an option only when the Detector has stopped, unless one of the notes that follow says otherwise.
ensure that this option is the same as that used in the previous run of the Detector (for which affinity data is to be restored). v Size of dataspace The size that you want to use for the data space to store the affinity data collected. The size of the data space is fixed for a run of the Detector. For information about estimating the size of the data space, see “Estimating the size of the MVS data space and VSAM files” on page 21.
Detector errors If the CAFF or CAFB transaction, or an exit program, encounters a serious error, the Detector stops by terminating CAFF and CAFB with one of the following termination codes: v A code in the AUxx range accompanied by messages on the CAFF transient data queue that indicate the cause of the error v A code not in the AUxx range, presumably being one of the other CICS transaction abend codes For a description of the code, see the CICS Messages and Codes manual.
40 CICS Transaction Affinities Utility Guide
Chapter 6. Running the Reporter This chapter describes how to run the Reporter that runs as a batch job to produce a report of the affinities found by the Detector. The commands reported on are those listed in “Commands detected by the Transaction Affinities Utility” on page 11. For information about interpreting the report output by the Reporter, see “Using the affinity report” on page 47.
v The CMDGRPS DD statement Specify the affinity (command) types you want to see in the report. Only those affinity types listed on this DD statement are shown in the report. (The types correspond exactly to the type options on the CAFF02 screen.
Affinity report Figure 8 shows an example report for two affinities, a TS queue affinity and a CWA affinity. These were the only affinity types selected, as shown.
CICS TRANSACTION AFFINITIES UTILITY INTER-TRANSACTION AFFINITIES REPORT FOR TEMPORARY STORAGE COMMANDS Trangroup : TS.
Note: The Trangroup value for an affinity transaction group may vary from one run to another of the Detector or Reporter. Affinity The affinity relation. If appropriate, this also indicates whether the relation was worsened from a less restrictive relation. For more information about worsened relations, see “Worsening of transaction affinities relations” on page 14. Lifetime The affinity lifetime. If appropriate, this also indicates whether the lifetime was worsened from a less restrictive lifetime.
Usage The number of times that this particular EXEC CICS command (with the transaction, program, and offset values reported) taking part in the affinity, up to a limit of 5000. Note: The usage count is an indication of the relative importance of the affinity, and is not a completely accurate usage count. For performance reasons, when the usage count is incremented by the Detector, the “save to file” flag is not necessarily set to indicate that the record needs to be saved to the data file.
2. MATCH or STATE attributes are not generated on CREATE TRANGRP commands, because those attributes are relevant only to the combined affinity transaction groups. For more information about MATCH and STATE attributes, see page 55. 3. The HEADER statement is generated so that the Builder can detect a new data set in its input concatenation. It also gives the CICS applid, and the date and time of the last Detector save, all obtained from the CAUCNTL control file.
Understanding the affinities The inter-transaction affinities listed in the report highlight those transactions that have affinities with other transactions. Understanding the affinities present in the CICS region enables you to determine which of the them are most pervasive. If you decide that it is worth changing your application programs, it is generally more cost-effective to remove the most pervasive affinities, because those affinities most restrict dynamic routing.
to be convinced that it is related to a terminal or userid. Change this to LUNAME or USERID (and correct the lifetime) if you know that the affinity really is terminalor userid-related. You may want to prevent worsening by specifying WORSEN=NO. v Remove affinity lifetime worsening An LUNAME affinity with a lifetime of LOGON, or a USERID affinity with a lifetime of SIGNON, may be worsened to SYSTEM or PERMANENT because the Detector cannot always observe log offs or sign offs.
Using the IBM Cross System Product The following information about the IBM Cross System Product (CSP) 4GL application generator concentrates on tests carried out running CSP 3.3, but in general the information also applies to later releases of CSP. There are two components to CSP: v CSP/AD (Application Development) is used to develop the applications v CSP/AE (Application Environment) is the run-time environment for application execution.
Detailed affinity analysis Each of the above command scenarios is dealt with below. A description of how the use of the command appears in the Transaction Affinities Utility Reporter report is given, followed by an assessment of any affinity problem it causes. However, it would be helpful first to expand on the structure of a CSP segmented application.
There may also be an EQ affinity group in the report with a resource name of CSMT when CSP serializes writing of information to TD destination CSMT. This does not cause affinity because each cloned CICS has its own CSMT. GETMAIN SHARED There is a GM affinity group in the report for each pair of transactions that were observed performing GETMAINs and FREEMAINs on shared storage. The programs involved are DCBINIT and DCBRINIT. Upon analysis, this use of GETMAIN SHARED may cause affinity.
an affinity of LUNAME and a lifetime of PCONV. The presence of one group rather than a group for each application is actually not important. When dynamic routing, the affinity still ends when the current pseudoconversation ends, so the effect is exactly the same. It is useful to have applied the PTF for CSP APAR PN45100, because this adds deletion of ’EZExtttt’ TS queues after a transaction abend.
54 CICS Transaction Affinities Utility Guide
Chapter 7. Running the Builder This chapter describes how to run the Builder that runs as a batch job to build affinity transaction groups suitable for input to the CICS system management product, the CICSPlex SM element of CICS Transaction Server for OS/390 Release 3.
Specify the name of the Transaction Affinities Utility load library where you have installed the Builder program, CAUBLD. v The REPGRPS DD statement Specify the (concatenation of) names of the sequential data sets containing the basic affinity transaction groups to be input to the Builder. The Builder reads the lines of the input data sets, and checks them for syntax and logic errors. For information about the valid syntax, see “Syntax for input to the Builder”.
9. If a line comment contains the characters HEADER anywhere in it, it is not treated as a comment and is parsed like any ordinary line in case it is a HEADER statement. Otherwise comment lines are thrown away. 10. The only valid values for AFFINITY are GLOBAL, LUNAME, USERID, and BAPPL. NONE is not allowed. 11. Keywords and values (including surrounding brackets) must not be split across input lines. 12. Nested brackets are not allowed within values. 13. The Builder is case sensitive.
HEADER statements The HEADER statement is specific to the Builder, and is not a CICSPlex SM statement. It is produced by the Reporter, and is needed by the Builder to create unique transaction group names. The Reporter generates temporary transaction group names (for example, CW.00000001 and TS.00000001) while it is running, and stores these names in the output data set for that run.
* HEADER APPLID(BUILDER ) SAVEDATE(95/11/27) SAVETIME(12:00:51); 1 * * Generated by the CICS Transaction Affinities Utility (Builder) on 1995/06/28 * Note: Suitable for input to CICSPlex SM * CONTEXT CICPLEX1; * * REMOVE TRANGRP NAME(AFF1GRP ); CREATE TRANGRP NAME(AFF1GRP ) AFFINITY(LUNAME) AFFLIFE(SYSTEM ) MATCH(LUNAME) STATE(DORMANT); CREATE DTRINGRP TRANGRP(AFF1GRP ) TRANID(AFF1); CREATE DTRINGRP TRANGRP(AFF1GRP ) TRANID(AFF2); CREATE DTRINGRP TRANGRP(AFF1GRP ) TRANID(AFF3); CREATE DTRINGRP TRANGRP(AFF1
through “Affinity relations” on page 4 show the relations and lifetimes that result from combining basic affinity transaction groups. To help you analyze the effect of combining basic transaction affinity groups, the Builder produces a report that lists the combinations that occurred. Table 7.
Table 11. Resultant affinity lifetimes (GLOBAL relation) Lifetime X Lifetime Y Resultant lifetime Z PERMANENT Any lifetime PERMANENT Any other lifetime combination SYSTEM Data sets processed report This report gives the names of all the input data sets (specified on the REPGRPS DD statement) that were read. This is produced even if errors occur in the input data sets. Note: Only data sets that contain a HEADER statement appear in the report.
CICS TRANSACTION AFFINITIES UTILITY BUILDER GROUP MERGE REPORT Trangroup : AFF1GRP Affinity : LUNAME Lifetime : SYSTEM Match : LUNAME State : DORMANT Consists of Transactions AFF1 AFF2 AFF3 AFF4 AFF5 Consists of groups merged from CICSPDN1.TRANGRPS.MERGE1 TS.00000001 (LUNAME PCONV CICSPDN1.TRANGRPS.MERGE2 TS.00000001 (LUNAME SYSTEM Trangroup : AFTDGRP Affinity : LUNAME Lifetime : PCONV Match : LUNAME State : DORMANT Consists of Transactions AFTD AFTR AFTW Consists of groups merged from CICSPDN1.TRANGRPS.
CICS TRANSACTION AFFINITIES UTILITY 1996/02/08 Page BUILDER REPGRPS ERROR REPORT Dataset = CICSPDN1.TRANGRPS.ERR1 Line Number Statement in error ----------- -----------------------------------------------------------------------------5 CREATE TRANGRP NAME(G3 ) AFFINITY(GLOBAL) AFFLIFE(LOGON ); DFHAU5038 INVALID AFFLIFE for AFFINITY. 6 CREATE TRANGRP NAME(G4 ) AFFINITY(GLOBAL) AFFLIFE(SIGNON ); DFHAU5038 INVALID AFFLIFE for AFFINITY.
64 CICS Transaction Affinities Utility Guide
Appendix A. Details of what is detected This appendix describes what is detected by the Detector and Reporter for each affinity type. Additionally, it highlights the differences, if any, with what the Scanner detects. (In general, the Scanner always detects more, because it covers paths that may not get exercised by the Detector, and because it cannot see beyond the command argument zero to eliminate commands that do not actually cause affinity.
TS commands v The affinity here is between all transactions that use the same TS queue. It applies to both MAIN and AUXILIARY TS. The match is made on the name of the TS queue. v The affinity relation can be GLOBAL, BAPPL, LUNAME, or USERID. v Lifetime can be PCONV, LOGON, SIGNON, ACTIVITY, PROCESS,SYSTEM, and PERMANENT. A MAIN queue cannot be recovered, regardless of definition, so cannot cause PERMANENT.
v If the transaction to be STARTed is defined as remote or a remote SYSID was specified on the START command so that the command is function shipped to a remote CICS region, no data is collected. v Commands in error are treated in the same way as commands that give a NORMAL response, so data is collected. Scanner differences: Scanner detects all instances of RETRIEVE WAIT, and all instances of START that either specify TERMID, or omit NOCHECK, or specify REQID (because of CANCEL affinity).
v The LOAD and FREEMAIN protocol applies only to programs defined as RELOAD(YES). Note that HOLD is irrelevant, as CICS Program Control never sees the FREEMAIN, or knows the storage location of the individual task’s copy, and so cannot release the program at task end. This implies that all LOADs must be examined as they are all effectively LOAD HOLDs. v The affinity relation may be GLOBAL, BAPPL, LUNAME, or USERID. v Lifetime can be PCONV, LOGON, SIGNON, ACTIVITY, PROCESS,or SYSTEM.
v Lifetime can be PCONV, LOGON, SIGNON, ACTIVITY, PROCESS, SYSTEM, or PERMANENT. The PROTECT option determines whether SYSTEM or PERMANENT would be used. However, the Detector always worsens LOGON and SIGNON to SYSTEM or PERMANENT, because of limitations in the way that this affinity is detected. The affinity relation for DELAY and POST may be GLOBAL, BAPPL, LUNAME, or USERID. v Lifetime can be only SYSTEM, PROCESS, ACTIVITY, or PCONV.
70 CICS Transaction Affinities Utility Guide
Appendix B. Correlating Scanner and Reporter output to source This appendix describes how to match the EXEC CICS command in the Reporter report and/or the Scanner detail report with the actual program source code. It also gives some examples of the procedures described. Reporter output The reported offset of a command is the offset from the start of the load module of the BALR to the CICS stub. To get the offset from the start of the program, subtract the length of the CICS stub from the offset reported.
Example 2–VS COBOL II The literal pool in VS COBOL II is part of the CGT. Having calculated the offset from the start of the program, you should subtract the start of the CGT from your calculated offset to get the offset within the CGT. In the listing, there is an MVC instruction with the argument zero as the source, of the form: MVC D1(L,R1),D2(R2) DFHEIV0 PGMLIT AT ...
For the Scanner output: CICS TRANSACTION AFFINITIES UTILITY 1995/11/19 Page 1 LOAD MODULE SCANNER - DETAILED LISTING OF CICS.PRODN1.
001126 MOVE 2. Look at the COBOL source for the MOVE at line 001126. This is for the EXEC CICS WRITEQ TS command starting on line 001124.
Appendix C. Useful tips when analyzing Transaction Affinities Utility reports Sometimes the report produced by the Reporter from data gathered from the Detector can contain some results that appear odd at first glance. This appendix gives tips for resolving such results. COBOL affinities If an application program is invoked using the native CALL statement, CICS COBOL run-time code issues an EXEC CICS LOAD HOLD for the program and branches to it directly.
76 CICS Transaction Affinities Utility Guide
Appendix D. Diagnostics This appendix contains these sections: v “Detector table manager diagnostics” v “Detector CAFB request queue manager diagnostics” on page 80 v “Date formatter diagnostics” on page 80 Detector table manager diagnostics This section lists the meaning for each possible value of the call parameters that are included in the error messages issued if an error occurs on a call to the Detector and Builder table manager, CAUTABM.
Table identifier values AUTM_EDSR AUTM_EDST AUTM_EDR AUTM_EDT AUTM_TSQ AUTM_TST AUTM_LRP AUTM_LRT AUTM_SRS AUTM_SRT AUTM_CWA AUTM_CWT AUTM_GFA AUTM_GFM AUTM_LFA AUTM_LFM AUTM_ICR AUTM_ICM AUTM_SPI AUTM_WAIT AUTM_TT AUTM_UT AUTM_BLD_DNT AUTM_BLD_GNT AUTM_BLD_TT AUTM_BLD_MERGED 78 CICS Transaction Affinities Utility Guide 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 28 29 30 31
Reason code values AUTM_INVALID_FUNCTION AUTM_NO_STORAGE AUTM_ELEMENT_NOT_FOUND AUTM_ELEMENT_EXISTS AUTM_INVALID_TABLE AUTM_IEFUSI_HIT AUTM_TABLE_EXISTS AUTM_TABLE_DOES_NOT_EXIST AUTM_POOL_EXISTS AUTM_POOL_DOES_NOT_EXIST AUTM_INVALID_CURSOR AUTM_DEFAULT_SIFD_ERROR AUTM_DEFAULT_SIFA_ERROR AUTM_DEFAULT_DSP_ERROR AUTM_DEFAULT_AVL_ERROR AUTM_SIFD_CREATE_POOL_ERROR AUTM_SIFA_CREATE_POOL_ERROR AUTM_DSP_CREATE_POOL_ERROR AUTM_SIFD_DESTROY_POOL_ERROR AUTM_SIFA_DESTROY_POOL_ERROR AUTM_DSP_DESTROY_POOL_ERROR AUTM_AVL
Detector CAFB request queue manager diagnostics This section Lists the meaning for each possible value of the call parameters that are included in the error messages issued if an error occurs on a call to the Detector CAFB request queue manager, CAUCAFP.
Index A activity 5 affinity avoiding 6 combining basic affinity transaction groups 59 control record VSAM file 17 data VSAM files 17 inter-transaction 4 lifetimes 4 overview 3 programming techniques 5 safe 6 suspect 6 unsafe 6 relations 4 transaction group definitions, producing 46 transaction-system 4 affinity data VSAM files 17 affinity transaction group definitions, producing 46 affinity transaction groups, combining 59 analyzing affinity utility program reports COBOL affinities 75 LOGON or SYSTEM when P
Detector (continued) saving data 17 starting data collection 33 stopping data collection 35 table manager diagnostics 77 what is detected 13 what is not detected 14 worsening of affinities lifetimes 14 worsening of affinities relations 14 diagnostics CAFB request queue manager 80 data formatter 80 table manager 77 dynamic transaction routing benefits 3 compared to static routing 1 cost 3 overview 1 G global affinity relation 4 H HEADER statements, Builder HOLD commands 66 58 I installing the affinity u
T target region 2 temporary storage compression 49 Transaction Affinities Utility Builder overview 18 commands detected 11 control record VSAM file 17 data VSAM files 17 date formatter diagnostics 80 Detector overview 12 overview 9 preparing to use 21 Reporter overview 18 Scanner overview 12 what is detected 13 what is not detected 14 transaction affinity avoiding 6 combining basic affinity transaction groups 59 control record VSAM file 17 data VSAM files 17 inter-transaction 4 lifetimes 4 overview 3 pr
84 CICS Transaction Affinities Utility Guide
Sending your comments to IBM If you especially like or dislike anything about this book, please use one of the methods listed below to send your comments to IBM. Feel free to comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information in this book and the way in which the information is presented.
IBMR Program Number: 5655-147 Printed in the United States of America on recycled paper containing 10% recovered post-consumer fiber.
Spine information: IBM CICS TS for OS/390 CICS Transaction Affinities Utility Guide Release 3
