Converts data from the buffer object to a standard character format and writes it to the current output destination or to a named output stream. Only fields specified in the field list are included and they are written in the order specified. You can use data exported to a file in standard format as input to other ABL procedures.

The method returns TRUE if at least one field was exported from the record, and FALSE if no fields were exported

Return-type: LOGICAL

Applies to: Buffer object handle

Syntax

BUFFER-EXPORT-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 exported. 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-EXPORT-FIELDS() to export four fields from the Customer table.
VAR HANDLE hBuffer.
VAR HANDLE hQuery.

CREATE BUFFER hBuffer FOR TABLE "Customer".

CREATE QUERY hQuery.
hQuery:SET-BUFFERS(hBuffer).
hQuery:QUERY-PREPARE("FOR EACH " + hBuffer:NAME).
hQuery:QUERY-OPEN().
hQuery:GET-FIRST().

OUTPUT TO VALUE(hBuffer:NAME + ".d").

DO WHILE NOT hQuery:QUERY-OFF-END:
  hBuffer:BUFFER-EXPORT-FIELDS(?, ?, "Name,Country,State,City").
  hQuery:GET-NEXT().
END.

OUTPUT CLOSE.

hQuery:QUERY-CLOSE().
DELETE OBJECT hQuery.
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.
  • 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 writing.
    • the user does not have read access to the database table.
    • a ROWID or Progress.Lang.Object field is included in the list.
    • an error occurs when reading a record field.
  • BUFFER-EXPORT-FIELDS() must follow an OUTPUT TO statement, which redirects the output destination. You cannot write data to the screen.
  • Other procedures can use the data exported with the BUFFER-EXPORT-FIELDS() method as input by reading the file with the INSERT, PROMPT-FOR, SET, UPDATE or IMPORT statements, or BUFFER-IMPORT() or BUFFER-IMPORT-FIELDS() methods.
  • The data is in a standard format to be read back into ABL. All character fields are enclosed in quotes ("") and quotes contained in the data you are exporting are replaced by two quotes (""). A single space separates one field from the next. An Unknown value (?) is displayed as an unquoted question mark (?).
  • There are no trailing blanks, leading zeros, or formatting characters (for example, dollar signs) in the data.
  • ABL exports logical fields as the value YES or NO.
  • When exporting a BLOB or CLOB field, the AVM creates a separate object data file with the code page embedded in the filename and with a file extension of .blb. The filename is stored in the BLOB or CLOB field of the exported record. (When importing records that contain a BLOB or CLOB field, the AVM uses this filename to locate the object data file associated with each record.) If the BLOB or CLOB field contains the Unknown value (?), the AVM stores the Unknown value (?) in the BLOB or CLOB field of the exported record and does not create an object data file. If the BLOB or CLOB field contains a zero-length object, the AVM creates a zero-length object data file. The AVM raises the ERROR condition if an object data file cannot be created.
  • The BUFFER-EXPORT-FIELDS() method creates large object data files in the directory specified as the output destination in the OUTPUT TO statement, by default. You can use the LOB-DIR option on the OUTPUT TO statement to specify the directory in which the BUFFER-EXPORT-FIELDS() method creates the BLOB and CLOB data files.
  • For DATETIME and DATETIME-TZ data, the data format is fixed and conforms 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.
  • If you specify the delimiter parameter with a delimiter other than a space character, you must specify the same delimiter character in a subsequent IMPORT statement, BUFFER-IMPORT() method, or BUFFER-IMPORT-FIELDS() method that loads the data.
  • 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 more information, see Export and import data dynamically using buffers in Develop ABL Applications.

See also

BUFFER-EXPORT( ) method, BUFFER-IMPORT( ) method, BUFFER-IMPORT-FIELDS( ) method, EXPORT statement, IMPORT statement, OUTPUT TO statement