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.

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

source-buffer-handle

An expression that evaluates to the source buffer handle.

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

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.

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).

Caution: Using this option can create the potential for errors in your data and lead to inappropriate results. Therefore, before using this option, you must understand the nature of your data and be sure that logic using this option will not result in inconsistent or out-of-date data in the database.

When copying buffers in a ProDataSet object, the AVM 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, the AVM 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 (?), the AVM 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, the AVM 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, the AVM 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, the AVM 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.

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


bh:BUFFER-COPY(BUFFER Customer:HANDLE, ?, "cust-sales-rep,SalesRep").