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.
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().