IBM OS - Manual

Reporter output . . . . . . . . . . . . . . . . . . . . . . . . 71 Scanner output . . . . . . . . . . . . . . . . . . . . . . . . 71 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 71 Appendix C. Useful tips when analyzing Transaction Affinities Utility reports . . . . . . . . . . . . . ....

Notices This information was developed for products and services offered in the U.S.A. IBMmay not offer the products, services, or features discussed in this document in othercountries. Consult your local IBM representative for information on the products andservices currently available in your area...

The licensed program described in this document and all licensed material availablefor it are provided by IBM under terms of the IBM Customer Agreement, IBMInternational Programming License Agreement, or any equivalent agreementbetween us. Trademarks The following terms are trademarks of Internation...

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 CICSdynamic routing fo...

usually in step. However, due to the time required to print and distribute hardcopybooks, the BookManager version is more likely to have had last-minute changesmade to it before publication. Subsequent updates will probably be available in softcopy before they are availablein hardcopy. This means th...

Bibliography CICS Transaction Server for OS/390 CICS Transaction Server for OS/390: Planning for Installation GC33-1789 CICS Transaction Server for OS/390 Release Guide GC34-5352 CICS Transaction Server for OS/390 Migration Guide GC34-5353 CICS Transaction Server for OS/390 Installation Guide GC33-1...

CICSPlex SM books for CICS Transaction Server for OS/390 General CICSPlex SM Master Index SC33-1812 CICSPlex SM Concepts and Planning GC33-0786 CICSPlex SM User Interface Guide SC33-0788 CICSPlex SM View Commands Reference Summary SX33-6099 Administration and Management CICSPlex SM Administration SC...

Summary of changes The affinity utility program is an integral part of CICS Transaction Server for OS/390and 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 theIBM CICS Transaction Affinities Utility MVS/ES...

Chapter 1. Introducing transaction affinities This chapter provides a brief introduction to the concept of transaction affinities andthe associated CICS programming techniques, and highlights the significance oftransaction affinities in a dynamic routing (known in previous releases of CICS asdynamic...

Note that, if you are dynamically routing non-terminal-related START and DPLrequests, you should review your application to determine whether or not theapplication is suitable for dynamic routing. The Transaction Affinities Utility cannotdetect affinities in these circumstances. Inter-transaction af...

Userid A group of transactions where all instances of the transactions that areinitiated from a terminal and executed on behalf of the same userid mustexecute in the same target region for the lifetime of the affinity. The affinitylifetime for userid relations can be pseudoconversation, signon, syst...

Protecting applications from one another The transaction isolation function offers storage protection between applicationprograms, ensuring that one application does not accidentally overwrite the storageof another. Transaction isolation ensures that user-key programs 1 execute in their own subspace...

Chapter 2. Introducing the Transaction Affinities Utility This chapter gives an overview of the Transaction Affinities Utility, and describes thebasic components: v “Commands detected by the Transaction Affinities Utility” on page 11 v “The Scanner component” on page 12 v “The Detector component” on...

Commands detected by the Transaction Affinities Utility You can use the Transaction Affinities Utility to detect instances of the EXEC CICScommands listed in Table 1. Table 1. Commands detected by the Transaction Affinities Utility Inter-transaction affinity commands Transaction-system affinity comm...

You are recommended to run the Detector on stable CICS regions only. Do notapply maintenance to application programs while the Detector is running. Suchmaintenance may introduce or remove affinities, thus rendering collected datainaccurate. What is detected The Detector detects the EXEC CICS command...

v Log offs and sign offs by intercepting messages DFHSN1200, DFHZC3462, andDFHZC5966. 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 d...

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 ...

Detector performance The Detector is intended to be run against production CICS regions. However, overthe period when the Detector is running, the CICS region suffers a performancedegradation (dependent on the workload and number of affinities) equivalent to theperformance impact of vendor monitor p...

Chapter 3. Preparing to use the affinity utility program This chapter describes what needs to be done before you can use the affinity utilityprogram. v “Creating the VSAM files” v “Estimating the size of the MVS data space and VSAM files” v “Defining the VSAM files to CICS” on page 22 v “Tailoring y...

#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 affinitie...

v For file CAUCNTL only, if recovery is not required ensure thatRECOVERY(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, takeacc...

Chapter 4. Running the Scanner This chapter describes how to run the Scanner that scans load modules forinstances of API commands that could cause inter-transaction affinity andtransaction-system affinity. You can run the Scanner to produce either a summary report and module list toidentify suspect ...

v The AFFMOD DD statement Specify the name of the sequential data set where the list of modules withpotential transaction affinities is to be sent. You can edit the data set to alter thelist of modules to be scanned before running the Scanner to produce a detailedreport. v The DETAIL DD statement (d...

Creating a detailed report You can request a detailed report from the Scanner by editing and running the jobCAUJCLLD. Change the following statements as appropriate: v The PARM statement PARM='$DETAIL[,ALL]' $DETAIL Specifies that a detailed scan and report is required. The extent of the scanis defi...

v The STEPLIB DD statement Specify the name of the Transaction Affinities Utility load library in which youhave 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 rep...

Chapter 5. Running the Detector This chapter describes how to run the Detector that runs in a CICS region lookingfor instances of API commands that could cause transaction affinity. This chapter describes how to perform the following functions: v “Displaying the Detector control screen” on page 32 v...

Displaying the Detector control screen To display the control screen that you can use to run the Detector at a CICSterminal, first type the transaction identifier CAFF, then press Enter. In response, theDetector control screen, CAFF01 (shown in Figure 6), is displayed. You can use thisscreen to revi...

„ 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 affinitydata, this figure may be inaccurate. However, the figure is corrected the next timethe Detector is started. „ 6 … The date and time when t...

Each time the Detector is started, a new data space is created. For help withcalculating the likely data space storage requirement, see “Estimating the size ofthe MVS data space and VSAM files” on page 21. You specify this size on theDetector options screen, CAFF02. You can also specify that data fr...

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 ...

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 isindicated by the “Date/time of last change” field changing very inf...

The Detector options screen, CAFF02, shows the options available to you. You canchange an option only when the Detector has stopped, unless one of the notes thatfollow says otherwise. Notes: „ 1 … The control options: v Perform periodic saves Whether or not you want the affinity data collected to be...

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 followingtermination codes: v A code in the AUxx range accompanied by messages on the CAFF transient dataqueue that indicate the cause of th...

Chapter 6. Running the Reporter This chapter describes how to run the Reporter that runs as a batch job to producea report of the affinities found by the Detector. The commands reported on arethose listed in “Commands detected by the Transaction Affinities Utility” on page 11.For information about i...

v The CMDGRPS DD statement Specify the affinity (command) types you want to see in the report. Only thoseaffinity types listed on this DD statement are shown in the report. (The typescorrespond exactly to the type options on the CAFF02 screen.) You can specifyany of the following affinity types, wit...

Affinity report Figure 8 shows an example report for two affinities, a TS queue affinity and a CWAaffinity. These were the only affinity types selected, as shown. CICS TRANSACTION AFFINITIES UTILITY 1995/11/24 Page 1 AFFINITY TYPE REPORTING OPTIONS Applid=CICSPDN1 Affinity Type Reporting Message ---...

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 co...

2. MATCH or STATE attributes are not generated on CREATE TRANGRP commands, because those attributes are relevant only to the combined affinitytransaction 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 n...

Understanding the affinities The inter-transaction affinities listed in the report highlight those transactions thathave affinities with other transactions. Understanding the affinities present in the CICS region enables you to determinewhich of the them are most pervasive. If you decide that it is ...

to be convinced that it is related to a terminal or userid. Change this to LUNAMEor USERID (and correct the lifetime) if you know that the affinity really is terminal-or userid-related. You may want to prevent worsening by specifyingWORSEN=NO. v Remove affinity lifetime worsening An LUNAME affinity ...

Using the IBM Cross System Product The following information about the IBM Cross System Product (CSP) 4GLapplication generator concentrates on tests carried out running CSP 3.3, but ingeneral the information also applies to later releases of CSP. There are two components to CSP: v CSP/AD (Applicatio...

Detailed affinity analysis Each of the above command scenarios is dealt with below. A description of how theuse of the command appears in the Transaction Affinities Utility Reporter report isgiven, followed by an assessment of any affinity problem it causes. However, itwould be helpful first to expa...

an affinity of LUNAME and a lifetime of PCONV. The presence of one group ratherthan a group for each application is actually not important. When dynamic routing,the affinity still ends when the current pseudoconversation ends, so the effect isexactly the same. It is useful to have applied the PTF fo...

Chapter 7. Running the Builder This chapter describes how to run the Builder that runs as a batch job to buildaffinity transaction groups suitable for input to the CICS system managementproduct, the CICSPlex SM element of CICS Transaction Server for OS/390Release 3. This chapter contains the followi...

Specify the name of the Transaction Affinities Utility load library where you haveinstalled the Builder program, CAUBLD. v The REPGRPS DD statement Specify the (concatenation of) names of the sequential data sets containing thebasic affinity transaction groups to be input to the Builder. The Builder...

Notes: 1. The values of the SAVEDATE and SAVETIME fields in the HEADER statement give the latest save date and save time from any of the input data sets. (SeeFigure 11 ( „ 1 … ) and Figure 12 on page 61.) 2. The combined transaction groups can be input again to the Builder. For example, you may deci...

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 REPGRPSDD statement) that wer...

Error report This report gives the syntax or logic of any errors that were detected in theprocessing of the input files. Each error is accompanied by a message. For adescription of the message, see the CICS Messages and Codes manual. CICS TRANSACTION AFFINITIES UTILITY 1995/11/28 Page 3 BUILDER GROU...

Appendix A. Details of what is detected This appendix describes what is detected by the Detector and Reporter for eachaffinity type. Additionally, it highlights the differences, if any, with what the Scannerdetects. (In general, the Scanner always detects more, because it covers paths thatmay not ge...

TS commands v The affinity here is between all transactions that use the same TS queue. Itapplies to both MAIN and AUXILIARY TS. The match is made on the name ofthe TS queue. v The affinity relation can be GLOBAL, BAPPL, LUNAME, or USERID. v Lifetime can be PCONV, LOGON, SIGNON, ACTIVITY, PROCESS,SY...

v If the transaction to be STARTed is defined as remote or a remote SYSID wasspecified on the START command so that the command is function shipped to aremote CICS region, no data is collected. v Commands in error are treated in the same way as commands that give aNORMAL response, so data is collect...

v Lifetime can be PCONV, LOGON, SIGNON, ACTIVITY, PROCESS, SYSTEM, orPERMANENT. The PROTECT option determines whether SYSTEM orPERMANENT would be used. However, the Detector always worsens LOGONand SIGNON to SYSTEM or PERMANENT, because of limitations in the way thatthis affinity is detected. The af...

Appendix B. Correlating Scanner and Reporter output tosource This appendix describes how to match the EXEC CICS command in the Reporterreport and/or the Scanner detail report with the actual program source code. It alsogives some examples of the procedures described. Reporter output The reported off...

Example 2–VS COBOL II The literal pool in VS COBOL II is part of the CGT. Having calculated the offsetfrom the start of the program, you should subtract the start of the CGT from yourcalculated offset to get the offset within the CGT. In the listing, there is an MVCinstruction with the argument zero...

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 ...

Table identifier values AUTM_EDSR 1 AUTM_EDST 2 AUTM_EDR 3 AUTM_EDT 4 AUTM_TSQ 5 AUTM_TST 6 AUTM_LRP 7 AUTM_LRT 8 AUTM_SRS 9 AUTM_SRT 10 AUTM_CWA 11 AUTM_CWT 12 AUTM_GFA 13 AUTM_GFM 14 AUTM_LFA 15 AUTM_LFM 16 AUTM_ICR 17 AUTM_ICM 18 AUTM_SPI 19 AUTM_WAIT 20 AUTM_TT 21 AUTM_UT 22 AUTM_BLD_DNT 28 AUTM...

Reason code values AUTM_INVALID_FUNCTION 0 AUTM_NO_STORAGE 1 AUTM_ELEMENT_NOT_FOUND 2 AUTM_ELEMENT_EXISTS 3 AUTM_INVALID_TABLE 4 AUTM_IEFUSI_HIT 5 AUTM_TABLE_EXISTS 6 AUTM_TABLE_DOES_NOT_EXIST 7 AUTM_POOL_EXISTS 8 AUTM_POOL_DOES_NOT_EXIST 9 AUTM_INVALID_CURSOR 10 AUTM_DEFAULT_SIFD_ERROR 192 AUTM_DEF...

Detector CAFB request queue manager diagnostics This section Lists the meaning for each possible value of the call parameters that areincluded in the error messages issued if an error occurs on a call to theDetector CAFB request queue manager, CAUCAFP. Function code values AUCP_ADD_CELL_FIRST 1 AUCP...

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-syste...

IBMR Program Number: 5655-147 Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber. SC33-1777-02