OpenTP1 manages a lock from the time a lock request is issued until the time the lock is released. A lock is usually managed for each global transaction; however, the DAM-service locks are managed for each transaction branch.

The scope of a lock is within one OpenTP1 system. A UAP on one OpenTP1 system cannot lock a resource on another OpenTP1 system. Even in one OpenTP1 system that is composed of multiple nodes, a lock between nodes is not possible.

The dc_lck_get function can be called from a UAP to lock a resource. In the arguments, specify the resource name and lock mode (method of preventing other UAPs from accessing the resource).

Two lock modes are available: PR mode excludes only UAPs that update the resource, allowing access by other UAPs that only reference the resource. EX mode grants exclusive use of the resource, prohibiting access by all other UAPs.

The following table lists and describes the lock modes.

Table 3-19 Lock modes

Lock mode	Type	Description
PR	Reference	While a UAP is using the resource, OpenTP1 permits other UAPs to access the resource for reference only, and prohibits other UAPs from updating the resource.
EX	Update	While a UAP is using the resource, OpenTP1 prohibits all kinds of access from other UAPs.

Note

PR: Protected Retrieve

EX: EXclusive

The following table lists and describes when resources can be shared depending on the combination of lock modes.

Table 3-20 Possibility of sharing resources depending on combination of lock modes

Lock mode of UAP currently using the resource	UAP that requests access with PR mode	UAP that requests access with EX mode
PR mode	Can share	Cannot share
EX mode	Cannot share	Cannot share

A lock on a resource can be released by a UAP issuing:

• a lock-release request for each resource (e.g., by issuing the function dc_lck_release_byname())
• a global lock-release request (e.g., by issuing the function dc_lck_release_all())

OpenTP1 automatically releases all the resources from locks at the termination of a transaction. This ensures that resources are never left monopolized even if the user omits issuing the release request or the UAP terminates abnormally.

In a parameter of the lock-request function dc_lck_get(), you can specify whether or not the UAP should wait if it cannot immediately use a resource. A UAP cannot use a resource when:

• another UAP is already using the resource and has locked the resource in the EX mode
• the UAP attempts to use the resource with a lock in the EX mode while another UAP is already using the resource and has locked the resource with the PR mode

If the parameter specifies that a UAP is to wait until a resource can be locked, OpenTP1 makes the UAP that wants to use a resource wait until the lock on the resource is released.

If the parameter specifies that a UAP is not to wait until a resource can be locked, an error is immediately returned.

When several UAPs want to use a resource, the lock-wait priority determines which UAP is to next use the resource. The lock-wait priority for a UAP is specified in the user service definition for each UAP service group. A UAP with a higher priority might be able to use a resource earlier than a UAP with a lower priority. The fact that a UAP with a low priority might access a resource after UAPs with higher priorities needs to be kept in mind when assigning priorities.

In the lck_wait_timeout operand in the lock service definition, you can specify how long a UAP should wait for a resource lock to be released. If a lock is not released before this time expires, a lock-request error is returned.

Figure 3-68 illustrates how lock-wait priority affects the sequence in which UAPs can use a resource.

Figure 3-68 Priorities determining sequence in which resources are used

This section describes how TAM and DAM lock functions are affected by deadlocks.

When two or more UAPs lock multiple resources in different sequences, an undesirable situation called a deadlock might occur. For example, in one form of deadlock, one UAP might lock resource A and wait for resource B to be released while another UAP might be locking resource B and waiting for resource A to be released. Figure 3-69 illustrates a deadlock.

Figure 3-69 Example of a deadlock

OpenTP1 detects deadlocks differently depending on whether the UAPs are on the same or different nodes. When UAPs are running on the same node, OpenTP1 automatically checks at regular intervals to detect deadlocks. When UAPs are running on different nodes, however, OpenTP1 cannot directly detect a deadlock so OpenTP1 checks whether any UAP has exceeded the specified time-limit for waiting for a resource. In the lck_wait_timeout operand in the lock service definition, you can specify the time-limit for waiting for a resource.

(a) Handling deadlocks

When a deadlock occurs, OpenTP1 returns an error to the lock request from the UAP process that has the lowest lock-wait priority. You can specify a UAP lock-wait priority with the deadlock_priority operand in the user service definition.

When a deadlock causes an error to be returned by the function that attempted to reserve the resource, you should do the following in the UAPs:

• For SUPs or SPPs
  When a deadlock occurs during SUP or SPP processing, you should roll back the transaction by using a rollback function (e.g., dc_trn_unchained_rollback()). SUPs or SPPs that have been rolled back because of a deadlock are not re-executed. You should ensure that the client UAP re-requests the relevant service.
  
• For MHPs
  When a deadlock occurs during MHP processing, issue the dc_mcf_rollback() function to roll back. In this function you can specify whether to re-execute the rolled back application.
  

(b) Output of deadlock information and timeout information

When a deadlock occurs, detailed deadlock information about the UAPs that caused the deadlock can be output to a directory in a node that contains the lock service.

When a UAP waiting for the release of a resource exceeds the time specified in the lck_wait_timeout operand in the lock service definition, the function issued by the UAP returns an error. In such a case, detailed timeout information about the resource that the UAP wanted to reserve is output to a directory in the node that contains the lock service.

In the lck_deadlock_info operand in the lock service definition, you can specify whether to output deadlock information and timeout information. For details about the format of deadlock and timeout information, see the OpenTP1 Programming Guide.

There are two ways to delete the acquired deadlock information:

• By executing the lckrminf command.
  By deleting, at the start of OpenTP1, information that was created up to the previous online processing: Specify the delete conditions in the lck_deadlock_info_remove_level operand of the lock service definition.