Commands
The command is the basic unit of code in ObjectScript programming. All of the execution tasks in ObjectScript are performed by commands. Every command consists of a command keyword followed by (in most cases) one or more command arguments.
This topic provides an overview of the most commonly used commands; also see the ObjectScript Reference.
Command Keywords
In ObjectScript all command statements are explicit; every executable line of ObjectScript code must begin with a command keyword. For example, to assign a value to a variable, you must specify the SET keyword, followed by the arguments for the variable and the value to be assigned.
A command always begins with a keyword. Consider the following:
WRITE "Hello"
The word WRITE is the command keyword. It specifies the action to perform. The WRITE command does exactly what its name implies: it writes to the principal device whatever you specify as its argument. In this case, WRITE writes the string Hello.
ObjectScript command names are not case-sensitive. Most command names can be represented by an abbreviated form. Therefore, WRITE, Write, write, W, and w are all valid forms of the WRITE command. For a list of command abbreviations, see Table of Abbreviations.
Command keywords are not reserved words. It is therefore possible to use a command keyword as a user-assigned name for a variable, label, or other identifier.
In an ObjectScript program, the first command on a code line must be indented; the command keyword cannot appear in column 1. When issuing a command from the Terminal command line prompt, or from an XECUTE command, no indent is required (indent is permitted).
An executable line of code can contain one or more commands, each with their own command keyword. Multiple commands on a line are separated by one or more spaces. One or more commands may follow a label on the same line; the label and the command are separated by one or more spaces.
In ObjectScript no end-of-command or end-of-line delimiter is required or permitted. You can specify an in-line comment following a command, indicating that the rest of the command line is a comment. A blank space is required between the end of a command and comment syntax, with the exception of ##; and /* comment */ syntax. A /* comment */ multiline comment can be specified within a command as well as at the end of one.
Command Arguments
Following a command keyword, there can be zero, one, or multiple arguments that specify the object(s) or the scope of the command. If a command takes one or more arguments, you must include exactly one space between the command keyword and the first argument. For example:
SET x = 2
Spaces can appear within arguments or between arguments, so long as the first character of the first argument is separated from the command itself by exactly one space (as appears above). Thus the following are all valid:
SET a = 1
SET b=2
SET c=3,d=4
SET e= 5 , f =6
SET g
= 7
WRITE a,b,c,d,e,f,g
If a command takes a postconditional expression, there must be no spaces between the command keyword and the postconditional, and there must be exactly one space between the postconditional and the beginning of the first argument. Thus, the following are all valid forms of the QUIT command:
QUIT x+y
QUIT x + y
QUIT:x<0
QUIT:x<0 x+y
QUIT:x<0 x + y
No spaces are required between arguments, but multiple blank spaces can be used between arguments. These blank spaces have no effect on the execution of the command. Line breaks, tabs, and comments can also be included within or between command arguments with no effect on the execution of the command. For further details, see White Space.
Multiple Arguments
Many commands allow you to specify multiple independent arguments. The delimiter for command arguments is the comma ,. That is, you specify multiple arguments to a single command as a comma-separated list following the command. For example:
SET x=2,y=4,z=6
This command uses three arguments to assign values to the three specified variables. In this case, these multiple arguments are repetitive; that is, the command is applied independently to each argument in the order specified. Internally, InterSystems IRIS® data platform parses this as three separate SET commands. When debugging, each of these multiple arguments is a separate step.
In the command syntax provided in the command reference pages, arguments that can be repeated are followed by a comma and ellipsis: ,.... The comma is a required delimiter character for the argument, and the ellipsis (...) indicates that an unspecified number of repetitive arguments can be specified.
Repetitive arguments are executed in strict left-to-right order. Therefore, the following command is valid:
SET x=2,y=x+1,z=y+x
but the following command is not valid:
SET y=x+1,x=2,z=y+x
Because execution is performed independently on each repetitive argument, in the order specified, valid arguments are executed until the first invalid argument is encountered. In the following example, SET x assigns a value to x, SET y generates an <UNDEFINED> error, and because SET z is not evaluated, the <DIVIDE> (divide-by-zero) error is not detected:
KILL x,y,z
SET x=2,y=z,z=5/0
WRITE "x is:",x
Arguments with Parameters and Postconditionals
Some command arguments accept parameters (not to be confused with function parameters). If a given argument can take parameters, the delimiter for the parameters is the colon :).
The following sample command shows the comma used as the argument delimiter and the colon used as the parameter delimiter. In this example, there are two arguments, with four parameters for each argument.
VIEW X:y:z:a,B:a:y:z
For a few commands (DO, XECUTE, and GOTO), a colon following an argument specifies a postconditional expression that determines whether or not that argument should be executed.
Argumentless Commands
Commands that do not take an argument are referred to as argumentless commands. A postconditional expression appended to the keyword is not considered an argument.
There are a small number of commands that are always argumentless. For example, HALT, CONTINUE, TRY, TSTART, and TCOMMIT are argumentless commands.
Several commands are optionally argumentless. For example, BREAK, CATCH, FOR, GOTO, KILL, LOCK, NEW, QUIT, RETURN, TROLLBACK, WRITE, and ZWRITE all have argumentless syntactic forms. In such cases, the argumentless command may have a slightly different meaning than the same command with an argument.
If you use an argumentless command at the end of the line, trailing spaces are not required. If you use an argumentless command on the same code line as other commands, you must place two (or more) spaces between the argumentless command and any command that follows it. For example:
QUIT:x=10 WRITE "not 10 yet"
In this case, QUIT is an argumentless command with a postconditional expression, and a minimum of two spaces is required between it and the next command.
Argumentless Commands and Curly Braces
Argumentless commands when used with command blocks delimited by curly braces do not have whitespace restrictions:
-
An argumentless command that is immediately followed by an opening curly brace has no whitespace requirement between the command name and the curly brace. You can specify none, one, or more than one spaces, tabs, or line returns. This is true both for argumentless commands that can take an argument, such as FOR, and argumentless commands that cannot take an argument, such as ELSE.
FOR { WRITE !,"Quit out of 1st endless loop" QUIT } FOR{ WRITE !,"Quit out of 2nd endless loop" QUIT } FOR { WRITE !,"Quit out of 3rd endless loop" QUIT }
-
An argumentless command that is immediately followed by a closing curly brace does not require trailing spaces, because the closing curly brace acts as a delimiter. For example, the following is a valid use of the argumentless QUIT:
IF 1=2 { WRITE "Math error"} ELSE { WRITE "Arthmetic OK" QUIT} WRITE !,"Done"
Command Postconditional Expressions
In most cases, when you specify an ObjectScript command you can append a postconditional.
A postconditional is an optional expression that is appended to a command or (in some cases) a command argument that controls whether InterSystems IRIS executes that command or command argument. If the postconditional expression evaluates to TRUE (defined as nonzero), InterSystems IRIS executes the command or the command argument. If the postconditional expression evaluates to FALSE (defined as zero), InterSystems IRIS does not execute the command or command argument, and execution continues with the next command or command argument.
All ObjectScript commands can take a postconditional expression, except the flow-of-control commands (IF, ELSEIF, and ELSE; FOR, WHILE, and DO WHILE) and the block structure error handling commands (TRY, THROW, CATCH).
The ObjectScript commands DO and XECUTE can append postconditional expressions both to the command keyword and to their command arguments. A postconditional expression is always optional; for example, some of the command’s arguments may have an appended postconditional while its other arguments do not.
If both a command keyword and one or more of that command’s arguments specify a postconditionals, the keyword postconditional is evaluated first. Only if this keyword postconditional evaluates to TRUE are the command argument postconditionals evaluated. If a command keyword postconditional evaluates to FALSE, the command is not executed and program execution continues with the next command. If a command argument postconditional evaluates to FALSE, the argument is not executed and execution of the command continues with the next argument in left-to-right sequence.
Postconditional Syntax
To add a postconditional to a command, place a colon (:) and an expression immediately after the command keyword, so that the syntax for a command with a postconditional expression is:
Command:pc
where Command is the command keyword, the colon is a required literal character, and pc can be any valid expression.
A command postconditional must follow these syntax rules:
-
No spaces, tabs, line breaks, or comments are permitted between a command keyword and its postconditional, or between a command argument and its postconditional. No spaces are permitted before or after the colon character.
-
No spaces, tabs, line breaks, or comments are permitted within a postconditional expression, unless either an entire postconditional expression is enclosed in parentheses or the postconditional expression has an argument list enclosed in parentheses. Spaces, tabs, line breaks, and comments are permitted within parentheses.
-
Spacing requirements following a postconditional expression are the same as those following a command keyword: there must be exactly one space between the last character of the keyword postconditional expression and the first character of the first argument; for argumentless commands, there must be two or more spaces between the last character of the postconditional expression and the next command on the same line, unless the postconditional is immediately followed by a close curly brace. (If parentheses are used, the closing parenthesis is treated as the last character of the postconditional expression.)
Note that a postconditional expression is not technically a command argument (though in the ObjectScript reference pages the explanation of the postconditional is presented as part of the Arguments section). A postconditional is always optional.
Evaluation of Postconditionals
InterSystems IRIS evaluates a postconditional expression as either True or False. Most commonly these are represented by 1 and 0, which are the recommended values. However, InterSystems IRIS performs postconditional evaluation on any value, evaluating it as False if it evaluates to 0 (zero), and True if it evaluates to a nonzero value.
-
InterSystems IRIS evaluates as True any valid nonzero numeric value. It uses the same criteria for valid numeric values as the arithmetic operators. Thus, the following all evaluate to True: 1, “1”, 007, 3.5, -.007, 7.0 , 3 little pigs, $CHAR(49), 0_"1".
-
InterSystems IRIS evaluates as False the value zero (0), and any nonnumeric value, including a null string ("") or a string containing a blank space (" "). Thus, the following all evaluate to False: 0, -0.0, A, -, $, The 3 little pigs, $CHAR(0), $CHAR(48), "0_1".
-
Standard equivalence rules apply. Thus, the following evaluate to True: 0=0, 0="0", "a"=$CHAR(97), 0=$CHAR(48), and (" "=$CHAR(32)). The following evaluate to False: 0="", 0=$CHAR(0), and (""=$CHAR(32)).
In the following example, which WRITE command is executed depends on the value of the variable count:
FOR count=1:1:10 {
WRITE:count<5 count," is less than 5",!
WRITE:count=5 count," is 5",!
WRITE:count>5 count," is greater than 5",!
}
Multiple Commands on a Line
A single line of ObjectScript source code may contain multiple commands and their arguments. They are executed in strict left-to-right order, and are functionally identical to commands appearing on separate lines. A command with arguments must be separated from the command following it by one space character. An argumentless command must be separated from the command following it by two space characters. A label can be followed by one or more commands on the same line. A comment can follow one or more commands on the same line.
For the maximum length of a line of source code, see General System Limits. Note that if you are using Studio to write or edit source code, this limit may differ.
Variables
To assign a value to a variable, use the SET command.
The SET command assigns values to variables. It can assign a value to a single variable or to multiple variables at once.
The most basic syntax of SET is:
SET variable = expression
This sets the value of a single variable. It also involves several steps:
-
ObjectScript evaluates the value expression, determining its value (if possible). This step can generate errors, if the expression contains an undefined variable, invalid syntax (such as division by zero), or other errors.
-
If the variable does not already exist, ObjectScript creates it.
-
Once the variable has been created, or if it already exists, ObjectScript sets its value to that of the expression.
To set the value for each of multiple variables, use the following syntax:
SET variable1 = expression1, variable2 = expression2, variable3 = expression3
To set multiple variables equal to a single expression use the following syntax:
SET (variable1,variable2,variable3)= expression
For example, to set the value of the Gender property of an instance of the Person class use the following code:
SET person.Gender = "Female"
where person is the object reference to the relevant instance of the Person class.
You can also set the Gender property of multiple Person objects at the same time:
SET (per1.Gender, per2.Gender, per3.Gender) = "Male"
where per1, per2, and per3 are object references to three different instances of the Person class.
You can use SET to invoke a method that returns a value. When invoking methods, SET allows you to set a variable, global reference, or property equal to the return value of a method. The form of the argument depends on whether the method is an instance or a class method. To invoke a class method, use the following construction:
SET retval = ##class(PackageName.ClassName).ClassMethodName()
Where ClassMethodName() is the name of the class method that you wish to invoke, ClassName is the name of the class containing the method, and PackageName is the name of the package containing the class. The method’s return value is assigned to the retval local variable. The ##class() construction is a required literal part of the code.
To invoke an instance method, you need only have a handle to the locally instantiated object:
SET retval = InstanceName.InstanceMethodName()
Where InstanceMethodName() is the name of the instance method that you wish to invoke, and InstanceName is the name of the instance containing the method. The method’s return value is assigned to the retval local variable.
For further details, see SET.
Error Processing
Use the TRY / CATCH block structure for error processing: It is recommended that you use the TRY and CATCH commands to create block structures for error processing.
See The TRY-CATCH Mechanism, and see TRY, THROW, and CATCH.
Transaction Processing
Use the TSTART, TCOMMIT, and TROLLBACK commands for transaction processing. See Transaction Processing, and see TSTART, TCOMMIT, and TROLLBACK.
Locking and Concurrency Control
Use the LOCK command for locking and unlocking resources. See Locking and Concurrency Control and see LOCK.
Locking is also relevant in transaction processing; see Transaction Processing.
Invoking Code
This section describes commands used for invoking the execution of one or more commands:
DO
To invoke a routine, procedure, or method in ObjectScript, use the DO command. The basic syntax of DO is:
DO ^CodeToInvoke
where CodeToInvoke can be an InterSystems IRIS system routine or a user-defined routine. The caret character ^ must appear immediately before the name of the routine.
You can run procedures within a routine by referring to the label of the line (also called a tag) where the procedure begins within the routine. The label appears immediately before the caret. For example,
SET %X = 484
DO INT^%SQROOT
WRITE %Y
This code sets the value of the %X system variable to 484; it then uses DO to invoke the INT procedure of the InterSystems IRIS system routine %SQROOT, which calculates the square root of the value in %X and stores it in %Y. The code then displays the value of %Y using the WRITE command.
When invoking methods, DO takes as a single argument the entire expression that specifies the method. The form of the argument depends on whether the method is an instance or a class method. To invoke a class method, use the following construction:
DO ##class(PackageName.ClassName).ClassMethodName()
where ClassMethodName() is the name of the class method that you wish to invoke, ClassName is the name of the class containing the method, and PackageName is the name of the package containing the class. The ##class() construction is a required literal part of the code.
To invoke an instance method, you need only have a handle to the locally instantiated object:
DO InstanceName.InstanceMethodName()
where InstanceMethodName() is the name of the instance method that you wish to invoke, and InstanceName is the name of the instance containing the method.
For further details, see DO.
JOB
While DO runs code in the foreground, JOB runs it in the background. This occurs independently of the current process, usually without user interaction. A jobbed process inherits all system defaults, except those explicitly specified.
For further details, see JOB.
XECUTE
The XECUTE command runs one or more ObjectScript commands; it does this by evaluating the expression that it receives as an argument (and its argument must evaluate to a string containing one or more ObjectScript commands). In effect, each XECUTE argument is like a one-line subroutine called by a DO command and terminated when the end of the argument is reached or a QUIT command is encountered. After InterSystems IRIS executes the argument, it returns control to the point immediately after the XECUTE argument.
For further details, see XECUTE.
QUIT and RETURN
The QUIT and RETURN commands both terminate execution of a code block, including a method. Without an argument, they simply exit the code from which they were invoked. With an argument, they use the argument as a return value. QUIT exits the current context, exiting to the enclosing context. RETURN exits the current program to the place where the program was invoked.
The following table shows how to choose whether to use QUIT RETURN:
Location | QUIT | RETURN |
---|---|---|
Routine code (not block structured) | Exits routine, returns to the calling routine (if any). | Exits routine, returns to the calling routine (if any). |
TRY or CATCH block | Exits TRY / CATCH block structure pair to next code in routine. If issued from a nested TRY or CATCH block, exits one level to the enclosing TRY or CATCH block. | Exits routine, returns to the calling routine (if any). |
DO or XECUTE | Exits routine, returns to the calling routine (if any). | Exits routine, returns to the calling routine (if any). |
IF | Exits routine, returns to the calling routine (if any). However, if nested in a FOR, WHILE, or DO WHILE loop, exits that block structure and continues with the next line after the code block. | Exits routine, returns to the calling routine (if any). |
FOR, WHILE, DO WHILE | Exits the block structure and continues with the next line after the code block. If issued from a nested block, exits one level to the enclosing block. | Exits routine, returns to the calling routine (if any). |
Controlling Flow
In order to establish the logic of any code, there must be flow control; conditional executing or bypassing blocks of code, or repeatedly executing a block of code. To that end, ObjectScript supports the following commands:
Conditional Execution
To conditionally execute a block of code, based on boolean (true/false) test, you can use the IF command. (You can perform conditional execution of individual ObjectScript commands by using a postconditional expression.)
IF takes an expression as an argument and evaluates that expression as true or false. If true, then the block of code that follows the expression is executed; if false, the block of code is not executed. Most commonly these are represented by 1 and 0, which are the recommended values. However, InterSystems IRIS performs conditional execution on any value, evaluating it as False if it evaluates to 0 (zero), and True if it evaluates to a nonzero value. For further details, see Operators and Expressions.
You can specify multiple IF boolean test expressions as a comma-separated list. These tests are evaluated in left-to-right order as a series of logical AND tests. Therefore, an IF evaluates as true when all of its test expressions evaluate as true. An IF evaluates as false when the one of its test expressions evaluates as false; the remaining test expressions are not evaluated.
The code usually appears in a code block containing multiple commands. Code blocks are simply one or more lines of code contained in curly braces; there can be line breaks before and within the code blocks. Consider the following:
IF, ELSEIF, and ELSE
The IF construct allows you to evaluate multiple conditions, and to specify what code is run based on the conditions. A construct, as opposed to a simple command, consists of a combination of one or more command keywords, their conditional expressions and code blocks. The IF construct consists of:
-
One IF clause with one or more conditional expressions.
-
Any number of ELSEIF clauses, each with one or more conditional expressions. The ELSEIF clause optional; there can be more than one ELSEIF clause.
-
At most one ELSE clause, with no conditional expression. The ELSE clause is optional.
The following is an example of the IF construct:
READ "Enter the number of equal-length sides in the polygon: ",x
IF x=1 {WRITE !,"It's so far away that it looks like a point"}
ELSEIF x=2 {WRITE !,"I think that's a line, not a polygon"}
ELSEIF x=3 {WRITE !,"It's an equalateral triangle"}
ELSEIF x=4 {WRITE !,"It's a square"}
ELSE {WRITE !,"It's a polygon with ",x," number of sides" }
WRITE !,"Finished the IF test"
For further details, refer to the reference for IF.
FOR
You use the FOR construct to repeat sections of code. You can create a FOR loop based on numeric or string values.
Typically, FOR executes a code block zero or more times based on the value of a numeric control variable that is incremented or decremented at the beginning of each loop through the code. When the control variable reaches its end value, control exits the FOR loop; if there is no end value, the loop executes until it encounters a QUIT command. When control exits the loop, the control variable maintains its value from the last loop executed.
The form of a numeric FOR loop is:
FOR ControlVariable = StartValue:IncrementAmount:EndValue {
// code block content
}
All values can be positive or negative; spaces are permitted but not required around the equals sign and the colons. The code block following the FOR will repeat for each value assigned to the variable.
For example, the following FOR loop will execute five times:
WRITE "The first five multiples of 3 are:",!
FOR multiple = 3:3:15 {
WRITE multiple,!
}
You can also use a variable to determine the end value. In the example below, a variable specifies how many iterations of the loop occur:
SET howmany = 4
WRITE "The first ",howmany," multiples of 3 are "
FOR multiple = 1:1:howmany {
WRITE (multiple*3),", "
IF multiple = (howmany - 1) {
WRITE "and "
}
IF multiple = howmany {
WRITE "and that's it!"
}
}
QUIT
Because this example uses multiple, the control variable, to determine the multiples of 3, it displays the expression multiple*3. It also uses the IF command to insert and before the last multiple.
The IF command in this example provides an excellent example of the implications of order of precedence in ObjectScript (order of precedence is always left to right with no hierarchy among operators). If the IF expression were simply multiple = howmany - 1, without any parentheses or parenthesized as a whole, then the first part of the expression, multiple = howmany, would be evaluated to its value of False (0); the expression as a whole would then be equal to 0 - 1, which is -1, which means that the expression will evaluate as true (and insert and for every case except the final iteration through the loop).
The argument of FOR can also be a variable set to a list of values; in this case, the code block will repeat for each item in the list assigned to the variable.
FOR item = "A", "B", "C", "D" {
WRITE !, "Now examining item: "_item
}
You can specify the numeric form of FOR without an ending value by placing a QUIT within the code block that triggers under particular circumstances and thereby terminates the FOR. This approach provides a counter of how many iterations have occurred and allows you to control the FOR using a condition that is not based on the counter’s value. For example, the following loop uses its counter to inform the user how many guesses were made:
FOR i = 1:1 {
READ !, "Capital of MA? ", a
IF a = "Boston" {
WRITE "...did it in ", i, " tries"
QUIT
}
}
If you have no need for a counter, you can use the argumentless FOR:
FOR {
READ !, "Know what? ", wh
QUIT:(wh = "No!")
WRITE " That's what!"
}
For further details, see FOR.
WHILE and DO WHILE
Two related flow control commands are WHILE and DO WHILE commands, each of which loops over a code block and terminates based on a condition. The two commands differ in when they evaluate the condition: WHILE evaluates the condition before the entire code block and DO WHILE evaluates the condition after the block. As with FOR, a QUIT within the code block terminates the loop.
The syntax for the two commands is:
DO {code} WHILE condition
WHILE condition {code}
The following example displays values in the Fibonacci sequence up to a user-specified value twice — first using DO WHILE and then using WHILE:
fibonacci() PUBLIC { // generate Fibonacci sequences
READ !, "Generate Fibonacci sequence up to where? ", upto
SET t1 = 1, t2 = 1, fib = 1
WRITE !
DO {
WRITE fib," " set fib = t1 + t2, t1 = t2, t2 = fib
}
WHILE ( fib '> upto )
SET t1 = 1, t2 = 1, fib = 1
WRITE !
WHILE ( fib '> upto ) {
WRITE fib," "
SET fib = t1 + t2, t1 = t2, t2 = fib
}
}
The distinction between WHILE, DO WHILE, and FOR is that WHILE necessarily tests the control expression’s value before executing the loop, DO WHILE necessarily tests the value after executing the loop, and FOR can test it anywhere within the loop. This means that if you have two parts to a code block, where execution of the second depends on evaluating the expression, the FOR construct is best suited; otherwise, the choice depends on whether expression evaluation should precede or follow the code block.
Controlling I/O
ObjectScript input/output commands provide the basic functionality for getting data in and out of InterSystems IRIS. These are:
Display (Write) Commands
ObjectScript supports four commands to display (write) literals and variable values to the current output device:
Argumentless Display Commands
-
Argumentless WRITE displays the name and value of each defined local variable, one variable per line. It lists both public and private variables. It does not list global variables, process-private globals, or special variables. It lists variables in collation sequence order. It lists subscripted variables in subscript tree order.
It displays all data values as quoted strings delimited by double quote characters, except for canonical numbers and object references. It displays a variable assigned an object reference (OREF) value as variable=<OBJECT REFERENCE>[oref]. It displays a %List format value or a bitstring value in their encoded form as a quoted string. Because these encoded forms may contain non-printing characters, a %List or bitstring may appear to be an empty string.
WRITE does not display certain non-printing characters; no placeholder or space is displayed to represent these non-printing characters. WRITE executes control characters (such as line feed or backspace).
-
Argumentless ZWRITE is functionally identical to argumentless WRITE.
-
Argumentless ZZDUMP is an invalid command that generates a <SYNTAX> error.
-
Argumentless ZZWRITE is a no-op that returns the empty string.
Display Commands with Arguments
The following tables list the features of the argumented forms of the four commands. All four commands can take a single argument or a comma-separated list of arguments. All four commands can take as an argument a local, global, or process-private variable, a literal, an expression, or a special variable:
The following tables also list the %Library.Utility.FormatString()Opens in a new tab method default return values. The FormatString() method is most similar to ZZWRITE, except that it does not list %val= as part of the return value, and it returns only the object reference (OREF) identifier. FormatString() allows you to set a variable to a return value in ZWRITE / ZZWRITE format.
WRITE | ZWRITE | ZZDUMP | ZZWRITE | FormatString() | |
---|---|---|---|---|---|
Each value on a separate line? | NO | YES | YES (16 characters per line) | YES | One input value only |
Variable names identified? | NO | YES | NO | Represented by %val= | NO |
Undefined variable results in <UNDEFINED> error? | YES | NO (skipped, variable name not returned) | YES | YES | YES |
All four commands evaluate expressions and return numbers in canonical form.
WRITE | ZWRITE | ZZDUMP | ZZWRITE | FormatString() | |
---|---|---|---|---|---|
Hexadecimal representation? | NO | NO | YES | NO | NO |
Strings quoted to distinguish from numerics? | NO | YES | NO | YES (a string literal is returned as %val="value") | YES |
Subscript nodes displayed? | NO | YES | NO | NO | NO |
Global variables in another namespace (extended global reference) displayed? | YES | YES (extended global reference syntax shown) | YES | YES | YES |
Non-printing characters displayed? | NO, not displayed; control characters executed | YES, displayed as $c(n) | YES, displayed as hexadecimal | YES, displayed as $c(n) | YES, displayed as $c(n) |
List value format | encoded string | $lb(val) format | encoded string | $lb(val) format | $lb(val) format |
%Status format | string containing encoded Lists | string containing $lb(val) format Lists, with appended /*... */ comment specifying error and message. | string containing encoded Lists | string containing $lb(val) format Lists, with appended /*... */ comment specifying error and message. | string containing $lb(val) format Lists, with (by default) appended /*... */ comment specifying error and message. |
Bitstring format | encoded string | $zwc format with appended /* $bit() */ comment listing 1 bits. For example: %val=$zwc(407,2,1,2,3,5)/*$bit(2..4,6)*/ | encoded string | $zwc format with appended /* $bit() */ comment listing 1 bits. For example: %val=$zwc(407,2,1,2,3,5)/*$bit(2..4,6)*/ | $zwc format with (by default) appended /* $bit() */ comment listing 1 bits. For example: %val=$zwc(407,2,1,2,3,5)/*$bit(2..4,6)*/ |
Object Reference (OREF) format | OREF only | OREF in <OBJECT REFERENCE>[oref] format. General information, attribute values, etc. details listed. All subnodes listed | OREF only | OREF in <OBJECT REFERENCE>[oref] format. General information, attribute values, etc. details listed. | OREF only, as quoted string |
JSON dynamic arrays and JSON dynamic objects are returned as OREF values by all of these commands. To return the JSON contents, you must use %ToJSON(), as shown in the following example:
SET jobj={"name":"Fred","city":"Bedrock"}
WRITE "JSON object reference:",!
ZWRITE jobj
WRITE !!,"JSON object value:",!
ZWRITE jobj.%ToJSON()
For further details, see WRITE, ZWRITE, ZZDUMP, and ZZWRITE.
READ
The READ command allows you to accept and store input entered by the end user via the current input device. The READ command can have any of the following arguments:
READ format, string, variable
Where format controls where the user input area will appear on the screen, string will appear on the screen before the input prompt, and variable will store the input data.
The following format codes are used to control the user input area:
Format Code | Effect |
---|---|
! | Starts a new line. |
# | Starts a new page. On a terminal it clears the current screen and starts at the top of a new screen. |
?n | Positions at the nth column position where n is a positive integer. |
For further details, see READ.
OPEN, USE, and CLOSE
For more sophisticated device handling, InterSystems IRIS provides a wealth of options. In short, you can take ownership of an open device with the OPEN command; specify the current device with the USE command; and close an open device with the CLOSE command. This process as a whole is described in the I/O Device Guide.