GET CONTAINER (BTS)
Retrieve data from a named BTS data-container.
Description
GET CONTAINER reads the data associated with a specified BTS activity or process into working storage.
- 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.