z/os IBM Planning and Operating Guide Version 2 Release 3 SC23-6877-30
Note Before using this information and the product it supports, read the information in Notices on page 127. This edition applies to Version 2 Release 3 of z/os (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions. Last updated: July 17, 2017 Copyright IBM Corporation 2003, 2017. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents Figures............... v Tables............... vii About this document......... ix Required product knowledge........ ix z/os information............. x How to send your comments to IBM.. xi If you have a technical problem........ xi Summary of changes........ xiii Summary of changes for z/os Version 2 Release 3 (V2R3) and its updates.......... xiii Summary of changes for z/os Version 2 Release 2 (V2R2)................ xiii Chapter 1. Understanding the environment............. 1 Transaction processing and transactional recovery.. 1 Terminology............. 1 Transaction processing.......... 4 Transactional recovery.......... 4 VSAM record-level sharing (RLS)....... 6 Overview of VSAM RLS......... 6 Read sharing of recoverable data sets..... 10 VSAM RLS read integrity options...... 10 Read-sharing integrity across KSDS control-interval and control-area splits.... 11 Read and write sharing of nonrecoverable data sets................ 11 Non-RLS access to VSAM data sets..... 11 Differences between VSAM RLS access and non-rls access............ 12 Requirements for VSAM RLS request execution mode............... 13 VSAM options that RLS and do not support............... 14 overview........... 14 Transaction processing from a batch job.... 15 Recovery coordination.......... 15 Access to recoverable VSAM data sets.... 16 Transaction processing.......... 16 How works with RRS and other resource managers........... 19 How complements CICS..... 20 Context services and RRMS......... 20 Native contexts............ 21 Privately managed contexts........ 21 Units of recovery........... 21 Chapter 2. Planning for... 25 Planning tasks............. 25 Coupling-facility planning......... 26 Coupling facilities........... 26 Number of coupling facilities....... 27 Standalone or internal coupling facility.... 27 Volatile or nonvolatile coupling facility.... 28 Contents of a coupling facility....... 28 Coupling-facility size.......... 29 Coupling facility links.......... 31 Processor-capacity planning......... 31 Software-configuration planning....... 32 System-logger planning.......... 32 Logging flow overview......... 32 Log streams............. 33 Structures and log streams........ 35 DASD-only log streams......... 35 Log stream sizing........... 36 DASD staging data sets......... 37 DASD log data sets........... 37 VSAM operations planning......... 38 Recovery procedures.......... 38 Forward recovery operation planning..... 39 Reorganization............ 39 Automatic Restart Manager planning..... 39 and ARM.......... 40 Installation of.......... 40 Chapter 3. Configuring the environment and defining resources.. 41 Defining your Parallel Sysplex environment... 42 Setting up the logging environment...... 42 Using coupling facilities.......... 43 Defining staging data sets......... 44 Specifying SYS1.PARMLIB parameters for 45 Defining a PARMLIB member specific to one system............... 46 Defining a parmlib member that applies to multiple systems........... 46 Chapter 4. Setting up logging.............. 47 Determining the amount of logging to do.... 47 Defining coupling-facility structures for log streams 48 Definition of a coupling-facility structure for a log stream.............. 50 Log structure names.......... 50 Allocating system log streams........ 51 Examples of system log stream definitions... 52 System log stream names......... 53 Offloading of log data.......... 54 Using backout logging........... 54 Backout records for in-doubt and long-running units of recovery........... 55 Backout logging events......... 55 Defining forward recovery logs........ 56 Creating a log of logs........... 59 Authorizing access to log streams....... 60 Copyright IBM Corp. 2003, 2017 iii
Authorization to access log streams..... 60 RACF RDEFINE coding......... 61 Chapter 5. Designing and coding applications to use.... 63 Determining which applications should use............... 63 Modifying an application to use.... 64 Coding an application to use..... 64 Defining transactions.......... 64 Understanding restrictions.... 65 Considering RLS and restrictions.. 67 Using VSAM data sets in a transaction.... 67 Accessing a data set with..... 67 Structuring your application for commit and backout............... 69 Understanding the effects of a task ending... 70 Understanding record locking that uses................ 70 Handling long-running jobs and programs.... 73 Using restartable applications........ 73 Establishing positioning after logical errors.... 74 Using sequential or random access to a data set.. 75 Deleting and renaming data sets....... 75 Monitoring and retrying shunted transactions... 76 Applying advanced application development techniques............... 77 Record management requests....... 78 Multitasking............. 78 Chapter 6. Monitoring performance and tuning the environment... 81 Monitoring performance.......... 81 SMF record type 42 (hexadecimal 2A).... 81 SMF record type 88 (hexadecimal 58)..... 82 RMF post-processor reports........ 82 RMF monitor III............ 83 CICS monitoring tools.......... 83 System messages........... 83 Operator commands.......... 83 Shunted units of recovery........ 83 Effects of, log stream, and data set states............... 84 Effects of states based on events... 87 Improving sequential performance...... 104 Improving logging performance....... 104 Tuning the environment...... 105 Categorizing a system logger problem.... 107 Collecting diagnostic information about logging problems.............. 108 Investigating console messages and dumps.. 108 Displaying coupling-facility status..... 109 Checking global resource serialization (GRS) resource contention.......... 110 Checking SMF and RMF statistics for performance problems......... 111 Interrupting an operation or resource request... 111 Recovering from a log stream problem..... 112 Resolving waits............. 113 Restarting after SMSVSAM address space failure.............. 113 Cold starting.......... 114 Performing peer recovery......... 114 Peer recovery initiation......... 115 SMSVSAM failures while peer recovery is in process.............. 116 System failures while peer recovery is in process 116 Peer-recovery interference with failed instance restart............... 116 Appendix A. Quiescing a data set... 117 Appendix B. Accessing data sets that have retained locks or lost locks... 119 Appendix C. Accessibility...... 123 Accessibility features........... 123 Consult assistive technologies........ 123 Keyboard navigation of the user interface.... 123 Dotted decimal syntax diagrams....... 123 Notices.............. 127 Terms and conditions for product documentation 129 IBM Online Privacy Statement........ 130 Policy for unsupported hardware....... 130 Minimum supported hardware....... 130 Trademarks.............. 131 Glossary............. 133 Index............... 147 Chapter 7. Diagnosing and recovering from problems...... 107 Diagnosing system logger and performance problems............... 107 iv z/os Planning and Operating Guide
Figures 1. CICS VSAM non-rls access....... 7 2. CICS VSAM RLS access......... 8 3. Batch jobs designed to use transactional recovery............. 20 4. Contexts as a series of units of recovery 22 5. Two-phase commit processing actions.... 23 6. Sample definition of the CFRM policy... 49 7. Sample log stream coupling-facility structure definition............. 50 8. Sample definitions of the system logs.... 53 9. Sample definitions of forward recovery logs 58 10. Sample definition of the log of logs.... 59 11. Example of an RACF PERMIT command 61 12. Example of RACF RDEFINE commands 61 13. Example of RACF commands to grant VSAM RLS authority to read and write log streams. 61 14. Example of key hashing........ 72 15. Multitasking............ 79 16. Example of MVS commands to produce a dump of XCF and system logger address spaces.............. 108 17. Example of a command to display system logger couple data set status...... 109 18. Example of a normal response from a command to display system logger couple data set status........... 109 19. Example of a command to reconnect the couple data set........... 109 20. Example of a command to display all structures with Failed_Persistent connections. 109 21. Examples of DISPLAY GRS commands 110 22. Example of a normal response from a DISPLAY GRS command........ 110 23. Example of a GRS command showing contention............ 110 24. Example of a GRS command to display log streams with an exclusive enqueue.... 111 25. Example of output from a GRS command to display log streams with an exclusive enqueue............. 111 Copyright IBM Corp. 2003, 2017 v
vi z/os Planning and Operating Guide
Tables 1. Effect of MAXSYSTEM value on lock-table-entry size.......... 30 2. Lock-allocation estimates........ 30 3. Opening recoverable and nonrecoverable VSAM data sets from batch jobs..... 68 4. Effects of states on processing............. 85 5. Effects of log states on processing 85 6. Effects of data set states on processing............. 86 7. Installation exit environment and state 120 Copyright IBM Corp. 2003, 2017 vii
viii z/os Planning and Operating Guide
About this document This document is intended for system programmers, application programmers, and operators who are responsible for customizing, writing applications for, and operating z/os DFSMS Transactional VSAM Services (). You can use this document to perform these tasks: v Plan for using to share VSAM data for concurrent batch updates v Install and operate Required product knowledge v Design and code applications to use v Diagnose and recover from problems. For information about accessibility features of z/os, for users who have a physical disability, see Appendix C, Accessibility, on page 123. Before you read this document, you should understand storage management concepts and be familiar with the virtual sequential access method (VSAM) information in z/os DFSMS Using Data Sets. To use this document effectively, you should also be familiar with the following IBM products, programs, and components: v CICS (Customer Information Control System) extends the availability of CICS by enabling multiple batch jobs and CICS to share access to the same data sets to update data as well as to read it. and CICS can use the same log of logs, a log stream that provides information for forward recovery programs. v CICS VSAM Recovery (CICSVR) CICSVR is a forward recovery program. It can use written to forward recovery logs by CICS or to recover VSAM data sets. v Data Facility Storage Management Subsystem data facility product (DFSMSdfp) DFSMSdfp provides functions for storage management, data management, program management, device management, and distributed data access. For information about DFSMSdfp, see z/os DFSMSdfp Storage Administration. v Hierarchical Storage Manager (DFSMShsm) DFSMShsm provides automatic space management and availability functions through a hierarchy of storage devices. For information about DFSMShsm, see z/os DFSMShsm Storage Administration. v Recoverable resource management services (RRMS) RRMS provides the context and unit-of-recovery management under which participates as a recoverable resource manager. Part of the operating system, RRMS comprises registration services, context services, and recoverable resource services (RRS). For information about RRMS, see z/os MVS Programming: Resource Recovery. v System logger uses the services of the system logger for logging. For information about the system logger, see z/os MVS Setting Up a Sysplex. Copyright IBM Corp. 2003, 2017 ix
z/os information This information explains how z/os references information in other documents and on the web. When possible, this information uses cross document links that go directly to the topic in reference using shortened versions of the document title. For complete titles and order numbers of the documents for all products that are part of z/os, see z/os Information Roadmap. To find the complete z/os library, go to IBM Knowledge Center (www.ibm.com/support/knowledgecenter/ssltbw/welcome). x z/os Planning and Operating Guide
How to send your comments to IBM We appreciate your input on this documentation. Please provide us with any feedback that you have, including comments on the clarity, accuracy, or completeness of the information. Use one of the following methods to send your comments: Important: If your comment regards a technical problem, see instead If you have a technical problem. v Send an email to mhvrcfs@us.ibm.com. v Send an email from the Contact z/os web page (www.ibm.com/systems/z/os/ zos/webqs.html). Include the following information: v Your name and address v Your email address v Your phone or fax number v The publication title and order number: z/os Planning and Operating Guide SC23-6877-30 v The topic and page number or URL of the specific information to which your comment relates v The text of your comment. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute the comments in any way appropriate without incurring any obligation to you. IBM or any other organizations use the personal information that you supply to contact you only about the issues that you submit. If you have a technical problem Do not use the feedback methods that are listed for sending comments. Instead, take one or more of the following actions: v Visit the IBM Support Portal (support.ibm.com). v Contact your IBM service representative. v Call IBM technical support. Copyright IBM Corp. 2003, 2017 xi
xii z/os Planning and Operating Guide
Summary of changes This information includes terminology, maintenance, and editorial changes. Technical changes or additions to the text and illustrations for the current edition are indicated by a vertical line to the left of the change. Summary of changes for z/os Version 2 Release 3 (V2R3) and its updates This information contains no technical changes for this release. Summary of changes for z/os Version 2 Release 2 (V2R2) The following changes are made for z/os Version 2 Release 2 (V2R2). Changed v Added security requirements for performing a retry of shunted transactions, in Monitoring and retrying shunted transactions on page 76. Deleted No content was removed from this information. Copyright IBM Corp. 2003, 2017 xiii
xiv z/os Planning and Operating Guide
Chapter 1. Understanding the environment Before you plan for z/os DFSMS Transactional VSAM Services (), you need to understand it. This topic provides an overview of in these topics: v Transaction processing and transactional recovery v VSAM record-level sharing (RLS) on page 6 v overview on page 14 v Context services and RRMS on page 20 Transaction processing and transactional recovery Different applications often need to share VSAM data sets. Sometimes the applications need only to read the data set. Sometimes an application needs to update a data set while other applications are reading it. The most complex case of sharing a VSAM data set is when multiple applications need to update the data set and all require complete data integrity. Consider these examples: v Transactions initiated by different applications might need to access the same VSAM data set at the same time. v A transaction might need to access a VSAM data set at the same time that a batch job is using the data set. Transaction processing provides functions that coordinate work flow and the processing of individual tasks for the same data sets. VSAM record-level sharing and provide key functions that enable multiple batch update jobs to run concurrently with CICS access to the same data sets, while maintaining integrity and recoverability. Terminology This topic introduces several new terms or uses terms with definitions that are specific to either VSAM record-level sharing (RLS) or. Atomic Backout When an application changes data in multiple resource managers as a single transaction, and all of the changes are accomplished through a single commit request by a syncpoint manager, the transaction is called atomic. If the transaction is successful, all the changes will be committed. If any piece of the transaction is not successful, then all of the changes will be backed out. An atomic instant occurs when the syncpoint manager in a two-phase commit process logs a commit record for the transaction. A request to remove all changes to resources since the last commit or backout or for the first unit of recovery, since the beginning of the application. Backout is also called rollback or abort. Any of these events can initiate backout: v A user request v An inability of a resource manager to commit resource changes Copyright IBM Corp. 2003, 2017 1
Understanding the environment Commit Context v An abnormal end of a user task while a transaction is in-flight A request to make all changes to recoverable resources permanent since the last commit or backout or, for the first unit of recovery, since the beginning of the application. Sometimes called a work context, a context is a representation of a work request, or part of a work request, in an application. A context might have a series of units of recovery associated with it. A context represents a work request in an application, and the life of a context consists of a series of units of recovery, with zero or one unit of recovery associated with the context at any point in time. Forward recoverable data set A data set that was defined with the LOG(ALL) attribute option. Forward recovery A process used to recover a lost data set. The data is recovered from a backup copy and all the changes that were made after the backup copy was taken are applied. The forward recovery process requires a log of the changes made to a data set, together with a date and time stamp. The log of changes is called the forward recovery log. Forward recovery log Log of logs A log that contains copies of records after they were changed. The forward recovery log records are used by forward recovery programs and products such as CICS VSAM Recovery (CICSVR) to reconstruct the data set in the event of hardware or software damage to the data set. A log that and CICS write to provide information to forward recovery programs such as CICS VSAM Recovery (CICSVR). The log of logs is a form of user journal that contains copies of the tie-up records that or CICS has written to forward recovery logs. This log provides a summary of which recoverable VSAM data sets that or CICS has used, when they were used, and to which log stream the forward recovery log records were written. If you have a forward recovery product that can utilize the log of logs, ensure that all CICS regions that share the recoverable data sets write to the same log-of-logs log stream. Nonrecoverable data set A data set for which no changes are logged. Neither backout nor forward recovery is provided. Primary system log The undo log. Recoverable data set A data set that can be recovered using backout or forward recovery processing, defined with the LOG parameter set to UNDO or ALL. Resource manager 2 z/os Planning and Operating Guide
Understanding the environment A subsystem or component, such as CICS, IMS, or DB2, or, that manages resources that can be involved in transactions. There are three types of resource managers: work managers, data resource managers, and communication resource managers. Secondary system log Shunt log Sync point The shunt log. The secondary system log, which contains entries that were shunted to the log when was unable to finish processing sync points. If a unit of work fails, it is removed (shunted) from the primary system log to the secondary system log, pending recovery from the failure. An end point during processing of a transaction. A sync point occurs when an update or modification to one or more of the transaction's protected resources is logically complete. A sync point can be either a commit or a backout. Syncpoint manager A syncpoint manager is a function that coordinates the two-phase commit process for protected resources, so that all changes to data are either committed or backed out. In z/os, RRS can act as the system level syncpoint manager. Two-phase commit Undo log The process used by syncpoint managers and resource managers to coordinate changes in an ACID transaction, which is a transaction that involves multiple resource managers using the two-phase commit process to ensure atomic, consistent, isolated, and durable properties. In the first phase of the process, resource managers prepare a set of coordinated changes, but the changes are uncommitted pending the agreement of all the resource managers involved in the transaction. In the second phase, those changes are all committed if the resource managers all agreed to them; or, the changes are all backed out if any of the resource managers failed or disagreed. Using the two-phase commit process, multiple changes across multiple resource managers can be treated as a single ACID transaction. The primary system log, which contains images of changed records as they existed prior to being changed. Backout processing uses the undo log to back out the changes that a transaction made to resources. Unit of recovery (UR) Unit of work A set of changes on one node that is committed or backed out as part of an ACID transaction. A UR is implicitly started the first time a resource manager touches a protected resource on a node. A UR ends when the two-phase commit process for the ACID transaction changing it completes. In, one or more logical units of recovery that are committed or backed out together as a transaction. Chapter 1. Understanding the environment 3
Understanding the environment Transaction processing Transaction processing provides data sharing of recoverable resources and ensures that data is synchronized. In z/os, transaction processing means that each logical unit of work runs as a single transaction. Products such as CICS, IMS, DB2, and provide a transaction-processing environment. An application that maintains a database must be capable of managing transactions. The transactions can arrive virtually simultaneously from clients. Transactional recovery Transactional recovery is the capability to isolate the changes made to recoverable resources by a transaction. This means that when the transaction makes a change, that change is seen only by that transaction. After the transaction reaches the commit point, all changes that the transaction made are visible to other transactions. If an application decides to back out a transaction rather than complete it, then the resource manager backs out all changes that the transaction made. This transactional recovery is a major part of transaction processing. For example, consider a context in which changes are made to two different records in a recoverable VSAM data set. A field in one record is decremented from 200 to 100. A field in the other record item is incremented from 700 to 800. Transactional recovery ensures that either both changes are made or neither change is made. When the application requests that the changes be committed, both changes are made atomically. If an application makes these changes to nonrecoverable data and the application or the system fails, one or both of the changes could be lost. Coordination of recovery requires three key programs and three key functions to coordinate the recovery of protected resources. Key programs: These three programs work together to coordinate the recovery of protected resources and the records within a recoverable VSAM data set: Application program The application program accesses protected resources and requests changes to the resources. Resource manager A resource manager controls and manages access to a resource. A resource manager is an authorized program that provides an application programming interface (API) that enables the application program to read and change a protected resource. The resource manager, in conjunction with the syncpoint manager, controls whether changes to resources are committed or backed out. For, the resources consist of records in recoverable VSAM data sets. Syncpoint manager A syncpoint manager uses a two-phase commit protocol to coordinate changes to protected resources, so that either all changes are made or none of the changes are made. Recoverable resource services (RRS) functions as the syncpoint manager. Key functions: These three programs work in concert to provide the three basic functions needed to implement transactional recovery: 4 z/os Planning and Operating Guide
Understanding the environment Resource locking This function provides serialized access to changed resources. Resource recovery logging This function enables a resource manager to keep a record of the changes made to recoverable resources by a transaction. Two-phase commit processing This function provides the services that ensure that a transaction appears as an atomic operation. A two-phase commit protocol and backout processing work together to ensure that either all changes that are made by a transaction are committed, or that all of the changes are backed out. Resource locking Locking serializes access to the records that are being changed. Locking at a more granular level, such as record level rather than at a control interval (CI) level, is done to minimize the need to wait for locks. Record locks are generally released at syncpoint time, when commit processing occurs and the unit of recovery ends. A transaction might be required to wait if it requests a change to a record that is locked by another transaction. This wait generally lasts until the lock-holding transaction reaches a sync point or the transaction reaches a timeout. Resource recovery logging Using the services of the system logger, logging provides a means of backing out the changes to resources. The undo log contains images of changed records as they existed prior to being changed. When forward recoverability is requested, records are also written to a forward recovery log, which contains copies of records after they were changed. In the event that a unit of work fails, a secondary system log is used. The failed unit of work is moved from the primary log to the secondary log, pending resolution of the failure by the user. Two-phase commit processing When an application is ready to commit or back out its changes, the application invokes RRS through its commit or backout interface. RRS invokes commit or backout interfaces of the participating resource managers to begin the two-phase commit protocol or to back out the changes. The two-phase commit protocol is a set of actions. The actions ensure that all participating resource managers either make all changes to the resources represented by a unit of recovery or make no changes to the resources. The protocol verifies that the all-or-nothing changes are made even if the application program, the system, RRS, or a resource manager fails. After an application program completes the set of updates to resources, it can invoke the RRS commit interface to make those changes permanent. The commit occurs in two phases. The first phase is called prepare, and the second phase is called commit. During the prepare phase, the commit coordinator, RRS, invokes the prepare exits of each of the resource managers. The resource managers determine whether they can make the changes permanent during the commit phase. This means that they must keep their backout information until the commit phase in case they are told to back out the changes. If any of the resource managers are unable to perform the prepare function, RRS directs all of the resource managers to back out the transaction. During the commit phase, the resource managers commit the changes represented by a unit of recovery and release any resource serialization. When all resource Chapter 1. Understanding the environment 5
Understanding the environment managers have completed the task, the application is notified, the unit of recovery is completed, and the two-phase commit process ends. After making a number of uncommitted changes, an application program can choose to invoke the RRS backout interface to reverse all the changes. In this case, RRS calls backout exits for each of the resource managers involved in the transaction. In this exit, the resource managers restore the resources to their prior state and release any resource serialization. VSAM record-level sharing (RLS) VSAM record-level sharing (RLS) extends the DFSMS storage hierarchy to support a data-sharing environment across multiple systems in a Parallel Sysplex. This support is primarily for VSAM data sets that online-transaction-processing applications use. Overview of VSAM RLS VSAM RLS processing involves support from multiple products: v CICS Transaction Server v CICS VSAM Recovery (CICSVR) v DFSMS VSAM RLS is a data set access mode that enables multiple address spaces, CICS application-owning regions on multiple systems, and batch jobs to access recoverable VSAM data sets at the same time. With VSAM RLS, multiple CICS systems can directly access a shared VSAM data set, eliminating the need to ship functions between the application-owning regions and file-owning regions. CICS provides the logging, commit, and backout functions for VSAM recoverable data sets. VSAM RLS provides record-level serialization and cross-system caching. CICSVR provides a forward recovery utility. The level of sharing that is allowed between applications is determined by whether or not a data set is recoverable. For example: v Both CICS and non-cics jobs can have concurrent read or write access to nonrecoverable data sets. However, there is no coordination between CICS and non-cics, so data integrity can be compromised. v Non-CICS jobs can have read-only access to recoverable data sets concurrently with CICS jobs, which can have read or write access. VSAM RLS uses a coupling facility to perform data set-level locking, record locking, and data caching. VSAM RLS uses the conditional write and cross-invalidate functions of the coupling facility cache structure, thereby avoiding the need for control interval (CI) level locking. VSAM RLS uses the coupling facility caches as store-through caches. When a control interval of data is written, it is written to both the coupling facility cache and to direct access storage device (DASD). This ensures that problems occurring with a coupling facility cache do not result in the loss of VSAM data. Data set types that VSAM RLS supports VSAM RLS supports access to these types of data sets: v Key-sequenced data set (KSDS) v Entry-sequenced data set (ESDS) v Relative-record data set (RRDS) 6 z/os Planning and Operating Guide
Understanding the environment v Variable-length relative-record data set cluster (VRRDS) VSAM RLS also supports access to a data set through an alternate index but does not support opening an alternate index directly in RLS mode. Also, VSAM RLS does not support access through an alternate index to data stored under z/os UNIX System Services. How CICS uses VSAM RLS The CICS file-control program is a transactional file system built on top of VSAM. Without VSAM RLS, the CICS file-control program must perform its own record-level locking. The VSAM data sets are accessed through a single CICS. Local data sets are accessed by the CICS application-owning region (AOR) that submits requests directly to VSAM. Remote (shared) data sets are accessed by the CICS AOR that submits (function ships) a data set control request to a CICS file-owning region (FOR) and by the FOR that submits a request to VSAM. Figure 1 illustrates the AOR, FOR, and VSAM request flow. CICS AORs function ship VSAM requests to access a specific data set to the CICS FOR that owns that data set. This distributed access form of data sharing has existed in CICS for some time. CICS AOR CICS AOR CICS AOR CICS AOR VSAM VSAM CICS FOR VSAM MVS 1 MVS n Figure 1. CICS VSAM non-rls access Figure 2 on page 8 illustrates how VSAM RLS enables multiple CICS transaction server AORs to access VSAM data sets for update while preserving data integrity. The updating regions can reside in any MVS image within a Parallel Sysplex. Each MVS image has one SMSVSAM server. Each AOR that needs to access the VSAM data in RLS mode connects automatically to the SMSVSAM server address space. VSAM RLS stores locking information in a coupling-facility structure that SMSVSAM owns. Chapter 1. Understanding the environment 7
Understanding the environment CICS AOR CICS AOR CICS AOR CICS AOR VSAM RLS Instance 1 VSAM RLS Instance n SMSVSAM Address space SMSVSAM Address space MVS 1 MVS 32 Coupling facility (CF) Figure 2. CICS VSAM RLS access The CICS file-control program provides commit, backout, and forward recovery logging functions for VSAM recoverable data sets. With VSAM RLS, CICS continues to provide the transactional functions. VSAM RLS itself does not provide the transactional functions but does provide record locking based on a coupling facility as well as coupling-facility data caching. Recoverable and nonrecoverable data sets VSAM RLS introduced a VSAM data set attribute named LOG. With this attribute, you can declare a data set as recoverable or nonrecoverable. For recoverable data sets, a log of changed records is maintained and used to commit or back out a transaction's changes to a data set. CICS maintains logs of its changes to recoverable data sets. The CICS file-control program supports recoverable and nonrecoverable data sets. The data set definition includes a recoverability attribute. You can specify these attribute options: LOG(NONE) Nonrecoverable. This option declares the data set to be nonrecoverable. CICS does not perform any logging of changes for a data set that has this attribute. Neither backout nor forward recovery is provided. LOG(UNDO) Recoverable. This option declares the data set to be backward recoverable. LOG(ALL) Recoverable. 8 z/os Planning and Operating Guide
Understanding the environment This option declares the data set to be both backward recoverable and forward recoverable. In addition to the logging and recovery functions provided for backout, CICS records the image of changes to the data set, after they were made. The forward recovery log records are used by forward recovery programs and products such as CICS VSAM Recovery (CICSVR) to reconstruct the data set in the event of hardware or software damage to the data set. You can use CICS recoverable file attributes that correspond to VSAM data set attributes. The file definition must match the data set attributes in the catalog. You can use the IDCAMS DEFINE and ALTER (LOG(xxx)) commands to set the data set attributes, either by running an IDCAMS job or by defining them in the SMS DATACLAS parameter. You can also use the BWO and LOGSTREAMID parameters in the IDCAMS commands. For CICS and access, you can define VSAM data sets as recoverable with the backup-while-open (BWO) parameter set to TYPECICS. Both CICS and can open a recoverable data set for output. You can open a non-rls data set in nonshared resources (NSR), local shared resources (LSR), or global shared resources (GSR) mode. When you open a data set in NSR, LSR, or GSR access mode, the recoverable attributes of the data set do not apply and are ignored. Thus, existing programs that do not use VSAM RLS access are not impacted by the recoverable data set rules. Related reading: v For more information about the IDCAMS DEFINE and ALTER commands, see z/os DFSMS Access Method Services Commands. v For more information about NSR, LSR, and GSR access mode, see z/os DFSMS Using Data Sets. CICS transactional recovery for VSAM recoverable data sets In most cases, changes to recoverable data sets made by a transaction remain invisible to other transactions until the modifying transaction reaches the commit. However, if you are using the no-read integrity (NRI) option, you might see uncommitted changes. Exclusive locks that VSAM RLS holds on the modified records cause other transactions that have read-with-integrity requests and write requests for these records to wait. After the modifying transaction is committed or backed out, VSAM RLS releases the locks and the other transactions can access the records. The CICS backout function removes changes made to the recoverable data sets by a transaction. When a transaction abnormally ends, CICS performs a backout implicitly. The commit and backout functions protect an individual transaction from changes that other transactions make to a recoverable data set (or other recoverable resource). How VSAM RLS provides functions The SMSVSAM server provides VSAM RLS functions. This server resides in a system address space. The address space is created and the server is started at MVS IPL time. VSAM internally performs cross-address space accesses and linkages between requestor address spaces and the SMSVSAM server address space. Chapter 1. Understanding the environment 9
Understanding the environment The SMSVSAM server owns two data spaces. One data space is called the SMSVSAM data space. It contains some VSAM RLS control blocks and a system-wide buffer pool. The other data space, named MMFSTUFF, is used by VSAM RLS to collect statistical information that is used to produce VSAM RLS system management facilities (SMF) 42 subtype 16-19 records. VSAM RLS is an access option interpreted at open time. To enable RLS access, specify the MACRF=RLS parameter in the ACB macro, or specify the RLS parameter in JCL. The RLS MACRF option is mutually exclusive with the MACRF NSR (nonshared resources), LSR (local shared resources), and GSR (global shared resources) options. Read sharing of recoverable data sets A non-cics application can open a recoverable data set for input in RLS mode. CICS provides the necessary transactional recovery for the write operations to a recoverable data set. Concurrently, non-cics applications can have the sphere open for read-rls access. VSAM RLS read integrity options VSAM RLS provides three levels of read integrity: 1. NRI (no read integrity ) This level tells VSAM not to obtain a record lock on the record accessed by a GET or POINT request. This avoids the overhead of record locking. This is sometimes referred to as a dirty read because the reader might see an uncommitted change made by another transaction. Even with this option specified, VSAM RLS still performs buffer validity checking and refreshes the buffer when the buffer is invalid. Thus, a sequential reader of a KSDS does not miss records that are moved to new control intervals by CI and CA splits. There are situations where VSAM RLS temporarily obtains a shared lock on the record even though NRI is specified. A shared lock is one in which several tasks can hold the lock. This happens when the read encounters an inconsistency within the VSAM sphere while attempting to access the record. 2. CR (consistent read) This level tells VSAM to obtain a shared lock on the record that is accessed by a GET or POINT request. It ensures that the reader does not see an uncommitted change made by another transaction. Instead, the GET or POINT request waits for the change to be committed or backed out. The request also waits for the exclusive lock on the record to be released. 3. CRE (consistent read explicit) This level has a similar meaning as CR, except that VSAM RLS holds the shared lock on the record until the end of the unit of recovery, or unit of work. CRE is not available to VSAM RLS (non-) non-cics applications. CRE is valid only when used by CICS or in mode because of the syncpoint nature of the locks. VSAM can only handle an end-of-transaction for CICS. This capability is also called a repeatable read. The record locks obtained by the VSAM RLS GET requests, with CRE option, inhibit the ability to update or erase the records by other concurrently executing transactions. However, the CRE requests do not inhibit other transactions from inserting other records. 10 z/os Planning and Operating Guide
Understanding the environment Read-sharing integrity across KSDS control-interval and control-area splits VSAM does not ensure read integrity across splits for non-rls access to a data set with cross-region share options 2, 3, and 4. If the application requires read integrity, the application must ensure it. When KSDS control-interval (CI) and control-area (CA) splits move records from one CI to another CI, the writer cannot invalidate the data and index buffers for the reader. This can result in the reader not seeing some records that were moved. VSAM RLS can ensure read integrity across splits. It uses the cross-invalidate function of the coupling facility to invalidate copies of data and index control intervals in buffer pools other than the writer's buffer pool. This invalidation ensures that all VSAM RLS readers, CICS and non-cics, are able to see any records moved by a concurrent CI or CA split. On each GET request, VSAM RLS tests the validity of the buffers, and if invalid, refreshes the buffers from the coupling facility or DASD. Read and write sharing of nonrecoverable data sets Nonrecoverable data sets do not participate in transactional recovery. Commit, backout, and forward recovery logging do not apply to these spheres. Because CICS and non-cics applications are not required to use transactional recovery, VSAM RLS allows concurrent read-and-write sharing of nonrecoverable data sets. Any application can open the sphere for output in RLS mode. VSAM RLS provides record locking and buffering across the CICS and non-cics read or write sharers of nonrecoverable data sets. VSAM RLS releases the record lock when the buffer that contains the change is written to the coupling-facility cache and DASD. This record locking differs from the case in which a CICS transaction modifies VSAM RLS recoverable data sets. In that case, the corresponding locks are held until the end of a recoverable unit of work. For a CICS transaction, however, the locks are not held until the end of a transaction in either of these cases: v The transaction is made up of multiple units of work. v The locks are released at a sync point (at the end of each logical unit of work). For sequential and skip-sequential processing, VSAM RLS does not write a modified CI until one of these actions occurs: v The processing moves to another CI. v The application issues an ENDREQ. If an application or the VSAM RLS server abnormally ends, the changes to nonrecoverable data sets that were buffered are lost. VSAM RLS permits read-sharing and write-sharing of nonrecoverable data sets across CICS and non-cics programs. However, most programs are not designed to tolerate this type of sharing. The absence of transactional recovery requires very careful design of the data and the programs. Non-RLS access to VSAM data sets VSAM RLS access does not change the format of the data in the VSAM data sets. The data sets are compatible for non-rls access. If you set the cross-region share option to 2, you can issue a non-rls open-for-input request while the data set is already open for VSAM RLS access. However, a non-rls open-for-output request Chapter 1. Understanding the environment 11
Understanding the environment fails. If the data set is already open for non-rls output, an open for VSAM RLS fails. Therefore, at any point in time, a data set (sphere) can be open for non-rls write access or open for VSAM RLS access. CICS and VSAM RLS provide a quiesce function to assist in the process of switching a sphere from CICS RLS usage to non-rls usage. Recommendation: Be careful about quiesce with a path name; always use a base name. Related reading: For information about the quiesce function, see Appendix A, Quiescing a data set, on page 117. Differences between VSAM RLS access and non-rls access This topic describes the differences between VSAM RLS access and non-rls access. 12 z/os Planning and Operating Guide Share options For non-rls access, VSAM uses the share options settings to determine the type of sharing allowed. VSAM provides full read and write integrity for the VSAM RLS users, but does not provide read integrity for the non-rls user. You cannot specify a non-rls open-for-output request when the data set is already opened for VSAM RLS. VSAM RLS provides read sharing and write sharing for multiple users; it does not use share option settings to determine levels of sharing. When you request an RLS open and the data set is already open for non-rls input, VSAM does check the cross-region setting. If the share option is 2, the data set can be opened in RLS mode. The open fails if you use any other share option, or if the data set is opened for non-rls output. Locking Non-RLS access provides local locking (within the scope of a single buffer pool) at the VSAM CI level. A locking contention can result in an exclusive control conflict error response to a VSAM record management request. All SMSVSAM servers (one per MVS image) use the coupling facility for locking.when contention occurs on a VSAM record, the request that encountered the contention waits for the contention to be removed. The lock manager provides deadlock detection. When a lock request is in deadlock, the request is rejected resulting in the VSAM record management request completing with a deadlock error response. VSAM RLS supports a timeout value that can be specified through the request parameter list (RPL), in the PARMLIB member, or in the JCL. CICS provides two places where you can supply a timeout value: v By transaction, you can specify the DTIMOUT value in the transaction definition. v By CICS region, you can use the FTIMOUT system initialization value. CICS uses DTIMOUT when it is supplied; otherwise, it uses FTIMOUT. This ensures that a transaction does not wait indefinitely for a lock to become available. VSAM RLS uses a timeout function of the lock manager. Lock Retention: VSAM RLS uses share and exclusive record locks to control access to the shared data. An exclusive lock ensures that a single user is updating a
Understanding the environment specific record. The exclusive lock causes a read-with-integrity request for the record by another user, such as a CICS transaction or non-cics application, to wait until the update is complete and the lock is released. Failure conditions can delay completion of an update to a recoverable data set. This occurs when a CICS transaction enters in-doubt status. This means that CICS waits for a distributed unit of work to complete before CICS can back out or commit the unit of work. Therefore, the recoverable records modified by the transaction must remain locked. Failure of a CICS AOR also causes the current transaction's updates to recoverable data sets to not complete. They cannot complete until CICS restarts the AOR. When a transaction enters an in-doubt state or a CICS AOR abnormally ends, exclusive locks on records of recoverable data sets held by the transaction must remain held. However, other users waiting for these locks should not continue to wait. The outage is likely to be longer than the user would want to wait. When these conditions occur, VSAM RLS converts these exclusive locks into retained locks. Exclusive and retained locks are not available to other users. When another user encounters a lock contention with an exclusive lock, the user's lock request waits. When another user encounters a lock contention with a retained lock, the lock request is immediately rejected with a retained lock error response. This causes the VSAM record management request, which produced the lock request, to fail. Non-RLS access while retained locks exist: Retained locks are created when a failure occurs. The locks need to remain until completion of the corresponding recovery. The retained locks have meaning only for RLS access. Lock requests issued by RLS access requests can encounter the retained locks. Non-RLS access does not perform record locking and does not encounter the retained locks. To ensure integrity of a recoverable sphere, VSAM does not permit non-rls update access to the sphere while retained locks exist for that sphere. An installation might need to run a non-cics application that requires non-rls update access to the sphere. VSAM RLS provides an IDCAMS command that sets the status of a sphere to enable non-rls update access to a recoverable sphere while retained locks exist. This command does not release the retained locks. VSAM informs the CICS transaction servers that hold the retained locks when they later open the sphere with RLS. Related reading: For information about non-rls access to data sets that have retained locks, see Appendix B, Accessing data sets that have retained locks or lost locks, on page 119. Requirements for VSAM RLS request execution mode When a program makes a request while a data set is open in RLS mode (OPEN, CLOSE, or record management request), the program must be running in the following execution mode, with the listed constraints: v Task mode (not SUB mode) v Address space control=primary v Home address space=primary address space=secondary address space v No functional recovery routine (FRR) is in effect, but an ESTAE routine might be in effect. Chapter 1. Understanding the environment 13
Understanding the environment The VSAM RLS record management request task must be the same task that opened the ACB, or the task that opened the access method control block (ACB) must be in the task hierarchy. VSAM options that RLS and do not support VSAM RLS does not support these options and capabilities: v Linear data sets v Addressed access to a KSDS v Control interval processing (CNV or ICI) to any VSAM data set type v User buffering (UBF) v Clusters that have been defined with the IMBED option v Key range data sets v Temporary data sets v GETIX and PUTIX requests v DFSMS checkpoint/restart facility v ACBSDS (system data set) specification v Hiperbatch overview v Catalogs, VVDS, JRNAD exit, any AMP=JCL parameters v Data that is stored under UNIX System Services In addition, VSAM RLS does not support these usages: v If the caller, executing in cross-memory mode, issues a request, RLS does not honor the request. v When accessing a VSAM data set using the ISAM compatibility interface, you cannot specify RLS access. v You cannot open individual components of a VSAM cluster for RLS access. v You cannot specify a direct open of an alternate index for RLS access, but you can specify an RLS open request of a data set through an alternate index path. v You cannot specify an RLS open request to implicitly establish position to the beginning of the data set. For sequential or skip-sequential processing, you must specify a POINT or GET DIR, NSP request to establish position. Without, a CICS system might have been available only during normal business hours. After business hours, the CICS system or application would be shut down for the supporting batch work to run. As soon as CICS stopped, backups were taken of key data sets as a point of recovery. Batch jobs could then be scheduled to run. If several jobs updated the same data set, they ran in sequence because they could not update the data set at the same time. After the updates were complete, a job would read the updated data and produce reports, and another backup would be taken. Finally, CICS could be restarted and become active again. However, the need to extend the availability of CICS has increased due to growing business volume. is an enhancement to VSAM RLS access that enables multiple batch update jobs and CICS to share access to the same data sets. provides two-phase commit and backout protocols, as well as backout logging and forward recovery logging. 14 z/os Planning and Operating Guide