Caché ObjectScript Reference
^$GLOBAL
[Home]  [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Provides information about globals.
Synopsis
^$|nspace|GLOBAL(global_name)
^$|nspace|G(global_name)
Parameters
or
Optional — An extended SSVN reference, either an explicit namespace name or an implied namespace. Must evaluate to a quoted string, which is enclosed in either square brackets (["nspace"]) or vertical bars (|"nspace"|). Namespace names are not case-sensitive; they are stored and displayed in uppercase letters.
You may also specify ^$GLOBAL as a process-private global as either ^||$GLOBAL or ^|"^"|$GLOBAL.
global_name An expression that evaluates to a string containing an unsubscripted global name.
Description
You can use ^$GLOBAL as an argument to the $DATA, $ORDER, and $QUERY functions to get information about the existence of global variables in the current namespace (the default), or in a specified namespace.
Note:
^$GLOBAL does not support global_name as a process-private global. Attempting to specify global_name as a process-private global results in a <NAME> error.
For more information on global variables, refer to Using Caché Multidimensional Storage in Using Caché Globals.
Parameters
nspace
This optional parameter allows you to specify a structured system variable in another namespace by using an extended SSVN reference. You can specify the namespace name either explicitly, as a quoted string literal or 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("LOSER")   ; a non-existent namespace
 
You can use the $NAMESPACE special variable to determine the current namespace, and the ZNSPACE command to change the current namespace.
global_name
An expression that evaluates to a string containing an unsubscripted global name.
Examples
The following examples show how to use ^$GLOBAL as an argument to the $DATA, $ORDER, and $QUERY functions.
As an Argument to $DATA
^$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.
Value Meaning
0 Global name does not exist
1 Global name is an existing node with data but has no descendants.
10 Global name is an existing node with no data but has descendants.
11 Global name is an existing node with data and has descendants.
The following example test for the existence of a global variable in the user’s default namespace.
   KILL ^GBL
   WRITE $DATA(^$GLOBAL("^GBL"))
 
returns 0.
The following example test for the existence of a global variable in the SAMPLES namespace.
   SET ^GBL(1)="TEST"
   WRITE $DATA(^$|"SAMPLES"|GLOBAL("^GBL"))
 
returns 10.
   SET ^GBL(1)="TEST"
   WRITE $DATA(^$||GLOBAL("^GBL"))
 
As an Argument to $ORDER
$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, Caché 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 user’s default namespace and stores the global names in a local array named GLOBAL.
GLOB   
  SET NAME=""
  WRITE !,"The following globals are in ",$ZNSPACE
  FOR I=1:1 {
    SET NAME=$ORDER(^$GLOBAL(NAME))
    WRITE !,NAME
    QUIT:NAME=""
    SET GLOBAL(I)=NAME
  }
  WRITE !,"All done"
  QUIT
 
As an Argument to $QUERY
^$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 SAMPLES namespace.
   ZNSPACE "SAMPLES"
   SET (^GBL1,^GBL2,^GBL3)="TEST"
   ZNSPACE "USER"
   WRITE $QUERY(^$|"SAMPLES"|GLOBAL("^GBL1"))
   WRITE !,$QUERY(^$|"SAMPLES"|GLOBAL("^GBL2"))
   ZNSPACE "SAMPLES"
   KILL ^GBL1,^GBL2,^GBL3
 
The first WRITE returns ^$|"SAMPLES"|GLOBAL("^GBL2")
The second WRITE returns ^$|"SAMPLES"|GLOBAL("^GBL3")
See Also