Materialize Process Locks (MATPRLK)


Op Code (Hex) Operand 1 Operand 2

0312 Receiver Process control space

Operand 1: Space pointer.

Operand 2: System pointer or null.

Bound program access
Built-in number for MATPRLK is 51.
MATPRLK (
         receiver                : address
         process_control_space   : address of system pointer OR
                                   null operand
)

Description

The lock status of the process identified by operand 2 is materialized into the receiver specified by operand 1. If operand 2 is null, the lock status is materialized for the process containing the thread issuing the instruction. The lock status is materialized for each lock allocated to the process and for each lock allocated to each thread contained in the process. The materialization identifies each object or space location for which the process or applicable thread has a lock allocated or for which the applicable thread is in a synchronous or asynchronous wait. 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
Number of lock entries
Bin(2)
10 A
Expanded number of lock entries
Bin(4)
14 E
Reserved (binary 0)
Char(2)
16 10
Lock status
[*] Char(32)



(repeated for the number of lock entries)


16 10
Object, space location or binary 0 (if no pointer exists)
System pointer or Space pointer or Open pointer
32 20
Lock state
Char(1)
32 20
LSRD
Bit 0
32 20
LSRO
Bit 1
32 20
LSUP
Bit 2
32 20
LEAR
Bit 3
32 20
LENR
Bit 4
32 20
Reserved (binary 0)
Bits 5-7
33 21
Status of lock state for process
Char(1)
33 21
Lock scope object type
Bit 0



0 = Process control space
1 = Transaction control structure


33 21
Lock scope
Bit 1



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


33 21
Object or space location no longer exists
Bit 2
33 21
Waiting because this lock is not available
Bit 3
33 21
Thread is in asynchronous wait for lock
Bit 4
33 21
Thread is in synchronous wait for lock
Bit 5
33 21
Implicit lock (machine-applied)
Bit 6
33 21
Lock held by a process, thread, or transaction control structure
Bit 7
34 22
Lock information
Char(1)
34 22
Reserved
Bits 0-5
34 22
Lock is held by a process, thread or transaction control structure other than the current process or thread
Bit 6
34 22
Lock is held by the machine
Bit 7
35 23
Reserved (binary 0)
Char(1)
36 24
Unopened thread handle
UBin(4)
40 28
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, then the excess bytes are unchanged. No exceptions (other than the materialization length invalid  (hex 3803) exception described previously) are signaled if the receiver contains insufficient area for the materialization.

The number of lock entries field identifies the number of lock entries that are materialized. When a process and its threads hold more than 32,767 locks, this field is set with its maximum value of 32,767. This field has been retained in the template for compatibility with programs using the template prior to the changes made to support materialization of more than 32,767 lock entries.

The expanded number of lock entries field identifies the number of lock entries that are materialized. This field is always set in addition to the number of lock entries field described previously; however, it does not have a maximum limit of 32,767, so it can be used to specify that more than 32,767 locks have been materialized. When a process and its threads hold more than 32,767 locks, the number of lock entries field will equal 32,767, which would be incorrect. The expanded number of lock entries field, however, will identify the correct number of lock entries materialized. In all cases, this field should be used instead of the number of lock entries field to get the correct count of lock entries materialized.

The lock scope field identifies the scope of the lock being requested. If the lock is allocated, the lock holder information field is binary 0. If the lock is pending, the lock information field contains information about the current holder of the lock.

For allocated locks that are process scope, the unopened thread handle and thread ID fields will be set to binary 0. For allocated locks that are thread scope, these fields will identify the specific thread in the specified process that holds the lock. For locks being waited on, these fields will identify the specific thread in the specified process that is waiting for the lock, regardless of the lock scope value.

If the current thread does not belong to the process whose locks are being materialized, a null pointer value will be returned for any teraspace storage locations.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

28 Process/Thread State

2E Resource Control Limit

36 Space Management

38 Template Specification

44 Protection Violation