Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

ZQUIT (legacy command)

Exits a program with error handling.

Synopsis

ZQ:pc expression

Arguments

Argument Description
pc Optional — A postconditional expression.
expression Optional — An expression that evaluates to an integer greater than 0.

Description

Caché platforms recognize only the ZQ abbreviation for ZQUIT.

Note:

This page describes the legacy ZQUIT command. The ZQUIT command is considered legacy as of Caché 5.1, and should not be used in new programming. It is described here solely for compatibility with legacy applications. New programming should use the ZTRAP command with the $ZERROR argument to pass control between error handlers. A ZQUIT command in new procedure code will result in a <COMMAND> error. Refer to the ZTRAP command for further details.

The ZQUIT command exits a coded routine and provides explicit control for error handling.

Each time a DO, FOR, or XECUTE command is executed, or a user-defined function is invoked, Caché places return information on the program stack (sometimes called the "call stack"). ZQUIT provides a mechanism whereby a nested error-handling routine can pass control to a higher level error handler. ZQUIT re-signals the error condition and causes Caché to unwind the program (call) stack.

ZQUIT is similar to the QUIT command, but it provides explicit control for error handling. Unlike the QUIT command, ZQUIT can be used only in a coded routine. Caché ignores ZQUIT when entered from the programmer prompt.

ZQUIT has two forms:

  • Without an argument.

  • With an argument.

ZQUIT Without an Argument

Argumentless ZQUIT clears the entire stack.

ZQUIT With an Argument

ZQ expression unwinds the stack to another call stack level with a $ZTRAP error handler. The value of expression specifies the number of handler-specified stack levels ZQUIT unwinds. If you use 1 as expression, Caché unwinds the stack to the first encountered $ZTRAP handler. If you use 2 as expression, Caché unwinds the stack to the second encountered $ZTRAP handler, and so on.

Arguments

pc

An optional postconditional expression. Caché executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). Caché does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions in Using Caché ObjectScript.

expression

Any valid ObjectScript expression that evaluates to an integer greater than 0. Caché platforms use the settings of $ZTRAP to clear the program stack back to the setting indicated by the resulting integer.

Example

The following is an example of a magnetic-tape read routine that reads a record into x, returns a tapemark flag (tm) TRUE (1) if it reads a tape mark (an "expected" error), and lets its caller’s errortrap routine, if any, handle any other errors:

Mtread
  SET $ZTRAP="Mterr"
  USE 47
  READ x
  SET tm=0
  QUIT ; Normal return
Mterr
  IF $ZERROR?1"<MAGTAPE>" ; Pattern matching: repcount stringliteral
  { } ; Automatic branch to error-trap handler
  ELSE { SET tm=123 }
  IF tm=1 { QUIT }
  ELSE {ZQ 1 }
  IF $ZTRAP'="" {GOTO @$ZTRAP} ; To caller's error routine
  ELSE
  { ; No caller's error routine
   USE 0
   WRITE !,$ZERROR ZQ
   QUIT
  }

Notes

Behavior of Argumentless ZQUIT

When specified with no arguments, ZQUIT unwinds the entire stack. Execution continues at the main program level; that is, the level at which the job began, in either programmer mode or application mode.

ZQUIT does not change the flow of control. Execution continues with the ObjectScript command that follows ZQUIT. To mimic the errortrap behavior of M/11, an error processing routine should end with the commands

   ZQ  QUIT

Note that there are two spaces after ZQ.

Here the QUIT command returns to programmer mode if the job began in programmer mode or it exits if the job began in application mode. To log application errors, end your errortrap code with:

   ZQ  GOTO ^%ET

Again, note the two spaces after ZQ.

Behavior of ZQUIT with an Argument

When specified with an argument, ZQUIT does not clear the entire stack, but instead clears it back one or more levels to the level at which a $ZTRAP special variable was set. The number of levels is specified by the expression argument, which must evaluate to an integer greater than 0. $ZTRAP directs error trapping to the routine to which it is set.

For example:

   ZQ 1

clears the stack back to the previous level at which $ZTRAP was set. Passing an argument of "2" to ZQUIT clears the stack back to the second to last level at which $ZTRAP was set, and so on.

Caché continues program execution on the execution level that contains the errortrap routine currently set in $ZTRAP. When that errortrap routine quits, control reverts to the same place that it would on a QUIT from the subroutine that set $ZTRAP.

If Caché should find an error handler specified by the $ETRAP special variable at a stack level before reaching the stack level of the specified $ZTRAP error handler, Caché passes control to that $ETRAP error handler. If the $ETRAP error handler cannot dismiss the error, the $ZTRAP error handler that issued the original ZQUIT gains control again. At that point, the $ZTRAP error handler can use a GOTO command to transfer control to the $ZTRAP handler originally specified.

Note:

Do not use an indirect GOTO (for example, ZQ 1 GOTO @$ZT) within a procedure or an object method with the default ProcedureBlock attribute. This results in a compile error, because you cannot use a GOTO to exit a procedure. Existing routines that use this construct should not be converted to procedures. Object methods that use this construct must be excepted from the ProcedureBlock attribute.

You can alter this error-return sequence by using ZQUIT in any of the following ways:

  • ZQ 1 QUIT — Returns to the caller of the subroutine that set the previous error trap.

  • ZQ 1 GOTO @$ZT — Invokes the previous errortrap routine. (See Note above.)

  • ZQ QUIT — Either halts the application or enters programmer mode with an empty program stack. Note the two spaces between ZQUIT and QUIT.

  • ZQ GOTO ^routine — Clears the program stack and resumes execution at the specified top-level routine that is typically a function driver. Note the two spaces between ZQUIT and GOTO.

See Also

Next sectionZSYNC (legacy command)
Previous sectionIF (legacy version)
FeedbackOpens in a new tab