copy, copy-clear

action

Syntax
copy  shelf-name to shelf-name

OR

copy-clear  shelf-name to shelf-name


Purpose

You can use copy to copy the entire contents of one shelf to another. The contents of the destination shelf are removed and replaced with the contents of the source shelf.

You can use copy-clear to copy the entire contents of one shelf to another. The contents of the destination shelf are removed and replaced with the contents of the source shelf. The contents of the source shelf are removed.

Both the source and destination shelves must be of the same data type. In the case of shelves of a record type, you may also copy a shelf of an extended record type to a shelf of the type it extends.

Because the destination shelf will become the same size as the source shelf, it must be either variable size or the same size as the source shelf. If the destination shelf was declared variable with a maximum size, the maximum size must be equal to or greater than the current size of the source shelf.

For copy-clear the source shelf must be of variable size. Fixed sized shelves cannot be cleared.

When stream shelves are copied using copy, all streams on the source shelf must either be unattached or attached to buffers and closed. When you use copy-clear, however, streams on the source shelf may be attached and open and will remain attached an open on the destination shelf.

All open streams on the destination shelf will automatically be discarded before the copy action takes place.

This example copies all the items of the integer shelf "reference-counts" to "saved-reference-counts". After the copy, "saved-reference-counts" has the same number of items as "reference-counts", and each item in "saved-reference-counts" has the same value and key as its corresponding item in "reference-counts". 

  global integer reference-counts
  process
     local integer saved-reference-counts
     copy reference-counts to saved-reference-counts

copy does not copy the values of a shelf of records but the references to these records. After the copy both shelves reference the same set of records.