org.rexxla.bsf.engines.rexx

## Interface RexxExitHandler

- All Superinterfaces:
    RexxHandler
  All Known Implementing Classes:
    AbstractExitHandler

      public interface RexxExitHandler
      extends RexxHandler

  Interface class for Rexx exit handlers. Cf. ooRexx' `rexxpg.pdf` documentation.

  All final static fields that use ooRexx names also use the ooRexx constant values from the ooRexx include file `rexxapidefs.h`, from which the descriptions and values got copied from.

      ------------------------ Apache Version 2.0 license -------------------------
          Copyright (C) 2012-2022 Rony G. Flatscher

          Licensed under the Apache License, Version 2.0 (the "License");
          you may not use this file except in compliance with the License.
          You may obtain a copy of the License at

              http://www.apache.org/licenses/LICENSE-2.0

          Unless required by applicable law or agreed to in writing, software
          distributed under the License is distributed on an "AS IS" BASIS,
          WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
          See the License for the specific language governing permissions and
          limitations under the License.
       -----------------------------------------------------------------------------

  Since:
    2022-08-22
  Version:
    850.0
  Author:
    Rony G. Flatscher

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String[]` | `RX_EXIT_NAMES` Names of Rexx system exit function numbers between number 0 and 15.
    `static int` | `RXCMD` Process host commands.
    `static int` | `RXCMDHST` Calls a named subcommand handler.
    `static int` | `RXENDLST` End of exit list.
    `static int` | `RXEXF` scripting function call
    `static int` | `RXEXFCAL` Processes calls to external functions.
    `static int` | `RXEXIT_HANDLED` Exit handled exit event
    `static int` | `RXEXIT_NOT_HANDLED` Exit passes on exit event
    `static int` | `RXEXIT_RAISE_ERROR` Exit handler error occurred
    `static int` | `RXFNC` Process external functions.
    `static int` | `RXFNCCAL` Processes calls to external functions.
    `static int` | `RXHLT` Halt processing.
    `static int` | `RXHLTCLR` Clear HALT indicator
    `static int` | `RXHLTTST` Test HALT indicator
    `static int` | `RXINI` Initialization processing.
    `static int` | `RXINIEXT` Initialization exit.
    `static int` | `RXMSQ` Manipulate queue.
    `static int` | `RXMSQNAM` Set active queue name
    `static int` | `RXMSQPLL` Pull a line from queue
    `static int` | `RXMSQPSH` Place a line on queue
    `static int` | `RXMSQSIZ` Return num of lines on queue
    `static int` | `RXNOOFEXITS` 1 + largest exit number.
    `static int` | `RXNOVAL` NOVALUE exit
    `static int` | `RXNOVALCALL` Processes a Rexx NOVALUE condition.
    `static int` | `RXOFNC` Process external functions using object values.
    `static int` | `RXOFNCCAL` Processes calls to external functions.
    `static int` | `RXSIO` Session I/O.
    `static int` | `RXSIODTR` DEBUG read from char stream
    `static int` | `RXSIOSAY` SAY a line to STDOUT
    `static int` | `RXSIOTLL` Return linelength (n/a OS/2)
    `static int` | `RXSIOTRC` Trace output
    `static int` | `RXSIOTRD` Read from char stream
    `static int` | `RXTER` Termination processing.
    `static int` | `RXTEREXT` Termination exit.
    `static int` | `RXTRC` Test ext trace indicator.
    `static int` | `RXTRCTST` Tests the external trace indicator.
    `static int` | `RXVALUE` VALUE function exit
    `static int` | `RXVALUECALL` Processes an extended call to the VALUE() built-in function.
    `static java.lang.String` | `version` Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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`.

    - ### 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`

- - ### Field Detail

    - #### version

          static final java.lang.String version

      Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.
      See Also:
        Constant Field Values

    - #### RXEXIT_HANDLED

          static final int RXEXIT_HANDLED

      Exit handled exit event
      See Also:
        Constant Field Values

    - #### RXEXIT_NOT_HANDLED

          static final int RXEXIT_NOT_HANDLED

      Exit passes on exit event
      See Also:
        Constant Field Values

    - #### RXEXIT_RAISE_ERROR

          static final int RXEXIT_RAISE_ERROR

      Exit handler error occurred
      See Also:
        Constant Field Values

    - #### RXENDLST

          static final int RXENDLST

      End of exit list.
      See Also:
        Constant Field Values

    - #### RXFNC

          static final int RXFNC

      Process external functions.
      See Also:
        Constant Field Values

    - #### RXFNCCAL

          static final int RXFNCCAL

      Processes calls to external functions.
      See Also:
        Constant Field Values

    - #### RXCMD

          static final int RXCMD

      Process host commands.
      See Also:
        Constant Field Values

    - #### RXCMDHST

          static final int RXCMDHST

      Calls a named subcommand handler.
      See Also:
        Constant Field Values

    - #### RXMSQ

          static final int RXMSQ

      Manipulate queue.
      See Also:
        Constant Field Values

    - #### RXMSQPLL

          static final int RXMSQPLL

      Pull a line from queue
      See Also:
        Constant Field Values

    - #### RXMSQPSH

          static final int RXMSQPSH

      Place a line on queue
      See Also:
        Constant Field Values

    - #### RXMSQSIZ

          static final int RXMSQSIZ

      Return num of lines on queue
      See Also:
        Constant Field Values

    - #### RXMSQNAM

          static final int RXMSQNAM

      Set active queue name
      See Also:
        Constant Field Values

    - #### RXSIO

          static final int RXSIO

      Session I/O.
      See Also:
        Constant Field Values

    - #### RXSIOSAY

          static final int RXSIOSAY

      SAY a line to STDOUT
      See Also:
        Constant Field Values

    - #### RXSIOTRC

          static final int RXSIOTRC

      Trace output
      See Also:
        Constant Field Values

    - #### RXSIOTRD

          static final int RXSIOTRD

      Read from char stream
      See Also:
        Constant Field Values

    - #### RXSIODTR

          static final int RXSIODTR

      DEBUG read from char stream
      See Also:
        Constant Field Values

    - #### RXSIOTLL

          static final int RXSIOTLL

      Return linelength (n/a OS/2)
      See Also:
        Constant Field Values

    - #### RXHLT

          static final int RXHLT

      Halt processing.
      See Also:
        Constant Field Values

    - #### RXHLTCLR

          static final int RXHLTCLR

      Clear HALT indicator
      See Also:
        Constant Field Values

    - #### RXHLTTST

          static final int RXHLTTST

      Test HALT indicator
      See Also:
        Constant Field Values

    - #### RXTRC

          static final int RXTRC

      Test ext trace indicator.
      See Also:
        Constant Field Values

    - #### RXTRCTST

          static final int RXTRCTST

      Tests the external trace indicator.
      See Also:
        Constant Field Values

    - #### RXINI

          static final int RXINI

      Initialization processing.
      See Also:
        Constant Field Values

    - #### RXINIEXT

          static final int RXINIEXT

      Initialization exit.
      See Also:
        Constant Field Values

    - #### RXTER

          static final int RXTER

      Termination processing.
      See Also:
        Constant Field Values

    - #### RXTEREXT

          static final int RXTEREXT

      Termination exit.
      See Also:
        Constant Field Values

    - #### RXEXF

          static final int RXEXF

      scripting function call
      See Also:
        Constant Field Values

    - #### RXEXFCAL

          static final int RXEXFCAL

      Processes calls to external functions.
      See Also:
        Constant Field Values

    - #### RXNOVAL

          static final int RXNOVAL

      NOVALUE exit
      See Also:
        Constant Field Values

    - #### RXNOVALCALL

          static final int RXNOVALCALL

      Processes a Rexx NOVALUE condition.
      See Also:
        Constant Field Values

    - #### RXVALUE

          static final int RXVALUE

      VALUE function exit
      See Also:
        Constant Field Values

    - #### RXVALUECALL

          static final int RXVALUECALL

      Processes an extended call to the VALUE() built-in function.
      See Also:
        Constant Field Values

    - #### RXOFNC

          static final int RXOFNC

      Process external functions using object values.
      See Also:
        Constant Field Values

    - #### RXOFNCCAL

          static final int RXOFNCCAL

      Processes calls to external functions.
      See Also:
        Constant Field Values

    - #### RXNOOFEXITS

          static final int RXNOOFEXITS

      1 + largest exit number.
      See Also:
        Constant Field Values

    - #### RX_EXIT_NAMES

          static final java.lang.String[] RX_EXIT_NAMES

      Names of Rexx system exit function numbers between number 0 and 15. (As baseline is Java 1.4 enumerations cannot be used.)

  - ### Method Detail

    - #### handleExit

          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`.

      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`

      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)