Start of change

PUT CONTAINER (CHANNEL)

Place data in a named channel container.

Start of change
Read syntax diagramSkip visual syntax diagram
PUT CONTAINER (CHANNEL)

>>-PUT--CONTAINER(data-value)--+---------------------+---------->
                               '-CHANNEL(data-value)-'   

>--FROM(data-area)--+---------------------+--------------------->
                    '-FLENGTH(data-value)-'   

   .-BIT------------.                              
>--+----------------+--+-----------------------+---------------><
   +-DATATYPE(cvda)-+  '-FROMCCSID(data-value)-'   
   '-CHAR-----------'                              

Conditions: CCSIDERR, CHANNELERR, CONTAINERERR, INVREQ, LENGERR

This command is threadsafe.

End of change

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.
  • Implicitly, by omitting the CHANNEL option. If this is omitted, the current channel is implied.
Note:
  1. There is no limit to the number of containers that can be associated with a channel.
  2. The size of individual containers is limited only by the amount of storage available.
    CAUTION:
    Take care not to create so many large containers that you limit the amount of storage available to other applications.
  3. If the named container does not already exist, it is created. If the named container already exists, its previous contents are overwritten.
  4. If the named channel does not already exist, it is created.

Options

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 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 Start of changea-zEnd of change 0-9 & : = , ; < > . - and _.

CONTAINER(data-value)
specifies the name (1–16 characters) of the container into which data is to be 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 beginning with "DFH", unless requested to do so by CICS.

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 0-9 & : = , ; < > . - and _.

DATATYPE(cvda)
specifies the type of data to be put into the container. This option applies only to new containers. If the container already 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 in the container is converted (if necessary) to the code page of the application that created the channel. If the channel was created by a client application on an ASCII-based system, this will be an ASCII code page. If it was created by a CICS® Transaction Server for z/OS® application, it will be an EBCDIC code page. Conversion is only necessary if the client and server programs run on different platforms.

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, to ensure that data conversion works correctly you must put each character string into a separate container.

Start of changeFor CHAR containers, the data is stored in the Coded Character Set Identifier (CCSID) specified on the original PUT CONTAINER command that created the container. If the FROMCCSID option was not specified on the original PUT CONTAINER command, the data is stored in the region's default CCSID (or, for CICS-created channels, in the CCSID of the channel). The data on all future PUT CONTAINER CHANNEL commands for this container is converted into this same CCSID. If you want to avoid this, the application program should delete the existing container before issuing the new PUT CONTAINER command, thus recreating the container.End of change

A DATATYPE of CHAR must be specified if the container contains character data and the channel will be passed from CICS Transaction Server for z/OS to an ASCII system. If the container contains binary data, or the channel will not be passed to an ASCII system, DATATYPE is an optional parameter.

It is not possible to change the data-type of an existing container by means of a PUT CONTAINER command. For example, if a container is created with a data-type of BIT and a subsequent PUT CONTAINER command specifies a data-type of CHAR, for the same container, an INVREQ condition is raised. If you do need to replace an existing container by one of a different data-type, you must first explicitly delete the existing container.

For more information about data conversion with channels, see the CICS Application Programming Guide.

FLENGTH(data-value)
specifies, as a fullword binary value, the length of the data area from which data is to be read.
FROM(data-area)
specifies the data area from which the data is written to the container.
FROMCCSID(data-value)
specifies, as a fullword decimal number, the current Coded Character Set Identifier (CCSID) of the character data to be put into the container. For CICS Transaction Server for z/OS applications, this is typically an EBCDIC CCSID. (However, it is possible to specify an ASCII CCSID, if you want to pass ASCII data.)

Start of changeFROMCCSID is effective only on the PUT CONTAINER command that creates the container. This is because, for CHAR containers, the data is stored in the CCSID specified on the original PUT CONTAINER command that created the container. If you want to use a different CCSID, the application program should delete the existing container before issuing the new PUT CONTAINER command, thus recreating the container.End of change

If FROMCCSID is specified, DATATYPE(DFHVALUE(CHAR)) is implied.

If FROMCCSID is not specified, its value defaults to the CCSID of the region Start of change(or, for CICS-created channels, the CCSID of the channel)End of change. The default CCSID of the region is specified on the LOCALCCSID system initialization parameter.

For an explanation of CCSIDs, and a list of the CCSIDs supported by CICS, see the CICS Family: Communicating from CICS on System/390® manual.

Conditions

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
Start of changeOne 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. End of change
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.
CHANNELERR
RESP2 values:
1
The name specified on the CHANNEL option contains an illegal character or combination of characters.
CONTAINERERR
RESP2 values:
18
The name specified on the CONTAINER option contains an illegal character or combination of characters.
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.
LENGERR
RESP2 values:
1
A negative number was specified on the FLENGTH option.
End of change