Print PEX Report (PRTPEXRPT)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Print PEX 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.

Restrictions:

This command is shipped with PUBLIC *EXCLUDE authority.
You must have read (*READ) and execute (*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 the operating system. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_TRACE, can be used to change the list of users that are allowed to perform trace operations.

Top

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
OUTFILE	File to receive output	Qualified object name	Optional
	Qualifier 1: File to receive output	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
OUTMBR	Output member options	Element list	Optional
	Element 1: Member to receive output	Name, *FIRST
	Element 2: Replace or add records	REPLACE, ADD
TRACEOPT	Trace options	Element list	Optional
	Element 1: Sort by	TIMESTAMP, TASK
	Element 2: Omit completion records	NO, YES
	Element 3: Omit Category	Single values: NONE Other values (up to 17 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
PERIOD	Time period for report	Element list	Optional
	Element 1: Start time and date	Element list
	Element 1: Starting time	Time, *AVAIL
	Element 2: Starting date	Date, BEGIN, CURRENT
	Element 2: End time and date	Element list
	Element 1: Ending time	Time, *AVAIL
	Element 2: Ending date	Date, END, CURRENT
SLTJOB	Select jobs	Single values: *ALL Other values (up to 10 repetitions): Qualified job name	Optional
	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
	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
	Element 1: Sort by	Integer, CPU, PGMNAME, INVCNT, DBSYNCIO, DBASYNCIO, NDBSYNCIO, NDBASYNCIO, MICALLS, MIINST, CUMLCPU, CUMLDBSYNCIO, CUMLDBASYNCIO, CUMLNDBSYNCIO, CUMLNDBASYNCIO
	Element 2: Summarize by	PROGRAM, MODULE, *BLANK
PROFILEOPT	Profile options	Element list	Optional
	Element 1: Sort by	SAMPLECOUNT, ADDRESS
	Element 2: Summarize by	PROGRAM, MODULE, PROCEDURE, STATEMENT, *BLANK
	Element 3: Filter percentage	0-99, 0
ORDER	Order	DESCENDING, ASCENDING	Optional
NBRTHD	Number of threads	1-64, 1, *CALC	Optional
TASKINF	Task information	ALL, NONE	Optional

Top

Member (MBR)

Specifies where the data is located for the report. This is the value that was specified for the SSNID or DTAMBR parameter when the data was saved using the End Performance Explorer (ENDPEX) command. Each database file used by performance explorer when it saved the collected performance data should have a member with the name specified.

This is a required parameter.

name: Specify the member name.

Top

Library (LIB)

Specifies the library where the data will be found.

QPEXDATA: The collected data exists in database files in library QPEXDATA.
name: Specify the library name which contains the database files that hold the collected performance data.

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 PEX 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.

Top

Output (OUTPUT)

Specifies whether the output from the command is printed with the job's spooled output or directed to a database file.

Note: This parameter is valid only if TYPE(*TRACE) is specified.

*PRINT: The output is printed with the job's spooled output.
*OUTFILE: The output is directed to the database file specified in the File to receive output (OUTFILE) parameter.

Top

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 QSYS.

Qualifier 1: File to receive output

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

Qualifier 2: Library

*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.
name: Specify the name of the library where the output file is located.

Top

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 File to receive output (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.
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: Replace or add records

*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.

Top

Trace options (TRACEOPT)

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

Element 1: Sort by

*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

*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

Single values

*NONE: No categories are omitted.

Other values (up to 17 repetitions)

*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 disk server events.
*PAGEFLT: Exclude the category for the page fault events.
*RMPR: Exclude the category for the resource management process management events.
*RMSL: Exclude the category for the resource management seize lock events.

Top

Select trace type (TRCTYPE)

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

Single values

*ALL: Include all trace events in the output.

Other values (up to 11 repetitions)

*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.
*PRFDTA: 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.

Top

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.

Element 1: Start time and date

Element 1: Starting time

*AVAIL

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

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.

Element 2: Starting date

*BEGIN: The recorded data from the beginning of the log is shown.
*CURRENT: The recorded data for the current day and between the specified starting and ending times (if specified) is shown.
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.

Element 2: End time and date

Element 1: Ending time

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

Element 2: Ending date

*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.
*CURRENT: The current day is the last day for which recorded data is shown.
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.

Top

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.

Single values

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

Other values (up to 10 repetitions)

Qualifier 1: Select jobs

name: Specify the name of the job to be included in the performance explorer report.
generic-name: Specify the generic name of the job to be included in the performance explorer report.
Note: A generic name is a character string of one or more characters followed by an asterisk (*). A generic name specifies all items that have names with the same prefix as the generic name.

Qualifier 2: User

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

Qualifier 3: Number

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

Top

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.

Single values

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

Other values (up to 10 repetitions)

Qualifier 1: Omit jobs

name: Specify the name of the job to be omitted in the performance explorer report.
generic-name: Specify the generic name of the job to be omitted in the performance explorer report.
Note: A generic name is a character string of one or more characters followed by an asterisk (*). A generic name specifies all items that have names with the same prefix as the generic name.

Qualifier 2: User

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

Qualifier 3: Number

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

Top

Stats options (STATSOPT)

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

Note: This parameter is ignored if, on the Add PEX Definition (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

*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.
*CUMLDBASYNCIO: 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.
*MODULE: The data is summarized at the module level.
*BLANK: The data is not summarized.

Top

Profile options (PROFILEOPT)

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

Element 1: Sort by

*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.
*MODULE: Summarize the data at the module level.
*PROCEDURE: Summarize the data at the procedure level.
*STATEMENT: Summarize the data at the statement level.
*BLANK: No summary records are provided.

Element 3: Filter percentage

0: No records are omitted from the report.
0-99: Specify a number in the range of 0 to 100.
Note: 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.

Top

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).

Top

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).

1: Only one thread for the PRTPEXRPT command is used to process the collected data.
*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.
1-64: Specify the number of threads for the PRTPEXRPT command to use to process the collected data.

Top

Task information (TASKINF)

Specifies whether the task information section is to be printed or not.

*ALL: The task information section will be printed and will include details for all jobs and tasks available in the collected data. If ADDPEXDFN LSTALLJOB(*YES) was specified in the definition used to collect this data, then details for all jobs and tasks on the system during the time of the collection will be printed.
*NONE: The task information section will not be printed.

Top

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.

Top

Error messages

*ESCAPE Messages

CPFAF0A: Collection &1 was not found
CPFAF09: Library &1 not found.
CPF4102: File &2 in library &3 with member &4 not found.
CPFAF14: The data in the member specified does not match the type of report requested.

Top