EXEC CICS MOVE CONTAINER command (EXCI)

Move a container (and its contents) from one channel to another.

MOVE CONTAINER (EXCI)

Conditions: CHANNELERR, CONTAINERERR, INVREQ

Description

MOVE CONTAINER (EXCI) moves a container from one channel to another. After the move, the source container no longer exists.

The source and target containers are identified by name and by the channels that own them. The channel that owns the source container is identified by the CHANNEL option. The channel that owns the target container is identified by the TOCHANNEL option.

You can move a container:

From one channel to another
Within the same channel (This has the effect of renaming the container.)

You can use MOVE CONTAINER , instead of GET CONTAINER and PUT CONTAINER , as a more efficient way of transferring data between channels.

Note:

The source channel must be within the scope of the program that issues the MOVE CONTAINER command.
If the target channel does not exist, within the scope of the program that issues the MOVE CONTAINER command, it is created.
If the source container does not exist, an error occurs.
If the target container does not already exist, it is created. If the target container already exists, its previous contents are overwritten.
If you try to overwrite a container with itself, nothing happens. That is, if you specify the same value for the CONTAINER and AS options and specify the same value for the CHANNEL and TOCHANNEL options, so that the same channel is specified, the source container is not changed nor deleted. No error condition is raised.

Options

AS(data-value)

Specifies the name (1–16 characters) of the target container. If the target container already exists, its contents are overwritten.

The acceptable characters are A-Z a-z 0-9 $ @ # / % & ? ! : | " = ¬ , ; < > . - and _. Leading and embedded blank characters are not permitted. If the name supplied is less than 16 characters, it is padded with trailing blanks up to 16 characters.

Container names are always in EBCDIC. The allowable set of characters for container names, listed above, includes some characters that do not have the same representation in all EBCDIC code pages. Therefore, it is recommended that, if containers are to be shipped between regions, the characters used in naming them should be restricted to A-Z a-z 0-9 & : = , ; < > . - and _.

CHANNEL(data-value)

Specifies the name (1–16 characters) of the channel that owns the source container. You can specify the channel name DFHTRANSACTION to use the transaction channel.

CONTAINER(data-value)

Specifies the name (1–16 characters) of the source container that is to be moved.

RETCODE(data-area)

Specifies a 20-byte area into which the external CICS interface places return information. This area is formatted into five 1–word fields. This command will return information in the first two words. These words will contain the RESP and RESP2 codes. The other three words will be set to nulls.

RESP: The primary response code, which indicates whether the external CICS interface MOVE CONTAINER command caused an exception condition during its execution.
RESP2: The secondary response code that further qualifies, where necessary, some of the conditions that are raised in the RESP parameter.

TOCHANNEL(data-value)

Specifies the name (1–16 characters) of the channel that owns the target container. If you are specifying a new channel, remember that the acceptable characters are A-Z a-z 0-9 $ @ # / % & ? ! : | " = ¬ , ; < > . - and _. Leading and embedded blank characters are not permitted. If the name supplied is less than 16 characters, it is padded with trailing blanks up to 16 characters. If the channel does not exist, it is created. This new channel remains in scope until the link level changes. For more information about channel scope, see The scope of a channel.

Channel names are always in EBCDIC. The allowable set of characters for channel names, listed above, includes some characters that do not have the same representation in all EBCDIC code pages. Therefore, if channels are to be shipped between regions, it is advisable to restrict the characters that are used to name them to A-Z a-z 0-9 & : = , ; < > . - and _.

You can specify the channel name DFHTRANSACTION to use a transaction channel. A transaction channel does not go out of scope when the link level changes: it is always accessible in the task. For more information, see Channels and containers.

Conditions

122 CHANNELERR

RESP2 values:

1: The name specified on the TOCHANNEL option contains an illegal character or combination of characters.
2: The channel specified on the CHANNEL option could not be found.
3: The channel specified on the CHANNEL option is read-only.
904: XCEIP ESTAE invoked.

110 CONTAINERERR

RESP2 values:

10: The container named on the CONTAINER option could not be found.
18: The name specified on the AS option contains an illegal character or combination of characters.

16 INVREQ

RESP2 values:

30: You cannot move a CICS-defined read-only container.
31: You cannot move a container to (that is, overwrite) an existing, CICS-defined, read-only container.