Materialize Process Record Locks (MATPRECL)

Edit online

Instruction Syntax

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

Operand 2: Space pointer.

Bound Program Access 
Built-in number for MATPRECL is 52.
MATPRECL (
          receiver                     : address
          process_selection_template   : address
)

Description:

Data space record locks for a process identified in the process selection template specified by operand 2 are materialized into the receiver identified by operand 1. The materialization identifies each data space record lock which is either held by the process or is waited for by a thread within the process.

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

Offset
Dec Hex Field Name Data Type and Length
0 0 Process description System pointer
16 10 Lock selection Char(1)
16
10
  • Materialize held locks
    0 =
    Do not materialize
    1 =
    Materialize
  • Bit 0
16
10
  • Materialize locks waited for
    0 =
    Do not materialize
    1 =
    Materialize
  • Bit 1
16 10
  • Reserved
  • Bits 2-7
17 11 Template options Char(1)
17
11
  • Format for lock counts
    1 =
    Use UBin(4) for lock counts
    0 =
    Use Bin(2) for lock counts
  • Bit 0
17 11
  • Reserved
  • Bits 1-7
18 12 Reserved Char(6)
24
18
--- End ---

The process description must be a system pointer to a process control space (PCS) or a null pointer value. If the pointer is null, locks for the process containing the current thread are materialized. If it is a system pointer, the requester must be a thread in either the subject process or the process that initiated subject process, or the requesting thread must have process control special authorization in its user profile or an adopted user profile.

Both of the fields specified under lock selection are bits which determine the locks to be materialized. If the materialize held locks is materialize, any database record lock held by the process is materialized. If the materialize locks waited for is materialize, any database record lock a thread of the process is waiting for is materialized.

The format for lock counts bit determines the format of the lock held count and lock wait count fields in the materialization template. If the bit is set on then UBin(4) counts are used, else Bin(2) counts are used. UBin(4) counts are recommended, to simplify processing for more than 32,767 locks.

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
  • Bytes provided
  • Bin(4)
4 4
  • Bytes available
  • Bin(4)
8 8 Materialization data (2 possible formats) Char(8)
  • If format for lock counts bit=1
8 8
  • Lock held count
  • UBin(4)
12 C
  • Lock wait count
  • UBin(4)
  • --- End of bit=1 ---
  • If format for lock counts bit=0
8 8
  • Lock held count
  • Bin(2)
10 A
  • Lock wait count
  • Bin(2)
12 C
  • Reserved
  • Char(4)
  • --- End of bit=0 ---
16
10
Locks held descriptions
(repeated for multiple locks held)
[*] Char(32)
16 10
  • Data space
  • System pointer
32 20
  • Relative 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
  • 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 (binary 0)
    • Bits 2-7
38 26
  • Reserved
  • Char(2)
40 28
  • Thread ID
  • Char(8)
*
*
Lock wait descriptions
(repeated for multiple lock waits)
[*] Char(32)
* *
  • Data space
  • System pointer
* *
  • Relative 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
  • 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 (binary 0)
    • Bits 2-7
* *
  • Reserved
  • Char(2)
* *
  • Thread ID
  • Char(8)
*
*
--- End ---

The first 4 bytes of the materialization identify the total 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 bytes available to be materialized, limited to 2,147,483,647 if more locks are available than fit in a template of that size. 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 invalid (hex 3803) exception described previously.

Lock held count is the total number of locks held that match materialization criteria, limited to 32,767 for Bin(2) format. Lock wait count is the total number of lock waits that match materialization criteria, limited to 32,767 for Bin(2) format.

The number of entries in the lock held descriptions array is the lesser of total locks held that match materialization criteria and the number of entries that fit in the template using bytes provided, except the array is limited to 32,767 entries for Bin(2) lock counts when lock wait count is nonzero. Each entry contains a system pointer to the data space, relative record number in the data space, and lock state. When lock scope has a value of lock is scoped to the thread, the thread ID field identifies the thread that holds the lock.

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.

The number of entries in the lock wait descriptions array is the lesser of total lock waits that match materialization criteria and the number of entries after the lock wait descriptions array that fit in the template using bytes provided. Each entry contains a system pointer to the data space, relative record number in the data space, and lock state requested. The thread ID field identifies the thread that is waiting for the lock, regardless of the lock scope value.

Authorization Required

  • Process control special authorization
    • To materialize locks for a process that is neither the current process nor a process initiated by the current process
  • 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
    • 0A04 Special Authorization Required
  • 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
    • 2403 Pointer Addressing Invalid Object Type
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 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