Defining and Referring to Class Parameters

This topic describes how to define class parameters and how to refer to them programmatically.

Introduction to Class Parameters

A class parameter defines a special constant value available to all objects of a given class. When you create a class definition (or at any point before compilation), you can set the values for its class parameters. By default, the value of each parameter is the null string, but you can specify a non-null value as part of the parameter definition. At compile-time, the value of the parameter is established for all instances of a class. With rare exceptions, this value cannot be altered at runtime.

Class parameters are typically used for the following purposes:

To customize the behavior of the various data type classes (such as providing validation information).
To define user-specific information about a class definition. A class parameter is simply an arbitrary name-value pair; you can use it to store any information you like about a class.
To define a class-specific constant value.
To provide parameterized values for method generator methods to use. A method generator is a special type of method whose implementation is actually a short program that is run at compile-time in order to generate the actual runtime code for the method. Many method generators use class parameters.

Defining Class Parameters

To add a class parameter to a class definition, add an element like one of the following to the class:

Parameter PARAMNAME;

Parameter PARAMNAME as Type;

Parameter PARAMNAME as Type = value;

Parameter PARAMNAME as Type [ Keywords ] = value;

Where

PARAMNAME is the name of the parameter. Note that by convention, parameters in InterSystems IRIS® system classes are nearly all in uppercase; this convention provides an easy way to distinguish parameters from other class members, merely by name. There is no requirement for you to do the same.
Type is a parameter type. See the next section.
value is the value of the parameter. In most cases, this is a literal value such as 100 or "MyValue". For some types, this can be an ObjectScript expression. See the next section.
Keywords represents any parameter keywords. These are optional. For an introduction to keywords, see Compiler Keywords. For parameter keywords; see Parameter Keywords.

Parameter Types and Values

It is not necessary to specify a parameter type. If you do, note that this information is primarily meant for use by the development environment.

The parameter types include BOOLEAN, STRING, and INTEGER. Note that these are not InterSystems IRIS class names. For a complete list, see Parameter Definitions.

Except for the types COSEXPRESSION and CONFIGVALUE (both described in subsections), the compiler ignores the parameter types.

Class Parameter to Be Evaluated at Compile Time (Curly Braces)

You can define a parameter as an ObjectScript expression that it is evaluated at compile time. To do so, specify no type and specify the value in curly braces:

Parameter PARAMNAME = {ObjectScriptExpression};

where PARAMNAME is the parameter being defined and ObjectScriptExpression is the ObjectScript expression that is evaluated at compile time. This expression can use the %classname variable but otherwise cannot refer to the current class or any of its members. The expression can invoke code in other classes, provided that those classes are compiled before this class.

For example:

Parameter COMPILETIME = {$zdatetime($h)};

Class Parameter to Be Evaluated at Runtime (COSEXPRESSION)

You can define a parameter as an ObjectScript expression that it is evaluated at runtime. To do so, specify its type as COSEXPRESSION and specify an ObjectScript expression as the value:

Parameter PARAMNAME As COSEXPRESSION = "ObjectScriptExpression";

where PARAMNAME is the parameter being defined and ObjectScriptExpression is the ObjectScript content that is evaluated at runtime.

An example class parameter definition would be:

Parameter DateParam As COSEXPRESSION = "$H";

Class Parameter to Be Updated at Runtime (CONFIGVALUE)

You can define a parameter so that it can modified outside of the class definition. To do so, specify its type as CONFIGVALUE. In this case, you can modify the parameter via the $SYSTEM.OBJ.UpdateConfigParam() method. For example, the following changes the value of the parameter MYPARM (in the class MyApp.MyClass) so that its new value is 42:

set sc=$system.OBJ.UpdateConfigParam("MyApp.MyClass","MYPARM",42)

Note that $SYSTEM.OBJ.UpdateConfigParam() affects the generated class descriptor as used by any new processes, but does not affect the class definition. If you recompile the class, InterSystems IRIS regenerates the class descriptor, which will now use the value of this parameter as contained in the class definition, thus overwriting the change made via $SYSTEM.OBJ.UpdateConfigParam().

Referring to Parameters of a Class

To refer to a parameter of a class, you can do any of the following:

Within a method of the associated class, use the following expression:
```
..#PARMNAME
```
You can use this expression with the DO and SET commands, or you can use it as part of another expression. The following shows one possibility:
```
 set object.PropName=..#PARMNAME
```
In the next variation, a method in the class checks the value of a parameter and uses that to control subsequent processing:
```
 if ..#PARMNAME=1 { 
   //do something
 } else { 
   //do something else
 }
```
To access a parameter in any class, use the following expression:
```
##class(Package.Class).#PARMNAME
```
where Package.Class is the name of the class and PARMNAME is the name of the parameter.
This syntax accesses the given class parameter and returns its value. You can use this expression with commands such as DO and SET, or you can use it as part of another expression. The following shows an example:
```
 w ##class(%XML.Adaptor).#XMLENABLED
```
displays whether methods generated by the XML adaptor are XML enabledOpens in a new tab, which by default is set to 1.
To access the parameter, where the parameter name is not determined until runtime, use the $PARAMETER function:
```
$PARAMETER(classnameOrOref,parameter)
```
where classnameOrOref is either the fully qualified name of a class or an OREF of an instance of the class, and parameter evaluates to the name of a parameter in the associated class.
For information on OREFs, see Working with Registered Objects.