ImportString

method (DataWindows)

Description

Inserts data into a DataWindow control or DataStore from
tab-separated, comma-separated, or XML data in a string.

Applies to

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

Syntax

PowerBuilder

long dwcontrol.ImportString ( {saveastype importtype}, string string {, long startrow {, long endrow {,long startcolumn {, long endcolumn {, long dwstartcolumn } } } } } )

1	long dwcontrol.ImportString ( {saveastype importtype}, string string {, long startrow {, long endrow {,long startcolumn {, long endcolumn {, long dwstartcolumn } } } } } )

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 string or number representing that value (see SaveAsType). 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 for PowerBuilder)

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 for PowerBuilder)

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 for
PowerBuilder)

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.

endcolumn (optional for PowerBuilder)

The number of the last column in the string 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

ImportString may trigger an ItemError event.

Return value

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 string

-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

-13 — Unsupported DataWindow style for import

-14 — Error resolving DataWindow nesting

Usage

All the arguments of this function except string are optional. You
do not need to specify the importtype argument.

The string must be formatted in tab-separated or comma-separated
columns or in XML. For TXT and CSV files, the format of the string is the
same as if the data came from an ASCII file, and each line must end with a
carriage return and a newline character (~r~n). If the string has four
tab-separated columns, one line might look like for a tab-separated
string:

col1_data~t col2_data~t col3_data~t col4_data~r~n

1	col1_data~t col2_data~t col3_data~t col4_data~r~n

For a DataWindow control or DataStore, the string should consist of
rows of data. If the data 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
string.

The startcolumn and endcolumn arguments control the number of
columns imported from the string 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.

dwstartcolumn + ( endcolumn - startcolumn )

1	dwstartcolumn + ( endcolumn - startcolumn )

If string data to be assigned to a single row and column has
multiple lines (indicated by line-ending characters in the import string),
you must quote the string data using ~”. Do not use single quotes.

This example of a valid tab-separated import string assigns
multiline values to each row in column 2:

ls_s = &amp;
      "1~t~"Mickey~r~nMinnie~r~nGoofy~" ~r~n" + &amp;
      "2~t~"Susan~r~nMary~r~nMarie~" ~r~n" + &amp;
      "3~t~"Chris~r~nBen~r~nMike~" ~r~n" + &amp;
      "4~t~"Mott~r~nBarber~r~nPicard~" "

ls_s = &

"1~t~"Mickey~r~nMinnie~r~nGoofy~" ~r~n" + &

"2~t~"Susan~r~nMary~r~nMarie~" ~r~n" + &

"3~t~"Chris~r~nBen~r~nMike~" ~r~n" + &

"4~t~"Mott~r~nBarber~r~nPicard~" "

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.

ImportString does not support Crosstab DataWindow objects.

Examples

These statements copy all data in the string ls_Emp_Data to the
DataWindow control dw_employee starting at the first column:

string ls_Emp_Data
ls_Emp_Data = . . .
dw_employee.ImportString(ls_Emp_Data)

string ls_Emp_Data

ls_Emp_Data = . . .

dw_employee.ImportString(ls_Emp_Data)

This statement stores data in the string ls_Text and imports it into
the DataWindow dw_employee. The DataWindow is a report of department 100
and start and end dates of personnel. The string includes the department
number and other information, which is not imported. ImportString imports
rows 2 through 10 and columns 2 through 5 in the string to the DataWindow
beginning in column 2. The result is 9 rows added to the DataWindow with
data in columns 5 through 8:

string ls_text
 
ls_text = "Dept~tLName~tFName~tStart" &amp; 
      + "~tEnd~tAmount~tOutcome ~r~n"
ls_text = ls_text + &amp;
      "100~tJones~tMary~tApr88~tJul94~t40~tG~r~n"
ls_text = ls_text + &amp;
      "100~tMarsh~tMarsha~tApr89~tJan92~t35~tG~r~n"
ls_text = ls_text + &amp;
      "100~tJames~tHarry~tAug88~tMar93~t22~tM~r~n"
...
ls_text = ls_text + &amp;
      "100~tWorth~tFrank~tSep87~tJun94~t55~tE~r~n"
 
dw_employee.ImportString(ls_text, 2, 10, 2, 5, 5)

string ls_text

ls_text = "Dept~tLName~tFName~tStart" &

+ "~tEnd~tAmount~tOutcome ~r~n"

ls_text = ls_text + &

"100~tJones~tMary~tApr88~tJul94~t40~tG~r~n"

ls_text = ls_text + &

"100~tMarsh~tMarsha~tApr89~tJan92~t35~tG~r~n"

ls_text = ls_text + &

"100~tJames~tHarry~tAug88~tMar93~t22~tM~r~n"

...

ls_text = ls_text + &

"100~tWorth~tFrank~tSep87~tJun94~t55~tE~r~n"

dw_employee.ImportString(ls_text, 2, 10, 2, 5, 5)

This statement imports rows 1 to 200 of the data in the XML string
ls_emp, ignoring any template mappings before column 5:

dw_employee.ImportString(ls_emp, 1, 200, 0, 0, 5)

1	dw_employee.ImportString(ls_emp, 1, 200, 0, 0, 5)

See also

ImportClipboard

ImportFile

Document get from Powerbuilder help

Thank you for watching.

Powerbuilder Documentation 2019

August 21, 2023

Was this article helpful?

Connection Information

ImportString – PB Docs 2019

ImportString

method (DataWindows)

My Website Links