Transfer Object Lock (XFRLOCK)


Op Code (Hex) Operand 1 Operand 2

0382 Receiving process control space Lock transfer template

Operand 1: System pointer.

Operand 2: Space pointer.

Bound program access
Built-in number for XFRLOCK is 54.
XFRLOCK (
         receiving_process_control_space   : address of system pointer
         lock_transfer_template            : address
)

Description

Locks designated in the lock transfer template (operand 2) are either allocated to the receiving process (operand 1), the thread identified within the lock transfer template, or to the transaction control structure attached to the thread issuing this instruction. Upon completion of the transfer lock request, the current process, thread, or transaction control structure no longer holds the transferred lock(s).

Operand 2 identifies the objects and the associated lock states that are to be transferred to the receiving process, or to the receiving thread, or to the transaction control structure attached to the thread issuing this instruction. The space contains a system pointer to each object that is to have a lock transferred and a byte which defines whether this entry is active. If the entry is active, the space also contains the lock states to be transferred. Operand 2 must be aligned on a 16-byte boundary. The format is as follows:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Number of lock transfer requests in template
Bin(4)
4 4
Offset to lock state selection bytes
Bin(2)
6 6
Reserved
Char(8) +
14 E
Transfer lock options
Char(2)
14 E
Reserved
Bits 0-6 +
14 E
Template extension specified
Bit 7



0 = Template extension is not specified.
1 = Template extension is specified.


14 E
Lock scope
Bit 8



0 = Transfer lock scope object type locks.
1 = Transfer thread scoped locks.


14 E
Lock scope object type
Bit 9



0 = Process containing the current thread.
1 = Transaction control structure attached to the current thread.


14 E
Change lock scope
Bit 10



0 = No.
1 = Yes.


14 E
Reserved (binary 0)
Bits 11-15
16 10
--- End ---

The transfer lock template extension is only present if template extension specified is indicated above. Otherwise, the object lock(s) to be transferred should immediately follow.

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Transfer lock template extension
Char(16)
0 0
Extension options
Char(1)
0 0
Reserved
Bits 0-2 +
0 0
New lock scope
Bit 3



0 = Lock scope is lock scope object type.
1 = Lock scope is to the current thread.


0 0
Lock scope object type
Bit 4



0 = Process containing the current thread.
1 = Transaction control structure attached to the current thread.


0 0
Reserved
Bits 5-7 +
1 1
Extension area
Char(15)
1 1
Reserved
Char(8) +
9 9
Reserved (binary 0)
Char(3)
12 C
Open thread handle
UBin(4)
16 10
Object lock(s) to be transferred
[*] System pointer



(repeated as specified by number of lock transfer requests in template above)


* *
--- End ---

The lock state selection is located by adding the offset to lock state selection bytes above to operand 2.

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Lock state selection
[*] Char(1)



(repeated for each pointer in the template)


0 0
Lock state to transfer. Only one state may be requested per entry. (1 = transfer)
Bits 0-4
0 0
LSRD
Bit 0
0 0
LSRO
Bit 1
0 0
LSUP
Bit 2
0 0
LEAR
Bit 3
0 0
LENR
Bit 4
0 0
Reserved (binary 0)
Bit 5 +
0 0
Lock count
Bit 6



0 = The current lock count is transferred.
1 = A lock count of 1 is transferred.


0 0
Entry active indicator
Bit 7



0 = Entry not active. This entry is not used.
1 = Entry active. This lock is transferred.


* *
--- End ---

Note: Fields indicated by a plus sign (+) are ignored by the instruction.

Locks to be transferred in one instruction must be either all process scoped, all thread scoped, or all transaction control structure scoped. Process scoped locks may be transferred from the process containing the current thread to the receiving process or to the transaction control structure that is attached to the current thread. Thread scoped locks may be transferred from the current thread to either the initial thread of the process associated with the receiving process control space, the thread specified by the open thread handle field in the transfer lock template extension, or to the transaction control structure attached to the current thread. Transaction control structure scoped locks may be transferred from the transaction control structure attached to the current thread to either the process containing the current thread or the current thread.

The lock scope for a lock held on an object may be changed. When change lock scope has a value of no, the following lock transfers are permitted:

When change lock scope has a value of no, the new lock scope and lock receiver object type fields in the template extension are ignored.

When change lock scope has a value of yes, the template extension must be present. If the template extension is not present, a template value invalid  (hex 3801) exception is signaled.

When change lock scope is specified, then locks may either be transferred between the transaction control structure attached to the current thread and the current thread or the process containing the current thread, the process containing the current thread and the transaction control structure attached to the current thread or the current thread, or the current thread and the process containing the current thread or the transaction control structure attached to the current thread. Table 1 defines the permissible lock transfers when change lock scope is specified.

Table 1. Change Lock Scope

Current Lock Scope New Lock Scope
Process1 Transaction control structure2 Thread
Process3 Transaction control structure4
Process1 Ignored Allowed Allowed Allowed
Transaction control structure2 Allowed Ignored Allowed Allowed
Thread/Process3 Allowed Allowed Ignored Allowed
Thread/Transaction control structure4 Allowed Allowed Allowed Ignored
Notes:

1

Lock scope is process containing the current thread.

2

Lock scope is transaction control structure attached to the current thread.

3

Lock scope is thread with the process containing the current thread as the logical parent for lock conflict checking.

4

Lock scope is thread with the transaction control structure attached to the current thread as the logical parent for lock conflict checking.

When change lock scope has a value of yes, the receiving process identified by operand 1 and the open thread handle are ignored.

If the receiving process control space (operand 1) does not reference an active process, the process control space not associated with a process  (hex 2802) exception is signaled and no locks are transferred. If the receiving thread identified by the open thread handle does not reference an active thread, the thread handle not associated with an active thread  (hex 2804) exception is signaled and no locks are transferred.

If either lock scope object type or lock receiver object type has a value of transaction control structure attached to the current thread and a transaction control structure is not attached to the current thread, an object not available to process  (hex 2205) exception is signaled. If lock receiver object type has a value of transaction control structure attached to the current thread and the transaction control structure state does not allow objects to be locked on behalf of the transaction control structure, a object not eligible for operation  (hex 2204) exception is signaled.

If a thread contained by the receiving process is issuing the instruction to transfer process scoped locks, then no operation is performed, and no exception is signaled. If the thread issuing the instruction is the receiver of the transferred thread scoped locks, then no operation is performed, and no exception is signaled. If the transaction control structure attached to the current thread is the receiver of transaction control structure scoped locks, then no operation is performed, and no exception is signaled.

The lock count transferred is either the current lock count held by the transferring process, thread or transaction control structure or a count of 1. If the receiving process, thread or transaction control structure already holds an identical lock, then the final lock count is the sum of the count originally held by the receiving process, thread or transaction control structure and the transferred count.

Only process scoped locks currently allocated to the process containing the thread issuing the instruction or thread scoped locks currently allocated to the thread issuing the instruction or the transaction control structure attached to the thread issuing the instruction can be transferred. If the transfer of an allocated lock would result in the violation of the lock allocation rules, then the lock cannot be transferred. An implicit lock may not be transferred.

No locks are transferred if an entry in the template is invalid.

The locks specified by operand 2 are transferred sequentially and individually. If one lock cannot be transferred because the process or thread does not hold the indicated lock on the object, then exception data is saved to identify the lock that could not be transferred. Processing of the next lock to be transferred continues.

If any lock was not transferred, the invalid object lock transfer request  (hex 1A04) exception is signaled.

When an object lock is transferred, the transferring thread or its containing process or the transaction control structure attached to the thread synchronously loses the record of the lock, and the object is locked to the receiving process, thread or transaction control structure. However, the receiving thread obtains the lock asynchronously after the instruction currently being executed in that thread is completed. If the target is a process, the receiving process obtains the lock asynchronously after the instruction currently being executed in the initial thread of that process is completed. The receiving transaction control structure obtains the locks before the completion of this instruction. If the transferring process, thread or transaction control structure holds multiple locks for the object, any lock states not transferred are retained in the process, thread or transaction control structure.

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

28 Process/Thread State

2E Resource Control Limit

36 Space Management

38 Template Specification

44 Protection Violation