$ZREFERENCE

Synopsis

$ZREFERENCE
$ZR

Description

$ZREFERENCE contains the name and subscript(s) of the last global reference. This is known as the naked indicator.

The last global reference can be either a global (^myglob) or a process-private global (^||myppg). $ZREFERENCE returns the process-private global prefix in the form that was initially used for that variable, regardless of which process-private global prefix is used subsequently for that variable. In the description of $ZREFERENCE that follows, the word “global” refers to both types of variables.

The last global reference is the global most recently referred to by a command or a function. Because ObjectScript performs operations in left-to-right order, the last global reference is always the rightmost global. When a command or function takes multiple arguments, the global specified in the rightmost argument is the last global reference. When an argument contains multiple global references, the rightmost specified global is the last global reference. This strict left-to-right order holds true even if parentheses are used to define the order of operations.

Caché updates $ZREFERENCE when an explicit global reference is issued. Invoking an expression (such as a local variable) that evaluates to a global reference does not update $ZREFERENCE.

$ZREFERENCE contains the most recent global reference, even if this global reference was not successful. When a command references an undefined global, issuing an <UNDEFINED> error, Caché updates $ZREFERENCE to that global reference, just as if the global were defined. This behavior is unaffected by setting the %SYSTEM.Process.Undefined()Opens in a new tab method.

$ZREFERENCE often contains the most recent global reference, even if the command execution was not successful. Caché updates $ZREFERENCE as each global is referenced. For example, a command issuing a <DIVIDE> error (attempting to divide a number by 0) updates $ZREFERENCE to the last global referenced in the command before the error occurred. However, a <SYNTAX> error does not update $ZREFERENCE.

Naked Global Reference

If the last global reference was a naked global reference, $ZREFERENCE contains the external, readable, full form of the current naked global reference. This is demonstrated in the following example:

  SET ^MyData(1)="fruit"
  SET ^MyData(1,1)="apples" ; Full global reference
  SET ^(2)="oranges"        ; Naked global reference,
                            ; implicitly ^MyData(1,2)
  WRITE !,$ZREFERENCE       ; Returns "^MyData(1,2)"

For further details on naked global references, see Using Caché Multidimensional Storage (Globals) in Using Caché Globals.

Examples

The following example returns the last global reference:

   SET ^a(1,1)="Hello"  ; Full global reference
   SET ^(2)=" world!"   ; Naked global reference
   WRITE $ZREFERENCE

returns:

^a(1,2)

The following example returns global references from several different commands. Note that WRITE and ZWRITE set different representations of the same global reference.

   SET (^barney,^betty,^wilma,^fred)="flintstone"
   WRITE !,$ZREFERENCE
   KILL ^flies
   WRITE !,$ZREFERENCE
   WRITE !,^fred
   WRITE !,$ZREFERENCE,!
   ZWRITE ^fred
   WRITE !,$ZREFERENCE

returns:

^fred          ; last of several globals set in left-to-right order
^flies         ; KILL sets global indicator, though no global to kill
flintstone                ; WRITE global
^fred                       ; global from WRITE
^fred="flintstone"   ; ZWRITE global
^fred("")                 ; global from ZWRITE

The following example returns an extended global reference. Note that the namespace name is always returned in uppercase letters:

   SET ^["samples"]a(1,1)="Hello"
   SET ^(2)=" world!"
   WRITE $ZREFERENCE
   QUIT

returns:

^["SAMPLES"]a(1,2)

The following example returns the last global reference. In this case, it is ^a(1), used as an argument to the $LENGTH function:

   SET ^a(1)="abcdefghijklmnopqrstuvwxyz"
   SET ^b(1)="1234567890"
   SET x=$LENGTH(^a(1))
   WRITE $ZREFERENCE
   QUIT

The following example returns the value set for $ZREFERENCE as if it were the last global reference. In this case, it is ^a(1,1).

   SET ^a(1,1)="abcdefghijklmnopqrstuvwxyz"
   SET ^b(1,1)="1234567890"
   WRITE !,^(1)
             ; Naked reference uses last global
   SET $ZREFERENCE="^a(1,1)"
   WRITE !,$ZREFERENCE
   WRITE !,^(1)
             ; Naked reference uses $ZREFERENCE
             ; value, rather than last global.

The following example sets an extended global reference. Note the doubled quotation marks:

   KILL ^x
   WRITE !,$ZREFERENCE
   SET $ZREFERENCE="^[""samples""]a(1,2)"
   WRITE !,$ZREFERENCE

See Also

• ZNSPACE command

• $NAMESPACE special variable

• $ZNSPACE special variable

• Configuring Namespaces in Caché System Administration Guide

• Global Structure in Using Caché Globals

• Naked Global Reference in Using Caché Globals