$SYSTEM (ObjectScript)

Contains system information about system objects.

Synopsis

$SYSTEM 
$SY  
$SYSTEM.class.method()

Description

$SYSTEM can be invoked as either a special variable or as a class which invokes methods that return system information.

$SYSTEM Special Variable

$SYSTEM as a special variable contains the local system name and the name of the current instance of InterSystems IRIS, separated by a colon (:). The name of the machine follows the case conventions of the local operating system and the name of the instance is in uppercase. For example:

MyComputer:IRISInstance

You can also determine your local system name using the LocalHostName()Opens in a new tab method:

  WRITE $SYSTEM,!
  WRITE $SYSTEM.INetInfo.LocalHostName()

The abbreviation $SY can only be used for $SYSTEM as a special variable.

$SYSTEM Class

$SYSTEM as a class provides access to a variety of system objects. You can invoke a method that returns information, or a method that performs some operation such as upgrading or loading and returns status information. InterSystems IRIS supports several classes of system objects, including the following:

Version: for version numbers of InterSystems IRIS and its components
SYS: for the system itself
OBJ: for Objects
SQL: for SQL queries

Note that object class names and method names are case-sensitive. Specifying the wrong case for these names results in a <CLASS DOES NOT EXIST> or <METHOD DOES NOT EXIST> error. If you do not specify parentheses with the method name, it issues a <SYNTAX> error.

$SYSTEM methods and properties can be accessed using dot syntax, as shown in the following equivalent syntax examples:

WRITE ##class(%SYSTEM.INetInfo).LocalHostName()
WRITE $SYSTEM.INetInfo.LocalHostName()

$SYSTEM can access the System API classes in the %SYSTEM class package, described in the InterSystems Class Reference documentation. Note that in the ##class syntax the %SYSTEM class package name is case-sensitive. In the $SYSTEM syntax the $SYSTEM keyword is not case-sensitive. For further information on using dot syntax, refer to the chapter “Working with Registered Objects” in Defining and Using Classes.

For further information on using %SYSTEM.OBJOpens in a new tab, refer to Flags and Qualifiers.

Flags and Qualifiers

These are arguments which can be used to control the import of external sources into InterSystems IRIS, compile existing applications, and export these to external destinations. In the class documentation for %SYSTEM.OBJOpens in a new tab, these are often supplied as the value of the parameter, qspec. The available settings for each can be displayed on the Terminal using the commands:

 USER>DO $SYSTEM.OBJ.ShowFlags()

and

 USER>DO $SYSTEM.OBJ.ShowQualifiers()

The flags or qualifiers that have been set are listed at the end of each method’s display, as shown in the following examples: Default flags for this namespace kb, Default Qualifiers for namespace 'USER' are: /percent=1 /compileembedded=1, or Default Qualifiers at system level are: /percent=0.

Flags

Of the two, the flags are the earlier. They were modeled on UNIX® command-line parameters and thus are one- or two-character sequences. The existing flags and their meanings (excluding deprecated flags) are:

Existing Flags

Flag	Meaning	Default
b	Includes subclasses and classes that reference the current class in SQL usage.
c	Compiles the class definitions after loading.
d	Display. Flag set by default.	X
e	Deletes the extent definition that describes the global storage used by the extent, and deletes the data.
h	Shows hidden classes.
i	Validates XML export format against schema on Load. Flag set by default.	X
k	Keep source. When this flag is set, source code of generated routines will be kept.
l	Deprecated — Locking of classes during compilation is always automatically performed, regardless of the setting of this flag.	X
p	Includes classes whose names begin with the “%” character.
r	Recursive. Compiles all the classes that are dependency predecessors.
s	System. Processes system messages or application messages.
u	Update only. Skip compilation of classes that are already up-to-date.
y	Includes classes that are related to the current class; classes that either reference the current class in SQL usage, or are referenced by the current class in SQL usage.
o1, o2, o3, o4	Optimization specifiers. Deprecated and ignored by the class compiler.

Note:

Flags may be turned off by preceding them with a dash (-).

Qualifiers

InterSystems IRIS also includes a more extensible set of controls to supplement flags: qualifiers. The flag mechanism remains fully supported. In addition, a qualifier exists whose meaning is the same as each existing flag, and the two may be used in the same specifier.

Since there are so many more qualifiers, they are organized into groups according to the function they control as shown in the following tables. Deprecated qualifiers are not shown.

You can also set these qualifiers for the current namespace (the default) or system-wide using the SetQualifiers()Opens in a new tab method.

Compiler Qualifiers

Qualifier	Meaning	Default
/autoinclude	Automatically includes any classes that are not up to date that are required to compile this class.	1
/checkschema	Validates imported XML files against the schema definition.	1
/checksysutd	Checks system classes for up-to-dateness.	0
/checkuptodate	Skips classes or expanded classes that are up-to-date.	expandedonly
/compile	Causes classes loaded to be compiled as well.	0
/compileembedded	Causes Embedded SQL to be compiled when the ObjectScript code that contains it is compiled. By default, Embedded SQL is compiled upon first execution of the SQL code.	0
/cspcompileclass	Causes classes created by CSP or CSR load to be compiled.	1
/cspdeployclass	When CSP page loaded deploys the class generated.	0
/csphidden	Classes generated from CSP and CSR compilation are marked as hidden.	1
/defaultowner	When loading classes, if the Owner keyword is not defined, insert the user name specified in this string into the class definition as the class owner. If the value of this string is $USERNAME, insert the current user name into the class definition as the class owner.	—
/defines	Comma separated list of macros to define and, optionally, their values.	—
/deleteextent	Deletes the extent definition that describes the global storage used by the extent, and deletes the data.	0
/diffexport	Does not include any time or platform information in export so the files can be run through diff/merge tools.	0
/display	Alias qualifier for /displaylog and /displayerror.	—
/displayerror	Displays error information.	1
/displaylog	Displays log information.	1
/expand	Alias qualifier for /predecessorclasses, /subclasses and /relatedclasses.	—
/exportgenerated	When exporting classes also exports generated classes where the class generating them is also included.	0
/exportselectivity	Exports the selectivity values stored in the storage definition for this class.	1
/filterin	Alias qualifier for /application, /system and /percent.	—
/generated	Determines when expanding patterns or lists of classes in a package whether to include generated items (routines, classes, etc.).	1
/generatemap	Generates the map file.	1
/importselectivity	0: Do not import selectivity values from the XML file. 1: Import the selectivity values stored in the storage definition when importing XML file. 2: Keep the existing class selectivity values, but if the existing class does not have selectivity specified for something that is present in the XML file then use the selectivity value from the XML file.	2
/includesubpackages	Includes sub-packages.	1
/journal	Journaling enabled while performing a class compile. If the process performing the compile has specifically disabled journaling, /journal defaults to 0, rather than the system-wide default of 1.	1
/keepsource	Keeps the source code of generated routines.	0
/lock	Deprecated — Classes are automatically always locked during compilation, regardless of the setting of this qualifier.	1
/mapped	Includes classes mapped from another database. If you specifically ask to compile a class from another database (CompileList() method), the class will be compiled regardless of the /mapped setting. /mapped only applies when the code is searching for classes, for example, using the CompileAll() method. If you are upgrading the class definition database for one namespace using the Upgrade() method, or all namespaces using the UpgradeAll() method, you must set /mapped = 1 or mapped objects will not be included in the upgrade.	0
/mergeglobal	If importing a global from XML file merges the global with existing data.	0
/multicompile	Enables multiple users’ jobs to compile classes.	1
/percent	Includes percent classes.	0
/predecessorclasses	Recursively includes dependency predecessor classes.	0
/relatedclasses	Recursively includes related classes.	0
/retainstorage	When a class is compiled, the compiler generates a storage definition. By default, if the storage definition is updated the class definition is updated with the updated storage definition. If a new version of the class is loaded from an external source, that updated storage definition is overwritten by whatever is defined in the new version of the class definition. If the new version of the class does not include a storage definition then the existing storage definition is removed. Setting /retainstorage saves the existing storage definition temporarily and restores it after the new version of a class is loaded. If the new version of the class also defines the storage definition, the existing storage definition is overwritten and not retained. If the new version of the class does not define the storage definition, the previous version of the storage definition is restored.	0
/subclasses	Recursively includes sub-classes.	0
/system	Processes system messages or application messages.	0

Export Qualifiers

Flag	Meaning	Default
/checksysutd	Checks system classes for up-to-dateness.	0
/checkuptodate	Checks if classes are up-to-date when projecting.	expandedonly
/createdirs	Creates directories if they do not exist.	0
/cspdeployclass	When CSP page loaded deploys the class generated.	0
/diffexport	Does not include any time or platform information in export so the files can be run through diff/merge tools.	0
/display	Alias qualifier for /displaylog and /displayerror.	—
/displayerror	Displays error information.	1
/displaylog	Displays log information.	1
/documatichost	Host that is used in JavaDoc generation.	—
/documaticnamespace	Namespace that is used in JavaDoc generation.	—
/documaticport	Port that is used in JavaDoc generation.	—
/exportgenerated	When exporting classes also exports generated classes where the class generating them is also included.	0
/exportselectivity	Exports the selectivity values stored in the storage definition for this class.	1
/exportversion	Specifies the InterSystems platform and version of the system that you are exporting to. Specify the platform as iris or cache. Specify the version as a three-part release version, for example 2018.1.1. For example, /exportversion=iris2018.1.1 or /exportversion=cache2018.1.2. IRIS uses the /exportversion value when the exporting and importing systems are not the same InterSystems version. The system handles changes in the export format across versions by removing class keywords that were not implemented in the earlier InterSystems version. Specifying /exportversion does not guarantee compatibility of code between the exporting and importing systems.	Specifies the InterSystems platform and version of the system that you are exporting to. Specify the platform as iris or cache. Specify the version as a two-part or three-part release version, such as 2018.1 or 2018.1.1. For example, /exportversion=iris2018.1.1 or /exportversion=cache2018.1.2. IRIS uses the /exportversion value when the exporting and importing systems are not the same InterSystems version. The system handles changes in the export format across versions by removing class keywords that were not implemented in the earlier InterSystems version. Specifying /exportversion does not guarantee compatibility of code between the exporting and importing systems.	The current version of InterSystems IRIS
/generatemap	Generates the map file.	1
/generationtype	Generation mode.	—
/genserialuid	Generates serialVersionUID.	1
/importselectivity	0: do not import selectivity values from the XML file; 1: import the selectivity values stored in the storage definition when importing XML file; 2: keep any existing selectivity values but if a property does not have an existing value then use the selectivity from the XML file.	2
/includesubpackages	Includes sub-packages.	1
/javadoc	Does not create javadoc.	1
/make	Only generates dependency or class if timestamp of last compilation is greater than timestamp of last generation.	0
/mapped	Includes classes mapped from another database.	0
/mergeglobal	If importing a global from XML file merges the global with existing data.	0
/newcollections	Uses native Java collections.	1
/percent	Includes percent classes.	0
/pojo	POJO generation mode.	0
/predecessorclasses	Recursively includes dependency predecessor classes.	0
/primitivedatatypes	Uses Java primitives for %Integer, %Boolean, %BigInt, %Decimal.	0
/projectabstractstream	Projects classes that contain methods whose arguments are abstract streams or whose return type is an abstract stream.	0
/projectbyrefmethodstopojo	Projects byref methods to pojo implementation.	0
/recursive	Exports classes recursively.	1
/relatedclasses	Recursively includes related classes.	0
/skipstorage	Does not export the class storage information.	0
/subclasses	Recursively includes sub-classes.	0
/system	Processes system messages or application messages.	0
/unconditionallyproject	Projects regardless of problems that may prevent code from compiling or working correctly.	0
/usedeepestbase	Uses deepest base in which method or property is defined for method or property definition. If P is defined in A,B, and C and A extends B extends C, then C is a deeper base for P.	0

ShowClassAndObject Qualifiers

Flag	Meaning	Default
/detail	Shows detailed information.	0
/diffexport	Does not include any time or platform information in export so the files can be run through diff/merge tools.	0
/hidden	Shows hidden classes.	0
/system	Processes system messages or application messages.	0

UnitTest

Flag	Meaning	Default
/autoload	Specifies the directory to be auto-loaded.	—
/cleanup	Cleans up globals upon completion of unit test. By default, globals are not cleaned up. Even when set, Analytics globals are not cleaned up.	0
/debug	Causes the Asserts to BREAK if they fail.	0
/delete	Determines if loaded classes should be deleted.	1
/display	Alias qualifier for /displaylog and /displayerror.	—
/displayerror	Displays error information.	1
/displaylog	Displays log information.	1
/findleakedvariables	When enabled, the public variables currently set in the process are recorded before a test is run, then compared with those set after the test is completed. Other than a predetermined set of known context and output variables, such as SQLCODE, any newly defined variables are reported, with their values, as a test failure.	0
/load	Determines if classes should be loaded; if not, then only classnames are obtained from the directories.	1
/loadudl	Loads UDL files produced by your IDE. When set, loads .cls, .mac, .int, and .inc files. /loadudl and /loadxml can be used to limit what types of files are loaded; by default, all files are loaded. UDL files are always loaded as UTF8 so that Unicode characters are loaded correctly.	1
/loadxml	Loads XML files produced by Studio. When set, loads .xml files. /loadudl and /loadxml can be used to limit what types of files are loaded; by default, all files are loaded.	1
/recursive	Determines if tests in subdirectories should run recursively.	1
/run	Determines if tests should run.	1

These qualifiers are given in the qspec as they appear, for example, “/compile/displayerror/subclasses”. No spaces are allowed between qualifiers.

Note:

Qualifiers may be negated by preceding the qualifier with “no” as in “/nodisplaylog”. Alternatively, the value of the qualifier can be specified explicitly as in “/displaylog=0”.

Qualifiers For Flags

The following table gives the existing flag and the equivalent qualifier. Some flags map into multiple qualifiers, and also have different meanings when used for differing purposes.

Flag Qualifier Mapping

Flag	Group	Qualifier	Default
b	Compiler	/subclasses	0
c	Compiler	/compile	0
d	Compiler	/displayerror	1
d	Compiler	/displaylog	1
d	UnitTest	/displayerror	1
d	UnitTest	/displaylog	1
e	Compiler	/deleteextent	0
i	Compiler	/checkschema	1
k	Compiler	/keepsource	0
l	Compiler	/lock	1
p	Compiler	/percent	0
r	Compiler	/predecessorclasses	0
r	Compiler	/includesubpackages	1
s	Compiler	/system	0
y	Compiler	/relatedclasses	0
b	Export	/subclasses	0
d	Export	/displayerror	1
d	Export	/displaylog	1
g	Export	/exportselectivity	0
p	Export	/percent	0
r	Export	/includesubpackages	1
r	Export	/recursive	1
r	Export	/predecessorclasses	0
s	Export	/system	0
y	Export	/relatedclasses	0
h	ShowClassAndObject	/hidden	0
s	ShowClassAndObject	/system	0

Order Of Processing

The qspec is processed from left to right. The setting for a given flag or qualifier overrides the current setting whether it came from the environment defaults, or from an occurrence earlier in the qspec.

When both flags and qualifiers appear, the flags must be placed before (to the left of) the qualifiers. This means that qualifier settings always override any flag settings.

Examples

The following is an example of using $SYSTEM to invoke a method that displays a list of the classes available in the current namespace:

   DO $SYSTEM.OBJ.ShowClasses()

This displays results like the following:

%SYS>d $system.OBJ.ShowClasses()
%SYS.APIManagement
%SYS.Audit
%SYS.AuditString
%SYS.ClusterInfo
%SYS.DatabaseQuery
...
SYS.WSMon.wsProcess
SYS.WSMon.wsResource
SYS.WSMon.wsSystem

You can list all of the methods for the OBJ class as follows. (By changing the class name, you can use this method to get a list for any system class):

   DO $SYSTEM.OBJ.Help()

To list information about just one method in a class, specify the method name in the Help argument list, as shown in the following example:

   DO $SYSTEM.OBJ.Help("Load")

The following are a few more examples of $SYSTEM that invoke methods:

   DO $SYSTEM.OBJ.Upgrade()
   WRITE !,"* * * * * * * * * * * "
   DO $SYSTEM.CSP.DisplayConfig()
   WRITE !,"* * * * * * * * * * * "
   WRITE !,$SYSTEM.Version.GetPlatform()
   WRITE !,"* * * * * * * * * * * "
   WRITE !,$SYSTEM.SYS.TimeStamp()

The following example calls the same methods as the previous example, using the ##class(%SYSTEM) syntax form:

   DO ##class(%SYSTEM.OBJ).Upgrade()
   DO ##class(%SYSTEM.CSP).DisplayConfig()
   WRITE !,##class(%SYSTEM.Version).GetPlatform()
   WRITE !,##class(%SYSTEM.SYS).TimeStamp()

The previous two examples requires that UnknownUser have assigned the %DB_IRISSYS role.