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.

Controls

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataWindowChild object, DataStore object
Web ActiveX	DataWindow control, DataWindowChild object

Syntax

[PowerBuilder]

long <span>dwcontrol</span>.<span>ImportFile</span> ( {saveastype <span>importtype</span>}, string <span>filename </span>{, long <span>startrow </span>{, long <span>endrow</span> {, long <span>startcolumn</span> {, long <span>endcolumn </span>{, long <span>dwstartcolumn</span> } } } } } )

1	long <span>dwcontrol</span>.<span>ImportFile</span> ( {saveastype <span>importtype</span>}, string <span>filename </span>{, long <span>startrow </span>{, long <span>endrow</span> {, long <span>startcolumn</span> {, long <span>endcolumn </span>{, long <span>dwstartcolumn</span> } } } } } )

[Web ActiveX]

number <span>dwcontrol</span>.<span>ImportFile</span> ( number <span>importtype</span>, string <span>string</span>, number <span>startrow</span>, number<span> endrow</span>, number <span>startcolumn,</span> number <span>endcolumn</span>, number <span>dwstartcolumn</span> )

1	number <span>dwcontrol</span>.<span>ImportFile</span> ( number <span>importtype</span>, string <span>string</span>, number <span>startrow</span>, number<span> endrow</span>, number <span>startcolumn,</span> number <span>endcolumn</span>, number <span>dwstartcolumn</span> )

Argument	Description
dwcontrol	A reference to a DataWindow control or DataStore
importtype (optional for PowerBuilder)	An enumerated value of the SaveAsType DataWindow constant or a number representing that value (see SaveAsType). If this argument is specified, the filename argument can be specified without an extension. Valid type arguments for ImportFile are: Text! CSV! XML! DBase2! DBase3!
filename	A string whose value is the name of the file from which you want to copy data. The file must be an ASCII, tab-separated file (TXT) or a comma-separated file (CSV), Extensible Markup Language file (XML), or dBase format 2 or 3 file (DBF). Specify the file’s full name. If the optional importtype is not specified, the name must end in the appropriate extension. If filename is an empty string, or if it is null, ImportFile displays the File Open dialog box and allows the user to select a file. The remaining arguments are ignored.
startrow (optional for PowerBuilder)	The number of the first detail row in the file 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 for PowerBuilder)	The number of the last detail row in the file 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 for PowerBuilder)	The number of the first column in the file 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.
endcolumn (optional for PowerBuilder)	The number of the last column in the file that you want to copy. The default is the rest of the columns. For default XML import, if endcolumn is supplied and is smaller than N, where N is the DataWindow row size, import skips the last (N – endcolumn) elements in each row. This argument has no effect on template XML import.
dwstartcolumn (optional for PowerBuilder)	The number of the first column in the DataWindow control or DataStore that should receive data. The default is 1. This argument is supported for default and template XML import.

Events

ImportFile may trigger an ItemError event.

Return Values

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.

<span>dwstartcolumn</span> + (<span>endcolumn</span> - <span>startcolumn</span>)

1	<span>dwstartcolumn</span> + (<span>endcolumn</span> - <span>startcolumn</span>)

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:

Table 9-6: Examples of strings 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 empty
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:

dw_employee.<span>ImportFile</span>("D:TMPEMPLOYEE.CSV")

1	dw_employee.<span>ImportFile</span>("D:TMPEMPLOYEE.CSV")

This statement inserts all the data in the file D:TMPEMPLOYEE.XML into
dw_employee starting at the first column:

dw_employee.<span>ImportFile</span>(XML!,"D:TMPEMPLOYEE")

1	dw_employee.<span>ImportFile</span>(XML!,"D:TMPEMPLOYEE")

The following statements are equivalent. Both import
the contents of the XML file named myxmldata:

dw_control.ImportFile("myxmldata.xml")<br>dw_control.ImportFile(XML!, "myxmldata")

1	dw_control.ImportFile("myxmldata.xml")<br>dw_control.ImportFile(XML!, "myxmldata")

This statement imports rows 1 to 200 of employee.xml,
ignoring any template mappings before column 5:

dw_employee.ImportFile(XML!,"D:TMPEMPLOYEE.XML", 1, 200, 0, 0, 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:

dw_employee.<span>ImportFile</span>("D:TMPEMPLOYEE.TXT", &amp;<br>&#160;&#160;&#160;2, 30, 3, 8, 5)

1	dw_employee.<span>ImportFile</span>("D:TMPEMPLOYEE.TXT", &<br>   2, 30, 3, 8, 5)

ImportFile – PB Docs 150