Materialize Data Space Record Locks (MATDRECL)

Operand 2: Space pointer.

Built-in number for MATDRECL is 49.
MATDRECL (
          receiver                    : address
          record_selection_template   : address
)

Description

The locks currently allocated on the specified data space record are materialized.

The current lock status of the data space record identified by the template in operand 2 is materialized into the space identified by operand 1.

The record selection template identified by operand 2 must be 16-byte aligned. The format of the record selection template is as follows.

The data space identification must be a system pointer to a data space.

The record number is a relative record number within that data space. If the record number is zero then all locks on the specified data space will be materialized. If the record number is not valid for the specified data space a template value invalid  (hex 3801) exception is signaled.

Both of the fields specified under lock selection are bits which determine the locks to be materialized. If the materialize data space locks held is materialize, the current holders of the specified data space record lock are materialized. If the materialize data space locks waited for is materialize, process information is materialized for any thread contained in the process that is waiting to lock the specified data space record.

The format for number of locks bit determines the format of the number of locks held and number of locks waited for fields in the materialization template. If the bit is set to binary 1 then Bin(4) counts are used, else Bin(2) counts are used.

The materialization template identified by operand 1 must be 16-byte aligned. The format of the materialization is as follows:

The first 4 bytes of the materialization identify the total number of bytes provided for use by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length invalid  (hex 3803) exception to be signaled.

The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested, the excess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length exception described previously.

The number of lock held descriptions contains the number of locks held. A system pointer to the lock holder (the object that holds the lock), the relative record number which is locked, and the lock state are materialized in the area identified as lock held descriptions. The lock holder can be either a process control space (PCS) or a transaction control structure. The object type is determined by the value of the lock scope object type field. When lock scope has a value of lock is scoped to the thread, the thread ID field identifies the thread that holds the lock. Otherwise it is set to binary 0. These fields contain data only if materialize data space locks held is materialize.

The number of lock waited for descriptions contains the number of locks being waited for. A system pointer to the process control space (PCS) for each thread waiting for a lock, the relative record number, and the lock state which the thread is waiting for are materialized in the area identified as lock waited for descriptions. The process control space and the thread ID fields will identify the thread that is waiting for the lock, regardless of the lock scope value. These fields contain data only if materialize data space locks waited for is materialize.

A database weak record lock is only acquired thread-scoped and it only conflicts with update record locks which are thread-scoped to a different thread. The weak record lock does not conflict in any other situation.

If UBin(2) fields are requested for the number of lock held descriptions and number of lock waited for descriptions, then the maximum number that can be returned in each count is 32,767. If the actual number is greater than 32,767 for a number then that number will be set to 32,767, only the first 32,767 locks will be materialized and no exception will be signaled.

Authorization Required

• Execute

  • Contexts referenced for address resolution

Lock Enforcement

• Materialize

  • Contexts referenced for address resolution

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range

08 Argument/Parameter

• 0801 Parameter Reference Violation

0A Authorization

• 0A01 Unauthorized for Operation

10 Damage Encountered

• 1004 System Object Damage State
• 1005 Authority Verification Terminated Due to Damaged Object
• 1044 Partial System Object Damage

1A Lock State

• 1A01 Invalid Lock State

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2201 Object Not Found
• 2202 Object Destroyed
• 2203 Object Suspended
• 2207 Authority Verification Terminated Due to Destroyed Object
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

• 3201 Scalar Type Invalid

36 Space Management

• 3601 Space Extension/Truncation

38 Template Specification

• 3801 Template Value Invalid
• 3803 Materialization Length Invalid

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed