Batch Report Writer Operation

The Batch Report Writer reads the request file to determine what data is required from the trace input and what format to use on the output report. Once this information is generated, the input file is read sequentially to collect all the data that is required to satisfy every request.
caidb219
The
CA SYSVIEW for DB2
Batch Report Writer reads the request file to determine what data is required from the trace input and what format to use on the output report. The input file is then read sequentially to collect all the data that is required to satisfy every request. The results can be sorted. The requested reports are written to the output data sets and the program terminates.
Prerequisites
The Batch Report Writer has the following prerequisites:
  • If SMF or GTF records are used as an input, they should be sorted in time sequence order (
    ccyymmddhhmmss999999
    ), where
    999999
    is fractions of a second. A single GTF or SMF file is typically in the correct order. However, when you concatenate files, the records can be out of sequence. The SAVEIFI or online history VSAM file has data in the correct sequence. You cannot concatenate multiple SAVEIFI or online history files.
  • Sufficient virtual storage to process the requests.
Input Files
The Batch Report Writer is submitted as a batch job that uses the following input:
  • Batch Report Writer parameters file
  • Request file that contains the IQL requests to run
  • Db2 trace data file, which can be any of the following file types:
    • Unloaded SMF file
    • GTF file
    • SAVEIFI trace VSAM linear data set from online IQL execution
    • Unloaded online SAVEIFI or history file (which are in SMF format)
    • An online history STATS or ACCOUNTING VSAM linear data set
    The Batch Report Writer accepts only one input data file. If multiple data files are provided, the Batch Report Writer picks one according to the following preference:
    1. //HISTACCT
    2. //HISTSTAT
    3. //SAVEIFI
    4. //DB2DDN
The Batch Report Writer IQL requests that specify the INTERVAL parameter require the sorting of Db2 trace records in time ascending sequence. If you are concatenating multiple GTF or SMF files, the data
must
be sorted. Exit routines NSIGHT15 and NSIGHT35 are provided to sort the GTF and SMF Db2 trace records according to the store clock (STCK) value in QWHSSTCK.
Sample JCL is provided in the SMFSORT member in the SOURCE data set.
The Batch Report Writer can process SMF records that were compressed when SMFCOMP=ON.
The Batch Report Writer does
not
start any traces. Put the Db2 trace records in the file using
one
of the following methods:
  • Start traces manually or automatically (using Db2 initialization parameters or Db2 START TRACE commands).
  • Start an IQL request using the SAVEIFI output destination.
  • Unload the online history or online trace file.
Output Files
The Batch Report Writer output files are a system message file, and the report and output files that were specified in the requests.
Termination Codes
Batch Report Writer termination codes are listed in the section Return Codes.
Batch Report Writer JCL Example
Member IDB2RWJ includes the sample JCL for executing the Batch Report Writer. The member is located in the
CA SYSVIEW for DB2
source library. We recommend that you tailor this member to produce only the reports you want by including the DBGIN statements of the reports.
For more examples, refer to the section Batch Report Filtering Examples.
DD Statements
JCL for executing the Batch Report Writer includes the following required or optional DD statements:
  • jobcard1
    and
    jobcard2
    (Required) Contains a jobname and other parameters according to your site conventions, regarding installation job naming and the JOB statement parameter specification.
  • //IDB2RWJ EXEC
    (Required) Invokes the Batch Report Writer program and specifies the available region size.
    Add a PARM= value to the EXEC statement to override certain SYSPARMS values that are specified in the file pointed to by the SYSPARMS DD statement.
    The following parameters can be specified:
    • DBSUB
      Specifies the Db2 subsystem to report on, for example:
      //IDB2RWJ EXEC PGM=NSIGHTRW,REGION=4M,PARM='/DBSUB=ssid'
    • DBLOC
      Specifies the Db2 location, for example:
      //IDB2RWJ EXEC PGM=NSIGHTRW,REGION=4M,PARM='/DBLOC=location'
    • DB2VER
      Specifies the Db2 version for processing the requests that are specified as input using the DBGIN DD statement, for example:
      //IDB2RWJ EXEC PGM=NSIGHTRW,REGION=4M,PARM='/DB2VER=version'
  • //STEPLIB
    Specifies the authorized library containing the load modules. This DD statement is required unless the library containing the product load modules is part of the LINKLIB concatenation.
  • //SYSPARMS
    (Required) Points to the file containing the Batch Report Writer parameters.
  • Trace Data Files
    One of the following statements is required:
    • //DB2DDN
      Points to the Db2 file containing the sorted (by date and time) GTF or SMF trace data. This statement can also be an unloaded online history file.
    • //SAVEIFI
      Points to a single SAVEIFI trace VSAM linear data set containing the records that the IQL SAVEIFI trace output destination captured. For more information about the SAVEIFI output option, see the topic Output-Specification.
    • //HISTSTAT
      Points to an online history statistics VSAM linear data set. The data collector that owns this file may be either up or down when the report writer is executed.
    • //HISTACCT
      Points to an online history accounting VSAM linear data set. The data collector that owns this file may be either up or down when the report writer is executed.
  • //OBIDTBL
    Translates DBIDs and OBIDs into database and tablespace names. This DD statement is recommended for proper translation.
  • //DBGIN
    (Required) Points to the input request stream, which specifies the reports and report formats to generate from the Db2 trace data. This statement can be a single file containing one request or a single file containing multiple requests. This statement can also be (as in the sample) a list of concatenated files, each containing an individual request.
    You can include a GLOBAL WHERE clause into the input request stream to filter data by specific criteria. For IQL syntax details, see GLOBALS Statement.
    //DBGIN DD *
    GLOBALS
    WHERE EVENT-TIME >= '150716120330' AND <= '150716170000'
    AND PLAN-NAME = 'PAY200'
    // DD DSN=hlq.CDBATREQ(BTACTSMS),DISP=SHR
  • //DBGPRINT
    (Required) Points to the IDB2RWJ messages file destination.
  • //SYSUDUMP
    (Optional) Points to a destination for any ABEND dumps that occur during execution.
  • //BTACTSMS
    (Required) Represents the name of the output for the same named request. The sample JCL includes one DD statement for each of the same named requests that are specified in the DBGIN DD statement concatenation list. This statement points to a SYSOUT data set to contain output reports or a data set that is the destination for the output reports.
If the IQL contains GROUP BY or ORDER BY syntax, the Batch Report Writer sorts the results before writing the output. The Batch Report Writer can sort the data internally or it can LINK to the system SORT routine. The internal sort routine is used when there is a small amount of data to sort. Otherwise, the system SORT routine is used. If the system SORT routine is used, the sort work data sets (SORTWKxx DD statements) are dynamically allocated with the appropriate size. You can specify the SORTWKxx DD statements in the JCL.
We recommend that you do
not
specify the SORTWKxx DD statements, because the number and size of sort work data sets required are unknown.
  • //SORTWKxx - where xx is 01, 02, 03, etc.
    Allocates the sort work data sets for the system SORT routine. This DD statement is optional and its use is not recommended.
  • //DFSPARM DD *
    (Optional) Controls the system SORT PARM options and program control statement overrides. Use of this statement overrides the system SORT routine defaults and the defaults that the batch Report Writer specifies. We do not recommend use of this DD statement.
    For more information about this DD statement, see the IBM
    z/OS DFSORT Application Programming Guide
    .