Skip to main content

Rules and Guidelines for Identifiers

For convenience, this page summarizes the rules for ObjectScript identifiers in all server-side contexts and provides guidelines to avoid name collisions.

Also 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 security entities such as users, roles, and resources, see the relevant section of Authorization Guide.

Namespaces

In a namespace name, the first character must be a letter or a percent sign (%). The remaining characters must be letters, numbers, hyphens, or underscores. The name cannot be longer than 255 characters.

Namespace Names to Avoid

The following namespace names are reserved: %SYS, BIN, BROKER, and DOCUMATIC. Some of these namespaces are described in “System-Supplied Namespaces,” earlier in this book. Others are used internally by InterSystems IRIS.

Databases

In a database name, the first character must be a letter or an underscore. The remaining characters must be letters, numbers, hyphens, or underscores. The name cannot be longer than 30 characters.

Database Names to Avoid

The following database names are reserved: IRISLOCALDATA, IRISSYS, IRISLIB, IRISAUDIT, IRISTEMP.

For information on these databases, see “System-Supplied Databases,” earlier in this book.

Local Variables

For the name of 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 any letter character above ASCII 128.

  • 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 in the InterSystems IRIS Error Reference.

Global Variables

For the name of a global variable, the following rules apply in ObjectScript:

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

  • 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 “IRISSYS Database and Custom Items.”

    In all other databases, InterSystems reserves all global names starting with ^IRIS. and ^%IRIS.

    Also see the following subsection.

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.

To avoid overwriting system globals, do not set, modify, or kill the following globals in any namespace:

  • Globals with names that start with ^%, with the following exceptions:

    • Your own globals with names that start ^%z or ^%Z

    • ^%SYS (you can set nodes as noted in the documentation)

  • ^BfVY. (reserved for use by InterSystems IRIS sharding)

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

  • ^InterSystems.Sequences (restriction applies only to a namespace in which you are using the InterSystems IRIS Hibernate Dialect)

  • ^IRIS.* (reserved for use by InterSystems)

  • ^IRISAuditD

  • ^IS. (reserved for use by InterSystems IRIS sharding)

  • ^ISCDebugLevel (except for setting nodes as noted in the documentation)

  • ^ISCMonitor (except for setting nodes as noted in the documentation)

  • ^ISCSOAP (except for setting nodes as noted in the documentation)

  • ^ISCMethodWhitelist

  • ^mqh (SQL query history)

  • ^mtemp*

  • ^OBJ.GUID (except as noted in the documentation)

  • ^OBJ.DSTIME

  • ^OBJ.JournalT

  • ^oddBIND

  • ^oddCOM

  • ^oddDEF (contains class definitions)

  • ^oddDEP

  • ^oddEXT

  • ^oddEXTR

  • ^oddMAP

  • ^oddMETA

  • ^oddPKG

  • ^oddPROC

  • ^oddPROJECT

  • ^oddSQL

  • ^oddStudioDocument

  • ^oddStudioMenu

  • ^oddTSQL

  • ^oddXML

  • ^rBACKUP

  • ^rINC (contains include files)

  • ^rINCSAVE

  • ^rINDEX

  • ^rINDEXCLASS

  • ^rINDEXEXT

  • ^rINDEXSQL

  • ^rMAC (contains MAC code)

  • ^rMACSAVE

  • ^rMAP

  • ^rOBJ (stores OBJ code)

  • ^ROUTINE (stores routines)

  • ^SPOOL (restriction applies only to a namespace in which you are using InterSystems IRIS spooling; see “Spool Device” in the I/O Device Guide)

  • ^SYS (except for setting nodes as noted in the documentation)

  • ^z* and ^Z* (reserved for use by InterSystems)

Routines 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 IRISSYS Database and Custom Items.

  • 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 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 routine names are reserved for your use. See IRISSYS Database and Custom Items.

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 Terminal starts. See Using the Terminal.

  • 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 in Specialized System Tools and Utilities.

  • ^%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 in Specialized System Tools and Utilities.

  • The ^%ZJREAD routine is intended to contain logic to manipulate journal files if you use the ^JCONVERT routine. See Journaling in the Data Integrity Guide.

Classes

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.

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

  • In any interoperability-enabled namespace, avoid using the following package names: Ens, EnsLib, EnsPortal, or 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, InterSystems recommends that you avoid using any package names that start with Ens (case-sensitive). For more information, see Environmental Considerations in Developing Productions.

  • 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; see the next section.

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

Class Members

For a class member that you create, 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.

Note that SQL reserved words include 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.

IRISSYS Database and Custom Items

You can create items in the IRISSYS database. However, the process of upgrading InterSystems IRIS deletes custom items in IRISSYS unless they follow the conventions below.

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 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 the upgrade process.

An alternative method of making items accessible by all namespaces is to use the %ALL namespace, as described in Mapping Data to All Namespaces.

Next sectionGeneral System Limits
Previous sectionWhat’s That?
FeedbackOpens in a new tab