(Legacy) Using ^%ETN for Error Logging

An older style of error logging uses the ^%ETN utility, described here for reference.

The ^%ETN utility logs an exception to the application error log and then exits. You can invoke ^%ETN (or one of its entry points) as a utility:

  DO ^%ETN

Or you can set the $ZTRAP special variable equal to ^%ETN (or one of its entry points):

  SET $ZTRAP="^%ETN"

You can specify ^%ETN or one of its entry points:

• FORE^%ETN (foreground) logs an exception to the standard application error log, and then exits with a HALT. This invokes a rollback operation. This is the same operation as ^%ETN.

• BACK^%ETN (background) logs an exception to the standard application error log, and then exits with a QUIT. This does not invoke a rollback operation.

• LOG^%ETN logs an exception to the standard application error log, and then exits with a QUIT. This does not invoke a rollback operation. The exception can be a standard %Exception.SystemExceptionOpens in a new tab, or a user-defined exception.

  To define an exception, set $ZERROR to a meaningful value prior to calling LOG^%ETN; this value will be used as the Error Message field in the log entry. You can also specify a user-defined exception directly into LOG^%ETN: DO LOG^%ETN("This is my custom exception"); this value will be used as the Error Message field in the log entry. If you set $ZERROR to the null string (SET $ZERROR="") LOG^%ETN logs a <LOG ENTRY> error. If you set $ZERROR to <INTERRUPT> (SET $ZERROR="<INTERRUPT>") LOG^%ETN logs an <INTERRUPT LOG> error.

  LOG^%ETN returns a %List structure with two elements: the $HOROLOG date and the Error Number.

The following example uses the recommended coding practice of immediately copying $ZERROR into a variable. LOG^%ETN returns a %List value:

  SET err=$ZERROR
  /* error handling code */
  SET rtn = $$LOG^%ETN(err)
  WRITE "logged error date: ",$LIST(rtn,1),!
  WRITE "logged error number: ",$LIST(rtn,2)

Calling LOG^%ETN or BACK^%ETN automatically increases the available process memory, does the work, and then restores the original $ZSTORAGE value. However, if you call LOG^%ETN or BACK^%ETN following a <STORE> error, restoring the original $ZSTORAGE value might trigger another <STORE> error. For this reason, the system retains the increased available memory when these ^%ETN entry points are invoked for a <STORE> error.