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.
Applies to
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 |
controlname.InsertData ( seriesnumber, datapoint, datavalue {, categoryvalue } ) |
|
Argument |
Description |
|---|---|
|
controlname |
The name of the graph in which you want to insert data |
|
seriesnumber |
The number that identifies the series in which you want to |
|
datapoint |
The number of the data point before which you want to |
|
datavalue |
The value of the data point you want to insert. |
|
categoryvalue (optional) |
The category for this data value on the category axis. The |
Return value
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 2 3 4 5 6 7 |
integer SeriesNbr, CategoryNbr // Get the numbers of the series and category. SeriesNbr = gr_product_data.FindSeries("Costs") CategoryNbr = gr_product_data.FindCategory("Mar") gr_product_data.InsertData(SeriesNbr, & 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 2 3 4 5 6 7 8 |
integer SeriesNbr, CategoryNbr // Get the number of the series and category. CategoryNbr = gr_product_data.FindCategory("Apr") SeriesNbr = gr_product_data.FindSeries("Revenues") gr_product_data.InsertData(SeriesNbr, & CategoryNbr + 1, 1250) |
See also