Using the log stream copy utility to copy your MVS log streams

When VSAM spheres are updated by CICS® applications and batch applications, log records are written to MVS log streams to record this activity.

If a failure occurs, CICS VR uses these log records to forward recover the VSAM spheres. You must create a copy of these log records so that CICS VR can also perform forward recovery at the remote recovery site.

The CICS VR log stream copy utility copies log records from your MVS log streams to a sequential access method (SAM) data set. You cannot use IDCAMS or CICS VR archive to copy an MVS log stream. You can create up to nine sequential data set copies from an MVS log stream in one LOGSTREAMCOPY job, but CICS VR only records the data set name allocated to the DWWCOPY1 ddname in the RCDS. Therefore, be sure to send the data set allocated to the DWWCOPY1 ddname to the remote recovery site. Then, use the CICS VR panel interface to create and submit a recovery job for the VSAM spheres at the remote recovery site.

Use a production planning system, such as Tivoli® Workload Scheduler for z/OS®, to submit log stream copy jobs and send the SAM log stream copy data sets to your remote recovery site at regularly scheduled times.

This sample JCL that is used to run the CICS VR log stream copy utility, shows a sample LOGSTREAMCOPY job that makes one copy of the specified MVS log stream.

Figure 1. Sample JCL to run the CICS VR log stream copy utility

//JOB1     JOB  ACCOUNTING INFORMATION,REGION=0M
//COMMAND  EXEC PGM=DWWLC                             (1)
//STEPLIB  DD   DSN=DWW.SDWWLOAD,DISP=SHR             (2)
// DD DSN=DWW.SDWWLENU,DISP=SHR
//DWWCOPY1 DD   DSN=USER1.DWWCOPYL,                   (3)
//              UNIT=3590,VOL=SER=TAPE04,
//              LABEL=(1,SL),DISP=(NEW,KEEP)
//DWWCON1  DD   DSN=DWW.DWWCON1,DISP=SHR              (4)
//DWWCON2  DD   DSN=DWW.DWWCON2,DISP=SHR
//DWWCON3  DD   DSN=DWW.DWWCON3,DISP=SHR
//DWWMSG   DD   SYSOUT=*                              (5) 
//DWWPRINT DD   SYSOUT=*                              (6)
//DWWIN    DD   *                                     (7)
           LOGSTREAMCOPY    -                         (8)
             NAME(CICSVR.MVSLOG)   -
             SELECT(CICSVR)        -
             COPIES(1)      -
             MOD 
/*
//

Here is a description of the numbered statements:

The program to be run is DWWLC. The prefix DWW always refers to a component of CICS VR.
This statement supplies the name of the CICS VR load library.
This is the DWWCOPY1 DD statement. It specifies the SAM data set USER1.DWWCOPYL, in which the log stream copy is stored. USER1.DWWCOPYL is allocated on a standard label 3590 volume TAPE04 and kept.
DWWCON1–DWWCON3 defines the three recovery control data sets. If you are running the CICS VR server, you must use the hlq.slq that was defined in the IGDSMSxx PARMLIB member for these data sets.
DWWMSG defines the output data set that contains the CICS VR messages. This is usually defined as a SYSOUT data set.
The DCB parameters for this data set are RECFM=FBA and LRECL=133. The block size can be provided on the DWWMSG DD statement and must be a multiple of 133. The default is 27930.
DWWPRINT defines the output data set that contains the reports produced by CICS VR. This is usually defined as a SYSOUT data set.
The DCB parameters for this data set are RECFM=FBA and LRECL=133. The block size can be provided on the DWWPRINT DD statement and must be a multiple of 133. The default is 27930.
DWWIN defines the data set that contains the CICS VR commands. You can either specify a sequential data set with 80-byte fixed-length records, or include the CICS VR commands in-stream.
The log stream copy utility processes an MVS log stream called CICSVR.MVSLOG. The log records produced by CICS and by CICS VR (for VSAM batch logging) are copied from CICSVR.MVSLOG. One copy of the log is requested; the log records are copied and added to the end of the DWWCOPY1 data set.

Once set up, this job can be run over and over again to update the copy of the log stream.

This log stream copy report shows the log stream copy report, followed by descriptions of the fields in the report.

Figure 2. Log stream copy report

CICSVR -  MVS LOG STREAM COPY UTILITY        DATE : 01/06/08     TIME : 12:51:13     PAGE : 1

STATISTICS FROM THE MVS LOG STREAM COPY UTILITY
===============================================

MVS LOG STREAM NAME    : CICSVR1.MVSLOG
FIRST TIME GMT         : 01.159 12:39:09
LAST TIME GMT          : 01.159 12:39:44
FIRST TIME LOCAL       : 01.159 13:39:09
LAST TIME LOCAL        : 01.159 13:39:44
FIRST BLOCK ID         :              5965196
LAST BLOCK ID          :             11890088
NUMBER OF BLOCKS READ  :                  148
NUMBER OF CICSVR BLOCKS:                  148
NUMBER OF BLOCKS COPIED:                  148
TYPE OF COPY           : ALL
OUTPUT LOG NAME(S)     : CICSVR1.MVSLOG.COPY
PERFORMED ACTIONS      : COPY

MVS log stream name

The name of the MVS log stream.

First time GMT

The first time recorded on the MVS log stream in GMT format.

Last time GMT

The last time recorded on the MVS log stream in GMT format.

First time LOCAL

The first time recorded on the MVS log stream in local time format.

Last time LOCAL

The last time recorded on the MVS log stream in local time format.

First block ID

The first block ID on the MVS log stream.

Last block ID

The last block ID on the MVS log stream.

Number of blocks read

The number of blocks read from the MVS log stream.

Number of CICS blocks read

The number of CICS and CICS VR-specific blocks read from the MVS log stream.

Number of blocks copied

The number of blocks copied to the SAM copy of the MVS log stream.

Type of copy

The type of copy requested (CICS AND CICSVR or ALL).

CICS AND CICSVR specifies records produced by CICS and CICS VR batch logging were copied from the MVS log stream. ALL specifies all records were copied from the MVS log stream.

Output log name(s)

The name of the SAM copy data set.

Performed actions

The action that the log stream copy utility has performed on the log stream:

COPY: The log stream blocks were successfully copied.
COPY and DELETE: The log stream blocks were successfully copied and the log stream tail was deleted.
DELETE: The “start of copy” cursor was repositioned to the browse cursor and the log stream tail up to the browse cursor was deleted.
NO ACTIONS: No actions were performed on the log stream, or the only action was that the “start of copy” cursor was repositioned to the browse cursor.

On rare occasions, you might want to make a copy of a portion of a log stream. Use the STARTTIME and STOPTIME keywords, the STARTBLKID and STOPBLKID keywords, or the STARTTOD and STOPTOD keywords.

With the STARTTIME and STOPTIME keywords, CICS VR copies records from the time specified on the STARTTIME keyword up to the time specified on the STOPTIME keyword, as shown in the following example.

Figure 3. Sample LOGSTREAMCOPY command with STARTTIME and STOPTIME

      LOGSTREAMCOPY NAME(CICSVR1.MVSLOG)  -    
           SELECT(ALL)                    -    
           COPIES(3)                      -    
           STARTTIME(96159/07:30:00,GMT)  -    
           STOPTIME(96249/07:30:00,GMT)   -    
           MOD

The LOGSTREAMCOPY command in the previous example specifies that CICS VR makes three copies of the MVS log stream. These copies are made to the data sets that are specified on the ddnames DWWCOPY1, DWWCOPY2, and DWWCOPY3. Records are copied to the end of the data sets that are specified in the DWWCOPYn ddnames. All records are copied from the MVS log stream between the start and the stop time specified in the command.

To specify the start and the stop time in a more granular format, you can use the STARTTOD and STOPTOD keywords in place of STARTTIME and STOPTIME.

Use this method only when you need a one-time-copy for test data. Do not use it for copying consecutive portions of the log, because the time values are not precise enough to prevent gaps in the log.

With the STARTBLKID and STOPBLKID keywords, CICS VR copies records from the STARTBLKID to the STOPBLKID. Use the CICS DWWJUP program to find out the MVS block identifier you can use as the STARTBLKID and the STOPBLKID. This method is not easy to use and is not recommended. If you require more information on DWWJUP, see the PRINT: print information about records logged on an MVS log.

You can use the DELETE keyword to avoid log stream overloading by deleting the log stream blocks after they have been successfully copied. The LOGSTREAMCOPY command specifies that CICS VR makes one copy of the specified MVS log stream and deletes copied blocks.

Log stream block deletion is performed only if CICS VR permits it; see LOGSTREAMCOPY: Copy an MVS log stream.

Figure 4. Sample LOGSTREAMCOPY command with DELETE

         LOGSTREAMCOPY NAME(CICSVR1.MVSLOG)  -
              SELECT(ALL)                    - 
              COPIES(1)                      - 
              STOPTIME(96249/07:30:00,GMT)   - 
              DELETE                         - 
              MOD

The SETBRCUR, REPBRCUR and MOVBRCUR keywords provide another method for automatic continuous log stream copying, as you do not need to include date and time information in your log stream copy job. Using these keywords ensures that the beginning and end of your copy are precisely defined, and the copy is repeatable.

Note that log streams to be processed in this way must be defined as AUTODELETE(NO) RETPD(0), to avoid unexpected loss of data.

You must not run more than one job per log stream using a SETBRCUR, REPBRCUR or MOVBRCUR keyword with the same RCDS at any one time in your SYSPLEX. If you run more than one such job simultaneously, they update the same cursor in the CICS VR RCDS, and then your copy would not be repeatable. You can run jobs that use only non-cursor related keywords of the LOGSTREAMCOPY command with the same RCDS at the same time as a job using one of the cursor-related keywords (SETBRCUR, REPBRCUR or MOVBRCUR), as the other log stream copying keywords do not affect the position of the cursors.

The following sequence is recommended for using the SETBRCUR, REPBRCUR and MOVBRCUR keywords for log stream copying:

Run a job using the SETBRCUR keyword, to copy a set of log records, record this copy in the RCDS, and then set the browse cursor at the last record copied. The following LOGSTREAMCOPY command does this:
Figure 5. Sample LOGSTREAMCOPY command with SETBRCUR
```
         LOGSTREAMCOPY NAME(CICSVR1.MVSLOG)  -
              SELECT(ALL)                    - 
              SETBRCUR
```
If the job fails, you can repeat the job with the SETBRCUR keyword.
If you want to copy the same set of records again, for example, if you need more copies in addition to 9 copies provided by the log stream copy utility, run a job using the REPBRCUR keyword. This keyword does not change the position of any cursors. The following LOGSTREAMCOPY command does this:
Figure 6. Sample LOGSTREAMCOPY command with REPBRCUR
```
         LOGSTREAMCOPY NAME(CICSVR1.MVSLOG)  -
              SELECT(ALL)                    - 
              REPBRCUR
```
If the job fails or you want to copy the same set of log records again, you can repeat the job using the REPBRCUR keyword.
To repeat the whole copying process so far for any reason, you can now start again at Step 1 with the SETBRCUR keyword. If you restart the process, any new data that has been placed on the log stream can be picked up.
If the copying process has been successful, you can run a job using the MOVBRCUR keyword to set the start of copy cursor at the end of the records you have just copied. The following LOGSTREAMCOPY command does this:
Figure 7. Sample LOGSTREAMCOPY command with MOVBRCUR
```
         LOGSTREAMCOPY NAME(CICSVR1.MVSLOG)  -
              SELECT(ALL)                    - 
              MOVBRCUR
```
If you are certain that you no longer need the records that you have copied, run a job using both the MOVBRCUR and DELETE keywords, to delete the records that you have copied. Make sure that CICS VR permits the log stream deletion.
If the job fails, you can repeat the job using the MOVBRCUR keyword (with or without the DELETE keyword).

You have now copied a set of records, and if wanted, deleted them from the log stream. You can repeat the whole process to copy a new set of log stream records.