Specifying reports and bpd files with BPACTIVITY

Purpose

The BPACTIVITY command and its REPORT subcommand is used to create reports from collected data. Subcommand options specify the contents and appearances of reports. The REPORT subcommand can be used up to five times within a batch job. This means that you can create up to five different reports by using different options.

The BPACTIVITY command and its FILE subcommand is used to create bpd files from collected data. Subcommand options specify the contents of bpd files. The FILE subcommand can be used only once within a batch job.

Usage

Some options are identical for both subcommands: FROM and TO limit the time frame, INCLUDE and EXCLUDE explicitly include or exclude specific contents, LEVEL specifies whether to include detail data or only summary data in a report or bpd (buffer pool data) file, and DDNAME overwrites the default output ddname.

The REPORT subcommand has one unique option: ORDER arranges the appearance of the reported data.

The FILE subcommand has one unique option: ACTIVEOBJECTS writes only information about active objects to the output ddname.

Defaults

All options provide default values, if none are specified. Thus, the simplest command usage is BPACTIVITY REPORT or BPACTIVITY FILE to produce usable results.

By default, the reports are written to BPRPTDD, and the bpd file is written to BPFILDD1. These defaults can be changed by means of the DDNAME subcommand option.

Subcommand options and keywords

FROM

TO

Use these options with the REPORT or FILE subcommand if you want to selectively use trace data from input data sets for activity reports or bpd files. You can specify the selection by a start date and time (FROM) or an end date and time (TO), or any meaningful combination of both. If these options are used, trace records with timestamps equal or greater, respectively less or equal, to the criteria are included.

Specify dates as mm/dd/yy, whereby mm is the month, dd the day, and yy the year. Specify times as hh/mm/ss.th, whereby hh is the hour, mm the minute, ss the second, and th the thousands of a second (two digits each).

The use of theses options, aligned with appropriate data collection times and intervals, facilitates sophisticated reporting methods. For example, consider a collect task that accumulates summary data of your business' daily peak hours. Using this data as input, you can specify multiple REPORT subcommands in your batch job with different FROM and TO values to create separate summary reports for a comparison by day.

Usually, the use of this option is not required with the FILE subcommand. However, limiting the time scope of the bpd file content can make sense depending on the intended use on the client.

• For viewing performance data (described in Viewing performance data on the client) or object placement optimization (described in Optimizing object placements and initial buffer pool sizes) you can limit the time scope, for example, to isolate a known peak load period from the collected data. You can also segregate multiple periods from a single input data set to create several bpd files, each covering a different period, for example, to perform separate object placement optimizations. This of cause requires multiple runs of your batch job because the FILE subcommand can only be used once in a batch job. Note that both client functions do not provide means to limit the time scope; they use the entire content of the bpd file.
• For long-term analyses, described in Analyzing long-term buffer pool performance, you should ignore the FROM and TO options with the FILE subcommand. This function usually uses several bpd files as input and provides its own means to limit the time scope of data to be included in the analysis.

INCLUDE

EXCLUDE

Use these options with the REPORT or FILE subcommand if you want to selectively use trace data from input data sets for activity reports or bpd files. You can specify the inclusion (in the meaning of include only these) or exclusion (in the meaning of use all but these), or any meaningful combination. If these options are used, data associated with the specified identifier and value combination is included, respectively excluded.

Note that, although these options can be used with the FILE subcommand, they are of limited use and should therefore be avoided. If you are anyway using these options, for whatever reason, be aware that the content of the resulting bpd file is no longer a reliable input to the object placement and initial buffer pool sizing function.

You can use the identifiers listed in Table 1. However, two side effects should be noted:

• The absence of some identifiers affects the contents of summary reports and bpd files. To prevent missing information, ensure that these identifiers are not excluded.
• If the input data was collected with a short record format, some record header information is not present in the trace records. If you specify an identifier for which no header information is available, it will have no effect in reports or bpd files. For example, if you want to explicitly exclude records with a specific end user workstation name (identifier WSNAME), and short record format was used, those records cannot be identified because the WSNAME information is missing in the record header. Nevertheless, the presence of those identifiers do not harm.

Table 1. Possible identifiers for the INCLUDE and EXCLUDE options of the BPACTIVITY command

Identifier	Meaning	Affects summaries	No effect with short record format
BPID	Buffer pool ID	X
CONNTYPE	Connection type		X
ENDUSER	End user ID		X
PLANNAME	Plan name
PRIMAUTH	Primary authorization ID
PSTYPE	Type of page set for table space (T) or index space (I)
QPAGESET	Combination of database and page set	X
TRANSACT	End user transaction name		X
WSNAME	End user workstation name		X

LEVEL

Use this option with the REPORT or FILE subcommand if you want to create a summary report (where detail information is not required) or to avoid detail data in a bpd (buffer pool data) file. By default, if LEVEL is not specified, detail information is processed, which results in a detail report, respectively detail data in a bpd file. (Provided that a data type of Detail was specified when the data was collected.)

If used with the REPORT subcommand, LEVEL(SUMMARY) simply determines that a summary report is to be created. LEVEL(DETAIL) is the default and creates a detail report.

If used with the FILE subcommand, LEVEL(SUMMARY) can considerably reduce the processing time and the file size of the resulting bpd file by eliminating detail data. However, most client-based functions that use bpd files as input require detail data. See Determining what to collect for further details and about which IFCIDs are included in detail and summary data. If processing time and file size are not critical, do not specify LEVEL and accept the default LEVEL(DETAIL).

Note: If the FILE and REPORT subcommands are used together in the same batch job, the same LEVEL specification is required for both subcommands to ensure that either summary or detail data is processed with one invocation of the BPACTIVITY command.

The following examples are valid:

//* Valid invocation. Both subcommands assume LEVEL(DETAIL) as default
BPACTIVITY
   FILE
   REPORT

//* Valid invocation, both subcommands use only summary data
BPACTIVITY
   FILE LEVEL(SUMMARY)
   REPORT LEVEL(SUMMARY)

//* Also a valid invocation because the second REPORT processes
//* a subset of DETAIL data.
BPACTIVITY
   FILE
   REPORT LEVEL(DETAIL)
   REPORT LEVEL(SUMMARY)

The following examples are not valid:

//* Not a valid invocation because FILE excludes detail data.
BPACTIVITY
   REPORT LEVEL(DETAIL)
   FILE LEVEL(SUMMARY)

//* Not a valid invocation because FILE excludes detail data.
BPACTIVITY
   FILE LEVEL(SUMMARY)
   REPORT LEVEL(DETAIL)
   REPORT LEVEL(SUMMARY)

DDNAME

Use this option with the REPORT or FILE subcommand if you want to specify a ddname other than the default for the output reports or bpd files. By default, reports are written to BPRPTDD, and bpd files are written to BPFILDD1. If you specify a ddname, ensure that your JCL contains a valid DD statement for this ddname. If a DD statement is not specified, it is dynamically allocated to the SYSOUT message class of the job. See Specifying a JCL command stream for more information.

ORDER

Use this option with the REPORT subcommand if you want to manipulate the aggregation level and sequence of reported statistics, the sorting of the aggregation, and the threshold for a top-n list of an activity report.

Aggregation summarizes the trace records by specific identifiers. By default report entries are aggregated by buffer pool ID (BPID) and by a combination of database and page set (QPAGESET). Further, the topmost 11 entries are included in the activity report.

• If you want to modify the aggregation level and sequence, you can specify up to three identifiers (id1 to id3) of those listed in Table 2. The number of identifiers determines the aggregation level, and the sequence of identifiers determines the aggregation sequence. Multiple identifiers are separated by a dash (–). Note that some identifiers have no effect if the input data was collected with a short record format (where extensive IFCID header information is omitted).

  Table 2. Possible aggregation identifiers for the ORDER option of the BPACTIVITY command

  Identifier	Meaning	No effect with short record format
  BPID	Buffer pool ID
  CONNTYPE	Connection type	X
  ENDUSER	End user ID	X
  PLANNAME	Plan name
  PRIMAUTH	Primary authorization ID
  PSTYPE	Type of page set for table space (T), or index space (I), or undetermined.
  QPAGESET	Combination of database and page set
  TRANSACT	End user transaction name	X
  WSNAME	End user workstation name	X

• If you want to modify the sort sequence of the (default or specified) aggregation, use the SORTBY option. The sort sequence can be specified by up to two optional identifiers (of those used for the aggregation, listed in Table 2) and one mandatory sort field from those listed in Table 3. Note that the identifiers correspond to record header fields and sort fields to record data fields (containing activity counts).

  Table 3. Possible sort fields for the SORTBY option of the BPACTIVITY command

  Sort field	Meaning	Valid for detail reports	Valid for summary reports
  GETPAGE	Getpage - total	X
  READREQ	Read request - total	X
  READSEQ	Read request - Synchronous	X
  READSYNC	Read request - Seq prefetch	X
  MISSRAND	Getpage Miss Random	X
  MISSASYN	Getpage Miss Asynch	X
  READPAGE	Read page total	X
  WRITEPAGE	Write page total	X
  WRITEREQ	Write request total	X
  SYNCREQ	Synchronous request		X
  ASYNCREAD	Asynchronous request		X
  ASYNCPAGE	Asynchronous page		X

  For example, if you specify ORDER (BPID-CONNTYPE SORTBY (BPID,GETPAGE)), the statistics records are aggregated by BPID and CONNTYPE, but sorted by BPID and the number of Getpage operations.

• If you want to modify the default threshold (11) for the inclusion of statistics records in the activity report, use the TOP option and specify any number other than 11. The TOP option skips reporting for objects that have low usage rates. A value of 0 (or a very high value) includes all records in the activity report. See The report header for an example of how this setting affects the report.

ACTIVEOBJECTS

Specify this option with the FILE subcommand if you want only information about active objects (those with buffer pool activities) in the output data set (the bpd file). By default, if this option is not used, also information about inactive objects (those without activities during the collection time) is included in the output.

The purpose of this subcommand option is to reduce the size of the bpd file if information about inactive objects is not needed. In large installations, the percentage of objects that show no activity during the time data is collected can be high, thus creating large bpd files. Smaller files are faster to download to the client and cause shorter preprocessing times.

Note that the object placement function on the client can make use of information about inactive objects. See Preliminary remarks about the content and filtering of input data and Step 3: Assigning objects to buffer pools (the description about the Used column and the Assign objects not accessed during data collection check box).