Materialize Object Locks (MATOBJLK)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2
033A Receiver System object or space location
Operand 1: Space pointer.

Operand 2: System pointer or space pointer data object.

Bound Program Access 
Built-in number for MATOBJLK is 50.
MATOBJLK (
          receiver                          : address
          system_object_or_space_location   : address of system pointer OR
                                              address of space pointer(16)
)

Description:

If operand 2 is a system pointer, the current lock status of the object identified by the system pointer is materialized into the template specified by operand 1. If operand 2 is a space pointer, the current lock status of the specified space location is materialized into the template specified by operand 1.

Note: Teraspace storage locations are interpreted within the process in which the current thread is executing. If operand 2 is a space pointer to a teraspace location the current lock status for the invoking process and its secondary threads (if any) will be materialized as they relate to the teraspace location.

The materialization template identified by operand 1 must be aligned on a 16-byte boundary. 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 Current cumulative lock status Char(3)

8

8

  • Lock states currently allocated
    (1 = yes)

  • Char(1)
8 8
    • LSRD
    • Bit 0
8 8
    • LSRO
    • Bit 1
8 8
    • LSUP
    • Bit 2
8 8
    • LEAR
    • Bit 3
8 8
    • LENR
    • Bit 4
8 8
    • Locks implicitly set
    • Bit 5
8 8
    • Reserved (binary 0)
    • Bits 6-7

9

9

  • Lock states for which threads are in synchronous wait
    (1 = yes)

  • Char(1)
9 9
    • LSRD
    • Bit 0
9 9
    • LSRO
    • Bit 1
9 9
    • LSUP
    • Bit 2
9 9
    • LEAR
    • Bit 3
9 9
    • LENR
    • Bit 4
9 9
    • Implicit lock request
    • Bit 5
9 9
    • Reserved (binary 0)
    • Bits 6-7

10

A

  • Lock states for which threads are in asynchronous wait
    (1 = yes)

  • Char(1)
10 A
    • LSRD
    • Bit 0
10 A
    • LSRO
    • Bit 1
10 A
    • LSUP
    • Bit 2
10 A
    • LEAR
    • Bit 3
10 A
    • LENR
    • Bit 4
10 A
    • Reserved (binary 0)
    • Bits 5-7
11 B Reserved (binary 0) Char(1)
12 C Number of lock state descriptions Bin(2)
14 E Reserved (binary 0) Char(2)

16

10

Lock state descriptions
(repeated number of lock state descriptions times)

[*] Char(32)
16 10
  • Lock holder or waiter
  • System 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 request
  • 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 the thread

    • Bit 1
33 21
    • Reserved
    • Bit 2
33 21
    • Waiting because this lock is not available
    • Bit 3
33 21
    • Thread in asynchronous wait for lock
    • Bit 4
33 21
    • Thread 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 (binary 0)
    • Bits 0-5
34 22
    • Lock is held by a process, thread, or transaction control structure other than the current process or thread, or lock is waited on by some other 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 total is supplied as input to the instruction and is not modified by the instruction. A total 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.

Locks may be implicitly applied by the machine (implicit lock is binary 1). If the implicit lock is held for a process or thread, a pointer to the associated process control space is returned in the lock holder or waiter field. If the implicit lock is held for a transaction control structure, a pointer to the associated transaction control structure is returned in the lock holder or waiter field. Locks held by the machine, but not related to a specific process, thread, or transaction control structure, cause the lock holder or waiter unopened thread handle, and thread ID fields to each be assigned a value of binary 0.

When a lock is held by a process or a thread, the system security level is 40 or greater, and the invoker of this instruction is a user state program, then the process control space system pointer associated with the lock will be returned in the lock holder or waiter field if the lock is held by the current thread or its containing process. This field will be set to binary 0 if the lock is held by some other process or thread, or if the lock is waited on by some other thread. When system security level 30 or less is in effect or when the invoking program is in system state, then the lock requestor field will always be returned with the appropriate process control space system pointer value (which may be binary 0 if the machine holds the lock).

When the invoker of this instruction is a user state program, then the unopened thread handle and thread ID fields will be returned if the lock is held or waited on by the current thread. These fields will be set to binary 0 if the lock is held by some other process, thread, or transaction control structure, or if the lock is waited on by some other thread. When the invoking program is in system state, then the unopened thread handle and thread ID fields will always be returned with the appropriate values (which may be binary 0 if the machine holds the lock or if a transaction control structure holds the lock).

Locks may be held by a transaction control structure. If lock scope object type has a value of transaction control structure, then the lock holder or waiter field will contain a system pointer to the transaction control structure that holds the lock and the unopened thread handle and thread ID fields will be assigned a value of binary 0. When a thread is waiting for a transaction control structure scope lock, the lock holder or waiter, unopened thread handle, and thread ID will identify the thread that is waiting for the lock.

The lock information will be set appropriately regardless of security level and program state.

Only a single lock state is returned for each lock state description.

A space pointer machine object cannot be specified for operand 2.

A lock state description for a lock held by a process or a transaction control structure will have a value of binary 0 for the unopened thread handle and for the thread id. A lock state description for a lock held by a thread will have the lock holder or waiter contain a system pointer to the process control space containing the thread, and a non-zero value for the unopened thread handle and for the thread ID to identify the specific thread within the process that is holding the lock. A lock state description for a lock being waited on will have the lock holder or waiter contain a system pointer to the process control space containing the waiting thread, and a non-zero value for the unopened thread handle and for the thread ID to identify the specific thread that is waiting for the lock.

The maximum number of locks that can be materialized with this instruction is 32,767. No exception will be signaled if more than 32,767 exist and only the first 32,767 locks found will be materialized.

Authorization Required

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