Claims and drains

DB2® utilities, commands, and some ALTER, CREATE, and DROP statements can take over access to some objects independently of any transaction locks that are held on the object.

Claims and drains apply to the following types of objects:

  • Table spaces that are not partitioned.
  • Data partitions.
  • Indexes that are not partitioned.
  • Index partitions.

Claims

Begin program-specific programming interface information.Certain utilities, commands, and some ALTER, CREATE, and DROP statements can use a claim to take over access to objects, independently of any transaction locks that are held on the object. When an application first accesses an object, within a unit of work, it makes a claim on the object. It releases the claim at the next commit point.

Unlike a transaction lock, a claim normally does not persist past the commit point. To access the object in the next unit of work, the application must make a new claim.

A claim indicates activity on or interest in a particular page set or partition to DB2. Claims prevent drains from occurring until the claim is released.

The following table shows the three classes of claims and the actions that they allow.

Table 1. Three classes of claims and the actions that they allow
Claim class Actions allowed
Write Reading, updating, inserting, and deleting
Repeatable read Reading only, with repeatable read (RR) isolation
Cursor stability read Reading only, with read stability (RS), cursor stability (CS), or uncommitted read (UR) isolation

DB2 generates a trace record for each time period that a task holds an uncommitted read claim. The value of the LRDRTHLD subsystem parameter controls the length of the time period. Start of changeDB2 also issues warning message DSNB260I when the trace record is written.End of changeEnd program-specific programming interface information.

Drains

A drain is the action of taking control of access to an object by preventing new claims and by waiting for existing claims to be released.

A utility can drain a partition when applications are accessing it. Drain quiesce applications by allowing each to reach a commit point, but preventing them, or other applications, from making new claims. When no more claims exist, the process that drains (the drainer) controls access to the drained object. The applications that were drained can still hold transaction locks on the drained object, but they cannot make new claims until the drainer has finished.

A drainer does not always need complete control. It can drain the following combinations of claim classes:

  • Only the write claim class
  • Only the repeatable read claim class
  • All claim classes
For example, the CHECK INDEX utility needs to drain only writers from an index space and its associated table space. RECOVER, however, must drain all claim classes from its table space. The REORG utility can drain either writers (with DRAIN WRITERS) or all claim classes (with DRAIN ALL).End program-specific programming interface information.

How DB2 uses drain locks

Begin program-specific programming interface information.
A drain lock prevents conflicting processes from claiming or draining the same object at the same time. Processes that drain only writers can run concurrently. However, a process that drains all claim classes cannot drain an object concurrently with any other process. To drain an object, a drainer first acquires one or more drain locks on the object, one for each claim class that it needs to drain. When the locks are in place, the drainer can begin after all processes with claims on the object have released their claims.

A drain lock also prevents new claimers from accessing an object while a drainer has control of it.

The types of drain locks correspond to the following claim classes:

  • Write
  • Repeatable read
  • Cursor stability read

In general, after an initial claim has been made on an object by a user, no other user in the system needs a drain lock. When the drain lock is granted, no drains on the object are in process for the claim class needed, and the claimer can proceed.

The claimer of an object requests a drain lock in the following exception cases:

  • A drain on the object is in process for the claim class needed. In this case, the claimer waits for the drain lock.
  • The claim is the first claim on an object before its data set has been physically opened. Here, acquiring the drain lock ensures that no exception states prohibit allocating the data set.
When the claimer gets the drain lock, it makes its claim and releases the lock before beginning its processing.
End program-specific programming interface information.