ZWRITE (ObjectScript)
Synopsis
ZWRITE:pc expression,...
ZW:pc expression,...
Arguments
Argument | Description |
---|---|
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. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions.
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 displays the same result for a local variable set to a JSON array or JSON object. It does not display any further details about the OREF. For information on OREFs, see OREF Basics.
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.
-
Variables: displayed as varname=value
-
Expressions: evaluated and the results displayed as value
-
Special Variables: displayed as value
-
InterSystems IRIS List Structures: displayed as $lb(element1,element2)
-
Subscripted Globals, including those used to store SQL data values and SQL index values, displayed as $lb() List structures
-
Object References: displayed as <OBJECT REFERENCE>[oref]. This is the value displayed by ZWRITE without an argument; ZWRITE with an object reference argument displays this value plus additional “general information”, “attribute values”, and (where appropriate) “swizzled references” and “calculated references” information.
-
JSON Arrays and JSON Objects: displayed as JSON values.
-
Bit Strings: displayed as both the $ZWCHAR compressed binary string, and a user-readable representation of all of the “1” bits in the bitstring.
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 Display (Write) Commands.
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 InterSystems IRIS 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()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class or the RefInKindOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class has been set to strip extended global references. If you specify a nonexistent namespace, InterSystems IRIS issues a <NAMESPACE> error. If you specify a namespace for which you do not have privileges, InterSystems IRIS issues a <PROTECT> error, followed by the global name and database path, such as the following: <PROTECT> ^myglobal,c:\intersystems\iris\mgr\. For further information on subscripted variables and extended global reference, refer to Formal Rules about 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, InterSystems IRIS 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.
InterSystems IRIS List Structures
You can specify an InterSystems IRIS 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
A Subscripted Global and its Descendants
The following example shows ZWRITE displaying the contents of a subscripted global variable and all of its descendent nodes. This example displays the data defined for the Sample.Person persistent class that projects to an SQL table. The global variable takes its name from the persistent class name (not the SQL table name) and is case-sensitive; a “D” is appended to indicate a data global. Note that the descendent nodes contain list structures, which are displayed as $LISTBUILD ($lb) constructions:
ZWRITE ^Sample.PersonD
To display a single data record, you can specify the RowID value as the global subscript, as shown in the following:
ZWRITE ^Sample.PersonD(22)
To display the contents of an index, you can specify the persistent class name with an “I” appended, supplying the index name as the subscript. The index name is case-sensitive:
ZWRITE ^Sample.PersonI("NameIDX")
Additional non-printing characters used in lists are also displayed.
The following example shows ZWRITE using extended global reference to display the contents of a subscripted global variable located in a specified namespace:
ZWRITE ^["USER"]Sample.PersonD
The namespace name can be a different namespace or the current namespace. Namespace names are not case-sensitive.
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.
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 a value such as the following: variable=9@%SQL.Statement ; <OREF> or 9@%SQL.Statement ; <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.
The <OREF> identifier suffix 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()Opens in a new tab 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).%New("mytempdomain")
DO doref.%Save()
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”:
SET poref=##class(Sample.Person).%OpenId(1)
ZWRITE poref
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.
JSON Arrays and JSON Objects
ZWRITE without an argument displays JSON dynamic arrays and JSON dynamic objects as object references, for example:
USER>SET jarray = ["apples","oranges"]
USER>SET jobj = {"fruit":"apples","count":24}
USER>ZWRITE
jarray=<OBJECT REFERENCE>[1@%Library.DynamicArray]
jobj=<OBJECT REFERENCE>[2@%Library.DynamicObject]
ZWRITE with an argument displays the values of JSON dynamic arrays and JSON dynamic objects. This is shown in the following example:
A JSON array:
USER>SET jarray = ["apples","oranges"]
USER>SET jobj = {"fruit":"apples","count":24}
USER>ZWRITE jarray
jarray = ["apples","oranges"] ; <DYNAMIC ARRAY>
USER>ZWRITE jobj
jobj = {"fruit":"apples","count":24} ; <DYNAMIC OBJECT>
ZWRITE without an argument displays an OREF value within a JSON object as shown in the following example:
USER>SET oref = ##class(%SQL.Statement).%New()
USER>SET jobj = {"ObjRef":(oref)}
USER>ZWRITE
jobj=<OBJECT REFERENCE>[4@%Library.DynamicObject]
oref=<OBJECT REFERENCE>[6@%SQL.Statement]
ZWRITE with an JSON object OREF argument displays an OREF value within a JSON object using a format like ("6@%SQL.Statement"):
USER>SET orefsql = ##class(%SQL.Statement).%New()
USER>SET jobjsql = {"ObjRef":(orefsql)}
USER>SET orefrs = ##class(%ResultSet).%New()
USER>SET jobjrs = {"ObjRef":(orefrs)}
USER>ZWRITE jobjsql
jobjsql={"ObjRef":("6@%SQL.Statement")} ; <DYNAMIC OBJECT>
USER>ZWRITE jobjrs
jobjrs={"ObjRef":("7@%Library.ResultSet")} ; <DYNAMIC OBJECT>
For information on object references (OREFs), see OREF Basics.
ZWRITE handles $DOUBLE values in a JSON object as follows:
ZWRITE without an argument
USER>SET jnum = {"doub":($DOUBLE(1.234))}
USER>SET jnan = {"doub":($DOUBLE("NAN"))}
USER>SET jinf = {"doub":($DOUBLE("-INF"))}
USER>ZWRITE
jinf=<OBJECT REFERENCE>[6@%Library.DynamicObject]
jnan=<OBJECT REFERENCE>[5@%Library.DynamicObject]
jnum=<OBJECT REFERENCE>[4@%Library.DynamicObject]
ZWRITE with a $DOUBLE JSON object argument:
USER>SET jnum = {"doub":($DOUBLE(1.234))}
USER>SET jnan = {"doub":($DOUBLE("NAN"))}
USER>SET jinf = {"doub":($DOUBLE("-INF"))}
USER>ZWRITE jnum
jnum={"doub":1.2339999999999999857} ; <DYNAMIC OBJECT>
USER>ZWRITE jnan
jnan={"doub":($DOUBLE("NAN"))} ; <DYNAMIC OBJECT>
USER>ZWRITE jinf
jnan={"doub":($DOUBLE("-INF"))} ; <DYNAMIC OBJECT>
For further details on handling JSON in ObjectScript, refer to the SET command.
Bitstrings
You can specify a bitstring to ZWRITE as either a variable or an expression. If the ZWRITE argument is an InterSystems IRIS 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