Instruction/ maintenance manual of the product OS IBM
Go to page of 103
CIC S® T ransa ct i o n Se rv er f o r OS /39 0® CI CS T r a ns a cti o n Af fini ti es U tili ty G ui d e Relea se 3 SC33-1777-02 IBM.
.
CIC S® T ransa ct i o n Se rv er f o r OS /39 0® CI CS T r a ns a cti o n Af fini ti es U tili ty G ui d e Relea se 3 SC33-1777-02 IBM.
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 o.
Contents Notices ........................... v i i T rademarks .......................... viii Preface ........................... i x What this book is about ..................... i x Who this book is for ...................... i x What you need to know to understand this book .
Creating the VSAM files ..................... 2 1 Estimating the size of the MVS data space and VSAM files ........ 2 1 Defining the VSAM files to CICS .................. 2 2 T ailoring your CICS startup job ................... 2 3 Restarting your CICS region .
Reporter output ........................ 7 1 Scanner output ........................ 7 1 Examples ......................... 7 1 Appendix C. Useful tips when analyzing T ransaction Aff inities Utility reports .......................... 7 5 COBOL aff inities .
vi CICS T ransaction 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.
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 af finity utility program . It explains what the utility does, how to install it, and how to run the various components of the utility .
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 .
Bibliography CICS T ransaction Server for OS/390 CICS T ransaction Server for OS/390: Planning for Installation GC33-1789 CICS T ransaction Server for OS/390 Release Guide GC34-5352 CICS T ransaction .
CICSPlex SM books for CICS T ransaction 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 .
Summary of changes The aff inity utility program is an integral part of CICS T ransaction Server for OS/390 and is for use only with the CICS T ransaction Server for OS/390. T o use the utility on CICS for MVS/ESA 4.1 and earlier releases of CICS, install the IBM CICS T ransaction Affinities Utility MVS/ESA (program number 5696-582).
xiv CICS T ransaction Affinities Utility Guide.
Chapter 1. Introducing transaction af finities This chapter provides a brief introduction to the concept of transaction aff inities and the associated CICS programming techniques, and highlights the significance of transaction aff inities in a dynamic routing (known in previous releases of CICS as dynamic transaction routing) environment.
CICS T ransaction Server for OS/390 Release 3 introduces extended dynamic routing facilities, that allow the dynamic routing of: v T ransactions initiated at a terminal v EXEC CICS ST ART requests tha.
The benefits of dynamic routing Being able to route transactions to target regions dynamically offers many benefits in an online transaction processing (OL TP) system.
Note that, if you are dynamically routing non-terminal-related ST ART and DPL requests, you should review your application to determine whether or not the application is suitable for dynamic routing. The T ransaction Affinities Utility cannot detect aff inities in these circumstances.
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 aff inity . The af finity lifetime for userid relations can be pseudoconversation, signon, system, or permanent.
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) opt.
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 .
What next? This chapter has briefly summarized the techniques and commands that can cause transaction aff inity . “Chapter 2. Introducing the T ransaction Affinities Utility” on page 9 gives an o.
Chapter 2. Introducing the T ransaction Af finities Utility This chapter gives an overview of the T ransaction Affinities Utility , and describes the basic components: v “Commands detected by the T .
Figure 2 shows the affinity utility program. Each of the four components is described in more detail in the rest of this chapter . Report Report Scanner Detector Reporter Builder User AOR or TOR/AOR Collected Affinity Data Combined Affinity Transaction Groups Basic Affinity Transaction Groups Application Load Library T o CICSPlex SM 1.
Commands detected by the T ransaction Aff inities Utility Y ou can use the T ransaction Af finities Utility to detect instances of the EXEC CICS commands listed in T able 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 aff inity . It examines the individual object programs looking for patterns matching the argument zero 3 format for the commands in question.
Y ou 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 aff inities, thus rendering collected data inaccurate.
v Log offs and sign of fs by intercepting messages DFHSN1200, DFHZC3462, and DFHZC5966. v Completion of CICS BTS activities and processes. For more information, see “Appendix A.
v Command is a non-terminal-related ST ART 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.
2. There is an affinity table for each of the following command groups that cause transaction-system aff inity: v INQUIRE, SET , ENABLE, DISABLE, EXTRACT , COLLECT ST A TS, PERFORM, DISCARD, CREA TE, and RESYNC commands v CICS BTS BROWSE commands are treated as inquire commands v W AITCICS, WAIT EVENT , and WAIT EXTERNAL commands 3.
The af finity data VSAM files The Detector uses three non-recoverable VSAM KSDS to hold saved aff inity data. Ensure the files are big enough to hold the maximum amount of aff inity data that might be collected. Three are required because of the wide range of key lengths that the different tables have.
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 aff inities) equivalent to the performance impact of vendor monitor products that use the same user exits.
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.
20 CICS T ransaction Affinities Utility Guide.
Chapter 3. Preparing to use the af finity utility program This chapter describes what needs to be done before you can use the aff inity 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 .
v For file CAUCNTL only , if recovery is not required ensure that RECOVERY(NONE) and FWDRECOVLOG(NO) are specified. 3. INST ALL group mygroup to make these definitions known to CICS.
24 CICS T ransaction 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 aff inity .
v The AFFMOD DD statement Specify the name of the sequential data set where the list of modules with potential transaction aff inities is to be sent. Y ou can edit the data set to alter the list of modules to be scanned before running the Scanner to produce a detailed report.
Creating a detailed report Y ou can request a detailed report from the Scanner by editing and running the job CAUJCLLD. Change the following statements as appropriate: v The P ARM statement PARM='$DETAIL[,ALL]' $DET AIL Specifies that a detailed scan and report is required.
v The STEPLIB DD statement Specify the name of the T ransaction 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 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 .
30 CICS T ransaction 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 T o 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.
5 The total number of aff inity records in the affinity data VSAM files. If the Detector was stopped by CICS crashing, and was in the middle of saving aff inity data, this figure may be inaccurate. However , the figure is corrected the next time the Detector is started.
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. Y ou specify this size on the Detector options screen, CAFF02.
T able 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 ST ART TRANSID(’CAFF’) FROM(’CONTINUE’) Note: 1 cicsjob is the name of your CICS startup job.
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.
The Detector options screen, CAFF02, shows the options available to you. Y ou 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 aff inity data is to be restored). v Size of dataspace The size that you want to use for the data space to store the aff inity data collected. The size of the data space is fixed for a run of the Detector .
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 .
40 CICS T ransaction 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 aff inities found by the Detector . The commands reported on are those listed in “Commands detected by the T ransaction Affinities Utility” on page 1 1.
v The CMDGRPS DD statement Specify the aff inity (command) types you want to see in the report. Only those aff inity types listed on this DD statement are shown in the report.
Af finity report Figure 8 shows an example report for two affinities, a TS queue af finity and a CW A aff inity . These were the only af finity types selected, as shown.
Notes for Figure 8: 1 Incorrect aff inity types This lists any aff inity types that were specified incorrectly on the CMDGRPS DD statement of the CAUJCLRP job.
Note: The T rangroup value for an af finity transaction group may vary from one run to another of the Detector or Reporter . Aff inity The af finity relation. If appropriate, this also indicates whether the relation was worsened from a less restrictive relation.
Usage The number of times that this particular EXEC CICS command (with the transaction, program, and offset values reported) taking part in the af finity , up to a limit of 5000. Note: The usage count is an indication of the relative importance of the aff inity , and is not a completely accurate usage count.
2. MA TCH or ST A TE attributes are not generated on CREA TE TRANGRP commands, because those attributes are relevant only to the combined aff inity transaction groups. For more information about MA TCH and ST A TE attributes, see page 55. 3. The HEADER statement is generated so that the Builder can detect a new data set in its input concatenation.
Understanding the af finities The inter-transaction aff inities listed in the report highlight those transactions that have aff inities with other transactions. Understanding the aff inities present in the CICS region enables you to determine which of the them are most pervasive.
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 aff inity really is terminal- or userid-related.
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.
Detailed af finity analysis Each of the above command scenarios is dealt with below . A description of how the use of the command appears in the T ransaction Affinities Utility Reporter report is given, followed by an assessment of any aff inity problem it causes.
There may also be an EQ aff inity group in the report with a resource name of CSMT when CSP serializes writing of information to TD destination CSMT . This does not cause aff inity because each cloned CICS has its own CSMT .
an aff inity 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 aff inity still ends when the current pseudoconversation ends, so the effect is exactly the same.
54 CICS T ransaction Affinities Utility Guide.
Chapter 7. Running the Builder This chapter describes how to run the Builder that runs as a batch job to build aff inity transaction groups suitable for input to the CICS system management product, the CICSPlex SM element of CICS T ransaction Server for OS/390 Release 3.
Specify the name of the T ransaction 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 aff inity transaction groups to be 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.
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 .
Notes: 1. The values of the SA VEDA TE and SA VETIME fields in the HEADER statement give the latest save date and save time from any of the input data sets. (See Figure 1 1 ( 1 ) and Figure 12 on page 61.) 2. The combined transaction groups can be input again to the Builder .
through “Aff inity relations” on page 4 show the relations and lifetimes that result from combining basic aff inity transaction groups. T o help you analyze the effect of combining basic transaction af finity groups, the Builder produces a report that lists the combinations that occurred.
T able 1 1. 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.
Error report This report gives the syntax or logic of any errors that were detected in the processing of the input files. Each error is accompanied by a message.
CICS TRANSACTION AFFINITIES UTILITY 1996/02/08 Page 1 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.
64 CICS T ransaction Affinities Utility Guide.
Appendix A. Details of what is detected This appendix describes what is detected by the Detector and Reporter for each aff inity type. Additionally , it highlights the differences, if any , with what the Scanner detects.
TS commands v The aff inity 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 aff inity relation can be GLOBAL, BAPPL, LUNAME, or USERID. v Lifetime can be PCONV , LOGON, SIGNON, ACTIVITY , PROCESS,SYSTEM, and PERMANENT .
v If the transaction to be ST ART ed is defined as remote or a remote SYSID was specified on the ST ART 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.
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.
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 aff inity is detected.
70 CICS T ransaction 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.
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 of fset within the CGT .
For this, the calculations are: Scanner offset = X'7A6' CICS stub length = X'28' Offset of CGT = X'B8' CGT base register = GPR 10 Offset within CGT = X'7A6' - X'28' - X'B8' = X'6C6' = 1734 (decimal) MVC instruction looks like: MVC d(l,r),1734(10) DFHEIV0 PGMLIT AT .
001126 MOVE 2. Look at the COBOL source for the MOVE at line 001 126. This is for the EXEC CICS WRITEQ TS command starting on line 001 124. 74 CICS T ransaction Affinities Utility Guide.
Appendix C. Useful tips when analyzing T ransaction Af finities 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.
76 CICS T ransaction 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 diagnos.
T able 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 A.
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_.
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 aff inity avoiding 6 combining basic aff inity transaction groups 59 control record VSAM file 17 data VSAM files 17 inter-transaction 4 lifetimes 4 overview 3 programming techniqu.
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 aff inities lifetimes .
T target region 2 temporary storage compression 49 T ransaction Affinities Utility Builder overview 18 commands detected 1 1 control record VSAM file 17 data VSAM files 17 date formatter diagnostics.
84 CICS T ransaction 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.
IBMR Program Number: 5655-147 Printed in the United States of America on recycled paper containing 10% recovered post-consumer fiber . SC33-1777-02.
Spine information: IBM CI CS TS f o r OS /3 9 0 CI C S T r ans a cti o n Af finiti es U tility G ui d e Re lease 3.
An important point after buying a device IBM OS (or even before the purchase) is to read its user manual. We should do this for several simple reasons:
If you have not bought IBM OS yet, this is a good time to familiarize yourself with the basic data on the product. First of all view first pages of the manual, you can find above. You should find there the most important technical data IBM OS - thus you can check whether the hardware meets your expectations. When delving into next pages of the user manual, IBM OS you will learn all the available features of the product, as well as information on its operation. The information that you get IBM OS will certainly help you make a decision on the purchase.
If you already are a holder of IBM OS, but have not read the manual yet, you should do it for the reasons described above. You will learn then if you properly used the available features, and whether you have not made any mistakes, which can shorten the lifetime IBM OS.
However, one of the most important roles played by the user manual is to help in solving problems with IBM OS. Almost always you will find there Troubleshooting, which are the most frequently occurring failures and malfunctions of the device IBM OS along with tips on how to solve them. Even if you fail to solve the problem, the manual will show you a further procedure – contact to the customer service center or the nearest service center
