Mainframe Logger - Extracting Events

Mainframe Logger has an extraction program, SXS3STX1 that reads the IBM z/OS log stream and publishes the same events to an EMS Queue or Topic. Regardless of the NO-SEND parameter, it writes the extracted events to the IBM z/OS file when the file parameter is specified.

A checkpoint file USERHLQ .CHCKPT must always be defined, with DCB information as:
Organization  . . . : PS 
Record format . . . : F  
Record length . . . : 80 
Block size  . . . . : 80 
Sample JCL
//RUNEX1   EXEC PGM=SXS3STX1                       
//STEPLIB  DD DISP=SHR,DSN=USERHLQ.LOAD                  
    :         
//CHCKPT   DD   UNIT=VIO,DCB=(RECFM=F,LRECL=80,BLKSIZE=80)        
//TIBLDATA DD   DISP=(NEW,CATLG,DELETE),DSN=USERHLQ..TIBLDATA,  
//              SPACE=(CYL,(5,5)),                                
//              DCB=(RECFM=VB,LRECL=8000,BLKSIZE=0)                    
//SYSIN    DD   *                                             
//CEEOPTS  DD   *   
  POSIX(ON)       

CHCKPT is a file that can be either virtual Input/Output (VIO) or on Direct Access Storage Device (DASD). If it is on DASD, the LOG offset will checkpoint to this file as needed and subsequent re-starts of SXS3STX1 will position the log at the checkpointed offset. If VIO is selected, then SXS3STX1 will position the log at the oldest item.

SYSIN parameters

Parameters Description
STREAM-NAME

Required. The name of log stream file to be extracted.

URL-SERVER

Only required if NO-SEND parameter is not specified. Specify the URL of the EMS server.

DESTINATION

Name of EMS Destination. The default destination is tibss.syslog.extract.

TYPE

{Queue | Topic} The output destination type (default is Queue).

SELECT-COUNT

{0 - Number} Number of events to read from the log, starting from the beginning. These events will be sent to the destination specified unless the NO-SEND keyword is specified. (default is zero, which reads all events)

BATCH-COUNT

{1 - 10000} Frequency of Checkpointing (default is 1000). Also used to determine the EMS transaction count.

SELECT-RETRY

{0 - Number} Time in seconds to poll (default is zero).

When specified with a number larger than zero, the extraction program runs indefinitely, until the SELECT-COUNT value has been reached or a stop for the job is issued by the operator.

DELETE

{YES | NO} deletes the log events at BATCH-COUNT point (default is NO).

OUTPUT

{JSON | JSON-ALL | JSON-STAT{,MSGINFO} | RAW} Output selection types of the log stream data to be sent or written to a file. (default is JSON).

JSON - Sends all fields where the values are non-zero or not equal to NULL.

JSON-ALL - Sends all fields available in the selected log stream.

JSON-STAT - Sends only statistical important fields {MSGINFO}. In addition, this optional value also sends the data length of the incoming and outgoing user packets, the Substation or application message Id and the message text that was provided to the log stream.

NO-SEND

Does not send events. It reads, discards and when directed deletes the events selected.

COMPRESSION {YES | NO} If compression is set to yes, the logger will apply compression when possible and display a confirmation message (default is YES).
FILE {YES | NO} When specified and in addition to all the other options, the extracted events can also be directed to a local file assigned to DDName TIBLDATA.
HELP

Print input options and end.

DEBUG

{0 - 5} Set the level of debug output in addition to the normal messages (default is 0). If you set the value to one (1), you can see a list of the fields and their values shown in the DDName SYSPRINT.

For example:

Extract all the events and publish them to an EMS Queue.

LOGGER                     SXLLOGS.LOGR.LOG  
DESTINATION                my.stats.json.data
URL-SERVER                 ems.server.com:7222
SELECT-COUNT               1000000
BATCH-COUNT                5000
DELETE                     YES
OUTPUT                     JSON

The program reads up to 1,000,000 events or until end of file, whichever comes first. It also checkpoints every 5000 events and deletes them from the IBM z/OS log stream.