PANIC | KCML Reference Manual

PANIC

General Forms:

PANIC [stringexpr]
PANIC CONTINUE [stringexpr]
PANIC numeric_expression, [stringexpr] { TO [filename] }

The first form of the PANIC statement takes a snapshot of the current program state into a file. If programming is enabled then the KCML editor is displayed, otherwise, if programming is disabled, a message is displayed and the KCML session is terminated. Note that programming is disabled by setting byte 36 of $OPTIONS RUN. An immediate mode PANIC prints the message specifying the filename used but does not terminate.

In the second form, PANIC CONTINUE, the program continues executing and does not terminate. It does not print a message to the CO device. This allows a program which has detected an error condition to dump its state and recover. Note that the LIST device is used and will be reset to /005 by this statement.

In either form a string expression may follow the statement and it will be included in the header of panic dump.

The third form of PANIC takes a numerical expression for the first parameter, controlling the PANIC statement, with a mandatory string expression that will be included in the PANIC. It has an optional expression "TO [filename]" in braces to allow a specific output file. Constants are defined to control whether the application should stop with the PANIC or CONTINUE and to define what sections should be included in the panic file. These constants may be combined using the | operator:

Constant	Description
_PANIC_ACTION_STOP	Stop after the PANIC statement
_PANIC_ACTION_CONTINUE	Continue executing after the PANIC satement
_PANIC_SECTION_Basics	Include Basics section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Screen	Include Screen section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Stack	Include Stack section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_NewStack	Include NewStack section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Libraries	Include Libraries section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Handle	Include Handle section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_SysInfo	Include SysInfo section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Args	Include Args section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Environment	Include Environment section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_ListDim	Include ListDim section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_DynLibs	Include DynLibs section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_History	Include History section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_ProcessInfo	Include ProcessInfo section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_MemMap	Include MemMap section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_ListHeap	Include ListHeap section in PANIC file
_PANIC_SECTION_Pools	Include Pools section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Forms	Include Forms section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_Syslog	Include Syslog section in PANIC file (included in _PANIC_SECTION_BASIC)
_PANIC_SECTION_BASIC	Sections contained in simpler forms of PANIC statement
_PANIC_PANIC	Equivalent to PANIC statement
_PANIC_CONTINUE	Equivalent to PANIC CONTINUE statement

The bkstat utility under Unix, kservadm on Windows or the Web Administration Tool can be used to force a KCML process to generate a dump. There are two options on the signal menu: the Panic+ option generates the dump and terminates the process whereas the Panic option only generates the dump and it allows the process to continue to run.

PANIC should be used in place of STOP statements in parts of programs that can only be executed as a result of a program bug or data corruption. It will terminate the session but give a postmortem dump of the program state allowing support personel to analyse the cause of the bug. The STOP PANIC statement can be used to force all STOP statements to act like PANIC.

The dump is placed in a native file whose name starts with the word 'panic' ('pan' on Windows versions) followed by a unique number corresponding to the process id of the KCML task. The panic event, together with the file name used, is logged in the operating system event log. The file contains the following information:

The date and time.
Contents of the text output screen (if any)
UNIX login name
UNIX terminal number
The KCML version number.
The KCML software license number.
The contents of the $MACHINE, $OPTIONS, $OPTIONS RUN, $OPTIONS LIST and $PSTAT system variables.
The operating system type and version number (if available.)
A list of operating system environment variables.
The value of the #TERM and #PART functions.
The value of the ERR function.
The value of the #LINE and #STAT functions.
The output from the LIST RETURN, LIST DT and LIST DIM commands.
List of shared libraries.
Process information: start time, processor time, memory usage etc.
List of System log messages that the process reported. (KCML 7.15 or later)

In versions of KCML prior to 6.0 the format of the dump was unstructured ascii text with LIST DIM and LIST RETURN in exactly the same format as their console mode equivalents. If KCML 6.0+ the format is XML and there is a .xml extension to the filename. This can be viewed as a structured tree in an XML aware web browser like Firefox or IE6. To format the file a XSLT stylesheet pan.xsl is installed in the kcml directory and copied to the panic directory with the first panic.

The PANIC file is created by default in the current working durectory. On Windows 9x and Windows NT, if the the registry key HKEY_LOCAL_MACHINE/SOFTWARE/Kerridge/PanicDir exists then it can provide the default directory. This key can be set using the kservadm utility which also has a facility to browse the panic directory and display any panics. Setting the environment variable PANICDIR to a native directory name using the ENV() function will cause all future PANIC files to be created in the specified directory. This takes priority over the registry setting.

If KCML detects an unrecoverable internal fault, a PANIC file is automatically created along with a core file if the DUMP environment variable is set.

If the HEX(02) bit of $OPTIONS RUN byte 53 is set, programming is enabled, HALT is enabled and the user has previously interrupted the program displaying the debugger, then a PANIC executed within the program will not not produce a panic file and terminate the session but will drop back into the editor with an error A08.41. The behaviour of PANIC in immediate mode is not affected so you can then manually force one if you need it. This bit in $OPTIONS is set by default so to revert to the behaviour prior to KCML 5.0 unset this bit in your program.

The level of detail in PANIC files can be configured with the panconf.xml configuration file.

Routines that have a stack depth lower that the first call to 'KCML_Panic_Suppress() will not be included in the LIST RETURN stack trace.

Panic hooks

User-defined functions can be registered to run before and after PANIC and PANIC CONTINUE statements by setting the PrePanic and PostPanic fields in the input to KCML_Hook_SetCallbacks. The behaviour of the panic can be modified by returning different panic actions in the pre-hook. The low-byte is used to control whether the panic file is written or suppressed, and the high byte is used to control whether the panic stops execution, behaves like a PANIC CONTINUE, or is converted to a catchable runtime error.