COPY-TEMP-TABLE( ) method

Copies a source temp-table object to a target temp-table object. Either of the temp-tables (source or target) may be a member of a ProDataSet object. The AVM empties the target temp-table of all records before copying the source temp-table, by default.

Return type:

LOGICAL

Applies to:

Temp-table object handle

 

Syntax 

targ-tt-handle:COPY-TEMP-TABLE ( src-tt-handle [ , append-mode   [ , replace-mode [ , loose-copy-mode [ , name prefix ] ] ] ] )

targ-tt-handle

The handle to the target temp-table object to receive the copy.

src-tt-handle

The handle to the source temp-table object from which to copy records to the temp-table object on which you call this method.

append-mode

An optional logical expression where TRUE indicates that the AVM copy the temp-table object in an append mode.

When TRUE, the AVM appends the source temp-table object to the target temp-table object. If there is a unique index on the target temp-table and the AVM finds a row with a duplicate key, it does not replace the row. If there is not a unique index on the target temp-table, the AVM appends the data row from the source temp-table to the target temp-table, which might result in duplicate rows. If this operation results in duplicate rows, the AVM does not generate a run-time error.

Note:

In this mode, the AVM treats duplicate temp-table rows during the copy operation in the same way it treats duplicate temp-table rows during a fill operation in MERGE mode.

When you are certain a temp-table object does not contain duplicate rows, copying the object in append mode is more efficient than copying it in replace mode.

When FALSE, the AVM does not append records in the target temp-table object. The default value is FALSE.

The AVM ignores this expression when replace-mode is TRUE.

replace-mode

An optional logical expression where TRUE indicates that the AVM copy the temp-table object in a replace mode.

When TRUE, the AVM replaces records in the target temp-table object with corresponding records from the source temp-table object. The target temp-table must have a unique primary index that the AVM can use to find the corresponding record. When the corresponding record is found in the target temp-table, the AVM replaces the target record with the source record. When the corresponding record is not found in the target temp-table, the AVM creates a new target record using the source record. If the before-image table associated with the target temp-table contains a row for the target record, the row is left in place.

Copying a temp-table object in replace mode is less efficient than copying it in append mode. When you are certain a temp-table object does not contain duplicate rows, copy the object in append mode.

When FALSE, the AVM does not replace records in the target temp-table object. The default value is FALSE.

loose-copy-mode

An optional logical expression where TRUE indicates that the AVM copy the temp-table object in a loose-copy mode. That is, it relaxes the requirement that the metaschema for the source and target temp-tables be the same.

When TRUE, the AVM copies the source temp-table object to the target temp-table object based on a field mapping between the source and target temp-table buffers. If there is an attached data source with a field mapping, the AVM uses that field mapping to copy fields from the source temp-table buffer to its target temp-table buffer. If there are fields in either buffer that do not exist in the other, they are ignored. If there is no field mapping with the attached data source, or there is no attached data source, the AVM copies only those fields with the same name that appear in both the source and target temp-table metaschema.

When FALSE, the metaschema for the source and target temp-tables must be the same or the AVM generates a run-time error. The default value is FALSE.

name-prefix

An optional character expression used as the prefix for naming the target temp-table. If the parameter is not passed, or is passed as the Unknown value (?), the AVM uses the default "cpy" prefix. If the parameter is passed as an empty string "", then no prefix is added and the target temp-table will have the same name as the source.

If the source temp-table object has a before-image table that contains changed row data, the AVM generates a run-time error.

When the AVM copies a temp-table object in any mode, except loose-copy mode, and the target temp-table object is in a PREPARED state (that is, it has a metaschema), the source temp-table object metaschema must be the same. Each column in the source temp-table must match the target temp-table in position, data type, and extent. If the source temp-table object metaschema is not the same, the AVM generates a run-time error. If the target temp-table object is not in a PREPARED state (that is, it has no metaschema), the AVM copies the source temp-table object including its metaschema.

If the target temp-table object is a member of a ProDataSet object, the AVM does not track changes to the data in that temp-table (it ignores the TRACKING-CHANGES attribute setting during the copy operation).

Note:

If the source or target (but not both) temp-table has any before-table records, you can use COPY-TEMP-TABLE on that temp-table. However, if append mode or replace mode is specified and the target temp-table has any before-table records, the AVM generates a run-time error.

See also:

FILL-MODE attribute, COPY-DATASET( ) method