Retrieve data from a named channel container.
Description
GET CONTAINER (CHANNEL) reads the data
associated with a specified channel container.
The container which
holds the data is identified by name and by the channel for which it is a
container—the channel that “owns” it. 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.
Options
- CHANNEL(data-value)
- specifies
the name (1–16 characters) of the channel that owns the container.
- CONTAINER(data-value)
- specifies
the name (1–16 characters) of the container that holds the data to be retrieved.
- FLENGTH(data-area)
- As
an input field, FLENGTH specifies, as a fullword binary value, the length
of the data to be read. As an output field, FLENGTH returns the length of
the data in the container. Whether FLENGTH is an input or an output field
depends on which of the INTO, SET, or NODATA options you specify.
- INTO option specified
- FLENGTH is both an input and an output field.
On input, FLENGTH
specifies the maximum length of the data that the program accepts. If the
value specified is less than zero, zero is assumed. If the length of the data
exceeds the value specified, the data is truncated to that value and the LENGERR
condition occurs.
FLENGTH need not be specified if the length can be
generated by the compiler from the INTO variable. If you specify both INTO
and FLENGTH, FLENGTH specifies the maximum length of the data that the program
accepts.
On output (that is, on completion of the retrieval operation)
CICS sets the data area, if specified, to the actual length of the data in
the container. If the container holds character data that has been converted
from one CCSID to another, this is the length of the data after conversion.
- SET or NODATA option specified
- FLENGTH is an output-only field. It must be specified and must be specified
as a data-area.
On completion of the retrieval operation, the data area
is set to the actual length of the data in the container. If the container
holds character data that has been converted from one CCSID to another, this
is the length of the data after conversion.
- INTO(data-area)
- specifies
the data area into which the retrieved data is to be placed.
- INTOCCSID(data-value)
- specifies,
as a fullword binary number, the Coded Character Set Identifier (CCSID) into
which the character data in the container is to be converted. For CICS Transaction
Server for z/OS applications, this is typically an EBCDIC CCSID. (However,
it is possible to specify an ASCII CCSID if, for example, you want to retrieve
ASCII data without it being automatically converted to EBCDIC.)
If INTOCCSID
is not specified, its value defaults to the CCSID of the region. The default
CCSID of the region is specified on the LOCALCCSID system
initialization parameter.
Only character data can be converted, and
only then if a DATATYPE of CHAR was specified on the PUT CONTAINER command
used to place the data in the container.
For more information about
data conversion with channels, see the CICS Application Programming
Guide.
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.
- NODATA
- specifies
that no data is to be retrieved. Use this option to discover the length of
the data in the container (returned in FLENGTH).
The length of character
data may change if data conversion takes place. Therefore, if character data
is to be converted into any CCSID other than that of this region, when
you specify NODATA you should also specify INTOCCSID. This ensures that the
correct length of the converted data is returned in FLENGTH.
- SET(ptr-ref)
- specifies
a data area in which the address of the retrieved data is returned.
The
data area is maintained by CICS until any of the following occurs:

- A subsequent GET CONTAINER command with the SET option, for the same container
in the same channel, is issued by any program that can access this storage.
- The container is deleted by a DELETE CONTAINER command.
- The container is moved by a MOVE CONTAINER command.
- The channel goes out of program scope.

Beware of linking to other programs that might issue one of the above
commands.
Do not issue a FREEMAIN command to release this storage.
If
your application needs to keep the data it should move it into its own storage.
Conditions
- CCSIDERR
- RESP2
values:
- 1
- The CCSID specified on the INTOCCSID option is outside the range of valid
CCSID values.
- 2
- The CCSID specified on the INTOCCSID option and the CCSID of the channel
are an unsupported combination.
- 3
- The data was created with a data-type of BIT. Code page conversion is
not possible. The data was returned without any code page conversion.
- 4
- One or more characters could not be converted. The 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.
- CHANNELERR
- RESP2
values:
- 2
- The channel specified on the CHANNEL option could not be found.
- CONTAINERERR
- RESP2
values:
- 10
- The container named on the CONTAINER option could not be found.
- INVREQ
- RESP2
values:
- 2
- The INTOCCSID option was specified without the CHANNEL option, and there
is no current channel (because the program that issued the command was not
passed one.) INTOCCSID is valid only on GET 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.
- LENGERR
- RESP2
values:
- 11
- The length of the program area is shorter than the length of the data
in the container. When the area is smaller, the data is truncated to fit into
it.