How it Works
IBM
Loading...
OS
User Manual
103 pgs447.18 Kb0

IBM OS User Manual

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 replaces and makes obsolete the previous edition, SC33-1777-01. The technical changes for this edition are summarized under ″Summary of changes″ and are indicated by a vertical bar to the left of a change.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below.
At the back of this publication is a page entitled “Sending your comments to IBM”. If you want to make comments, but the methods described are not available to you, please address them to:
IBM United Kingdom Laboratories, Information Development, Mail Point 095, Hursley Park, Winchester, Hampshire, England, SO21 2JN.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1994, 1999. All rights reserved.
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Notices ........................... vii
Trademarks..........................viii
Preface ........................... ix
What this book is about ..................... ix
Who this book is for...................... ix
What you need to know to understand this book ........... ix
How to use this book ..................... ix
Determining if a publication is current ............... ix
Notes on terminology ..................... x
Bibliography ......................... xi
CICS Transaction Server for OS/390 ................ xi
CICS books for CICS Transaction Server for OS/390 ......... xi
CICSPlex SM books for CICS Transaction Server for OS/390 ...... xii
Other CICS books ...................... xii
Summary of changes......................xiii
Changes for the CICS Transaction Server for OS/390 Release 3 edition . . . xiii Changes for the CICS Transaction Server for OS/390 Release 2 edition . . . xiii Changes for the CICS Transaction Server for OS/390 Release 1 edition . . . xiii
Chapter 1. Introducing transaction affinities............. 1
The benefits of dynamic routing .................. 3
What does dynamic routing cost?................. 3
Transaction affinities ...................... 3
Inter-transaction affinity .................... 4
Transaction-system affinity ................... 4
Affinity relations ....................... 4
Affinity lifetimes ....................... 5
CICS programming techniques for transaction affinity .......... 5
Safe programming techniques .................. 6
Unsafe programming techniques ................. 6
Suspect programming techniques................. 6
Avoiding the effects of transaction affinity............... 6
Protecting applications from one another ............... 7
Chapter 2. Introducing the Transaction Affinities Utility ........ 9
Commands detected by the Transaction Affinities Utility .........11
The Scanner component .....................12
The Detector component .....................12
What is detected .......................13
What is not detected .....................14
Controlling the Detector ....................15
How the affinity data is collected .................15
Saving affinity data ......................16
The affinity data VSAM files...................17
The control record VSAM file ..................17
Detector performance .....................18
The Reporter component .....................18
The Builder component .....................18
Chapter 3. Preparing to use the affinity utility program ........21
© Copyright IBM Corp. 1994, 1999 iii
Creating the VSAM files .....................21
Estimating the size of the MVS data space and VSAM files ........21
Defining the VSAM files to CICS ..................22
Tailoring your CICS startup job...................23
Restarting your CICS region ...................23
Chapter 4. Running the Scanner .................25
Creating a summary report ....................25
Creating a detailed report ....................27
Contents of a detailed report ..................28
Chapter 5. Running the Detector .................31
Displaying the Detector control screen ................32
Starting the collection of affinity data ................33
Pausing the collection of affinity data ................34
Resuming the collection of affinity data................34
Stopping the collection of affinity data ................35
Changing the Detector options...................36
Detector errors ........................39
Chapter 6. Running the Reporter .................41
Requesting a report from the Reporter ................41
Output from the Reporter.....................42
Affinity report ........................43
Producing affinity transaction group definitions ............46
Using the affinity report .....................47
Understanding the affinities ...................48
Modifying affinity transaction groups................48
Compressing affinity data.....................49
Using the IBM Cross System Product ................50
Affinity analysis for a CICS region containing CSP 3.3 applications ....50
Detailed affinity analysis ....................51
Chapter 7. Running the Builder..................55
Syntax for input to the Builder ...................56
HEADER statements .....................58
Output from the Builder .....................58
Combined affinity transaction group definitions ............58
Data sets processed report ...................61
Empty transaction groups report .................61
Group merge report......................61
Error report .........................62
Appendix A. Details of what is detected ..............65
ENQ/DEQ ..........................65
TS commands.........................66
LOAD HOLD/RELEASE .....................66
RETRIEVE WAIT/START.....................66
ADDRESS CWA ........................67
GETMAIN SHARED/FREEMAIN ..................67
LOAD/FREEMAIN .......................67
CANCEL/DELAY/POST/START ..................68
SPI commands ........................69
WAIT commands........................69
Appendix B. Correlating Scanner and Reporter output to source ....71
iv CICS Transaction Affinities Utility Guide
Reporter output ........................71
Scanner output ........................71
Examples .........................71
Appendix C. Useful tips when analyzing Transaction Affinities Utility
reports ..........................75
COBOL affinities ........................75
LOGON or SYSTEM when PCONV expected .............75
Unrecognized Transids .....................75
Appendix D. Diagnostics ....................77
Detector table manager diagnostics .................77
Function code values .....................77
Detector CAFB request queue manager diagnostics ...........80
Function code values .....................80
Date formatter diagnostics ....................80
Reason code values .....................80
Index ............................81
Sending your comments to IBM .................85
Contents v
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. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan
The following paragraph does not apply in the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement may not apply to you.
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM United Kingdom Laboratories, MP151, Hursley Park, Winchester, Hampshire, England, SO21 2JN. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
© Copyright IBM Corp. 1994, 1999 vii
Trademarks
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.
The following terms are trademarks of International Business Machines Corporation in the United States, or other countries, or both:
BookManager DB2 CICS IBM CICS/ESA Language Environment CICSPlex VTAM
Other company, product, and service names may be trademarks or service marks of others.
viii CICS Transaction Affinities Utility Guide
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. It can also be used by application programmers to detect whether application programs they are developing are likely to cause inter-transaction affinity.
In particular, this book is of interest to CICS system programmers who are planning to use the CICSPlex®SM element of CICS Transaction Server for OS/390 Release 3 for workload balancing. For more information about CICSPlex SM, see the
CICSPlex SM Concepts and Planning
It is also of use if you are planning to implement asynchronous processing using CICS function shipping or are planning to use the CICS transaction isolation facility.
manual.
What you need to know to understand this book
You need to be familiar with the CICS application programming interface (API) and the various programming techniques available to CICS application programmers. In particular, you should be familiar with those techniques that CICS application programs can use to pass data from one to another, such as sharing common storage, and techniques to synchronize their execution.
“Chapter 1. Introducing transaction affinities” on page 1 gives a brief introduction to the inter-transaction affinity that can be caused by some of these techniques. For a full discussion of transaction affinities, see the
.
Guide
CICS Application Programming
How to use this book
This book is intended to be read sequentially, so that you understand how to:
1. Install the affinity utility
2. Run the separate components Later, when you are familiar with the utility, you need only refer to the chapter
dealing with the particular component that you want to run.
Determining if a publication is current
IBM regularly updates its publications with new and changed information. When first published, both hardcopy and BookManager softcopy versions of a publication are
© Copyright IBM Corp. 1994, 1999 ix
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.
For CICS Transaction Server books, these softcopy updates appear regularly on the
Transaction Processing and Data Collection Kit
reissue of the collection kit is indicated by an updated order number suffix (the -xx part). For example, collection kit SK2T-0730-06 is more up-to-date than SK2T-0730-05. The collection kit is also clearly dated on the cover.
Updates to the softcopy are clearly marked by revision codes (usually a “#” character) to the left of the changes.
Notes on terminology
CICS In general, this book refers to the Customer Information Control System as
MVS “MVS” is used for the operating system, which is an element of the CICS
Argument zero
CD-ROM, SK2T-0730-xx. Each
“CICS”, the element in the CICS Transaction Server for OS/390.
Transaction Server for OS/390.
When an EXEC CICS command is translated and compiled, it results in an encoded parameter list to be used with a call statement. The first parameter in this list is a constant known as the CICS argument zero. The first two bytes of this constant identify the command; for example, X'0A04' identifies it as a READQ TS command.
x CICS Transaction Affinities Utility Guide
Bibliography
CICS Transaction Server for OS/390
CICS Transaction Server for OS/390: Planning for Installation CICS Transaction Server for OS/390 Release Guide CICS Transaction Server for OS/390 Migration Guide CICS Transaction Server for OS/390 Installation Guide CICS Transaction Server for OS/390 Program Directory CICS Transaction Server for OS/390 Licensed Program Specification
CICS books for CICS Transaction Server for OS/390
General
CICS Master Index CICS User’s Handbook CICS Transaction Server for OS/390 Glossary
Administration
CICS System Definition Guide CICS Customization Guide CICS Resource Definition Guide CICS Operations and Utilities Guide CICS Supplied Transactions
Programming
CICS Application Programming Guide CICS Application Programming Reference CICS System Programming Reference CICS Front End Programming Interface User’s Guide CICS C++ OO Class Libraries CICS Distributed Transaction Programming Guide CICS Business Transaction Services
Diagnosis
CICS Problem Determination Guide CICS Messages and Codes CICS Diagnosis Reference CICS Data Areas CICS Trace Entries CICS Supplementary Data Areas
Communication
CICS Intercommunication Guide CICS Family: Interproduct Communication CICS Family: Communicating from CICS on System/390 CICS External Interfaces Guide CICS Internet Guide
Special topics
CICS Recovery and Restart Guide CICS Performance Guide CICS IMS Database Control Guide CICS RACF Security Guide CICS Shared Data Tables Guide CICS Transaction Affinities Utility Guide CICS DB2 Guide
(softcopy only) GC33-1705
GC33-1789 GC34-5352 GC34-5353 GC33-1681 GI10-2506 GC33-1707
SC33-1704 SX33-6104
SC33-1682 SC33-1683 SC33-1684 SC33-1685 SC33-1686
SC33-1687 SC33-1688 SC33-1689 SC33-1692 SC34-5455 SC33-1691 SC34-5268
GC33-1693 GC33-1694 LY33-6088 LY33-6089 SC34-5446 LY33-6090
SC33-1695 SC33-0824 SC33-1697 SC33-1944 SC34-5445
SC33-1698 SC33-1699 SC33-1700 SC33-1701 SC33-1702 SC33-1777 SC33-1939
© Copyright IBM Corp. 1994, 1999 xi
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 Application Programming Reference
Diagnosis
CICSPlex SM Resource Tables Reference CICSPlex SM Messages and Codes CICSPlex SM Problem Determination
Other CICS books
SC33-1812 GC33-0786 SC33-0788 SX33-6099
SC34-5401 SC33-0789 SC34-5402 SC33-1807 SC33-1808 SC33-1809
SC34-5457 SC34-5458
SC33-1220 GC33-0790 GC33-0791
CICS Application Programming Primer (VS COBOL II) CICS Application Migration Aid Guide CICS Family: API Structure CICS Family: Client/Server Programming CICS Family: General Information CICS 4.1 Sample Applications Guide CICS/ESA 3.3 XRF Guide
SC33-0674 SC33-0768 SC33-1007 SC33-1435 GC33-0155 SC33-1173 SC33-0661
If you have any questions about the CICS Transaction Server for OS/390 library,
CICS Transaction Server for OS/390: Planning for Installation
see
which discusses
both hardcopy and softcopy books and the ways that the books can be ordered.
xii CICS Transaction Affinities Utility Guide
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.
Significant changes for this edition are indicated by vertical lines to the left of the changes.
Changes for the CICS Transaction Server for OS/390 Release 2 edition
This book is based on the CICS Transaction Server for OS/390, release 1, edition, SC33-1777-00.
A new section has been added to “Chapter 6. Running the Reporter” on page 41. “Using the IBM Cross System Product” on page 50 describes the use of the Transaction Affinities Utility with programs developed using the IBM Cross System Product.
Changes for the CICS Transaction Server for OS/390 Release 1 edition
The chapter entitled “Installing the affinity utility” was renamed to “Preparing to use the Transaction Affinities Utility”, and was largely rewritten.
The messages and codes previously published in Appendix C were moved to the
CICS Messages and Codes
standard CICS messages. They are prefixed with the letters “DFH”, and have a component identifier of “AU”.
manual. The affinity utility program messages became
© Copyright IBM Corp. 1994, 1999 xiii
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 affinities, see the
transaction
CICS Application Programming Guide
routing) environment. For more information about transaction
This chapter introduces the following topics:
v “The benefits of dynamic routing” on page 3 v “Transaction affinities” on page 3 v “CICS programming techniques for transaction affinity” on page 5 v “Avoiding the effects of transaction affinity” on page 6 v “Protecting applications from one another” on page 7
CICS has been handling customers’ online transaction processing requirements for over thirty years. In that time, it has been extensively enhanced to meet the ever-growing needs of business applications, and to exploit the capabilities of modern computer processors and communication systems. One of the most significant enhancements in recent times is the addition of the dynamic routing facility.
.
Originally, a full-function CICS ran in a single address space (region) within the MVS environment. Currently, most CICS users use some form of intercommunications to operate multiple, interconnected, CICS regions (a CICSplex). Using the CICS multiregion operation (MRO) facility, a CICSplex typically consists of one or more terminal-owning regions (TOR), and a number of application-owning regions to which the TORs route the incoming transactions for processing. The CICSPlex SM element of CICS Transaction Server for OS/390 Release 3 includes a workload management component that optimizes processor capacity by dynamically routing transactions to whichever CICS region is the most appropriate at the time, taking into account any transaction affinities that exist. For an introduction to CICSPlex SM, see
CICSPlex SM Concepts and Planning
information about CICSPlex SM workload management, see
Managing Workloads
End-user MRO terminal CICS Relay User
Figure 1. The CICS transaction routing facility
.
CICS A CICS B Terminal-Owning Application-Owning Region (TOR) Region (AOR)
Transaction links Transaction
CICSPlex SM
; for
Before CICS Transaction Server for OS/390 Release 3, TORs routed transactions to the AORs predefined in transaction resource definitions by the system programmer. This static form of transaction routing adds to the system administration burden of the system programmer, because when transaction workloads have to be rebalanced across the AORs, transaction resource definitions have to be modified accordingly.
© Copyright IBM Corp. 1994, 1999 1
| |
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 workstation products using the External Call Interface (ECI) – Distributed Computing Environment (DCE) remote procedure calls (RPCs) – Open Network Computing (ONC) RPCs – Internet Inter-Object Request Block Protocol (IIOP) – Any function that issues an EXEC CICS LINK PROGRAM request
v Transactions associated with CICS business transaction services (CICS BTS)
activities.
New terms have been introduced that describe the roles played by CICS regions in dynamic routing:
Requesting region
The CICS region in which the dynamic routing request originates. For transactions initiated at a terminal, and inbound client DPL requests, this is typically a TOR. For terminal-related EXEC CICS START commands, for non-terminal-related EXEC CICS START commands, for peer-to-peer DPLs, and for CICS BTS activities, the requesting region is typically an AOR.
| | | | | | |
| | |
| |
| | | | | | |
Routing region
The CICS region in which the decision is taken on where the transaction or program should be run. For transactions initiated at a terminal, for EXEC CICS START commands associated with a terminal, and for inbound client DPL requests, this is typically a TOR. For non-terminla-related EXEC CICS START commands, for peer-to-peer DPL requests, and for CICS BTS activities, the routing region is typically an AOR.
Target region
The CICS region in which the transaction or program runs. For all dynamically-routed requests, this is typically an AOR.
Full details about the new dynamic routing facilities are described in
Intercommunication Guide
The dynamic routing facility removes the need to specify the remote system name of a target region in the transaction definition. Instead, you let the routing determine dynamically to which target region it should route incoming transactions. Unlike static routing, where there can only ever be one target region to which the routing region can route a transaction, dynamic routing gives you the means to create several target regions with the capability to process any given workload, and to let the routing regions choose the best one from a candidate list.
.
CICS
2 CICS Transaction Affinities Utility Guide
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. It needs a facility for you to specify your routing policies in a form that CICS can use. This can be a
| | | | | |
| |
user-written dynamic routing program used to supply the name of a suitable target region, or you can use the dynamic routing program EYU9XLOP provided with CICSPlex SM.. You can define the name of a dynamic routing program on either the DTRPGM system initialization (SIT) parameter, for terminal-related START and dynamic program link (DPL) requests, or the DSRTPRG SIT parameter for non-terminal-related START requests and CICS BTS processes.
At the basic level, a dynamic routing program simply contains tables of user transaction identifiers, with the matching system identifiers (SYSIDs) of the target regions that can process the transactions. At the highest and most sophisticated level, the dynamic routing program would also be capable of detecting and managing any special factors that might affect transaction routing.
|
One factor that can affect the otherwise free choice of target region is the use of particular CICS programming techniques that transactions use to pass data from one to another.
Transaction affinities
CICS transactions use many different techniques to pass data from one to another. Some techniques require that the transactions exchanging data must execute in the same CICS region, and therefore impose restrictions on the dynamic routing of transactions. If transactions exchange data in ways that impose such restrictions, there is said to be an affinity between them.
There are two categories of affinity:
v Inter-transaction affinity; see “Inter-transaction affinity” on page 4 v Transaction-system affinity; see “Transaction-system affinity” on page 4
The restrictions on dynamic routing caused by transaction affinities depend on the duration and scope of the affinities. Clearly, the ideal situation for a dynamic routing program is for there to be no transaction affinity at all, which means there is no
|
restriction in the choice of available target regions for dynamic routing. However, even when transaction affinities do exist, there are limits to the scope of these affinities determined by the:
v Affinity relations; see “Affinity relations” on page 4 v Affinity lifetime; see “Affinity lifetimes” on page 5
Chapter 1. Introducing transaction affinities 3
| | | |
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. It is
caused by the transactions using techniques to pass information between one another, or to synchronize activity between one another, in a way that requires the transactions to execute in the same CICS region. Inter-transaction affinity, which imposes restrictions on the dynamic routing of transactions, can occur in the following circumstances:
v One transaction terminates, leaving “state data” in a place that a second
transaction can access only by running in the same CICS region as the first transaction.
v One transaction creates data that a second transaction accesses while the first
transaction is still running. For this to work safely, the first transaction usually waits on some event, which the second transaction posts when it has read the data created by the first transaction. This synchronization technique requires that both transactions are routed to the same CICS region.
Transaction-system affinity
Affinity relations
| |
|
| | | | |
Transaction-system affinity is an affinity between a transaction and a particular CICS region (that is, it is not an affinity between transactions themselves). It is caused by the transaction interrogating or changing the properties of that CICS region.
Transactions with affinity to a particular system, rather than to another transaction, are not eligible for dynamic transaction routing. In general, they are transactions that use INQUIRE and SET commands or, depend on global user exit programs.
The affinity relation determines how the dynamic routing program selects a target region for a transaction instance associated with the affinity. An affinity relation can be classified as one of the following:
Global
A group of transactions where all instances of all transactions in the group that are initiated from any terminal must execute in the same target region for the lifetime of the affinity. The affinity lifetime for global relations can be system or permanent.
BAPPL
All instances of all transactions in the group are associated with the same CICS BTS (Business Transaction Services) process. There may be many different userids and terminals associated with the transactions included in this affinity group.
LUname
A group of transactions where all instances of all transactions in the group that are initiated from the same terminal must execute in the same target region for the lifetime of the affinity. The affinity lifetime for LUname relations can be pseudoconversation, logon, system, or permanent.
4 CICS Transaction Affinities Utility Guide
|
Affinity lifetimes
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.
|
|
| |
| |
The affinity lifetime determines when the affinity is ended.An affinity lifetime can be classified as one of:
System
The affinity lasts for as long as the target region exists, and ends whenever the target region terminates (at a normal, immediate, or abnormal termination). (The resource shared by transactions that take part in the affinity is not recoverable across CICS restarts.)
Permanent
The affinity extends across all CICS restarts. (The resource shared by transactions that take part in the affinity is recoverable across CICS restarts.) This is the most restrictive of all the inter-transaction affinities.
Process
The affinity exists until the process completes.
Activity
The affinity exists until the activity completes.
Pseudoconversation
The (LUname or userid) affinity lasts for the whole pseudoconversation, and ends when the pseudoconversation ends at the terminal.
Logon
The (LUname) affinity lasts for as long as the terminal remains logged on to CICS, and ends when the terminal logs off.
Signon
The (userid) affinity lasts for as long as the user is signed on, and ends when the user signs off.
Notes:
1. For userid affinities, the pseudoconversation and signon lifetimes are possible
only in those situations where one user per userid is permitted. Such lifetimes are meaningless if multiple users are permitted to be signed on with the same userid at the same time (at different terminals).
2. If an affinity is both userid and LUname (that is, all instances of all transactions
in the group were initiated from the same terminal and by the same userid), LUname takes precedence.
CICS programming techniques for transaction affinity
Associated with transaction affinity, there are three broad categories of CICS programming techniques:
v Safe programming techniques v Unsafe programming techniques v Suspect programming techniques
Chapter 1. Introducing transaction affinities 5
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 obtained via a LOAD PROGRAM HOLD
v Task-lifetime local storage shared by synchronized tasks v Synchronization or serialization of tasks using CICS commands:
– WAIT EVENT / WAIT EXTERNAL / WAITCICS commands
| |
| | |
– ENQ and DEQ commands that do not specify a length parameter and
therefore ENQ by address
– ENQ and DEQ commands that do specify a length and therefore ENQ by
name, unless you have used ENQMODEL definitions to give sysplex-wide scope to the ENQs (and DEQs)
Suspect programming techniques
Some programming techniques may create affinity, depending on exactly how they are implemented. A good example is the use of temporary storage. Application programs using techniques in this category must be checked to determine whether
|
|
|
they will work without restrictions in a dynamic routingenvironment. The programming techniques in the suspect category are the use of:
v Temporary storage queues with restrictive naming conventions v Transient data queues and trigger levels v Synchronization or serialization of tasks using CICS commands:
– RETRIEVE WAIT / START – START / CANCEL REQID – DELAY / CANCEL REQID – POST / CANCEL REQID
v INQUIRE and SET commands and global user exits
Avoiding the effects of transaction affinity
| | | | | |
In a dynamic routing environment, your dynamic routing program must take account of transaction affinity in order to route transactions effectively. Where possible, you should avoid creating application programs that cause affinity. However, where existing applications are concerned, it is important that you determine whether they are affected by transaction affinity before using them in a dynamic routing environment. The Transaction Affinities Utility is designed to help you with this task.
6 CICS Transaction Affinities Utility Guide
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 programs 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. In general, transaction isolation ensures that each user-key program is allocated a separate (unique) subspace, with appropriate access to any shared storage or to CICS storage. They do not have any access to the user-key task-lifetime storage of other tasks. Existing applications should run unmodified provided they conform to transaction isolation requirements. However, a minority of applications may need special definition if they:
v Issue MVS macros directly v Modify CICS control blocks v Have a legitimate need for one task to access or share another task’s storage
Some existing transactions may share task-lifetime storage in various ways, which may prevent them running isolated from each other. To allow such transactions to continue running without requiring that they run in the base space (where they could corrupt CICS data or programs), a single common subspace is provided in which all such transactions can run. They are then isolated from the other transactions in the system that are running in their own subspaces, but are able to share each other’s data within the common subspace.
1
execute in their own
You may have some transactions whose application programs access each other’s storage in a valid way. One such case is when a task waits on one or more event control blocks (ECBs) that are later posted, by another task, either an MVS POST or ‘hand posting’. For example, a task can pass the address of a piece of its own storage to another task (via a temporary storage queue or some other method) and then WAIT for the other task to post an ECB to say that it has updated the storage. Clearly, if the original task is executing in a unique subspace, the posting task will fail when attempting the update and hence fail to post the ECB, unless the posting task is executing in CICS key. CICS therefore checks when a WAIT is issued that the ECB is in shared storage, and raises an INVREQ condition if it is not.
Storage for the timer-event control area on WAIT EVENT, and storage for event control blocks (ECBs) specified on WAIT EXTERNAL and WAITCICS commands, must reside in shared storage.
2
You can use the Transaction Affinities Utility to identify those transactions whose programs issue WAIT EVENT, WAIT EXTERNAL, or WAITCICS commands, or MVS POST macros.
1. User key defines both the storage and execution key for user application programs.
2. Shared storage is allocated from one of the user-key shared dynamic storage areas, below or above the 16MB boundary (SDSA or ESDSA).
Chapter 1. Introducing transaction affinities
7
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.
8 CICS Transaction Affinities Utility Guide
Chapter 2. Introducing the Transaction Affinities Utility
This chapter gives an overview of the Transaction Affinities Utility, and describes the basic components:
v “Commands detected by the Transaction Affinities Utility” on page 11 v “The Scanner component” on page 12 v “The Detector component” on page 12 v “The Reporter component” on page 18 v “The Builder component” on page 18
| | | | | | |
| |
The Transaction Affinities Utility is designed to detect potential causes of inter-transaction affinity and transaction-system affinity for those users planning to use the CICS dynamic routing facility. It can be used to detect programs using EXEC CICS commands that may cause transaction affinity. It can also be used to create a file containing combined affinity transaction group definitions, suitable for input to the CICS system management product, the CICSPlex SM element of CICS Transaction Server for OS/390 Release 3.
The commands that can be detected are listed in “Commands detected by the Transaction Affinities Utility” on page 11. The Transaction Affinities Utility is also of value for those users planning to use either asynchronous processing by CICS function shipping, or the transaction isolation facility.
The Transaction Affinities Utility determines the affinities that apply to a single CICS region: that is, a single pure target region or single combined routing region/target region. It can be run against production CICS regions, and is also useful in a test environment, to detect possible affinities introduced by new or changed application suites or packages.
Important note
The Transaction Affinities Utility is only an aid to help you find any affinities in your applications. Relate the output from the Transaction Affinities Utility to the applications that contain affinities before deciding whether or not the applications are suitable for CICS dynamic routing.
To ensure that you detect as many potential affinities as possible, use the Transaction Affinities Utility against all parts of your workload, including rarely-used transactions and abnormal situations.
© Copyright IBM Corp. 1994, 1999 9
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
Application
1. 2.
Scanner Detector
Load Library
Report
Basic Affinity
Transaction Groups
Combined Affinity Transaction Groups
ToCICSPlex SM
Figure 2. Affinity utility program components
User Collected Affinity Data
3.4.
ReporterBuilder
Report
10 CICS Transaction Affinities Utility Guide
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. Commands detected by the Transaction Affinities Utility
Inter-transaction affinity commands Transaction-system affinity commands
ENQ DEQ READQ TS WRITEQ TS DELETEQ TS ADDRESS CWA LOAD RELEASE GETMAIN SHARED FREEMAIN RETRIEVE WAIT DELAY POST START CANCEL COLLECT STATISTICS
Notes:
ENABLE PROGRAM DISABLE PROGRAM EXTRACT EXIT INQUIRE SET PERFORM RESYNC DISCARD CREATE WAIT EXTERNAL WAIT EVENT WAITCICS CBTS STARTBROWSE CBTS GETNEXT CBTS ENDBROWSE
1. The Scanner may detect some instances of these commands that do not cause an affinity. For example, all FREEMAIN commands are detected but only those used to free GETMAIN SHARED storage may cause affinity.
2. The Scanner also detects MVS POST SVC calls and MVS POST LINKAGE=SYSTEM non-SVC calls, because of their tie-up with the various EXEC CICS WAIT commands.
3. The Transaction Affinities Utility does not search for transient data and file control EXEC CICS commands. They are assumed not to cause affinity because you can define transient data and file control resources as remote (in which case the request is function-shipped, causing no affinity problem).
4. The Detector ignores commands that target remote resources and are function shipped, because by function shipping the command there is no affinity problem.
5. The Scanner and Detector do not search for commands issued by any program named CAUxxxxx or DFHxxxxx, because CICS programs are not considered part of the workload. Also, the Detector does not search for commands issued from:
v DB2® and DBCTL task-related user exits v User-replaceable modules
6. There are other ways in which transactions can cause affinity with each other, but they are not readily detectable by the affinity utility program because they do not take place via the EXEC CICS API.
7. The Detector lists WAIT commands as transaction-system affinities because only half of the affinity can be detected. (The Detector does not detect MVS POST calls or the hand posting of ECBs.)
| |
8. The Detector and the Report ignore ENQ and DEQ commands that specify an ENQSCOPE name.
Chapter 2. Introducing the Transaction Affinities Utility 11
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
The Scanner detects the use of the EXEC CICS commands listed in Table 1 on page 11, and MVS POST requests.
The report produced by the Scanner indicates only that potential affinity problems may exist because it only identifies the programs that issue the commands. It cannot obtain dynamic information about the transactions using the programs, or the names of the resources acted upon. Use the report in conjunction with the main report produced by the Reporter (see “The Reporter component” on page 18).
Notes:
1. The Scanner operation is independent of the language the scanned program was written in and the release of CICS the scanned program was translated under.
2. The Scanner may indicate an affinity problem that does not really exist, because the bit pattern found accidentally matches the argument zero format for an affinity command.
3. The Scanner does not detect CICS macro-level commands.
| | | |
4. The Scanner distinguishes between ENQ by name and ENQ by address based on the presence of a length parameter on the EXEC CICS ENQ command. It does the same for DEQs. The reports show which ENQs and DEQs are by name and which are by address.
3
format for the commands in question.
The Detector component
You can use the Detector in real-time to detect transaction affinities in a running CICS region, and to save details of the affinities in an MVS data space. This data is subsequently saved to DASD. The Detector consists of:
v A control transaction, CAFF v An autosave transaction, CAFB v Some global user exit programs v A task-related user exit program
This is shown in Figure 3 on page 13. The data is collected by the global user exit programs at exit points XEIOUT,
|
XBADEACT, XMEOUT, and XICEXP, and a task-related user exit at task start and task end. Between them, these exit programs intercept all the EXEC CICS commands and other events (pseudoconversation end, terminal log off, user sign off) that are needed to deduce the affinities and their relations and lifetimes. These exit programs coexist with any other exit programs at the same exit points. (They can be placed before or after other exit programs, without any of the exit programs being affected.)
3. For an explanation of argument zero, see “Notes on terminology” on page x.
12 CICS Transaction Affinities Utility Guide
Data space
Collected affinity data
XEIOUT TRUE XMEOUT XICEXP
CAFB CAFF
CICS AOR
or
TOR/AOR
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.
Collected affinity data
XBADEACT
Exit programs
User
What is detected
| | | | |
The Detector detects the EXEC CICS commands listed in Table 1 on page 11 that can cause transaction affinity. For ENQ and DEQ commands, the Detector distinguishes between ENQ by name and ENQ by address based on the presence of a length parameter on the EXEC CICS ENQ command. It does the same for DEQs. The reports show which ENQs and DEQs are by name and which are by address.
It also detects: v The end of pseudoconversations, by detecting when one of the transactions in
the pseudoconversation terminates without issuing an EXEC CICS RETURN TRANSID command with a non-zero transaction identifier. If a pseudoconversation ends, and the resource shared by transactions that take part in the affinity still exists, the lifetime of the affinity must be greater than PCONV.
Chapter 2. Introducing the Transaction Affinities Utility 13
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). In such cases, the Detector records the (worsened) affinity relation as GLOBAL instead of LUNAME or USERID. Such relation worsening is flagged by the Detector and reported by the Reporter.
Worsening of transaction affinities lifetimes
If a pseudoconversation ends, and the resource still exists, the Detector deduces that the lifetime is longer than PCONV, that is, one of LOGON, SIGNON, SYSTEM, or PERMANENT.
If a log off or sign off occurs, and the resource still exists, the Detector deduces that the lifetime is longer than LOGON or SIGNON: that is, either SYSTEM or PERMANENT.
| | |
| |
If a CICS BTS activity completes and the resource still exits, the lifetime is worsened to process. If a CICS BTS process completes and the resource still exits, the liftime is worsened to system.
In some cases, the Detector may not detect a log off or sign off, so cannot be sure that the affinity lifetime is LOGON or SIGNON. In such cases, the Detector records the (worsened) lifetime as SYSTEM or PERMANENT instead of LOGON or SIGNON. For example, this occurs when the CICS region the Detector is running on is a target region, because it is impossible in some cases to detect a log off or sign off that occurs in a connected routing region.
Such lifetime worsening is flagged by the Detector, and reported by the Reporter.
What is not detected
The Detector does not detect EXEC CICS commands when the:
v Detector is not running v Issuing program was translated with the SYSEIB option v Command is an EXEC CICS FEPI command v Command is not one that can cause transaction affinity v Program name starts with “CAU” or “DFH” v Program is a DB2 or DBCTL task-related user exit v Program is a CICS user-replaceable module v Transaction identifier does not match the prefix, if specified, for transactions to be
v Command is not one of the affinity types specified to be detected v Command is function shipped to a remote CICS region v Inter-transaction affinity commands are used within the same task
detected
14 CICS Transaction Affinities Utility Guide
Loading...
+ 73 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use