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.
PUT64 CONTAINER
>>-PUT64--CONTAINER(data-value)--+---------------------+-------->
'-CHANNEL(data-value)-'
>--FROM(data-area64)--+---------------------+------------------->
'-FLENGTH(data-value)-'
.-BIT------------.
>--+----------------+--+--------------------------+------------->
+-DATATYPE(cvda)-+ +-FROMCCSID(data-value)----+
'-CHAR-----------' '-FROMCODEPAGE(data-value)-'
>--+--------+--------------------------------------------------><
'-APPEND-'
Conditions: CCSIDERR, CHANNELERR, CODEPAGEERR, CONTAINERERR,
INVREQ, LENGERR
This command is threadsafe.
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.
CAUTION:
If you create
multiple large containers you might limit the amount of storage available
to other applications.
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
used to name them to A-Z a-z 0-9 & : = , ; < > . - and _.
- 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 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 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-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 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.
- 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.