IBM Transaction Server OS Manuale Utente Pagina 1

CICS® Transaction Server for OS/390®CICS Transaction Affinities Utility GuideRelease 3SC33-1777-02IBM

The licensed program described in this document and all licensed material availablefor it are provided by IBM under terms of the IBM Customer Agreemen

84 CICS Transaction Affinities Utility Guide

Sending your comments to IBMIf you especially like or dislike anything about this book, please use one of themethods listed below to send your comment

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

Spine information:IBM CICS TS for OS/390 CICS Transaction Affinities Utility Guide Release 3

PrefaceWhat this book is aboutThis book describes the affinity utility program. It explains what the utility does,how to install it, and how to run th

usually in step. However, due to the time required to print and distribute hardcopybooks, the BookManager version is more likely to have had last-minu

BibliographyCICS Transaction Server for OS/390CICS Transaction Server for OS/390: Planning for InstallationGC33-1789CICS Transaction Server for OS/390

CICSPlex SM books for CICS Transaction Server for OS/390GeneralCICSPlex SM Master IndexSC33-1812CICSPlex SM Concepts and PlanningGC33-0786CICSPlex SM

Summary of changesThe affinity utility program is an integral part of CICS Transaction Server for OS/390and is for use only with the CICS Transaction

xiv CICS Transaction Affinities Utility Guide

Chapter 1. Introducing transaction affinitiesThis chapter provides a brief introduction to the concept of transaction affinities andthe associated CIC

CICS Transaction Server for OS/390 Release 3 introduces extended dynamicrouting facilities, that allow the dynamic routing of:v Transactions initiated

The benefits of dynamic routingBeing able to route transactions to target regions dynamically offers many benefitsin an online transaction processing (O

Note that, if you are dynamically routing non-terminal-related START and DPLrequests, you should review your application to determine whether or not t

UseridA group of transactions where all instances of the transactions that areinitiated from a terminal and executed on behalf of the same userid must

Safe programming techniquesThe programming techniques in the safe category are the use of:v The communication area (COMMAREA) on CICS RETURN commandsv

Protecting applications from one anotherThe transaction isolation function offers storage protection between applicationprograms, ensuring that one ap

What next?This chapter has briefly summarized the techniques and commands that cancause transaction affinity. “Chapter 2. Introducing the Transaction A

Chapter 2. Introducing the Transaction Affinities UtilityThis chapter gives an overview of the Transaction Affinities Utility, and describes thebasic

Figure 2 shows the affinity utility program. Each of the four components is describedin more detail in the rest of this chapter.ReportReportScanner De

Commands detected by the Transaction Affinities UtilityYou can use the Transaction Affinities Utility to detect instances of the EXEC CICScommands lis

The Scanner componentThe Scanner is a batch utility that scans a load module library to detect thoseprograms in the library that issue EXEC CICS comma

You are recommended to run the Detector on stable CICS regions only. Do notapply maintenance to application programs while the Detector is running. Su

CICS® Transaction Server for OS/390®CICS Transaction Affinities Utility GuideRelease 3SC33-1777-02IBM

v Log offs and sign offs by intercepting messages DFHSN1200, DFHZC3462, andDFHZC5966.v Completion of CICS BTS activities and processes.For more inform

v Command is a non-terminal-related START or a DPLv ENQ or DEQ commands that specify a resource name for which an appropriateENQMODEL definition is ena

2. There is an affinity table for each of the following command groups that causetransaction-system affinity:v INQUIRE, SET, ENABLE, DISABLE, EXTRACT,

The affinity data VSAM filesThe Detector uses three non-recoverable VSAM KSDS to hold saved affinity data.Ensure the files are big enough to hold the ma

Detector performanceThe Detector is intended to be run against production CICS regions. However, overthe period when the Detector is running, the CICS

The basic groups are combined because of a CICSPlex SM rule stating that agiven tranid may appear only in a single transaction group. It is quite poss

20 CICS Transaction Affinities Utility Guide

Chapter 3. Preparing to use the affinity utility programThis chapter describes what needs to be done before you can use the affinity utilityprogram.v

#transidsis the number of transaction identifiers in the CICS region.#termidsis the number of terminal identifiers in the CICS region.Note: The amount o

v For file CAUCNTL only, if recovery is not required ensure thatRECOVERY(NONE) and FWDRECOVLOG(NO) are specified.3. INSTALL groupmygroupto make these de

Note!Before using this information and the product it supports, be sure to read the general information under “Notices” on page vii.Third edition (Mar

24 CICS Transaction Affinities Utility Guide

Chapter 4. Running the ScannerThis chapter describes how to run the Scanner that scans load modules forinstances of API commands that could cause inte

v The AFFMOD DD statementSpecify the name of the sequential data set where the list of modules withpotential transaction affinities is to be sent. You

Creating a detailed reportYou can request a detailed report from the Scanner by editing and running the jobCAUJCLLD.Change the following statements as

v The STEPLIB DD statementSpecify the name of the Transaction Affinities Utility load library in which youhave installed the Scanner program, CAULMS.v

v A summary report of the modules, giving:– The total possible affinity commands– The total possible MVS post commandsv Library totals, as for the sum

30 CICS Transaction Affinities Utility Guide

Chapter 5. Running the DetectorThis chapter describes how to run the Detector that runs in a CICS region lookingfor instances of API commands that cou

Displaying the Detector control screenTo display the control screen that you can use to run the Detector at a CICSterminal, first type the transaction

5 The total number of affinity records in the affinity data VSAM files. If theDetector was stopped by CICS crashing, and was in the middle of saving

ContentsNotices ... viiTrademarks...viiiPreface ... ixWhat this book is about .

Each time the Detector is started, a new data space is created. For help withcalculating the likely data space storage requirement, see “Estimating th

Table 5. Methods for resuming data collection by the DetectorWhere used Command or function keyControl display, CAFF01 F8 function key3270 terminal CA

Note: If there are a large number of data records to be saved, the CAFF screenmay be frozen for some appreciable time, until the records have been sav

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

ensure that this option is the same as that used in the previous run of theDetector (for which affinity data is to be restored).v Size of dataspaceThe

Detector errorsIf the CAFF or CAFB transaction, or an exit program, encounters a serious error,the Detector stops by terminating CAFF and CAFB with on

40 CICS Transaction Affinities Utility Guide

Chapter 6. Running the ReporterThis chapter describes how to run the Reporter that runs as a batch job to producea report of the affinities found by t

v The CMDGRPS DD statementSpecify the affinity (command) types you want to see in the report. Only thoseaffinity types listed on this DD statement are

Affinity reportFigure 8 shows an example report for two affinities, a TS queue affinity and a CWAaffinity. These were the only affinity types selected

Creating the VSAM files ...21Estimating the size of the MVS data space and VSAM files ...21Defining the VSAM files to CICS ...

Notes for Figure 8:1 Incorrect affinity typesThis lists any affinity types that were specified incorrectly on the CMDGRPS DDstatement of the CAUJCLRP

Note: The Trangroup value for an affinity transaction group may vary fromone run to another of the Detector or Reporter.AffinityThe affinity relation.

Usage The number of times that this particular EXEC CICS command (with thetransaction, program, and offset values reported) taking part in the affinit

2. MATCH or STATE attributes are not generated on CREATE TRANGRPcommands, because those attributes are relevant only to the combined affinitytransacti

Understanding the affinitiesThe inter-transaction affinities listed in the report highlight those transactions thathave affinities with other transact

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 re

Using the IBM Cross System ProductThe following information about the IBM Cross System Product (CSP) 4GLapplication generator concentrates on tests ca

Detailed affinity analysisEach of the above command scenarios is dealt with below. A description of how theuse of the command appears in the Transacti

There may also be an EQ affinity group in the report with a resource name ofCSMT when CSP serializes writing of information to TD destination CSMT. Th

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 dynam

Reporter output ...71Scanner output ...71Examples ...71Appendix C. Useful tips when an

54 CICS Transaction Affinities Utility Guide

Chapter 7. Running the BuilderThis chapter describes how to run the Builder that runs as a batch job to buildaffinity transaction groups suitable for

Specify the name of the Transaction Affinities Utility load library where you haveinstalled the Builder program, CAUBLD.v The REPGRPS DD statementSpec

9. If a line comment contains the characters HEADER anywhere in it, it is nottreated as a comment and is parsed like any ordinary line in case it is a

HEADER statementsThe HEADER statement is specific to the Builder, and is not a CICSPlex SMstatement. It is produced by the Reporter, and is needed by t

Notes:1. The values of the SAVEDATE and SAVETIME fields in the HEADER statementgive the latest save date and save time from any of the input data sets.

through “Affinity relations” on page 4 show the relations and lifetimes that resultfrom combining basic affinity transaction groups.To help you analyz

Table 11. Resultant affinity lifetimes (GLOBAL relation)Lifetime X Lifetime Y Resultant lifetime ZPERMANENT Any lifetime PERMANENTAny other lifetime c

Error reportThis report gives the syntax or logic of any errors that were detected in theprocessing of the input files. Each error is accompanied by a

CICS TRANSACTION AFFINITIES UTILITY 1996/02/08 Page 1BUILDER REPGRPS ERROR REPORTDataset = CICSPDN1.TRANGRPS.ERR1Line Number Statement in error-------

vi CICS Transaction Affinities Utility Guide

64 CICS Transaction Affinities Utility Guide

Appendix A. Details of what is detectedThis appendix describes what is detected by the Detector and Reporter for eachaffinity type. Additionally, it h

TS commandsv 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 t

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 a

v The LOAD and FREEMAIN protocol applies only to programs defined asRELOAD(YES). Note that HOLD is irrelevant, as CICS Program Control neversees the FR

v Lifetime can be PCONV, LOGON, SIGNON, ACTIVITY, PROCESS, SYSTEM, orPERMANENT. The PROTECT option determines whether SYSTEM orPERMANENT would be used

70 CICS Transaction Affinities Utility Guide

Appendix B. Correlating Scanner and Reporter output tosourceThis appendix describes how to match the EXEC CICS command in the Reporterreport and/or th

Example 2–VS COBOL IIThe literal pool in VS COBOL II is part of the CGT. Having calculated the offsetfrom the start of the program, you should subtrac

For this, the calculations are:Scanner offset = X'7A6'CICS stub length = X'28'Offset of CGT = X'B8'CGT base register = G

NoticesThis information was developed for products and services offered in the U.S.A. IBMmay not offer the products, services, or features discussed i

001126 MOVE2. Look at the COBOL source for the MOVE at line 001126. This is for the EXECCICS WRITEQ TS command starting on line 001124.74 CICS Transac

Appendix C. Useful tips when analyzing Transaction AffinitiesUtility reportsSometimes the report produced by the Reporter from data gathered from theD

76 CICS Transaction Affinities Utility Guide

Appendix D. DiagnosticsThis appendix contains these sections:v “Detector table manager diagnostics”v “Detector CAFB request queue manager diagnostics”

Table identifier valuesAUTM_EDSR 1AUTM_EDST 2AUTM_EDR 3AUTM_EDT 4AUTM_TSQ 5AUTM_TST 6AUTM_LRP 7AUTM_LRT 8AUTM_SRS 9AUTM_SRT 10AUTM_CWA 11AUTM_CWT 12AUT

Reason code valuesAUTM_INVALID_FUNCTION 0AUTM_NO_STORAGE 1AUTM_ELEMENT_NOT_FOUND 2AUTM_ELEMENT_EXISTS 3AUTM_INVALID_TABLE 4AUTM_IEFUSI_HIT 5AUTM_TABLE

Detector CAFB request queue manager diagnosticsThis sectionLists the meaning for each possible value of the call parameters that areincluded in the er

IndexAactivity 5affinityavoiding 6combining basic affinity transaction groups 59control record VSAM file 17data VSAM files 17inter-transaction 4lifetime

Detector(continued)saving data 17starting data collection 33stopping data collection 35table manager diagnostics 77what is detected 13what is not dete

Ttarget region 2temporary storage compression 49Transaction Affinities UtilityBuilder overview 18commands detected 11control record VSAM file 17data VS