ACQUIRE

Acquire access to a BTS activity from outside the process that contains it.

Syntax

ACQUIRE PROCESS

Conditions: ACTIVITYBUSY, ACTIVITYERR, INVREQ, IOERR, LOCKED, NOTAUTH, PROCESSBUSY, PROCESSERR

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

Description

ACQUIRE enables a program that is executing outside a particular BTS process to access an activity within the process. It allows the program to:

Read and write to the activity's data-containers.
Issue various commands, such as RUN and LINK, against the activity (if the acquired activity is a root activity, against the process).

An activity that a program gains access to by using an ACQUIRE command is known as an acquired activity. A program can acquire only one activity per unit of work. The activity remains acquired until the next syncpoint.

ACQUIRE ACTIVITYID acquires the specified descendant (non-root) activity.

ACQUIRE PROCESS acquires the root activity of the specified process.

Note: When a program defines a process, it is automatically given access to the process's root activity. (This enables the defining program to access the process containers and root activity containers before running the process.) When a program gains access to a root activity by means of either a DEFINE PROCESS or an ACQUIRE PROCESS command, the process is known as the acquired process.

Rules

A program can acquire only one activity within the same unit of work. The activity remains acquired until the next syncpoint. This means, for example, that a program:
- Cannot issue both a DEFINE PROCESS and an ACQUIRE PROCESS command within the same unit of work.
- Cannot issue both an ACQUIRE PROCESS and an ACQUIRE ACTIVITYID command within the same unit of work. That is, it can acquire either a descendant activity or a root activity, not one of each.
If a program is executing as an activation of an activity, it cannot:
- Acquire an activity in the same process as itself. It cannot, for example, issue ACQUIRE PROCESS for the current process.
- Use a LINK command to activate the activity that it acquired.
An acquired activity's process is accessible in the same way as the activity itself can access it. Thus, if the acquired activity is a descendant activity:
- Its process's containers can be read but not updated.
- The process cannot be the subject of any command—such as RUN, LINK, SUSPEND, RESUME, or RESET—that directly manipulates the process or its root activity.
Conversely, if the acquired activity is a root activity:
- Its process's containers can be both read and updated.
- The process can be the subject of commands such as RUN, LINK, SUSPEND, RESUME, or RESET. The ACQPROCESS keyword on the command identifies the subject process as the one the program that issues the command acquired in the current unit of work.

Options

ACTIVITYID(data-value): This option specifies the identifier (1–52 characters) of the descendant activity to be acquired.
PROCESS(data-value): This option specifies the name (1–36 characters) of the process whose root activity is to be acquired.
PROCESSTYPE(data-value): This option specifies the process-type (1–8 characters) of the process whose root activity is to be acquired.

Conditions

107 ACTIVITYBUSY

RESP2 values:

19: The request timed out. It may be that another task using this activity-record has been prevented from ending.

109 ACTIVITYERR

RESP2 values:

8: The activity referred to by the ACTIVITYID option cannot be found.

16 INVREQ

RESP2 values:

22: The unit of work that issued the ACQUIRE command has already acquired an activity; a unit of work can acquire only one activity.

17 IOERR

RESP2 values:

29: The repository file is unavailable.
30: An input/output error occurred on the repository file.

100 LOCKED

The request cannot be performed because a retained lock exists against the relevant record on the repository file.

70 NOTAUTH

RESP2 values:

101: The user who is associated with the issuing task is not authorized to access the file that is associated with the BTS repository data set on which details of the process are stored.

106 PROCESSBUSY

RESP2 values:

13: The request timed out. It may be that another task using this process-record has been prevented from ending.

108 PROCESSERR

RESP2 values:

5: The process that is named in the PROCESS option cannot be found.
9: The process-type that is named in the PROCESSTYPE option cannot be found.

Usage examples

ACQUIRE ACTIVITYID can be used to implement user-related activities. For example, on its first activation an activity might:

Define an input event to represent a particular user-interaction.
Issue an ASSIGN command to obtain the identifier of its own activity-instance.
Save the input event and activity identifier on a database.
Return without completing.

Later, when a user is ready to process the work that is represented by the activity, the user starts a transaction. This transaction, which executes outside the BTS process:

Retrieves the input event and activity identifier from the database.
Uses the ACQUIRE ACTIVITYID command to acquire access to the activity.
Places the information that is required to complete the activity in an input data-container, and runs the activity. The INPUTEVENT option of the RUN command tells the activity why it is being activated.

ACQUIRE PROCESS can be used to implement client/server processing. For example, a client program might use the DEFINE PROCESS and RUN commands to create and run a server process, which carries out some work, defines one or more input events, and returns without completing. The client issues a syncpoint or returns. To run the same server process again, the client uses the ACQUIRE PROCESS and RUN commands.