Caché Programming Orientation Guide
What’s That?
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Search:    

As you read existing Caché ObjectScript code, you may encounter unfamiliar syntax forms. This appendix shows syntax forms in different groups, and it explains what they are and where to find more information.

This appendix does not list single characters that are obviously operators or that are obviously arguments to functions or commands.
Also see the following appendices in the Caché ObjectScript Reference.
Non-Alphanumeric Characters in the Middle of “Words”
This section lists forms that look like words with non-alphanumeric characters in them. Many of these are obvious, because the operators are familiar. For example:
x>5
The less obvious forms are these:
abc^def
def is a routine, and abc is a label within that routine. abc^def is a subroutine.
Variation for abc:
Some variations for def:
xxx is an optional, comma-separated list of arguments.
A label can start with a percent sign but is purely alphanumeric after that.
A routine name can start with a percent sign and can include one or more periods. The caret is not part of its name. (In casual usage, however, it is very common to refer to a routine as if its name included an initial caret. Thus you may see comments about the ^def routine. Usually you can tell from context whether the reference is to a global or to a routine.)
i%abcdef
This is an instance variable, which you can use to get or to set the value of the abcdef property of an object. See Object-specific ObjectScript Features in Using Caché Objects.
This syntax can be used only in an instance method. abcdef is a property in the same class or in a superclass.
For information on finding the property definitions, see Finding the Definition of a Class Member,” earlier in this book.
abc->def
Variations:
This syntax is possible only within Caché SQL statements. It is an example of Caché arrow syntax and it specifies an implicit left outer join. abc is an object-valued field in the class that you are querying, and def is a field in the child class.
abc->def is analogous to Caché dot syntax (abc.def), which you cannot use in Caché SQL.
For information on Caché arrow syntax, see Implicit Joins (Arrow Syntax) in Using Caché SQL.
abc?def
Variation:
A question mark is the pattern match operator. In the first form, this expression tests whether the value in the variable abc matches the pattern specified in def. In the second form, "abc" is a string literal that is being tested. See Operators and Expressions in Using Caché ObjectScript.
Note that both the string literal "abc" and the argument def can include characters other than letters.
"abc"["def"
Variations:
A left bracket ([) is the binary contains operator. In the first form, this expression tests whether the string literal "abc" contains the string literal "def". In later forms, abc and def are variables that are being tested. See Operators and Expressions in Using Caché ObjectScript.
Note that both the string literals "abc" and "def" can include characters other than letters.
"abc"]"def"
Variations:
A right bracket (]) is the binary follows operator. In the first form, this expression tests whether the string literal "abc" comes after the string literal "def", in ASCII collating sequence. In later forms, abc and def are variables that are being tested. See Operators and Expressions in Using Caché ObjectScript.
Note that both the string literals "abc" and "def" can include characters other than letters.
"abc"]]"def"
Variations:
Two right brackets together (]]) are the binary sorts after operator. In the first form, this expression tests whether the string literal "abc" sorts after the string literal "def", in numeric subscript collation sequence. In later forms, abc and def are variables that are being tested. See Operators and Expressions in Using Caché ObjectScript.
Note that both the string literals "abc" and "def" can include characters other than letters.
. (One Period)
period within an argument list
Variations:
When you call a method or routine, you can pass an argument by reference or as output. To do so, place a period before the argument.
period at the start of a line
An older form of the Do command uses a period prefix to group lines of code together into a code block. See DO (legacy version) in the Caché ObjectScript Reference.
Code that uses this older form is sometimes referred to as dotty.
.. (Two Periods)
In every case, two periods together are the start of a reference from within a class member to another class member.
..abcdef
This syntax can be used only in an instance method (not in routines or class methods). abcdef is a property in the same class.
..abcdef(xxx)
This syntax can be used only in a method (not in routines). abcdef() is another method in the same class, and xxx is an optional comma-separated list of arguments.
..#abcdef
This syntax can be used only in a method (not in routines). abcdef is a parameter in this class.
In classes provided by InterSystems, all parameters are defined in all capitals, by convention, but your code is not required to do this.
Remember that the pound sign is not part of the parameter name.
For information on finding the class member definition, see Finding the Definition of a Class Member,” earlier in this book.
# (Pound Sign)
This section lists forms that start with a pound sign.
#abcdef
In most cases, #abcdef is a preprocessor directive. Caché provides a set of preprocessor directives. Their names start with either one or two pound signs. Here are some common examples:
For reference information and other directives, see ObjectScript Macros and the Macro Preprocessor in Using Caché ObjectScript.
Less commonly, the form #abcdef is an argument used with specific commands (such as READ and WRITE), special variables, or routines. For details, consult the reference information for the command, variable, or routine that uses this argument.
##abcdef
##abcdef is a preprocessor directive. See the comments for #abcdef.
##class(abc.def).ghi(xxx)
Variation:
abc.def is a package and class name, ghi is a class method in that class, and xxx is an optional comma-separated list of arguments.
If the package is omitted, the class def is in the same package as the class that contains this reference.
##super()
Variations:
This syntax can be used only in a method. It invokes the overridden method of the superclass, from within the current method of the same name in the current class. abcdef is a comma-separated list of arguments for the method. See Object-specific ObjectScript Features in Using Caché Objects.
Dollar Sign ($)
This section lists forms that start with a dollar sign.
$abcdef
Usually, $abcdef is a special variable. See Caché ObjectScript Special Variables in the Caché ObjectScript Reference.
$abcdef could also be a custom special variable. See Extending Caché ObjectScript with %ZLang in the chapter “Customizing Caché” in Caché Specialized System Tools and Utilities.
$abcdef(xxx)
Usually, $abcdef() is a system function, and xxx is an optional comma-separated list of arguments. For reference information, see the Caché ObjectScript Reference.
$abcdef() could also be a custom function. See Extending Caché ObjectScript with %ZLang in the chapter “Customizing Caché” in Caché Specialized System Tools and Utilities.
$abc.def.ghi(xxx)
In this form, $abc is $SYSTEM (in any case), def is the name of class in the %SYSTEM package, ghi is the name of a method in that class, and xxx is an optional comma-separated list of arguments for that method.
The $SYSTEM special variable is an alias for the %SYSTEM package, to provide language-independent access to methods in classes of that package. For example: $SYSTEM.SQL.DateDiff
For information on the methods in this class, see the InterSystems Class Reference.
$$abc
Variation:
abc is a subroutine defined within the routine or the method that contains this reference. This syntax invokes the subroutine abc and gets its return value. See the chapter User-defined Code in Using Caché ObjectScript.
$$abc^def
Variations:
This syntax invokes the subroutine abc and gets its return value. The part after the caret is the name of the routine that contains this subroutine. See the chapter User-defined Code in Using Caché ObjectScript.
$$$abcdef
abcdef is a macro; note that the dollar signs are not part of its name (and are thus not seen in the macro definition).
Some of the macros supplied by Cache are documented in System-supplied Macro Reference in Using Caché ObjectScript. Otherwise, see Finding a Macro in Studio,” earlier in this book.
In casual usage, it is common to refer to a macro as if its name included the dollar signs. Thus you may see comments about the $$$abcdef macro.
Percent Sign (%)
By convention, most packages, classes, and methods in Caché system classes start with a percent character. From the context, it should be clear whether the element you are examining is one of these. Otherwise, the possibilities are as follows:
%abcdef
%abcdef is one of the following:
%%abcdef
%abcdef is %%CLASSNAME, %%CLASSNAMEQ, %%ID, or %%TABLENAME. These are pseudo-field keywords. For details, see the Caché SQL Reference.
Caret (^)
This section lists forms that start with a caret, from more common to less common.
^abcdef
Variation:
There are three possibilities:
In casual usage, it is very common to refer to a routine as if its name included an initial caret. Thus you may see comments about the ^abcdef routine. Usually you can tell from context whether the reference is to a global or to a routine. Lock names appear only after the LOCK command; they cannot be used in any other context.
^$abcdef
Variation:
Each of these is a structured system variable, which provides information about globals, jobs, locks, or routines.
$abcdef is $GLOBAL, $JOB, $LOCK, or $ROUTINE.
ghijkl is a namespace name.
Caché stores information in the following system variables:
See the Caché ObjectScript Reference.
^||abcdef
Variations:
Each of these is a process-private global, a mechanism for temporary storage of large data values. Caché uses some internally but does not present any for public use. You can define and use your own process-private globals. See Variables in Using Caché ObjectScript.
^|XXX|abcdef
Some variations:
Each of these is an extended reference — a reference to a global or a routine in another namespace. The possibilities are as follows:
Extended references were sometimes necessary before Caché provided support for global and routine mappings.
The XXX component indicates the namespace. This is either a quoted string or an unquoted string. See “Extended References” in the chapter Syntax Rules in Using Caché ObjectScript.
^abc^def
This is an implied namespace, which can be used as an argument to the ZNSPACE command. See the ZNSPACE entry in the Caché ObjectScript Reference.
^^abcdef
This is an implied namespace, which can be used as an argument to the ZNSPACE command. See the ZNSPACE entry in the Caché ObjectScript Reference.
Other Forms
+abcdef
Some variations:
Each of these expressions returns a number. In the first version, abcdef is the name of a local variable. If the contents of this variable do not start with a numeric character, the expression returns 0. If the contents do start with a numeric character, the expression returns that numeric character and all numeric characters after it, until the first nonnumeric character. For a demonstration, run the following example:
 write +"123abc456"
 
See String Relational Operators in the chapter “Operators and Expressions” in Using Caché ObjectScript.
{"abc":(def),"abc":(def),"abc":(def)}
This syntax is a JSON object literal and it returns an instance of %DynamicObject. "abc" is the name of a property, and def is the value of the property. For details, see Using JSON in Caché.
{abcdef}
This syntax is possible where Caché SQL uses Caché ObjectScript. abcdef is the name of a field. See Referring to Fields from Caché ObjectScript in Using Caché Objects.
{%%CLASSNAME}
This syntax can be used within trigger code and is replaced at class compilation time.
Others:
These items are not case-sensitive. See CREATE TRIGGER in the Caché SQL Reference.
&sql(xxx)
This is embedded SQL and can be used anywhere Caché ObjectScript is used. xxx is one SQL statement. See Using Embedded SQL in Using Caché SQL.
&js<xxx>
This syntax is possible in Zen pages and it indicates embedded JavaScript commands. xxx is one or more JavaScript commands. See Zen Pages in Developing Zen Applications.
&html<xxx>
This syntax is possible in Zen pages and it indicates embedded HTML commands. xxx is one or more HTML commands. See Zen Pages in Developing Zen Applications.
[abcdef,abcdef,abcdef]
This syntax is a JSON array literal and it returns an instance of %DynamicArray. abcdef is an item in the array. For details, see Using JSON in Caché.
*abcdef
Special syntax used by the following functions and commands:
See these items in the Caché ObjectScript Reference.
?abcdef
The question mark is the pattern match operator and abcdef is the comparison pattern. See Operators and Expressions in Using Caché ObjectScript.
@abcdef
The at sign is the indirection operator. See Operators and Expressions in Using Caché ObjectScript.