GET CONTAINER

Retrieve data from a named channel container.

GET CONTAINER

Read syntax diagramSkip visual syntax diagramGET CONTAINER( data-value)CHANNEL( data-value)INTO( data-area)FLENGTH( data-area)SET( ptr-ref)-FLENGTH( data-area)NODATA-FLENGTH( data-area)INTOCCSID(data-value)

Conditions

CCSIDERR, CHANNELERR, CONTAINERERR, INVREQ, LENGERR

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.

For COBOL applications FLENGTH can be optional.

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.

If INTOCCSID is not specified, its value defaults to the CCSID of the region. The default CCSID of the region is derived from the regions' locale. 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.

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.
  • 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).
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.