EXEC CICS PUT CONTAINER command (EXCI)
Place data in a named channel container.
Description
PUT CONTAINER (EXCI) places data in a container associated with a specified channel.
The container is identified by name. The channel that owns the container is identified by the CHANNEL option.
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. Container data is held in 64-bit storage. The total amount of 64-bit storage available to an EXCI job is governed by MEMLIMIT , and the external CICS interface limits the total amount of container data to 5% of the MEMLIMIT value.
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. You can specify the channel name DFHTRANSACTION to use a transaction channel in CICS. For more information about using a transaction channel with EXCI, 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 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:
- 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 EXCI job
as specified in the
LOCALCCSID
parameter of DFHXCOPT.
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 EXCI job, as
specified in the
LOCALCCSID
parameter of DFHXCOPT.
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.
- 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 PUT 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.
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
- The channel specified on the CHANNEL option is read-only.
- 904
- XCEIP ESTAE invoked.
- 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.
- 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.