GET64 CONTAINER
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.
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 code page. If you use a code page 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. You can specify the channel name DFHTRANSACTION to use the transaction channel.
- 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.
- The channel, and the containers that are in it, are deleted by a DELETE CHANNEL command.
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.