Acquire access to a BTS activity from outside the process that contains it.
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.1
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 has 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 may be read but not updated.
- The process may not be the subject of any command—such as RUN, LINK, SUSPEND, RESUME, or RESET—that directly manipulates the process or its root activity.
- Its process's containers may be both read and updated.
- The process may 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 has acquired in the current unit of work.
Options
- ACTIVITYID(data-value)
- specifies the identifier (1–52 characters) of the descendant activity to be acquired.
- PROCESS(data-value)
- specifies the name (1–36 characters) of the process whose root activity is to be acquired.
- PROCESSTYPE(data-value)
- 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 could not 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 has 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 associated with the issuing task is not authorized to access the file 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 named in the PROCESS option could not be found.
- 9
- The process-type named in the PROCESSTYPE option could not 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 data base
- Return without completing.
Later, when a user is ready to process the work represented
by the activity, he or she starts a transaction. This transaction,
which executes outside the BTS process:
- Retrieves the input event and activity identifier from the data base
- Uses the ACQUIRE ACTIVITYID command to acquire access to the activity
- Places the information 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.
