FATAL

Chain to another program if a fatal error occurs

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

xcall FATAL(action[, filename])

Arguments

action

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

0

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

1

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

2

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

3

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

filename

(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)

Discussion

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	Information
1 – 3	d3	Synergy DBL fatal error number
4 – 13	d10	Windows—Error code from GetLastError() Unix—Last errno value OpenVMS—System service error code
14 – 23	d10	The line number of the statement that caused the error
24 – 53	a30	The name of the routine that caused the error
54 – 83	a30a	The name of the program that contains the error

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.

Examples

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)