If you are using a batch job to read log stream data, ensure that it includes the SUBSYS keyword as part of its input or data DD.
//ddname DD DSNAME=log_stream_name,
// SUBSYS=
where SUBSYS expands as follows:
SUBSYS >>-SUBSYS=(LOGR,DFHLGCNV-+----------------------------------+-)->< | .------------------. | | V | | '-,--| OP1 |----+--------------+-+-' +-,--LASTRUN---+ +-,--DELETE----+ +-,--COMPAT41--+ +-,--COMPAT41V-+ +-,--SETBRCUR--+ +-,--REPBRCUR--+ '-,--DELBRCUR--' OP1: .-GMT---. |--+-+---------+--+---------+-+--+-------+----------------------| | '-| OP2 |-' '-| OP3 |-' | '-LOCAL-' '-DURATION=(nnnn,HOURS)----' OP2: |--+---------------------------------------------+--------------| '-FROM=-+-+----------+--+-----------------+-+-' | '-YYYY/DDD-' '-,hh:mm--+-----+-' | | '-:ss-' | '-OLDEST----------------------------' OP3: |--+-------------------------------------------+----------------| '-TO=-+-+----------+--+-----------------+-+-' | '-YYYY/DDD-' '-,hh:mm--+-----+-' | | '-:ss-' | '-YOUNGEST--------------------------'
Other DD keywords will be validated, if specified, but will be ignored.
CICS provides support for log streams generated by multiple CICS systems (a typical example would be a forward recovery log stream). Such log streams can contain log records generated by different releases of CICS. In order to ensure downward compatibility for all possible types of CICS log records, make sure that the highest level of DFHLGCNV (and its associated module DFHGTCNV) is referenced by batch jobs run against the log streams. As DFHLGCNV and DFHGTCNV reside in the SDFHLINK library, the MVS linklist should reference the SDFHLINK library of the highest release of CICS on an MVS region so that the batch jobs always use the highest available version of DFHLGCNV and DFHGTCNV.
yyyy is a four-digit year number and ddd is a three-digit day number from 001 through 366 (366 is valid only on leap years). For example, code February 20, 2000 as 2000/051, and code December 31, 1996 as 1996/366.
hh is a 2-digit hour number from 00 to 23, mm is a 2-digit minute number from 00 to 59, and ss is a 2-digit second number from 00 to 59. The seconds field and associated : delimiter can be omitted if not required by the log stream owner.
The FROM= keyword is mutually exclusive with the DURATION= keyword, and is not allowed when the DELETE keyword is specified.
yyyy is a four-digit year number and ddd is a three-digit day number from 001 through 366 (366 is valid only on leap years). For example, code March 7, 2001 as 2001/066, and code November 12, 2000 as 2000/317.
hh is a 2-digit hour number from 00 to 23, mm is a 2-digit minute number from 00 to 59, and ss is a 2-digit second number from 00 to 59. The seconds field and associated : delimiter can be omitted if not required by the log steam owner.
The TO= keyword is mutually exclusive with the DURATION= keyword.
The time is GMT or local time, as selected in the GMT|LOCAL keyword.
The first block will be the one with a time stamp greater than or equal to the calculated start time. The last block read will be the youngest block on the log stream at the time the allocation for the DD occurs.
The DURATION= keyword is mutually exclusive with the TO= and the FROM= keywords.
The options that are valid for CICS log streams when using exit routine DFHLGCNV are:
LASTRUN is mutually exclusive with the FROM, TO and DURATION keywords in SUBSYS-options1.
Note also that LASTRUN is not recommended when copying and deleting logstream data. See Example 2 for the recommended way of doing this.
If the log stream has been opened in the job step, all records up to and including the last complete block read by the program are deleted from the log stream.
If the log stream has not been opened in the job step, all records prior to the TO= time are deleted from the log stream.
If it is important that unprocessed records are not deleted, put the DELETE keyword as part of a conditional job step; see Example 2.
Alternatively, you can create a new data set with the correct DCB information and the records, as far as possible, in the format used by CICS/ESA 4.1. To do this, run DFHJUP specifying the COMPAT41 option (and not the COMPAT41V option), and also specifying the NEWDCB option on the OPTION COPY command. (See Utility control statements for DFHJUP for more information on creating a new data set using NEWDCB.) You can then run batch applications that require the records in COMPAT41 format against this new data set. Note that once you have created a new data set, the batch applications do not need the COMPAT41 or COMPAT41V option to be specified at runtime.
To ensure that you are not reading the same records twice, after you run each job that uses the SETBRCUR option, run a job using the DELBRCUR option to delete the browsed records and reposition the deleted cursor at the last record deleted. If you do not reposition the deleted 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 SETBRCUR option followed by a job using the REPBRCUR option. This combination of jobs produces two copies of exactly the same records, so you can produce two copies of the same records in different formats, for example.
Do not use the SETBRCUR option with the DELETE or LASTRUN options.
The REPBRCUR option can be used to produce a second copy of the same records, perhaps in a different format to that produced by the original processing. To do this, run a job using the SETBRCUR option followed by a job using the REPBRCUR option.
Do not use the REPBRCUR option with the DELETE or LASTRUN options.
To ensure that you are not reading the same records twice, after you run each job that uses the SETBRCUR option, run a job using the DELBRCUR option to reposition the deleted cursor. If you do not reposition the deleted 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 option, before you run a job using the DELBRCUR option to reposition the deleted cursor.
Do not use the DELBRCUR option with any other options.
Table 2 shows the combinations of SUBSYS options that are supported. In each row of the table, you can use any combination of the options shown, including all or none of them. The exception to this rule is the time-related options TO, FROM and DURATION. You can use TO with FROM, and FROM with DURATION, but not TO with DURATION. You can use any of the time-related options on their own.
SETBRCUR, REPBRCUR and DELBRCUR are the recommended options for log stream offline processing, for example for archive purposes. For more information, see Using the SETBRCUR, REPBRCUR and DELBRCUR options for log stream processing.
COMPAT41 | TO, FROM or DURATION | ||||||
COMPAT41V | TO, FROM or DURATION | ||||||
LASTRUN | COMPAT41 | TO or DURATION | |||||
LASTRUN | COMPAT41V | TO or DURATION | |||||
DELETE | TO or DURATION | ||||||
COMPAT41 |
SETBRCUR |
TO or DURATION | |||||
COMPAT41V |
SETBRCUR |
TO or DURATION | |||||
COMPAT41 | REPBRCUR | ||||||
COMPAT41V | REPBRCUR | ||||||
DELBRCUR |
SETBRCUR, REPBRCUR and DELBRCUR are the recommended options for log stream offline processing. Using these options ensures that the beginning and end of your read are precisely defined, and the reads are repeatable. For example, using the REPBRCUR option enables you to archive the same records in two different formats. These options also provide enhanced support for automatic logstream processing, as you do not need to include date and time information in your batch program. Note that log streams to be processed in this way should be defined as AUTODELETE(NO) RETPD(0), to avoid unexpected loss of data.
We recommend that you should not run more than one job per logstream using a SETBRCUR, REPBRCUR or DELBRCUR option at any one time in your sysplex. If you run more than one such job simultaneously, they could update the same cursor, and then your reads would not be repeatable. You should also not run a job using LASTRUN at the same time as a job using SETBRCUR, REPBRCUR or DELBRCUR. You can run jobs that use only non-cursor related options at the same time as a job using one of the cursor-related options (SETBRCUR, REPBRCUR, DELBRCUR and LASTRUN), as the other log stream processing options do not affect the position of the cursors.
A suggested sequence for using the SETBRCUR, REPBRCUR and DELBRCUR options for log stream processing is as follows:
The following flowchart illustrates this sequence of actions:
For an example of how you can use SETBRCUR and REPBRCUR to make two copies of the same log stream partition, then delete the log stream partition using DELBRCUR, see Example 4.