Skip to main content

Storing Data in Globals

Storing Data in Globals

Storing data in global nodes is simple: you treat a global as you would any other variable. The difference is that operations on globals are automatically written to the database.

Creating Globals

There is no setup work required to create a new global; simply setting data into a global implicitly creates a new global structure. You can create a global (or a global subscript) and place data in it with a single operation, or you can create a global (or subscript) and leave it empty by setting it to the null string. In ObjectScript, these operations are done using the SET command.

The following examples define a global named Color (if one does not already exist) and associate the value “Red” with it. If a global already exists with the name Color, then these examples modify it to contain the new information.

In ObjectScript:

 SET ^Color = "Red"

When using direct global access within applications, develop and adhere to a naming convention to keep different parts of an application from “walking over” one another; this is similar to developing naming convention for classes, method, and other variables. Also, avoid certain global names that InterSystems IRIS® uses; for a list of these, see the section “Global Variable Names to Avoid” in the “Rules and Guidelines for Identifiers” appendix of the Orientation Guide for Server-Side Programming.

Storing Data in Global Nodes

To store a value within a global subscript node, simply set the value of the global node as you would any other variable array. If the specified node did not previously exist, it is created. If it did exist, its contents are replaced with the new value.

You specify a node within a global by means of an expression (referred to as a global reference). A global reference consists of the caret character (^), the global name, and (if needed) one or more subscript values. Subscripts (if present) are enclosed within parentheses “( )” and are separated by commas. Each subscript value is itself an expression: a literal value, a variable, a logical expression, or even a global reference.

Setting the value of a global node is an atomic operation: It is guaranteed to succeed and you do not need to use any locks to ensure concurrency.

The following are all valid global references:

In ObjectScript:

   SET ^Data = 2
   SET ^Data("Color")="Red"
   SET ^Data(1,1)=100        /* The 2nd-level subscript (1,1) is set
                                to the value 100. No value is stored at
                                the 1st-level subscript (^Data(1)). */   
   SET ^Data(^Data)=10       /* The value of global variable ^Data 
                                is the name of the subscript. */
   SET ^Data(a,b)=50         /* The values of local variables a and b
                                are the names of the subscripts. */
   SET ^Data(a+10)=50       

Also, you can construct global references at runtime using indirection.

Storing Structured Data in Global Nodes

Each global node can contain a single string of up to 32K characters.

Data is typically stored within nodes in one of the following ways:

  • As a single string of up to 32K characters (specifically, 32K minus 1).

  • As a character-delimited string containing multiple pieces of data.

    To store a set of fields within a node using a character delimiter, simply concatenate the values together using the concatenate operator (_). The following ObjectScript examples use the # character as a delimiter:

       SET ^Data(id)=field(1)_"#"_field(2)_"#"_field(3)

    When the data is retrieved, you can pull the fields apart using the $PIECE function:

       SET data = $GET(^Data(id))
       FOR i=1:1:3 {
         SET field(i) = $PIECE(data,"#",i)
  • As a $LIST-encoded string containing multiple pieces of data.

    The $LIST functions use a special length-encoding scheme that does not require you to reserve a delimiter character. (This is the default structure used by InterSystems IRIS objects and SQL.)

    To store a set of fields within a node use the $LISTBUILD function to construct a list:

       SET ^Data(id)=$LISTBUILD(field(1),field(2),field(3))

    When the data is retrieved, you can pull the fields apart using the $LIST or $LISTGET functions:

       SET data = $GET(^Data(id))
       FOR i = 1:1:3 {
           SET field(i)=$LIST(data,i)
  • As one part of a larger set of data (such as a stream or “BLOB”).

    As individual nodes are limited to just under 32K of data, larger structures, such as streams, are implemented by storing data in a set of successive nodes:

       SET ^Data("Stream1",1) = "First part of stream...."
       SET ^Data("Stream1",2) = "Second part of stream...."
       SET ^Data("Stream1",3) = "Third part of stream...."

    Code that fetches the stream (such as that provided by the %GlobalCharacterStream class) loops over the successive nodes in such a structure providing the data as a continuous string.

  • As a bitstring.

    If you are implementing a bitmap index (an index where a bit in a bitstring corresponds to a row in a table), you would set the node values of an index global to bit strings. Note that InterSystems IRIS uses a compression algorithm for encoding bit strings; therefore, bit strings can only be handled using the InterSystems IRIS $BIT functions. Refer to the Bit String Functions Overview for more details on bit strings.

  • As an empty node.

    If the data you are interested in is provided by the nodes themselves, then it is typical to set the actual subscript to a null string (""). For example, an index that associates a name with an ID value typically looks like this:

      SET ^Data("APPLE",1) = ""
      SET ^Data("ORANGE",2) = ""
      SET ^Data("BANANA",3) = ""