Extending Languages with ^%ZLANG Routines
You can use the ^%ZLANG feature to add custom commands, functions, and special variables to the ObjectScript and other languages. Your extensions are invoked in the same way as standard features, and follow the same rules for syntax, operator precedence, and so on. ^%ZLANG features generally do not execute as rapidly as standard InterSystems IRIS features. Consider this point when coding performance-critical routines.
To add such extensions:
-
Define routines with the following names, as needed:
Routine Name Purpose ^%ZLANGC00 Defines custom ObjectScript commands. ^%ZLANGF00 Defines custom ObjectScript functions. ^%ZLANGV00 Defines custom ObjectScript special variables. -
In these routines, define public subroutines as follows:
-
For the subroutine label, use the name of the command, function, or special variable that you are defining.
The name must start with the letter Z and can include only letters. Unicode characters are permitted, if the locale defines them as alphabetic. All letters must be in uppercase, though execution is not case-sensitive. The maximum length of a name is 31 letters.
The name cannot be the same as an existing command, function, or special variable (if it is, InterSystems IRIS ignores it). InterSystems also strongly recommends that you do not use an SQL reserved word.
If you are defining a function, even a function with no arguments, the label must include parentheses.
A label for a special variable can include parentheses.
-
Optionally include an additional label to define an abbreviation. Be careful that it is not already used by InterSystems IRIS.
-
Define the subroutine appropriately. See the “Notes” section for details.
-
-
As good programming practice, the first command in the parent routine should use QUIT so that nothing occurs if a user invokes the routine directly.
It is also helpful for the routine to include a comment at the top that indicates the name of the routine itself.
It is customary (but inaccurate) to refer to a routine as if the caret is part of its name. This documentation follows this custom.
For other subroutines, including ones invoked by the public subroutines, make sure that the labels for those are in lowercase or mixed case (or do not start with Z). Or implement them as private subroutines.
That is, because a ^%ZLANG routine extends the language, it is important to make sure that only the desired subroutines are available outside of it.
Notes
Commands are handled like a DO of a routine or procedure. Arguments are passed as call parameters.
Your code should preserve the values of system state such as $TEST and $ZREFERENCE unless you intend for them to be a result of your code. (But note that for functions and special variables, the system automatically preserves $TEST.)
You can SET the value of a special variable. There is only one entry point for the variable. To determine whether to set the value or retrieve the value, your code should check whether an argument is given. For example:
ZVAR(NewValue) public {
if $DATA(NewValue) Set ^||MyVar=NewValue Quit
Quit $GET(^||MyVar)
}
Then, a user can either set this variable or retrieve it, as demonstrated here:
USER>w $ZVAR
USER>s $ZVAR="xyz"
USER>w $ZVAR
xyz
To return an error code from a command or function, use $SYSTEM.Process.ThrowError().
Examples
For example, to define a custom special variable for use in ObjectScript, you define the routine ^%ZLANGV00, which could look like the following:
; implementation of ^%ZLANGV00
; custom special variables for ObjectScript
QUIT
ZVERNUM ; tag becomes name of a special variable
ZVE
QUIT $PIECE($ZVERSION,"(Build")
Then, for demonstration, you can use the new variable in the Terminal as follows:
USER>w $zvernum
InterSystems IRIS for Windows (x86-64) 2018.1
USER>w $zve
InterSystems IRIS for Windows (x86-64) 2018.1
For another example, suppose that you define the ^%ZLANGF00 routine as follows:
; implementation of ^%ZLANGF00
; custom functions for ObjectScript
QUIT
ZCUBE(input) public {
Quit input*input*input
}
Then, for demonstration, you can use the new function in the Terminal as follows:
USER>w $zcube(2)
8
The following example shows ^%ZLANGC00, which creates a command that executes the system status utility ^%SS:
; %ZLANGC00
; custom commands for ObjectScript
QUIT
ZSS ; tag name of a command to check system status
DO ^%SS
QUIT