Call External (CALLX)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
0283 Program to be called or call template Argument list Return list
Operand 1: System pointer or space pointer data object.

Operand 2: Operand list or null.

Operand 3: Instruction definition list or null.

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release.

Description:

The instruction preserves 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 program which does not contain a program entry procedure, 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:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Call options Char(4)
0
0
  • Suppress adopted user profiles
    0 =
    No
    1 =
    Yes
  • Bit 0
0 0
  • Reserved (binary 0)
  • Bits 1-29
0
0
  • Prefer teraspace storage
    0 =
    No
    1 =
    Yes
  • Bit 30
0
0
  • Force thread state to user state for call
    0 =
    No
    1 =
    Yes
  • Bit 31
4 4 Reserved (binary 0) Char(12)
16 10 Program to be called System pointer
32
20
--- End ---
 

The suppress adopted user profiles call 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 prefer teraspace storage option specifies whether or not to give preference to the teraspace storage model when determining the target activation group on a call to a bound program with callers activation group, inherit or teraspace storage model and user state. This option is ignored for the following cases:

  • The call targets a bound program with different program attributes than listed above.
  • The call targets a non-bound program.
  • The thread execution state for the call is user state.

When prefer teraspace storage specifies yes, preference is given to the teraspace user-state default activation group when no invocation-associated activation group satisfies the target activation group requirement.

The force thread state to user state option specifies whether or not the call changes the state of the thread to user state.

Operand 2 specifies an operand list that identifies the arguments to be passed to the invocation entry to be called. If operand 2 is null, no arguments are passed by the instruction. 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.

Operand 3 specifies an instruction definition list (IDL) that identifies the instruction number(s) of alternate return points within the calling invocation. A Return External instruction in an invocation immediately subordinate to the calling invocation can indirectly reference a specific entry in the IDL to cause a return of control to the instruction associated with the referenced IDL entry. If operand 3 is null, then the calling invocation has no alternate return points associated with the call. If operand 3 is not null and operand 1 specifies a bound program, an invalid operation for program (hex 2C15) exception is signaled.

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 one greater than the invocation number of the calling invocation. This is merely a measure of the depth of the call-stack.
    • The invocation type is hex 01 to indicate a CALLPGM or CALLX 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 program call instruction after a return from the program.

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.

Following the allocation and initialization of the invocation entry, control is passed to the invoked program.

Authorization Required

  • Execute
    • Program referenced by 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
    • 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
    • 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