Verbs and Built-in Functions › &NDBPHON › &NDBPHON Exit Call Details

&NDBPHON Exit Call Details

NDB can invoke a user exit when the &NDBPHON built-in function is called with the USER option.

The exit that is called is determined by the setting of the NDBPHONX SYSPARM. If no exit is set, then a syntax error results.

When the NDBPHONX SYSPARM nominates an exit, the exit is loaded. Any previous exit is deleted. (NDBPHONX=NO will delete any old exit without loading a new one).

When an &NDBPHON USER built-in function is executed, and the user supplied data is not null, then this exit is invoked as follows:

• It is called under the main task for your product region and so must not issue O/S waits, because this will impact other processing.
• The user interface is as follows:
  • R1: Pointer to parameter list (described later).
  • R13: Standard 72-byte save area.
  • R14: Return address.
  • R15: Entry point.
  • AM: 31 in MVS/XA or MVS/ESA.
• Parameter list:

  A(PARM1)

  A(PARM2)

  A(PARM3)

  A(PARM4)

  A(PARM5)

  A(PARM6) with high bit set on

  • PARM1 is a fullword function code. 0 (decimal) is &NDBPHON USER. You should allow for function codes 4, 8, and 12 for the future and return r15=0 for them.
  • PARM2 is a fullword containing the source data length. It will contain a value from 1 to 256. This length excludes leading and trailing blanks.
  • The source data. This is a 256-character area. The source data is placed here, uppercased, and padded to 256 with blanks.
  • PARM4 is a fullword, initialized to 0, that the exit must update with the length of the returned phonetic translation. A length of 0 to 256 must be set.
  • PARM5 is a 256-character area, initialized to blanks, that must be set to the return phonetic translation.
  • PARM6 is a 256-byte work area, initialized to binary 0. This area is used by the exit as required.

The exit must return r15=0 and set PARM4 and PARM5 as appropriate if it can perform the conversion. If it returns r15 not 0, the NCL process is aborted.

Important! The exit is called from under the MAINTASK for your product region. It must not issue any O/S waits, because these will severely impact processing in your region.

A sample exit, PHONEX01, is provided. It illustrates the parameter list usage. It implements the same SOUNDEX algorithm as &NDBPHON SOUNDEX uses.

If the exit abends, your product region will abend.