All Known Subinterfaces:: RexxCommandHandler, RexxExitHandler, RexxRedirectingCommandHandler

All Known Implementing Classes:: AbstractDirectCommandHandler, AbstractExitHandler, AbstractRedirectingCommandHandler, JavaDrawingHandler

public interface RexxHandler

Abstract class to allow Rexx exit and command handlers implemented in Java to use some of the ooRexx exit APIs directly.

Please note: these methods allow interfacing with the running instance of the Rexx interpreter instance on the same (!) thread in which the Rexx command or Rexx exit Java handler got invoked on. It is necessary to supply the opaque argument named slot from the Java handler methods unaltered.
If neither of these two restrictions holds, then the results of executing any of these static methods will be undefined, mostlikely tearing down ooRexx and Java!

------------------------ Apache Version 2.0 license -------------------------
    Copyright (C) 2012-2024 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.20220901
Author:: Rony G. Flatscher

Field Summary

Fields

Modifier and Type

Field

Description

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), e.g.
Method Summary

Modifier and Type

Method

Description

default boolean

checkCondition(Object slot)

Checks to see if any conditions have resulted from a call to a Rexx API (cf "rexxapi.pdf").

default void

clearCondition(Object slot)

Clears any pending condition status (cf "rexxapi.pdf").

default void

dropContextVariable(Object slot, String variableName)

Drops a Rexx variable from the context.

default Object

getAllContextVariables(Object slot)

Fetches and returns a Rexx directory containing all context variables.

default Object

getCallerContext(Object slot)

Returns the Rexx context object .context that can be analyzed to learn about the context of the command/exit.

default Object

getConditionInfo(Object slot)

Returns a directory object containing the condition information; this is equivalent to calling condition('O') from within Rexx code (cf "rexxapi.pdf").

default Object

getContextVariable(Object slot, String variableName)

Fetches and returns the Rexx variable value in the Rexx program for which the handler runs.

default Object

getGlobalEnvironment(Object slot)

Returns a reference to the Rexx interpreter global .environment directory.

default long

getInterpreterVersion(Object slot)

(Copied from the ooRexx rexxapi.pdf documentation) "Returns the version of the interpreter." "The returned version is encoded in the 3 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values." "For example, on a 32-bit platform, this value would be 0x00050000 for version 5.0.0."

default long

getLanguageLevel(Object slot)

(Copied from the ooRexx rexxapi.pdf documentation) "Returns the language level of the interpreter." "The returned language level is encoded in the 2 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values.

default Object

getLocalEnvironment(Object slot)

Returns a reference to this Rexx interpreter instance .local environment directory.

default Object

getNil(Object slot)

Returns a reference to the Rexx sentinel value .nil.

default void

haltThread(Object slot)

Raises a HALT condition on the current (Rexx) thread.

default Object

newArray(Object slot)

Returns a newly created ooRexx Array collection object.

default Object

newDirectory(Object slot)

Returns a newly created ooRexx Directory collection object.

default Object

newStem(Object slot, String stemName)

Returns a newly created ooRexx Stem collection object.

default Object

newStringTable(Object slot)

Returns a newly created ooRexx StringTable collection object.

default void

raiseCondition(Object slot, String conditionName, String description, Object[] additional, Object result)

Raises a condition in the current Rexx thread, pass-through method to the Rexx API, which should be called immediately before returning to Rexx.

default void

raiseException(Object slot, long definedErrorNumber, Object[] substitutions)

Raises a Rexx syntax condition of the given error number, call immediately before returning from Java to Rexx.

default void

raiseException0(Object slot, long definedErrorNumber)

Raises a Rexx error without substitution values of the given error number, call immediately before returning from Java.

default void

raiseException1(Object slot, long definedErrorNumber, String substitution1)

Raises a Rexx error of the given error number, call immediately before returning from Java.

default void

raiseException2(Object slot, long definedErrorNumber, String substitution1, String substitution2)

Raises a Rexx error of the given error number, call immediately before returning from Java.

default void

setContextVariable(Object slot, String variableName, Object variableValue)

Allows to set a variable with a value in the Rexx program for which the handler runs.

default void

setContextVariableToNil(Object slot, String variableName)

Allows to set a variable to .nil in the Rexx program for which the handler runs.

default void

setThreadTrace(Object slot, boolean state)

Sets the interactive trace state for the current thread.

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), e.g. 850.20240620.
  See Also:
  
  Constant Field Values
Method Details
- raiseCondition
  
  default void raiseCondition(Object slot, String conditionName, String description, Object[] additional, Object result)
  
  Raises a condition in the current Rexx thread, pass-through method to the Rexx API, which should be called immediately before returning to Rexx. Cf. the ooRexx documentation in rexxapi.pdf, 1.17.148. RaiseCondition.
  
  Parameters:
  
  slot - opaque argument supplied to the handler methods by the Rexx native code interface
  
  conditionName - Rexx condition name, usually "ERROR" or "FAILURE"
  
  description - optional String describing the condition
  
  additional - optional additional object
  
  result - optional result object, if routine or method does not trap the condition; may contain the error or failure number
- raiseException
  
  default void raiseException(Object slot, long definedErrorNumber, Object[] substitutions)
  
  Raises a Rexx syntax condition of the given error number, call immediately before returning from Java to Rexx. Please note: the value of definedErrorNumber has to be calculated as errorNumber*1000+subcode. Cf. the ooRexx reference manual (rexxref.pdf), "Appendix C. Error Numbers and Messages".
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  definedErrorNumber - errorNumber*1000+subcode
  
  substitutions - an Object array containing substitution values for the error message (if more entries than needed by the secondary message get added, then they can be retrieved by ooRexx using the additional method of the condition object)
- raiseException0
  
  default void raiseException0(Object slot, long definedErrorNumber)
  
  Raises a Rexx error without substitution values of the given error number, call immediately before returning from Java. Please note: the value of definedErrorNumber has to be calculated as errorNumber*1000+subcode. Cf. the ooRexx reference manual (rexxref.pdf), "Appendix C. Error Numbers and Messages".
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  definedErrorNumber - errorNumber*1000+subcode
- raiseException1
  
  default void raiseException1(Object slot, long definedErrorNumber, String substitution1)
  
  Raises a Rexx error of the given error number, call immediately before returning from Java. Please note: the value of definedErrorNumber has to be calculated as errorNumber*1000+subcode. Cf. the ooRexx reference manual (rexxref.pdf), "Appendix C. Error Numbers and Messages".
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  definedErrorNumber - errorNumber*1000+subcode
  
  substitution1 - String used as the first substition value for the error message
- raiseException2
  
  default void raiseException2(Object slot, long definedErrorNumber, String substitution1, String substitution2)
  
  Raises a Rexx error of the given error number, call immediately before returning from Java. Please note: the value of definedErrorNumber has to be calculated as errorNumber*1000+subcode. Cf. the ooRexx reference manual (rexxref.pdf), "Appendix C. Error Numbers and Messages".
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  definedErrorNumber - errorNumber*1000+subcode
  
  substitution1 - String used as the first substition value for the error message
  
  substitution2 - String used as the second substition value for the error message
- getAllContextVariables
  
  default Object getAllContextVariables(Object slot)
  
  Fetches and returns a Rexx directory containing all context variables.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  a RexxProxy representing a Rexx directory with the currently defined context variables
- getContextVariable
  
  default Object getContextVariable(Object slot, String variableName)
  
  Fetches and returns the Rexx variable value in the Rexx program for which the handler runs.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  variableName - name of the Rexx variable
  
  Returns:
  
  value of the Rexx variable
- setContextVariable
  
  default void setContextVariable(Object slot, String variableName, Object variableValue)
  
  Allows to set a variable with a value in the Rexx program for which the handler runs.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  variableName - name of the Rexx variable
  
  variableValue - the Rexx variable should be set to
- setContextVariableToNil
  
  default void setContextVariableToNil(Object slot, String variableName)
  
  Allows to set a variable to .nil in the Rexx program for which the handler runs.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  variableName - name of the Rexx variable
- dropContextVariable
  
  default void dropContextVariable(Object slot, String variableName)
  
  Drops a Rexx variable from the context.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  variableName - name of the Rexx variable
- newArray
  
  default Object newArray(Object slot)
  
  Returns a newly created ooRexx Array collection object.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  the newly created ooRexx collection object
- newDirectory
  
  default Object newDirectory(Object slot)
  
  Returns a newly created ooRexx Directory collection object.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  the newly created ooRexx collection object
- newStem
  
  default Object newStem(Object slot, String stemName)
  
  Returns a newly created ooRexx Stem collection object.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  stemName - the stem's base name
  
  Returns:
  
  the newly created ooRexx collection object
- newStringTable
  
  default Object newStringTable(Object slot)
  
  Returns a newly created ooRexx StringTable collection object.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  the newly created ooRexx collection object
- checkCondition
  
  default boolean checkCondition(Object slot)
  
  Checks to see if any conditions have resulted from a call to a Rexx API (cf "rexxapi.pdf").
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  true, if Rexx condition is set, false else
- clearCondition
  
  default void clearCondition(Object slot)
  
  Clears any pending condition status (cf "rexxapi.pdf").
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
- getConditionInfo
  
  default Object getConditionInfo(Object slot)
  
  Returns a directory object containing the condition information; this is equivalent to calling condition('O') from within Rexx code (cf "rexxapi.pdf").
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  returns a RexxProxy for a Rexx Directory object or NULL, if no pending Rexx condition
- getCallerContext
  
  default Object getCallerContext(Object slot)
  
  Returns the Rexx context object .context that can be analyzed to learn about the context of the command/exit.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  returns a RexxProxy for the Rexx .context object
- setThreadTrace
  
  default void setThreadTrace(Object slot, boolean state)
  
  Sets the interactive trace state for the current thread.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  state - new state for interactive trace
- haltThread
  
  default void haltThread(Object slot)
  
  Raises a HALT condition on the current (Rexx) thread.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
- getLocalEnvironment
  
  default Object getLocalEnvironment(Object slot)
  
  Returns a reference to this Rexx interpreter instance .local environment directory.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  a RexxProxy for the Rexx .local object
- getGlobalEnvironment
  
  default Object getGlobalEnvironment(Object slot)
  
  Returns a reference to the Rexx interpreter global .environment directory.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  a RexxProxy for the Rexx .environment object
- getNil
  
  default Object getNil(Object slot)
  
  Returns a reference to the Rexx sentinel value .nil.
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  a RexxProxy referring to the .nil object
- getInterpreterVersion
  
  default long getInterpreterVersion(Object slot)
  
  (Copied from the ooRexx rexxapi.pdf documentation) "Returns the version of the interpreter." "The returned version is encoded in the 3 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values." "For example, on a 32-bit platform, this value would be 0x00050000 for version 5.0.0."
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  the ooRexx interpreter version
- getLanguageLevel
  
  default long getLanguageLevel(Object slot)
  
  (Copied from the ooRexx rexxapi.pdf documentation) "Returns the language level of the interpreter." "The returned language level is encoded in the 2 least significant bytes of the returned value, using 1 byte each for the interpreter version, release, and revision values. For example, on a 32-bit platform, this value would be 0x00000603 for language level 6.03."
  
  Parameters:
  
  slot - an opaque Object array as passed to the RexxExitHandler or RexxCommandHandler object
  
  Returns:
  
  the ooRexx language level

Interface RexxHandler

Field Summary

Method Summary

Field Details

version

Method Details

raiseCondition

raiseException

raiseException0

raiseException1

raiseException2

getAllContextVariables

getContextVariable

setContextVariable

setContextVariableToNil

dropContextVariable

newArray

newDirectory

newStem

newStringTable

checkCondition

clearCondition

getConditionInfo

getCallerContext

setThreadTrace

haltThread

getLocalEnvironment

getGlobalEnvironment

getNil

getInterpreterVersion

getLanguageLevel