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

Return-type: LOGICAL

Applies to: Buffer object handle

Syntax

BUFFER-IMPORT( [ stream-handle [ , delimiter [ , except-list 
               [ , no-lobs ] ] ] ] )
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). The default value is the Unknown value (?), which means that the method uses the current unnamed stream (opened via the INPUT FROM 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.
except-list
A CHARACTER expression that evaluates to a comma-separated list of field names to be excluded from the import. The default value is the Unknown value (?), where no fields are excluded. Field names in except-list that do not match a field in the table are ignored.
no-lobs
A LOGICAL expression indicating whether to ignore BLOB and CLOB fields in the import. If TRUE, BLOB and CLOB fields are ignored during the operation. If FALSE, BLOB and CLOB fields are imported along with the other fields. The default value is FALSE (that is, BLOB and CLOB fields are included in the operation).

Example

This example shows how you can read data back to the Customer table dynamically:
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().
    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.
  • Like the EXPORT and IMPORT statements, RECID fields are not automatically included for database tables for BUFFER-EXPORT() and BUFFER-IMPORT(). However, you can explicitly reference them in BUFFER-EXPORT-FIELDS() and BUFFER-IMPORT-FIELDS().
  • For temp-table fields, fields of type ROWID or Progress.Lang.Object are not allowed. You must exclude any fields of those types via the except-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 except-list has an element of an array field (for example, field-name[1]). You can only exclude the field as a whole and not given elements in the array field.
    • the user does not have write access to the database table.
    • a transaction is not active, if importing data into a database table.
    • a temp-table contains a ROWID or Progress.Lang.Object field and the fields are not excluded.
    • an error occurs when updating a record field.
  • The BUFFER-IMPORT() 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. The order of the fields imported is the order of the fields in the table definition. 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.
  • For BUFFER-IMPORT(), set the no-lobs parameter to YES to ignore large object data when importing records that contain BLOB or CLOB fields. More specifically:
    • When you import an exported record into a new record, and the BLOB or CLOB field of the exported record contains either the Unknown value (?) or a filename, the AVM sets the value of the BLOB or CLOB field in the newly imported record to the Unknown value (?); the AVM does not create any object data.
    • When you import an exported record as an update to an existing record, and the BLOB or CLOB field of the exported record contains either the Unknown value (?) or a filename, the AVM does not change the value of the BLOB or CLOB field in the existing record and neither creates nor overwrites object data.
  • The BUFFER-IMPORT() 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 BUFFER-IMPORT() method 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() 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() 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() 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-EXPORT-FIELDS( ) method, BUFFER-IMPORT-FIELDS( ) method, EXPORT statement, IMPORT statement, INPUT FROM statement