MOVE CONTAINER (CHANNEL)

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

MOVE CONTAINER (CHANNEL)

Read syntax diagramSkip visual syntax diagramMOVECONTAINER( data-value)AS( data-value)CHANNEL( data-value)TOCHANNEL( data-value)

Conditions: CHANNELERR, CONTAINERERR, INVREQ

This command is threadsafe.

Description

MOVE CONTAINER (CHANNEL) 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 can be identified:
  • Explicitly, by specifying the CHANNEL option.
  • Implicitly, by omitting the CHANNEL option. If this is omitted, the current channel is implied.
Similarly, the channel that owns the target container can be identified:
  • Explicitly, by specifying the TOCHANNEL option.
  • Implicitly, by omitting the TOCHANNEL option. If this is omitted, the current channel is implied.
You can move a container:
  • From one channel to another.
  • Within the same channel—for example, from the current channel to the current 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:
  1. The source channel must be within the scope of the program that issues the MOVE CONTAINER command.
  2. If the target channel does not exist, within the scope of the program that issues the MOVE CONTAINER command, it is created.
  3. If the source container does not exist, an error occurs.
  4. If the target container does not already exist, it is created. If the target container already exists, its previous contents are overwritten.
  5. 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 either omit both the CHANNEL and TOCHANNEL options or give them the same value, so that the same channel is specified, the source container is not changed and not 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. We therefore recommend 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. If this option is not specified, the current channel is implied.
CONTAINER(data-value)
Specifies the name (1–16 characters) of the source container that is to be moved.
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. We therefore recommend that, if channels are to be shipped between regions, the characters used in naming them should be restricted 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.

If this option is not specified, the current channel is implied.

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
Either the current channel or the channel specified on the CHANNEL option is read-only.
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:
4
The CHANNEL or TOCHANNEL option (or both) was not specified, there is no current channel (because the program that issued the command was not passed one), and the command was issued outside the scope of a currently-active BTS activity.
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.