Rules and Guidelines for Identifiers
This page describes the rules for identifiers in ObjectScript code and in classes and also provides guidelines to avoid name collisions. Note that ObjectScript does not have reserved words, so if you use a command as an identifier, the result is syntactically correct, but the code is also potentially confusing to anyone who reads it.
For identifiers for namespaces and databases, see the relevant section of the System Administration Guide.
For identifiers for security entities such as users, roles, and resources, see the relevant section of the Authorization Guide.
Also see What Is Accessible in Your Namespaces.
Rules for Local Variable Names
For the name of a local variable, the following rules apply in ObjectScript:
-
The first character must be either a letter or a percent sign (%).
If you start a name with %, use z or Z as the next character after that.
-
The remaining characters must be letters or numbers, including letter characters above ASCII 255 (Unicode letters).
-
Names are case-sensitive.
-
The name must be unique (within the appropriate context) to the first 31 characters.
Any subscripts of the variable do not contribute to this count.
Local Variable Names to Avoid
Avoid using the following name for local variables:
-
SQLCODE
Avoid using SQLCODE as the name of a variable in any context where InterSystems SQL might run. See SQLCODE Values and Error Messages.
-
IO, IOF, IOBS, IOM, IOSL, IOT, IOST, IOPAR, MSYS, POP, RMSDF
Do not use these variable names in a context that uses the ^%IS utility (in practice, this is rare). See Introduction to I/O.
Rules for Global Variable Names
For the name of a global variable, the following rules apply:
-
The first character must be a caret (^), and the next character must be either a letter or a percent sign (%). For global names, a letter is defined as being an alphabetic character within the range of ASCII 65 through ASCII 255. Characters beyond ASCII 255 are not permitted.
-
The remaining characters must be letters or numbers (with one exception, noted in the next bullet).
-
The name of a global variable can include one or more period (.) characters, except not as the first or last character.
-
Names are case-sensitive.
-
The name must be unique (within the appropriate context) to the first 31 characters. The caret character does not contribute to this count. That is, the name of a global variable must be unique to the first 32 characters, including the caret.
Any subscripts of the variable do not contribute to this count.
-
In the IRISSYS database, InterSystems reserves to itself all global names except those starting with ^z, ^Z, ^%z, and ^%Z. See Custom Items in IRISSYS.
In all other databases, InterSystems reserves all global names starting with ^IRIS and ^%IRIS
Also see Global Variable Names to Avoid.
Global Variable Names to Avoid
When you create a database, InterSystems IRIS initializes it with some globals for its own use. Also, every namespace that you create contains mappings to system globals, including global nodes that are in writable system databases.
Percent Globals
Percent globals are available in all namespaces. The following rules apply:
-
You can set, modify, or kill your own globals with names that start ^%z or ^%Z (see Custom Items in IRISSYS)
-
You should not set, modify, or kill ^%SYS (except for setting nodes as noted in the documentation)
-
With the preceding exceptions, you should not set, modify, or kill globals with names that start ^%
Non-Percent Globals
To avoid overwriting system globals, do not set, modify, or kill the following globals in any namespace:
-
^CacheTemp* (reserved for use by some versions of InterSystems IRIS)
-
^DeepSee.* (restriction applies only to a namespace in which you are using InterSystems IRIS Analytics)
-
^Ens* (restriction applies only to an interoperability-enabled namespace; see Introducing Interoperability Productions)
-
^ERRORS
-
^HS (restriction applies in HealthShare namespaces)
-
^InterSystems.Sequences (restriction applies only to a namespace in which you are using the InterSystems IRIS Hibernate Dialect)
-
^IRIS* (reserved for use by InterSystems)
-
^IS.* (reserved for use by InterSystems IRIS sharding)
-
^ISC* (except for setting nodes as noted in the documentation)
-
^mqh (SQL query history)
-
^mtemp*
-
^OAuth2 (restriction applies in HealthShare namespaces)
-
^OBJ.GUID (except as noted in the documentation)
-
^OBJ.DSTIME
-
^OBJ.JournalT
-
^odd*
-
^rBACKUP
-
^rINC (contains include files)
-
^rINCSAVE
-
^rINDEX
-
^rINDEXCLASS
-
^rINDEXEXT
-
^rINDEXSQL
-
^rMAC (contains MAC code)
-
^rMACSAVE
-
^rMAP
-
^rOBJ (stores OBJ code)
-
^ROUTINE (stores routines)
-
^SchemaMap (restriction applies in HealthShare namespaces)
-
^SPOOL (restriction applies only to a namespace in which you are using InterSystems IRIS spooling; see Spool Devices)
-
^SYS (except for setting nodes as noted in the documentation)
-
^UnitTest.Result (stores results of any unit tests run in the given namespace)
-
^z* and ^Z* (reserved for use by InterSystems, except in the case of the IRISSYS database; see Custom Items in IRISSYS)
Rules for Routine Names and Labels
For the name of a routine or for a label, the following rules apply in ObjectScript:
-
The first character must be either a letter or a percent sign (%).
If you start a routine name with %, use z or Z as the next character after that; see Custom Items in IRISSYS.
-
The remaining characters must be letters or numbers (with one exception; see the next bullet). These other characters may include any letter character above ASCII 128.
The locale identifier is not taken into account when dealing with Unicode characters. That is, if a identifier consisting of Unicode characters is valid in one locale, the identifier is valid in any locale.
-
The name of a routine can include one or more period (.) characters, except not as the first or last character.
-
Names are case-sensitive.
-
The name of a routine must be unique (within the appropriate context) within the first 255 characters.
A label must be unique (within the appropriate context) within the first 31 characters.
Note that certain Z and %Z routine names are reserved for your use.
Reserved Routine Names for Your Use
InterSystems IRIS reserves the following routine names for your use. These routines do not exist, but if you define them, the system automatically calls them when specific events happen.
-
The ^ZWELCOME routine is intended to contain custom code to execute when the ObjectScript shell starts. See Using the ObjectScript Shell.
-
The ^ZAUTHENTICATE and ^ZAUTHORIZE routines are intended to contain custom code for authentication and authorization (to support delegated authentication and delegated authorization). For these routines, InterSystems IRIS provides templates. See Using Delegated Authorization and Delegated Authentication.
-
The ^ZMIRROR routine is intended to contain code to customize failover behavior when you use InterSystems IRIS Mirroring. See the High Availability Guide.
-
The ^%ZSTART and ^%ZSTOP routines are intended to contain custom code to execute when certain events happen, such as when a user logs in. These routines are not predefined. If you define them, the system can call them when these events happen. See Customizing Start and Stop Behavior with ^%ZSTART and ^%ZSTOP Routines.
-
^%ZLANGV00 and other routines with names that start ^%ZLANG are intended to contain your custom variables, commands, and functions. See Extending Languages with %ZLANG Routines.
-
The ^%ZJREAD routine is intended to contain logic to manipulate journal files if you use the ^JCONVERT routine. See Journaling.
Rules for Class Names
For any class, the full class name has the following form: packagename.classname
The rules for class names are as follows:
-
packagename (the package name) and classname (the short class name) must each start with a letter or a percent sign (%).
If you start a package name with %, use z or Z as the next character after that; see Custom Items in IRISSYS.
-
packagename can include periods.
If so, the character immediately after any period must be a letter.
Each period-delimited piece of packagename is treated as a subpackage name and is subject to uniqueness rules.
-
The remaining characters must be letters or numbers, including letter characters above ASCII 128.
The locale identifier is not taken into account when dealing with Unicode characters. That is, if a identifier consisting of Unicode characters is valid in one locale, the identifier is valid in any locale.
-
The package name and the short class name must be unique. Similarly, any subpackage name must be unique within the parent package name.
Note that the system preserves the case that you use when you define each class, and you must exactly match the case as given in the class definition. However, two identifiers cannot differ only in case. For example, the identifiers id1 and ID1 are considered identical for purposes of uniqueness.
-
There are length limits:
-
The package name (including all periods) must be unique within the first 189 characters.
-
The short class name must be unique within the first 60 characters.
The full class name contributes to the individual length limits for class members
-
Package, Class, and Schema Names to Avoid
For persistent classes, avoid using an SQL reserved word as the short name for the class.
If you use an SQL reserved word as the short name for a class, you will need to specify the SqlTableName keyword for the class. Also, the mismatch between the short class name and the SQL table name will require greater care when reading the code in the future.
For a list of the SQL reserved words, see Reserved Words.
Avoid the following package names (depending on the namespace). Do not use these as schema names either.
-
In any namespace, avoid the package name IRIS. This is reserved for use by InterSystems.
-
In any namespace, avoid the package name INFORMATION. This is a system package that is mapped to all namespaces.
-
In any interoperability-enabled namespace, avoid the package names Ens, EnsLib, EnsPortal, and CSPX. These packages are completely replaced during the upgrade process. If you define classes in these packages, you would need to export the classes before upgrading and then import them after upgrading.
-
In any interoperability-enabled namespace, avoid package names that start with Ens (case-sensitive). For more information, see Environmental Considerations
-
In a HealthShare namespace, avoid the package names HS, HSFHIR, HSMOD, and SchemaMap.
Rules for Class Member Names
For a class member, unless the name of that item is delimited, the name must follow these rules:
-
The name must start with either a letter or a percent sign (%).
There is an additional consideration for class members that are projected to SQL (this includes, for example, most properties of persistent classes). If the first character is %, the second character must be Z or z.
-
The remaining characters must be letters or numbers, including letter characters above ASCII 128.
-
The member name must be unique (within the appropriate context).
Note that the system preserves the case that you use when you define classes, and you must exactly match the case as given in the class definition. However, two class members cannot have names that differ only in case. For example, the identifiers id1 and ID1 are considered identical for purposes of uniqueness.
-
A method or property name must be unique within the first 180 characters.
-
The combined length of the name of a property and of any indexes on the property should be no longer than 180 characters.
-
The full name of each member (including the unqualified member name and the full class name) must be less than or equal to 220 characters.
-
InterSystems strongly recommends that you do not give two members the same name. This can have unexpected results.
Also, member names can be delimited. To create a delimited member name, use double quotes for the first and last characters of the name. Then the name can include characters that are otherwise not permitted. For example:
Property "My Property" As %String;
Member Names to Avoid
For persistent classes, avoid using an SQL reserved word as the name of a member.
If you use an SQL reserved word for one of these names, you will have to do extra work to specify how the class is projected to SQL. For example, for a property, you would need to specify the SqlFieldName keyword. Also, the mismatch between the identifier in the class and the identifier in SQL will require greater care when reading the code in the future.
For a list of the SQL reserved words, see Reserved Words. Notice that this list includes many items with names beginning with %, such as %SQLUPPER and %FIND. Such items are InterSystems extensions to SQL, and additional extensions may be added in future releases.
Custom Items in IRISSYS
You can create items in the IRISSYS database. Upon upgrade, some items will be deleted unless they follow the naming conventions for custom items.
To add code or data to this database so that your items are not overwritten, do one of the following:
-
Go to the %SYS namespace and create the item. For this namespace, the default routines database and default globals database are both IRISSYS. Use the following naming conventions to prevent your items from being affected by the upgrade installation:
-
Classes: start the package with Z, z, %Z, or %z
-
Routines: start the name with Z, z, %Z, or %z
-
Globals: start the name with ^Z, ^z, ^%Z, or ^%z
-
-
In any namespace, create items with the following names:
-
Routines: start the name with %Z or %z
-
Globals: start the name with ^%Z or ^%z
Because of the standard mappings in any namespace, these items are written to IRISSYS.
-
MAC code and include files are not affected by upgrade.