Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## BUFFER-COPY( ) method

> This method copies any common fields, determined by name, data type, and extent-matching, from the source buffer to the receiving buffer. If there are fields in one buffer that do not exist in the other, they are ignored. This method is used to accommodate temp-tables of joins.

> Return type: LOGICAL

> Applies to: Buffer object handle

> Syntax
>     BUFFER-COPY( source-buffer-handle
>        [ , except-list [ , pairs-list [ , no-lobs ] ] ] )

> ``source-buffer-handle``

> An expression that evaluates to the source buffer handle.

> ``except-list``

> A character expression that evaluates to a comma-separated list of field names to be excluded from the copy.

> ``pairs-list``

> A character expression that evaluates to a comma-separated list of field-name pairs to be copied.

> You can also specify an array element as one or both of the fields. This lets you copy a field or array element from one buffer to a field or array element in the other buffer, when the two fields do not have the same name. The order within each field-name pair does not matter; each pair must contain one field name from the source and one field name from the target.

> You can also copy one entire array to another by specifying its name without a subscript.

> ``no-lobs``

> A logical expression indicating whether to ignore BLOB and CLOB fields in the copy. If TRUE, BLOB and CLOB fields are ignored during the copy. If FALSE, BLOB and CLOB fields are copied along with the other fields. The default value is FALSE (that is, BLOB and CLOB fields are included in the copy).

> The following example fragment copies the customer table to the buffer, `bh`, except that `customer.sales-rep` is copied to a field called `cust-sales-rep` in the buffer:

>     bh:BUFFER-COPY(buffer customer:handle,?,"cust-sales-rep,sales-rep").

> #### Note

> - When copying buffers in a ProDataSet object, Progress checks as to whether the BUFFER-COPY( ) method satisfies the following two requirements:

> - The copy is between a buffer on a Data-source object table and the corresponding ProDataSet temp-table buffer. This means the operation can use any buffer for the data source database table, but only the default buffer for the ProDataSet temp-table.
> - There are no `except-list` or `pairs-list` arguments for the BUFFER-COPY( ) method.

> If these two requirements are satisfied, the BUFFER-COPY( ) method identifies the fields to copy based on the `pairs-list` argument specified in the ATTACH-DATA-SOURCE( ) method for the Data-source object, if any, along with either the `except-list` or `include-list` arguments, if any. Because the ATTACH-DATA-SOURCE( ) method already allows you to define a field mapping between a Data-source object buffer and a ProDataSet temp-table buffer, as well as a list of fields to include or exclude from the operation, you do not need to specify these in the BUFFER-COPY( ) method.

> - When copying records that contain a BLOB or CLOB field, Progress copies the object data associated with the source record to the target record. If the BLOB or CLOB field in the source record contains the Unknown value (`?`), Progress stores the Unknown value (`?`) in the BLOB or CLOB field of the target record. If the target record already has object data associated with it, Progress deletes that object data before copying the new object data.

> - Use the `no-lobs` option with the BUFFER-COPY( ) method to ignore large object data when copying records that contain BLOB or CLOB fields. More specifically:

> - When you copy a source record to a new target record, Progress sets the value of the BLOB or CLOB field in the target record to the Unknown value (`?`).
> - When you copy a source record to an existing target record, Progress does not change the value of the BLOB or CLOB field in the existing target record.

> You can also use the `except-list` option to exclude BLOB and CLOB fields from the copy.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095