Materialize Allocated Object Locks (MATAOL)


Op Code (Hex) Operand 1 Operand 2

03FA Receiver Designated lockable item

Operand 1: Space pointer.

Operand 2: System pointer or space pointer

Bound program access
Built-in number for MATAOL is 48.
MATAOL (
        receiver                   : address
        designated_lockable_item   : address of system pointer OR
                                     address of space pointer(16)
)

Description

This instruction materializes the current allocated locks on a designated lockable item. If operand 2 is a system pointer, the current allocated locks on the object identified by the system pointer specified by operand 2 are materialized into the template specified by operand 1. If operand 2 is a space pointer, the current allocated locks on the specified space location are materialized into the template specified by operand 1. The materialization template identified by operand 1 must be 16-byte aligned. 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
Reserved (binary 0)
Char(2)
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
System pointer
32 20
Lock state
Char(1)



Hex 80 = LSRD lock request
Hex 40 = LSRO lock request
Hex 20 = LSUP lock request
Hex 10 = LEAR lock request
Hex 08 = LENR lock request

All other values are reserved



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 (binary 0)
Bits 2-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)



A value of 1 in the corresponding bit indicates the condition is true:


34 22
Reserved (binary 0)
Bits 0-5
34 22
Lock is held by some 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 eight 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. Other than the materialization length invalid  (hex 3803) exception, no exceptions are signaled should the receiver contain insufficient area for the materialization. As a result, the number of lock descriptions may be more than the number of lock descriptors that follow, since an insufficient area was provided to return the descriptors.

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 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 field. Locks held by the machine, but not related to a specific process, thread, or transaction control structure, cause the lock holder, unopened thread handle, and thread ID fields to each be assigned a value of binary 0.

When the 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 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. When system security level 30 or less is in effect or when the invoking program is in system state, then the lock holder 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).

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

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

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

The lock scope field has no meaning if lock held by a process, thread or transaction control structure is binary 0.

A lock state description for a lock held by a process 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 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.

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 by the current thread. These fields will be set to binary 0 if the lock is held by some other process or 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).

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.

If operand 2 is a space pointer to a teraspace storage location, it is interpreted within the process in which the current thread is executing.

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

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation