Release 10.1A: OpenEdge Development:
ProDataSets

> ## COPY-DATASET and COPY-TEMP-TABLE methods

> 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 section, you’ll learn about two additional Progress 4GL 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. For example:

> 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 DATASET` `target-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.

> `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, so that 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.

> If the source ProDataSet has any before-tables that have any rows in them, you cannot use `COPY-DATASET` on that ProDataSet. It would not be appropriate to copy and duplicate this transactional data, which is presumably waiting to be committed back to its Data-Source. Since it would also not be appropriate to copy the ProDataSet and silently omit this data, it’s simply not allowed. If you need to copy after-tables from one ProDataSet to another at a time when the before-tables have data in them, you can use the `COPY-TEMP-TABLE` method.

> `COPY-DATASET` has four additional positional, optional arguments. The `replace-mode`, `loose-copy-mode` and `current-only` options are `LOGICAL` datatypes, and the `pairs-list` option is a character expression. The full syntax of `COPY-DATASET` is. For example:

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

> The `COPY-TEMP-TABLE` method works similarly for individual temp-tables, as shown:

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

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

> ##### The replace-mode argument

> The `replace-mode` option defaults to `FALSE`. If `replace-mode` is `TRUE`, Progress tries to find the corresponding row in the target table, through the target’s unique primary index. If a corresponding row is not found in the target table, Progress uses the source row to create a new target row. If Progress finds the row in the target, it copies the source row values into that row. If the target row has a `BEFORE-TABLE` row, that row is left in place. There must be a unique primary index on each target member table in order for the `replace-mode` option to be used.

> When `replace-mode` is `TRUE`, it does not matter if `append-mode` is `TRUE` or `FALSE`. The target table is not emptied prior to the copy operation.

> ##### The loose-copy-mode argument

> By default, pairs of source and target temp-tables being copied by the `COPY-DATASET` or `COPY-TEMP-TABLE` method must have compatible definitions. The `loose-copy-mode` option overrides this default.

> For the `COPY-DATASET` method, if `loose-copy-mode` is `TRUE`, the parameter applies to each temp-table buffer in the ProDataSet. Thus, the remainder of this paragraph applies to both the `COPY-DATASET` and `COPY-TEMP-TABLE` methods. If `loose-copy-mode` is `TRUE` for a temp-table buffer, Progress effectively performs a `BUFFER-COPY` from source to target. `BUFFER-COPY` is more flexible than the default behavior of `COPY-TEMP-TABLE` or `COPY-DATASET` because it matches each source field to its corresponding field in the target by name, and ignores fields that do not match, without error. This is somewhat more expensive than the default behavior of `COPY-DATASET` and `COPY-TEMP-TABLE`, which assumes compatible definitions field-for-field between source and target. When `loose-copy-mode` is `TRUE`, Progress checks for an existing field-mapping between the two buffers specified in a previous `ATTACH-DATA-SOURCE` operation. If the source temp-table is in fact the Data-Source for the target, then its field-mapping is used to match up field pairs with differing names, just as for `BUFFER-COPY`. If there is no `ATTACH-DATA-SOURCE` between the two buffers, the copy is done by matching field names and only copying those fields that appear in both source and target. As with `BUFFER-COPY`, different field order and missing fields do not prevent the method from succeeding. There is also no requirement that indexes on the two temp-tables be identical.

> ##### The pairs-list argument

> The `pairs-list` argument only applies to `COPY-DATASET`. The `pairs-list` is a comma-separated list of target and source tables to be copied, such as: `targetT1,sourceT1,targetT2,sourceT2`. If the `pairs-list` is present, the copy is done between only those member tables given in the `pairs-list`, by matching target and source table names. If the `pairs-list` is not given, the tables are copied in the order in which they were defined or added in the two ProDataSets.

> If one ProDataSet has more tables than the other, the extra unpaired tables are ignored. In other words, you can use `COPY-DATASET` without the `pairs-list` option to copy one ProDataSet to another, even when one ProDataSet has more tables than the other, as long as the tables to be copied have the same relative positions within the ProDataSet structure. This is the same as the order in which the tables would be returned by the `GET-BUFFER-HANDLE (i)` method.

> If the tables to be copied are not in the same relative order, then you must specify the `pairs-list` option to tell Progress which source tables go with which targets. If the source and target tables don’t match up in their relative order within their respective ProDataSets, you must specify the `pairs-list` even if the table names are the same.

> For example, given a source ProDataSet with temp-tables `T1`, `T2`, and `T3`, and a target ProDataSet with just tables `T1` and `T3`, you must define the `pairs-list` option to be `T1,T1,T3,T3`, because the relative position of `T3` in the two ProDataSets is not the same, even though the table names are the same. It is also worth noting that for static temp-table definitions, it is not possible for the source and target temp-tables to have the same name anyway, since each static name defines a single unique instance with that name.

> ##### The current-only argument

> The `current-only` argument also applies only to `COPY-DATASET`. If `current-only` is present and is `TRUE`, it tells Progress to copy only the current buffer contents of each source ProDataSet buffer to the target ProDataSet. This option can be useful in situations where the business logic needs to deal with a modified row and its parent (and possibly grand-parent, etc.) without using any other rows. The `current-only` option is a way of getting this minimal set of data to pass to such an operation. Note that you might need to set the `AUTO-SYNCHRONIZE` attribute to `TRUE` or execute the `SYNCHRONIZE( )` method to ensure that the contents of each buffer are what is needed. Since the usefulness of the `current-only` option is that it automatically copies a single row at multiple levels at once, it is supported only for `COPY-DATASET`. For a temp-table, you can use a single `BUFFER-COPY` statement or method to copy a single row.

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