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
- ACTIVITYBUSY
- RESP2
values:
- 19
- The request timed out. It may be that another task using this activity-record
has been prevented from ending.
- ACTIVITYERR
- RESP2
values:
- 8
- The activity referred to by the ACTIVITYID option could not be found.
- 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.
- IOERR
- RESP2
values:
- 29
- The repository file is unavailable.
- 30
- An input/output error has occurred on the repository file.
- LOCKED
- The
request cannot be performed because a retained lock exists against the relevant
record on the repository file.
- 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.
- PROCESSBUSY
- RESP2
values:
- 13
- The request timed out. It may be that another task using this process-record
has been prevented from ending.
- 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.
For an example of the use of ACQUIRE ACTIVITYID, see the CICS® Business Transaction Services manual.
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.
For an example of the use of ACQUIRE PROCESS, see the CICS Business Transaction Services manual.