Retrieve data from a
named channel container into 64-bit storage. 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.
GET64 CONTAINER
>>-GET64--CONTAINER(data-value)--+---------------------+-------->
'-CHANNEL(data-value)-'
>--+-INTO(data-area64)-+----------------------------------------------+-+-->
| '-FLENGTH(data-area)-+-----------------------+-' |
| '-BYTEOFFSET(data-area)-' |
+-SET(ptr-ref64)-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
GET64 CONTAINER reads the data
associated with a specified channel container into 64-bit storage.
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 retrieve.
- CONVERTST(cvda)
- Specifies
the required data conversion status.
- NOCONVERT
- The container data is
retrieved without being converted. If you used the WEB RECEIVE command
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 field only. 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-area64)
- Specifies
the 64-bit data area into which the retrieved data is placed. 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.
- 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 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 might 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-ref64)
- Specifies
a 64-bit pointer reference in which the 64-bit address of the retrieved
data is returned. This pointer reference is always to 64-bit (above-the-bar)
storage.
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 FREEMAIN64 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 GET64 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).
- 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.