iChart Reference

The chart object can process and display data sets of up to 32 tags and thousands of observations per tag in a variety of visual formats.

The iChart applet supports the SelectionEvent applet parameter to permit JavaScript functions to be linked to the user clicking on an item in the chart legend.

iChart Types

*Chart Type*	*Description*
Line	Line chart, typically used for time-series data
Bar	Bar chart, with data values interspersed
GroupBar	Bar chart, with data values ordered by tagname/dataset, then by observation
Pie	Pie chart
Polar	Polar chart or circular chart, where values are drawn in a circular fashion
StackedBar	Stacked bar chart, where individual samples are "stacked" into a single bar
FloatingBar	Floating bar with a crosshair indicator, typically used with min/max/average or low/high/close type charts
VariabilityBar	Floating bar, used with average and standard deviation data to plot process variability using +/- 3 sigma
Gauge	Rotary gauge with moving needle and user-specifiable gauge start and end angles
XY	Scatter plot which displays crosshair indicators for data values, where the first tag/dataset provides the X axis value
XYRegression	Same as XY chart, with a linear regression line drawn on top of the scatter plot
Regression	Same as XYRegression chart, but the scatter plot (individual data points) are not drawn
Strip	Very similar to a line chart, but the underlying data source provides current values that are trended "in memory"
Radar	Similar to a polar chart, however, the data values generally do not have a time axis, and are displayed in a slightly different visual format. The radar chart can be used to show comparisons between multiple observations or versus target ranges.
EventHorizon	This chart shows a vertical line associated with each time stamped event returned from a query. The appearance is similar to a spectral analysis. It is a convenient means for showing the occurrence of alarms/events over a specified time interval.
Custom	This chart combines the characteristics of the line, bar, and group bar charts. Each returning data point, or pen, can be assigned to draw as a line, single bar, or as part of a group bar. See the Custom Chart Helper Reference for more information on the specifics of this chart type.
Waterfall Chart	This chart is a variation on a stacked bar chart. Each floating bar represents a number for the current X-axis period, but the position of the floating bar along the Y-axis represents a cumulative total of the previous bars. Negative and positive values are displayed in different colors. This is ideal for showing "contribution margin" or "components" where the values may be both positive and negative.
Horizontal Bar	This is a variation on the Bar chart, allowing the bar length to be horizontal rather than vertical.
Horizontal Group Bar	This is a variation on the Group Bar chart, allowing the bar length to be horizontal rather than vertical.

iChart Events

In addition to the generally supported applet events, the iChart supports the ChartSelection and the ChartDoubleClick events.

Parameter Name	*Data Type*	*Default Value*	*Comments*
General Event Support			See the section on Linking JavaScript To Applet Events in the Applet General Reference
ChartSelectionEvent	String	None	This parameter is used to provide the name of a JavaScript function in a Web page that will be called whenever the user clicks on the chart in the iChart applet. For example, it can be used to call the getLastSelectedTag or getLastSelectedPoint methods to determine which point has been selected (see below for details).
ChartDoubleClickEvent	String	None	This parameter is used to provide the name of a JavaScript function in a Web page that will be called whenever the user double-clicks in the chart area of the iChart applet.

iChart Methods

iChartComponent getChartObject()

This method is used to obtain a reference to the underlying chart display object (the iChartComponent class). The following section describes the properties and methods exposed by this object.

void updateChart(boolean bReloadData)

This method is used to update the chart contents. The parameter indicates whether or not to re-read the underlying data. This method differs from the refresh() method in the case where the underlying query is "time-based". In the case of a time-based query, the refresh() method will update the start and end dates based on the current time less the duration/duration units, but the updateChart method will use the specified dates.

void doPrint()

This method is used to pop up an HTML page containing a GIF representation of the current chart, suitable for printing.

iChartComponent General Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
ChartType	String	Line	See above for listing of types.
MainBackgroundColor	Color	#404040	Color of the overall applet background
MainBorderColor	Color	#000000	Border color for the applet
ChartBackgroundColor	Color	#000000	Color for the chart area background
ChartBorderColor	Color	#FFFFFF	Border color for the chart area
TitleColor	Color	#FFFFFF
Title	String	None
TitleFontFace	String	Helvetica
TitleFontSize	Integer	16
TitleFontStyle	Integer	3
HorizontalGridColor	Color	#C0C0C0
VerticalGridColor	Color	#C0C0C0
HorizontalGridLineCount	Integer	10	Note that this also controls how gauges will be displayed. For gauge mode, the grid lines divide the chart into a series of gauge areas that will determine gauge sizing.
VerticalGridLineCount	Integer	8
GaugeStartAngle	Integer	225	This defines the start angle, with "East" being zero. This is only applicable to the Gauge type chart.
GaugeSweepAngle	Integer	270	This defines the sweep angle in degrees, moving clockwise. This is only applicable to the Gauge type chart.
ThreeD	Boolean	False	This determines whether or not the chart will be drawn in 3D mode, and only applies to bar-style charts.
ZeroBasedCenterline	Boolean	False	If true, the centerline of the chart is drawn at a zero y-axis value as opposed to the center of the chart area
BarSpacing	Integer	2	If using a bar chart, this defines the horizontal spacing between the bars (in pixels)
BarGroupSpacing	Integer	4	If using a bar chart, this defines the horizontal spacing between the bar groups (in pixels)
BarMarginSpacing	Integer	4	If using a bar chart, this defines the horizontal margin spacing between the chart objects (bars) and the chart perimeter (in pixels)
MarkerSize	Integer	5	In a line chart, you may define the marker size for individual data point markers. Larger numbers mean bigger markers
MarkerStyle	Integer	0	In a line chart, you may define the default marker style for individual data points. If you wish to have different markers for different lines, you must define them on a pen by pen basis. Default value of 0 means no marker.
ShowLines	Boolean	true	For a line chart you can choose to just show the markers and not the lines.
InterpolateLines	Boolean	true	This controls whether a line chart will interpolate values between data readings. For a step type chart, this value should be turned off. A true setting will draw a direct line between two points, "smoothing" the chart appearance.

iChartComponent Legend Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
LegendBackgroundColor	Color	#404040	Color for the background of the legend area.
LegendBorderColor	Color	#FFFFFF	Color for the border of the legend area.
LegendSelectionBorderColor	Color	#C0C0C0	Color for a border around the selected legend item.
LegendLabelColor	Color	#FFFFFF	Color for legend labels if "UsePenColor" is set to false.
LegendOnTop	Boolean	False	Determines whether the legend will be located to the right of or at the top of the chart area.
LegendWidth	Integer	20	Defines the space to allocate for the legend, in characters.
LegendHeight	Integer	0	Defines the space to allocate for the legend when displayed on top, in characters.
LegendShowValue	Boolean	False	Determines whether or not to display tag values next to the legend items. This is only meaningful with charts that have a single data value per legend item/tag.
LegendShowTagName	Boolean	True	Determines if chart will display the tagname.
LegendShowTagDescription	Boolean	False	Determines if chart will display the tag description.
LegendDescriptionLabel	String	Tag Description:	Text to be shown preceding the tag description in the area below the chart.
LegendUsePenColor	Boolean	True	Determines whether to draw legend text using the pen color or using the LegendLabelColor property.
LegendFontFace	String	Helvetica
LegendFontSize	Integer	12
LegendFontStyle	Integer	0

iChartComponent Chart Area Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
ShowTitle	Boolean	True
ShowLegend	Boolean	True
ShowHorizontalGrid	Boolean	True
ShowVerticalGrid	Boolean	True
ShowXAxis	Boolean	True
ShowYAxis	Boolean	True
ShowTagDescription	Boolean	True	Determines whether or not to show the tag/legend item description below the chart area.
ShowTimeControl	Boolean	True	Determines whether or not to show the navigation/refresh bar at the bottom of the chart.
ShowScooter	Boolean	False	Determines whether or not to show the scooter values in the legend when the mouse moves over the chart area.
ShowMouseTracking	Boolean	False	Determines whether or not to show the mouse tracking values in the upper left corner of the chart when the mouse moves over the chart area. For more information on customizing the mouse tracking display information please refer to the User's Guide for Applet Basics.
ShowMouseTrackingTagName	Boolean	True	(ShowMouseTracking = True) Determines whether or not to include the TagName of an object (bar, line, datapoint, etc.) when the cursor is over the object.
ShowMouseTrackingXValue	Boolean	True	(ShowMouseTracking = True) Determines whether or not to include the XAxis value when the cursor is over the object.
ShowMouseTrackingYValue	Boolean	True	(ShowMouseTracking = True) Determines whether or not to include the YAxis value when the cursor is over the object.
ShowMouseTrackingDatalinkValue	Boolean	True	(ShowMouseTracking = True) Determines whether or not to include the first mapped Datalink Column value when the cursor is over the object. (In order for a DataLink value to appear, at least one DataLinkColumns must be mapped into the chart, using the Data Mapping tab in Template Editor.)
ShowMouseTrackingValues	Boolean	True	(ShowMouseTracking = True) Determines whether or not to display the mouse tracking information when the cursor is directly over an object (bar, line, marker, etc.).
ShowMouseTrackingBackground	Boolean	True	(ShowMouseTracking = True) Determines whether or not to display the mouse tracking information when the cursor is not directly over an object (bar, line, marker, etc.).

iChartComponent X Axis Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
XAxisTickColor	Color	#FFFFFF
XAxisTickHighlightColor	Color	#000000
XAxisLabelColor	Color	#FFFFFF
XAxisThreeD	Boolean	True	Determines whether tick marks will be drawn with a highlight shadow or not.
XAxisShowTicks	Boolean	True
XAxisShowLabels	Boolean	True
XAxisMajorTickCount	Integer	10
XAxisMinorTickCount	Integer	6
XAxisTicksPerLabel	Integer	2	Determines the frequency of labels relative to Major ticks.
XAxisLabelDepth	Integer	1
XAxisDateFormat	String	MM/dd/yy
XAxisTimeFormat	String	HH:mm:ss
XAxisNumberFormat	String		This controls the format with which numeric values would be displayed on the X Axis for the Waterfall and Pie Charts. By default, this is controlled by the decimal places defined for the pen. Examples would be 0.00;(0.00) or #,##0 PSI
XAxisFontFace	String	Helvetica
XAxisFontSize	Integer	12
XAxisFontStyle	Integer	0
XAxisWidth	Integer	8	Determines the amount of horizontal space to allocate for the X axis for the horizontal bar chart types; measured in characters
CustomLabelColor	Color	#FFFFFF	Defines the color to be used for the custom labels
CustomLabels	String List	None	This parameter provides a list of user-provided labels that will be displayed below the X Axis of the chart. The label positions will be evenly spaced based on the number of items provided in the list. Only the Bar, GroupBar, VariabilityBar, FloatingBar, and StackedBar charts support this parameter. The custom labels will be displayed using the XAxisFont and the XAxisLabelColor values.

iChartComponent Y Axis Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
YAxisTickColor	Color	#FFFFFF
YAxisTickHighlightColor	Color	#000000
YAxisLabelColor	Color	#FFFFFF
YAxisThreeD	Boolean	True	Determines whether tick marks will be drawn with a highlight shadow or not.
YAxisShowTicks	Boolean	True
YAxisShowLabels	Boolean	True
YAxisUsePenColor	Boolean	True	Determines whether or not the Y Axis labels will be drawn using the currently selected pen color or the YAxisLabelColor.
YAxisMajorTickCount	Integer	10
YAxisMinorTickCount	Integer	6
YAxisTicksPerLabel	Integer	2	Determines the frequency of labels relative to Major ticks
YAxisWidth	Integer	8	Determines the amount of vertical space to allocate for the Y axis; measured in characters
YAxisDateFormat	String	MM/dd/yy
YAxisTimeFormat	String	HH:mm:ss
YAxisNumberFormat	String		This controls the format with which numeric values would be displayed on the Y Axis and in value labels on the various charts. By default, this is controlled by the decimal places defined for the pen. Examples would be 0.00;(0.00) or #,##0 PSI
YAxisFontFace	String	Helvetica
YAxisFontSize	Integer	12
YAxisFontStyle	Integer	0

iChartComponent Data Binding Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
ValueColumns	String List	None	This controls which data columns in a query will be used as the values to plot on the chart.
LabelColumns	String List	None	This controls which data columns in a query will be used to create "virtual tag names" when the chart is drawn. This set of parameters is typically not needed when the query source is a Tag connector, but is required when the source is a SQL or Alarm connector.
DescriptionColumns	String List	None	This controls which data columns in a query will be used to create "virtual tag descriptions" when the chart is drawn. This set of parameters is typically not needed when the query source is a Tag connector, but is required when the source is a SQL or Alarm connector.
DatalinkColumns	String List	None	This controls which data columns in a query will be used to create "datalink" items associated with each item in the legend. This is convenient means of associating special column values such as a part code, downtime ID, or other internal key field that has no meaning to the end user but is valuable when cross-correlating or linking with other applets. The first mapped Datalink column is also used by the MouseTracking feature.
AxisValueColumn	String	None	This is used to create explicit X-Axis values from a returning column in the query
AxisLabelColumns	String List	None	This controls which data columns in a query will be used to create X-Axis labels associated with each data point in the chart. This is supported only with barchart-style charts (Bar, GroupBar, StackedBar, FloatingBar, and Variability Bar).
MinRangeColumn	String List	None	This controls which data columns in a query will be used to create the minimum pen scaling range for the Y-Axis legend.
MaxRangeColumn	String List	None	This controls which data columns in a query will be used to create the maximum pen scaling range for the Y-Axis legend.
IncludeValueInLabel	Boolean	False	This controls whether the value column names will be merged with the LabelColumn column names when generating "virtual tag names".
FieldSeparator	String	Underscore ("_")	This controls the character that will be used when appending multiple string values in the creation of "virtual tag names".

iChartComponent Global Scaling And Numeric Precision Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
GlobalAutoScale	Boolean	false	This parameter determines whether or not auto-scaling will be applied to all pens.
ZeroBasedScale	Boolean	false	If auto-scaling is enabled, either at the pen or global level, this property determines how the minimum range will be calculated. If this parameter is true, the value of zero (0) will always be used as the minimum range.
GlobalServerScaling	Boolean	true	This parameter determines whether the min/max ranges should be based on the values returned by the connector in its legend information (typically min/max engineering ranges). Note that only Tag connectors (and not all Tag connectors) are capable of providing this information.
UseGlobalRanges	Boolean	false	This parameter determines whether or not to force the min/max range for each pen to the values defined in the GlobalMinRange and GlobalMaxRange parameters.
GlobalMinRange	Floating Point	0.0	Used when UseGlobalRanges is set to true.
GlobalMaxRange	Floating Point	100.0	Used when UseGlobalRanges is set to true.
UseGlobalDecimals	Boolean	false	Determines whether or not to use a single global setting for the decimal precision for each pen.
GlobalDecimals	Integer	2	If UseGlobalDecimals is true, this value determines the number of decimals places that will be used when outputting numbers/labels in the chart.
UseScreenResolution	Boolean	true	If true, the RowCount parameter in the underlying query for the chart will be set to the width, in pixels, of the chart object. This is useful if the connector is capable of interpolated data values (which many of the Tag-based connectors are) to minimize the size of the data set by balancing it with the available screen resolution. In general, this value should NOT be used with HistoryEvent mode or with SQL and/or Alarm connector queries.

iChartComponent Pen-Specific Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
MinRange.1 ... MinRange.32	Floating Point	0.0	Minimum range for the pen
MaxRange.1 ... MaxRange.32	Floating Point	100.0	Maximum range for the pen
AutoScale.1 ... AutoScale.32	Boolean	false	Indicates whether or not to auto-scale this pen (note that global values take precedence)
UseServerScaling.1 ... UseServerScaling.32	Boolean	false	Indicates whether or not to use the min/max ranges returned by the connector
PenColor.1 ... PenColor.32	Color	varies for each pen
PenType.1 ... PenType.32	String	Default	This parameter is only valid for the custom chart type. It allows the user to define what type of graphical element will be drawn for the returning value. The choices are Default, which will always be the chart type, Line, Marker, Bar, and Stacked Bar. Line is a simple line with no markers representing individual points. Marker is a line with each data point having a specific marker type (defined by PenMarkerStyle parameter, see below). Bar is a simple individual bar. Stacked Bar behaves like the stacked bar chart. Only a single "stack" can be defined per chart, so all pens of this type will be stacked together. There may be multiple individual bars per chart and will be grouped together similar to the GroupBar chart type.
PenMarkerStyle.1 ... PenMarkerStyle.32	Integer	0	Marker Style defines the representation for individual data points on a "Marker" type line. Each point can also have individual selections points, such as click and double-click. The style choices include: 0-None (which is the default indicating no marker), 1-Circle, 2-Square, 3-Triangle, 4-Diamond, 5-X, and 6-Cross.
Decimals.1 ... Decimals.32	Integer	2	Defines the # of decimal places to use when outputting data or labels for this pen.

iChartComponent Behavior Properties

Parameter Name	*Data Type*	*Default Value*	*Comments*
EnableMenu	Boolean	True	This parameter enables or disables the right-click functionality in the chart object.
EnableDoubleClickRefresh	Boolean	True	This parameter enables or disables the ability to refresh a chart by double clicking on it. In the case of time-sensitive charts, the double click event will update the chart to the current time.
EnableLegendClick	Boolean	True	This parameter enables or disables the ability to select an item in the legend.
EnableQueryProperties	Boolean	True	This parameter enables or disables the ability to modify tag queries (such as browsing tags, connectors, servers, etc.) at runtime
EnableQueryTemplateSave	Boolean	True	This parameter enables or disables the ability to save query templates via the popup menu.
EnableQueryTemplateLoad	Boolean	True	This parameter enables or disables the ability to load query templates via the popup menu.
EnableDisplayProperties	Boolean	True	This parameter enables or disables the ability to modify display attributes at runtime (chart layout, appearance, refresh rate, etc.).
EnableDisplayTemplateSave	Boolean	True	This parameter enables or disables the ability to save display templates via the popup menu.
EnableDisplayTemplateLoad	Boolean	True	This parameter enables or disables the ability to load display templates via the popup menu.
EnableSaveAs	Boolean	True	This parameter enables or disables the ability to save the currently viewed query as a CSV file on the local computer.
EnableShowDetail	Boolean	True	This parameter enables or disables the ability to view the underlying data (or a statistical/current value view of the data) as an HTML page.
EnableAutoRefresh	Boolean	True	This parameter enables or disables the ability to control the buttons on the navigation/refresh bar at the bottom of the chart.
EnableItemSelection	Boolean	True	This parameter enables or disables the ability to select an item in the chart area, typically a marker or a bar.

iChartComponent Refresh Properties

Please refer to the Applet General Reference for details on the Refresh Properties.

iChartComponent Methods

int getTagCount()

This method is used to get the current # of tags in the chart/legend.

boolean isTagAssigned(int nPen)

This method is used to determine whether one of the thirty-two (32) available pen slots it assigned to a tag.

int getSelectedPen()

This method is used to obtain which pen number has been selected in the chart legend.

void setSelectedPen(int nPen)

This method is used to select a pen number in the chart legend.

String getTagDescription(int nPen)

This method is used to obtain the description for a specific pen.

String getTagName(int nPen)

This method is used to obtain the tag name (or virtual tag name) for a specific pen.

String getSelectedTagName()

This method is used to obtain which pen name has been selected in the chart legend.

String getDatalinkValue(int TagNumber, int PointNumber, int AttributeIndex)

This method is used to obtain any additional data that has been bound to a specific pen (usually done with Tag queries).

String getDatalinkColumn(int index)

Returns a string value representing the datalink value for the item at the input index in the value list.

int getLastSelectedTag()

Returns the last tag that was selected in the chart menu. This value is updated on each tag click or double-click. The value gets updated before the selection event or double-click event is fired.

int getLastSelectedPoint()

Returns the index of the last selected point in the chart. This value is updated on each point click or double-click. The value gets updated before the selection event or double-click event is fired.

int getNumberOfDataPoints(int nPen)

This method is used to obtain the # of data values associated with a specific pen.

double getYDataValueAt(int nPen, int dataindex)

This method is used to obtain the underlying Y axis (data) value for a specific pen/data item.

double getXDataValueAt(int nPen, int dataindex)

This method is used to obtain the underlying X axis value for a specific pen/data item.

long getChartWidth()

This method is used to obtain the current time interval for the chart, in milliseconds.

void zoomFullScale()

This method is used to zoom the chart to its full range limits.

void zoomToCursor()

This method is used to zoom the chart to the selected cursor range (using rubberband zoom box highlighted by dragging with the mouse).

void zoomBox(double dHorizontal, double dVertical)

Zooms the chart to a percentage of the currently visible range or chart width. The chart center remains the same. To zoom on one dimension only, use a value of 100 percent for the range you do not wish to zoom. The range for both parameters is 0 to 1000.

void scrollBox(double dHorizontal, double dVertical)

Scrolls the chart to a percentage of the currently visible range or chart width. The min/max ranges and chart width remain the same. To scroll on one dimension only, use a value of zero (0) percent for the range you do not wish to scroll. The range for both parameters is -100.0 to 100.0.

double getXAxisZoomMin()
double getXAxisZoomMax()
double getYAxisZoomMin()
double getYAxisZoomMax()

These methods return the zoom minimum and maximum ranges for each of the axes. The default values upon loading a chart are a minimum of 0 and a maximum of 100.

void setXAxisZoomMin(double dMin)
void setXAxisZoomMax(double dMax)
void setYAxisZoomMin(double dMin)
void setYAxisZoomMax(double dMax)

These methods set the zoom minimum and maximum ranges for each of the axes. The default values upon loading a chart are a minimum of 0 and a maximum of 100. This can be used to programmatically zoom and pan the chart externally.

double getEffectiveMinRange(int PenIndex)

This method returns the minimum range value for the current view for the passed in pen index.

double getEffectiveMaxRange(int PenIndex)

This method returns the maximum range value for the current view for the passed in pen index.

iChart Usage Notes

Chart Parameters Applicable to Various Chart Types

Not all of the chart parameters are applicable to all of the supported chart types. For example, the pie chart and gauge chart have only a single axis. In general, the Y Axis properties control output for text on these special types of charts.

Gauge Chart Layout

Another special case is the gauge chart. The gauge chart can be thought of as an "array" or "grid" of gauges. The size and orientation of these gauges is controlled by the HorizontalGridLineCount and VerticalGridLineCount parameters.

XY Charts And Queries

When utilizing XY charts, the first tag will be considered the "X" tag, and any other tags will be correlated against the values of this tag.

Floating Bar Charts and Queries

The floating bar chart expects data to be provided with three values per data point, including a minimum, maximum, and average. This can be accomplished with Tag-based connectors using statistics mode and a method such as MIN,MAX,AVG (arithmetic average) or MIN,MAX,TWA (time-weighted average). SQL queries used to feed this type of chart must provide a similar data set.

Variability Bar Charts and Queries

The variability bar chart expects data to be provided with two values per data point, including an average and a standard deviation. This can be accomplished with Tag-based connectors using statistics mode and a method such as AVG,SDV (arithmetic average) or TWA,SDV (time-weighted average). SQL queries used to feed this type of chart must provide a similar data set.

Radar Charts

Because of the unique visual orientation of the Radar chart, it can be confusing which properties control which color features on the chart. The XAxisTickColor property controls the color of the "spikes" or "arms" radiating from the center of the chart. The YAxisTickColor property controls the color of the concentric polygons that mark each "tick" on the chart. The YAxisMajorTickCount controls the number of "ticks".

Strip Charts

Unlike Line charts, which are accessing data from some type of process historian or database, the Strip chart acquires current values from a SAP xApp Manufacturing Integration and Intelligence (SAP xMII) server and displays a live trend of these values. Whenever the page is closed, the values are no longer stored. The chart will begin anew the next time it is displayed in a Web page.

Two parameters control the width of the time axis (X axis) on the Strip chart. These are the RefreshRate parameter in the chart and the RowCount parameter in the query template. The total duration for the real-time trend is determined by simply multiplying the RefreshRate times the RowCount.

Event Horizon Charts

When utilizing EventHorizon charts, the only requirement is that the query return a timestamp value in its results. Additionally, you can use the Data Mapping techniques to "group" events via the LabelColumns property. Each "group" of events will be displayed in a different color on the chart.

Waterfall Charts

When utilizing Waterfall charts, the colors for the various bars will be controlled using the first four (4) pen colors. Pen #1 color will control the leftmost bar, Pen #2 color will control negative values, Pen #3 color will control positive values, and Pen #4 color will control the rightmost (calculated) bar.

Data Mapping

As discussed in the parameter reference above, using the iChart object with SQL and Alarm queries requires some data mapping to give the iChart object "hints" as to how to link the columns returned from the query with the various elements in the chart (legend, description, data values). Experimentation with these properties is the easiest way to learn the behaviors of each. As an example, suppose that a SQL query returns the following data set:

UsageDate	UsageSource	Feed1Watts	Feed2Watts	Feed3Watts
01/18/2000 09:30:01	BagHouse	1312.00	3654.00	2625.00
01/18/2000 09:30:03	Oven2	14765.00	18123.00	478.00
01/18/2000 09:30:05	Oven1	18203.00	512.00	14897.00
01/18/2000 09:31:02	BagHouse	1365.00	3531.00	2606.00
01/18/2000 09:31:02	Oven2	13242.00	19657.00	903.00
01/18/2000 09:31:07	Oven1	18998.00	12.00	13809.00
01/18/2000 09:32:01	BagHouse	1347.00	3439.00	2701.00
01/18/2000 09:32:01	Oven2	11909.00	19454.00	1897.00
01/18/2000 09:32:11	Oven1	19234.00	3.00	13623.00
01/18/2000 09:33:00	BagHouse	1303.00	3507.00	2684.00
01/18/2000 09:33:01	Oven1	19465.00	1.00	14154.00
01/18/2000 09:33:02	Oven2	9565.00	19154.00	3023.00
01/18/2000 09:34:02	BagHouse	1309.00	3498.00	2404.00
01/18/2000 09:34:03	Oven2	10560.00	18877.00	4312.00
01/18/2000 09:34:12	Oven1	19087.00	3.00	14002.00
01/18/2000 09:35:00	BagHouse	1352.00	3525.00	2329.00
01/18/2000 09:35:01	Oven2	11523.00	16896.00	5434.00
01/18/2000 09:35:30	Oven1	19912.00	4.00	10876.00
01/18/2000 09:36:02	Oven2	12787.00	15897.00	6554.00
01/18/2000 09:36:03	BagHouse	1398.00	3676.00	2198.00
01/18/2000 09:36:09	Oven1	21454.00	100.00	11654.00
01/18/2000 09:37:00	BagHouse	1425.00	3698.00	2014.00
01/18/2000 09:37:03	Oven2	13165.00	14907.00	7654.00
01/18/2000 09:37:06	Oven1	23155.00	3.00	11876.00
01/18/2000 09:38:01	Oven2	14126.00	16065.00	8776.00
01/18/2000 09:38:02	BagHouse	1465.00	3708.00	1995.00
01/18/2000 09:38:04	Oven1	22005.00	5.00	13009.00
01/18/2000 09:39:01	BagHouse	1478.00	3699.00	1992.00
01/18/2000 09:39:02	Oven2	15123.00	17998.00	9065.00
01/18/2000 09:39:07	Oven1	21014.00	0.00	12131.00
01/18/2000 09:39:57	Oven1	19645.00	655.00	11405.00
01/18/2000 09:39:59	BagHouse	1587.00	3435.00	2417.00

In this case, the LabelColumns,ValueColumns, FieldSeparator, and IncludeValueInLabel parameters might be set as follows:

<PARAM NAME="LabelColumns" VALUE="UsageSource">
<PARAM NAME="ValueColumns" VALUE="Feed1Watts,Feed2Watts,Feed3Watts">
<PARAM NAME="IncludeValueInLabel" VALUE="true">
<PARAM NAME="FieldSeparator" VALUE="@">

As a result, when the SAP xMII processes the results of the query, it will look at the values of the label column(s) and assemble "virtual tag names" for each unique combination that it finds, up to the 32 tag limits. Additionally, if the IncludeValueInLabel column is set, which is usually only needed when there is more than one value column to be charted, the "virtual tag names" will include the column names for the value columns. Thus, in this example, the virtual tag names created would be:

Oven1@Feed1Watts
Oven1@Feed2Watts
Oven1@Feed3Watts
Oven2@Feed1Watts
Oven2@Feed2Watts
Oven2@Feed3Watts
BagHouse@Feed1Watts
BagHouse@Feed2Watts
BagHouse@Feed3Watts

Note that the value of the FieldSeparator property controls the delimiter character that will be used when assembling tag names, descriptions, or axis labels.

The tag descriptions are dynamically assembled in a similar manner, based on the DescriptionColumns parameter.

A capability is also provided to link data values in one or more values from the query results to labels for each data point that can be displayed on the horizontal (X) axis of bar-style charts. Note that unlike DataLink and Description values, which are associated with each tag/item in the legend, these values are associated with each data point. As a result, they are typically only used in charts with relatively small numbers of data points, to avoid a cluttered chart appearance.

Additionally, the DataLinkColumns parameter allows other values from the query results to be associated with each "virtual tag". Again, experimentation with these parameters is the best way to become familiar with their flexibility and use.

Accessing Underlying Data

The getTagCount, getSelectedPen, getTagName, getTagDescription, getNumberOfDataPoints, getXDataValueAt, getYDataValueAt, and getDatalinkValue methods provide accessors to the underlying chart data. For example, to get the first value for the currently selected pen, a script such as the following could be used:

var myChart = document.ChartApplet.getChartObject();


var pen = myChart.getSelectedPen();


var value = myChart.getYDataValueAt(pen,1);

The accessor methods are "one based", indicating that the tag # and data point # start with a value of one (1), not zero (0).