^$GLOBAL (ObjectScript)

You can use ^$GLOBAL to get information about the existence of process-private global variables in all namespaces. You can specify lookup of a process-private global as either ^$||GLOBAL or ^$|"^"|GLOBAL.

For example, to get information about the process-private global ^||a and its descendents, you would specify $DATA(^$||GLOBAL("^a")). Process-private globals are not namespace-specific, so this lookup returns information about ^||a regardless of the current namespace when the process-private global was defined.

Note that ^$GLOBAL does not support specifying process-private global syntax in the global_name itself. Attempting to specify global_name with process-private global syntax results in a <NAME> error.

This optional argument allows ^$GLOBAL to look up a global_name that is defined in another namespace. This is known as extended SSVN reference. You can specify the namespace name either explicitly, as a quoted string literal, as a variable, or by specifying an implied namespace. Namespace names are not case-sensitive. You can use either bracket syntax ["USER"] or environment syntax |"USER"|. No spaces are allowed before or after the nspace delimiters.

You can test whether a namespace is defined by using the following method:

   WRITE ##class(%SYS.Namespace).Exists("USER"),!  ; an existing namespace
   WRITE ##class(%SYS.Namespace).Exists("TESTNAMESPACE1")   ; a non-existent namespace

You can use the $NAMESPACE special variable to determine the current namespace. The preferred way to change the current namespace is NEW $NAMESPACE then SET $NAMESPACE="nspacename".

An expression that evaluates to a string containing an unsubscripted global name. Globals are case-sensitive.

• ^$GLOBAL("^a"): The global_name "^a" looks up this global and its descendents in the current namespace. It does not look up the process-private global "^||a".

• ^$|"USER"|GLOBAL("^a"): The global_name "^a" looks up this global and its descendents in the “USER” namespace. It does not look up the process-private global "^||a".

• ^$||GLOBAL("^a"): The global_name "^a" looks up the process-private global "^||a" and its descendents in all namespaces. It does not look up the global "^a".

^$GLOBAL as an argument to $DATA returns an integer value that signifies whether the global name you specify exists as a ^$GLOBAL node. The integer values that $DATA can return are shown in the following table.

The following example tests for the existence of the specified global variable in the current namespace:

   KILL ^GBL
   WRITE $DATA(^$GLOBAL("^GBL")),!
   SET ^GBL="test"
   WRITE $DATA(^$GLOBAL("^GBL")),!
   SET ^GBL(1,1,1)="subscripts test"
   WRITE $DATA(^$GLOBAL("^GBL"))

returns 0, then 1, then 11.

The following example tests for the existence of the specified global variable in the USER namespace:

   SET $NAMESPACE="USER"
   SET ^GBL(1)="test"
   SET $NAMESPACE="%SYS"
   WRITE $DATA(^$|"USER"|GLOBAL("^GBL"))

returns 10.

The following example tests for the existence of the specified process-private global variable in any namespace:

   SET $NAMESPACE="USER"
   SET ^||PPG(1)="test"
   SET $NAMESPACE="%SYS"
   WRITE $DATA(^$||GLOBAL("^PPG"))

returns 10.

$ORDER(^$|nspace|GLOBAL( global_name),direction)

^$GLOBAL as an argument to $ORDER returns the next or previous global name in collating sequence to the global name you specify. If no such global name node exists in ^$GLOBAL, $ORDER returns a null string.

The direction argument specifies whether to return the next or the previous global name. If you do not provide a direction argument, InterSystems IRIS returns the next global name in collating sequence to the one you specify. For further details, refer to the $ORDER function.

The following subroutine searches the current namespace and stores the global names in a local array named GLOBAL.

GLOB   
  SET NAME=""
  WRITE !,"The following globals are in ",$NAMESPACE
  FOR I=1:1 {
    SET NAME=$ORDER(^$GLOBAL(NAME))
    WRITE !,NAME
    QUIT:NAME=""
    SET GLOBAL(I)=NAME
  }
  WRITE !,"All done"
  QUIT

^$GLOBAL as an argument to $QUERY returns the next global name in collating sequence to the global name you specify. If no such global name exists as a node in ^$GLOBAL, $QUERY returns a null string.

In the following example, three globals (^GBL1, ^GBL2 and ^GBL3) are present in the USER namespace.

  NEW $NAMESPACE
  SET $NAMESPACE="USER"
  SET (^GBL1,^GBL2,^GBL3)="TEST"
  NEW $NAMESPACE
  SET $NAMESPACE="%SYS"
  WRITE $QUERY(^$|"USER"|GLOBAL("^GBL1")),!
  WRITE $QUERY(^$|"USER"|GLOBAL("^GBL2"))
  NEW $NAMESPACE
  SET $NAMESPACE="USER"
  KILL ^GBL1,^GBL2,^GBL3

The first WRITE returns ^$|"USER"|GLOBAL("^GBL2")

The second WRITE returns ^$|"USER"|GLOBAL("^GBL3")

^$GLOBAL as the source argument of the MERGE command copies the global directory to the destination variable. MERGE adds each global name as a destination subscript with a null value. This is shown in the following example:

   MERGE gbls=^$GLOBAL("")
   ZWRITE gbls