Materialize Object Locks (MATOBJLK)


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
Char(1)



(1 = yes)


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
Char(1)



(1 = yes)


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
Char(1)



(1 = yes)


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



(repeated number of lock state descriptions times)


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


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

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

36 Space Management

38 Template Specification

44 Protection Violation