^%ZTER: Kernel Standard Error Recording Routine

Reference Type: Supported, Category: Error Processing, ICR#: 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 (#3.075) file.

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 (#3.075) file 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 (#3.075) file.

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 developer to record local symbols and global structures at predetermined places within code execution for later checking.

NOTE: As of Kernel Patch XU*8.0*431, the ^%ZTER error trap routine checks a count (limit) in the ERROR TRAP SUMMARY (#3.077) file and stops recording errors once this limit has been reached. This limit is initialized to 10 but can be changed by the sites. To change the value, use VA FileMan to edit the ERROR LIMIT (#520.1) field in the KERNEL SYSTEM PARAMETERS (#8989.3) file.

Format

  ^%ZTER

Make sure to perform the following steps before calling this API:

1. NEW all non-namespaced variables.
   
   
2. Set all input variables.
   
   
3. Call the API.

Input Variable

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

Output Variables

Examples

Example 1

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
	;

Example 2

To test the error limit set in the ERROR LIMIT (#520.1) field in the KERNEL SYSTEM PARAMETERS (#8989.3) file, run the following:

    >F I=1:1:20 D APPERROR^%ZTER("My Application Error")

Check the error trap and see how many errors with "My Application Error" get recorded in the Kernel error log (i.e., ERROR LOG [#3.075] file). If the value in the ERROR LIMIT (#520.1) field is set to 10, there should just be 10 occurrences of the “My Error” error in the Kernel error log.

NOTE: For more information, see the APPERROR^%ZTER API.