Materialize Data Space Record Locks (MATDRECL)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2
032E Receiver Record selection template
Operand 1: Space pointer.

Operand 2: Space pointer.

Bound Program Access 
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.

Offset  
Dec Hex Field Name Data Type and Length
0 0 Record selection Char(24)
0 0
  • Data space identification
  • System pointer
16 10
  • Record number
  • UBin(4)
20 14
  • Reserved
  • Char(4)
24 18 Lock selection Char(1)

24

18

  • Materialize data space locks held

    0 =
    Do not materialize
    1 =
    Materialize

  • Bit 0

24

18

  • Materialize data space locks waited for

    0 =
    Do not materialize
    1 =
    Materialize

  • Bit 1
24 18
  • Reserved
  • Bits 2-7
25 19 Template options Char(1)

25

19

  • Format for number of locks

    1 =
    Use Bin(4) for number of locks
    0 =
    Use UBin(2) for number of locks

  • Bit 0
25 19
  • Reserved
  • Bits 1-7
26 1A Reserved Char(6)

32

20

--- End ---

 

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:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization size specification Char(8)
0 0
  • Number of bytes provided for materialization
  • Bin(4)
4 4
  • Number of bytes available for materialization
  • Bin(4)
8 8 Materialization data (2 possible formats) Char(8)
   
  • If format for number of locks bit=1
 
8 8
  • Number of lock held descriptions
  • Bin(4)
12 C
  • Number of lock waited for descriptions
  • Bin(4)

16

10

  • --- End of bit=1 ---
    If format for number of locks bit=0

8 8
  • Number of lock held descriptions
  • UBin(2)
10 A
  • Number of lock waited for descriptions
  • UBin(2)
12 C
  • Reserved
  • Char(4)
16 10
  • --- End of bit=0 ---

16

10

Lock held descriptions
(repeated number of lock held descriptions times)

[*] Char(32)
16 10
  • Lock holder
  • System pointer
32 20
  • Record number
  • UBin(4)

36

24

  • Lock state

    Hex 30 =
    DLWK (Database lock weak) lock state
    Hex C0 =
    DLRD (Database lock read) lock state
    Hex F8 =
    DLUP (Database lock update) lock state

    All other values are reserved.

  • Char(1)
37 25
  • Lock holder information
  • Char(1)

37

25

    • Lock scope object type

      0 =
      Process control space
      1 =
      Transaction control structure

    • Bit 0

37

25

    • Lock scope

      0 =
      Lock is scoped to the lock scope object type
      1 =
      Lock is scoped to the thread

    • Bit 1
37 25
    • Reserved
    • Bits 2-7
38 26
  • Reserved (binary 0)
  • Char(2)
40 28
  • Thread ID
  • Char(8)

*

*

Lock waited for descriptions
(repeated number of lock waited for descriptions times)

[*] Char(32)
* *
  • Process control space
  • System pointer
* *
  • Record number
  • UBin(4)

*

*

  • Lock state requested

    Hex 30 =
    DLWK (Database lock weak) lock state
    Hex C0 =
    DLRD (Database lock read) lock state
    Hex F8 =
    DLUP (Database lock update) lock state

    All other values are reserved.

  • Char(1)
* *
  • Lock waiter information
  • Char(1)

*

*

    • Lock scope object type

      0 =
      Process control space
      1 =
      Transaction control structure

    • Bit 0

*

*

    • Lock scope

      0 =
      Lock is scoped to the lock scope object type
      1 =
      Lock is scoped to the thread

    • Bit 1
* *
    • Reserved
    • Bits 2-7
* *
  • Reserved
  • Char(2)
* *
  • Thread ID
  • Char(8)

*

*

--- End ---

 

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
Parent topic: Object Lock Management