Skip to main content

System Flags and Qualifiers (qspec)

Many methods in the class library accept the qspec argument, via which you can control the import of external sources into InterSystems IRIS® data platform, control how code is compiled, and control the export of code. The qspec argument is a concatenation of the supported system flags and qualifiers, documented on this page.

These mechanisms work together. That is, qspec can include both flags and qualifiers, but flags must be placed before (to the left of) the qualifiers. No spaces are allowed between qualifiers.

The flags were modeled on UNIX® command-line parameters and thus are one- or two-character sequences. The qualifiers are more numerous and have longer names, each of which starts with a slash character (/). The flags and qualifiers can be negated.

For many flags, there is an equivalent or related qualifier, and the two may be used in the same qspec. Also see Order Of Processing for qspec.

Example

The following example uses the qspec argument for the Load() method of %SYSTEM.OBJOpens in a new tab, which imports a file. In this example, qspec is a concatenation of the c and k flags.

 Do $system.OBJ.Load(filename,"ck")

Or equivalently:

 Do $system.OBJ.Load(filename,"/compile/keepsource")

The following is also equivalent:

 Do $system.OBJ.Load(filename,"c/keepsource")

These flags and qualifiers are described later on this page.

Negation

To negate a flag, precede it with a hyphen (-).

To negate a qualifier, use /no instead of /; for example: /nodisplaylog. Or append =0 to the end of the qualifier; for example: /displaylog=0

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.

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
/checkstoragedefined Checks that the class has storage defined for all properties. When set equal to 1, this qualifier indicates when the storage definition has changed during the compilation. 0
/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 two-part or three-part release version, such as 2020.1 or 2020.1.1. For example, /exportversion=iris2020.1.1 or /exportversion=cache2018.1.8. 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 Qualifiers

Flag Meaning Default
/autoload Specifies the directory to be auto-loaded; its subdirectories are also auto-loaded. For more information, see the RunTest()Opens in a new tab method in %UnitTest.ManagerOpens in a new tab.
/cleanup Cleans up globals upon completion of the 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 class names 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-format source files. 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

Qualifiers for Flags

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

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

Help for Flags and Qualifiers

To see the available settings for the flags, use the command:

 Do $system.OBJ.ShowFlags()

This produces output like the following:

See $system.OBJ.ShowQualifiers() for comprehensive list of qualifiers as flags have been superseded
by qualifiers
 
    b - Include sub classes.
    c - Compile. Compile the class definition(s) after loading.
    d - Display. This flag is set by default.
...
Default flags for this namespace
You may change the default flags with the SetFlags(flags,system) classmethod.

Similarly, to see the available settings for the qualifiers, use the command:

 Do $system.OBJ.ShowQualifiers()

This produces output like the following:

            Name: /checkschema
    Description: Validate imported XML files against the schema definition.
           Type: logical
           Flag: i
  Default Value: 1

           Name: /checksysutd
    Description: Check system classes for up-to-dateness
           Type: logical
  Default Value: 0

           Name: /checkuptodate
    Description: Skip classes or expanded classes that are up-to-date.
           Type: enum
           Flag: ll
      Enum List: none,all,expandedonly,0,1
  Default Value: expandedonly
  Present Value: all
  Negated Value: none
...

These methods also report on the current flags and qualifiers, respectively.

Controlling the Defaults

This page lists the defaults (if applicable) for the flags and qualifiers. You can override the default flags by using the SetFlags() method of %SYSTEM.OBJOpens in a new tab; see the class reference for details. Similarly, you can set qualifiers for the current namespace (the default) or system-wide by using the SetQualifiers() method.

Order of Processing for qspec

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.

Note that because flags must be listed to the left of any qualifiers, the qualifier settings always override any flag settings.

FeedbackOpens in a new tab