Transfer Control (XCTL)

Operand 1: System pointer or space pointer data object.

Operand 2: Operand list or null.

Description

The instruction destroys the calling invocation and passes control to either the program entry procedure of a bound program or the external entry point of a non-bound program. If operand 1 specifies a Java™ program or a bound service program, an invalid operation for program  (hex 2C15) exception is signaled.

Operand 1 may be specified as a system pointer which directly addresses the program that is to receive control or as a space pointer to a call template which identifies the program to receive control. Specifying a template allows for additional controls over how the specified program is to be invoked. The format of the call template is the following:

The suppress adopted user profiles option specifies whether or not the program adopted and propagated user profiles which may be serving as sources of authority to the thread are to be suppressed from supplying authority to the new invocation. Specifying yes causes the propagation of adopted user profiles to be stopped as of the calling invocation, thereby, not allowing the called invocation to benefit from their authority. Specifying no allows the normal propagation of adopted and propagated user profiles to occur. The called program may adopt its owning user profile, if necessary, to supplement the authority available to its invocation.

The force thread state to user state for transfer option specifies whether or not the transfer control needs to be done in the current thread state or change the thread state to user state.

Operand 2 specifies an operand list that identifies the arguments to be passed to the invocation to which control is being transferred. Automatic objects allocated by the transferring invocation are destroyed as a result of the transfer operation and, therefore, cannot be passed as arguments. An argument list length violation  (hex 0802) exception is signaled if the number of arguments passed does not correspond to the number required by the parameter list of the target program.

If the transferring invocation has an activation, the invocation count is decremented by 1.

If the transferring invocation has received control to process an exception, or an invocation exit, the return instruction invalid  (hex 2C01) exception is signaled.

If the transferring invocation currently has an invocation exit set, the invocation exit is not given control and is implicitly cleared.

Common Program Call Processing

The details of processing differ for non-bound and bound programs. The following outlines the common steps.

1. A check is made to determine if the caller has authority to invoke the program and that the object is indeed a program object. The specified program must be either a bound program that contains a program entry procedure or a non-bound program.

2. The activation group in which the program is to be run is located or created if it doesn't exist.

3. If the program requires an activation entry and it is not already active within the appropriate activation group, it is activated. Bound programs always require an activation; non-bound programs require an activation only if they use static storage. The invocation count of a newly created activation is set to 1 while the invocation count of an existing activation is incremented by 1.

4. The invocation created for the target program has the following attributes (as would be reported via the Materialize Invocation Attributes (MATINVAT) instruction.)

   • The invocation mark is at least one higher than any previous invocation within the thread. The invocation mark value is generated from the thread mark counter and is unique within the thread. There is no relationship between the values of the invocation mark and the marks of the activation or activation group associated with the invocation.

   • The invocation number is the same as the invocation number of the transferring invocation.

   • The invocation type is hex 02 to indicate a XCTL type of invocation.

5. The automatic storage frame (ASF), if required, is allocated on a 16-byte boundary.

6. Control is transferred to the program entry procedure (or external entry point) of the program.

7. Normal flow-of-control resumes at the instruction following the caller of the program issuing the XCTL instruction.

The details of locating the target activation group and activating the program differ depending upon the model of the program.

Bound Program

A bound program is activated and run in an activation group specified by program attributes. There are two logical steps involved:

• locate the existing, or create a new activation group for the program

• locate an existing, or create a new activation entry for the program within the activation group

After locating the activation entry for the program, control is passed to the program entry procedure for the program. If required, the activation group is destroyed when the invocation for the program entry procedure is destroyed.

Non-bound Program

The automatic storage frame begins with a 64 byte header. If the program defines no automatic data items the frame consists solely of the 64-byte header, otherwise the automatic storage items are located immediately following the header. In prior releases of the machine, this header contained invocation information which is now available via the Materialize Invocation Attributes (MATINVAT) instruction. This header is not initialized and the contents of the header are not used by the machine. (The space is allocated merely to provide for compatibility with prior implementations of the machine.) The update PASA stack program attribute, supported in prior implementations of the machine, is no longer meaningful and is ignored, if specified as an attribute of the program.

Authorization Required

• Execute

  • Operand 1

  • 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
• 0802 Argument List Length 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

• 1C02 Program Limitation Exceeded
• 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

2A Program Creation

• 2AB5 Observable Information Necessary For Retranslation Not Encapsulated

2C Program Execution

• 2C01 Return Instruction Invalid
• 2C15 Invalid Operation for Program
• 2C1D Automatic Storage Overflow
• 2C1E Activation Access Violation
• 2C1F Program Signature Violation
• 2C20 Static Storage Overflow
• 2C21 Program Import Invalid
• 2C22 Data Reference Invalid
• 2C23 Imported Object Invalid
• 2C24 Activation Group Export Conflict
• 2C25 Import Not Found
• 2C2A Argument Optimization Interface Error

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

36 Space Management

• 3601 Space Extension/Truncation

38 Template Specification

• 3801 Template Value Invalid

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation