org.rexxla.bsf.engines.rexx

## Class AbstractExitHandler

- java.lang.Object
- - org.rexxla.bsf.engines.rexx.AbstractExitHandler

- All Implemented Interfaces:
    RexxExitHandler, RexxHandler

      public abstract class AbstractExitHandler
      extends java.lang.Object
      implements RexxExitHandler

  Make it easy for Rexx programs to implement direct command handlers in Rexx. :)
  Since:
    850 (2022-08-30)

- - ### Field Summary

    - ### Fields inherited from interface org.rexxla.bsf.engines.rexx.RexxExitHandler

      `RX_EXIT_NAMES, RXCMD, RXCMDHST, RXENDLST, RXEXF, RXEXFCAL, RXEXIT_HANDLED, RXEXIT_NOT_HANDLED, RXEXIT_RAISE_ERROR, RXFNC, RXFNCCAL, RXHLT, RXHLTCLR, RXHLTTST, RXINI, RXINIEXT, RXMSQ, RXMSQNAM, RXMSQPLL, RXMSQPSH, RXMSQSIZ, RXNOOFEXITS, RXNOVAL, RXNOVALCALL, RXOFNC, RXOFNCCAL, RXSIO, RXSIODTR, RXSIOSAY, RXSIOTLL, RXSIOTRC, RXSIOTRD, RXTER, RXTEREXT, RXTRC, RXTRCTST, RXVALUE, RXVALUECALL, version`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractExitHandler()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract int` | `handleExit(java.lang.Object slot, int exitNumber, int subFunction, java.lang.Object[] parmBlock)` Exit handler signature (called via native code) according to the ooRexx API documentation in `rexxpg.pdf`.
    `static void` | `main(java.lang.String[] args)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.rexxla.bsf.engines.rexx.RexxHandler

      `checkCondition, clearCondition, dropContextVariable, getAllContextVariables, getCallerContext, getConditionInfo, getContextVariable, getGlobalEnvironment, getInterpreterVersion, getLanguageLevel, getLocalEnvironment, getNil, haltThread, newArray, newDirectory, newStem, newStringTable, raiseCondition, raiseException, raiseException0, raiseException1, raiseException2, setContextVariable, setContextVariableToNil, setThreadTrace`

- - ### Constructor Detail

    - #### AbstractExitHandler

          public AbstractExitHandler()

  - ### Method Detail

    - #### main

          public static void main(java.lang.String[] args)

    - #### handleExit

          public abstract int handleExit(java.lang.Object slot,
                                         int exitNumber,
                                         int subFunction,
                                         java.lang.Object[] parmBlock)

      Description copied from interface: `RexxExitHandler`
      Exit handler signature (called via native code) according to the ooRexx API documentation in `rexxpg.pdf`.

      The following documents briefly the `parmBlock`-array that gets supplied to the Java exit handler, depending on the exit number and subfunction. Please refer also to the ooRexx documentation "rexxpg.pdf", section entitled "Context Exit Definitions" on which this implementation is based upon.

      Exit name/number | subfunction name/number | Description
      --- | --- | ---
      `RXFNC/2` | `RXFNCCAL/1` | Processes calls to external functions. `parmBlock`:
      `[0] rxfnc_flags`, type: `boolean[]` `[0] rxfferr`, settable ("invalid call to routine") `[1] rxffnfnd`, settable ("function not found") `[2] rxffsub`, if `true` then called as subroutine, else as function
      `[1] rxfnc_name`, subroutine/function name, type: `String`
      `[2] rxfnc_que`, current queue name, type: `String`
      `[3] rxfnc_argv`, supplied arguments, type: `Object[]`, can be `null`
      `[4] rxfnc_retc`, return value by handler, if any, type: `String`
      `RXCMD/3` | `RXCMDHST/1` | Calls a named subcommand handler. `parmBlock`:
      `[0] rxfnc_flags`, type: `boolean[]` `[0] rxffail`, settable ("command failed (trap FAILURE condition)") `[1] rxffcerr`, settable ("command raises an error (trap ERROR condition)")
      `[1] rxcmd_address`, address name, type: `String`
      `[2] rxcmd_dll`, DLL name, if handler is in a DLL, empty string else, type: `String`
      `[3] rxcmd_command`, command, type: `String`
      `[4] rxcmd_retc`, return value by handler, if any, type: `String`
      `RXMSQ/4` | `RXMSQPLL/1` | Pulls a line from the external data queue. `parmBlock`:
      `[0] rxmsq_retc`, return value by handler, if any, type: `String`
      | `RXMSQPSH/2` | Places a line in the external data queue. `parmBlock`:
      `[0] rxfnc_flags`, type: `boolean[]` `[0] rxfmlifo`, if set `LIFO (QUEUE)`, if `false FIFO (PUSH)`
      `[1] rxmsq_value`, entry to be pushed/queued, type: `String`
      | `RXMSQSIZ/3` | Returns the number of lines in the external data queue. `parmBlock`:
      `[0] rxmsq_size`, number of lines in queue, type: `String`
      | `RXMSQNAM/20` | Sets the name of the active external data queue. `parmBlock`:
      `[0] rxmsq_name`, new external data queue name, type: `String`
      `RXSIO/5` | `RXSIOSAY/1` | Writes a line to the standard output stream. `parmBlock`:
      `[0] rxsio_string`, string to display, type: `String`
      | `RXSIOTRC/2` | Writes trace and error message output to the standard error stream. `parmBlock`:
      `[0] rxsio_string`, trace line to display, type: `String`
      | `RXSIOTRD/3` | Reads from standard input stream. `parmBlock`:
      `[0] rxsiotrd_retc`, return value by handler, if any, type: `String`
      | `RXSIODTR/4` | Interactive debug input. `parmBlock`:
      `[0] rxsiodtr_retc`, return value by handler, if any, type: `String`
      `RXHLT/7` | `RXHLTCLR/1` | Clears the HALT condition. `parmBlock`:
      `[0] rxhlt_flags`, type: `boolean[]` `[0] rxfhhalt`, settable, if set to `true`, the `HALT` condition will be cleared
      | `RXHLTTST/2` | Tests the halt indicator. `parmBlock`:
      `[0] rxhlt_flags`, type: `boolean[]` `[0] rxfhhalt`, settable, if set to `true`, the `HALT` condition will be raised
      `RXTRC/8` | `RXTRCTST/1` | Tests the external trace indicator. `parmBlock`:
      `[0] rxtrc_flags`, type: `boolean[]` `[0] rxftrace`, settable, if set to `true`, then tracing will take place
      `RXINI/9` | `RXINIEXT/1` | Initializing processing.
      `RXTER/10` | `RXTEREXT/1` | Termination processing.
      `RXEXF/12` | `RXEXFCAL/1` | Processes calls to external functions (ooRexx version), at end of search for an external routine. `parmBlock`:
      `[0] rxfnc_flags`, type: `boolean[]` `[0] rxfferr`, settable ("invalid call to routine") `[1] rxffnfnd`, settable ("function not found") `[2] rxffsub`, if `true` then called as subroutine, else as function
      `[1] rxfnc_name`, subroutine/function name, type: `String`
      `[2] rxfnc_argv`, supplied arguments, type: `Object[]`, can be `null`
      `[3] rxfnc_retc`, return value by handler, if any, type: `Object`
      `RXNOVAL/13` | `RXNOVALCALL/1` | Processes a Rexx `NOVALUE` condition. `parmBlock`:
      `[0] variable_name`, variable name, type: `String`
      `[1] value`, return value by handler, if any, type: `Object`
      `RXVALUE/14` | `RXVALUECALL/1` | Processes an extended call to the `VALUE()` built-in function ("BIF") `parmBlock`:
      `[0] selector`, the environment selector name, type: `String`
      `[1] variable_name`, variable name, type: `String`
      `[2] value`, return value by handler, if any, type: `Object`
      `RXOFNC/15` | `RXOFNCCAL/1` | Processes calls to external functions (ooRexx version), at beginning of the search for an external routine. `parmBlock`:
      `[0] rxfnc_flags`, type: `boolean[]` `[0] rxfferr`, settable ("invalid call to routine") `[1] rxffnfnd`, settable ("function not found") `[2] rxffsub`, if `true` then called as subroutine, else as function
      `[1] rxfnc_name`, subroutine/function name, type: `String`
      `[2] rxfnc_argv`, supplied arguments, type: `Object[]`, can be `null`
      `[3] rxfnc_retc`, return value by handler, if any, type: `Object`

      Specified by:
        `handleExit` in interface `RexxExitHandler`
      Parameters:
        `slot` - this is an opaque `Object` argument which must be supplied unchanged to the direct Rexx API methods in `RexxHandler`
        `exitNumber` - the Rexx exit number
        `subFunction` - the Rexx exit subfunction number
        `parmBlock` - an `Object[]` which is structured according to the ooRexx exit documentation in `rexxpg.pdf`; each structure is itself contained in an `Object[]`
      Returns:
        RXEXIT_HANDLED (0), RXEXIT_NOT_HANDLED (1) or RXEXIT_RAISE_ERROR (-1)