Caché ObjectScript Reference
ZWRITE
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Displays variable names and their values and/or expression values.
Synopsis
ZWRITE:pc expression,...
ZW:pc expression,...
Arguments
pc Optional — A postconditional expression.
expression Optional — A variable or expression to display, or a comma-separated list of variables and/or expressions to display. A comma-separated list can contain any combination of variables and expressions.
Description
The ZWRITE command lists names of variables and their values. It lists these variables and their descendents in the format varname=value in canonical order, one variable per line, on the current device. ZWRITE also lists the values of expressions. Expressions are listed as value, one per line, in the order specified. The ZWRITE command has two forms:
ZWRITE can take 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.
ZWRITE listing can be interrupted by issuing a CTRL-C, generating an <INTERRUPT> error.
ZWRITE without an Argument
ZWRITE without an expression argument is functionally identical to WRITE without an argument. It displays the names and values of all variables in the local variable environment (local variables), including private variables. It does not display process-private globals or special variables. It lists variables by name in ASCII order. It lists subscripted variables in subscript tree order.
ZWRITE without an argument displays an OREF value assigned to a local variable as variable=<OBJECT REFERENCE>[oref]. It does not display any further details about the OREF. For information on OREFs, see OREF Basics in Using Caché Objects.
ZWRITE without an argument displays a bitstring assigned to a local variable as a compressed character string, which (because it contains non-printing characters) may appear to be an empty string. It does not display any further details about the bitstring.
For further details, refer to the WRITE command.
ZWRITE with Arguments
ZWRITE with an argument can specify one expression argument or a comma-separated list of expression arguments. These arguments are evaluated in left-to-right order. Each argument can specify a variable or an expression. If expression is a comma-separated list, each variable or expression is displayed on a separate line.
ZWRITE displays a string containing one or more non-numeric characters as a quoted string.
ZWRITE displays a numeric value as a canonical number. ZWRITE displays a numeric string containing a number in canonical form as an unquoted canonical number. ZWRITE displays a numeric string not in canonical form as a quoted string. Note however that any arithmetic operation on a non-canonical numeric string converts it to a canonical number. This is shown in the following example:
  SET numcanon=7.9     // returns number
  SET num=+007.90      // returns number
  SET strnum="+7.9"    // returns string
  SET strcanon="7.9"   // returns number
  SET strnumop=+"+7.90" // returns number
  ZWRITE numcanon,num,strnum,strcanon,strnumop
 
ZWRITE truncates the display of very long strings and appends ... to indicate that the string display was truncated.
ZWRITE displays values containing control characters (including those created with $LISTBUILD and $BIT) in a readable format. If this formatting causes very long string values to exceed the maximum string length, ZWRITE truncates the displayed string and appends ... to indicate that the string was truncated.
For a comparison of ZWRITE with the WRITE, ZZDUMP, and ZZWRITE commands, refer to the Display (Write) Commands features tables in the “Commands” chapter of Using Caché ObjectScript.
Variables
If expression is a variable, ZWRITE writes varname=value on a separate line. The variable can be a local variable, process-private global, global variable, or object reference (OREF).
ZWRITE ignores undefined variables. It does not issue an error. If you specify one or more undefined variables in a comma-separated list of variables, ZWRITE ignores the undefined variables and returns the defined variables. This behavior allows you to display multiple variables without checking to determine if all of them are defined. If you specify an undefined variable to WRITE, ZZDUMP, or ZZWRITE Caché issues an <UNDEFINED> error.
Variables can be subscripted. If the variable has defined subnodes, ZWRITE writes a separate varname=value line for each subnode in subscript tree order. When you specify a root node, ZWRITE displays all of its subnodes, even when the root node is undefined.
You can use extended global reference to specify a global variable not mapped to the current namespace. ZWRITE displays extended global references even when the RefInKind() method of the %SYSTEM.Process class or the RefInKind property of the Config.Miscellaneous class has been set to strip extended global references. If you specify a nonexistent namespace, Caché issues a <NAMESPACE> error. If you specify a namespace for which you do not have privileges, Caché issues a <PROTECT> error, followed by the global name and database path, such as the following: <PROTECT> ^myglobal,c:\intersystems\cache\mgr\. For further information on subscripted variables and extended global reference, refer to Global Structure in Using Caché Globals.
Non-Display Characters
ZWRITE displays all printable characters. It displays non-printable characters using the $CHAR function, representing each non-printable character as a concatenated $c(n) value. It does not execute non-printing control characters. This is shown in the following example:
  SET charstr=$CHAR(65,7,66,67,0,68,11,49,50)
  ZWRITE charstr
 
Expressions
If expression is a literal expression, ZWRITE evaluates the expression and writes the resulting value on a separate line. If the expression contains an undefined variable, Caché issues an <UNDEFINED> error.
If the expression is a multidimensional property, ZWRITE will not display the property descendents. To display an entire multidimensional property with ZWRITE, either MERGE it into a local array and display the array, or display the entire object.
Caché List Structures
You can specify a Caché list structure (%List) to ZWRITE as a variable or an expression. ZWRITE displays a list structure as $lb(element1,element2). This is shown in the following example:
  SET FullList = $LISTBUILD("Red","Blue","Green","Yellow")
  SET SubList = $LIST(FullList,2,4)
  SET StrList = $LISTFROMSTRING("Crimson^Azure^Lime","^")
  ZWRITE FullList,SubList,StrList
 
Object References
You can specify an object reference (OREF) to ZWRITE as either a variable or an expression. If you have specified an object reference, ZWRITE displays variable=<OBJECT REFERENCE>[oref] or <OBJECT REFERENCE>[oref] and also displays General Information, Attribute Values, and (when appropriate) Swizzled References and Calculated References for the properties of the object, one attribute per line.
Note:
The <OBJECT REFERENCE> identifier prefix may not be displayed when executing ZWRITE through a browser interface, because browsers interpret angle brackets as tags.
If the ZWRITE argument is an embedded object property, ZWRITE displays General Information and Attribute Values for the array elements of the container property, one attribute per line. The display format is the same as the %SYSTEM.OBJ.Dump() method.
The following example displays the OREF, followed by “general information”, “attribute values” and “swizzled references”:
  SET oref = ##class(%SQL.Statement).%New()
  ZWRITE oref
 
The following example displays the OREF, followed by “general information”, “attribute values”, and “calculated references”:
  SET doref=##class(%iKnow.Domain).Create("mytempdomain")
  SET domId=doref.Id
  ZWRITE doref
  SET stat=##class(%iKnow.Domain).DeleteId(domId)
 
The following examples displays the OREF, followed by “general information”, “attribute values”, “swizzled references”, and “calculated references”:
  ZNSPACE "Samples"
  SET poref=##class(Sample.Person).%OpenId(1)
  ZWRITE poref
 
  ZNSPACE "SAMPLES"
  SET myquery = "SELECT TOP 2 Name,DOB FROM Sample.Person"
  SET oref = ##class(%SQL.Statement).%New()
  SET qStatus = oref.%Prepare(myquery)
    IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT}
  SET rset = oref.%Execute()
  ZWRITE rset
 
For information on OREFs, see OREF Basics in Using Caché Objects.
JSON Arrays and JSON Objects
ZWRITE displays JSON dynamic arrays and JSON dynamic objects as object references. The referenced object classes are %Library.DynamicArray and %Library.DynamicObject. This is shown in the following example:
A JSON array:
  SET jarray = ["apples","oranges"]
  ZWRITE jarray
 
A JSON object:
  SET jobj = {"fruit":"apples","count":24}
  ZWRITE jobj
 
For information on object references (OREFs), see OREF Basics in Using Caché Objects.
Bitstrings
You can specify a bitstring to ZWRITE as either a variable or an expression. If the ZWRITE argument is a Caché compressed bitstring (created using the $BIT function), ZWRITE displays the decimal representation of the compressed binary string as $ZWCHAR ($zwc) two-byte (wide) characters.
ZWRITE also displays a comment that lists the uncompressed “1” bits in left-to-right order as a comma-separated list. If there are three or more consecutive “1” bits, it lists them as a range (inclusive) with two dot syntax (n..m). For example, the bitstring [1,0,1,1,1,1,0,1] is shown as /*$bit(1,3..6,8)*/. The bitstring [1,1,1,1,1,1,1,1] is shown as /*$bit(1..8)*/. The bitstring [0,0,0,0,0,0,0,0] is shown as /*$bit()*/. The following example shows ZWRITE bitstring output:
  SET $BIT(a,1) = 0
  SET $BIT(a,2) = 0
  SET $BIT(a,3) = 1
  SET $BIT(a,4) = 0
  SET $BIT(a,5) = 1
  SET $BIT(a,6) = 1
  SET $BIT(a,7) = 1
  SET $BIT(a,8) = 0
  ZWRITE a
 
Examples
ZWRITE Without an Argument
In following example, ZWRITE without an argument lists all defined local variables in ASCII name order.
   SET A="A",a="a",AA="AA",aA="aA",aa="aa",B="B",b="b"
   ZWRITE
returns:
A="A"
AA="AA"
B="B"
a="a"
aA="aA"
aa="aa"
b="b"
In the following example ZWRITE without an argument lists canonical and non-canonical numeric values:
   SET w=10
   SET x=++0012.00
   SET y="6.5"
   SET z="007"
   SET a=w+x+y+z
   ZWRITE
returns:
a=35.5
w=10
x=12
y=6.5
z="007"
ZWRITE with Arguments
In the following example, ZWRITE displays three variables as varname=value, each on its own line:
   SET alpha="abc"
   SET x=100
   SET y=80
   SET sum=x+y
   ZWRITE x,sum,alpha
 
In the following example, ZWRITE evaluates an expression in the first argument. It returns the expression as value, and the variable as varname=value:
   SET x=100
   SET y=80
   ZWRITE x+y,y
The following example compares ZWRITE and WRITE when displaying different variable values. ZWRITE returns quotation marks delimiting strings, WRITE does not:
   SET a=+007.00
   SET b=9E3
   SET c="+007.00"
   SET d=""
   SET e="Rhode Island"
   SET f="Rhode"_"Island"
   ZWRITE a,b,c,d,e,f
   WRITE !,a,!,b,!,c,!,d,!,e,!,f
 
ZWRITE Displaying Subscript Subnodes
The following example shows ZWRITE displaying the contents of subscripted process-private global variables. ZWRITE displays the subscripts of the variable in hierarchical order:
   SET ^||fruit(1)="apple",^||fruit(4)="banana",^||fruit(8)="cherry"
   SET ^||fruit(1,1)="Macintosh",^||fruit(1,2)="Delicious",^||fruit(1,3)="Granny Smith"
   SET ^||fruit(1,2,1)="Red Delicious",^||fruit(1,2,2)="Golden Delicious"
   SET ^||fruit="Fruits"
   WRITE "global arg ZWRITE:",!
   ZWRITE ^||fruit
 
Note that specifying a root node displays all subnodes, even when the root node itself is undefined:
   SET fruit(1)="apple",fruit(4)="banana",fruit(8)="cherry"
   SET fruit(1,1)="Macintosh",fruit(1,2)="Delicious",fruit(1,3)="Granny Smith"
   SET fruit(1,2,1)="Red Delicious",fruit(1,2,2)="Golden Delicious"
   WRITE "global arg ZWRITE:",!
   ZWRITE fruit
 
ZWRITE Displaying a Global and its Descendants
The following example shows ZWRITE displaying the contents of a subscripted global variable and all its descendent nodes. Note that the descendent nodes contain list structures, which are displayed as $LISTBUILD ($lb) constructions:
   ZNSPACE "SAMPLES"
   ZWRITE ^CinemaooFilmCategoryD
 
Additional non-printing characters used in lists are also displayed.
ZWRITE Displaying a Global in Another Namespace
The following example shows ZWRITE using extended global reference to display the contents of a subscripted global variable located in another namespace:
   ZNSPACE "SAMPLES"
   ZWRITE ^CinemaooFilmD(17)
   WRITE !,"Changing namespace",!!
   ZNSPACE "USER"
   ZWRITE ^["SAMPLES"]CinemaooFilmD(17)
 
ZWRITE always displays the extended global reference, regardless of the setting of the RefInKind method or property, which can be set to strip extended global references from globals returned by $QUERY or $NAME.
See Also