Skip to main content

^$GLOBAL (ObjectScript)

Provides information about globals and process-private globals.

Synopsis

^$|nspace|GLOBAL(global_name)
^$|nspace|G(global_name)

^$||GLOBAL(global_name)
^$||G(global_name)

Arguments

Argument Description

|nspace| or

[nspace]

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.
global_name An expression that evaluates to a string containing an unsubscripted global name. Global names are case-sensitive. When using ^$||GLOBAL() syntax, an unsubscripted global name that corresponds to the process-private global: ^a for ^||a.

Description

You can use ^$GLOBAL as an argument to the $DATA, $ORDER, and $QUERY functions to return information about the existence of global variables in the current namespace (the default), or in a specified namespace. You can also use ^$GLOBAL to return information about existence of process-private global variables.

For more information on global variables, refer to Using InterSystems IRIS Multidimensional Storage in Using Globals.

Process-Private Globals

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.

Arguments

nspace

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("LOSER")   ; 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".

global_name

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".

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 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.

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.

Note:

$ORDER(^$GLOBAL(name)) does not return % global names from the IRISSYS database.

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

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.

Note:

$QUERY(^$GLOBAL(name)) does not return % global names from the IRISSYS database.

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")

As an Argument to MERGE

^$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

See Also

Next section^$JOB (ObjectScript)
FeedbackOpens in a new tab