Reads a line from an input file that might have been created by the EXPORT statement or the BUFFER-EXPORT-FIELDS() method. Returns TRUE if the import is successful.

Return-type: LOGICAL

Applies to: Buffer object handle

Syntax

BUFFER-IMPORT-FIELDS( stream-handle , delimiter , field-list )
stream-handle
A HANDLE expression that resolves to the handle of a named stream (defined via the DEFINE STREAM statement. The handle is a STREAM-HANDLE object). If the Unknown value (?) is specified, the method uses the current unnamed stream (opened via the OUTPUT TO statement).
delimiter
A CHARACTER expression that evaluates to a single character to be used as the delimiter between field values. The default is a space character. A multi-byte character is allowed. If you specify more than one character, ABL uses the first character as the delimiter.
field-list
A CHARACTER expression that evaluates to a comma-separated list of field names to be imported. field-list cannot resolve to the Unknown value (?) as an actual field list is required. The method raises an error if the table does not contain one of the provided field names.

One or more array elements may be specified in the list (for example myfield[1]). If you specify an array field name without a subscript, the whole array field is processed. An error is raised if you provide a subscript for a non-array field.

Example

This example shows how to use BUFFER-IMPORT-FIELDS() to import four fields into the Customer table:
VAR HANDLE hBuffer.

CREATE BUFFER hBuffer FOR TABLE "Customer".

INPUT FROM VALUE(hBuffer:NAME + ".d").

DO TRANSACTION:
  REPEAT ON ENDKEY UNDO, LEAVE:
    hBuffer:BUFFER-CREATE().
    hBuffer:BUFFER-IMPORT-FIELDS(?, ?, "Name,Country,State,City").
    hBuffer:BUFFER-RELEASE().        
  END.
END.

INPUT CLOSE.

DELETE OBJECT hBuffer.

Notes

  • The method may be called on a buffer object, whether the record is for a database table or a temp-table.
  • The method cannot be part of a multi-assignment statement. If it is, the compiler raises an error.
  • When working with a database table, a transaction must be active at the time of the method call.
  • For temp-table fields, fields of type ROWID or Progress.Lang.Object are not allowed. You must not include any fields of those types in the field-list parameter for the method to work.
  • The method raises an error if:
    • a stream-handle is provided and it’s not a valid handle to a named stream or is not open for reading.
    • the user does not have write access to the database table.
    • a transaction is not active, if importing data into a database table.
    • a ROWID or Progress.Lang.Object field is included in the list.
    • an error occurs when updating a record field.
  • The BUFFER-IMPORT-FIELDS() method must follow a statement that redirects the input source (INPUT FROM statement). You cannot read data from the screen.
  • The data in the input stream must be in a standard format to be read back into ABL. You must enclose all character fields in quotes ("") if they contain any delimiter characters. If you want to import any quotes contained in the data, replace them with two quotes (""). You must display the Unknown value (?) as an unquoted question mark.
  • If an input data line contains an unquoted hyphen in place of a data value, then the corresponding field is skipped, as it is in UPDATE. If you specify a hyphen (-) as the delimiter character, all hyphens are treated as delimiters.
  • A period (.) on a line by itself is treated as an end-of-file indicator. The ENDKEY is applied, but the file or stream remains open for input.
  • When importing records that contain a BLOB or CLOB field, the AVM uses the value stored in the BLOB or CLOB field of the exported record to determine whether or not the exported record has an associated object data file to import. If the BLOB or CLOB field in the exported record contains the Unknown value (?), the AVM stores the Unknown value (?) in the BLOB or CLOB field of the new or updated record. If the BLOB or CLOB field in the exported record contains a filename, the AVM imports the associated object data. If an updated record already has object data associated with it, the AVM deletes that object data before importing the new object data. The AVM raises the ERROR condition if an object data file cannot be found or read.
  • The BUFFER-IMPORT-FIELDS() method reads large object data files from the directory specified as the input data source in the INPUT FROM statement, by default. You can use the LOB-DIR option on the INPUT FROM statement to specify the directory from which the import reads BLOB and CLOB data files.
  • The method is sensitive to the Date Format (-d), Century (-yy), and European Numeric Format (-E) parameters. When loading data with the IMPORT statement, BUFFER-IMPORT() method, or BUFFER-IMPORT-FIELDS() method, use the same settings that you used with the export statement/methods.
  • For DATETIME and DATETIME-TZ data, the data format must be fixed and must conform to the ISO 8601 standard for date/time representations (YYYY-MM-DDTHH:MM:SS.SSS+HH:MM). For DATETIME, there is no time zone offset.
  • ABL interprets the null character as a data field terminator. This can cause unexpected behavior if a complete record was not read before the null character was encountered, because BUFFER-IMPORT-FIELDS() reads the next line to populate any buffer fields that were not read. Progress strongly discourages the importing of data containing null characters.
  • BUFFER-IMPORT-FIELDS() requires a newline character after the last line in the file for the line to be imported. Otherwise, the line is not imported. Note that data exported via the BUFFER-EXPORT-FIELDS() method does have a new line character at the end of each exported record.
  • When importing a CLOB field, the AVM uses the code page embedded in the filename of the clobfile.blb to determine the clob's code page.
  • When values are imported, any ASSIGN triggers for the field changed execute after all fields are imported into the given record.
  • For more information, see Export and import data dynamically using buffers in Develop ABL Applications.

See also

BUFFER-EXPORT( ) method, BUFFER-IMPORT( ) method, BUFFER-EXPORT-FIELDS( ) method, EXPORT statement, IMPORT statement, INPUT FROM statement