Skip to main content

System Functions

System Functions

This section highlights some of the most commonly used system functions in ObjectScript.

The names of these functions are not case-sensitive.

The Caché class library also provides a large set of utility methods that you can use in the same way that you use functions. To find a method for a particular purpose, use the InterSystems Programming Tools Index.

See also “Date and Time Values,” later in this chapter.

Value Choice

You can use the following functions to choose a value, given some input:

  • $CASE compares a given test expression to a set of comparison values and then returns the return value associated with the matching comparison value. For example:

    SAMPLES>set myvar=1
     
    SAMPLES>write $CASE(myvar,0:"zero",1:"one",:"other")
    one
    
  • $SELECT examines a set of expressions and returns the return value associated with the first true expression. For example:

    SAMPLES>set myvar=1
     
    SAMPLES>write $SELECT(myvar=0:"branch A",1=1:"branch B")
    branch B
    

Existence Functions

You can use the following functions to test for the existence of a variable or of a node of a variable.

  • To test if a specific variable exists, use the $DATA function.

    For a variable that contains multiple nodes, this function can indicate whether a given node exists, and whether a given node has a value and child nodes.

  • To get the value of a variable (if it exists) or get a default value (if not), use the $GET function.

List Functions

ObjectScript provides a native list format. You can use the following functions to create and work with these lists:

  • $LISTBUILD returns a special kind of string called a list. Sometimes this is called $LIST format, to distinguish this kind of list from other kinds (such as comma-separated lists).

    The only supported way to work with a $LIST list is to use the ObjectScript list functions. The internal structure of this kind of list is not documented and is subject to change without notice.

  • $LIST returns a list element or can be used to replace a list element.

  • $LISTLENGTH returns the number of elements in a list.

  • $LISTFIND returns the position of a given element, in a given list.

There are additional list functions as well.

If you use a list function with a value that is not a list, you receive the <LIST> error.

Note:

The system class %Library.ListOpens in a new tab is equivalent to a list returned by $LISTBUILD. That is, when a class has a property of type %Library.ListOpens in a new tab, you use the functions named here to work with that property. You can refer to this class by its short name, %ListOpens in a new tab.

Caché provides other list classes that are not equivalent to a list returned by $LISTBUILD. These are useful if you prefer to work with classes. For an introduction, see “Collection Classes,” later in this book.

String Functions

ObjectScript also has an extensive set of functions for using strings efficiently:

  • $EXTRACT returns or replaces a substring, using a character count.

  • $FIND finds a substring by value and returns an integer specifying its end position in the string.

  • $JUSTIFY returns a right-justified string, padded on the left with spaces.

  • $ZCONVERT converts a string from one form to another. It supports both case translations (to uppercase, to lowercase, or to title case) and encoding translation (between various character encoding styles).

  • $TRANSLATE modifies the given string by performing a character-by-character replacement.

  • $REPLACE performs string-by-string replacement within a string and returns a new string.

  • $PIECE returns a substring from a character-delimited string (often called a pieced string). Many older applications use character-delimited strings as a convenient format to contain related values, each of which is a substring within the larger string. The large string acts as a record, and the substrings are its fields.

    In many cases, the delimiter is a caret. Thus in existing code, you might see pieced strings like this: "value 1^value 2^value 3"

    The following demonstrates how to extract a substring:

     SET mystring="value 1^value 2^value 3"
     WRITE $PIECE(mystring,"^",1)
  • $LENGTH returns the number of characters in a specified string or the number of delimited substrings in a specified string, depending on the parameters used.

    For example:

     SET mystring="value 1^value 2^value 3"
     WRITE !, "Number of characters in this string: " 
     WRITE $LENGTH(mystring)
     WRITE !, "Number of pieces in this string: "
     WRITE $LENGTH(mystring,"^")
    

Working with Multidimensional Arrays

You can use the following functions to work with a multidimensional array as a whole:

  • $ORDER allows you to sequentially visit each node within a multidimensional array.

  • $QUERY enables you to visit every node and subnode within an array, moving up and down over subnodes.

To work with an individual node in an array, you can use any of the functions described previously. In particular:

  • $DATA can indicate whether a given node exists and whether a given node has child nodes.

  • $GET gets the value of a given node or gets a default value otherwise.

Character Values

Sometimes when you create a string, you need to include characters that cannot be typed. For these, you use $CHAR.

Given an integer, $CHAR returns the corresponding ASCII or Unicode character. Common uses:

  • $CHAR(9) is a tab.

  • $CHAR(10) is a line feed.

  • $CHAR(13) is a carriage return.

  • $CHAR(13,10) is a carriage return and line feed pair.

The function $ASCII returns the ASCII value of the given character.

$ZU Functions

In existing code, you might see items like $ZU(n), $ZUTIL(n), $ZU(n,n), and so on, where n is an integer. These are the $ZU functions, which are now deprecated and are no longer documented. They are still available, but users are encouraged to replace them with methods and properties in the Caché class library that perform the equivalent actions. There is a table of replacements in “Replacements for ObjectScript $ZUTIL Functions” in the Caché ObjectScript Reference.

FeedbackOpens in a new tab