Skip to main content

Rules and Guidelines for Identifiers

For convenience, this appendix 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 the Caché Security Administration 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, DOCBOOK and DOCUMATIC. Some of these namespaces are described in “System-supplied Namespaces,” earlier in this book. Others are used internally by Caché.

Also, if you use the namespace name SAMPLES, you must take care not to install the InterSystems code samples database, which uses that namespace.

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: CACHE, CACHESYS, CACHELIB, CACHEAUDIT, CACHETEMP, and DOCBOOK.

Also, if you use the database name SAMPLES, you must take care not to install the InterSystems code samples database, which has that name.

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. On Unicode systems, these other characters can include 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 names for local variables:

  • SQLCODE

    Avoid using SQLCODE as the name of a variable in any context where Caché SQL might run. See the “SQLCODE Values and Error Messages” chapter of the Caché Error Reference.

  • zenPage, this, and zenThis

    In Zen classes, avoid using these as names of variables. See the “Zen Special Variables” section in the “Zen Pages” chapter in Developing Zen Applications.

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 CACHESYS database, InterSystems reserves to itself all global names except those starting with ^z, ^Z, ^%z, and ^%Z. See “Custom items in CACHESYS.”

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

    Also see the following subsection.

Global Variable Names to Avoid

When you create a database, Caché 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)

  • ^BP (restriction applies only to a namespace in which you are using Caché MVBasic)

  • ^COMO (restriction applies only to a namespace in which you are using Caché MVBasic)

  • ^CacheAuditD

  • ^CacheMsg, the message dictionary; see the article String Localization and Message Dictionaries.

  • ^CacheTemp and globals whose names start with ^CacheTemp, with one exception:

    • Your own globals with names that start with ^CacheTempUser

  • ^CMQLlog (restriction applies only to a namespace in which you are using Caché MVBasic; you can set or kill this global as noted in the documentation)

  • ^D.1 and ^D.2 (restriction applies only to a namespace in which you are using Caché MVBasic)

  • ^DeepSee.* (restriction applies only to a namespace in which you are using DeepSee)

  • ^DICT.* (restriction applies only to a namespace in which you are using Caché MVBasic)

  • ^ERRORS

  • ^InterSystems.Sequences (restriction applies only to a namespace in which you are using the Caché Hibernate dialect; see “Using the Caché Hibernate Dialect” in Using Caché with JDBC.)

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

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

  • ^mqh (SQL query history)

  • ^mtemp*

  • ^MV.* (restriction applies only to a namespace in which you are using Caché MVBasic)

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

  • ^OBJ.DSTIME

  • ^OBJ.JournalT

  • ^oddBIND

  • ^oddCOM

  • ^oddDEF (contains class definitions)

  • ^oddDEP

  • ^oddEXT

  • ^oddEXTR

  • ^oddFMD (restriction applies only to a namespace in which you are the FileMan Mapping Utility)

  • ^oddMAP

  • ^oddMETA

  • ^oddPKG

  • ^oddPROC

  • ^oddPROJECT

  • ^oddSQL

  • ^oddStudioDocument

  • ^oddStudioMenu

  • ^oddTSQL

  • ^oddXML

  • ^PH (restriction applies only to a namespace in which you are using Caché MVBasic)

  • ^rBACKUP

  • ^rINC (contains include files)

  • ^rINCSAVE

  • ^rINDEX

  • ^rINDEXCLASS

  • ^rINDEXEXT

  • ^rINDEXSQL

  • ^rMAC (contains MAC code)

  • ^rMACSAVE

  • ^rMAP

  • ^rOBJ (stores OBJ code)

  • ^ROUTINE (stores routines)

  • ^SAVEDLISTS (restriction applies only to a namespace in which you are using Caché MVBasic)

  • ^SPOOL (restriction applies only to a namespace in which you are using Caché spooling; see “Spool Device” in the Caché 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 “Custom items in CACHESYS.”

  • The remaining characters must be letters or numbers (with one exception; see the next bullet). On Unicode systems, 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 the subsection.

Reserved Routine Names for Your Use

Caché 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, Caché provides templates. See the Caché Security Administration Guide.

  • The ^ZMIRROR routine is intended to contain code to customize failover behavior when you use Caché Mirroring. See the Caché 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 Caché 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 Caché Specialized System Tools and Utilities.

  • The ^%ZJREAD routine is intended to contain logic to manipulate journal files if you use the ^JCONVERT routine. See the chapter “Journaling” in the Caché 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.

    On Unicode systems, these other characters can include 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.

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

For a list of the SQL reserved words, see “Reserved Words” in the Caché SQL Reference.

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. On Unicode systems, these other characters can include 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 indices 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.

As of release 2012.2, 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” in the Caché SQL Reference. Notice that this list includes many items with names beginning with %, such as %UPPER and %CONTAINS. Such items are InterSystems extensions to SQL, and additional extensions may be added in future releases.

Custom Items in CACHESYS

You can create items in the CACHESYS database. When you install a Caché upgrade, this database is upgraded. During this upgrade, some items are 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 routine database and default global database are both CACHESYS. 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 CACHESYS.

MAC code and include files are not affected by upgrade.

FeedbackOpens in a new tab