Acquire access to a BTS activity from outside the process
that contains it.
ACQUIRE PROCESS
>>-ACQUIRE--+-PROCESS(data-value)--PROCESSTYPE(data-value)-+---><
'-ACTIVITYID(data-value)-----------------------'
Conditions: ACTIVITYBUSY, ACTIVITYERR, INVREQ, IOERR,
LOCKED, NOTAUTH, PROCESSBUSY, PROCESSERR
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
An activity that a program gains access to by means of 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 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.
Conversely, if the acquired activity is a 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.