SUBSYS=(LOGR,DFHLGCNV,...) keyword

SUBSYS=(LOGR,DFHLGCNV,...) keyword

has the form and syntax described in Figure 1:

//ddname   DD  DSNAME=log_stream_name,
//           SUBSYS=

where SUBSYS expands as follows:

SUBSYS

OP1

OP2

OP3

Note: Quotation marks around SUBSYS-options1 and SUBSYS-options2 are required when non-alphanumeric characters are used in the options. They are not required when the option consists of a single keyword.

Other DD keywords will be validated, if specified, but will be ignored.

DSNAME=log_stream_name

specifies the name of the log stream to read. The name can be 1 to 26 characters in a data set name format.

SUBSYS=(LOGR[,exit_routine_name][,‘SUBSYS-options1'][,‘SUBSYS-options2'])

specifies that processing of this DD is to be handled by the LOGR subsystem.

exit_routine_name

The exit_routine_name is the second positional parameter and specifies the name of the exit routine to receive control from the MVS™ system logger. For log streams written by CICS®, the exit routine name should be specified as DFHLGCNV.

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.

Note: Omitting the exit_routine parameter, in order to read log records in the form they are stored on the log stream, is not a supported programming interface for CICS.

SUBSYS-options1

specifies options meaningful to all exit routines.

Note: If multiple options are required, quotation marks are required around each set of options, and the set of options should be separated by a comma. Quotation marks are not required when only one option is required. For example, the coding SUBSYS=(LOGR,DFHLGCNV,TO=(,12:00),COMPAT41) uses only one SUBSYS-options1 option and one SUBSYS-options2 option, so it does not require quotation marks. However, the coding SUBSYS=(LOGR,DFHLGCNV,'TO=(,12:00),GMT','COMPAT41,SETBRCUR') uses two SUBSYS-options1 options and two SUBSYS-options2 options. Quotation marks are used around each set of options, and the sets of options are separated by a comma.

'FROM={([yyyy/ddd][,hh:mm[:ss]]) |OLDEST}'

indicates the starting time of the first log stream block to be processed. The first block processed will be the one with a time stamp greater than or equal to the specified time.

OLDEST

indicates that the first block read will be the oldest block on the log stream. If you omit the FROM= keyword, OLDEST is taken as the default.

yyyy/ddd

specifies the start date. If you omit a start date, the current date is assumed.

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:mm[:ss]

specifies the start time. If you omit the time, the first block written after midnight is used.

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.

Note: The time is GMT or local time, as selected in the GMT|LOCAL keyword.

'TO={([yyyy/ddd][,hh:mm[:ss]]) |YOUNGEST}'

indicates the ending time of the last log stream block to be processed. The last block will be the one with a time stamp less than or equal to the specified time.

YOUNGEST

indicates the last block read will be the youngest block on the log stream at the time the allocation for the DD occurs. If the TO= keyword is not specified, YOUNGEST is the default.

yyyy/ddd

specifies the end date. If the date is omitted, the current date is assumed.

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:mm[:ss]

specifies the end time. If the time is omitted, the last block written before midnight is used. If the end date is the same as the current day, the system uses the youngest block on the log stream at the time the allocation for the DD occurs.

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 TO= keyword is mutually exclusive with the DURATION= keyword.

Note: The direction of the log stream browse is from the oldest (FROM=) to the youngest (TO=). If the value specified for the FROM= is greater than the value specified for the TO=, the jobstep is terminated with a JCL error.

The time is GMT or local time, as selected in the GMT|LOCAL keyword.

'DURATION=(nnnn,HOURS)'

The DURATION keyword is another method of requesting which blocks are to be processed. Each “n” is a numeric from 0 to 9. (nnnn,HOURS) requests the blocks for the “last nnnn hours” up to the youngest block to be processed. The “last nnnn hours” are calculated from the current time of the allocation for the DD.

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.

GMT|LOCAL

specifies whether the time is local time or GMT time. GMT is the default.

SUBSYS-options2

specifies exit routine unique options. Table 1 shows the combinations of SUBSYS-options2 options that are supported.

Note: If multiple options are required, quotation marks are required around each set of options, and the set of options should be separated by a comma. Quotation marks are not required when only one option is required. For example, the coding SUBSYS=(LOGR,DFHLGCNV,TO=(,12:00),COMPAT41) uses only one SUBSYS-options1 option and one SUBSYS-options2 option, so it does not require quotation marks. However, the coding SUBSYS=(LOGR,DFHLGCNV,'TO=(,12:00),GMT','COMPAT41,SETBRCUR') uses two SUBSYS-options1 options and two SUBSYS-options2 options. Quotation marks are used around each set of options, and the sets of options are separated by a comma.

The options that are valid for CICS log streams when using exit routine DFHLGCNV are:

LASTRUN

indicates that the starting point of the records to be read from the log stream is from the last record read by a previous use of a batch program that used LASTRUN. The end point of the records is to the youngest block in the log stream.

LASTRUN is mutually exclusive with the FROM, TO and DURATION keywords in SUBSYS-options1.

Note: Only one last run point is associated with a log stream. You cannot, for example, specify LASTRUN on a daily log stream processing job and on a job run on a weekly basis

Use the SETBRCUR, REPBRCUR and DELBRCUR options for log stream processing. For more information about how to do this see Using the SETBRCUR, REPBRCUR and DELBRCUR options for log stream processing.

DELETE

indicates 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 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 before the TO= time are deleted from the log stream.

Note: This method of deleting records on an unopened log stream is much faster than deleting records on a log stream that has been opened.

If it is important that unprocessed records are not deleted, put the DELETE keyword as part of a conditional job step; see Example 2.

COMPAT41 or COMPAT41V

If you are running applications against the log stream that require the records to be presented, as far as possible, in the format introduced at CICS Transaction Server for OS/390®, Version 1 Release 1, specify the COMPAT41 option. For COBOL applications, specify the COMPAT41V option. This ensures that records are presented in the correct variable blocked format.

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.

SETBRCUR

indicates that the starting point of the records to be read from the log stream is the position where a deleted cursor was last set (by a batch program that used the DELBRCUR option). Records are read from the deleted cursor to the youngest block in the log stream, or to another position that you have specified (for example, using the TO keyword). When the required records have been read, a browsed 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 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.

REPBRCUR

indicates that records are to be read from the log stream from the position where a deleted cursor was last set (by a batch program that used the DELBRCUR option), to the position where a browsed cursor was last set (by a batch program that used the SETBRCUR option). It repeats exactly the same data that was processed last time you ran a batch program using the SETBRCUR option, provided that the deleted cursor has not been moved since that read. The deleted cursor and browsed cursor are not changed by running a batch program using the REPBRCUR option.

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.

DELBRCUR

indicates that log stream records are to be deleted from the log stream as far as the position where a browse cursor was last set (by a batch program that used the SETBRCUR option). When the required records have been deleted, a deleted cursor is placed at the position where the browse cursor was set.

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.

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.