Page History
This activity acquires an exclusive lock using a specified identifier. It can be used (in conjunction with the MUTEX_RELEASE activity) to implement "single-threaded" access to a specified "resource", or, to put it another way, to block concurrent usage of the "resource".
For example, you may need to invoke a third-party provided web service that requires authentication, but permits only one concurrent request. If you need to implement this web service in your BPI solutions, then the MUTEX_ACQUIRE and MUTEX_RELEASE activities can be used (surrounding the web-service call) to ensure that only one active process attempts to invoke the web service, while any other concurrent process attempting to do so either waits or treats the unavailability as an exception accordingly.
...
When implementing MUTEX_ACQUIRE, the possibility arises of unanticipated circumstances leading to affected processes being unexpectedly "blocked" from normal operation. You need to understand this and plan procedures to free locks that inadvertently remain. In the simplest instance you can immediately free a lock by running the MUTEX_RELEASE activity - if you wish, you can do this directly from the LANSA Composer client (it does not have to be included in a processing sequence, but can be run on its own). In these circumstances, you will normally need to specify *YES for the FORCERELEASE parameter.
...
2. When implementing the MUTEX_ACQUIRE activity, we advise that you always "pair" it with a corresponding MUTEX_RELEASE activity surrounding the Processing Sequence directives and activities (as closely as possible) that comprise the conceptual resource you are seeking to protect. Options are available for automatic release of the locks - refer to the description of the DURATION parameter – but we advise that you do not rely on these exclusively, but include the MUTEX_RELEASE activity as early as possible to explicitly free the lock.
...
LANSA Composer supplies the example Processing Sequence EXAMPLE_MUTEX01 as a simple illustration of the use of this activity. Refer to Example Processing Sequences for information on installing and using the example Processing Sequences. Refer to the notes attached to the EXAMPLE_MUTEX01 Processing Sequence for information on using the example.
INPUT Parameters:
LOCKID: Required
This parameter must specify the identifier for the exclusive lock to be acquired. A maximum of 32 characters may be used for the identifier. If successful, the lock will block any other process that attempts to acquire a lock using the same identifier.
The identifier you use with MUTEX_ACQUIRE (and MUTEX_RELEASE) is a purely conceptual identifier – it does not represent any "real" system object or resource. However, it is your responsibility to devise and use an appropriate naming convention that will prevent unintended contention arising from using the same identifier for different purposes or resources.
DURATION: Optional
This parameter can specify the duration of the acquired lock, such that LANSA Composer may free the lock automatically where appropriate. If it is not specified, a default of *AUTOACTIVE is assumed. You can choose from the following supported values:
*AUTOACTIVE | This value specifies that the lock will endure until explicitly released using the MUTEX_RELEASE activity OR until the current processing sequence run ends, whether it completes normally or not. This option has the advantage of minimizing the risk of inadvertently leaving locks that may block subsequent processes. However, you may choose to avoid this option if you anticipate that your processing sequence may end in error while the lock is active and you wish the process to be restartable from that point. When you restart the processing sequence run that ended in error, it will no longer have the lock. You need to consider whether this behavior is appropriate for your solution. |
|---|---|
*AUTOCOMPLETE | This value specifies that the lock will endure until explicitly released using the MUTEX_RELEASE activity OR until the current processing sequence run ends normally or in a state that is ineligible to be restarted. If your processing sequence ends in error, but remains eligible to be restarted, the lock is NOT automatically released. This option ensures that the processing sequence run, when restarted, still has the specified lock. However, it will block other processing sequences until this one has been restarted and run to normal completion. |
*INDEFINITE | This value specifies that the lock will endure until explicitly released using the MUTEX_RELEASE activity. LANSA Composer will NOT automatically release the lock under any circumstances. It is your responsibility to ensure the lock is released at the appropriate time using the MUTEX_RELEASE activity. |
RETRIES: Optional
If the activity cannot immediately acquire the specified lock, this parameter (along with the RETRYINTERVAL parameter) determines whether and how the activity will wait and retry the request.
...
You may specify zero, if you want the activity to end in error immediately after the first and only attempt to acquire the lock.
RETRYINTERVAL: Optional
If the activity cannot immediately acquire the specified lock, and a value greater than zero is specified (or assumed) for the RETRIES parameter, this parameter specifies how long (in milliseconds) the activity will wait between retry attempts.
The default value is 500, meaning that the activity will wait for approximately half a second to elapse before retrying.
OUTPUT Parameters:
There are no output parameters