Materialize Process Record Locks (MATPRECL)


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.

If the process control space (PCS) pointer is null or all zeros, the lock activity for the process containing the current thread is materialized.

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 selection
Char(16)
0 0
Process descriptions
System pointer
16 10
Lock selection
Char(1)
16 10
Materialize held locks
Bit 0



0 = Do not materialize
1 = Materialize


16 10
Materialize locks waited for
Bit 1



0 = Do not materialize
1 = Materialize


16 10
Reserved
Bits 2-7
17 11
Template options
Char(1)
17 11
Format for number of locks
Bit 0



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


17 11
Reserved
Bits 1-7
18 12
Reserved
Char(6)
24 18
--- End ---

The process descriptions must be a system pointer to a process control space (PCS) or a null pointer value.

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 number of locks bit determines the format of the number of lock held descriptions and number of locks waited for descriptions fields in the materialization template. If the bit is set on 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 desscriptions
Bin(4)
16 10
--- End of bit=1 ---




If format for number of locks bit=0


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

16 10
Locks held descriptions
[*] Char(32)



(repeated number of lock held descriptions times)


16 10
Data space
System pointer
32 20
Relative record number
UBin(4)
36 24
Lock state
Char(1)



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.



37 25
Lock holder information
Char(1)
37 25
Lock scope object type
Bit 0



0 = Process control space
1 = Transaction control structure


37 25
Lock scope
Bit 1



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


37 25
Reserved (binary 0)
Bits 2-7
38 26
Reserved
Char(2)
40 28
Thread ID
Char(8)
* *
Lock waited for descriptions
[*] Char(32)



(repeated number of lock waited for descriptions times)


* *
Data space
System pointer
* *
Relative record number
UBin(4)
* *
Lock state requested
Char(1)



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.



* *
Lock waiter information
Char(1)
* *
Lock scope object type
Bit 0



0 = Process control space
1 = Transaction control structure


* *
Lock scope
Bit 1



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


* *
Reserved (binary 0)
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 invalid  (hex 3803) exception described previously.

The number of lock held descriptions contains the number of locks held by the process. One system pointer to the data space, relative record number in the data space, and lock state is materialized in the area identified as lock held descriptions for each lock. 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 held locks 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.

The number of lock waited for descriptions contains the number of locks that the process is waiting for. One system pointer to the data space, relative record number in the data space, and lock state requested is materialized in the area identified as lock waited for descriptions for each lock waited for. The thread ID field identifies the thread that is waiting for the lock, regardless of the lock scope value. These fields contain data only if materialize locks waited for is materialize.

If Bin(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 count then that count will be set to 32,767, only the first 32,767 locks will be materialized, and no exception will be signaled.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

1A Lock State

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation