Find Relative Invocation Number (FNDRINVN)

Operand 2: Character(48) scalar or null.

Operand 3: Space pointer.

Built-in number for FNDRINVN is 124.
FNDRINVN (
          relative_invocation_number   : address of signed binary(4)
          search_range                 : address OR
                                         null operand
          search_criterion_template    : address
)

Description

The invocations identified by operand 2 are searched in the order specified by operand 2 until an invocation is found which satisfies the search criterion specified in the operand 3 template. The identity of the first invocation (in search order) to satisfy the search criterion is returned in operand 1. If no invocation in the specified range satisfies the search criterion, then either an exception is signaled, or a value of zero is returned in operand 1, depending on the modifiers specified in the operand 3 template.

Operand 1 is returned as a signed binary(4) value identifying the first invocation found that satisfies the specified search criterion. It is specified relative to the starting invocation identified by operand 2. A positive number indicates a displacement in the direction of newer invocations, while a negative number indicates a displacement in the direction of older invocations. A zero value can either indicate that no invocation in the specified range matched the specified criterion, or the starting invocation satisfied the specified criterion, depending on the modifiers specified in the operand 3 template. Operand 1 is not modified in the event that the instruction terminates with an exception.

Note that a modifier in the operand 3 template determines if the starting invocation identified by operand 2 is to be skipped. If the starting invocation is specified to be skipped during the search then a result of zero in operand 1 indicates failure to find an invocation that satisfies the criterion. If the starting invocation is specified not to be skipped, then a result of zero indicates the starting invocation has satisfied the specified criterion. If the starting invocation is specified not to be skipped and no invocation is found that satisfies the search criterion, an exception will be signaled.

Operand 2 identifies the starting invocation and the range of the search. If operand 2 is specified as a null operand, then operand 2 is assumed to identify a range starting with the current invocation and proceeding through all existing older invocations.

Operand 3 is a space pointer to a template that identifies the search criterion and search modifiers for the find operation.

Operand 2

The value specified by operand 2 identifies the range of invocations to be searched. This operand can be null (which indicates the range which starts with the current invocation and proceeds through all existing older invocations), or it can contain either an invocation pointer to an invocation or a null pointer (which indicates a range starting with the current invocation).

Operand 2 has the following format:

If a non-null pointer is specified for starting invocation pointer, then operand 2 must be 16-byte aligned in the space.

Terminology

Field descriptions

Starting invocation offset

A signed numerical value indicating an invocation relative to the invocation located by the starting invocation pointer. A value of zero denotes the invocation addressed by the starting invocation pointer, with increasingly positive numbers denoting increasingly later invocations in the stack, and increasingly negative numbers denoting increasingly earlier invocations in the stack.

If the starting invocation pointer is valid or null, but the invocation identified by this offset does not exist in the stack, an invocation offset outside range of current stack  (hex 2C1A) exception will be signaled.

Originating invocation offset

This field is used by other instructions but is ignored by FNDRINVN.

Invocation range

Invocation range is a signed numerical value which specifies the direction of the search and the maximum number of invocations to be examined. The magnitude of invocation range specifies the maximum number of invocations to be searched exclusive of the starting invocation. It is not an error if this magnitude is greater than the number of existing invocations in the specified direction. If the sign of invocation range is positive (and non-zero), the search is performed in the direction of newer invocations, while if the sign is negative, the search is performed in the direction of older invocations.

Note that the bypass starting invocation modifier in operand 3 affects how the starting invocation is treated. If this modifier is binary 0, then the starting invocation is the first invocation examined. If invocation range is zero in this case then only the starting invocation is examined. If, on the other hand, bypass starting invocation is binary 1, then the starting invocation does not participate in the search, and, if invocation range is zero, no invocations are searched and a value of zero is returned for operand 1.

Starting invocation pointer

An invocation pointer to an invocation. If null, then the current invocation is indicated. If not null, then operand 2 must be 16-byte aligned in the space.

If the pointer identifies an invocation in another thread, a process object access invalid  (hex 2C11) exception will be signaled. If the invocation identified by this pointer does not exist in the stack, an object destroyed  (hex 2202) exception will be signaled.

Operand 3

The search criterion template identified by operand 3 must be aligned on a 16-byte boundary. The template is a 32-byte value with the following format:

Search option

Specifies the invocation attribute to be examined:

1	Routine type. Search argument is a one-byte routine type, left aligned. Allowed search argument values are: Hex 01 = Non-Bound Program Hex 02 = Bound Program Entry Procedure (PEP) Hex 03 = Bound Program Procedure Note: Bound program procedures are contained within bound programs, bound service programs, and Java™ programs. All discussion of bound program procedure semantics also apply to Java program procedures.
2	Invocation type. Search argument is a one-byte invocation type, left aligned. Allowed search argument values are: Hex 01 = Call external Hex 02 = Transfer control Hex 03 = Event handler Hex 04 = External exception handler (for non-bound program) Hex 05 = Initial program in process problem state Hex 06 = Initial program in process initiation state Hex 07 = Initial program in process termination state Hex 08 = Invocation exit (for non-bound program) Hex 09 = Return or return/XCTL trap handler Hex 0A = Call program Hex 0B = Cancel handler (bound program only) Hex 0C = Exception handler (bound program only) Hex 0D = Call bound procedure/call with procedure pointer Hex 0E = Process Default Exception Handler
3	Invocation status. Search argument consists of two four-byte fields, left aligned. The invocation status of each examined invocation is ANDed with the first field and then compared to the second field.
4	Invocation mark. Search argument is a four-byte invocation mark, left aligned. If the search is in the direction of older invocations, the result identifies the first invocation found with an invocation mark less than or equal to the search argument. If the search is in the direction of newer invocations, the result identifies the first invocation found with an invocation mark greater than or equal to the search argument. If invocation range is zero, then the search is satisfied only if the invocation mark of the starting invocation exactly matches the search argument, and this can occur only if bypass starting invocation is binary 0. For this option compare for mismatch is ignored.
5	Activation mark. Search argument is a four-byte activation mark, left aligned. The activation mark of the program or module activation corresponding to each examined invocation is compared to search argument. Invocations with no activation (ie, the invocations of non-bound reentrant programs, and the invocation stack base entry) are considered to have an activation mark of binary 0.
6	Activation group mark. Search argument is a four-byte activation group mark, left aligned. The activation group mark of each examined invocation is compared to search argument. The activation group mark of each examined invocation is determined from the activation associated with the invocation. (Each activation belongs to a single activation group.) However, if no activation exists for the invocation, or if an activation exists and it belongs to an shared activation group owned by another process then, the activation group mark for the examined invocation is taken to be, 1 for a system-state invocation 2 for a user-state invocation
7	Program pointer. Search argument is a system pointer to a program. The program corresponding to each examined invocation is compared to the program identified by the pointer.
8	Invocation mark. Search argument is an eight-byte invocation mark, left aligned. If the search is in the direction of older invocations, the result identifies the first invocation found with an invocation mark less than or equal to the search argument. If the search is in the direction of newer invocations, the result identifies the first invocation found with an invocation mark greater than or equal to the search argument. If invocation range is zero, then the search is satisfied only if the invocation mark of the starting invocation exactly matches the search argument, and this can occur only if bypass starting invocation is binary 0. For this option compare for mismatch is ignored.
9	Activation mark. Search argument is an eight-byte activation mark, left aligned. The activation mark of the program or module activation corresponding to each examined invocation is compared to search argument. Invocations with no activation (ie, the invocations of non-bound reentrant programs, and the invocation stack base entry) are considered to have an activation mark of binary 0.
10	Activation group mark. Search argument is an eight-byte activation group mark, left aligned. The activation group mark of each examined invocation is compared to search argument. The activation group mark of each examined invocation is determined from the activation associated with the invocation. (Each activation belongs to a single activation group.) However, if no activation exists for the invocation, or if an activation exists and it belongs to a shared activation group owned by another process then, the activation group mark for the examined invocation is taken to be, 1 for a system-state invocation 2 for a user-state invocation

Bypass starting invocation

If bypass starting invocation is binary 0, then the starting invocation specified by operand 2 is the first invocation examined. In this case, if the invocation range of operand 2 is exhausted without satisfying the search criterion then a template value invalid  (hex 3801) exception is signaled, with the search argument field of operand 3 identified as the erroneous field.

If bypass starting invocation is binary 1, then the starting invocation specified by operand 2 is skipped, and a failure to satisfy the search criterion is indicated by returning a binary 0 value in operand 1.

Compare for mismatch

If compare for mismatch is binary 0, then the search criterion is satisfied when an invocation is found whose attribute matches the search argument. If compare for mismatch is binary 1, however, then the search criterion is satisfied when an invocation is found whose attribute does not match the search argument.

Search argument

A value of between one and 16 bytes as described above. Unused bytes are ignored.

Authorization Required

• None

Lock Enforcement

• None

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range

08 Argument/Parameter

• 0801 Parameter Reference Violation

10 Damage Encountered

• 1004 System Object Damage State
• 1044 Partial System Object Damage

16 Exception Management

• 1603 Invalid Invocation Address

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded

1E Machine Observation

• 1E02 Invocation Not Found

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2202 Object Destroyed
• 2203 Object Suspended
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

2C Program Execution

• 2C11 Process Object Access Invalid
• 2C1A Invocation Offset Outside Range of Current Stack

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

• 3203 Scalar Value Invalid

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
• 4402 Literal Values Cannot Be Changed