COPY

Copy resource table records.

Read syntax diagramSkip visual syntax diagramCOPYFROM( cpsm-token)TO( cpsm-token)ALLCURRENTFILTER(cpsm-token)MARKEDNOTFILTER(cpsm-token)NOTMARKEDCOUNT(data-ref)REPLACEADDUPDATETHREAD(cpsm-token) RESPONSE(data-ref )REASON(data-ref )

Description

This command copies some or all of the resource table records in one result set to another result set on the same processin thread.
  • The COPY command always begins processing with the last record that was fetched, rather than the next one in the result set.
  • The target result set can be an existing result set or a new one that is created by this process. If you specify an existing result set as the target, you can either overwrite the existing records or add to them.
  • A result set can contain only one record for a given resource. If duplicate records are found during the copy process, the ADD, REPLACE or UPDATE option you specified determines which record is retained.
  • To copy selected records from a source result set, you can use:
    • The SPECIFY FILTER command to define a filter for the source result set.
    • The MARK and UNMARK commands to mark records in the source result set. Any marks you place on records in the source result set are not retained when those records are copied to the target result set.
  • The relative position of records in the target result set may not be the same as it was in the source result set. The position can be affected by:
    • Deleted records being left in the source result set (when COPY ALL is specified) and other records assuming their position in the target result set.
    • The sort order associated with the target result set, if any. If the target result set does not exist, records are copied in the same order as they appeared in the source result set. If an existing result set is named as the target, records are copied and then sorted according to the sort order that was in effect for that result set.

Related commands

DELETE, DISCARD, GET, GETDEF, LOCATE, MARK, ORDER, PERFORM OBJECT, QUERY, SPECIFY FILTER

Options

ADD
Adds the resource table records from the source result set to an existing target result set. If duplicate records are found, the record in the target result set is retained.

If no existing result set is specified as the target, the ADD option is ignored.

ALL
Copies all the resource table records in the source result set to the target result set.

Any records that have been deleted from the source result set are not copied. In effect, the ALL option compresses a result set by leaving deleted records in the source result set and copying the remaining records to a new result set.

COUNT(data-ref)
Names a variable to receive the number of resource table records in the target result set after the copy process is complete.
CURRENT
Copies only the current resource table record in the source result set to the target result set.
FILTER(cpsm-token)
Identifies a filter to be used for this operation. The FILTER option copies only those resource table records that meet the specified filter criteria.

The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.

FROM(cpsm-token)
Identifies the source result set for this operation. The result set can be one produced by any of these commands:
  • COPY
  • GET
  • GETDEF
  • PERFORM OBJECT.
MARKED
Copies only those resource table records that are marked in the source result set. You can mark resource table records by using the MARK and UNMARK commands.
NOTFILTER(cpsm-token)
Identifies a filter to be used for this operation. The NOTFILTER option copies only those resource table records that do not meet the specified filter criteria.

The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.

NOTMARKED
Copies only those resource table records that are not marked in the source result set. You can mark resource table records by using the MARK and UNMARK commands.
REASON(data-ref)
Names a variable to receive the fullword reason value returned by this command.
REPLACE
Deletes the resource table records in an existing target result set and replaces them with the results of this copy operation. If the copy operation does not result in any resource table records being copied, the target result set is discarded.

If no existing result set is specified as the target, the REPLACE option is ignored.

RESPONSE(data-ref)
Names a variable to receive the fullword response value returned by this command.
THREAD(cpsm-token)
Identifies the API thread to be used for this operation. The cpsm-token value that identifies a thread is returned by the CONNECT command.
TO(cpsm-token)
Identifies the target result set for this operation. The result set can be one produced by any of these commands:
  • COPY
  • GET
  • GETDEF
  • PERFORM OBJECT.
Note: The target result set cannot be the same as the source result set that you specified on the FROM option.
If this field is:
  • Set to binary zero (in COBOL, C, PL/I or Assembler)
  • An uninitialized variable (in REXX).
CICSPlex SM creates a new result set and returns its identifying token in the same field.
UPDATE
Updates an existing target result set with resource table records from the source result set. If duplicate records are found, the record in the source result set replaces the record in the target result set.

If no existing result set is specified as the target, the UPDATE option is ignored.

Conditions

The following is a list of the RESPONSE values that can be returned by the COPY command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.
OK
The command completed processing successfully.
NODATA
No records were found that matched the specified search criteria.
BUSY
A busy condition occurred for one of the following reasons:
FROM
The source result set specified on the FROM option is being processed by another command.
TO
The target result set specified on the TO option is being processed by another command. This condition can occur if you specified the same result set on the FROM and TO options.
ENVIRONERROR
An environment error occurred for one of the following reasons:
NOSERVICE
The application stub program could not load the API service module.
NOSTORAGE
The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
SOCRESOURCE
A required resource that is owned by the CMAS is not available.
FAILED
The command failed for one of the following reasons:
ABENDED
Command processing abended.
EXCEPTION
Command processing encountered an exceptional condition.
INCOMPATIBLE
An incompatible condition occurred for one of the following reasons:
INVALIDOBJ
The target result set specified on the TO option is not compatible with the source result set specified on the FROM option. The result sets must contain the same type of resource table records.
INVALIDPARM
An invalid parameter was detected. The parameter that is invalid is returned as the reason value:
  • FILTER
  • FROM
  • NOTFILTER
  • THREAD
  • TO.
Check the command description for valid parameter syntax.
NOTAVAILABLE
A not available condition occurred for one of the following reasons:
APITASK
The API control subtask is not active.
CPSMAPI
The CMAS to which the processing thread is connected is not available for API processing.
SERVERGONE
The CMAS to which the processing thread was connected is no longer active.
VERSIONINVL
A version conflict occurred for one of the following reasons:
NOTSUPPORTED
The version of the application stub program used for this command is not supported.
NOTVSNCONN
The version of the application stub program used for this command is not the same as the version used with the CONNECT command.