Start of change

GET CONTAINER (CHANNEL)

Retrieve data from a named channel container.

Start of change
Read syntax diagramSkip visual syntax diagram
GET CONTAINER (CHANNEL)

>>-GET--CONTAINER(data-value)--+---------------------+---------->
                               '-CHANNEL(data-value)-'   

>--+-INTO(data-area)-+--+--------------------+------------------>
   +-SET(ptr-ref)----+  '-FLENGTH(data-area)-'   
   '-NODATA----------'                           

>--+-----------------------+-----------------------------------><
   '-INTOCCSID(data-value)-'   

Conditions: CCSIDERR, CHANNELERR, CONTAINERERR, INVREQ, LENGERR

This command is threadsafe.

End of change

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: Start of change
  • 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.
End of change 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.
End of change