JCL for the LOGR Subsystem

Use the SUBSYS parameter to call the log stream subsystem (LOGR) to access log stream data.

//ddname   DD  DSNAME=log.stream.name,
//           SUBSYS=(LOGR[,exit_routine_name][,'SUBSYS-options1'][,'SUBSYS-options2']) 

where:SUBSYS-options1: 
[FROM={({[yyyy/ddd][,hh:mm[:ss]]})  | OLDEST}]
[TO={({[yyyy/ddd][,hh:mm[:ss]]})  | YOUNGEST}]
[,DURATION=(nnnn,HOURS)]
[,VIEW={ACTIVE|ALL|INACTIVE}] 
[,GMT|LOCAL] SUBSYS-options2: 
defined by the log stream owner

Note: Quotation marks around keywords are required when parentheses, commas, equal signs, or blank characters are used within the SUBSYS keyword.

Other DD keywords are validated, if specified, but are ignored in the LOGR subsystem processing.

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. The exit_routine_name is the second positional parameter and specifies the name of the exit routine to receive control from the LOGR subsystem.

Specify or use the default value to IXGSEXIT to use the log stream subsystem exit routine.
Specify IFBSEXIT to access records from the logrec log stream. See SUBSYS-options2 for logrec-specific paramters.
Specify IFASEXIT to access records from SMF log streams. See SUBSYS-options2 for SMF-specific parameters.

SUBSYS-options1

Specifies options that are meaningful to all exit routines. See the documentation for a specific log stream exit for exceptions to these common options. The keywords are:

FROM=starting_time

Indicates the starting time of the first log stream block to be processed based on the log stream view that the VIEW keyword specifies. The first block is the one with a time stamp later than or equal to the specified time.

OLDEST: Indicates the first block read is the oldest block on the log stream. OLDEST is the default.
yyyy/ddd: Specifies the start date. If the date is omitted, the current date is assumed. yyyy is a 4-digit year number and ddd is a 3-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 the time is omitted, the first block written after midnight is used. hh is a 2–digit hour number from 00 to 23, mm is a two 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 it is not required by the log stream owner.

The FROM keyword is mutually exclusive with the DURATION keyword.

TO=ending_time

Indicates the ending time of the last log stream block to be processed based on the log stream view that the VIEW keyword specifies. The last block is the one with a time stamp earlier 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. YOUNGEST is the default.
yyyy/ddd: Specifies the end date. If the date is omitted, the current date is assumed. yyyy is a 4-digit year number and ddd is a 3-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 will be used. If the end date is the same as the current day, then the youngest block on the log stream at the time the allocation for the DD occurs will be used. hh is a 2–digit hour number from 00 to 23, mm is a two 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 it is not required by the log stream owner.

The TO keyword is mutually exclusive with the DURATION keyword.

Note: If the value specified for the FROM keyword is greater than the value specified for the TO keyword, the system ends the jobstep with a JCL error.

DURATION=(nnnn,HOURS)

Specifies which blocks are to be processed. Each n is a numeric from 0 to 9. Specifying (nnnn,HOURS) requests the blocks for the last nnnn hours up to the youngest block that is to be processed based on the log stream view that the VIEW keyword specifies. The last nnnn hours are calculated from the current time of the allocation for the DD.

The first block is the one with a time stamp greater than or equal to the calculated start time. The last block read is 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.

VIEW=ACTIVE|ALL|INACTIVE

Specifies the view or portion of log data to be used to obtain records from the log stream. System logger maintains two kinds of log stream data in a log stream: an active portion and an inactive portion. The active portion of the log stream is the log data that the log stream owner has not logically deleted through an IXGDELET request. The inactive portion of the log stream is the log data that the log stream owner has logically deleted but that has not yet been physically deleted from the log stream because the retention period (RETPD) specified for the log stream has not yet expired.

The VIEW option designates the portion(s) of the log stream to be used to obtain log data from the log stream, in addition to applying the other parameters.

Because the other parameters also apply, the combination of the FROM, TO, or DURATION parameters and the VIEW parameter might mean that the log stream subsystem exit returns no log data or only a portion of the intended log data. For example, if FROM=starting_time and VIEW=INACTIVE are both specified, and the starting_time is later (younger) than the log data in the inactive portion of the log stream, then there is no log data to meet the access criteria. In the same way, if TO=ending_time and VIEW=ACTIVE are both specified, and the ending_time is earlier (older) than the log data in the active portion of the log stream, then there is no log data to meet the access criteria.

ACTIVE: The view of the log stream is to include only active log data, in addition to applying the other log stream access parameters. ACTIVE is the default.
ALL: The view of the log stream is to include both active and inactive log data, in addition to applying the other log stream access parameters.
INACTIVE: The view of the log stream is to include only the inactive log data, in addition to applying the other log stream access parameters.

GMT|LOCAL

Specifies whether the time is local time (based on the time zone offset at the time the log was written) or GMT time. GMT is the default.

SUBSYS-options2

Specifies unique exit routine options. See the following:

For information about obtaining records from the logrec log stream, see z/OS MVS Diagnosis: Tools and Service Aids.
For information about obtaining records from SMF log streams, see Using SMF log streams in z/OS MVS System Management Facilities (SMF).