Chain to another program if a fatal error occurs

WTSupported in traditional Synergy on Windows


USupported on UNIX
VSupported on OpenVMS
xcall FATAL(action[, filename])



One of the following codes that tells the runtime what to do if an error occurs: (n)


Return to system level. The default program is not invoked, and any second argument is ignored.


Chain to the default, user‑designated program. If this program doesn’t exist, control returns to the terminal.


Chain to the specified program (filename). If filename is not specified, control returns to the terminal.


Return the name of the default, user‑designated program in the filename variable. If this program doesn’t exist, filename is filled with blanks.


(optional) An expression that contains the file specification for the program to which to chain if a fatal or untrapped error occurs. It may also be a variable that will be returned with the name of the default user‑designated program. (a)


The FATAL subroutine provides a graceful way to catch fatal and trappable errors. It specifies a program to which the current program should chain if an error occurs and sends an informational message to that program.

When your program chains to the program specified by the FATAL subroutine, a message containing error information is also sent to that program. To receive the message, you must use the RECV statement in the specified program.

The message doesn’t include field names. It has the following format:

Character position

Data type


1 – 3


Synergy DBL fatal error number

4 – 13


Windows—Error code from GetLastError()

UNIX—Last errno value

OpenVMS—System service error code

14 – 23


The line number of the statement that caused the error

24 – 53


The name of the routine that caused the error

54 – 83


The name of the program that contains the error

a. A maximum of 25 characters is returned for the program name. (The remaining 5 bytes are required to store “MAIN$”, which always precedes the program name but which is not returned as part of the name. See MAIN‑ENDMAIN for more information.)

For example, you can define the following record in the program to which you want to chain:

record error
    err1        ,d3
    err2        ,d10
    erln        ,d10
    modul       ,a30
    prgnm       ,a30

To receive the message, issue the following RECV statement in the receiving program:

recv(error, none)

If no message is available, control transfers to the statement labeled none.

The FATAL subroutine left‑justifies the routine and program names it sends to the program to which it chains on a fatal error.

FATAL uses the environment variable DBL$FATAL_IMAGE (or DBL_FATAL_IMAGE on UNIX) as filename (when action 3 is specified) and as the default program to which to chain.


The example below tells the program to chain to the ferr file if a fatal error occurs.

xcall fatal(2, "ferr")

In the example below, control is returned to the terminal if a fatal error is detected. Any previous filenames specified in the FATAL routine are disabled, and the program terminates as usual.

xcall fatal(0)