3.1 Function description

---

3.1 Function description

Before VSAM Record Level sharing, recoverable files could only be opened by a single CICS region, and all requests for file updates had to be routed to that lone region.

Figure 3-1: VSAM data sharing before Record Level Sharing (RLS)

With the advent of VSAM Record Level Sharing, multiple CICS regions could access recoverable VSAM data sets simultaneously; in this configuration, the SMSVSAM address space provided the locking functions to ensure proper serialization while the CICS regions performed the logging. Since the logging was encapsulated within CICS, batch jobs could not update recoverable VSAM data sets while the data sets were open for update in the CICS regions.

Figure 3-2: CICS/VSAM Record Level Sharing

Transactional VSAM extends the data sharing capability of VSAM RLS to batch. Multiple batch jobs can now update recoverable VSAM data sets while the data sets are open for update to the CICS regions. SMSVSAM still provides the locking, and the CICS regions still provide the logging for the updates made to the data sets by CICS transactions, and now DFSMStvs provides the logging for updates made by batch jobs.

Figure 3-3: Transactional VSAM and CICS

Transactional VSAM provides two-phase commit for updates to VSAM files by registering with Resource Recovery Services (RRS). Since Transactional VSAM uses RRS, all the documentation about this function tends to use the RRS terminology for recovery services. For that reason, what is normally referred to as a Unit of Work (UOW) in CICS manuals is called a Unit of Recovery (UR) in DFSMStvs documentation. A UR is the set of changes made by a particular task until the task invokes either the RRS Commit or RRS Backout, at which time all the changes are either committed to the VSAM data sets or backed out. The commit can either be explicit or implicit (at the end of the step). If the batch job does not issue any explicit commits, the entire step is considered a single UR. Any committed changes are not backed out if there is a subsequent Backout call; only those changes made since the previous commit are backed out.

To keep track of all the before-copy images that might have to be restored to the VSAM data sets (which is what happens when a UR indicates that it wants to "backout" the changes since the last commit point), Transactional VSAM needs to record the before-copy images.

Under normal circumstances, there is only one copy of Transactional VSAM on each image within the sysplex (for exceptions to the practice, refer to DFSMStvs Administration Guide, GC26-7483), and each instance of Transactional VSAM records the before-copy images for URs executing on its system into a unique undo log. For performance reasons, the one logical undo log consists of two physical log streams, referred to as IGWLOG.SYSLOG and IGWSHUNT.SHUNTLOG. As the names imply, IGWLOG.SYSLOG is the primary repository for before-copy images while IGWSHUNT.SHUNTLOG is the repository for information about shunted URs.

3.1.1 Log stream usage

Transactional VSAM directly uses three types of log streams: the undo log, forward-recovery and the log-of-logs.

The Undo log

Each instance of TVS (and normally there is only one instance on each image within the sysplex on which you want to access recoverable VSAM data sets from batch) requires its own unique undo log. The undo log consists of two physical log streams, referred to as IGWLOG.SYSLOG and IGWSHUNT.SHUNTLOG. Each instance of Transactional VSAM has a unique name (for more information on how to define this name, see 3.2.1, "Subsystem definitions" on page 88), and this name is incorporated into the log stream names to ensure that each instance of Transactional VSAM gets a unique set of Undo log stream. The complete names are:

IGW&tvsname.IGWLOG.SYSLOG and IGW&tvsname.IGWSHUNT.SHUNTLOG, where &tvsname is the unique name of the instance of Transactional VSAM.

DFSMStvs writes the 'before' image of a record in a recoverable VSAM data set to the IGWLOG.SYSLOG log stream. If an in-flight UR issues a backout or the UR abends, DFSMStvs uses the data in the Undo log stream to restore the original contents of the record to the VSAM data set.

DFSMStvs moves data from IGWLOG.SYSLOG to IGWSHUNT.SHUNTLOG in two circumstances:

• If a UR updates a record in a recoverable VSAM data set, but then fails to make an update to another record in recoverable VSAM data set within one activity keypoint, DFSMStvs moves the chain of log records for that UR since the last syncpoint (or the start of the UR) from IGWLOG.SYSLOG to IGWSHUNT.SHUNTLOG.

• If a UR goes into INDOUBT status, when a resource manager fails between the two phases of the two-phase commit.

These two log streams are active log streams. This means that DFSMStvs manages the content of the log streams and deletes data from them as it is no longer required, and this process is referred to as log tail management. For more information on the difference between active and funnel-type log streams, refer to "How System Logger is used" on page 3.

If you run Transactional VSAM on three systems within your sysplex, you need to define at least six log streams: two for each of the three instances with a total of three IGWLOG.SYSLOG log streams and three IGWSHUNT.SHUNTLOG log streams.

The undo log streams are required. Transactional VSAM attempts to connect to the undo log streams when it initializes (either during the IPL of the system or in response to a V SMS,TRANVSAM(tvsname),ENABLE command). If the connection to either one of the log streams is not successful, Transactional VSAM does not initialize.

The forward recovery log streams

When you use IDCAMS to define a data set, the LOG keyword determines the "recoverability" of the data set. There are three possible values for LOG:

• LOG(NONE)

  The data set is non-recoverable. Uncommitted changes cannot be backed out, and the data set cannot be reconstructed in case of a failure.

• LOG(UNDO)

  The data set is recoverable. Uncommitted changes may be backed out (as either a result of an explicit RRS Backout request or the step ending abnormally); however, the data set cannot be reconstructed in case of a failure.

• LOG(ALL)

  The data set is recoverable. Uncommitted changes may be backed out. In addition, Transactional VSAM records the after-images (the updated version of the record or an indication that a record was deleted) in the forward recover log stream. If the data set fails, a separate product like CICS/VR can rebuild the data set by recalling the last back-up version of the data set and reapplying all the changes recorded in the forward recovery log streams.

  If you code LOG(ALL), you must also specify the name of the forward recovery log stream using the LOGSTREAMID keyword.

If you define a data set with a forward recovery log stream, both CICS TS and Transactional VSAM write to the same log stream. Since both parties contribute to the same log stream, all the updates to the data set are used to rebuild a failed data set.

The forward recovery log streams are funnel-type log streams. This means that Transactional VSAM and CICS TS simply add data to the log streams; they never delete any data from these log streams.

The forward recovery log streams are required for data sets defined with LOG(ALL). If Transactional VSAM cannot connect to the log stream associated with a given data set, the OPEN for the data set fails. Each instance of Transactional VSAM in the sysplex connects to the forward recovery log stream associated with a data set as part of the OPEN processing. Similarly, when the last data set associated with a given log stream is closed, Transactional VSAM disconnects from the forward recovery log stream.

CICS TS connects to and disconnects from the forward recovery log streams in a similar manner (refer to "Log stream usage" on page 138), however, there is one difference. The recoverable data sets tend to remain open during the life of the CICS region. With Transactional VSAM, the connections to the forward recovery log streams might be made and broken more frequently depending on the data set pattern of reference and the number of batch jobs that run concurrently. If in your installation, the data sets are only used by batch jobs (and are not opened to CICS regions) and the forward recovery log streams are defined to use staging data sets, you might see message IGW838I, indicating a temporary delay while the staging data set is formatted, frequently as the connections come and go every time the data set opened and closed by the batch jobs.

The log-of-logs

The log-of-logs log stream is optional; you do not need to define or use a log-of-logs log stream. The log-of-logs log stream houses all the tie-up records, which indicate when data sets are opened and closed. The forward recovery product (like CICS/VR) can use this information to reconstruct a damaged data set more quickly.

If you choose to use a log-of-logs log stream, you should define the same log stream to both Transactional VSAM and CICS TS. For more information on defining the log-of-logs log stream to Transactional VSAM, refer to 3.2.1, "Subsystem definitions" on page 88. For details on how to define the log-of-logs log stream to CICS TS, see 5.2.2, "System Logger definitions" on page 144.

The log-of-logs log stream is a funnel-type log stream. This means that Transactional VSAM and CICS TS simply add data to the log stream; they never delete any data from this log stream.

The log-of-log log stream is optional; Transactional VSAM connects to the log-of-logs when it initializes (either during the IPL or in response to the V SMS,TRANVSAM(tvsname),ENABLE command), and if the connection to the log stream is unsuccessful, Transactional VSAM continues to initialize without a log-of-logs.

Indirect use of log streams

Transactional VSAM registers with RRS and uses RRS services. Since RRS maintains its own log streams, Transactional VSAM indirectly contributes to the RRS-related log streams. For more information on RRS, see "Resource Recovery Services" on page 218.

3.1.2 Criticality/persistence of data

The three types of log streams that Transactional VSAM uses each has its own level of criticality, ranging from low through medium to high. At the low end is the log-of-logs log stream. Since this log stream only contains data that makes the recovery of a failed data set quicker, this log stream (and the data within it) can be lost without adversely effecting overall system performance or functionality.

The next level of criticality is for the forward recovery log streams. If a forward recoverable data set should fail, the data in the forward recovery log stream is vital to the restoration of that data set. Without all the forward recovery images, CICS/VR or similar product cannot rebuild the data set from the last back up copy of the failed data set. For this reason, if a forward recovery log stream fails (or is inaccessible or simply does not exist), Transactional VSAM prohibits updates against the data set and CLOSEs the data set. The installation then must take a fresh back-up and rebuild the log stream.

Even though the data in the undo log stream is only maintained while it might be needed to perform a UR backout, the two log streams that comprise the undo log (IGWLOG.SYSLOG and IGWSHUNT.SHUNTLOG) are absolutely critical to the operation of Transactional VSAM. Without those two log streams, Transactional VSAM cannot function and terminates.

3.1.3 Log streams sizing

Log stream data exists in temporary or interim storage, and in permanent or hardened storage. This section discusses sizing of the interim storage in order to achieve the best log stream and overall system performance.

There are many variables which must be taken into account when sizing a log stream, making it difficult to get it perfect the first time around. Once an initial size is determined, the log stream performance must be monitored using the SMF Type 88 records produced by the System Logger, and adjustments made, as required.

Understanding the volume and rate data is written is critical when sizing the log stream interim storage.

Interim storage and duplexing

Interim storage can be viewed as the location where the log stream data can be accessed quickly - without I/O to long term DASD (offload data sets).For a CF-Structure log stream, interim storage is usually a CF structure. For a DASD-only log stream, interim storage is contained in local storage buffers. Local storage buffers are dataspaces associated with the System Logger address space, IXGLOGR.

Each time a log block is written to a log stream, the System Logger automatically creates a duplicate copy of the data. For DASD-only log streams, the data is written to the local buffers (dataspace) and duplexed to the staging data set. For a CF-Structure log stream, the data will also be duplexed to the local buffers unless a staging data set is being used or if CF-structure duplexing is being used. A staging data set is when the CF is volatile or is in a failure dependent configuration and STG_DUPLEX(YES) DUPLEXMODE(COND) has been specified in the log stream definitions, or if STG_DUPLEX(YES) DUPLEXMODE(UNCOND) was specified.

A CF is considered volatile when it no longer has a battery backup. A CF is considered to be in a failure-dependent environment when the CF LPAR and the z/OS LPAR are in the same physical box; that is, there is a single point of failure. The concept of failure independence as it relates to System Logger is discussed in more detail in 2.8.1, "Failure independence" on page 65.

The staging data set used to duplex a CF-Structure log stream must be large enough to hold the largest amount of data which can be contained in the CF log stream interim storage (that is, the part of the log stream that is currently in the structure in the CF).

With the exception of CF-Structure log streams duplexed to either staging data sets or CF-managed duplexed structures, the dataspace will contain the duplex copy of all data resident in interim storage for all active log streams in the z/OS image.

To optimize use of the dataspace, and reduce the potential impact on storage use, residency time of the data should be kept to minimum. For the TVS Undo log (IGWLOG and IGWSHUNT), the data should be retained in interim storage until the associated UOW commits or backs out. For forward-recovery log streams, all data is offloaded to the offload data sets so the interim storage (CF structure or staging data set) should be sized to provide minimal residency time.

Offload data sets contain data which has been offloaded from interim storage. Data is offloaded from interim storage as part of the offload process, usually initiated when the HIGHOFFLOAD threshold is reached. Offload data sets may be subsequently archived using a product like DFSMShsm™. For a compete description of offload processing, refer to "Offload processing" on page 57.

Sizing interim storage

Note 

Remember, sizing of a log stream is an iterative process. Unfortunately, it is difficult to get it perfect the first time.

Once a starting size has been identified, the SMF Type 88 records should be used to tune the log stream based on the activity during the key processing intervals.

When calculating the size of interim storage for a log stream, the following log stream characteristics are important:

The number of IXGWRITE requests issued during a specified time interval.

• TVS requests the System Logger to record information on a log stream using an IXGWRITE call. The number of IXGWRITE requests is found in the SMF Type 88 records for the log stream (SMF88LWB or IXGWRITES).

• Rate of IXGWRITE calls - LGSWRITES/interval in seconds.

• Number of bytes written in the interval. The number of bytes written is found in the SMF88 (SMF88SWB) records written for the log stream.

• Number of bytes written per IXGWRITE or average buffer size. Bytes written divided by the number of write requests (LGSBYTES/LGSWRITES). Reported as the average buffer size in the SMF 88 reports produced with IXGRPT1.

• HIGHOFFLOAD percentage. This determines at what point the offload starts and also determines how much space is left between when the offload starts and when the log stream fills.

• The number of log stream deletes for IGWLOG and IGWSHUNT found in the SMF88 (SMF88SII and SNF88SAI). This is a reflection of the number of times DFSMStvs performed log tail management. Log tail management is the process where DFSMSTVS issues an IXGDELET call to indicate records which are no longer required for recovery and may be deleted. Log tail management reduces the size required for interim storage without having to offload the data.

• Number of offloads during interval. Provided in the SMF Type 88 records (SMF88EO).

Each TVS Undo log stream requires enough storage to hold the data written in an Activity KeyPoint (AKP) interval + the duration of the longest UOW + a buffer of at least 25%. Structures should be large enough to hold the sum of the data written for all connected log streams in the interval.

Undo log streams

The methodology used to perform an initial sizing for the Undo log streams would follow the process listed below. Using this method may result in oversizing the log stream which should then be reduced based on the activity reported in the SMF Type 88 records. It is also difficult to size the Undo log stream initially since the all the sizing considerations are usually done against the current batch window and later on batch might spread over a different schedule because of the TVS enhancement changing completely the planned requirement. For this reason, it is even more important, after an initial consideration, to evaluate the configuration through the SMF88 records.

As of now, there are no tools to help size the Undo log stream. A suggested approach is to use the SMF64 at CLOSE time to obtain the number of writes against the data set. Multiple the number for the average recordsize and divide for the Activity Key Point: this should give you an idea of how much storage you should need in the interim media for this data set. If you sum all the data sets open in a certain interval, this should give you an idea of how much total storage you need for your Undo log stream.

Forward Recovery log streams

The forward recovery log streams are funnel-type log streams (all data is offloaded). Oversizing forward recovery log streams increases the working set of the System Logger and may result in overall system paging problems. Usually, an installation already has these log stream because of the CICS. You probably need to monitor and re-evaluate the size with SMF88 since the activity might increase against these log stream.

For details, see CICS section, "Log stream sizing" on page 164.

---