InsertData PowerScript function
Description
Inserts a data point in a series of a graph. You can specify
the category for the data point or its position in the series. Does
not apply to scatter graphs.
Controls
Graph controls in windows and user objects. Does not apply
to graphs within DataWindow objects, because their data comes directly
from the DataWindow.
Syntax
|
1 |
<span>controlname</span>.<span>InsertData</span> ( <span>seriesnumber</span>, <span>datapoint</span>, <span>datavalue <br></span> {, <span>categoryvalue</span> } ) |
|
Argument |
Description |
|---|---|
|
controlname |
The name of the graph in which you want |
|
seriesnumber |
The number that identifies the series |
|
datapoint |
The number of the data point before which |
|
datavalue |
The value of the data point you want |
|
categoryvalue (optional) |
The category for this data value on the |
Return Values
Integer. Returns the number of the data value if it succeeds
and -1 if an error occurs. If any argument’s value is null,
InsertData returns null.
Usage
When you specify datapoint without specifying categoryvalue, InsertData inserts
the data point in the category at that position, shifting existing
data points to the following categories. The shift may cause there
to be uncategorized data points at the end of the axis.
When you specify categoryvalue, InsertData ignores
the position in datapoint and puts the data
point in the specified category, replacing any data value that is
already there. If the category does not exist, InsertData creates
the category at the end of the axis.
To modify the value of a data point at a specified position,
use ModifyData.
Scatter graphs
To add data to a scatter graph, use Syntax 2 of AddData.
Equivalent syntax
If you want to add a data point to the end of a series or
to an existing category in a series, you can use AddData instead,
which requires fewer arguments.
InsertData and ModifyData behave
differently when you specify datapoint to indicate
a position for inserting or modifying data. However, they behave
the same as AddData when you specify a position
of 0 and a category. All three modify the value of a data point
when the category already exists. All three insert a category with
a data value at the end of the axis when the category does not exist.
When you specify a position as well as a category, and that
category already exists, InsertData ignores the
position and modifies the data of the specified category, but ModifyData changes
the category label at that position.
This statement:
|
1 |
gr_data.InsertData(1, 0, 44, "Qty") |
is equivalent to:
|
1 |
gr_data.ModifyData(1, 0, 44, "Qty") |
and is also equivalent to:
|
1 |
gr_data.AddData(1, 44, "Qty") |
When you specify a position, the following statements are
not equivalent:
-
InsertData ignores
the position and modifies the data value of the Qty category:1gr_data.InsertData(1, 4, 44, "Qty") -
ModifyData changes the category
label and the data value at position 4:1gr_data.ModifyData(1, 4, 44, "Qty")
Examples
Assuming the category label Jan does not already
exist, these statements insert a data value in the series named
Costs before the data point for Mar and assign the data point the
category label Jan in the graph gr_product_data:
|
1 |
integer SeriesNbr, CategoryNbr |
|
1 |
|
1 |
// Get the numbers of the series and category. |
|
1 |
SeriesNbr = gr_product_data.FindSeries("Costs") |
|
1 |
CategoryNbr = gr_product_data.FindCategory("Mar") |
|
1 |
gr_product_data.<span>InsertData</span>(SeriesNbr, & |
|
1 |
CategoryNbr, 1250, "Jan") |
These statements insert the data value 1250 after
the data value for Apr in the series named Revenues in the graph gr_product_data.
The data is inserted in the category after Apr, and the rest of
the data, if any, moves over a category:
|
1 |
integer SeriesNbr, CategoryNbr |
|
1 |
|
1 |
// Get the number of the series and category. |
|
1 |
CategoryNbr = gr_product_data.FindCategory("Apr") |
|
1 |
SeriesNbr = gr_product_data.FindSeries("Revenues") |
|
1 |
|
1 |
gr_product_data.<span>InsertData</span>(SeriesNbr, & |
|
1 |
CategoryNbr + 1, 1250) |