PlotXY

(Engine-Level Function)

Description: Displays a plot of a curve in the window given the X and Y values in two arrays.
Returns: Nothing
Usage: Steady State only.
Function Groups: Graphics
Related to: Plot | PlotBuff | Sort
Format: PlotXY(XArrayElem, YArrayElem, N, Left, Right, Top, Bottom, X1, Y1, X2, Y2, Style, Color)
< OR >
PlotXY(XArrayElem, YArrayElem, N, DataLimitLeft, DataLimitRight, DataLimitTop, DataLimitBottom, X1, Y1, X2, Y2, Pen, Reserved [, XORMode, Direction, DrawStepped, BitNumber, Average])

PlotXY takes the first parameter set or else detects that the Style parameter is a Pen, in which cast the second parameter set is used:
Parameters:  
XArrayElem
Required. Any array element giving the starting point in the array of X coordinates. The subscript for the array may be any numeric expression. If processing a multidimensional array, the usual rules apply to decide which dimension should be used.
YArrayElem
Required. Any array element giving the starting point in the array of Y coordinates. The subscript for the array may be any numeric expression. If processing a multidimensional array, the usual rules apply to decide which dimension should be used.
N
Required. Any numeric expression giving the number of array elements to plot starting at the element given by the first parameters. N must be greater than or equal to 0, and no greater than 16384.

If this parameter is greater than the dimension of the first array, the number of points plotted will be that array dimension.

If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed.
DataLimitLeft
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be less than Right but must not be equal to it. In the standard case, when this value is less than Right, it will define the minimum value to display from the array of X-values.
For example, if Left was 10, a data value of 10 would fall on the edge of the bounding box, on either X1, if the plot is vertical, or on Y1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box.
DataLimitRight
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than Left but must not be equal to it. In the standard case, when this value is greater than Left, it will define the maximum value to display from the array of X-values.
For example, if Right was 1000, a data value of 1000 would fall on the edge of the bounding box, on either X2, if the plot is vertical, or on Y2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box.
DataLimitTop
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be less than Bottom but must not be equal to it. In the standard case, when this value is less than Bottom, it will define the minimum value to display from the array of Y-values.
For example, if Top was 10, a data value of 10 would fall on the edge of the bounding box, on either Y1, if the plot is vertical, or on X1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box.
DataLimitBottom
Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than Top but must not be equal to it. In the standard case, when this value is greater than Top, it will define the maximum value to display from the array of Y-values.
For example, if Bottom was 1000, a data value of 1000 would fall on the edge of the bounding box, on either Y2, if the plot is vertical, or on X2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box.
X1 (Left)
Required. Any numeric expression giving the X coordinate on the screen of the left side of the plot area. This corresponds to the Left parameter for horizontal plots and to the Top parameter for vertical plots.
Y1 (Top)
Required. Any numeric expression giving the Y coordinate on the screen of the top side of the plot area. This corresponds to the Top parameter for horizontal plots and to the Left parameter for vertical plots.
X2 (Right)
Required. Any numeric expression giving the X coordinate on the screen of the side of the plot area opposite to X1. This corresponds to the Right parameter for horizontal plots and to the Bottom parameter for vertical plots.
Y2 (Bottom)
Required. Any numeric expression giving the Y coordinate on the screen of the side of the plot area opposite to Y1. This corresponds to the Bottom parameter for horizontal plots and to the Right parameter for vertical plots.
Style
Required. Any numeric expression giving the style of the plot - the line style, direction, bit number for bits plots, and the number of points to average per point displayed. If PlotXY senses that the Style parameter is a Pen, XORMode, DrawStepped, BitNumber, and Average parameters will become relevant. The Style is determined by adding together the following values.

Line style + Direction + Path + Bit number + Average

Line style is a number between 1 and 10 inclusive which gives the line style for line plots. A line style of 1 indicates a solid line. For other line styles, the background color is set to the current background screen color.
Direction is either 0 or 10. A 0 indicates a horizontal plot and a 10 indicates a vertical plot.
Path is either 0 or 50. A 0 indicates that line plots are to be drawn directly from point to point. A 50 indicates that plots are to be drawn in a step fashion with two line segments between each point. The first segment runs parallel to the X-axis and the second segment runs parallel to the Y-axis. This produces a square-looking plot. These step plots are useful for plotting status values which change in jumps rather than continuously.
Bit number is the number of the bit to use in the YArray data for plotting. If the normal entire value of the data is to be plotted, use 0 for this value. If only one of the bits from the data is to be plotted, use the bit number plus 1. The value to add is (Bit number + 1) * 100 or 0. The ability to plot only a single bit from an array of short or long values allows status data to be stored very efficiently by not requiring a separate array for each status value. For bit plots, the value plotted is always a 0 or a 1 corresponding to the value of the selected bit. The use of this plotting option is usually done in conjunction with a Path value of 50 for step plots.
Average is the number of consecutive array points to average to give a single point on the screen. Both XArray and YArray values are averaged. It can be used to plot a very large array of values on the screen without having to draw all of the points on the screen. This will produce a smoothed plot and reduce the drawing time. The number to add is (Data points per displayed point + 1) * 10000.
Color
Any numeric expression giving the VTScada Color Palette of the line and the foreground color for filled plots. If the number is less than 10000, the plot is non-destructive.

If the number is greater than or equal to 10000, the plot is destructive and the actual color used is Color - 10000.
Pen
The pen to be used (if any).
Reserved
Reserved has been allocated to permit the addition of a Brush parameter, should such a parameter become necessary in the future. Reserved can currently be any value or Invalid.
XORMode
An optional parameter specifying whether the plot is destructive (if destructive, the plot line won't be affected by the background color).
If set to 0 or Invalid (default), the destructive drawing mode will be used. If set to 1, the non-destructive or XOR drawing mode will be used.
Direction
An optional parameter specifying the horizontal or vertical direction for the plot. 0 or Invalid indicates horizontal, while 1 indicates vertical.
DrawStepped
An optional parameter specifying whether the plot is to be drawn from point-to-point, or stepped. 0 or Invalid indicates point-to-point, while 1 indicates stepped.
BitNumber
An optional parameter specifying the use of a whole value or a bit number. Invalid indicates a whole value should be used, while >=0 indicates that the specified bit number should be used.
Average
An optional parameter specifying whether consecutive points should be averaged to give a single point.
Invalid or 0 indicates that averaging should not be used, while >0 indicates that the number of consecutive points should be averaged to give a single point.
Comments:

This function is a layered graphics statement.
The PlotXY statement will execute timer functions during the plotting process. This will allow time critical functions such as driver I/O and data logging to continue running during the relatively long times it takes to update a plot on the screen.

Through the ordering of the Left, Right, Top, Bottom, X1, X2, Y1, and Y2 parameters, the plot may have 8 different orientations. The normal left to right orientation with the minimum at the bottom will have Left < Bottom, Top < Bottom, X1 < X2, and Y1 > Y2.

Exchanging either Left and Right (i.e. Left > Right) or X1 and X2 (i.e. X1 > X2), the plot will be from right to left. This means that the minimum X-value will be on the right rather than the left. Exchanging either Top and Bottom (i.e. Top > Bottom) or Y1 and Y2 (i.e. Y1 > Y2),will result in the plot will having its minimum Y-value at the top rather than the bottom.
PlotXY ignores invalid data elements in the arrays and leaves blank spaces for them on the display. If the X-values are not in order, the plot will appear as a scatter of lines. The Sort statement may be used to order the points in the arrays prior to plotting.

The plot area defined by X1, Y1, X2, and Y2 limits the area which can be plotted on the screen. Any points which fall outside this area will not appear on the screen but will be "clipped" at the boundary.

On a standard VTScada page, any Y value less than 40 will be hidden by the title bar.

Example:

Two arrays called speed and efficiency exist that each have 100 elements. The array called speed has values that range from 0 to 1800, while efficiency has values ranging from 0 to 100 (percent). A plot of speed against efficiency may be done with the following:

PlotXY(speed[0] { Starting element of X-values },
       efficiency[0] { Starting element of Y-values },
       100 { Number of elements to plot },
       0, 1800 { Low/high limits for speed },
       0, 100 { Low/high limits for efficiency },
       50, 550, 550, 50 { Bounding box for clipped area },
       1 { Solid line style, horizontal plot },
       0 { Plot is black });

This statement will result in a line plot of 100 data points in an area in the upper left corner of the window. The line will be horizontally orientated, solid in style and white in color.