PUT64 CONTAINER
Place data from 64-bit storage in a named channel container. This command is for use only in non-Language Environment® (LE) AMODE(64) assembler language application programs. CICS® business transaction services (BTS) containers are not supported.
Description
PUT64 CONTAINER places data from 64-bit storage in a container that is 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 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 that is 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 fewer 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 that are used to name them to 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 as follows:
- 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 that consists 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-area64)
- Specifies a 64-bit data area reference to an area from which the data is written to the container. data-area64 refers to an area that is referenced by a 64-bit pointer and that can be in 64-bit (above-the-bar) storage.
- 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 FROMCCSID 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 is 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 invalid 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 is 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 invalid character or combination of characters.
- 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 and there is no current channel (because the program that issued the command was not passed one).
- 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.