Description
Inserts data into a DataWindow control, DataStore object, or graph control from tab-separated, comma-separated, or XML data in a string. The way data is arranged in the string in tab-delimited columns depends on whether the target is a DataWindow (or DataStore) or a graph, and on the type of graph.
For DataWindow and DataStore syntax, see the ImportString method for DataWindows in the section called “ImportString” in DataWindow Reference.
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
graphname.ImportString ( { importtype}, string {, startrow {, endrow {, startcolumn } } } )
|
Argument |
Description |
|---|---|
|
graphname |
The name of the graph control to which you want to copy data from the specified string. |
|
importtype (optional) |
A value of the SaveAsType enumerated datatype specifying the format of the imported string. Valid type arguments are: Text! CSV! XML! If you want to generate an XML trace file, the XML! argument is required. |
|
string |
A string from which you want to copy the data. The string should contain tab-separated or comma-separated columns or XML with one row per line (see Usage). |
|
startrow (optional) |
The number of the first detail row in the string that you want to copy. The default is 1. For default XML import, if startrow is supplied, the first N (startrow -1) elements are skipped, where N is the DataWindow row size. For template XML import, if startrow is supplied, the first (startrow -1) occurrences of the repetitive row mapping defined in the template are skipped. |
|
endrow (optional) |
The number of the last detail row in the string that you want to copy. The default is the rest of the rows. For default XML import, if endrow is supplied, import stops when N * endrow elements have been imported, where N is the DataWindow row size. For template XML import, if endrow is supplied, import stops after endrow occurrences of the repetitive row mapping defined in the template have been imported. |
|
startcolumn (optional) |
The number of the first column in the string that you want to copy. The default is 1. For default XML import, if startcolumn is supplied, import skips the first (startcolumn - 1) elements in each row. This argument has no effect on template XML import. |
Return value
Returns the number of data points that were imported if it succeeds and one of the following negative integers if an error occurs:
-1 -- No rows or startrow value supplied is greater than the number of rows in the string
-2 -- Empty string or input data does not match number of columns or required column type
-3 -- Invalid argument
-4 -- Invalid input
-11 -- XML Parsing Error; XML parser libraries not found or XML not well formed
-12 -- XML Template does not exist or does not match the DataWindow
If any argument's value is null, ImportString returns null. If the optional importtype argument is specified and is not a valid type, ImportString returns -3.
Usage
For graph controls, ImportString only uses three columns on each line and ignores other columns. The three columns must contain information that depends on the type of graph:
-
For all graph types except scatter, the first column to be imported is the series name, the second column contains the category, and the third column contains the data.
-
For scatter graphs, the first column to be imported is the series name, the second column is the data's x value, and the third column is the y value.
You can add data to more than one series by specifying different series names in the first column.
Examples
These statements copy the data from the string ls_Text starting with row 2 column 3 and ending with row 30 column 5 to the graph gr_employee:
string ls_Text ls_Text = . . . gr_employee.ImportString(ls_Text, 2, 30, 3)
The following script stores data for two series in the string ls_gr and imports the data into the graph gr_custbalance. The categories in the data are A, B, and C:
string ls_gr ls_gr = "series1~tA~t12~r~n" ls_gr = ls_gr + "series1~tB~t13~r~n" ls_gr = ls_gr + "series1~tC~t14~r~n" ls_gr = ls_gr + "series2~tA~t15~r~n" ls_gr = ls_gr + "series2~tB~t14~r~n" ls_gr = ls_gr + "series2~tC~t12.5~r~n" gr_custbalance.ImportString(ls_gr, 1)
See also
