SIGNAL [VALUE] name  |  SIGNAL ON|OFF condition [NAME label]

1. SIGNAL [VALUE] name

In this form, the SIGNAL instruction is a primitive form of `goto'.
Using it to control program flow in this manner is strongly discouraged.

When this command is encountered interpretation jumps to the named label
(SIGNAL labels work just like procedure labels - but SIGNAL never invokes
another rexx program).

If the VALUE keyword is present, or if the name does not start with a
symbol or a string constant, then the name is treated as an expression
which must evaluate to the name of a label (irrespective of case).

All current DO and SELECT structures within the current procedure are
terminated by the SIGNAL instruction before the jump is taken.

When the SIGNAL instruction is executed, the variable SIGL is set to hold
the number of the line at the time of the jump. This can be used in
error analysis - as in:

  if something_is_wrong then signal error
  ...
  error: say "Something is wrong at line" sigl

or it can be used to type out long texts or help - as in:

   <lots of argument checking>
   if something_is_wrong then signal help /*
   This is a paragraph of help. It is enclosed in comments, so
   the interpreter ignores it. However the help routine will
   use the sourceline function to type it out on to the screen.
   */
   ...
   help: do i=sigl+1 while sourceline(i)~="*/"
   say sourceline(i)
   end

The SIGNAL VALUE construction is useful for calling procedures with
variable names. This can be done as follows:

   /* procname is set to the name of a procedure */
   call jumpto procname,arguments
   ...
   jumpto: parse arg jumpname
   signal value jumpname
   ...
When the named procedure is called, its first argument will be its name,
and the subsequent arguments will be those supplied by the caller.
The DO and SELECT structures in the calling program are protected from
the SIGNAL instruction, since the latter is encountered within procedure
`jumpto'.

2. SIGNAL ON  condition [NAME symbol]
   SIGNAL OFF condition

These instructions maintain exception handlers for the following
contitions:

 SYNTAX:   Any syntax error (for example "Bad arithmetic conversion" or
           "Unexpected ',' or ')'") which occurs during interpretation.
 NOVALUE:  A variable name is used which has no value.
           NOTE: This condition is not raised during interpretation of
                 sub-names in compound variables. Hence, if `foo' has no
                 value, then "a=foo+1" will cause a novalue error but
                 "a=abc.foo" will not cause an error unless ABC.'FOO' has
                 no value.  Also, the builtin function VALUE() will never
                 raise the NOVALUE condition.
 HALT:     The user has attempted to halt the program, for example by
           typing Control-C.  Signals SIGHUP and SIGTERM also raise the
           HALT condition.
 FAILURE:  A command to the environment returned a "failure" code.
           Usually this means a negative return code, but see the
           section on commands to the environment.
 ERROR:    A command to the environment returned an "error" code.
           This usually means a non-zero return code.  Note that if
           "failures" are not being trapped, then "error" will catch
           failures also.
 NOTREADY: A function from the REXX I/O model (see the separate section)
           was unsuccessful because, for example, an input function
           encountered an end-of-file condition.
           
(These are the same conditions as for CALL ON, with the two extra
conditions SYNTAX and NOVALUE).

The SIGNAL ON instruction turns on condition handling.  Whenever the
specified condition occurs, a SIGNAL is made to a handler.  If the NAME
keyword is specified, then the following symbol is taken as the name of
the handler.  Otherwise the handler has the same name as the condition.
At this point, RC holds the number of the error which caused the jump
(except in the case of NOTREADY) and SIGL holds the line number in
which the error occurred.  The routine in which the SIGNAL ON
instruction was encountered becomes the current routine; all internal
routines which became active since then are terminated.  All
DO/SELECT/IF control structures within the current routine are also
terminated.  The SIGNAL ON instruction is then cancelled, and another
SIGNAL ON instruction will be necessary to reinstate handling of this
particular condition.

At any time after control is passed to the handler, and before the
handler causes a return from the current subroutine, the CONDITION()
builtin function may be used to retrieve information about the
condition which was trapped.

A SIGNAL OFF instructions cancels condition handling for a particular
condition.  If handling is turned off for ERROR, FAILURE, NOTREADY or
NOVALUE, then the condition will be ignored whenever it occurs.  If
handling is turned off for HALT or SYNTAX, then the program will halt
when the condition occurs.

Condition handling persists from the point of the SIGNAL ON instruction
until the current function returns, or until a SIGNAL OFF instruction
is executed.  If an external routine is called, condition handling will
be turned off temporarily until the external routine finishes or turns
condition handling on.

The status of condition handling is saved across function calls.  If a
subroutine uses a "SIGNAL ON/OFF" or "CALL ON/OFF" instruction, the
condition handling within the current routine will be unaffected.

NOTE: The SIGNAL ON SYNTAX command does not trap fatal system errors or
      the error which is caused when EXIT or RETURN returns a non-integer
      to the UNIX environment (this is because the latter is, in effect,
      raised by the environment rather than by the interpreter itself).