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.
Additional parameters for system logger
Along with the general parameters that can be specified for a
log stream subsystem data set, system logger provides additional parameters
in the
SUBSYS-options2 specifications. The following values
can be coded for a logrec log stream:
- SUBSYS-options2
- Specifies unique exit routine options. Refer to information provided
by the specific log stream owner concerning these parameters.
- LASTRUN
- Indicates that the starting point of the records to be read from
the logrec log stream will be from the last record read by a previous
use of an application that used LASTRUN. The end point of the records
will be to the youngest block in the logrec log stream.
LASTRUN
is mutually exclusive with the FROM, TO and DURATION keywords in SUBSYS-options1 and with DELETE from SUBSYS-options2.
- DELETE
- Indicates that log stream records are to be deleted from the logrec
log stream. The log stream itself is not deleted and remains available
for use.
If the logrec log stream has been opened in the job step,
all records up to but not including the last complete block read by
the program will be deleted from the logrec log stream.
If the
logrec log stream has not been opened in the job step, all records
prior to the time indicated on the TO keyword will not be deleted
from the logrec log stream.
DELETE is mutually exclusive with
the FROM and DURATION keywords in SUBSYS-options1 and the LASTRUN
and SYSTEM keywords from SUBSYS-options2.
- DEVICESTATS
- Requests that the device statistics kept on the system where this
job is running are to be recorded in the logrec log stream before
any records are read.
- SYSTEM=system name
- Indicates that only records originating from the specified system name are to be returned to the application reading
the logrec log stream. The system name value should
match the name specified in the SYSNAME parameter of the IEASYSxx
parmlib member. SYSTEM= is mutually exclusive with
the DELETE keyword from SUBSYS-options2.
Time of day considerations for logrec
When
using the SUBSYS DD statement for LOGR, handle the time of day filtering
carefully. The SUBSYS parameter does not accept a stop time of 24:00,
but the EREP parameters do accept 24:00 as a stop time. If it is necessary
to write JCL and EREP control statements, you might have to request
filtering through both the SUBSYS DD statement and the EREP parameters:
- SUBSYS parameters use blocks of records, and filtering of these
blocks is done using time stamps assigned after each logical record
enclosed in a block has been assigned its own time stamp.
Figure 1 shows how to select logrec log stream
records that were produced between 05:00 on June 1st, 1997, and the
end of that day.
Figure 1. Example: Using SUBSYS parameters //ACCIN DD DSN=SYSPLEX.LOGREC.ALLRECS,DISP=SHR,
// DCB=(RECFM=VB,BLKSIZE=4000),
// SUBSYS=(LOGR,IFBSEXIT,
// 'FROM=(1997/152,05:00),TO=(1997/153,23:59),GMT')
- EREP parameters use logrec logical records. When you use the
TIME parameter with EREP, you are specifying a range of hours and
minutes of interest on each day selected.
Table 1 shows how to correctly select logrec records that were produced
between 05:00 on June 1st, 1997, and the end of that day.
Table 1. Example: Using
EREP parameters| Correct coding example |
Incorrect coding example |
|---|
DATE=(97152-97152),TIME=(0500-2400)
|
DATE=(97152-97153),TIME=(0500-0000)
|
Creating a history data set for log data
Use the JCL in Example: Creating a history data set to create a history data set from log data recorded on the logrec
log stream. In this example, DEVICESTATS requests device statistics
and the records are to be recorded in the log stream. Records are
read from the last block that was processed on the previous submission
of a "LASTRUN" EREP job up to the youngest block in the log stream.
The first time a job with the "LASTRUN" option is run, the records
are read from the oldest block in the log stream.
Example: Creating a history data set
//EREPDALY EXEC PGM=IFCEREP1,PARM=('HIST,ACC=Y,SYSUM')
//ACCIN DD DSN=SYSPLEX.LOGREC.ALLRECS,
// SUBSYS=(LOGR,IFBSEXIT,,'DEVICESTATS,LASTRUN'),
// DCB=(RECFM=VB,BLKSIZE=4000)
//ACCDEV DD DSN=EREP.HISTORY,
// DISP=(NEW,CATLG),
// DCB=(RECFM=VB,BLKSIZE=4000),
// UNIT=SYSDA,SPACE=(CYL,(25,5))
//SERLOG DD DUMMY
//DIRECTWK DD UNIT=SYSDA,SPACE=(CYL,15,,CONTIG)
//TOURIST DD SYSOUT=A,DCB=BLKSIZE=133
//EREPPT DD SYSOUT=A,DCB=BLKSIZE=133
//SYSABEND DD SYSOUT=A
//SYSIN DD DUMMY
/*
Producing an event
history from logrec
Use the JCL shown in Example: Producing an event history to produce an event history report from
records on the logrec log stream. By not specifying the FROM or TO
keywords, the default is FROM=OLDEST and TO=YOUNGEST, indicating processing
should include records from the beginning of the log stream to the
end of the log stream. By specifying a print data set, EREPPT, the
report can be browsed online for an overview of significant activity.
When reading records by date and time, you can provide both EREP and
SUBSYS parameters. EREP selects records from those passed to it from
the SUBSYS parameters.
Example: Producing an event history
//EREPNOW EXEC PGM=IFCEREP1,REGION=4M,
// PARM='CARD'
//ACCIN DD DSN=SYSPLEX.LOGREC.ALLRECS,
// DISP=SHR,
// SUBSYS=(LOGR,IFBSEXIT,,)
//DIRECTWK DD UNIT=SYSDA,SPACE=(CYL,5,,CONTIG)
//EREPPT DD DSN=EREP.EVENT,DISP=(NEW,CATLG),
// DCB=BLKSIZE=133,
// UNIT=SYSDA,SPACE=(CYL,(25,5))
//TOURIST DD SYSOUT=A,DCB=BLKSIZE=133
//SYSABEND DD SYSOUT=A
//SYSIN DD *
EVENT
HIST
ACC=N
TYPE=ACDEHIMOSX
ENDPARM
/*