^%ZTER: Kernel Standard Error Recording Routine

Reference Type: Supported, Category: Error Processing, Integration Agreement: 1621

Description

Kernel sets the error trap in ZU so that all user errors are trapped. In this context, when an error occurs, the optional %ZT input array is set to indicate the user's location in the menu system. Then ^%ZTER is called to record this information in the ERROR LOG file (#3.075).

The application-specific error trap routine, when it is called as a result of an error, can then use the ^%ZTER API to record error information in the ERROR LOG file (#3.075) if it decides that it needs to. ^%ZTER gathers all available information such as local symbols and last global reference and stores that information in an entry in the ERROR LOG file (#3.075).

The simple example below shows an application that replaces the standard Kernel error trap with its own error trap. When an error occurs, and the application's error trap routine is called, it calls $$EC^%ZOSV to see what type of error occurred. If an end-of-file (EOF) error occurs, it lets the application continue. Otherwise, it calls ^%ZTER to record the error, and then quits to terminate the application.

NOTE: The recording mechanism of ^%ZTER also functions in the absence of an error. In a debug mode, this would enable a programmer to record local symbols and global structures at predetermined places within code execution for later checking.

Format

  ^%ZTER

Symbol Table

  >S %ZT("^TMP($J)")=""
  >D ^%ZTER

Output

Example

The following is an example of the Error Trap:

ZXGAPP ; 999/NV - sample routine ; 23-FEB-95
	;;1.0;;
	;
FILEOPEN	;
	;
	; This code resets the error trap routine that is stepped to 
	; when an error occurs.
	;
	N $ESTACK,$ETRAP S $ETRAP="D ERR^ZXGAPP"
	;	
	; Open a file, and read lines from it until End-of-File (EOF)
	; is reached.
	;
	K %ZIS S %ZIS=""
	S %ZIS("HFSNAME")="MYFILE.DAT",%ZIS("HFSMODE")="RW"
	D ^%ZIS Q:POP
	F  U IO R LINE:DTIME U IO(0) W !,LINE
	;
FILECLOS	;
	;
	D ^%ZISC Q
	;
ERR	;
	; This is the application specific error trap.
	;
	I $$EC^%ZOSV["ENDOFILE" S $ECODE="" G FILECLOS ; continue if EOF error
	D ^%ZTER ; record the error if anything other than EOF
         D UNWIND^%ZTER ; unwind the stack, return to caller. 
	Q
	;