Materialize Process Locks (MATPRLK)

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, 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
(repeated for the number of lock entries)

[*] Char(32)
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

      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 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

  • 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
  • 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
  • 28 Process/Thread State
    • 2802 Process Control Space Not Associated with a Process
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 38 Template Specification
    • 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