U_ABORT

Process an abort

xcall U_ABORT(message1[, message2, ..., message5])

Arguments

message1 to message5

Up to five error messages. Message1 is required. Message2 through message5 are optional. (a)

Discussion

When a Toolkit error or a window error is generated, the error is automatically sent to U_ABORT, unless the error is returned in an argument for a Toolkit routine, such as the error argument for L_CREATE. (If this happens, the error number is returned in the argument, and you can use %U_GETWNDERR to get the error text.) However, you can also call U_ABORT directly when you detect a fatal error condition in your application.

U_ABORT behaves differently depending on the value of g_throwabort, a global defined in tkctl.def. The default behavior (active when g_throwabort is set to zero) may be adequate for interactive Toolkit applications, where the resulting fatal error message can be displayed to the screen. But for error trapping, use the second type of U_ABORT processing (active when g_throwabort is set to a non-zero value). Error trapping gives you greater control over errors generated by U_ABORT and enables server-side applications and applications running as services to pass error information on to client programs. You can set the g_throwabort global from your program or you can change its initial setting by setting the DTK_THROW_ABORT environment variable.

If g_throwabort is set to zero (the default), U_ABORT performs a STOP and displays a fatal error message. The STOP will have an exit status of D_EXIT_FAILURE, and U_ABORT will not return to the calling routine. (Most operating systems have commands that enable you to test the exit status. See your operating system documentation for information.) The error message will have the following format:

** ERROR ** ERROR ** ERROR **

followed by the contents of the message1 to message5 argument(s). If you pass more than one message argument, each message will start a new physical line of text. You can pass up to five messages.

Note the following OS-specific information:

On Windows, this routine creates a Windows-style message box with a stop sign icon and an OK button. Each message can wrap, so the total length of all messages is limited only by the desktop size.
On UNIX and OpenVMS, each message can be up to 70 characters long. Additional characters are truncated.
On Windows, U_ABORT cannot time out.
On UNIX and OpenVMS, if a time-out occurs g_select is set to true and g_entnam is set to the entry name specified in tkctl.def for g_time_entry. By default, g_time_entry is defined as “O_TIMEOUT”.

If g_throwabort is set to a non-zero value, U_ABORT calls U_FINISH to shut down the Toolkit environment and then calls EXITE to throw a trappable error with the mnemonic $ERR_TOOLKIT and the error text “Toolkit error.” Message arguments passed to U_ABORT are passed on as informational messages for the thrown error and can be retrieved using %ERR_TRACEBACK once the error has been trapped. Because U_ABORT shuts down the Toolkit environment, you will need to call U_START to perform any further Toolkit operations.

If g_throwabort is set to throw an error, your application should be written to catch and handle the thrown error. Otherwise the application may continue to execute in situations where it would have terminated had U_ABORT performed a STOP. For example, if input is redirected but the application’s error catching mechanism does not terminate the application after a certain number of EOFs, U_ABORT may cause the application to run indefinitely. Additionally, you may need to modify any automated procedures (batch files and so forth) that invoke U_ABORT so that they work with the new behavior.

If an interactive Toolkit application fails to trap an error thrown by U_ABORT

on Windows, the Synergy runtime will display a fatal error message box (which is different than the message displayed with U_ABORT’s default behavior).
on UNIX and OpenVMS, the Synergy runtime will generate a fatal error traceback (which does not require user input and which returns immediately to the command prompt). Additionally, U_FINISH will clear the screen unless the error occurs within U_START.

See also

ONERROR statement
%ERR_TRACEBACK routine
DTK_THROW_ABORT environment variable

Examples

The following call generates the specified messages (in addition to the **ERROR** message) if g_throwabort is set to 0. If g_throwabort is set to a non-zero value, it throws a trappable error and passes the messages on as informational error messages for the thrown error.

xcall u_abort("Customer file is corrupt", "Please call your distributor")

The next example is written for error trapping (active when g_throwabort is non-zero). It uses ONERROR to enable error trapping and %ERR_TRACEBACK to retrieve error information.

proc
  xcall u_start
  .
  .
  .
  onerror ($ERR_CATCH) catch    ;Need this to activate error trapping.
  xcall u_open(chan, "I", " cusmas ")
  reads(chan, cusmas, bad_cusmas)  ;We need to have a control record.
  if (cusmas.control .ne. 0)       ;If it is not a control record...
    begin
bad_cusmas, ;Either we have no record, or it is not a control record
      xcall u_abort("This is the first line of the message.",
 &                  "This is the second line of the message.")
    end
  .
  .
  .
catch,
  offerror       ;Prevents an error within catch from looping back to
                 ; the catch label.
  xcall u_start  ;Need this because U_ABORT shuts down Toolkit, but we
                 ; need Toolkit to call U_MSGBOX.
  set cnt, len = 1
  while cnt      ;Loop through messages passed by U_ABORT.
    begin 
      cnt = %err_traceback(errtext(len,^size(errtext)))
      if (cnt)
        begin 
          len = %trimz(errtext) + 1
          errtext(len:2) = "
          len += 2
        end
    end
  xcall u_msgbox(errtext(1:len), D_MICONSTOP, "Trapped error")
  .
  .
  .