Data Types and Values

Caché ObjectScript is a typeless language—you do not have to declare the types of variables. Any variable can have a string, numeric, or object value.

Strings

A string is a set of characters: letters, digits, punctuation, and so on. You can define a string literal by placing text within a matched set of quotation marks ("):

 Set string = "This is a string."
 Write string

Escaping Quotation Marks

You can include a " (double quote) character within a string literal by preceding it with another double quote character:

—Escaping Quotation Marks—

 Set string = "This string has ""quotes"" in it."
 Write string

There are no other escape sequences within ObjectScript string literals.

Concatenating Strings

You can concatenate two strings into a single string using the _ concatenation operator:

—Concatenation—

 Set string = "Hello" _ " Goodbye"
 Write string

Numbers

Numeric literals do not require any enclosing punctuation. You can specify a number using any valid numeric characters. Caché converts a number to canonical form.

Numeric literal values support the following:

They can contain the decimal numbers 0-9. They can contain leading or trailing zeros. They can contain any number of leading plus and minus signs.
They can contain at most one decimal separator character. The choice of character is locale-dependent: American format uses a period (.) as the decimal separator, which is the default. European format uses a comma (,) as the decimal separator.
They can contain at most one letter “E” (or “e”) to specify an exponent. This exponentiation character (“E” or “e”) must be immediately followed by either a whole number, or a single plus or minus sign followed by a whole number. It cannot be followed by a blank space, a decimal point, multiple plus and minus signs, or a fractional number. An exponent can contain leading or trailing zeros.

Numeric literal values do not support the following:

They cannot contain numeric group separators. These are locale-dependent: American format uses commas, European format uses periods. You can use the $FNUMBER function to remove numeric group separators.
They cannot contain currency symbols, hexadecimal letters, or other nonnumeric characters. They cannot contain blank spaces, except before or after operators (such as plus and minus signs).
They cannot contain trailing plus or minus signs. However, the $FNUMBER function can display a number as a string with a trailing sign, and the $NUMBER function can take a string in this format and convert it to a number with a leading sign.
They cannot specify enclosing parentheses to represent a number as a negative number (a debit). However, the $FNUMBER function can display a negative number as a string with a enclosing parentheses, and the $NUMBER function can take a string in this format and convert it to a number with a leading negative sign.

A number or numeric expression can containing pairs of enclosing parentheses. These parentheses are not part of the number, but govern the precedence of operations. By default, Caché performs all operations in strict left-to-right order.

When Caché converts a number to canonical form, it does the following:

Exponents are resolved.
Leading signs are resolved. First, multiple signs are resolved to a single sign (for example, two minus signs resolve to a plus sign). Then, if the leading sign is a plus sign, it is removed.
All leading and trailing zeros are removed.
A trailing decimal separator is removed.

A number can be concatenated to another number using the concatenation operator (_). Caché first converts each number to its canonical form, then performs a string concatenation on the results. Thus, the following all result in 1234: 12_34, 12_+34, 12_--34, 12.0_34, 12_0034.0, 12E0_34. The concatenation 12._34 results in 1234, but the concatenation 12_.34 results in 12.34. The concatenation 12_-34 results in the string “12-34”.

By default, Caché represents floating-point numbers using its own floating-point standard. This is the preferred format for most uses, and provides the highest level of precision. However, you can use the $DOUBLE function to convert a floating-point number to IEEE floating-point standard.

Integers of greater than 19 digits may have their low-order digits replaced by zeros.
Decimal numbers with more than 19 fractional digits may have their fractional part rounded.
Exponents larger than the maximum permitted generate a <MAXNUMBER> error. The largest permitted exponent depends on the size of the number that is receiving the exponent.

Objects

An object value refers to an instance of an in-memory object. You can assign an object value to any local variable:

 Set person = Sample.Person
 Write person

To refer to the methods and properties of an object, use dot syntax:

 Set person.Name = "El Vez"

To determine if a variable contains an object, use the IsObject function:

 Set str = "A string" 
 Set person = ##class(Sample.Person).%New()
 If $IsObject(person) {
     Write "Person is an object.",!
 } Else {
     Write "Person is not an object."
 }
 
 If $IsObject(str) {
      Write "String is an object."
 } Else {
     Write "String is not an object."
 }

You cannot assign an object value to a global. Doing so results in a runtime error.

Assigning an object value to a variable (or object property) has the side effect of incrementing the object's internal reference count. When the number of references to an object reaches 0, Caché automatically destroys the object (invoke its %OnClose method and remove it from memory).

Persistent Multi-dimensional Arrays (Globals)

A global is a sparse, multidimensional database array. A global is not different from any other type of array, with the exception that the global variable name starts with a caret (^). Data can be stored in a global with any number of subscripts; subscripts in Caché are typeless.

The following is an example of using a global. Once you set the global ^x, you can examine its value:

 Set ^x = 10
 Write "The value of ^x is: ", ^x

For more information on globals, see the “Multidimensional Arrays” chapter in this document and the Using Caché Multi-Dimensional Storage document.

Undefined Values

ObjectScript variables do not need to be explicitly declared or defined. As soon as you assign a value to a variable, the variable is defined. Until this first assignment, all references to this variable are undefined. You can use the $Data function to determine if a variable is defined or undefined.

$Data takes one or two arguments. With one argument, it simply tests if a variable has a value:

 Write "Does ""MyVar"" exist?",! 
 if $Data(MyVar) {     
         Write "It sure does!"  
 } Else {      
         Write "It sure doesn't!"
 }   
     
 Set MyVar = 10  
 Write !,!,"How about now?",! 
 if $Data(MyVar) {
        Write "It sure does!" 
 } Else {
        Write "It sure doesn't!"
 }

$Data returns a boolean that is True (1) if the variable has a value (that is, contains data) and that is False (0) if the variable has no value (that is, contains no data). With two arguments, it performs the test and sets the second argument's variable equal to the tested variable's value:

 If $Data(Var1,Var2) {
    Write "Var1 has a value of ",Var2,".",!  
 } Else {
     Write "Var1 is undefined.",!
 }
 
 Set Var1 = 3
 If $Data(Var1,Var2) {
    Write "Var1 has a value of ",Var2,".",!  
 } Else {
     Write "Var1 is undefined.",!
 }

Boolean Values

In certain cases, such as when used with logical commands or operators, a value may be interpreted as a boolean (true or false) value. In such cases, a value is interpreted as true if evaluates to a nonzero numeric value or false if it evaluates to a zero numeric value.

For example, the following values are interpreted as true:

1
10
"1 banana"
1 + 1
-1

The following values are interpreted as false:

0
""
"one banana"
1 - 1

Dates

ObjectScript has no built-in date type; instead it includes a number of functions for operating on and formatting date values represented as strings. These date formats include:

Date Formats

Format	Description
$Horolog	This is the format returned by the $Horolog ($H) special variable. It is a string containing two comma-separated integers: the first is the number of days since December 31, 1840; the second is the number of seconds since midnight of the current day. There are a number of functions for formatting and validating dates in this format.
ODBC Date	This is the format used by ODBC and many other external representations. It is a string of the form: “YYYY-MM-DD HH:MM:SS”. ODBC date values will collate; that isl if you sort data by ODBC date format, it will automatically be sorted in chronological order.
System Time	This is the format returned by the $ZHorolog ($ZH) special variable. It is a floating point number containing the number of seconds (and parts thereof) that the system has been running. Typically this format is used for timing and testing operations.

The following example shows how you can use the different date formats:

—Date Formats—

 Set now = $Horolog
 Write "Current time and date ($H): ",now,!
 Set odbc = $ZDateTime(now,3)
 Write "Current time and date (ODBC): ",odbc,!
 Set time = $ZH
 Write "Current system time ($ZH): ",time,!