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.
>>-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-'
Only one STARTTIME keyword is allowed for each LOGSTREAMCOPY control statement. You need only 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.
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.
Only one STARTTOD keyword is allowed for each LOGSTREAMCOPY control statement. You need only 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.
STARTTOD(BF1758AE97C2A000)
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.
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.
STOPTIME(01.159/00:30:00)
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.
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.
STOPTOD(BF1788BCFDD2A000)
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.
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 exactly 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 repeats exactly the same log stream data that was processed last time you ran the log stream copy utility using the SETBRCUR keyword, provided that 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.
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.
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 desired 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.
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. 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.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 exactly 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.
EXCLUDE FILEID(DD3) TRANSACTIONID(APQ4)
EXCLUDE TERMINALID(TST2)
Assume the five commands below
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
INCLUDE FILEID(DD1)
INCLUDE TERMID(T1)
Assume the five commands below 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
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:
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) | Blockid 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:
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) | Blockid 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:
Attribute | Format | Description |
---|---|---|
length | fixed (32) | Length of the prefix(24) + length of the MVS log block read, i.e. 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 |
The Spanned format for records using a SAM file table describes the 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 above records |
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.
The LOGSTREAMCOPY Synonyms table provides LOGSTREAMCOPY commands or keywords along with acceptable synonyms to use in place of the commands or keywords:
Command, keyword or value | Synonyms |
---|---|
LOGSTREAMCOPY | LOGCOPY |
SELECT | SEL |
COPIES | CPS |
STARTBLKID | STARTBLK |
STOPBLKID | STOPBLK |
Keyword | Synonyms |
---|---|
FILEID | DD, DDNAME |
TERMID | TERMINALID |
TRANSID | TRANSACTIONID |