Syntax 1: for Graph controls
Description
Inserts data into a DataWindow control, DataStore object, or graph
control from data in a file. The data can be tab-separated text,
comma-separated text, XML, or dBase format 2 or 3. The format of the
file 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 ImportFile method for
DataWindows in the section called “ImportFile” 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
|
1 |
graphname.ImportFile ( { importtype}, filename {, startrow {, endrow {, startcolumn } } } ) |
|
Argument |
Description |
|---|---|
|
graphname |
The name of the graph control to which you want to copy |
|
importtype (optional) |
An enumerated value of the SaveAsType DataWindow Text! CSV! XML! DBase2! DBase3! |
|
filename |
A string whose value is the name of the file from which If filename is an empty string or if it is null, |
|
startrow (optional) |
The number of the first detail row in the file that you For default XML import, if startrow is supplied, the For template XML import, if startrow is supplied, the |
|
endrow (optional) |
The number of the last detail row in the file that you For default XML import, if endrow is supplied, import For template XML import, if endrow is supplied, import |
|
startcolumn (optional) |
The number of the first column in the file that you want For default XML import, if startcolumn is supplied, This argument has no effect on template XML |
Return value
Long. Returns the number of rows 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 file
-2 — Empty file or input data does not match number of columns or
required column type
-3 — Invalid argument
-4 — Invalid input
-5 — Could not open the file
-6 — Could not close the file
-7 — Error reading the text
-8 — Unsupported file name suffix (must be *.txt, *.csv, *.dbf or
*.xml)
-10 — Unsupported dBase file format (not version 2 or 3)
-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
-15 — File size exceeds limit
If any argument’s value is null, ImportFile returns null. If the
optional importtype argument is specified and is not a valid type,
ImportFile returns -3.
Usage
The format of the file can be indicated by specifying the optional
importtype parameter, or by including the appropriate file
extension.
For graph controls, ImportFile only uses three columns and ignores
other columns. Each row of data must contain three pieces of
information. The information 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. To let users select the file to
import, specify a null string for filename. PowerBuilder displays the
Select Import File dialog box.
Double quotes
The location and number of double quote marks in a field in a tab
delimited file affect how they are handled when the file is imported. If
a string is enclosed in one pair of double quotes, the quotes are
discarded. If it is enclosed in three pairs of double quotes, one pair
is retained when the string is imported. If the string is enclosed in
two pairs of double quotes, the first pair is considered to enclose a
null string, and the rest of the string is discarded.
When there is a double quote at the beginning of a string, any
characters after the second double quote are discarded. If there is no
second double quote, the tab character delimiting the fields is not
recognized as a field separator and all characters up to the next
occurrence of a double quote, including a carriage return, are
considered to be part of the string. A validation error is generated if
the combined strings exceed the length of the first string.
Double quotes after the first character in the string are rendered
literally. Here are some examples of how tab-delimited strings are
imported into a two-column DataWindow:
|
Text in file |
Result |
|---|---|
|
“Joe” TAB “Donaldson” |
Joe Donaldson |
|
Bernice TAB “””Ramakrishnan””” |
Bernice “Ramakrishnan” |
|
“”Mary”” TAB “”Li”” |
Empty cells |
|
“Mich”ael TAB “””Lopes””” |
Mich “Lopes” |
|
“Amy TAB Doherty” |
Amy<TAB>Doherty in first cell, second cell |
|
3″”” TAB 4″ |
3″”” 4″ |
Specifying a null string for file name
If you specify a null string for filename, the remaining
arguments are ignored. All the rows and columns in the file are
imported.
Examples
This statement copies all the data in the file D:EMPLOYEE.TXT to
gr_employee starting at the first row:
|
1 |
gr_employee.ImportFile("D:EMPLOYEE.TXT") |
This statement copies the data from the file D:EMPLOYEE.TXT
starting with row 2 column 3 and ending with row 30 column 5 to the
graph gr_employee:
|
1 |
gr_employee.ImportFile("D:EMPLOYEE.TXT", 2, 30, 3) |
The following statements are equivalent. Both import the contents
of the XML file named myxmldata:
|
1 2 |
gr_control.ImportFile(myxmldata.xml) gr_control.ImportFile(XML!, myxmldata) |
This example causes PowerBuilder to display the Specify Import
File dialog box:
|
1 2 3 |
string null_str SetNull(null_str) dw_main.ImportFile(null_str) |
See also