LOGSTREAMCOPY: Copy an MVS log stream

Use the LOGSTREAMCOPY command to copy an MVS™ log stream to a sequential access method (SAM) data set. Information about the copy is stored in the RCDS.

Format

Read syntax diagramSkip visual syntax diagram
>>-LOGSTREAMCOPY--NAME--(--MVS log stream--)-------------------->

>--+--------------------------+--------------------------------->
   |            .-CICSVR-.    |   
   '-SELECT--(--+-ALL----+--)-'   

>--+------------------------------------+----------------------->
   |            .-1----------------.    |   
   '-COPIES--(--+-number of copies-+--)-'   

>--+--------------------------------------------------+--------->
   |                                    .-,LOCAL-.    |   
   +-STARTTIME--(--start date and time--+-,GMT---+--)-+   
   |                               .-,LOCAL-.         |   
   +-STARTTOD--(--start block TOD--+-,GMT---+--)------+   
   '-STARTBLKID--(--start block--)--------------------'   

>--+------------------------------------------------+----------->
   |                                  .-,LOCAL-.    |   
   +-STOPTIME--(--stop date and time--+-,GMT---+--)-+   
   |                             .-,LOCAL-.         |   
   +-STOPTOD--(--stop block TOD--+-,GMT---+--)------+   
   '-STOPBLKID--(--stop block--)--------------------'   

>--+----------+--+--------+--+-----+---------------------------><
   +-SETBRCUR-+  '-DELETE-'  '-MOD-'   
   +-REPBRCUR-+                        
   '-MOVBRCUR-'                        

Keywords

NAME(MVS log stream)
Specifies the name of the MVS log stream.
MVS log stream
Is the name of the MVS log stream. The name is 1–26 characters.
SELECT(CICSVR|ALL)
Specifies the records that you want to copy. You can specify one of the following values: (CICSVR) or (ALL).
CICSVR
Specifies records produced by CICS® and CICS VR batch logging are to be copied from the MVS log stream. CICSVR is the default value. For compatibility purposes, the value CICS is also accepted for the SELECT keyword, CICS has the same meaning as the value CICSVR.
ALL
Specifies all records are to be copied from the MVS log stream.
COPIES(1 | number of copies)
Specifies whether the MVS log stream is to be copied to another data set.
number of copies
Specifies the number of copies to be made from the input MVS log stream. The COPIES keyword is optional; if it is not specified, the default value of 1 is used.
  • If COPIES(0) is specified, no copy is made, and a report is produced, see Figure 1. For example, you could use this keyword if you do not need to create a copy of the log stream, but you want to process the log stream records using your own exit program, see DEFEXIT: Define CICS VR exit names for the log stream copy utility. Usage Notes has more information about the use of COPIES(0).
  • If the number of copies specified is greater than zero, the MVS log stream is copied to the data sets named on the corresponding ddnames, DWWCOPYn, where n is a number, 1–9, that you specify on the COPIES keyword.
STARTTIME(start date and time,LOCAL | GMT)
Identifies the earliest timestamp that you want to copy the MVS log stream from. CICS VR ignores all records for this MVS log stream whose timestamp is earlier than the time specified in the STARTTIME keyword. CICS VR copies records from this place in the log.

Only one STARTTIME keyword is allowed for each LOGSTREAMCOPY control statement. You only need to specify STARTTIME the first time you run the log stream copy utility. Following log stream copy runs continues from the point on the MVS log stream after the last copy.

If you do not specify STARTTIME, STARTTOD, or STARTBLKID, the MVS log stream is copied from the beginning of the log, or after the point of the last copy.

Do not use the STARTTIME keyword with the SETBRCUR, REPBRCUR, or MOVBRCUR keywords.

start date and time
Must be in the format yy/ddd/hh/mm/ss, where:
  • yy is the last two digits of the year (00–99)
  • ddd is the day of the year (001–366)
  • hh is the hour of the day (00–23)
  • mm is the number of minutes (00–59)
  • ss is the number of seconds (00–59)
You can separate these values with a slash (/), period (.), or colon (:). You can also omit the separator character. For example:
STARTTIME(08.159/22:23:00)

You cannot substitute commas, blanks, and so on, for the time values, but you can omit values from the right. For example, if you specify STARTTIME(01.159), CICS VR assumes that the time segment is 00:00:00.

CICS VR interprets year values (yy) in the range 00–85 to be years 2000–2085, and year values in the range 86–99 to be years 1986–1999.

LOCAL
Specifies that the date and time are in local format. LOCAL is the default value.
GMT
Specifies that the date and time are in Greenwich mean time (GMT) format.
STARTTOD(start block TOD,LOCAL | GMT)
Identifies the earliest timestamp that you want to copy the MVS log stream from. STARTTOD lets you specify this in a more granular format than STARTTIME. CICS VR ignores all records for this MVS log stream whose TOD timestamp is earlier than the time specified in the STARTTOD keyword. CICS VR copies records from this place in the log.

Only one STARTTOD keyword is allowed for each LOGSTREAMCOPY control statement. You only need to specify STARTTOD the first time you run the log stream copy utility. Following log stream copy runs continue from the point on the MVS log stream after the last copy.

If you do not specify STARTTIME, STARTTOD, or STARTBLKID, the MVS log stream is copied from the beginning of the log, or after the point of the last copy.

Do not use the STARTTOD keyword with the SETBRCUR, REPBRCUR, or MOVBRCUR keywords.

start block TOD
A timestamp in the TOD format, for example:
STARTTOD(BF1758AE97C2A000)
LOCAL
Specifies that the TOD timestamp is in local format. LOCAL is the default value.
GMT
Specifies that the TOD timestamp is in Greenwich mean time (GMT) format.
STARTBLKID(start block)
Identifies the block ID from which the records are to be copied. CICS VR ignores all records for this MVS log stream before the block ID specified in the STARTBLKID keyword.

Only one STARTBLKID keyword is allowed for each LOGSTREAMCOPY control statement.

If you do not specify STARTBLKID, STARTTOD, or STARTTIME, the MVS log stream is copied from the beginning of the log.

Do not use the STARTBLKID keyword with the SETBRCUR, REPBRCUR, or MOVBRCUR keywords.

start block
Is the block ID on the MVS log stream. You must specify the exact block ID.
STOPTIME(stop date and time,LOCAL | GMT)
Identifies the latest timestamp that you want to copy the MVS log stream from. CICS VR ignores all records for this MVS log stream whose timestamp is later than the time specified in the STOPTIME keyword. CICS VR copies records up to this place in the log.

Only one STOPTIME keyword is allowed for each LOGSTREAMCOPY control statement.

If you do not specify STOPTIME, STOPTOD, or STOPBLKID, the copy ends at job run time.

Do not use the STOPTIME keyword with the REPBRCUR or MOVBRCUR keywords.

stop date and time
Must be in the format yy/ddd/hh/mm/ss, where:
  • yy is the last two digits of the year (00–99)
  • ddd is the day of the year (001–366)
  • hh is the hour of the day (00–23)
  • mm is the number of minutes (00–59)
  • ss is the number of seconds (00–59)
You can separate these values with a slash (/), period (.), or colon (:). You can also omit the separator character. For example:
STOPTIME(01.159/00:30:00)
You cannot substitute commas, blanks, and so on, for the time values, but you can omit values from the right. For example, you can specify day 01159, time 23:59:59, as follows:
STOPTIME(01.159)
If you specify this, CICS VR assumes that the day is 01365 and the time is 23:59:59:
STOPTIME(01)
CICS VR assumes that these values are for day 01159, and time 16:59:59:
STOPTIME(0115916)

CICS VR interprets year values (yy) in the range 00–85 to be years 2000–2085, and year values in the range 86–99 to be years 1986–1999.

LOCAL
Specifies that the date and time are in local format. LOCAL is the default value.
GMT
Specifies that the date and time are in GMT format.
STOPTOD(stop block TOD,LOCAL | GMT)
Identifies the latest timestamp that you want to copy the MVS log stream from. STOPTOD lets you specify this in a more granular format than STOPTIME. CICS VR ignores all records for this MVS log stream whose TOD timestamp is later than the TOD time specified in the STOPTOD keyword. CICS VR copies records up to this place in the log.

Only one STOPTOD keyword is allowed for each LOGSTREAMCOPY control statement.

If you do not specify STOPTIME, STOPTOD, or STOPBLKID, the copy ends at job run time.

Do not use the STOPTOD keyword with the REPBRCUR or MOVBRCUR keywords.

stop block TOD
A timestamp in the TOD format, for example:
STOPTOD(BF1788BCFDD2A000)
LOCAL
Specifies that the TOD timestamp is in local format. LOCAL is the default value.
GMT
Specifies that the TOD timestamp is in Greenwich mean time (GMT) format.
STOPBLKID(stop block)
Identifies the block ID at which CICS VR is to stop copying records. CICS VR ignores all records for this MVS log stream after the block ID specified in the STOPBLKID keyword.

Only one STOPBLKID keyword is allowed for each LOGSTREAMCOPY control statement.

If you do not specify STOPBLKID, STOPTOD, or STOPTIME, the copy ends at job run time.

Do not use the STOPBLKID keyword with the REPBRCUR or MOVBRCUR keywords.

stop block
Is the block ID on the MVS log stream. You must specify the exact block ID.
SETBRCUR
Specifies that the starting point of the records to be read from the log stream is the position where a “start of copy” cursor was last set by the log stream copy utility that used the MOVBRCUR keyword.

The first time you use SETBRCUR, the MVS log stream is copied from the beginning of the log. Records are read from the beginning of the log or from the “start of copy” cursor, to the youngest block in the log stream, or to another position that you have specified using the STOPTIME, STOPTOD, or STOPBLKID keyword. When the required records have been read, a browse cursor is positioned at the last record read.

To ensure that you are not reading the same records twice, after you run each job that uses the SETBRCUR keyword, run a job that uses the MOVBRCUR keyword to reposition the “start of copy” cursor at the last copied record. If you do not reposition the “start of copy” cursor, any subsequent job using SETBRCUR starts to read from the same record as the first job.

If you do want to copy the same set of records twice, run a job using the SETBRCUR keyword followed by a job using the REPBRCUR keyword. This combination of jobs produces two copies of the same records.

If you run a job using the SETBRCUR keyword, but the log stream has been changed, redefined or deleted using another utility, so that it does not contain the active block where the “start of copy” cursor was positioned, the log stream is copied from the beginning of the log, from its first active block.

Do not use the SETBRCUR keyword with the STARTTIME, STARTBLKID, STARTTOD, DELETE, or COPIES(0) keyword.

REPBRCUR
Specifies that records are to be read from the log stream from the position where a “start of copy” cursor was last set by the log stream copy utility that used the MOVBRCUR keyword, to the position where a browse cursor was last set by the log stream copy utility that used the SETBRCUR keyword.

REPBRCUR repeats the same log stream data that was processed last time you ran the log stream copy utility using the SETBRCUR keyword, if the “start of copy” cursor has not been moved since that copying. The “start of copy” cursor and browse cursor are not changed by running the log stream copy utility using the REPBRCUR keyword.

The REPBRCUR keyword can be used to produce several copies of the same log stream records. To do this, run a job using the SETBRCUR keyword followed by a series of jobs using the REPBRCUR keyword.

If you run a job using the REPBRCUR keyword, but the log stream has been changed, redefined or deleted using another utility, so that it does not contain the active block where the “start of copy” cursor was positioned, the log stream is copied from the beginning of the log, from its first active block, and copying ends at the newest block at or before the position where a browse cursor was last set.

Do not use the REPBRCUR keyword with the STARTTIME, STARTBLKID, STARTTOD, STOPTIME, STOPBLKID, STOPTOD, DELETE, or COPIES(0) keywords.

MOVBRCUR
Specifies that the “start of copy” cursor is to be placed at the position where the browse cursor was set. No log stream records are copied from the log stream when this keyword is used.

To ensure that you are not reading the same records twice, after you run each job that uses the SETBRCUR keyword, run a job using the MOVBRCUR keyword to reposition the “start of copy” cursor. If you do not reposition the “start of copy” cursor, any subsequent job using SETBRCUR starts to read from the same record as the first job.

If you do want to read the same set of records twice, run a job using the REPBRCUR keyword, before you run a job using the MOVBRCUR keyword to reposition the “start of copy” cursor.

Do not use the MOVBRCUR keyword with any other LOGSTREAMCOPY keywords, except for the NAME and DELETE keywords.

DELETE
Specifies that log stream records are to be deleted from the log stream. The log stream itself is not deleted and remains available for use.

If the DELETE keyword is used without the MOVBRCUR keyword, log stream records are deleted from the log stream from the oldest log stream block, the beginning of the log, up to the last successfully copied block. If the DELETE keyword is used with the MOVBRCUR keyword, log stream records are deleted from the log stream from the oldest log stream block, the beginning of the log, up to the block in the position where a browse cursor was last set by the log stream copy utility that used the SETBRCUR keyword.

CICS VR protects log stream blocks from casual deletion, so the deletion of the log stream blocks is performed only if CICS VR permits it. CICS VR permits the log stream copy utility to perform deletion of log stream blocks if the CICS VR global default LCDEL is set to YES. Otherwise the log stream utility considers that the deletion is prohibited and ignores the DELETE keyword. Ensure that the default for log stream deletion is set to the wanted value. LCDEL must be set to YES to perform log stream block deletion. LCDEL must be set to NO to ignore log stream block deletion requests. Defining a CICS VR general control parameter explains how to determine the current setting for LCDEL.

The DELETE keyword is also ignored if the copy was not completed, or if no blocks were found and copied, or if the COPIES(0) keyword was specified.

If the log stream has been changed, redefined or deleted using another utility, so that it does not contain either the last successfully copied active block, if you are not using the MOVBRCUR keyword, or the active block in the position where a browse cursor was last set, if you are using the MOVBRCUR keyword, no log stream records are deleted from the log stream.

Do not use the DELETE keyword with the SETBRCUR and REPBRCUR keywords.

MOD
Indicates that records are to be added to the end of the data set specified in the DWWCOPYn ddname. Use the MOD keyword if you specified DISP=MOD for any of the DWWCOPYn ddnames.
EXCLUDE(specific log records)
Use the EXCLUDE command to eliminate specific log records from the Logcopy function.
Format
EXCLUDE FILEID ( id1,id2,...) TERMID ( id1,id2,...) TRANSID ( id1,id2,...)
Keywords
FILEID(id1,id2,...)
Specifies that the utility must ignore any log records with these FILEIDs when copying records. If more than one keyword is specified, for example; EXCLUDE FILEID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be excluded.
Id1,id2,...
Specifies the FILEID defined to CICS. id1, id2, for example, can be 1 to 8 characters. Up to 99 IDs can be specified for one FILEID. If more than one ID is specified on the FILEID keyword, a log record needs to match only one of the specified FILEIDs to be excluded.
TERMID(id1,id2,...)
Specifies that the utility must ignore any log records with these TERMINALIDs when copying records. If more than one keyword is specified, for example, EXCLUDE FILEID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be excluded.
Id1,id2,...
Specifies the TERMINALID defined to CICS. For example; id1, id2, can be 1 to 4 characters. Up to 99 IDs can be specified for one TERMID. If more than one ID is specified on the TERMID keyword, a log record only needs to match one of the specified terminal IDs to be excluded.
TRANSID(id1,id2,...)
Specifies that the utility must ignore any log records with these TRANSACTIONIDs when copying records. If more than one keyword is specified, for example, EXCLUDE TRANSID(APQ1),TERMID(TST1), the log record must match both IDs specified for it to be excluded.
Id1,id2,...
Specifies the TRANSACTIONID defined to CICS. id1, id2, for example, can be 1 - 4 characters. Up to 99 IDs can be specified for one TRANSID. If more than one ID is specified on the TRANSID keyword, a log record only needs to match one of the specified TRANSACTIONIDs to be excluded.
INCLUDE(specific log records)
Use the INCLUDE command to selectively include specific log records from the Logcopy function.
Format
INCLUDE FILEID ( id1,id2,...) TERMID ( id1,id2,...) TRANSID ( id1,id2,...)
Keywords
FILEID(id1,id2,...)
Specifies that the Logcopy function use log records only with these file IDs. If more than one keyword is specified, for example; INCLUDE FILEID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be included.
Id1,id2,...
Specifies the FILEID defined to CICS. For example; id1, id2, can be 1 - 8 characters. Up to 99 IDs can be specified for one FILEID. If more than one ID is specified on the FILEID keyword, a log record needs to match only one of the specified file IDs to be included.
TERMID(id1,id2,...)
Specifies that the Logcopy function use log records only with these terminal IDs. If more than one keyword is specified, for example; INCLUDE FILEID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be included.
Id1,id2,...
Specifies the TERMINALID defined to CICS.For example; id1, id2, can be 1 - 4 characters. Up to 99 IDs can be specified for one TERMID. If more than one ID is specified on the TERMID keyword, a log record needs to match only one of the specified terminal IDs to be included.
TRANSID(id1,id2,...)
Specifies that the Logcopy function uses log records only with these transaction IDs. If more than one keyword is specified, for example; INCLUDE TRANSID(DD1),TERMID(TST1), the log record must match both IDs specified for it to be included.
Id1,id2,...
Specifies the TRANSACTIONID defined to CICS. id1, id2, for example, can be 1 - 4 characters. Up to 99 IDs can be specified for one TRANSID. If more than one ID is specified on the TRANSID keyword, a log record needs to match only one of the specified transaction IDs to be included.

Usage Notes

  • If the forward recovery log is a DASDONLY logstream, the LOGSTREAMCOPY jobs must be run on the same LPAR as the CICS region which produced it. If the forward recovery logstream is a Coupling Facility logstream, the LOGSTREAMCOPY job can be run on any LPAR.
  • In general, log stream copies are made for use at a disaster recovery site. For more information about what is needed at a disaster recovery site, see Using CICS VR with CICS TS at your disaster recovery site.
  • After the first log stream copy run, subsequent runs automatically begin copying after the point on the MVS log stream that the last copy finished. Use the same RCDS data sets in the subsequent log stream copy jobs to provide log stream copying without gaps. The use of CICS VR server's RCDS is recommended, see Understanding the recovery control data sets (RCDSs).
  • The log stream copy utility is started by the CICS VR module, DWWLC, see Figure 1.
  • You can have only one LOGSTREAMCOPY command in a single CICS VR job step.
  • LOGSTREAMCOPY keywords can be coded in any sequence.
  • You can copy the entire MVS log stream or just the records produced by CICS and CICS VR batch logging.
  • LOGSTREAMCOPY copies the MVS log stream to a maximum of nine data sets and stores information about the first copy in the RCDS.
  • You start the log stream copy utility by running the required JCL, and providing the statements you need as parameters on the DWWIN DD statement.
  • You define the data sets to which the MVS log stream is to be copied on the DWWCOPY1—DWWCOPY9 DD statements. See Figure 1 for an example of the JCL to run the log stream copy utility.
  • Before the log stream copy utility copies the MVS log stream record to the output data set a precopy exit can be called. This exit lets you inspect and act on a copy of the record before it is written to the output data set. This exit must be defined during the LOGSTREAMCOPY run by the DEFEXIT command.
  • Before the log stream copy utility terminates, a termination exit can be called. This exit lets you terminate actions that were performed.
  • Use the MOD keyword if you specified DISP=MOD for any of the DWWCOPYn ddnames.
  • Only the MVS log stream copied to DWWCOPY1 is registered in the RCDS. An exception is copies produced by the LOGSTREAMCOPY command with the REPBRCUR keyword, which are never registered in the RCDS.
  • If you want to process a part of the MVS log stream without having an impact on further CICS VR log stream processing, specify COPIES(0) and run the CICS VR log stream copy utility without the RCDS data sets. For example, you might want to process this part of the log stream using your own exit program, or you might want to examine the log stream copy report for the MVS log stream state. Your action is not recorded in the RCDS.
  • If you want to process a part of the MVS log stream by your own methods but also reflect this action in CICS VR, specify COPIES(0) and run the CICS VR log stream copy utility with the RCDS data sets. For example, you might want to process this part of the log stream using only your own exit program without copying it, or you might want to skip this part of the log stream. Your action is recorded in the RCDS and might affect further CICS VR log stream processing.
  • If you use the SETBRCUR, REPBRCUR, MOVBRCUR, or DELETE keywords on the LOGSTREAMCOPY command, you must specify the RCDS data sets in the log stream copy job.
  • The values of the “start of copy” cursor and browse cursor are kept in the RCDS. To avoid any confusion, use the same RCDS when using subsequent SETBRCUR, REPBRCUR, and MOVBRCUR keywords with the same MVS log stream.
  • For more information about using LOGSTREAMCOPY, see Using the log stream copy utility to copy your MVS log streams.
Consider the following when using the EXCLUDE command:
  • The RCDS is not updated if EXCLUDE or INCLUDE or EXCLUDE and INCLUDE commands are used so the logcopy made is not used in automatic forward recovery. This is because the logcopy might be missing some vital records because not all records are copied. The copy can be used in manual forward recovery if you are sure that no relevant records are missing.
  • At least one keyword must be specified for each EXCLUDE command.
  • Multiple EXCLUDE commands and INCLUDE commands can be specified in the same job step. The Logcopy function processes a log record against all EXCLUDE commands before it processes the log record against all INCLUDE commands.
  • For each log record, if the EXCLUDE criteria is met, the record is excluded. If the EXCLUDE criteria is not met, the Logcopy function matches the log record against the next EXCLUDE command.
  • When the log record has been examined against all the EXCLUDE commands, the utility examines the log record against the first INCLUDE command (if the log record was not excluded by any of the EXCLUDE commands).
  • If the INCLUDE criteria is met the record is used in the utility. If it is not met, the Logcopy function matches the record against the next INCLUDE command.
  • If the log record does not match any of the INCLUDE commands, the log record is not used. Logcopy function repeats this process for the next log record by matching it first against the EXCLUDE commands and then the INCLUDE commands.
  • If one or more EXCLUDE commands are entered and no INCLUDE commands are entered, all log records that do not match the entered exclude criteria are copied. For example, if you specify:
    EXCLUDE FILEID(DD1),TERMID(T1)
    The utility ignores log records that have a FILEID of DD1 and TERMINALID of T1. If you want to ignore log records that have a FILEID of DD2 or TERMINALID of T2, specify two EXCLUDE commands as follows:
    EXCLUDE FILEID(DD2)  
    EXCLUDE TERMID(T2)
    There is no limit on the number of EXCLUDE (and INCLUDE) commands that you can specify.
  • You can specify up to 99 IDs on each keyword.
  • If you specify INCLUDE or EXCLUDE commands that eliminate all of the records, no records are copied.
  • Do not specify EXCLUDE and INCLUDE criteria that conflict. For example; INCLUDE FILEID(DD1) and EXCLUDE FILEID(DD1). If conflicting criteria is specified, no records are copied and no error messages are produced.
Consider the following when using the INCLUDE command:
  • The RCDS is not updated with information if EXCLUDE or INCLUDE or EXCLUDE and INCLUDEcommands are used so the logcopy made is not used in automatic forward recovery. This is because the logcopy might be missing some vital records because not all records are copied. The copy can be used in manual forward recovery if you are sure that no relevant records are missing.
  • Multiple INCLUDE commands and EXCLUDE commands can be specified in the same job step. The Logcopy function processes a log record against all EXCLUDE commands before it processes the log record against all INCLUDE commands.
  • For each log record, if the EXCLUDE criteria is met, the record is excluded. If the EXCLUDE criteria is not met, the Logcopy function matches the log record against the next EXCLUDE command.
  • When the log record has been examined against all the EXCLUDE commands, the Logcopy function examines the log record against the first INCLUDE command (if the log record was not excluded by any of the EXCLUDE commands).
  • If the INCLUDE criteria is met, or if no INCLUDE commands were specified, then the record is copied.
  • If the criteria it is not met, the Logcopy function matches the record against the next INCLUDE command. If the log record does not match any of the INCLUDE commands, the log record is not copied. The Logcopy function repeats this process for the next log record by first matching it against the EXCLUDE commands, then the INCLUDE commands.
  • If one or more INCLUDE commands are entered and no EXCLUDE commands are entered, all log records that match the entered include criteria is copied. For example, if you specify:
    INCLUDE FILEID(DD1),TERMID(T1)
    The Logcopy function only uses log records that have a FILEID of DD1 and TERMINALID of T1. If you want the Logcopy function to use log records that have a FILEID of only DD1 or TERMINALID of T1, specify two INCLUDE commands as follows:
    INCLUDE FILEID(DD1)  
    INCLUDE TERMID(T1)
    There is no limitation on the number of INCLUDE (and EXCLUDE) commands.
  • You can specify up to 99 IDs on each keyword.
  • If you specify INCLUDE or EXCLUDE commands that eliminate all of the records, no records are copied.
  • Avoid specifying INCLUDE and EXCLUDE criteria that conflict (for example, INCLUDE FILEID(DD1) and EXCLUDE FILEID(DD1)). If conflicting criteria is specified, no records are copied. No error messages are produced.

Examples

The following LOGSTREAMCOPY command tells CICS VR to make three copies of the MVS log stream. These copies are made to the data sets specified on the ddnames DWWCOPY1, DWWCOPY2, and DWWCOPY3. Records are copied to the end of the data sets specified in the DWWCOPYn ddnames. Records are copied from the beginning of the MVS log stream or the first record after the end of the previous LOGSTREAMCOPY and stop at current time of this job or when the end of the log stream is reached. CICS VR remembers where the log stream copy stopped; so this same job could be run over and over to continuously copy the MVS log stream. This is the best way to do a log stream copy.

LOGSTREAMCOPY NAME(CICSVR1.MVSLOG)   -
         SELECT(ALL)     -
         COPIES(3)       -
         MOD

The following LOGSTREAMCOPY command tells CICS VR to make two copies of the MVS log stream. These copies are made to the data sets specified on the ddnames DWWCOPY1, DWWCOPY2. Records are copied to the end of the data sets specified in the DWWCOPYn ddnames. Records are copied from the MVS log stream at the start time specified and stop at the current time of this job or when the end of this log stream is reached. CICS VR remembers where the log stream copy stopped Because a start time was specified, you must update the STARTTIME when a new backup is taken.

LOGSTREAMCOPY NAME(CICSVR1.MVSLOG)   -
         SELECT(ALL)     -
         COPIES(2)       -
         STARTTIME(01159/07:30:00,GMT)   -
         MOD

The following LOGSTREAMCOPY command tells CICS VR to make three copies of the MVS log stream. These copies are made to the data sets specified on the ddnames DWWCOPY1, DWWCOPY2, and DWWCOPY3. Records are copied to the end of the data sets specified in the DWWCOPYn ddnames. Records are copied from the beginning of the MVS log stream or the first record after the end of the previous LOGSTREAMCOPY and stop at the specified stop time. CICS VR remembers where the log stream copy stopped. This could be used to control the size of the output.

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

The following LOGSTREAMCOPY command tells CICS VR to make three copies of the MVS log stream. These copies are made to the data sets specified on the ddnames DWWCOPY1, DWWCOPY2, and DWWCOPY3. Records are copied to the end of the data sets 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. CICS VR remembers where the log stream copy stopped. This is not a recommended method to copy the log unless this is a one time copy to produce test data. Do not use this method to make consecutive copies because the time values are not precise enough to prevent gaps.

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

The following LOGSTREAMCOPY command tells CICS VR to make one copy of the MVS log stream blocks. This copy is made to the data set specified on the ddname DWWCOPY1. Records are copied starting from the first block of the MVS log stream whose TOD timestamp, in the Local time format, is equal to or greater than the TOD value specified in the STARTTOD keyword. Copying stops at the block whose TOD timestamp (in the GMT time format) is greater than the TOD value specified in the STOPTOD keyword, or when the end of the log stream is reached.

LOGSTREAMCOPY NAME(CICSMVS.V42BLK.FILELOG) – 
              SELECT(CICSVR)     -      
              STARTTOD(BE87C2EA57000000,LOCAL) –
              STOPTOD(BE8B8882B9000000,GMT) - 
              COPIES(1)       

The following LOGSTREAMCOPY command tells CICS VR to make a copy of the MVS log stream and position a browse cursor at the last record copied. The copy is made to the data set specified on the ddname DWWCOPY1. Records are copied starting from the beginning of the MVS log stream, if this is the first time when the cursor is set, or from the “start of copy” cursor. Copying stops at the block specified in the STOPBLKID keyword, or when the end of the log stream is reached.

LOGSTREAMCOPY NAME(CICSMVS.V42BLK.FILELOG) – 
              STOPBLKID(1900)      –
              SETBRCUR             -
              COPIES(1)     

The following LOGSTREAMCOPY command must be run immediately after the previous example. It tells CICS VR to make the same copy of the MVS log stream as the previous example did. This copy is made to the data set specified on the ddname DWWCOPY1. Records are copied starting from the beginning of the MVS log stream, if this is the first time when the cursor is set, or from the “start of copy” cursor. Copying stops at the block specified in the browse cursor. Note that this copy is not registered in the RCDS.

LOGSTREAMCOPY NAME(CICSMVS.V42BLK.FILELOG) – 
              REPBRCUR             -
              COPIES(1)   

The following LOGSTREAMCOPY command must be run immediately after the previous two examples. It tells CICS VR not to make a copy of the MVS log stream, but just to reposition the “start of copy” cursor to the browse cursor. Next time you run the log stream copy utility with the SETBRCUR keyword, it starts copying from the new log position specified in the “start of copy” cursor.

LOGSTREAMCOPY NAME(CICSMVS.V42BLK.FILELOG) – 
              MOVBRCUR                

The following LOGSTREAMCOPY command tells CICS VR to make one copy of the MVS log stream blocks. This copy is made to the data set specified on the ddname DWWCOPY1. Records are copied starting from the specified start time, and copying stops at the specified stop time. CICS VR remembers where the log stream copy stopped. The log stream block tail up to the last copied block is deleted if CICS VR permits the log stream deletion.

   LOGSTREAMCOPY NAME(CICSMVS.V42BLK.FILELOG) – 
              SELECT(ALL)     -                      
              STARTTOD(BE87C2EA57000000,LOCAL) –
              STOPTIME(06085/07:30:00,GMT) – 
              DELETE                       -
              COPIES(1)               

The following LOGSTREAMCOPY command tells CICS VR not to make a copy of the MVS log stream, but just to reposition the “start of copy” cursor to the browse cursor, and delete the log stream block tail up to the position of the browse cursor. The deletion is done only if CICS VR permits it.

     LOGSTREAMCOPY NAME(CICSMVS.V42BLK.FILELOG) – 
              DELETE           -
              MOVBRCUR              

The Logcopy function filtering is started by adding EXCLUDE and INCLUDE, or EXCLUDE or INCLUDE commands to the command input in the DWWIN dd statement.

Assume the following two EXCLUDE commands are specified in one job step. The two EXCLUDE commands tell the Logcopy function to exclude all records that have both a FILEID of DD3 and TRANSACTIONID of APQ4, or, exclude all records that have a TERMINALID of TST2
EXCLUDE FILEID(DD3) TRANSACTIONID(APQ4) 
EXCLUDE TERMINALID(TST2)
Assume the following five commands are specified in one job step. Since multiple EXCLUDE and INCLUDE commands are specified in one step, the Logcopy function processes a log record against all EXCLUDE commands before the log record is processed against all INCLUDE commands.
INCLUDE FILEID(DD1,DD2)  
INCLUDE FILEID(DD3) TERMINALID(TST1)   
INCLUDE FILEID(DD4) TRANSACTIONID(APQ1,APQ2,APQ3)  
EXCLUDE FILEID(DD3) TRANSACTIONID(APQ4)  
EXCLUDE TERMINALID(TST2)

Exclude all records that have both a FILEID of DD3 and TRANSACTIONID of APQ4, or exclude all records that have a TERMINALID of TST2.

This example is exactly like the previous example. When the log record has been processed using the exclude criteria, it is processed using the include criteria. If the log record was not excluded by the EXCLUDE command:

Include all records that have a FILEID of DD1 or DD2, or include all records that have a FILEID of DD3 and TERMINALID of TST1, or Include all records that have a FILEID of DD4 and TRANSACTIONID of APQ1, APQ2, or APQ3.

Assume the following two INCLUDE commands are specified in one job step. The two INCLUDE commands tell the Logcopy function to include all records that have both a FILEID of DD3 and TRANSACTIONID of APQ4, or, include all records that have a TERMINALID of TST2
INCLUDE FILEID(DD1)  
INCLUDE TERMID(T1)
Assume the following five commands are specified in one job step. Since multiple INCLUDE or EXCLUDE commands are specified in one step, the Logcopy function processes a log record against all EXCLUDE commands before the log record is processed against all INCLUDE commands.
INCLUDE FILEID(DD1,DD2)  
INCLUDE FILEID(DD3) TERMINALID(TST1)  
INCLUDE FILEID(DD4) TRANSACTIONID(APQ1,APQ2,APQ3)  
EXCLUDE FILEID(DD3) TRANSACTIONID(APQ4)  
EXCLUDE TERMINALID(TST2) 

Exclude all records that have both a FILEID of DD3 and TRANSACTIONID of APQ4, or Exclude all records that have a TERMINALID of TST2.

If the log record was not excluded by any of the EXCLUDE commands, it is processed using the include criteria. For the remaining records (the log records that were not excluded by the EXCLUDE command).

Include all records that have a FILEID of DD1 or DD2, or| Include all records that have a FILEID of DD3 and TERMINALID of TST1, or Include all records that have a FILEID of DD4 and TRANSACTIONID of APQ1, APQ2, or APQ3.

Format

The format of the log stream copy starts and ends with writing a special record.

Layout of the first log stream copy record table describes the layout of first record:

Table 1. Layout of the first log stream copy record.
Attribute Format Description
constant (104) fixed (32) Length of the rest of this record
constant ('>DWW') char (4) Type of record
constant (1) fixed (31) Version number
* char (8) Reserved
blkid char (8) Block ID of the first block read
* char (8) Reserved
gmttime char (8) GMT time of the first block read, time-of-day (TOD) format
localtime char (8) Local time of the first block read, time-of-day (TOD) format
* char (8) Reserved
logname char (26) MVS log name
* char (22) Reserved

The Layout of last record table describes the layout of last record:

Table 2. Layout of last record
Attribute Format Description
constant (104) fixed (32) Length of the rest of this record
constant ('>DWW') char (4) Type of record
constant (1) fixed (31) Version number
* char (8) Reserved
blkid char (8) Block ID of the last block read
* char (8) Reserved
gmttime char (8) GMT time of the last block read, time-of-day (TOD) format
localtime char (8) Local time of the last block read, time-of-day (TOD) format
* char (8) Reserved
logname char (26) MVS log name
* char (22) Reserved

The Layout of all other records table describes the layout of all other records:

Table 3. Layout of all other records.
Attribute Format Description
length fixed (32) Length of the prefix(24) + length of the MVS log block read, for example, length of the rest of this record
blkid char (8) Block ID of the MVS block read
gmttime char (8) GMT time of the MVS block read, time-of-day (TOD) format
localtime char (8) Local time of the last block read, time-of-day (TOD) format
block char (*) The MVS log block read
Note: All of the previous records are written to a SAM file using the following spanned format:

The Spanned format for records using a SAM file table describes the spanned format for records using a SAM file.

Table 4. Spanned format for records using a SAM file.
Attribute Format Description
length fixed (16) Total length of this block, including this field
bb fixed (16) Block indicator
record char (*) A whole or part of one of the previous records
The block indicator can be one of the following values:
00
The whole record is contained in this block
01
First part of the record is contained in this block
02
Last part of the record is contained in this block
03
A middle part of the record is contained in this block

One of the reasons for this is that an MVS block can be up to 64K, but the largest SAM block that can be written is 32K.

Synonyms

The LOGSTREAMCOPY Synonyms table provides LOGSTREAMCOPY commands or keywords along with acceptable synonyms to use in place of the commands or keywords:

Table 5. LOGSTREAMCOPY Synonyms
Command, keyword, or value Synonyms
LOGSTREAMCOPY LOGCOPY
SELECT SEL
COPIES CPS
STARTBLKID STARTBLK
STOPBLKID STOPBLK
Table 6. Synonyms for EXCLUDE and INCLUDE commands or keywords
Keyword Synonyms
FILEID DD, DDNAME
TERMID TERMINALID
TRANSID TRANSACTIONID

Reference Reference

Feedback


Timestamp icon Last updated: Friday, 7 February 2014


http://pic.dhe.ibm.com/infocenter/cicsts/v5r1/topic///dwwig/xlscop.html