The Display Historical Graph (DSPHSTGPH) command produces a graph from the historical data created by the Create Historical Data (CRTHSTDTA) command. The DSPHSTGPH command is intended to give you a historical perspective of your system in a graphic representation.

The CRTHSTDTA command summarizes the performance data collected by Collection Services. The graph format must have been defined by the Create Graph Format (CRTGPHFMT) command. The graph can be directed to a graphics terminal, non-graphics terminal, printer, plotter, and a graphics data format (GDF) file that can be used by other systems. Historical data members can be selectively included in the graph.

It is important that the Create Historical Data (CRTHSTDTA) command has been run for each of the members that you want to include in the graph. If CRTHSTDTA has not been run for a member, it is not included in the graph unless you specify *YES on the Create historical data prompt (CRTHSTDTA parameter) of this command.

Parameters

Keyword	Description	Choices	Notes
GRAPH	Graph format or package	Qualified object name	Required, Positional 1
	Qualifier 1: Graph format or package	Name
	Qualifier 2: Library	Name, QPFRDATA, *CURLIB
LIB	Library	Name, QPFRDATA	Optional, Positional 2
TITLE	Title	Character value, *SAME, *MBRTEXT, *BLANK	Optional
SUBTITLE	Subtitle	Character value, *SAME, *MBRTEXT, *BLANK	Optional
OUTPUT	Output	*, *PRINT, *PLOT, *OUTFILE	Optional
OUTFILE	Output file	Qualified object name	Optional
	Qualifier 1: Output file	Name
	Qualifier 2: Output file library	Name, *LIBL, *CURLIB
OUTMBR	Output file member	Element list	Optional
	Element 1: Member name	Name, *FIRST
	Element 2: Replace or add records	*REPLACE, *ADD
PLTSPD	Plotter speed	1-100, 100	Optional
PLTPEN	Plotter pen width	1-10, 3	Optional
PLTADR	Plotter address	1-31, 1	Optional
PRTDEV	Printer device or type	Name, 4214, 4234, 522X, *IPDS, *NONGRAPHIC	Optional
OUTQ	Output queue	Single values: *PRTDEV Other values: Qualified object name	Optional
	Qualifier 1: Output queue	Name
	Qualifier 2: Library	Name, *LIBL
PAGELEN	Page length	*PRTDEV, 51, 66	Optional
TYPE	Type	*GPHFMT, *GPHPKG	Optional
PERIOD	Time period for report	Element list	Optional
	Element 1: Starting date	Date, *FIRST, *SELECT
	Element 2: Ending date	Date, *LAST
CRTHSTDTA	Create historical data	*NO, *YES	Optional
XAXIS	X-axis	Element list	Optional
	Element 1: Range	Single values: *SAME, *AUTO Other values: Element list
	Element 1: First	0-99999
	Element 2: Last	0-99999
YAXIS	Y-axis	Element list	Optional
	Element 1: Range	Single values: *SAME, *AUTO Other values: Element list
	Element 1: First	0-99999
	Element 2: Last	0-99999
AREAFILL	Area fill	*SAME, *YES, *NO	Optional
JOB	Job name	Name, DSPHSTGPH	Optional
JOBD	Job description	Single values: *NONE Other values: Qualified object name	Optional
	Qualifier 1: Job description	Name, QPFRJOBD
	Qualifier 2: Library	Name, *LIBL, *CURLIB

Top

Graph format or package (GRAPH)

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

This is a required parameter.

The possible library values are:

QPFRDATA

The IBM-supplied performance data library, QPFRDATA, is where the graph format or graph package is located.

*CURLIB

The current library for the job is used to locate the graph format or graph package. If no library is specified as the current library for the job, QGPL is used.

library-name

Specify the name of the library where the graph format or graph package is located.

Since the following are not elements, they are mutually exclusive. Therefore, specify the name of the graph format or specify the name of the graph package. You cannot specify them at the same time.

format-name

Specify the name of the graph format.

package-name

Specify the name of the graph package.

Library (LIB)

Specifies the library in which the historical data created by the Create Historical Data (CRTHSTDTA) command is located.

The possible library values are:

QPFRDATA

The IBM-supplied performance data library, QPFRDATA, is where the historical data is located.

library-name

Specify the library where the historical data is located.

Title (TITLE)

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

*SAME

The title defined in the graph format is used.

*BLANK

A blank title is used.

*MBRTEXT

The text of the selected member that was last created by the performance monitor is used.

graph-title

Specify a title of up to 50 characters enclosed in apostrophes.

Subtitle (SUBTITLE)

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

*SAME

The subtitle defined in the graph format is used.

*BLANK

A blank subtitle is used.

*MBRTEXT

The text of the selected member that was last created by the performance monitor is used.

subtitle

Specify a subtitle of up to 50 characters enclosed in apostrophes.

Output (OUTPUT)

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

*

The graph is to be displayed on the output screen. This special value is not valid if JOBD(*NONE) is not 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 printed to the printer file, QPPGGPH while the spooled output file is named the same as the graph format.

Note:

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 for the Y (vertical) axis.

*PLOT

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

*OUTFILE

The graph is saved to the graphics data format (GDF) file specified in the Output file prompt (OUTFILE parameter). This option is not valid if a package is being displayed.

You can use this file to display the graph on any system supporting the graphical data display manager function or the Business Graphics Utility licensed program.

Note:

Graph packages cannot be sent to a GDF file.

Output file (OUTFILE)

Specifies the library and file in which the graph data format is to be saved. This parameter is only valid when OUTPUT(*OUTFILE) is specified. The graph is saved in a graphics data format (GDF) file.

The possible library values are:

*LIBL

All libraries in the job's library list are searched until the first match is found.

*CURLIB

Search the current job library to locate the file in which to save the graph. If no current job library entry exists in the library list, QGPL is used.

library-name

Specify the name of the library where the graph is to be saved.

file-name

Specify the name of the file into which the graph is to be saved.

Output file member (OUTMBR)

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

*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 in the Output file prompt (OUTFILE parameter).

member-name

Specify the name of the member into which the graph is to be saved. 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.

The possible optional values are:

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

Plotter speed (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 OUTPUT(*PLOT) is specified.

100

A plotter speed of 100 is used.

plotter-speed

Specify the speed of the plotter. The plotter speed ranges from 1 through 100 (velocity).

Plotter pen width (PLTPEN)

Specifies the pen width in which to shade the graph. The smaller the value, the closer together the lines will be for shading. If you choose 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 OUTPUT(*PLOT) is specified.

3

A pen width of .3 millimeters is used.

pen-width

Specify the width of the pen. The pen widths range from .1 millimeter through 1 millimeter. Valid values range from 1 through 10.

Plotter address (PLTADR)

Specifies the plotter address for the terminal on which the graph is to be created.

1

Use the plotter designated by address 1.

plotter-address

Specify the address of the plotter. Valid values range from 1 through 31.

Printer device or type (PRTDEV)

Specifies the name of the printer or the type of printer on which the graph is to be printed. If a printer name is used, for example, PRT01, PRT02, and so on, the output is spooled to the output queue of the printer. If a printer type is specified, for example, 4214, the output is spooled to the output queue specified on the Output queue prompt (OUTQ parameter). This parameter is valid only when OUTPUT(*PRINT) is specified.

4214

The 4214 printer is used.

4234

The 4234 printer is used.

522X

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

*IPDS

One of the Intelligent Printer Data Stream (IPDS) printers are used. They are the 3812 and 4224 printers.

*NONGRAPHIC

The output is not spooled in a graphics format for printing on printers that do not support graphics.

printer-name

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

Output queue (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.

output-queue-name

Specify the name of the output queue.

The possible library values are:

*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 where the output queue is located.

Page length (PAGELEN)

Specifies the page length for graphs. The PAGELEN parameter is valid only when 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).

Type (TYPE)

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

*GPHFMT

The graph is a graph format.

*GPHPKG

The graph is a graph package.

Time period for report (PERIOD)

Specifies the members which are to be included in the graph which will specify the time period range of the graph. The members can be selected using the *SELECT value or by specifying a starting and ending date range.

Note: Members which have not had their historical data created are not included on the graph unless CRTHSTDTA(*YES) is specified.

*N may be used in place of an element that precedes the value being specified in order to maintain positioning. For example:

PERIOD(*N 091289)

This example specifies the ending date and uses the default starting date, which is specified by *N.

Specify one of the following values to signify the starting date. Historical information collected before this date is not included in the graph.

The possible Starting Date values are:

*FIRST

Historical information is included in the graph beginning on the date of the oldest historical information in the library.

*SELECT

Shows a list of performance members and whether or not they have historical data. From this list you can select which members are included in the graph. This value is valid only in the interactive environment. If used, the remaining values on the Time period for report prompt (PERIOD parameter) are ignored (end-date).

start-date

Specify the date after which data records are included. The date must be entered in the format specified by the system values, QDATFMT, and, if separators are used, QDATSEP. For example, the system might have a date format of 'mm/dd/yy'. The month (mm), day (dd), and year (yy) are all required (1- or 2-digit values). The slashes (/) are optional if all 6 digits are specified. If the slashes are omitted, or if the value is entered from the prompt screen, then apostrophes are not required.

Specify one of the following values to signify the ending date. Historical information collected after this date is not included in the graph.

The possible Ending Date values are:

*LAST

Historical information is included in the graph ending on the date of the latest historical information in the library.

end-date

Specify the date after which records are no longer included. This value is specified in the same format as start-date.

Create historical data (CRTHSTDTA)

Specifies whether historical data is to be created for any performance data member that has not had historical data created.

*NO

Historical data is not created. All performance members that exist during the period of time selected, and do not have historical data representing them, are not included on the graph.

*YES

Historical data is created.

Note: Creating historical data takes more time than most display jobs.

X-axis (XAXIS)

Specifies the range used on the X-axis.

*SAME

The range specified in the graph format is used.

*AUTO

The system determines a range based on the data being used.

The possible Starting Number value is:

starting-number

Specify the starting number for the range on the X-axis. This user-defined variable is not valid if you have specified *TIME for the X-axis. If you specify a starting number, you must also specify an ending number.

The possible Ending Number value is:

ending-number

Specify the ending number for the range on the X-axis. This user-defined variable is not valid if you have specified *TIME for the X-axis. If you specify an ending number, you must also specify a starting number.

Y-axis (YAXIS)

Specifies the range used on the Y-axis.

*SAME

The range specified in the graph format is used.

*AUTO

The system determines a range based on the data being used.

The possible Starting Number value is:

starting-number

Specify the starting number for the range on the Y-axis. If you specify a starting number, you must also specify an ending number.

The possible Ending Number value is:

ending-number

Specify the ending number for the range on the Y-axis. If you specify an ending number, you must also specify a starting number.

Area fill (AREAFILL)

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

This parameter allows you to display detailed graphs quickly. If you specify AREAFILL(*NO) on this command when you have specified AREAFILL(*YES) on the CRTGPHFMT command, the graph is displayed more quickly. This is caused by the fact that it takes longer to fill in areas with shading patterns than it does to draw lines. Also, the more dense the shading pattern, the more time it takes. 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 will be filled in with a shading pattern.

*NO

The graph will not be filled in with a shading pattern.

Job name (JOB)

Specifies the job name to be used if submitting a job for batch processing.

If *NONE is specified on the Job description prompt (JOBD parameter), this parameter is ignored and job processing is performed interactively.

The possible job-name values are:

DSPHSTGPH

The command name is used for the job name.

job-name

Specify the name to be used for batch jobs.

Job description (JOBD)

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

*NONE

A batch job is not submitted; instead, processing continues interactively while the user waits. The user's work station cannot be used during this time. This is something to consider for especially long jobs.

*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 used to locate the job description. If no library is specified as the current library for the job, QGPL is used.

library-name

Specify the name of the library where the job description is located.

QPFRJOBD

The IBM-supplied performance tools job description is used.

job-description-name

Specify the name of an alternate job description.

Examples

Example 1: Displaying a Data File

DSPHSTGPH   GRAPH(GRAPHLIB/CPU)

This command shows the historical data file in library QPFRDATA on the user's screen. It is shown using the graph format CPU in library GRAPHLIB. All of the historical information in library QPFRDATA is included in the graph.

Example 2: Saving a Graph

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

This command submits a job to save the graph in a GDF file. The graph is saved in the file USERLIB/USERFILE/TEST.

Example 3: Printing a Graph

DSPHSTGPH   GRAPH(GRAPHLIB/CPU)  OUTPUT(*PRINT)
            PRTDEV(PRT03)  JOBD(*LIBL/QPFRJOBD)

This command submits a job to print the graph on the system printer named PRT03.

Example 4: Printing All Graphs in a Package

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

This command submits a job to print all of the graphs defined in PACKAGE1 in GRAPHLIB. The print job is sent to the system printer named PRT03. It uses the historical data members in QPFRDATA for its information.

Example 5: Displaying a Graph

DSPHSTGPH   GRAPH(GRAPHLIB/CPU)  OUTPUT(*)
            PERIOD(112799 100900)

This command displays a graph of historical information from 27 NOV 1999 to 9 OCT 2000.

Example 6: Selecting Members to be in a Graph

DSPHSTGPH   GRAPH(GRAPHLIB/CPU)  MBRLIB(MONDAY)
            OUTPUT(*)  PERIOD(*SELECT *N)

This command shows the historical members selection menu for the members in library MONDAY. The user then selects the members to be shown in the graph.

Error messages

*ESCAPE Messages

PFR5501

Performance data file(s) are not upward compatible.

PFR5502

Performance data file(s) are not downward compatible.

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.

PFR9072

Cannot use member &3 in historical graph.

PFR9073

Cannot use member &2 in historical graph.

PFR9074

Too many members selected.

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.

PFR9088

Cannot display graph because of missing data.

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.

PFR9114

No historical data to graph.