Kernel 8.0 APIs Banner [skip navigation]
Office of Information & Technology (OIT) Banner

^%ZTER: Kernel Standard Error Recording Routine

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


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.

NOTE: As of Kernel Patch XU*8.0*431, the ^%ZTER error trap routine checks a count (limit) in the ERROR TRAP SUMMARY file (#3.077) 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 field (#520.1) in the KERNEL SYSTEM PARAMETERS file (#8989.3).



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


(optional) The %ZT array can be used to identify a global node whose descendents should be recorded in the error log. When called within the standard Kernel error trap, %ZT is set to record the user's location in the menu system:

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



Calls to the error recorder always return this parameter. It has the error name and error type as its first and second caret-delimited ("^") pieces, for example, %ZTERROR=UNDEF^P. While the first piece is always defined since it is retrieved from the operating system, the second piece could be missing if unavailable from the ERROR MESSAGES file (#3.076).

Example 1

The following is an example of the Error Trap:

ZXGAPP ; 999/NV - sample routine ; 23-FEB-95
	; This code resets the error trap routine that is stepped to 
	; when an error occurs.
	; Open a file, and read lines from it until End-of-File (EOF)
	; is reached.
	K %ZIS S %ZIS=""
	; 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. 

Example 2

To test the error limit set in the ERROR LIMIT field (#520.1) in the KERNEL SYSTEM PARAMETERS file (#8989.3), 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 file [#3.075])). If the value in the ERROR LIMIT field (#520.1) is set to "10", there should just be 10 occurrences of the “My Error” error in the Kernel error log.

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


VA (Internet) / VA(Intranet) / OI / PD / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: January 10, 2012

If you have questions, need more information, or are having accessibility problems with this website, please contact us by E-Mail: Webmasters, Phone: 510-768-6800, or FAX: 510-768-6850.