Chapter 3 Using Multidimensional Storage (Global Variables)

This chapter describes the various operations you can perform using multidimensional storage (global variables).

Store data as global variables

Storing data in global nodes is simple: Treat global variables just like any other variable. The difference is that operations on global variables are automatically written to the database.

Creating global variables

Creating new global variables requires no setup work; New global structures are implicitly created by simply setting the data to global variables. You can create a global variable (or global variable subscript) and put data into it by a single operation, or you can create a global variable (or global variable subscript) and leave it empty by setting it to an empty string. In ObjectScript, these operations are done using the SET command.

The following example defines a global variable named Color(if it doesn’t already exist) and associates the value “Red” with it. If a global variable named Color already exists, these examples modify it to contain new information.

In ObjectScript:

 SET ^Color = "Red"
Copy the code

Note: When using direct global access variables in an application, you should specify and follow naming conventions to prevent different parts of the application from “traversing” each other; This is similar to developing naming conventions for classes, methods, and other variables.

Stores data in the global variable node

To store values in the global subscript node, you simply set the value of the global node as you would any other array of variables. If the specified node does not previously exist, it is created. If it does exist, its content is replaced with the new value.

Nodes within a global can be specified through expressions called global references. A global reference consists of a cross character (^), a global name, and, if required, one or more subscript values. Subscripts (if any) are enclosed in parentheses “()” and separated by commas. Each subscript value is itself an expression: literal value, variable, logical expression, or even a global reference.

Setting the value of a global node is an atomic operation: it is guaranteed to succeed, and no locks are required to ensure concurrency.

The following are valid global references:

In ObjectScript:

   SET ^Data = 2
   SET ^Data("Color") ="Red"
   SET ^Data(1.1) =100        /* the second-level subscript (1,1) is set to the value 100. The first level subscript (^DATA(1)) does not store any values. * /   
   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       
Copy the code

In addition, global references can be constructed in an indirect manner at run time.

Store structured data in the global variable node

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

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

• As the most32KA single string of four characters (specifically,32K - 1).
• As a character delimited string containing more than one piece of data.

To store a set of fields in a node using a character delimiter, you simply join the values together using the join operator (_). The following ObjectScript example uses the # character as a separator:

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

When retrieving data, you can split the fields using the $PIECE function:

    SET data = $GET(^Data(id))
    FOR i=1:1:3 {
        SET field(i) = $PIECE(data,"#",i)
    }
    QUIT
Copy the code

• As containing multiple pieces of data$LISTEncoding string.

The $LIST function uses a special length encoding scheme that does not require delimiters. (This is the default structure used by InterSystems IRIS objects and SQL.)

To store a set of fields in a node, construct the list using the $LISTBUILD function:

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

When retrieving data, you can split the fields using the $LIST or $LISTGET functions:

    SET data = $GET(^Data(id))
    FOR i = 1:1:3 {
        SET field(i)=$LIST(data,i)
    }
    QUIT
Copy the code

• As larger data sets (such as streams or"BLOB").

Because the amount of data on a single node is limited to slightly less32K, so larger structures (such as streams) can be achieved by storing data in a set of contiguous 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...."
Copy the code

The code that gets the stream, such as the stream provided by the %GlobalCharacterStream class, loops through successive nodes in a structure that provides the data as successive strings.

• As a bit string.

If you are implementing a bitmap index (where bits in a bitstring correspond to indexes of rows in a table), you should set the node value of the global index to a bitstring. Note that IRIS uses a compression algorithm to encode bit strings; Therefore, BIT strings can only be handled using the IRIS $BIT function.

• As an empty node.

If the data of interest is supplied by the node itself, the actual subscript is usually set to an empty string (“”). For example, an index that associates a name with an ID value would normally look like this:

  SET ^Data("APPLE".1) = ""
  SET ^Data("ORANGE".2) = ""
  SET ^Data("BANANA".3) = ""
Copy the code

Deleting a Global Node

To remove a global node, a group of child nodes, or the entire global node from the database, use ObjectScript kill or ZKILL commands.

The Kill command removes all nodes (data and their corresponding entries in the array) at a particular global reference, including any child nodes. That is, all nodes starting with the specified subscript will be deleted.

For example, the ObjectScript statement:

  KILL ^Data
Copy the code

Delete the entire ^Data global variable. Subsequent references to this global variable will return a

error.

ObjectScript statements:

   KILL ^Data(100)
Copy the code

Delete the contents of node 100 in the ^Data global variable. If there are child nodes, such as ^data(100,1), ^data(100,2), and ^data(100,1, 2, 3), these child nodes are also removed.

The ObjectScript ZKILL command is used to delete a specified global or global subscript node. It does not delete child nodes.

Note: After killing a large global variable, the space that was once occupied by the global variable may not be fully released because the garbage collector daemon marks the blocks as free behind the scenes. Therefore, called immediately after a large global variable is terminatedSYS.DatabaseOf the classReturnUnusedSpaceMethod may not return the expected size of space because the globally occupied block may not have been freed.

Cannot be used with global variablesnewCommand.

Tests the existence of an all-variable office node

To test whether a particular global variable (or its descendants) contains DATA, use the $DATA function.

$DATA returns a value indicating whether the specified global variable reference exists. Possible return values include:

The status value	meaning
0	Global variables are not defined.
1	Global variables exist and contain data, but have no children. Notice that the empty string (""Can be used as data.
10	Global variables have descendants (including downward Pointers to child nodes), but contain no data themselves. Any direct reference to such a variable will differentiate<UNDEFINED>Error. For example, if$data(^y)return10,SET x=^yWill produce<UNDEFINED>Error.
11	Global variables contain both data and descendants (including downward Pointers to child nodes).

Retrieves the value of the global variable node

To get the value stored in a particular global variable node, simply use the global reference as an expression:

   SET color = ^Data("Color"); assign to a local variable WRITE ^Data("Color"); use as a command argument SET x=$LENGTH(^Data("Color")); use as a function parameterCopy the code

$GETfunction

You can also use the $GET function to GET the value of the global node:

   SET mydata = $GET(^Data("Color"))
Copy the code

This retrieves the value of the specified node (if present), and returns an empty string (” “) if the node has no value. If the node has no value, you can use the optional second argument $get to return the specified default value.

WRITE,ZWRITEandZZDUMPThe command

Various ObjectScript display commands can be used to display the contents of global variables or global variable quantum nodes. The WRITE command returns the value of the specified global or child node as a string. The ZWRITE command returns the name of the global variable and its value, as well as each of its children and its value. The ZZDUMP command returns the value of a specified global or child node in hexadecimal dump format.