ImportFile

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 DataWindow Reference or the online Help.

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.ImportFile (  { importtype}, filename {, startrow {, endrow {, startcolumn } } } )

Argument	Description
graphname	The name of the graph control to which you want to copy data from the specified file.
importtype (optional)	An enumerated value of the SaveAsType DataWindow constant. If this argument is specified, the importtype 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), comma-separated file (CSV), Extensible ), 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 you do not specify filename or if it is null, ImportFile prompts the user for a file name. The remaining arguments are ignored.
startrow (optional)	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)	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)	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.

Returns

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

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 empty
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

Example 1

This statement copies all the data in the file D:\EMPLOYEE.TXT to gr_employee starting at the first row:

gr_employee.ImportFile("D:\EMPLOYEE.TXT")

Example 2

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:

gr_employee.ImportFile("D:\EMPLOYEE.TXT", 2, 30, 3)

Example 3

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

gr_control.ImportFile(myxmldata.xml)
gr_control.ImportFile(XML!, myxmldata)

Example 4

This example causes PowerBuilder to display the Specify Import File dialog box:

string null_str

SetNull(null_str)

dw_main.ImportFile(null_str)