BBI-SS PAS journal log

BBI-SS PAS journal logging begins automatically when the BBI-SS PAS is started, unless the corresponding DD statements are removed from the BBI-SS PAS JCL.

A BBI-SS PAS journal log records:

• All BBI commands and responses issued from terminal session users assigned to the BBI-SS PAS
• All commands and responses issued automatically by BMC AMI Ops Automation EXECs
• Time stamps for BBI-SS PAS and target system start and stop
• Any warning or exception warning message issued by services
• BBI informational, error, and audit messages
• Service commands and messages
• Db2 commands and messages (BMC AMI Ops Monitor for Db2 only)

When messages are written to the system console, such as WTOs (write-to-operators), the BBI-SS PAS subsystem ID is appended whenever possible. The subsystem ID is not recorded in the BBI-SS PAS journal log.

Viewing a BBI-SS PAS journal log online

Use the LOG DISPLAY option from the Primary Option Menu to view a BBI-SS PAS journal log online. The log displayed is identified by the entry in the TGT field, which you can change. You can scroll the display left and right.

• If a target system ID is entered, the journal log of the BBI-SS PAS assigned to the target is displayed.
• If a BBI-SS PAS ID is entered, the journal log of that BBI-SS PAS is displayed.

The TGT value can be modified. When the value is changed, the BBI-SS PAS journal belonging to that specified target is displayed.

Enhanced journal facility

The Standard Journal Facility displays all messages from the BBI-SS PAS assigned to the specified target (default). However, the Enhanced Journal Facility provides user-customizable subsets of the Log Display. It allows you to view subsets of the journal log defined by one or more message origins.

The PROFILE command displays an input panel where you can define which messages you want to see. You can specify up to six patterns for message origins to be included and six patterns for message origins to be excluded in the display. Generic qualifiers can be used to define these patterns. For example, you can include all messages from CICS* and exclude all messages from CICSTEST.

You also can include messages from the current target specified in the TGT field by specifying the variable, &target, in the Included Origins column.

These specifications are saved in userid.BBPROF member LDPARM00, which enables each user to have an individual application profile.

To view the origin of the messages in the Log Display, scroll to the left.

Displaying the status of a BBI-SS PAS journal log

To display the status of a BBI-SS PAS journal log, use the BBI control command DISPLAY JOURNAL (see BBI-control-commands for more information about the DISPLAY command).

Switching BBI-SS PAS journal log data sets

When one BBI-SS PAS journal log data set becomes full, logging is switched automatically to the alternate data set.

Logging also can be switched manually to the alternate data set with the BBI control command SWITCH JOURNAL. This command could be used, for example, to synchronize the data sets with a target session (see BBI-control-commands for more information about the SWITCH command).

Whenever a journal log data set is switched, either automatically or manually, a user exit (BBIUSR01) is invoked automatically to dump and reset the data set so that it is available for reuse (for more information, see Customizing-after-installation).

Printing a BBI-SS PAS journal log

You can print a BBI-SS PAS journal log in the following ways:

• Automatically

  User exit BBIUSR01 is scheduled automatically to invoke a started task that prints and resets the BBI-SS PAS journal log data set (see Creating-automatic-BBI-SS-PAS-log-handling-procedures).

• Manually by copying BBSAMP member DLOGJCL

  Edit the copied sample procedure to replace the PROC statement with a JOB statement. Submit the job to print and reset the BBI-SS PAS journal log data set so it can be reused.

  Note

  To print the BBI-SS PAS journal log to a data set on disk or tape, the BBIPRINT DD statement can be modified to point to a data set with DCB=(RECFM=FBA,LRECL=121) specified. Any suitable BLKSIZE is allowed.

• Manually by copying BBSAMP member PLOGJCL

  Edit the copied sample JCL and submit the job to print and not reset the BBI-SS PAS journal log data set. The data set must first be closed.

Extracting BBI-SS PAS journal log records to CSV format (PTF BQI2590 applied)

You can extract selected archived BBI-SS PAS journal records into comma-separated values (CSV) format. You can then process the records using off-mainframe analytics tools, such as Excel or Splunk. To extract the records, perform the following steps:

1. Copy and edit the BBSAMP member DLOGJCL (BBIDLOG proc), or modify the current proc specified in your BBPARM member BBISSPxx in the JRNLSTC= parameter as follows:
   1. Direct the BBIPRINT DD to a preallocated archive sequential data set. This step is required to issue LG1207I messages. If the BBIPRINT DD is directed to SYSOUT, the LG1207I message is not issued.

   2. Add PARM=’&SSID’ to the end of the EXEC statement to pass the SSID of the relevant PAS to LGLOGP: //IEFPROC EXEC PGM=LGLOGP,PARM=’&SSID’

      SSID is an optional parameter, but it is recommended. If you do not pass it to LGLOGP, it has a null value in the SSID column in the output CSV data set.

2. Modify the BBSAMP member JRNLBTCH as follows:

   Parameter	Required	Description
   SYSPROC DD	Yes	Data set where the JRNLCSV REXX program is located
   DATAIN DD	Yes	Archive data set specified in the BBIPRINT DD of the modified DLOGJCL proc
   DATAOUT DD	Yes	CSV output data set
   SYSIN DD	Yes	Selection criteria for selecting messages from the BBI-SS PAS journal: Selection Criterion Description FROM Start date/time Format is YYYYMMDD HH:MM:SS. Example: 20190507 06:35:00 TO End date/time Format is YYYYMMDD HH:MM:SS. Example: 20190508 06:35:00 ORIGIN The origin of the event message, which is column 3 from the archive data set written to the BBIPRINT DD (see the sample of offloaded BBI-SS PAS journal data) Wildcards are allowed. Multiple ORIGIN parameters are allowed. MSGID First space-delimited word of the message text Wildcards are allowed. Multiple MSGID parameters are allowed. Examples: If the message is: " EM0027I  EXEC DALSTRT  EID= 75273 ENDED ON 17-MAY-18 AT 00:00:00 ", then the MSGID is "EM0027I". If the message is: " DEKZCAT.LOGCOPY1.DS01, STARTRBA=0000000001311AD0B000,", then the MSGID is "DSNAME=DEKZCAT.LOGCOPY1.DS01,". All selection criteria are required. The extraction process is terminated if a keyword is missing. The input field for selection criteria is columns 1–72. You can enter selection criteria on multiple lines. For example: FROM * TO * ORIGIN SW1C      MVSSYW      AAOSW81 MSGID I*       PM* For all selection criteria, an asterisk indicates any value. To treat an asterisk as a literal, enclose it in single quotes. For example: MSGID * means all message IDs that starts with any character. MSGID '*'* means all message IDs that start with a literal asterisk. If you do not enter a value for any of the selection criteria, or if you enter an asterisk (*), they have no filtering effect. Selection Criterion Description FROM * No lower date/time limit for extraction TO * No upper date/time limit for extraction ORIGIN * No origin filter for extraction MSGID * No message ID filter for extraction You can use an asterisk as a wildcard for ORIGIN and MSGID. For example: MSGID PM*,*2E,EM*I PM* = PM0010I,PM0137I *2E = CT1122E,IM9242E EM*I = EM0026I,EM0027I

3. Copy the edited DLOGJCL and JRNLBTCH members to your JES PROCLIB data set. Rename them as necessary to meet your installation naming standards.
4. Edit the BBISSPxx  parameter JRNLSTC= to point to the edited DLOGJCL proc.
5. Use your automation product to intercept message LG1207I, which is issued when a journal data set is archived, and trigger the edited JRNLBTCH Started Task. For example, you can use BMC AMI Ops Automation for z/OS to define a rule that intercepts the LG1207I message and trigger a START command as follows:
   1. Add an event-type MSG rule to an enabled rule set for BMC AMI Ops Automation for z/OS PAS running on the same LPAR from which the  LG1207I message is issued with the following specifications:
      • Selection criteria:
        • Event type: MSG
        • Text ID: LG1207I
        • Any additional selection criteria based on your automation needs
      • Actions:
        • MVS command to start the proc created from the sample JRNLBTCH proc

1. 
   
   1. 
      
      • 
        
        • Any additional actions based on your automation needs
          
   2. Save this rule to a rule set that will be enabled.

   3. When the LG1207I message is issued, the rule issues a START command, assigning the fields from the message as values for JRNLCSV input parameters:
      The following table describes the parameters passed to the JRNLBTCH by the START command:

      Parameter	Description
      archive dataset	Archive data set specified in the BBIPRINT DD of the modified DLOGJCL proc
      system	Name of the system on which the BBI PAS is running
      sysplex	Name of the sysplex on which the BBI PAS is running
      ssid	BBI-SS name of the PAS to which the archived journal records belong If this is not passed to LGLOGP in DLOGJCL proc, it has a null value.

2. To test the setup, trigger the process by issuing the .I J BBI command to switch between the two BBI-SS PAS journal data sets that are allocated to your BBI PAS.

A sample of offloaded BBI-SS PAS journal data follows:

The output CSV contains the following columns:

• SYSPLEX
• SYSTEM
• SSID - If you did not enter PARM=’&SSID’ as a LGLOGP parameter, the SSID column of the CSV output contains a null value.
• DATE
• TIME
• ORIGIN
• MESSAGE - Enclosed in double quotation marks. Double quotation marks that appear in the message are doubled.

Sample content of CSV on mainframe

Sample content of CSV in Excel

You can use SFTP to export your CSV file out of the mainframe for analysis. For more information about using SFTP, see Exporting-historical-data-using-SFTP.

Restricting BBI-SS PAS journal log messages and commands

Use the journal log user exit routine SMLXIT to selectively restrict the messages and commands that go to the BBI-SS PAS journal log. The message text, however, cannot be altered.

The exit must be link-edited as reusable with the name SMLXIT. The following conventions are used:

• Upon entry, register 0 points to one of the following values:
  • the VTAM node name that issued the command or received the message
  • the job name of the target system that sent a message to the BBI-SS PAS
  • the user ID that issued the command

  • the subsystem name that responded to the command

    Register 1 points to one of the following locations:

    • +0 points to the length (two bytes) of the command or message text
    • +4 points to the actual text to be edited

• Upon exit, all registers are restored except for register 15, which contains one of the following return codes:

  • RC=0 Log the message or command to the BBI-SS PAS journal log.
  • RC=4 Do not log the message.

  Note

  Do not call other routines from this exit. The message cannot be changed.

A coding example of the journal log exit is supplied in BBSAMP member SMLXIT. Make any required changes, and then assemble and link-edit SMLXIT into the load library. If SMLXIT is in the load library, the exit is loaded at BBI-SS PAS initialization time. The following message is displayed on the console and written to the BBI-SS PAS journal log:

Handling BBI-SS PAS journal log maintenance and errors

When the journal log is full or an I/O error is encountered on the journal, a user exit named BBIUSR01 is invoked (see Customizing-after-installation).

When an error occurs, a message is sent to the BBI-SS PAS journal log for user action. Logging can be resumed by issuing the BBI control command START JOURNAL described in BBI-control-commands. When a BBI-SS PAS journal log is restarted after being stopped for any reason, recording resumes where it left off when the journal was stopped.