GET CONTAINER (BTS)

Retrieve data from a named BTS data-container.

GET CONTAINER

Read syntax diagramSkip visual syntax diagramGETCONTAINER( data-value)ACTIVITY( data-value)ACQACTIVITYPROCESS ACQPROCESSINTO( data-area)SET( ptr-ref)NODATAFLENGTH( data-area)

Conditions: ACTIVITYERR, CONTAINERERR, INVREQ, IOERR, LENGERR, LOCKED, PROCESSBUSY

Description

GET CONTAINER reads the data associated with a specified BTS activity or process into working storage.

The container which holds the data is identified by name and by the process or activity for which it is a container—the process or activity that “owns” it. The activity that owns the container can be identified:
  • Explicitly, by specifying one of the PROCESS- or ACTIVITY-related options.
  • Implicitly, by omitting the PROCESS- and ACTIVITY-related options. If these are omitted, the current activity is implied.

See also PUT CONTAINER (BTS) and MOVE CONTAINER (BTS).

Options

ACQACTIVITY
specifies either of the following:
  • If the program that issues the command has acquired a process, that the container is owned by the root activity of that process.
  • Otherwise, that the container is owned by the activity that the program has acquired by means of an ACQUIRE ACTIVITYID command.
ACQPROCESS
specifies that the container is owned by the process that the program that issues the command has acquired in the current unit of work.
ACTIVITY(data-value)
specifies the name (1–16 characters) of the activity that owns the container. This must be a child of the current activity.
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. If the length of the data is less than the value specified, the data is copied with no padding 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.

SET or NODATA option specified
FLENGTH is an output-only field. It must be specified and 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.

INTO(data-area)
specifies an area of working storage into which the retrieved data is to be placed.
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).
PROCESS
specifies that the container to be retrieved is owned by the current process—that is, the process that the program that issues the command is executing on behalf of.
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 a subsequent GET CONTAINER command with the SET option is issued by the task, or until the task ends.

If your application needs to keep the data it should move it into its own storage.

Conditions

109 ACTIVITYERR
RESP2 values:
8
The activity named on the ACTIVITY option could not be found.
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 (explicitly or implicitly) a channel. It is not valid on GET CONTAINER (BTS) commands.
4
The command was issued outside the scope of a currently-active activity.
15
The ACQPROCESS option was used, but the unit of work that issued the request has not acquired a process.
24
The ACQACTIVITY option was used, but the unit of work that issued the request has not acquired an activity.
25
The PROCESS option was used, but the command was issued outside the scope of a currently-active process.
17 IOERR
RESP2 values:
30
An input/output error has occurred on the repository file.
31
The record on the repository file is in use.
22 LENGERR
RESP2 values:
11
The length of the program area is not the same as the length of the data in the container. If the area is smaller, the data is truncated to fit into it. If the area is larger, the data is copied to the program area but no padding is added.
100 LOCKED
The request cannot be performed because a retained lock exists against the relevant record on the repository file.
106 PROCESSBUSY
RESP2 values:
13
The request could not be satisfied because the process record is locked by another task.