DSPPFRGPH (Display Performance Graph) Command Description

Note: To use this command, have the 5722-PT1 (Performance Tools for iSeries) licensed program installed.

DSPPFRGPH Command syntax diagram

Purpose

The Display Performance Graph (DSPPFRGPH) command produces a graph from the performance data collected by Collection Services.

The graph format must have been defined on the Create Graph Format (CRTGPHFMT) command. The graph can be sent as output to a graphics terminal, a non-graphics terminal, a printer, a plotter, or to a graphics data format (GDF) file that can be used by other systems. Jobs can be selectively included or omitted from the graph.

Required Parameters

GRAPH

Specifies the graph format or graph package used to create the graph.

The possible library values are:

• QPFRDATA: The graph format or graph package is located in the IBM-supplied performance data library, QPFRDATA.
• *CURLIB: The current library is used to locate the graph format or graph package. If no library is specified as the current library for the job, the QGPL library is used.
• library-name: Specify the name of the library where the graph format or graph package is located.

format-name: Specify the name of the graph format. If this value is specified, a package name cannot be specified.

package-name: Specify the name of the graph package. If this value is specified, format name cannot be specified.

MBR

Specifies the name of the file member for which performance data will be shown in the graph.

Optional Parameters

LIB

Specifies the name of the library where the object is saved.

QPFRDATA: The performance data is located in the IBM-supplied performance data library, QPFRDATA.

library-name: Specify the name of the library where the performance data is located.

TITLE

Specifies a title to display at the top of the graph or of each graph of a package.

*SAME: The text of the graph title is the title defined in the graph format.

*BLANK: A blank title is used.

*MBRTEXT: The text of the selected member is used.

'graph-title': Specify no more than 50 characters of text, enclosed in apostrophes.

SUBTITLE

Specifies a subtitle to display at the top of the graph or of each graph of a package.

*SAME: The text of the graph subtitle is the subtitle defined in the graph format.

*BLANK: A blank subtitle is used.

*MBRTEXT: The text of the selected member is used.

'graph-subtitle': Specify no more than 50 characters of text, enclosed in apostrophes.

OUTPUT

Specifies whether the chart is to be displayed, plotted, printed, or saved in a graphics data format (GDF) file.

*: The graph is shown on the output display. This special value is valid only if JOBD(*NONE) is specified. Your display station can be either a graphics or nongraphics display station. A graphics display station shows the graph with colors, shading, and so forth. A nongraphics display station shows the graph using characters you choose to represent colors, shading, and so forth. Once your graph is shown, you can define one overlay. An overlay is a graph that is placed on top of the current graph.

*PRINT: The graph is sent to the QPPGGPH printer file while the spooled file has the same name as the graph format. The appearance of graphs printed or displayed by graphical devices can be different from how they appear when printed or displayed by nongraphical devices, especially when *AUTO is specified by the Y (vertical) axis.

*PLOT: The graph is plotted on an attached plotter. This value is valid only if JOBD(*NONE) is specified. The 6180, 6182, 7371, and 7372 plotters are supported.

*OUTFILE: The graph is saved to the Graphics Data Format (GDF) file specified on the OUTFILE parameter. This option is not valid if a package is being displayed. Use this file to display the graph on any system that supports the graphical data display manager function or the Business Graphics Utility licensed program. Graph packages cannot be sent to a GDF file.

PRTDEV

Specifies the name or type of printer on which the graph is printed. If a printer name (for example, PRT01) is specified, the output is spooled to the output queue of the printer. If a printer type (for example, 4214) is specified, the output is spooled to the output queue specified on the OUTQ parameter. This parameter is valid only if OUTPUT(*PRINT) is specified.

4214: The 4214 printer is used.

4234: The 4234 printer is used.

522X: One of the 522X series printer is used. They are the 5224 and 5225 printers.

*IPDS: One of the Intelligent Printer Data Stream (IPDS) printers is used. The choices are the 3812 and 4224 printers.

*NONGRAPHIC: The output is spooled to the output queue in a nongraphics format for use with printers that do not support graphics.

printer-name: Specify the system name of the printer to which the output is sent.

OUTQ

Specifies the name and library of the output queue to which the printer file is to be sent.

*PRTDEV: The output queue associated with the printer is used. If a printer type has been specified, the output is sent to the job's output queue.

The name of the output queue can be qualified by one of the following library values:

• *LIBL: All libraries in the job's library list are searched until the first match is found.
• library-name: Specify the name of the library to be searched.

output-queue-name: Specify the name of the output queue.

PAGELEN

Specifies the page length for graphs. This parameter is valid only if OUTPUT(*PRINT) is specified.

*PRTDEV: The page length for the printer or printer type specified on the PRTDEV parameter is used.

51: Specifies 51 lines per page (8.5 inches).

66: Specifies 66 lines per page (11 inches).

PLTSPD

Specifies the speed at which the plotter creates the graph. A larger value represents a faster plotting rate. The smaller the value the better the plotting quality of the graph. This parameter is valid only when *PLOT is specified on the OUTPUT parameter.

100: A plotter speed of 100 is used.

plotter-speed: Specify the speed of the plotter. The plotter speed ranges from 1 through 100.

PLTPEN

Specifies the pen width in which to shade the performance graph. The smaller the value, the closer together the lines are for shading. If the user chooses a small value, the graph takes longer to plot. If the value is too large, the shading will have gaps in it. This parameter is valid only when *PLOT is specified on the OUTPUT parameter.

3: A pen width of 0.3 millimeters is used.

pen-width: Specify the width of the pen. Pen widths (values 1 through 10) range from 0.1 millimeter through 1.0 millimeter.

PLTADR

Specifies the address of the plotter attached to the terminal on which the graph is created. This parameter is valid only when the *PLOT is specified on the OUTPUT parameter.

1: The plotter with the address of 1 is used.

plotter-address: Specify the address of the plotter. Address values range from 1 through 31.

OUTFILE

Specifies the file in which the graph data format is saved. This parameter is valid only when *OUTFILE is specified on the OUTPUT parameter.

The possible library values are:

• QPFRDATA: The graph is saved in the IBM-supplied performance data library, QPFRDATA.
• *LIBL: The library list is used to locate the file in which to save the graph.
• *CURLIB: The current library is used to locate the file in which to save the graph. If no library is specified as the current library for the job, the QGPL library is used.
• library-name: Specify the name of the library where the graph is saved.

file-name: Specify the name of the file into which the graph is saved.

OUTMBR

Specifies the format member in which the graph is to be saved. This parameter is valid only if OUTPUT(*OUTFILE) is specified.

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.

member-name: Specify the name of the file member that receives the output. If the OUTMBR(member-name) is specified and the member does not exist, the system creates it. If the member already exists, the user has the option to either add new records to the end of the existing member or to clear the member and then add the new records.

Element 2: Operation to Perform on Member

*REPLACE: If a member exists, the system clears it and adds the new records.

*ADD: If a member exists, the system adds the new records to the end of the existing records.

TYPE

Specifies whether the graph is a graph format or graph package.

*GPHFMT: The graph is a graph format.

*GPHPKG: The graph is a graph package.

XAXIS

Specifies the range used on the X-axis.

*SAME: The range is the same as that defined in the graph format.

*AUTO: The system determines the range based on the data. This value must be specified if *TIME is specified for the X-axis variable.

Element 1: Starting Number of Range

starting-number: Specify the start of the X-axis range. This value is valid only if an ending number is also specified.

Element 2: Ending Number of Range

ending-number: Specify the end of the X-axis range. This value is valid only if a starting number is also specified.

YAXIS

Specifies the range used on the Y-axis.

*SAME: The range is the same as that defined in the graph format.

*AUTO: The system determines the range based on the data.

Element 1: Starting Number of Range

starting-number: Specify the start of the Y-axis range. This value is valid only if an ending number is also specified.

Element 2: Ending Number of Range

ending-number: Specify the end of the Y-axis range. This value is valid only if a starting number is also specified.

AREAFILL

Specifies whether the graph is displayed with surfaces and bars filled in with a shading pattern.

This parameter allows the user to display detailed graphs quickly. If the user specifies AREAFILL(*NO) on this command after previously specifying AREAFILL(*YES) on the CRTGPHFMT command, the graph is displayed more quickly. This is caused by the greater amount of time it takes to fill in areas with shading patterns than to merely draw lines. Also, the more dense the shading pattern, the more time it takes to create. These issues are important if time is short and graphic quality is not momentarily important.

*SAME: The graph is shaded according to the graph format definition.

*YES: The graph is filled in with a shading pattern.

*NO: The graph is not filled in with a shading pattern.

PERIOD

Specifies the period of time for which to collect performance information for the performance graph. The starting and ending times and dates consist of four elements:

PERIOD((start-time start-date)
  (end-time end-date))

*N can be used in place of an element that precedes the value being specified in order to maintain positioning. For example, PERIOD(*N(*N 091289)) specifies the ending date and the default values for start-time, start-date, and end-time.

Element 1: Starting Time

One of the following pair of values is used to specify the starting time. Information collected before the starting time and starting date is not included on the graph.

*FIRST: Records starting at the beginning of the start day (00:00:00) are included on the graph.

start-time: Specify the time of the start day after which records are included. The time is specified in 24-hour format with or without a time separator as follows:

• With a time separator, specify a string of 5 or 8 digits, where the time separator for the job separates the hours, minutes, and seconds. If you issue this command from the command line, the string must be enclosed in apoltrophes. If a time separator other than the separator specified for your job is used, this command fails.
• Without a time separator, specify a string of 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds. Valid values for hh range from 00 through 23. Valid values for mm and ss range from 00 through 59.

Element 2: Starting Date

One of the following pair of values is used to specify the starting date. Information collected before the starting time on the date specified on this parameter is not included on the graph.

*FIRST: Records starting on the first day of the collection period are included on the graph.

start-date: Specify the date on which information collection begins. The date must be entered in the format specified by the system values QDATFMT and, if separators are used, QDATSEP. For instance, the system might have a date format of 'mm/dd/yy'. The month (mm), day (dd), and year (yy) are all required 1-digit or 2-digit values. The slashes (/) are optional if all six digits are specified. If the slashes are omitted, or if the value is entered from the prompt display, the enclosing apostrophes are not required.

Element 3: Ending Time

One of the following pair of values is used to specify the ending time. Information collected after the ending time and ending date is not included on the graph.

*LAST: Records through the end of the end day (23:59:59) are included on the graph.

end-time: Specify the time after which records are no longer collected. See the Element 1 in this parameter for details on how the time must be specified.

Element 4: Ending Date

One of the following values is used to specify the ending date. Information collected after the ending time and ending date is not included on the graph.

*LAST: Records through the last day of the collection period are included on the graph.

end-date: Specify the date after which records are no longer collected. See Element 2 in this parameter for details on how the date must be specified.

SLTJOB

Specifies a list of up to 50 jobs to select. Only performance data for the specified jobs are included on the graph.

The SLTJOB and OMTJOB parameters are mutually exclusive.

A job identifier is either the special value *ALL or a qualified name with up to three elements, for example:

*ALL
job-name
user-name/job-name
job-number/user-name/job-name

*ALL: All jobs in the collected data are included, unless excluded by some other selection criteria.

job-name: Specify the name of jobs to select. Because jobs may have identical job names, this value may not identify a specific job. This can be either a specific name or a generic name.

user-name: Specify the user name of jobs to select. Because jobs may have identical user names, this value may not identify a specific job. This can be either a specific name or a generic name.

job-number: Specify the 6-digit number of a job to select. All six digits must be specified (use leading zeros if necessary).

OMTJOB

Specifies a list of up to 50 jobs whose performance data is omitted from the graph.

The SLTJOB and OMTJOB parameters are mutually exclusive.

Similar to the SLTJOB parameter, a job identifier is either the special value *NONE or a qualified name with up to three elements. *N can be used in place of an element to maintain the position in the parameter value sequence.

*NONE: No job is excluded based on job identifier.

job-name: Specify the name of jobs to omit. Because jobs may have identical job names, this value may not identify a specific job. This can be either a specific name or a generic name.

user-name: Specify the user name of jobs to omit. Because jobs may have identical user names, this value may not identify a specific job. This can be either a specific name or a generic name.

job-number: Specify the 6-digit number of a job to omit. All six digits must be specified (use leading zeros if necessary).

SLTUSER

Specifies a list of up to 50 user names to select. Only jobs with one of the specified user names are included on the graph.

The SLTUSER and OMTUSER parameters are mutually exclusive.

*ALL: Jobs with all user names are included, unless excluded by other selection criteria.

user-name: Specify the user name of jobs to select. Because jobs may have identical user names, this value may not identify a specific job.) This can be either a specific or generic name. SLTUSER(user) is equivalent to SLTJOB(*N/user/*N).

OMTUSER

Specifies a list of up to 50 user names to omit. Jobs having the specified user names are excluded from the graph.

The SLTUSER and OMTUSER parameters are mutually exclusive.

*NONE: No job is excluded based on user name.

user-name: Specify the user name of jobs to omit. Because jobs may have identical user names, this value may not identify a specific job. This can be either a specific or generic name. OMTUSER(user) is equivalent to OMTJOB(*N/user/*N).

SLTPOOLS

Specifies a list of up to 64 pools to select. Only jobs that run in one of the specified pools are included in the report.

*ALL: Jobs running in all pools are included, unless excluded by other selection criteria.

storage-pool-identifier: Specify the number of a pool to select. Valid values range from 1 through 64.

OMTPOOLS

Specifies a list of up to 64 pools to omit. Jobs running in the specified pools are excluded from the graph.

The SLTPOOLS and OMTPOOLS parameters are mutually exclusive.

*NONE: No jobs are excluded based on their pool.

storage-pool-identifier: Specify the number of a pool to omit. Valid values range from 1 through 64.

SLTSBS

Specifies a list of up to 50 subsystems to select. Only jobs running in one of the specified subsystems are included on the graph.

The SLTSBS and OMTSBS parameters are mutually exclusive.

*ALL: Jobs in all subsystems are included, unless excluded by other selection criteria.

subsystem-name: Specify the name of a subsystem to select.

OMTSBS

Specifies a list of up to 50 subsystems to omit. Jobs running in the specified subsystems are excluded from the graph.

The SLTSBS and OMTSBS parameters are mutually exclusive.

*NONE: No jobs are excluded based on subsystem.

subsystem-name: Specify the name of a subsystem to omit.

SLTLINE

Specifies a list of up to 50 communications lines to select. Only jobs using a remote device connected through one of the specified communications lines are included on the graph.

The SLTLINE and OMTLINE parameters are mutually exclusive.

*ALL: All jobs are included, unless excluded by other selection criteria.

communications-line-name: Specify the names of communications lines to select. This excludes jobs using remote devices connected through other communications lines (or no communications line), even if the controllers to which those devices are attached are specified on the SLTCTL parameter.

OMTLINE

Specifies a list of up to 50 communications lines to omit. Jobs using a remote device connected through any of the specified lines are excluded from the graph.

The SLTLINE and OMTLINE parameters are mutually exclusive.

*NONE: Jobs are not excluded based on communications lines they use.

communications-line-name: Specify the name of a communications line to omit.

SLTCTL

Specifies a list of up to 50 communications controllers to select. Only jobs using a device connected to one of the specified communications controllers are included on the graph.

The SLTCTL and OMTCTL parameters are mutually exclusive.

*ALL: All jobs are included, unless excluded by other selection criteria.

controller-name: Specify the name of a communications controller to select.

OMTCTL

Specifies a list of up to 50 communications controllers to omit. Jobs using a device connected to any of the specified communications controllers are excluded from the graph.

The SLTCTL and OMTCTL parameters are mutually exclusive.

*NONE: Jobs are not excluded based on communications controller.

controller-name: Specify the name of a communications controller to omit.

SLTFCNARA

Specifies a list of functional areas to select. Only jobs and users identified in one of the functional areas are included in the report.

A functional area is a list of job names and user names previously defined by the user. You can find information on defining functional areas in the Performance Tools for iSeries book.

*ALL: All jobs are included, unless excluded by other selection criteria.

functional-area-name: Specify the name of a functional area to select.

OMTFCNARA

Specifies a list of functional areas to omit. Jobs and users identified in any of the functional areas are excluded from the report.

A functional area is a list of job names and user names previously defined by the user. You can find information on defining functional areas in the Performance Tools for iSeries book.

*NONE: No jobs are excluded based on functional area.

functional-area-name: Specify the name of a functional area to omit.

JOB

Specifies the job name used if the job is submitted for batch processing.

Note: If *NONE is specified on the JOBD parameter, this parameter is ignored; job processing is performed interactively.

DSPPFRGPH: The command name is used for the job name.

*MBR: The name selected for the performance data member on the MBR parameter is used.

job-name: Specify the name used for batch jobs.

JOBD

Specifies the job description used to submit jbos for batch processing.

*NONE: A batch job is not submitted; instead, processing continues interactively while the user waits. The user's work station is not available for other use during this time, which could be significant for long jobs. This must be the job description if the output is to a screen or to a plotter. It is recommended that the user submit the job to batch if it is for printing or saving to a GDF file.

The name of the job description can be qualified by one of the following library values:

• *LIBL: All libraries in the job's library list are searched until the first match is found.
• *CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
• library-name: Specify the name of the library to be searched.

QPFRJOBD: The IBM-supplied Performance Tools job description is used.

job-description-name: Specify the name of the job description.

Examples for DSPPFRGPH

Example 1: Displaying Performance Data Files

DSPPFRGPH  GRAPH(GRAPHLIB/CPU)
  MBR(QPFRDATA/JUN1)  TITLE(*MBRTEXT)

This command displays the performance data files in library QPFRDATA member JUN1. It is displayed as specified by graph format CPU in library GRAPHLIB. The report title is taken from the text of the member.

Example 2: Saving a Graph

DSPPFRGPH  GRAPH(GRAPHLIB/CPU)
  MBR(JUN1)  OUTPUT(*OUTFILE)
  OUTFILE(USERLIB/USERFILE)  OUTMBR(TEST)
  JOBD(*LIBL/QPFRJOBD)

This command submits a job to save the graph of performance data from file member JUN1, which is in library QPFRDATA, in a GDF file. The graph is saved in file USERLIB/USERFILE/TEST (file member TEST in file USRFILE, which is in library USRLIB).

Example 3: Printing a Graph

DSPPFRGPH  GRAPH(GRAPHLIB/CPU)
  MBR(JUN1)  OUTPUT(*PRINT)
  PRTDEV(PRT03)  JOBD(*LIBL/QPFRJOBD)

This command submits a job to print the graph of performance data from file member JUN1, which is in library QPFRDATA, on the system printer named PRT03.

Example 4: Printing All Graphs

DSPPFRGPH  GRAPH(GRAPHLIB/PACKAGE1)
  MBR(JUN1)  OUTPUT(*PRINT)
  PRTDEV(PRT03)  JOBD(*LIBL/QPFRJOBD)
  TYPE(*GPHPKG)

This command submits a job to print all of the graphs defined in PACKAGE1 in GRAPHLIB. The print job is sent to system printer PRT03. It's data source is in performance data member JUN1 in library QPFRDATA.

Example 5: Displaying a Graph

DSPPFRGPH  GRAPH(GRAPHLIB/CPU)
  MBR(JUN1)  OUTPUT(*)
  PERIOD((2330)(0130))

This command displays a graph of the data collected from 11:30 PM on the first day of collection through 1:30 AM on the last day of collection. However, if data collection started and ended on the same day, an error message is printed, because the specified ending date and time precedes the specified starting date and time.

Example 6: Displaying a Graph

DSPPFRGPH  GRAPH(GRAPHLIB/CPU)
  MBR(JUN1)  OUTPUT(*)
  PERIOD((2330)(0130)) SLTUSER(D46*)

This command displays a graph of the performance data collected for all the jobs whose user ID starts with D46 from 11:30 PM on the first day of collection through 1:30 AM on the last day of collection. However, if data collection started and ended on the same day, an error message is printed, because the specified ending date and time precedes the specified starting date and time.

Error messages for DSPPFRGPH

*ESCAPE Messages

PFR5501

Performance data file(s) are not upward compatible.

PFR5502

Cannot process request because of missing data.

PFR9031

Cannot use member &3 in performance graph.

PFR9046

Jobs defined in more than one functional area.

PFR9049

Graph format &1 in library &3 does not exist.

PFR9068

Value for OUTFILE parameter must be specified.

PFR9069

*NONE value must be specified for JOBD parameter.

PFR9071

X-axis variable for both graphs must be the same.

PFR9075

Plotter not found.

PFR9076

Plotter type not supported.

PFR9077

Graph format has too many legend entries for overlay.

PFR9078

Cannot display graph because of missing data.

PFR9079

Cannot write graph to output file.

PFR9080

Specify *AUTO for range with *TIME for X-axis.

PFR9082

Printer &1 not found.

PFR9083

Graph format selected for historical graph not valid.

PFR9096

Historical Data File QAPGHSTD not found in Library &1.

PFR9097

Cannot copy graph format &1 onto itself.

PFR9098

Cannot copy graph package &1 onto itself.

PFR9099

Cannot copy functional area &1 onto itself.

PFR9101

Graph has too many data points to display.

PFR9107

Graph format &1 is not valid.

PFR9113

Cannot display graph because of missing data.