Extended Global References

Forms of Extended Global References

There are two forms of extended references:

• Explicit namespace reference — You specify the name of the namespace where the global is located as part of the syntax of the global reference.

• Implied namespace reference — You specify the directory and, optionally, the system name as part of the syntax of the global reference. In this case, no global mappings apply, since the physical dataset (directory and system) is given as part of the global reference.

The use of explicit namespaces is preferred, because this allows for redefinition of logical mappings externally, as requirements change, without altering your application code.

InterSystems IRIS supports two syntaxes for extended references:

• Bracket syntax, which encloses the extended reference with square brackets ([ ]).

• Environment syntax, which encloses the extended reference with vertical bars (| |).

Bracket Syntax

You can use bracket syntax to specify an extended global reference with either an explicit namespace or an implied namespace:

Explicit namespace:

^[nspace]glob

Implied namespace:

^[dir,sys]glob

In an explicit namespace reference, nspace is a defined namespace that the global glob has not currently been mapped or replicated to. In an implied namespace reference, dir is a directory (the name of which includes a trailing backslash: \), sys is a system, and glob is a global within that directory. If nspace or dir is specified as a carat (^), the reference is to a process-private global.

You must include quotation marks around the directory and system names or the namespace name unless you specify them as variables. The directory and system together comprise an implied namespace. An implied namespace can reference either:

• The specified directory on the specified system.

• The specified directory on your local system, if you do not specify a system name in the reference. If you omit the system name from an implied namespace reference, you must supply a double caret (^^) within the directory reference to indicate the omitted system name.

To specify an implied namespace on a remote system:

["dir","sys"]

To specify an implied namespace on the local system:

["^^dir"]

For example, to access the global ORDER in the C:\BUSINESS\ directory on a machine called SALES:

  Set x = ^["C:\BUSINESS\","SALES"]ORDER

To access the global ORDER in the C:\BUSINESS\ directory on your local machine:

   Set x = ^["^^C:\BUSINESS\"]ORDER

To access the global ORDER in the defined namespace MARKETING:

   Set x = ^["MARKETING"]ORDER

To access the process-private global ORDER:

   Set x = ^["^"]ORDER

Note:

When creating an implied namespace extended reference involving a mirrored database, you can use its mirrored database path, in the format :mirror:mirror_name:mirror_DB_name. For example, when referring to the database with the mirror database name mirdb1 in the mirror CORPMIR, you could form an implied reference as follows:

["^^:mirror:CORPMIR:mirdb1"]

The mirrored database path can be used for both local and remote databases.

Environment Syntax

The environment syntax is defined as:

^|"env"|global

"env" can have one of five formats:

• The null string ("") — The current namespace on the local system.

• "namespace" — A defined namespace that global is not currently mapped to. Namespace names are not case-sensitive. If namespace has the special value of "^", it is a process-private global.

• "^^dir" — An implied namespace whose default directory is the specified directory on your local system, where dir includes a trailing backslash (\).

• "^system^dir" — An implied namespace whose default directory is the specified directory on the specified remote system, where dir includes a trailing backslash (\).

• omitted — If there is no "env" at all, it is a process-private global.

To access the global ORDER in your current namespace on your current system, when no mapping has been defined for ORDER, use the following syntax:

   Set x = ^|""|ORDER

This is the same as the simple global reference:

   Set x = ^ORDER

To access the global ORDER mapped to the defined namespace MARKETING:

   Set x = ^|"MARKETING"|ORDER

You can use an implied namespace to access the global ORDER in the directory C:\BUSINESS\ on your local system:

   Set x = ^|"^^C:\BUSINESS\"|ORDER

You can use an implied namespace to access the global ORDER in the directory C:\BUSINESS on a remote system named SALES:

   Set x = ^|"^SALES^C:\BUSINESS\"|ORDER

To access the process-private global ORDER:

   Set x = ^||ORDER
   Set x=^|"^"|ORDER