Retrieve data from a named channel container.
GET CONTAINER (CHANNEL)
>>-GET--CONTAINER(data-value)--+---------------------+---------->
'-CHANNEL(data-value)-'
>--+-INTO(data-area)-+----------------------------------------------+-+-->
| '-FLENGTH(data-area)-+-----------------------+-' |
| '-BYTEOFFSET(data-area)-' |
+-SET(ptr-ref)-FLENGTH(data-area)-+------------------------+-------+
| '-BYTEOFFSET(data-value)-' |
'-NODATA-FLENGTH(data-value)---------------------------------------'
>--+--------------------------------------+--------------------><
+-INTOCCSID(data-value)----------------+
+-INTOCODEPAGE(data-value)-------------+
'-CONVERTST(cvda)-+------------------+-'
'-CCSID(data-area)-'
Conditions: CCSIDERR, CHANNELERR, CODEPAGEERR, CONTAINERERR,
INVREQ, LENGERR
This command is threadsafe.
Description
GET CONTAINER (CHANNEL) reads
the data associated with a specified channel container.
The
container that 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, or implicitly, by omitting the CHANNEL option.
When this option is omitted, the current channel is implied.
Options
- BYTEOFFSET(data-value)
- Specifies the offset in bytes where
the data returned starts. For CHAR containers, the BYTEOFFSET value
is used as an offset into the data in the requested codepage. If you
use a codepage with multibyte characters, depending on the BYTEOFFSET
value you specify, the data returned might have partial characters
at the beginning, end, or both. In this situation, your application
program must be able to handle and interpret the data returned. If
the value specified is less than zero, zero is assumed.
- CCSID(data-area)
- Returns
a fullword that contains the Coded Character Set Identifier (CCSID)
of the data returned by the CONVERTST(NOCONVERT) option. You can use
this option to retrieve containers with a DATATYPE of CHAR, without
converting the data. If a DATATYPE of BIT is specified for the container,
this value is zero.
- 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.
- CONVERTST(cvda)
- Specifies
the required data conversion status.
- NOCONVERT
- The container
data is retrieved without being converted. If you used the WEB RECEIVE
to store the HTTP body in a container, and you need to retrieve the
body unconverted from that container, you must use the NOCONVERT
option.
- 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. FLENGTH is an input or an
output field depending on which of the BYTEOFFSET, INTO, SET, or NODATA
options you specify.
- BYTEOFFSET 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. The data returned begins at the offset specified by the BYTEOFFSET
value. If the value specified is less than zero, zero is assumed.
On output (that
is, on completion of the retrieval operation) CICS® sets the data area to the length of the
data returned. The maximum length returned is equal to the length
of the data in the container minus the BYTEOFFSET value.
- 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. If the length
of the data is less than the specified value, the data is copied but
no padding is performed.
You do not need to specify FLENGTH
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 present 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 placed.
- INTOCCSID(data-value)
- Specifies the Coded Character Set Identifier
(CCSID) into which the character data in the container is converted,
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 INTOCODEPAGE option instead.
For CICS Transaction Server for z/OS® applications,
the CCSID 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 and INTOCODEPAGE are not specified, the value for conversion
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 or PUT64 CONTAINER command
used to place the data in the container. A DATATYPE of CHAR is implied
if FROMCCSID or FROMCODEPAGE is specified on the PUT CONTAINER or PUT64
CONTAINER command.
For more information about data
conversion with channels, see Data conversion with channels.
For
an explanation of CCSIDs, see Preparing for code page conversion with channels.
- INTOCODEPAGE(data-value)
- Specifies an IANA-registered alphanumeric
charset name or a Coded Character Set Identifier (CCSID) for the code
page into which the character data in the container is to be converted,
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.
Where
an IANA name exists for a code page and CICS supports its use, the
name is listed with the CCSID. For more information, see Preparing for code page conversion with channels.
- NODATA
- Specifies
that no data is 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.
If the application program that issues the GET
CONTAINER command is defined with DATALOCATION(ANY), the
address of the data can be above or below the 16 MB line. If the application
program is defined with DATALOCATION(BELOW), the address of the data
is below the 16 MB line. If TASKDATAKEY(USER) is specified for the
executing transaction, the data returned is in user key; otherwise
it is in CICS key.
CICS maintains the data area until any of
the following occurs:
- A subsequent GET CONTAINER or GET64
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 these
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
- 123 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
container are an unsupported combination. (The CCSID of the container
is the value that was specified using either FROMCODEPAGE or FROMCCSID,
or defaulted, when the container was built.)
- 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.
- 122 CHANNELERR
- RESP2 values:
- 2
- The channel specified on the CHANNEL option could not be found.
- 125 CODEPAGEERR
- RESP2 values:
- 1
- The code page specified on the INTOCODEPAGE option is not supported.
- 2
- The code page specified on the INTOCODEPAGE option and the code
page 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.
- 110 CONTAINERERR
- RESP2 values:
- 10
- The container named on the CONTAINER option could not be found.
- 16 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.
- 5
- The CONVERTST cvda value is invalid.
- 22 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.
- 12
- The offset is greater than, or equal to, the length of the container.