Print PEX Report (PRTPEXRPT)

The Print Performance Explorer Report (PRTPEXRPT) command prints a formatted listing of the data that was collected by the performance explorer and saved across a set of physical files in a particular library.

Restriction

This command is shipped with PUBLIC *EXCLUDE authority.
You must have read and execute authority to the specified library.
To use this command you must have *SERVICE special authority, or be authorized to the Service Trace function of Operating System/400 through iSeries Navigator's Application Administration support. The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform trace operations.

Parameters

Keyword	Description	Choices	Notes
MBR	Member	Name	Required, Positional 1
LIB	Library	Name, QPEXDATA	Optional, Positional 2
TYPE	Type	STATS, TRACE, PROFILE, BASIC	Optional, Positional 3
OUTPUT	Output	PRINT, OUTFILE	Optional, Positional 4
OUTFILE	File to receive output	Qualified object name	Optional, Positional 5
	Qualifier 1: File to receive output	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
OUTMBR	Output member options	Element list	Optional, Positional 6
	Element 1: Member to receive output	Name, *FIRST
	Element 2: Replace or add records	REPLACE, ADD
TRACEOPT	Trace options	Element list	Optional, Positional 7
	Element 1: Sort by	TIMESTAMP, TASK
	Element 2: Omit completion records	NO, YES
	Element 3: Omit Category	Single values: NONE Other values (up to 10 repetitions): PGM, LICPGM, ASM, BASE, DISK, DSKSVR, FAULT, JOB, LOCK, SAR, MIBRKT, LICBRKT, DASD, DASDSRVR, PAGEFLT, RMPR, RMSL
TRCTYPE	Select trace type	Single values: ALL Other values (up to 11 repetitions): CALLRTN, BASIC, DSKIO1, DSKIO2, DSKSVR, DSKSTG, VRTADR, PGMACT, FILEOPEN, PRFDTA, TASKSWT	Optional, Positional 8
PERIOD	Time period for report	Element list	Optional, Positional 9
	Element 1: Start time and date	Element list
	Element 1: Starting time	Time, *AVAIL
	Element 2: Starting date	Date, CURRENT, BEGIN
	Element 2: End time and date	Element list
	Element 1: Ending time	Time, *AVAIL
	Element 2: Ending date	Date, CURRENT, END
SLTJOB	Select jobs	Single values: ALL Other values (up to 10 repetitions): Qualified job name*	Optional, Positional 10
	Qualifier 1: Select jobs	Generic name, name
	Qualifier 2: User	Generic name, name, *ALL
	Qualifier 3: Number	000001-999999, *ALL
OMTJOB	Omit jobs	Single values: NONE Other values (up to 10 repetitions): Qualified job name*	Optional, Positional 11
	Qualifier 1: Omit jobs	Generic name, name
	Qualifier 2: User	Generic name, name, *ALL
	Qualifier 3: Number	000001-999999, *ALL
STATSOPT	Stats options	Element list	Optional, Positional 12
	Element 1: Sort by	Integer, PGMNAME, INVCNT, CPU, DBSYNCIO, DBASYNCIO, NDBSYNCIO, NDBASYNCIO, MICALLS, MIINST, CUMLCPU, CUMLDBSYNCIO, CUMLDBASYNCIO, CUMLNDBSYNCIO, CUMLNDBASYNCIO
	Element 2: Summarize by	BLANK, MODULE, *PROGRAM
PROFILEOPT	Profile options	Element list	Optional, Positional 13
	Element 1: Sort by	SAMPLECOUNT, ADDRESS
	Element 2: Summarize by	BLANK, STATEMENT, PROCEDURE, MODULE, *PROGRAM
	Element 3: Filter percentage	0-99, 0
ORDER	Order	ASCENDING, DESCENDING	Optional, Positional 14
NBRTHD	Number of threads	1-64, 1, *CALC	Optional, Positional 15
TASKINF	Task information	ALL, NONE	Optional, Positional 16

Top

Type (TYPE)

Specifies the type of report to produce. The type of report requested must match the type of data that was collected. If there is a mismatch, an error message is issued. The type of performance data collected is determined by the performance explorer definition that was specified on the Start Performance Explorer (STRPEX) command. Refer to the Add Performance Explorer Definition (ADDPEXDFN) command for more information.

Note: An exception to the matching of types occurs when you collect data with a definition of TYPE(*TRACE) INTERVAL(nn) BASEVT(*PMCO). When you collect this trace data, you are allowed to specify a report type of *PROFILE. This type of report is known as a *TRACE collection and a *PROFILE report.

*STATS: A statistics report is produced.
Note: This parameter is valid only for data collected by *STATS mode definitions.
*TRACE: A trace report is produced.
Note: This parameter is valid only for data collected by *TRACE mode or *PROFILE PRFTYPE(*JOB) definitions.
*PROFILE: A profile report is produced.
Note: This parameter is valid only for data collected by *PROFILE mode definitions or *TRACE TRCTYPE(*PROFILE) definitions.
*BASIC: A basic report is produced that includes the definition, run, and task information sections.
Note: This parameter is valid for data collected by any definition.

File to receive output (OUTFILE)

Specifies the name of the database file to which the output of the command is directed. If this file does not exist, this command creates a database file in the specified library. The public authority is the same as the create authority specified for the library in which the file is created.

Notes:

The file specified here cannot be a DDM file
The model file QAVPETRCI resides in library QPFR.

The possible library values are:

*LIBL: The library list is used to locate the output file. If the output file is not found, one is created in the current library. If no current library exists, the output file is created in the QGPL library.
*CURLIB: The current library for the job is used to locate the specified output file. If no library is specified as the current library for the job, the library QGPL is used.
library-name: Specify the name of the library where the output file is located.

database-file-name: Specify the name of the output file that receives the output of the command.

Output member options (OUTMBR)

Specifies the name of the database file member to which the output is directed.

Element 1: Member to Receive Output

*FIRST: The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified on the OUTFILE parameter. If the member already exists, the user has the option to add new records to the end of the existing member or clear the member and then add the new records.
member-name: Specify the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it. If the member already exists, you have the option to add new records to the end of the existing member or clear the member and then add the new records.

Element 2: Operation to Perform on Member

*REPLACE: The system clears the existing member and adds the new records.
*ADD: The system adds the new records to the end of the existing records.

Trace options (TRACEOPT)

Specifies how to organize a trace (*TRACE) report. Records are ordered based on the value specified for the ORDER parameter.

Element 1: Sort by

This value represents how the data is ordered.

*TIMESTAMP: The records are listed in time stamp order.
*TASK: The records are listed in time stamp order within each job/task.

Element 2: Omit completion records

This provides a mechanism to reduce large amounts of data to enable more efficient review of the data.

*NO: All records associated with this performance data collection session are included in the report.
*YES: All completion records are excluded from the report. This is helpful if there is a large amount of data to review.

Element 3: Omit category

Specify one or more categories to be omitted from the generated report.

The possible single value is:

*NONE: No categories are omitted.

The possible omitted category values are

*PGM: Exclude the category for the program call flow events.
*LICPGM: Exclude the category for the Licensed Internal Code call flow events.
*ASM: Exclude the category for the auxiliary storage management events.
*BASE: Exclude the category for the base events, which includes tasking events.
*DISK: Exclude the category for the direct access storage device events.
*DSKSVR: Exclude the category for the disk server events.
*FAULT: Exclude the category for the page fault events.
*JOB: Exclude the category for the job or process management events.
*LOCK: Exclude the category for the seize lock events.
*SAR: Exclude the category for the segment address register events.
*MIBRKT: Exclude the category for the machine interface program bracketing events.
*LICBRKT: Exclude the category for the Licensed Internal Code bracketing events.
*DASD: Exclude the category for the direct access storage device events.
*DASDSRVR: Exclude the category for the DASD server events.
*PAGEFLT: Exclude the category for the page fault events.
*RMPR: Exclude the category for the resource management process management events.
*RMSZ: Exclude the category for the resource management seize lock events.

Select trace type (TRCTYPE)

Specifies which trace events to include in the output. The options possible are the same options found on the Add Performance Explorer Definition (ADDPEXDFN) command.

The possible single value is:

*ALL: Include all trace events in the output.

The possible trace type values are:

*CALLRTN: Specifies that call return events are included in the output. Call return events occur when a program is entered and exited as well as when certain machine instructions are started and completed.
*BASIC: Specifies that events relative to general performance analysis are included in the output.
*DSKIO1: Specifies that events associated with disk input/output operations are included in the output.
*DSKIO2: Specifies that events associated with the disk input/output operations plus higher level requests to do input/output operations are included in the output.
*DSKSVR: Specifies that events associated with disk server operations are included in the output.
*DSKSTG: Specifies that events associated with disk storage consumption are included in the output.
*VRTADR: Specifies that events associated with virtual address assignment are included in the output.
*PGMACT: Specifies that events associated with program activations and deactivations are included in the output.
*FILEOPEN: Specifies that events associated with file opens are included in the output.
*PFRDTA: Specifies that events associated with CPU instruction profiling are included in the output.
Note: The *PFRDTA value provides you with a detailed list of files. To receive a list in a summary format, as an alternative, you can specify PRTPEXRPT TYPE(*PROFILE).
*TASKSWT: Specifies that events associated with tasking are included in the output.

Time period for report (PERIOD)

Specifies the period of time on which to report. The parameter consists of two lists of two elements each. Data collected prior to the starting time on the starting date and after the ending time on the ending date is not included in the report.

The possible starting time values are:

*AVAIL

The recorded data that is available for the specified starting date is shown.

start-time

Specify the starting time on the specified starting date that indicates the recorded data to be shown. The time is specified in 24-hour format with or without a time separator:

Without a time separator, specify a string of 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds.
With a time separator, specify a string of 5 or 8 digits where the time separator specified for your job is used to separate the hours, minutes, and seconds. If you enter this command from the command line, the string must be enclosed in apostrophes. If a time separator other than the separator specified for your job is used, this command will fail.

All time and date entries must be 2-digits in length, meaning zeros must be included.

The possible starting date values are:

*CURRENT: The recorded data for the current day and between the specified starting and ending times (if specified) is shown.
*BEGIN: The recorded data from the beginning of the log is shown.
start-date: Specify the date printed. The date must be entered in the format specified by the system value QDATFMT, and if separators are used, as specified by the system value QDATSEP.

The possible ending time values are:

*AVAIL: The recorded data that is available for the specified ending date is shown.
end-time: Specify the ending time for the specified ending date that determines the recorded date that is printed.

The possible ending date values are:

*CURRENT: The current day is the last day for which recorded data is shown.
*END: The last day on which data was logged is shown. If PERIOD(*END) is specified, a time value other than *AVAIL for end time is ignored.
end-date: Specify the ending date for which recorded data is to be printed. The date must be entered in the format specified by the system value QDATFMT, and if separators are used, as specified by the system value QDATSEP.

Select jobs (SLTJOB)

Specifies which jobs to include from the report. This allows the user to narrow the scope of the performance explorer report by selecting specific jobs.

The SLTJOB and OMTJOB parameters are mutually exclusive.

*ALL:: All jobs in the performance explorer database are included.

The possible Job Identifier values are:

job-name:: Specify the name of the job to be included in the performance explorer report.
generic*-job-name:: Specify the generic name of the job to be included in the performance explorer report.

Note: A generic name is a character string that contains one or more characters followed by an asterisk(*), for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic name, the system assumes it to be the complete object name.

The possible Job User Name Qualifier values are:

*ALL:: All jobs that match the specified job name are included.
user-name:: Specify the name of the user of the job to be included.
generic*-user-name:: Specify the generic user name of the jobs to be included.

The possible Job Number Qualifier values are:

*ALL:: All jobs that match the specified job name and user name are included.
job-number:: Specify the job number to further qualify the job name and user name.

Omit jobs (OMTJOB)

Specifies which jobs are omitted from the report. This allows the user to narrow the scope of the performance explorer report by omitting specific jobs.

The SLTJOB and OMTJOB parameters are mutually exclusive. You must use the default for one of these parameters.

*NONE:: No jobs in the performance explorer database are omitted.

The possible Job Identifier values are:

job-name:: Specify the name of the job to be omitted in the performance explorer report.
generic*-job-name:: Specify the generic name of the job to be omitted in the performance explorer report.

The possible Job User Name Qualifier values are:

*ALL:: All jobs that match the specified job name will be omitted.
user-name:: Specify the name of the user of the job to be omitted.
generic*-user-name:: Specify the generic user name of the jobs to be omitted.

The possible Job Number Qualifier values are:

*ALL:: All jobs that match the specified job name and user name will be omitted.
job-number:: Specify the job number to further qualify the job name and user name.

Stats options (STATSOPT)

Specifies how to organize a statistics (*STATS) report. Records are ordered based on the value specified for the ORDER parameter.

Note: This parameter is ignored if, on the ADDPEXDFN command, you specified TYPE(*STATS) and DTAORG(*HIER). The parameter is ignored to retain the parent-child relationship that was collected for this definition.

Element 1: Sort by

Specifies how the records are arranged in the report.

*CPU: Arrange the output by amount of CPU time.
*PGMNAME: Arrange the output by program name.
*INVCNT: Arrange the output by number of times program or procedure is called.
*DBSYNCIO: Arrange the output by amount of physical database synchronous I/O.
*DBASYNCIO: Arrange the output by amount of physical database asynchronous I/O.
*NDBSYNCIO: Arrange the output by amount of physical non-database synchronous I/O.
*NDBASYNCIO: Arrange the output by amount of physical non-database asynchronous I/O.
*MICALLS: Arrange the output by number of MI calls.
*MIINST: Arrange the output by MI instruction name.
*CUMLCPU: Arrange the output by cumulative CPU value.
*CUMLDBSYNCIO: Arrange the output by cumulative amount of physical database synchronous I/O.
*CUMLDNASYNCIO: Arrange the output by cumulative amount of physical database asynchronous I/O.
*CUMLNDBSYNCIO: Arrange the output by cumulative amount of physical non-database synchronous I/O.
*CUMLNDBASYNCIO: Arrange the output by cumulative amount of physical non-database asynchronous I/O.

Element 2: Summarize by

*PROGRAM: The data is summarized at the program level.
*BLANK: The data is not summarized.
*MODULE: The data is summarized at the module level.

Profile options (PROFILEOPT)

Specifies how to organize a profile (*PROFILE) report. Records are ordered based on the value specified for the ORDER parameter.

Element 1: Sort by

Specifies how the records are arranged in the report

*SAMPLECOUNT: Arrange the output relative to the sample count.
*ADDRESS: Arrange the output relative to the sampled address.

Element 2: Summarize By

*PROGRAM: Summarize the data at the program level.
*STATEMENT: Summarize the data at the statement level.
*PROCEDURE: Summarize the data at the procedure level.
*MODULE: Summarize the data at the module level.
*BLANK: No summary records are provided.

Element 3: Filter percentage

This provides a filter to eliminate the insignificant records. For example, an entry of 10 would omit all the records that contain less than 10% of the samples taken during the collection.

0: No records are omitted from the report.
filter-percentage: Specify a number in the range of 0 to 100.

Order (ORDER)

Specifies how the data should be ordered in the report.

*DESCENDING: The data records are ordered in descending order. If records are sorted by a numeric field, records are ordered from largest to smallest. If records are sorted by a name field, records are in reverse alphabetical order, for example, from Z to A.
*ASCENDING: The data records are in ascending order. If records are sorted by a numeric field, records will be ordered from smallest to largest. If records are sorted by a name field, records are in alphabetical order, for example, from A to Z).

Number of threads (NBRTHD)

Specifies the number of concurrent threads that the PRTPEXRPT command uses to print the data. Specifying a number greater than 1 allows the PRTPEXRPT command to take advantage of available CPU cycles, especially on a multi-processor system. While this may speed up the command processing, it may also degrade the performance of other jobs on the system. You can minimize this impact by changing the priority of the job that runs the PRTPEXRPT command to a higher number. You should also verify that the disk subsystem can handle the additional threads. Typically, the PRTPEXRPT command requires one disk arm for each active thread.

Note: If you specify OUTPUT (*PRINT), the number of spooled files is equal to NBRTHD (one spooled file per thread).

*CALC:: The system calculates a reasonable number of threads to do the command processing which does not use excessive system resources. Usually this is one or two threads for each available processor. If this command is run in an interactive job, *CALC uses only one thread.
number-of-threads:: Specify the number of threads for the PRTPEXRPT command to use to process the collected data.

Examples

Example 1: Printing a Statistics Report

PRTPEXRPT   MBR(SAMPLE)  LIBRARY(SAMPLELIB)
            TYPE(*STATS)  STATSOPT(*INVCNT *MODULE)

This command prints a report based on data members named SAMPLE in library SAMPLELIB. The data is arranged in descending order based on invocation counts and is summarized at the module level.

Example 2: Printing a Profile Report

PRTPEXRPT   MBR(SAMPLE2)  TYPE(*PROFILE)
            PROFILEOPT(*SAMPLECOUNT *PROGRAM)
            ORDER(*DESCENDING)

This command prints a report based on data members named SAMPLE2 in the default library, QPEXDATA. The data is arranged in descending order based on the sample count and is summarized at the program level.