DataBasic Application Dump

This feature allows a DataBasic application to dump (save) some information about its state, either automatically or on request.

There are three main situations when a DataBasic application dump may be required:

BASIC-DUMPS file

A default global BASIC-DUMPS file is supplied, in the SYSFILES account, in which to store DataBasic application dump items.

This file is read- and write-access protected, restricting initial access to SYSMAN. However, users do not need a key in order to use the DataBasic application dump feature.

If an application dump file is not present then this feature is not enabled, and any request to dump application data is silently skipped.

In addition, this feature is individually controlled by the AUTO.BASIC.DUMP custom option.

Note

The BASIC-DUMPS file is referenced through the language tables CLASS11 message 8. Although it is possible to alter this default, this is not recommended. Note that if necessary a non-default application dump file can be specified by the DUMP command and accessed by the DISP.DB.DUMPS program.

Warning and fatal run-time errors

Whenever DataBasic generates a warning or fatal message, even if these messages are suppressed, the system creates a respective WARN or ABORT dump item and saves it to the BASIC-DUMPS file.

However, multiple WARN and ABORT dump items caused by identical errors occurring on the same port, account, user, program and line number are typically suppressed. Instead, a single WARN or ABORT dump item is created at the first occurrence and thereafter a count on the item is incremented each time the error recurs. These duplicate item counts can effectively be reset by using the RELOG.DB.DUMPS program. The previous functionality, in which all errors are reported regardless, can be restored by setting the DB.DUMP.MULTIPLE custom environment option.

Note that even if warnings are configured to be fatal (for example, by using the F option of the RUN command, or the WF debugger command, or setting the FATAL.WARNINGS environment option) they are still recorded as WARN dump items.

BASIC.DUMP statement

A BASIC.DUMP DataBasic statement allows the programmer to write a SOFT dump item to the BASIC-DUMPS file whenever required.

Custom environment options

DUMP.BASIC.VARS

A DUMP.BASIC.VARS custom option is provided which, if set, causes the WARN, ABORT and SOFT dump items to include the program variables and their contents. If the option is clear (unset) these items do not include the program variables. DUMP.BASIC.VARS is clear by default.

This option helps to control the size of the BASIC-DUMPS file. It can be set or cleared inside a program, a logon Proc, and by the SET-OPTION and CLEAR-OPTION TCL commands. In addition, all custom options are configurable within a user environment profile, allowing multiple users to inherit the desired setting.

DB.DUMP.MULTIPLE

A DB.DUMP.MULTIPLE custom option is provided which, if set, causes the system to create multiple WARN or ABORT dump items even when reporting identical warning or fatal run-time error occurring on the same port, account, user, program and line number.

However, DB.DUMP.MULTIPLE is clear (unset) by default, meaning that multiple dump items are suppressed. Instead, a single WARN or ABORT dump item is created at the first occurrence and thereafter a duplicate count on the item is incremented each time the error recurs. For example, a WARN dump item with a duplicate count of 4 means that the same error has occurred five times. These duplicate counts can effectively be reset by using the RELOG.DB.DUMPS program as described below.

DUMP command

A DUMP DataBasic debugger command generates a DEBUG dump item that contains all of the program's variables (regardless of the setting of the DUMP.BASIC.VARS option) plus an optional user-specified message.

Optionally, a non-default application dump file can be specified. This can allow (for example) a support help desk to request a user to manually do an additional debug dump after a fatal error, to see all the variables and their contents even if DUMP.BASIC.VARS is clear.

DISP.DB.DUMPS program

A DISP.DB.DUMPS cataloged DataBasic program is provided to display DataBasic application dump items from either the default BASIC-DUMPS file or a user-specified alternative.

RELOG.DB.DUMPS program

The RELOG.DB.DUMPS cataloged DataBasic program clears the dump item cache. This effectively resets the duplicate counts that are maintained while the DB.DUMP.MULTIPLE custom environment option is unset (as it is by default).