COPY-DATASET( ) method

Copies a source ProDataSet object to a target ProDataSet object. By default, the AVM empties the target ProDataSet object temp-tables of all records before copying the source ProDataSet object.

Return type:

LOGICAL

Applies to:

ProDataSet object handle

This is the syntax to invoke this method:

 

Syntax 

targ-dataset-handle:COPY-DATASET ( src-dataset-handle [ , append-mode   [ , replace-mode [ , loose-copy-mode [ , pairs-list [ , current-only   [ , name-prefix ] ] ] ] ] ] )

targ-dataset-handle

The handle to the target ProDataSet object to receive the copy.

src-dataset-handle

The handle to the source ProDataSet object from which to copy temp-table records to the target ProDataSet object on which you execute the method.

append-mode

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

When TRUE, the AVM appends the source ProDataSet temp-tables to the target ProDataSet temp-tables. If there is a unique index on a 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 the ProDataSet temp-tables do not contain duplicate rows, copying the ProDataSet object in append mode is more efficient than copying it in replace mode.

When FALSE, the AVM does not append records in the target ProDataSet temp-tables. 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 ProDataSet object temp-tables in a replace mode.

When TRUE, the AVM replaces records in the target ProDataSet object temp-tables with corresponding records from the source ProDataSet temp-tables. The target temp-table must have a unique primary index that the AVM can use to find the corresponding records. When a corresponding record is found in the target temp-table, the AVM replaces the target record with the source record. When a 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 ProDataSet object temp-tables in replace mode is less efficient than copying them in append mode. When you are certain the ProDataSet object temp-tables do not contain duplicate rows, copy the ProDataSet object in append mode.

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

loose-copy-mode

An optional logical expression where TRUE indicates that the AVM copy the ProDataSet object temp-tables 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 each temp-table in the source ProDataSet object to the target ProDataSet 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 each 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 metaschemas.

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.

pairs-list

An optional character expression that evaluates to a comma-delimited list of the target and source temp-table pairs to be copied. Following is the pairs-list syntax:

 

"target-table1,source-table1[,target-table2,source-table2]..."

If specified, the AVM copies only the listed temp-tables by matching the target and source temp-table names.

If not specified, the AVM copies all the temp-tables in the order they were defined or added in the ProDataSets. If either the source or target ProDataSet has one or more extra temp-tables at the end, the extra temp-tables are ignored.

current-only

An optional logical expression where TRUE indicates that the AVM copy only the current record from each temp-table at each level in the source ProDataSet object to the target ProDataSet object. The default value is FALSE.

Note:

You might need to synchronize the buffers to ensure they are the related buffers. Once you have read a record into a top-level buffer, you can synchronize the related buffers by calling the SYNCHRONIZE( ) method.

To copy the current record from a single temp-table, you can use the BUFFER-COPY statement or BUFFER-COPY( ) method.

name-prefix

An optional character expression used as the prefix for naming the target ProDataSet. 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 ProDataSet will have the same name as the source.

When the AVM copies the source ProDataSet object, it copies each temp-table in its entirety and in the order in which the temp-table was defined. That is, it does not copy the temp-tables in an interleaved and nested manner based on their data relations. If either the source or target ProDataSet has one or more extra temp-tables at the end, the extra temp-tables are ignored.

When the AVM copies a ProDataSet object in any mode, except loose-copy mode, and the target ProDataSet object has a metaschema (that is, temp-table and relation definitions), the source ProDataSet object metaschema must be the same. If the source and target ProDataSet object metaschema is not the same, the AVM generates a run-time error. If the target ProDataSet object is a newly created dynamic object with only a handle and no metaschema, the AVM copies the source ProDataSet object including its metaschema.

Note:

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

See also:

ATTACH-DATA-SOURCE( ) method, FILL-MODE attribute, COPY-TEMP-TABLE( ) method