Specifying reports and bpd files with BPACTIVITY
Use the BPACTIVITY command within a JCL command stream to specify the contents of reports and bpd files.
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.
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.
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
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
mmis the month,
ddthe day, and
yythe year. Specify times as
hhis the hour,
ssthe second, and
ththe 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.
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
WSNAME), and short record format was used, those records cannot be identified because the
WSNAMEinformation 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
Buffer pool ID X
Connection type X
End user ID X
Primary authorization ID
Type of page set for table space (T) or index space (I)
Combination of database and page set X
End user transaction name X
End user workstation name X
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
Detailwas 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)
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.
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-nlist 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
Buffer pool ID
Connection type X
End user ID X
Primary authorization ID
Type of page set for table space (T), or index space (I), or undetermined.
Combination of database and page set
End user transaction name X
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 - total X
Read request - total X
Read request - Synchronous X
Read request - Seq prefetch X
Getpage Miss Random X
Getpage Miss Asynch X
Read page total X
Write page total X
Write request total X
Synchronous request X
Asynchronous request X
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.
- 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).
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).