EXEC CICS GET CONTAINER command (EXCI)

Description

GET CONTAINER (EXCI) 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.

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 be retrieved.

CONVERTST( cvda )

Specifies the required data conversion status.

NOCONVERT

The container data is retrieved without being converted.

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 EXCI job. The default CCSID of the EXCI job is specified on the LOCALCCSID parameter of DFHXCOPT.

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. A DATATYPE of CHAR is implied if FROMCCSID or FROMCODEPAGE is specified on the PUT 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.

RETCODE(data-area)

Specifies a 20-byte area into which the external CICS interface places return information. This area is formatted into five 1–word fields. This command will return information in the first two words. These words will contain the RESP and RESP2 codes. The other three words will be set to nulls.

RESP

The primary response code, which indicates whether the external CICS interface GET CONTAINER command caused an exception condition during its execution.

RESP2

The secondary response code that further qualifies, where necessary, some of the conditions that are raised in the RESP parameter.

SET( ptr-ref )

Specifies a data area in which the address of the retrieved data is returned.

The external CICS interface maintains the data area 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 and the containers that are in it are deleted by a DELETE CHANNEL command.

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, the application should move the data 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.

904

XCEIP ESTAE invoked.

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