Important This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.1 for BMC Helix Operations Management.

chart()

Pop up, destroy, or print a chart (graph) on the PATROL Console.

Syntax

chart( command , gdf_string ,[ID])

Parameters

Parameter

Definition

command

built-in constants (symbolic names) for the different chart commands*Valid Values* 
CHART_LOAD-loads a specified chart 
CHART_PRINT-prints a loaded chart 
CHART_DESTROY-destroys a loaded chart

gdf_string

string describing the chart For more information, see Graph Definition Format (GDF) Syntax.

ID

name identifying the chart on the console The ID is returned by the CHART_LOAD command, and it is required for CHART_PRINT and CHART_DESTROY commands.

Description

The chart() function loads (displays), prints, and destroys charts (also called graphs) on the PATROL Console.

Loading a Chart

Using CHART_LOAD for the command parameter loads a chart on the PATROL Console. The contents of the chart are specified in a Graph Description Format (GDF) string. See Graph Definition Format (GDF) Syntax. The following example shows the use of the CHART_LOAD command:

chart(CHART_LOAD,gdf_string);

 

The GDF information can be specified in the function call, supplied as a variable, or specified in an external file. For more information on specifying GDF information in chart() function calls, see Specifying GDF data in chart() function calls. 

The return value of the chart() function call with the CHART_LOAD command is the handle for the chart, and it is required as the ID parameter for the CHART_PRINT and CHART_DESTROY operations.

Printing a Loaded Chart

Using CHART_PRINT for the command parameter prints a chart that is loaded on the PATROL Console. When the CHART_PRINT command is used, the PATROL Console displays a print dialog box for the user to print the chart. The following example shows the use of the CHART_PRINT command:

 

chart(CHART_PRINT,"",ID);

 

Destroying a Loaded Chart

Using CHART_DESTROY for the command parameter destroys a chart that is loaded on the PATROL Console. When the chart is destroyed, it disappears from the console display, and it is removed from the console memory. The following example shows the use of the CHART_PRINT command:

 

chart(CHART_DESTROY,"",ID);

 

Errors

The chart() function returns the following PSL errno values on failure:

errno Value

Description

93

E_PSL_NO_SUCH_ID 
The required ID was not supplied or it is invalid.

120

E_PSL_BAD_CHART_COMMAND 
An invalid command was supplied.

GDF Syntax

The GDF definition for a PATROL graph consists of comments and keywords that define the graph and the data values for the graph.

GDF Comments

Comments in a GDF definition are usually used when a GDF definition is stored in an external file. A GDF comment must have an exclamation mark warning as its first character, and a comment can contain any character except the NULL character or a new-line (\n) character.

GDF Chart Definition Keywords

GDF provides a set of keywords that are used to define the graph. The keywords values are specified using the following format:

 

keyword:value

 

The GDF keyword values can contain any combination of letters, numbers, spaces, underscores (_), and dashes(-). The keywords can be separated into two types graph definition and data definition keywords. 

Each keyword specification is either terminated with a new-line (\n) character or a line break in an external file.

Graph Definition Keywords

There are several keywords that define the appearance of the chart on the PATROL Console. These keywords control the titles, scales, colors of the chart. The following table describes the GDF graph definition keywords:

Keyword Format

Description

WindowTitle:Window_Title

title of the window or icon

ChartTitle:Chart_Title

title of the chart

XAxisLabel:X_Axis_Label

label for the x-axis of the chart

YAxisLabel:Y_Axis_Label

label for the y-axis of the chart

ChartTemplate:File_Name

file that contains the chart template TheFile_Name may contain the path to the chart template file. The chart template file can be created by using the PATROL Developer Console and saving your chart customizations. For more information on customizing PATROL charts, see your PATROL Console documentation.

 

Data Definition Keywords

GDF provides two keywords for defining the data that is displayed in the chart:

Keyword Format

Description

StaticData2D

defines static data Static data is data that is defined before the chart is displayed and is not updated as the chart is displayed.

PatrolConsole

defines dynamic data Dynamic data is data that is read directly from a PATROL parameter, and it is updated on the chart as the parameter is updated.

 

Static Data 

Static data is created by supplying the data name and the data parameters to the chart() function in the GDF string. The data portion of the GDF string for a static chart contains the data name and one or more data points in the following format:

 

StaticData2D:name, time value,...,timen valuen\n

Variable

Description

name

name of the value that is graphed The name appears in the name column of the graph legend.

time value,... timen valuen

one or more pairs of time and value that are graphed The time is the current local system time specified as the number of seconds that have elapsed since 00:00:00 GMT, Jan 01, 1970. The time value pairs are separated by commas, and the time and value in the pair are separated by spaces.

 

The following example is the data portion of a GDF string for a static chart:

 

data="StaticData2D:Value Name, 956159608 10.5, 956159668 20.4\n";

 

Dynamic Data 

Dynamic data is created by supplying a host name and a parameter name to the chart() function in the GDF string. The data is then read from the host machine and displayed on the graph. A dynamic data chart is updated with new data points by the agent as long as the chart is active. 

The data portion of the GDF string for a dynamic chart contains the host name and the parameter name in the following format:

 

PatrolConsole: host_name , parameter_name \n

Variable

Description

host_name

name of the host that the data is displayed for in the chart Thehost_name must be specified in the same format as it appears in the tree view of the PATROL Console displaying the chart. There are three ways that a user can enter the host in the tree view of the PATROL Console:

The host_name specified in the chart() function call is not case sensitive. Note 
There are a couple of points to consider about the host name in the tree view of the PATROL Console:

  • For the chart() function to find the host and properly display the data, the host name must be in all upper-case or all lower-case characters on the PATROL Console.

  • There is no way to determine the host name entry in the tree view of the PATROL Console using PSL. The get("hostname") function call always returns the simple host name in all upper-case or all lower-case characters.|

    parameter_name

    name of the parameter that has its values displayed in the chart The parameter name must include the entire PATROL path name that follows the host name.

 

The following example is the data portion of a GDF string for a dynamic chart:

 

data="PatrolConsole:pfarrell,/NT_MEMORY/NT_MEMORY/MEMmemPagesInputPerSec\n"

 

Specifying GDF data in chart() function calls

The GDF definition for the chart is usually specified using one of the following techniques:

  • GDF string is specified in the chart() function call

    id = chart(CHART_LOAD,"StaticData2D:CPU, 956159600 10.5\n");

  • GDF string is assigned to a variable that is used in the chart() function call

    id = chart(CHART_LOAD,"StaticData2D:CPU, 956159600 10.5\n");

  • GDF string is specified in an external file

    id = chart(CHART_LOAD,cat("file.gdf"));

The following example shows the syntax of an external GDF file:

WindowTitle: Data Analysis from Patrol 3.4
!Here is a comment !Use current directory file named "example.ctf" as template file
ChartTemplate: example.ctf ChartTitle: hostname CPU and Memory Usage
XAxisLabel: April 19, 2000 YAxisLabel: % !Then add chart data
StaticData2D:CPU for hostname, 956159600 10.5, 956160200 20.4, 956160800 40.4
StaticData2D:Memory for hostname, 956159600 50.5, 956160200 60.7, 956160800 71.3

Example

The following example defines a chart with static data, destroys the static chart, and then creates a dynamic chart:

# define chart one
ct = "ChartTitle: Chart Example ONE - Static Data\n";
x = "XAxisLabel: Time\n";
y = "YAxisLabel: %\n";
d1 = "StaticData2D:CPU for host name,836586286 10.5, 836586386 20.4,
836586486 7.90, 836586586 20, 836586686 13, 836586786 0\n";
# build the GDF string
gdf_string = ct.x.y.d1;
#display chart one
id = chart(CHART_LOAD, gdf_string);
chart(CHART_PRINT, "", id);
sleep(10);
chart(CHART_DESTROY, "", id);
# define chart two
ct = "ChartTitle: Chart Example TWO - Feeding on PATROL
PARAMETERS\n";
x = "XAxisLabel: CPU\n";
y = "YAxisLabel: Percent\n";
# pfarrell is my PATROLAGENT machine
host_name = get("hostname");
d1 =
"PatrolConsole:".host_name.",/NT_CPU/CPU_0/CPUprcrUserTimePercent\n"
;
d2 =
"PatrolConsole:".host_name.",/NT_CPU/CPU_0/CPUprcrProcessorTimePerce
nt\n";
# build the GDF string
gdf_string = ct.x.y.d1.d2;
# display chart two
id = chart(CHART_LOAD,gdf_string);
chart(CHART_PRINT, "", id);
sleep(10);
chart(CHART_DESTROY, "", id);

 

This example creates the following charts: 
chart_example.png

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*