Syntax

So far this example has shown you how to append additional data to a single ProDataSet, and to control which parts of it get filled in at different times. In this topic, you will learn about two additional ABL methods that can assist you when you need to copy or combine data in other ways.

The COPY-DATASET method copies all the data in one ProDataSet to another, with this syntax:

target-dataset-handle:COPY-DATASET(source-dataset-handle [, append-mode ]).

The source-dataset-handle must be the handle of an existing static or dynamic ProDataSet. The target-dataset-handle can be the handle of another static or dynamic ProDataSet with the same temp-table and Data-Relation structure. It can also be a newly created dynamic ProDataSet with only a handle and no structure, that is, the result of executing the statement CREATE DATASETtarget-dataset-handle.

If the target-dataset has no structure, the table and Data-Relation structure of the source-dataset is copied to it along with the data. In this case the dynamic target ProDataSet is not given a name, but its temp-tables and their buffers are given the name "cpy_" plus the name of the temp-table or buffer in the source ProDataSet. This naming scheme can be overridden with your own prefix using the optional name-prefix argument, which is discussed in the .

COPY-DATASET copies the temp-tables from source to target in the order that they were defined or added in the two ProDataSets. As soon as it encounters a pair that do not have compatible table definitions, it puts out an error message and terminates the operation. As with other operations, two temp-table definitions are considered compatible if they contain the same number of fields with matching datatypes and extents for each field. Whether the field names are identical in the two tables does not matter. If either the source or target ProDataSet has an extra temp-table or temp-tables at the end of the ProDataSet, the COPY-DATASET succeeds because the unpaired tables are ignored.

By default, the tables in the target ProDataSet are emptied at the start of the COPY-DATASET operation. The end result is that the target ProDataSet temp-tables have the same rows as in the source ProDataSet. If you instead want to merge the data in the two ProDataSets, you include the optional second merge-flag parameter on the method call. If this logical parameter is present and evaluates to true, then data from the source ProDataSet temp-tables is merged into the target temp-tables according to the rules of the "MERGE" value for a temp-table buffer's FILL-MODE during a FILL. That is, rows from the two corresponding tables in each pair are combined so that the target ends up with all the rows that were in either the source or target at the start. If there is a unique index on the target temp-table, all rows from the source that violate that index constraint are silently eliminated during the COPY-DATASET operation, so that the target winds up with only one row for each index value. Note that there is no interleaving of data in related tables as it is copied from the source ProDataSet to the target. Each temp-table is copied individually in its entirety, starting at the top of the ProDataSet hierarchy. If duplicate rows are eliminated from a parent table in the course of the copy, this has no effect on the related rows in any child table.

COPY-DATASET has five additional positional, optional arguments. The replace-mode, loose-copy-mode and current-only options are LOGICAL datatypes, and the pairs-list and name-prefix options are character expressions. The full syntax of COPY-DATASET is:

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

The COPY-TEMP-TABLE method works similarly for individual temp-tables. This is the syntax for COPY-TEMP-TABLE:

target-table-handle:COPY-TEMP-TABLE(source-table-handle [ , append-mode ] 
  [ , replace-mode ] [ , loose-copy-mode ] [ , name-prefix ]).

You can use the COPY-TEMP-TABLE method on any source or target temp-table, whether it is part of a ProDataSet or not. Therefore you can use this method to copy individual temp-tables from one ProDataSet to another, or for other temp-tables having nothing to do with ProDataSets.

As with COPY-DATASET, by default the target temp-table is emptied at the start of the operation. The rules for temp-table compatibility, the use of the optional merge-flag, and so on, are the same as for COPY-DATASET.