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

  Modifier and Type
  Method
  Description
  `int`
  `handleExit(Object slot, int exitNumber, int subFunction, 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 Details

  - ### version

    static final 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 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 Details

  - ### handleExit

    int handleExit(Object slot, int exitNumber, int subFunction, 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)