PUT CONTAINER (CHANNEL)
Place data in a named channel container.
Description
PUT CONTAINER (CHANNEL) places data in a container associated with a specified channel.
The container is identified by name.
The channel that owns the container can be identified explicitly, by specifying the CHANNEL option, or implicitly, by omitting the CHANNEL option. When this option is omitted, the current channel is implied. If there is no current channel, the command is assumed to be an EXEC CICS® PUT CONTAINER (BTS) command. For more information, see PUT CONTAINER (BTS).
If the named container does not exist, it is created. If the named container exists, its previous contents are overwritten, unless you specify the APPEND option. If the named channel does not exist, it is created.
There is no limit to the number of containers that can be associated with a channel. The size of individual containers is limited only by the amount of storage available.
Options
- APPEND
- Specifies that the data passed to the container is appended to the existing data in the container. If this option is not stated, the existing data in the container is overwritten by the data passed to the container.
- CHANNEL(data-value)
- Specifies the name (1–16 characters) of
the channel that owns the container. 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.
Channel names are always in EBCDIC. The set of allowed characters for channel names, as listed earlier, 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 _.
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.
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 transaction. For more information, see Channels and containers.
- CONTAINER(data-value)
- Specifies the name (1–16 characters)
of the container into which data is placed.
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.
Do not use container names that begin with DFH, unless requested to do so by CICS.
Container names are always in EBCDIC. The set of allowed characters for container names, as listed earlier, includes some characters that do not have the same representation in all EBCDIC code pages. Therefore, if containers are to be shipped between regions, it is advisable to restrict the characters used to name themto A-Z 0-9 & : = , ; < > . - and _.
- DATATYPE(cvda)
- Specifies
the type of data to put into the container. This option applies only
to new containers. If the container exists, its data type was established
when it was created and cannot be changed. CVDA values are:
- BIT
- Bit data. The data in the container cannot be converted. This is the default value, unless FROMCCSID is specified.
- CHAR
- Character data. The data to store in the container is converted
(if required) according to the setting in the FROMCCSID or FROMCODEPAGE
value. If the FROMCCSID and FROMCODEPAGE options are not specified,
it is assumed that the data is encoded in the CCSID of the region,
as specified in the LOCALCCSID system initialization
parameter.
All the data in a container is converted as if it were a single character string. For SBCS code pages, a structure consisting of several character fields is equivalent to a single-byte character string. However, for DBCS code pages this is not the case. If you use DBCS code pages, you must put each character string into a separate container to ensure that data conversion works correctly.
- FLENGTH(data-value)
- Specifies, as a fullword binary value, the length of the data area from which data is read.
- FROM(data-area)
- Specifies the data area from which the data is written to the container.
- FROMCCSID(data-value)
- Specifies the current Coded Character
Set Identifier (CCSID) of the character data to put into the container,
as a fullword binary number. If you prefer to specify an IANA name
for the code page, or if you prefer to specify the CCSID as alphanumeric
characters, use the FROMCODEPAGE option instead. Use this option if
the data to place in the container is not encoded in the CCSID of
the region, as specified in the LOCALCCSID system initialization parameter.
If the FROMCCSID option is specified, DATATYPE(DFHVALUE(CHAR)) is implied.
- FROMCODEPAGE(data-value)
- Specifies an IANA-registered alphanumeric
charset name or a Coded Character Set Identifier (CCSID) for the current
code page of the character data to put into the container, using up
to 40 alphanumeric characters, including appropriate punctuation.
Use this option instead of the CCSID option if you prefer to use an
IANA-registered charset name, as specified in the Content-Type header
for an HTTP request. CICS converts
the IANA name into a CCSID, and the subsequent data conversion process
is identical. Also use this option if you prefer to specify the CCSID
in alphanumeric characters, rather than as a fullword binary number.
If the FROMCODEPAGE option is specified, DATATYPE(DFHVALUE(CHAR)) is implied.
Conditions
- 123 CCSIDERR
- RESP2 values:
- 1
- The CCSID specified on the FROMCCSID option is outside the range of valid CCSID values.
- 2
- The CCSID specified on the FROMCCSID option and the CCSID of the container are an unsupported combination. The CCSID of the container is the value that was specified, or defaulted, on the first PUT CONTAINER command for this container. The first time each invalid combination is used, CICS issues error message DFHAP0802, which contains the pair of CCSIDs.
- 4
- One or more characters could not be converted. Each unconverted character has been replaced by a blank in the converted data.
- 5
- There was an internal error in the code page conversion of a container. This error can occur only when the target of the PUT is an existing, CICS-created container.
- 122 CHANNELERR
- RESP2 values:
- 1
- The name specified on the CHANNEL option contains an illegal character or combination of characters.
- 3
- Either the current channel or the channel specified on the CHANNEL option is read-only.
- 125 CODEPAGEERR
- RESP2 values:
- 1
- The code page specified on the FROMCODEPAGE option is not supported.
- 2
- The code page specified on the FROMCODEPAGE option and the CCSID of the container are an unsupported combination. The CCSID of the container is the value that was specified using either FROMCODEPAGE or FROMCCSID, or defaulted, on the first PUT CONTAINER command for this container. The first time each invalid combination is used, CICS issues error message DFHAP0802, which contains the pair of CCSIDs.
- 4
- One or more characters could not be converted. Each unconverted character has been replaced by a blank in the converted data. This error can occur only when the target of the PUT is an existing container.
- 5
- There was an internal error in the code page conversion of a container. This error can occur only when the target of the PUT is an existing, CICS-created container.
- 110 CONTAINERERR
- RESP2 values:
- 18
- The name specified on the CONTAINER option contains an illegal
character or combination of characters.Note: This occurrence might happen if the CHANNEL attribute is not set, and that there is no default CHANNEL. The command might be interpreted as PUT CONTAINER (BTS), and be validated according to the BTS naming rules.
- 16 INVREQ
- RESP2 values:
- 1
- The DATATYPE option was specified without the CHANNEL option, and there is no current channel (because the program that issued the command was not passed one.) DATATYPE is valid only on PUT CONTAINER commands that specify (explicitly or implicitly) a channel.
- 2
- The FROMCCSID option was specified without the CHANNEL option, and there is no current channel (because the program that issued the command was not passed one.) FROMCCSID is valid only on PUT CONTAINER commands that specify (explicitly or implicitly) a channel.
- 4
- The CHANNEL option 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 tried to write to a CICS-defined read only container.
- 32
- A CVDA value other than CHAR or BIT was specified for DATATYPE.
- 33
- An attempt was made to change the data-type of an existing container.
- 34
- A data-type of BIT is invalid with a CCSID.
- 22 LENGERR
- RESP2 values:
- 1
- A negative number was specified on the FLENGTH option.