Interface validation exit

The Interface Validation Exit (INTFVAL) allows your exit routine to examine descriptive data for both caller and called at each external reference. The exit can perform audits, such as examining parameter passing conventions, the number of parameters, data types, and environments. It can accept the interface, rename the reference, or leave the interface unresolved.

When specifying this exit on STARTD, you provide the following information by means of the EXITS keyword:

The entry point address of the exit routine.
Optional user data that is passed directly to the exit without being processed by the binder. This is typically used as an address to dynamic storage when the binder is invoked by a reentrant program, but can be a counter or other data.
A third fullword that currently is not used.

The binder passes control to your exit routine at the completion of input processing, including autocall. This is before binding the module. If specified, the exit routine is invoked at three different points in binder processing, indicated by the function code passed to the exit:

'S': (Start) - Allows the exit routine to set up its environment and return a list of requested IDRs (product identifiers) to the binder.
'V': (Validate) - Allows the exit routine to validate all of the resolved and unresolved references from one section (CSECT) in the module to external labels in other sections.
'E': (End) - Invoked immediately prior to binding. Allows cleanup by the exit routine.

For each module being bound, Start will be called once, Validate will be called zero or more times, and End will be called once.

At the completion of autocall, the exit will be taken once for the Start function and once for each section in the module containing one or more unchecked external references. An external reference is unchecked if the signature in its ER record is either null (binary zeros) or does not match the signature in the LD.

An anchor word will be passed to the exit to provide for persistent storage between invocations. If the binder is invoked as a batch program, the anchor will be allocated and set to zero by the binder on invocation of the Start function; otherwise, the value passed to the binder on the STARTD exit specification will be passed through to the exit. If the exit routine provides its own dynamic storage, that address can be stored in the anchor word for addressability by subsequent invocations. No facilities will be available for trapping errors: If the exit fails, the binder fails. A message can be returned by the exit routine, however, to be printed by the binder.

The binder passes a parameter list to the exit routine. Register one contains the address of a list of addresses to the following data:

Function Code ('S', 'V' or 'E'). A 1-byte function code indicating Start, Validate or End, respectively.
Anchor Word. A 4-byte pointer variable for use by the exit.
Exit control. The character string passed on the exit specification. The character string is immediately preceded by a halfword length field.
Section name ('V' only). A varying string containing the name of the section being validated.
Section vaddr ('V' only). A 4-byte pointer to the beginning of the first text element in the section being validated. This might not be useful in a multiclass module, since there is no designated primary class. This field is reserved for future use.
Section IDRL. This parameter has a dual use, depending on the Function Code. On the Start ('S') call, the parameter is initialized to zero by the binder and optionally reset by the exit routine. On the Validate ('V') call, the binder sets the parameter to point to the IDR entry, if one is present, for the current section or to zero.
- ('S') A 4-byte pointer, initialized to zero by the binder and optionally reset to the address of an IDR list by the exit routine. The list, if specified, indicates those product identifiers of interest to the exit. If the list is not returned by the exit, the exit will be invoked for all sections. See below for a discussion of the IDR selection list.
- ('V') A 4-byte pointer, set by the binder, to the IDR entry for the section in process. The IDR data is preceded by a halfword length field.
Reference List ('V' only). A 4-byte pointer to a list of unchecked references. See below for a discussion of the reference list.
Return code. A fullword return code indicating the overall status of the exit. It will be initialized to zero on invocation of the exit.
Return codes from the exit routine are:
0

No further processing required of this section. The action code for all references is zero.

4

Further processing required by the binder, as indicated in the returned action codes.

12

Severe error. Make no more calls to the exit and do not save the module (unless LET=12).

16

Terminate binder processing immediately
Returned message. A 4-byte pointer to a varying string allocated by the exit and containing a message to be printed by the binder. The returned message must not be longer than 1000 bytes. The binder will prefix the returned message with its own message number.
The message will be initialized to the null string so that the exit routine need not take any action unless a message is issued.

The IDR selection list is built by the exit routine on the "Start" call and its address returned to the binder. The purpose of the list is to improve performance by limiting the number of exit invocations. If a section to be validated was compiled by a language product not on the list, or if no IDR information is available for that section, the exit will not be taken. Each entry in the list consists of:

A 4-byte address of another entry (zero indicates last entry)
A 2-byte length containing the number of IDR bytes to be compared (1-14)
A character string containing a substring of the product id, version and modification level. The string can contain a maximum of 14 bytes in the format ppppppppppvvmm.

The reference list is a linked list containing one entry for each unchecked ER in the section. References marked NOCALL or NEVERCALL will not be included in the list. The last entry in the list contains zero in the link field. A reference entry is 64 bytes in length and consists of the following fields:

OFF   TYPE      LEN   NAME          DESCRIPTION                   NOTES
---   --------  --- --------------  ----------------------------  -----
(0)   Address    4  REFL_NEXT       Address of next list entry      3
(4)   Address    4  REFL_T_SYMBOL   Address of referenced symbol    2
(8)   Address    4  REFL_T_SECTION  Address of target section name 2,8
(C)   Address    4  REFL_T_ELEMENT  Address of target element      1,8
(10)  Address    4  REFL_T_DESCR    Address of target descriptors  1,8
(14)  Address    4  REFL_T_IDR      Address of target IDR         1,5,8
(18)  Bit        4  REFL_T_ENVIR    Target environment            1,6,8
(1C)  Character  8  REFL_T_SIGN     Target signature                8
(24)  Address    4  REFL_T_ADCONS   Adcon list anchor               1
(28)  Address    4  REFL_C_DESCR    Address of caller descriptors   1
(2C)  Bit        4  REFL_C_ENVIR    Caller's environment           1,6
(30)  Character  8  REFL_X_SIGN     Exit signature                 4,9
(38)  Address    4  REFL_X_SYMBOL   New symbol (Char(*) varying)  4,7,9
(3C)  Unsigned   2  REFL_X_ACTION   Action code                    4,9
(3E)  Unsigned   2                  Reserved                        1

Notes:
  1   Must be zero.
  2   Points to varying character string.  String must begin with a
      halfword length field containing current length, excluding length
      field.
  3   Last entry in list set to zero.
  4   Output field.  Set by exit routine.
  5   IDR data is returned in the following format:
        0  CHAR    10  Processor Identification
       10  CHAR     2  Processor Version
       12  CHAR     2  Processor Modification Level
       14  CHAR     7  Date Compiled or Assembled (yyyyddd)
      The above 21-byte structure is preceded by a halfword length.
      The length can contain zero or any multiple of 21, allowing
      for multiple IDRs.
  6   Environmental bit settings are not yet defined.
  7   The exit routine must allocate and initialize a varying length
      character string, consisting of a halfword length field,
      containing the length of the symbol, immediately followed
      by the symbol itself.  The address of this varying string
      must be stored in the REFL_X_SYMBOL field in the reference
      list.
  8   Target fields will contain binary zeros for unresolved references
  9   Output fields will be initialized to binary zeros on invocation
      of the exit routine.
 10   Referenced symbol or section is in the following format:
              0   BIN    2    Length of name field.
              2   CHAR   *    Name.

Action codes set for each reference include the following:

0: No special processing required for this reference, such as changing the bind status flags, renaming the reference or storing signatures.
1: Validation successful. Store the exit signature in both LD and ER records.
2: Validation successful. Store glue code address in all referring adcons and store the exit signature in both LD and ER records.
3: Accept unresolved reference. Do not store the exit signature in the ER record. Reference will be treated as a weak reference and will not affect the return code from the binder.
4: Retry. New symbol has been provided for reference. Do not store signatures at this time. Reprocess autocall, if necessary, and revalidate.
5: Validation failed. Mark reference unresolved and do not store signatures at this time. The return code from the binder will reflect that there was at least one unresolved reference.

Post Processing:

On return from the exit, the binder will take the action described by the action code for each external reference. If the action code is 1 or 2, the signature returned by the exit will be stored, if nonzero, in both ER and LD, so that the interface will not be reexamined on a subsequent invocation. If the exit elects to rename a reference, the symbol will be changed FOR THAT REFERENCE ONLY. If the renamed reference cannot be resolved from labels already present in the module, another autocall pass will be required.

The exit routine should always return some kind of signature to the binder, if the interface is valid, so that the same reference does not get revalidated on subsequent passes. If the input signature is not null (binary zeros) return it to the binder; otherwise, return any 8-byte string (for example, date/time), which will then be saved in the LD and ER records. The signature can consist of any characters. The binder map, if requested, will indicate those sections that were included as a result of one or more renamed references. The flag position in the map, which normally contains an asterisk for autocalled sections, will be reset to "R". There will be no indication as to the number and location of such renamed references nor their original names.

Default Exit Routine:

In the absence of an interface exit specification, the binder will default the exit processing. During default validation, the binder will examine each resolved ER - LD pair, checking the following:

Compare the text type expected (ER) with that of the target (LD). Fifteen text types are supported by the binder, and can be passed in the ER and LD records via the binder API or the new object module (GOFF):
```
  0 - unspecified
  1 - data
  2 - instructions
  3-15 - for translator use
```
If the text type for either caller or called is unspecified, or if the two text types are equal, the interface is considered valid.
Compare the signature fields. If either is unspecified (binary zeroes) or if they match, the interface will be considered valid.

If either result is not valid, a warning message will be issued by the binder and the return code set to 4. The reference remains resolved, however.