Materialize Process Locks (MATPRLK)

Edit online

Instruction Syntax

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, lock status is materialized for the process containing the thread issuing the instruction. If operand 2 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.

Lock status is materialized for every lock allocated or pending allocation to the process or any thread in the process. Materialization data identifies the object or space location for which the process or thread has a lock allocated or for which a thread in the process is in 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
  • Bytes provided
  • Bin(4)
4 4
  • Bytes available
  • Bin(4)
8 8 Limited lock count Bin(2)
10 A Lock count UBin(4)
14 E Reserved (binary 0) Char(2)
16
10
Lock description
(repeated for multiple locks)
[*] Char(32)
16
10
  • Object or space location
    (null if object not available or location in teraspace for another process)
  • System pointer or Space 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
    • Implicit lock
    • Bit 5
32 20
    • Reserved (binary 0)
    • Bits 6-7
33 21
  • Status of lock state for process
  • Char(1)
33
21
    • Lock scope object type
      0 =
      Process control space
      1 =
      Transaction control structure
    • Bit 0
33
21
    • Lock scope
      0 =
      Lock is scoped to the lock scope object type
      1 =
      Lock is scoped to a thread in the process
    • Bit 1
33
21
    • Object or space location inaccessible
    • 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 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, 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.

Both lock count and limited lock count indicate the total number of locks that match materialization criteria (both locks held and lock waits), but limited lock count is limited to 32,767. Bin(4) lock count is recommended, to simplify processing for more than 32,767 locks.

The number of entries in the lock description array is as many as fit in the template using the smaller of bytes provided and bytes available.

Only a single lock state is returned for each lock description entry, but implicit lock may (also) be set in any entry.

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.

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
    • Context referenced by 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
    • 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
  • 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