The signal instruction is used for two purposes.
signal [ VALUE ] labelExpression
The signal instruction causes execution within the current procedure to be immediately transferred to the label identified by the labelName value, or the value of the labelExpression.
The signal instruction is analogous to a goto instruction in other programming languages, with an important exception. In other programming languages, a goto instruction generally preserves pending control flow structures. When a Rexx signal instruction is performed ALL pending control structures are deactivated. This includes the following:
In addition, a pending interpret instruction is also deactivated.
A signal instruction does not affect pending function and subroutine calls.
The line number of the target label of the signal instruction is assigned to the special SIGL variable.
Warning: if the target label is followed by a procedure instruction, this will cause error code 17 (unexpected procedure) to be raised.
The most common use of the signal instruction uses an explicit target labelName. Here is an example.
/* programName.rex */ parse arg n . if \ datatype( n, wholenumber ) then signal usagemsg ...perform processing return 0 usagemsg : say 'you did not enter a numeric argument' say 'usage:' say ' rexx programName wholeNumber'
Alternatively, you can transfer to the value of the labelExpression as follows:
/* switcharoo.rex */ parse arg n . if \ datatype( n, wholenumber ) then signal usagemsg if n < 1 | n > 3 then signal usagemsg signal value n /* switch to label n ! */ 3 : say 'three' 2 : say 'two' 1 : say 'one' return n usagemsg : say 'you did not enter a numeric value between 1 and 3' say 'usage:' say ' rexx switcharoo wholeNumber' exit 99
Note: significant performance improvement can be attained using SIGNAL VALUE. Click this to find out how.
Warning: some REXX implementations require the result of the SIGNAL VALUE labelExpression
to be an UPPERCASE value. These implementations raise syntax error #16 (label not found) when the
character case does not match. The following illustrates this consideration:
signal value '_a' /* case mismatch ! */
_a : ... /* this looks like a lower case 'a' but it isn't ! */
This can be corrected by:
signal value translate( '_a' ) /* force to UPPERCASE */
_a : ... /* ok, now */
signal ON conditionName [ NAME trapLabel ]
signal OFF conditionName
The signal ON or OFF instructions activate or deactivate the transfer of condition traps to an associated label. When active, a conditional trap will cause immediate control transfer to the trapLabel. In a signal ON instruction, if the trapLabel is absent, the label that is the signal target is the same as the condition name. The handling of condition traps can alternatively be activated or deactivated by the call ON or OFF instructions.
The conditionName in the signal ON or OFF is one of the following:
Click here to review Rexx condition handling.
A commonly recommended REXX programming practice precedes program logic with the following series of signal on instructions.
/* anticipate errors */ signal on error signal on failure signal on syntax signal on novalue . . (put program logic here) . signal off error signal off failure signal off syntax signal off novalue exit 0 /* error handling */ error: failure: syntax: novalue: say 'An error occurred...' say "???" condition( 'D' ) say " Error line:" SIGL'.' sourceline( SIGL )