ImportFile
method (DataWindows)
Description
Inserts data into a DataWindow control or DataStore from a file. The
data can be tab-separated text, comma-separated text, XML, or dBase format
2 or 3.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
Syntax
PowerBuilder
|
1 |
long dwcontrol.ImportFile ( {saveastype importtype}, string filename {, long startrow {, long endrow {, long startcolumn {, long endcolumn {, long dwstartcolumn } } } } } ) |
|
Argument |
Description |
|||||
|---|---|---|---|---|---|---|
|
dwcontrol |
A reference to a DataWindow control or |
|||||
|
importtype (optional for PowerBuilder) |
An enumerated value of the SaveAsType DataWindow
|
|||||
|
filename |
A string whose value is the name of the file from If filename is an empty string, or if it is |
|||||
|
startrow (optional for PowerBuilder) |
The number of the first detail row in the file that For default XML For template XML import, if startrow is |
|||||
|
endrow (optional for PowerBuilder) |
The number of the last detail row in the file that For default XML import, if endrow is supplied, For template XML import, |
|||||
|
startcolumn (optional for |
The number of the first column in the file that you For default XML This argument |
|||||
|
endcolumn (optional for PowerBuilder) |
The number of the last column in the file that you For default XML import, if endcolumn is This argument has no effect on template XML |
|||||
|
dwstartcolumn (optional for |
The number of the first column in the DataWindow |
Events
ImportFile may trigger an ItemError event.
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
-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
-13 — Unsupported DataWindow style for import
-14 — Error resolving DataWindow nesting
-15 — File size exceeds limit
Usage
The format of the file can be indicated by specifying the optional
importtype parameter, or by including the appropriate file
extension.
The file should consist of rows of data. If the file includes column
headings or row labels, set the startrow and startcolumn arguments to skip
them. The datatypes and order of the DataWindow object’s columns must
match the columns of data in the file.
The startcolumn and endcolumn arguments control the number of
columns imported from the file and the number of columns in the DataWindow
that are affected. The dwstartcolumn argument specifies the first
DataWindow column to be affected. The following formula calculates the
last DataWindow to be affected.
|
1 |
dwstartcolumn + (endcolumn - startcolumn) |
To let users select the file to import, specify a null string for
filename. PowerBuilder displays the Select Import File dialog box. A
drop-down list lets the user select the type of file to import.
Specifying a null string for filename
If you specify a null string for filename, the remaining arguments
are ignored. All the rows and columns in the file are imported.
Double quotes
The location and number of double quote marks in a field in a
tab-separated 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 or comma 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-separated 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 “””Mariam””” |
Mich “Mariam” |
|
“Amy TAB Doherty” |
Amy<TAB>Doherty in first cell, second cell |
|
3″”” TAB 4″ |
3″”” 4″ |
If an XML or CSV column contains a leading double quote, it is
assumed to be part of the column value. A leading double quote has to be
closed to mark the end of an item.
ImportFile does not support Crosstab DataWindow objects.
Examples
This statement inserts all the data in the file D:TMPEMPLOYEE.CSV
into dw_employee starting at the first column:
|
1 |
dw_employee.ImportFile("D:TMPEMPLOYEE.CSV") |
This statement inserts all the data in the file D:TMPEMPLOYEE.XML
into dw_employee starting at the first column:
|
1 |
dw_employee.ImportFile(XML!,"D:TMPEMPLOYEE") |
The following statements are equivalent. Both import the contents of
the XML file named myxmldata:
|
1 2 |
dw_control.ImportFile("myxmldata.xml") dw_control.ImportFile(XML!, "myxmldata") |
This statement imports rows 1 to 200 of employee.xml, ignoring any
template mappings before column 5:
|
1 |
dw_employee.ImportFile(XML!,"D:TMPEMPLOYEE.XML", 1, 200, 0, 0, 5) |
This statement inserts the data from the file D:TMPEMPLOYEE.TXT
into the DataWindow dw_employee. It copies rows 2 through 30 and columns 3
through 8 in the file to the DataWindow beginning in column 5. The result
is 29 rows added to the DataWindow with data in columns 5 through
10:
|
1 2 |
dw_employee.ImportFile("D:TMPEMPLOYEE.TXT", & 2, 30, 3, 8, 5) |
See also