A HALT condition happens when the person running your script presses the CTRL and C keys simultaneously to abort script execution, or some Function you call in a DLL/EXE wants your script to abort.

As mentioned previously, the default handling for the HALT condition is to display some information to the command prompt window, and then end the script right there. The information displayed includes the line number and the actual line in the script where the condition was raised, the name of the script, and a message indicating that the script was aborted. An error number is also displayed after the word "ERROR". This number is 4, which is the error number that indicates that a script was aborted.

But if you trap the HALT condition, then such default handling doesn't happen. Instead, REXX calls your own HALT handler.

Error/signal numbers

Whenever a HALT condition is raised, an error number, and a signal number, is associated with that instance of the condition being raised. If a HALT condition is raised within your script, then the error number will be 4, and the signal number can be any numeric value, within the range 1 to 65535, that tells you why the HALT condition was raised. There are three defined numbers -- 2 (the person using your script wants to abort), 15 (the operating system wants your script to close down), and 1 (ie, a UNIX signal not used on Windows).

Your handler can use the CONDITION() built-in function's 'E' option to fetch the error and signal numbers associated with a given instance of that condition. CONDITION('E') will return the two numbers separated by a dot. For example, 4.2 will be returned for the user pressing CTRL and C while your script is executing.

A signal number may have a matching name (ie, some string that identifies the signal being given to your script). There are 3 defined signal names for signal numbers 2, 15, and 1 respectively -- 'SIGINT', 'SIGTERM', and 'SIGHUP'.

Your handler can use CONDITION()'s 'D' option to fetch signal name.

Some functions that you call in an EXE/DLL may also raise HALT. These functions may specify other signal numbers/names. Consult the documentation with those functions for meanings of other names/numbers. If a function doesn't provide a matching signal name, then CONDITION('D') simply returns the signal number.

If you've issued an OPTIONS 'TRAP' instruction and are trapping HALT, and then a HALT condition is raised within another script that you call, the error number will be 65 instead of 4. CONDITION('D') will return an error message that reports the name of the script which was aborted, the line number where it was aborted, and the signal's name.

For example, here is an example of trapping HALT. 

/* Trap HALT */
SIGNAL ON HALT

/* Here you would have more instructions. If
 * the person running the script presses CTRL
 * and C keys while these instructions are
 * executing, REXX jumps to the label HALT
 */

EXIT

HALT:
   PARSE VALUE CONDITION('E') WITH error '.' sub
   IF error = 65 THEN SAY "Untrapped HALT in a script we called"
   IF sub = 2 THEN SAY "User wants to abort"
   ELSE IF sub = 15 THEN SAY "Operating system wants to close down"
   ELSE SAY "Other type of HALT =" sub
   RETURN

You can use the "PARSE SOURCE" and "SAY" REXX instructions, the SIGL variable, and the ERRORTEXT() and CONDITION() built-in functions to duplicate the default handling for HALT condition, as so: 

/* Handler for HALT that duplicates the default handling */
HALT:
   PARSE VALUE CONDITION('E') WITH err '.' sub
   IF err \= 65 THEN DO
      linenum = SIGL
      SAY "    " SIGL "+++" SOURCELINE(linenum)
      PARSE SOURCE . . scriptname
      SAY 'ERROR' CONDITION('E') 'in "'||scriptname||'" at line' linenum
      SAY ERRORTEXT(CONDITION('E'))
   END
   ELSE DO
      PARSE VALUE CONDITION('D') WITH . '"' scriptname '"' . 'line ' linenum ': ' sig
      SAY 'ERROR 4.'||sub 'in "'||scriptname||'" at line' linenum
	  SAY ERRORTEXT(4||'.'||sub)
   END
   RETURN