Variables

Subscripted Variables

Local variables, process-private variables, and global variables can all take subscripts. The subscript conventions for all types of variables are similar:

• A subscript can be a numeric or a string. It can include any characters, including Unicode characters. Valid numeric subscripts include positive and negative numbers, zero, and fractional numbers. The empty string ("") is not a valid subscript.

• Subscript values are case-sensitive.

• A numeric subscript is converted to canonical form. Thus, ^a(7), ^a(007), ^a(7.000), and ^a(7.) are all the same subscript. A string subscript is not converted to canonical form. Thus ^a(“7”), ^a(“007”), ^a(“7.000”), and ^a(“7.”) are different subscripts. The string subscript ^a(“7”) is the same as the numeric subscript ^a(7).

• There is a maximum length for any subscript. Exceeding the maximum subscript length results in a <SUBSCRIPT> error:

  • For a local array, the maximum length of a subscript is 32767 encoded bytes.

  • For a global array, the maximum length of a subscript is 511 encoded bytes.

  Note that in each case, the corresponding number of characters depends on the characters in the subscript and the current locale.

  Also, the longest permitted integer is 309 digits; exceeding this limit results in a <MAXNUMBER> error. Therefore, a numeric subscript longer than 309 characters must be specified as a string.

• The maximum number of subscript levels for a local variable is 255. The maximum number of subscript levels for a global or process-private global is 253. Exceeding the maximum number of subscript levels results in a <SYNTAX> error.

Actual maximums depend on several factors. For further details on global maximums, refer to Global Structure chapter in Using Globals.

Lock name subscripts follow the same conventions as variable subscripts.

Array Variables

An array variable is simply a variable with one or more subscript levels. Subscripts are enclosed in parentheses. Subscript levels are separated by commas. Any variable (with the exception of special variables) can be used as an array, as shown in the following example:

 SET a(1) = "A local variable array"
 SET a(1,1,1) = "Another local variable array"
 SET ^||a(1) = "A process-private global array"
 SET ^a(1) = "A global array"
 SET obj.a(1) = "A multidimensional array property"

For local variables, the maximum number of subscript levels is 255. For global variables, the maximum number of subscript levels depends on the length of the subscript names. For subscript conventions and limits, refer to the Global Structure chapter in Using Globals.

Object Properties

An object property is a value associated with, and stored within, a specific instance of an object. Strictly speaking, an object property is not a variable, but syntactically you can use an object property in exactly the same way as any other local variable.

There are several types of property references: oref.property, ..property, and i%property. The object reference (oref) must be a local variable, not an expression. The property reference can reference a single-value property or a subscripted multidimensional property. There can be chained property references like oref.prop1.prop2.

The following example shows a property reference used as a variable:

  // Create an Address object
  SET address = ##class(Sample.Address).%New()
  // Use the properties of the object
  SET address.City = "Boston"
  WRITE "City: ",address.City,!

There are some limitations for the use of property references as variables. A property of any type cannot be modified using SET $BIT() or SET $LISTBUILD(); a non-multidimensional property cannot be modified using SET $EXTRACT(), SET $LIST(), or SET $PIECE(). $DATA(), $GET(), and $INCREMENT() can only take a property if the property is multidimensional. Properties cannot be used with the MERGE command. These operations can be done within an object method using the instance variable syntax i%PropertyName.

Naming Conventions

Define a local variable using the following naming conventions:

• A local variable name must be a valid identifier. Its first character must be either a letter or the percent (%) character. Variable names starting with the “%” character are known as “percent variables” and have different scoping rules. Only variables that begin with “%Z” or “%z” are available for application code; all other percent variables are reserved for system use according to the rules described in “Rules and Guidelines for Identifiers” in the Orientation Guide for Server-Side Programming. The percent (%) character can only be used as the first character of a local variable name. The other characters of a local variable name may be letters or numbers.

• Any word can be used as a variable name. However, it is strongly recommended that a variable name not be the name of an ObjectScript command or an SQL reserved word.

• Local variable names are case-sensitive. For example: MYVAR, MyVar, and myvar are three different local variables.

• Local variable names may include letter characters above ASCII 255 (Unicode letters).

• Local variable names must be unique for the current process. Other processes may have local variables with the same name. A process-private global or a global may have the same name as a local variable. For example: myvar, ^||myvar, and ^myvar are three different variables.

• Local variable names are limited to 31 characters. You may specify a name longer than 31 characters, but only the first 31 characters are used. Therefore, a local variable name must be unique within its first 31 characters.

• Local variables can take subscripts. By using subscripts, you can define a local variable as an array of values. A subscript can be a number or a character string; it can include Unicode characters.

Scope of Local Variables

In ObjectScript code, all local variables are public, and can thus be accessed by any operation executed by that process in the current context. Access to a local variable value is restricted as follows:

• The NEW command creates a new local variable context. An argumentless NEW creates a new context in which none on the existing local variables are defined. NEW var creates a new context in which the local variable var is not defined. The QUIT command reverts to the prior local variable context.

• Within a procedure block local variables are private by default. A private local variable is only defined within that procedure block.

  Local variables within a procedure block behave as follows:

  • Private variables. A local variable used within a procedure block is a private variable and is only defined within that procedure block, unless it is declared a public variable or it is a % variable. By default, all object methods created with Studio use procedure blocks (the ProcedureBlock class keyword is set within the class definition) and so, by default, all variables created in methods are private variables. You cannot use the NEW command on a private variable in a procedure block.

  • Public variables. A procedure block can explicitly declare a list of local variables as public variables. These variables values are accessible outside the procedure block. This comma-separated list of public variables can include non-existent variables and % variables. You can use the NEW command on a public variable in a procedure block.

    A public variables list for the two local variables var1 and var2 is specified as follows: MyProc(x,y) [var1,var2] PUBLIC { code body }. (Note that the PUBLIC keyword specifies that the procedure is public; it has nothing to do with the public variables list.) Public variables are specified as a comma-separated list. Only unsubscripted local variables can be specified; specifying an unsubscripted variable in the public variables lists makes all of its subscript levels public as well. Only a simple object reference (OREF) can be specified; specifying an OREF in the public variables lists makes all of its object properties public as well. The list of public variables can include undefined variables.

  • % Variables. A local variable whose name starts with “%” is automatically declared a public variable. This makes it possible to define variables that are visible to all code within a process without having to explicitly list these variables as public. Only variables that begin with “%Z” or “%z” are available for application code; all other % variables are reserved for system use according to the rules described in “Rules and Guidelines for Identifiers” in the Orientation Guide for Server-Side Programming. You can use the NEW command on a % variable in a procedure block.

  These mechanisms are described in greater detail in the Procedure Variables section of the “Callable User-defined Code Modules” chapter.

• The XECUTE command defines local variables as public by default. You can explicitly define a local variable as private within the XECUTE command. Refer to XECUTE for more on explicitly defining local variables as either private or public.

You can use the WRITE or ZWRITE command, with no arguments, to list all currently defined local variables. You can use the $QSUBSCRIPT function to return the components (name and subscripts) of a specified local variable, or the $QLENGTH function to return the number of subscript layers. You can use the KILL command to delete local variables.

Object Values

An object value refers to an instance of an in-memory object. You can assign an object value to any local variable:

 SET person = ##class(Sample.Person).%New()
 WRITE person,!

You can refer to the methods and properties of an object using dot syntax:

 SET person.Name = "El Vez"

You can determine if a variable contains an object using the $ISOBJECT function:

 SET str = "A string"
 SET person = ##class(Sample.Person).%New()

 WRITE "Is string an object? ", $IsObject(str),!
 WRITE "Is person an object? ", $IsObject(person),!

You cannot assign an object value to a global. Doing so will result in a runtime error.

Assigning an object value to a variable (or object property) has the side effect of incrementing the object’s internal reference count. When the number of references to an object reaches 0, InterSystems IRIS will automatically destroy the object (invoke its %OnClose() callback method and remove it from memory). For example:

 SET person = ##class(Sample.Person).%New() // one reference to Person
 SET alias = person // two references

 SET person = "" // 1 reference 
 
 SET alias = "" // no references left, object destroyed

Naming Conventions

A process-private global name takes one of the following forms:

^||name 
^|"^"|name 
^["^"]name 
^["^",""]name

These four prefix forms are equivalent, and all four refer to the same process-private global. The first form (^||name) is the most common, and the one recommended for new code. The second, third, and fourth forms are provided for compatibility with existing code that defines globals. They allow you to specify a variable that determines whether to define name as a process-private global or a standard global. This is shown in the following example:

  SET x=1       // toggle storage type
  IF x=1 {
    SET a="^"   // for a process-private global
  }
  ELSE {
    SET a=""    // for a standard global
  }
  SET ^|a|name="a value"

Process-private globals use the following naming conventions:

• A process-private global name must be a valid identifier. Its first character (after the second vertical bar) must be either a letter or the percent (%) character. The percent (%) character can only be used as the first character of a process-private global name. Only percent variables that begin with “%Z” or “%z” are available for application code (such as ^||%zmyppg or ^||%Z123); all other percent variables are reserved for system use according to the rules described in “Rules and Guidelines for Identifiers” in the Orientation Guide for Server-Side Programming.

  The second and subsequent characters of a process-private global name may be letters, numbers, or the period character. A period cannot be used as the first or last character of the name.

• A process-private global name cannot contain Unicode letters (letter characters above ASCII 255). Attempting to include a Unicode letter in a process-private global name results in a <WIDE CHAR> error.

• Process-private global names are case-sensitive.

• A process-private global name must be unique within its process.

• Process-private global names are limited to 31 characters, exclusive of the prefix characters. You may specify a name longer than 31 characters, but only the first 31 characters are used. Therefore, a process-private global name must be unique within its first 31 characters.

• Process-private globals can take subscripts. By using subscripts, you can define a process-private global as an array of values. A subscript can be a number or a character string; it can include Unicode characters. For subscript conventions, limitations on the number of subscript levels, and other information about use of subscripts, refer to Global Structure in Using Globals.

Listing Process-Private Globals

You can use the ^$||GLOBAL() syntax form of ^$GLOBAL() to return information about process-private globals belonging to the current process.

You can use the ^GETPPGINFO routine to display the names of all current process-private globals and their space allocation, in blocks. ^GETPPGINFO does not list the subscripts or values for process-private globals. You can display process-private globals for a specific process by specifying its process Id (pid), or for all processes by specifying the "*" wildcard string. You must be in the %SYS namespace to invoke ^GETPPGINFO.

The following example uses ^GETPPGINFO to list the process-private globals for all current processes:

  SET ^||flintstones(1)="Fred"
  SET ^||flintstones(2)="Wilma"
  NEW $NAMESPACE
  SET $NAMESPACE="%SYS"
  DO ^GETPPGINFO("*")

The ^GETPPGINFO routine takes arguments as follows:

do ^GETPPGINFO("pdf","options","outfile")

These arguments are as follows:

• pdf can be a process Id or the * wildcard.

• options can be a string containing any combination of the following characters:

  • b (return values in bytes)

  • Mnn (list only processes with process-private globals that use nn or more blocks)

    Use M0 to include processes without any process-private globals in the listing.

    Use M1 to exclude processes without any process-private globals from the listing, but include processes having only a global directory block. (This is the default.)

    Use M2 to exclude processes without any process-private globals from the listing, as well as those having only a global directory block.

  • S (suppress screen display; used with outfile)

  • T (display process totals only).

• outfile is the file path for a file in CSV (comma-separated values) format that will be used to receive ^GETPPGINFO output.

The following example writes process-private globals to an output file named ppgout. The S option suppresses screen display; the M500 option limits output to only processes with process-private globals that use 500 or more blocks:

  NEW $NAMESPACE
  SET $NAMESPACE="%SYS"
  DO ^GETPPGINFO("*","SM500","/home/myspace/ppgout")