Skip to main content

Defining and Using Literal Properties

You can define literal properties in any object class. A literal property holds a literal value and is based on a data type class. This chapter describes how to define and use such properties.

Where noted, some topics also apply to properties of other kinds.

Also see the chapters “Working with Collections,” “Working with Streams,” “Defining and Using Object-Valued Properties,” “Defining and Using Relationships”, and “Using and Overriding Property Methods.”

Defining Literal Properties

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

Property PropName as Classname;
Property PropName as Classname [ Keywords ] ;
Property PropName as Classname(PARAM1=value,PARAM2=value) [ Keywords ] ;
Property PropName as Classname(PARAM1=value,PARAM2=value) ;

Where:

  • PropName is the name of the property.

  • Classname is the class on which this property is based. If you omit this, Classname is assumed to be %StringOpens in a new tab. To define this property as a literal property, either omit Classname or specify Classname as the name of a data type class; see “Common Data Type Classes” later in this chapter. You could also use a custom data type class.

  • Keywords represents any property keywords. See “Compiler Keywords,” earlier in this book. Later sections of this chapter discuss additional keywords.

  • PARAM1, PARAM2, and so on are property parameters. The available parameter depend on the class used by the property. Later sections of this chapter lists the most common property parameters.

Notice that the property parameters, if included, are enclosed in parentheses and precede any property keywords. The property keywords, if included, are enclosed in square brackets.

Examples

For example, a class can define a Count property using the %IntegerOpens in a new tab data type class:

Property Count As %Integer;

Because %IntegerOpens in a new tab is a data type class, Count is a data type property.

You can use data type parameters to place constraints on the allowed values of data type properties. For example, for a property of type %IntegerOpens in a new tab, you can specify the MAXVAL parameter:

Property Count As %Integer(MAXVAL = 100);

To set a data type property value equal to the empty string, use code of the form:

 Set object.Property = $C(0)

Every property has a collation type, which determines how values are ordered (such as whether capitalization has effects or not). The default collation type for strings is SQLUPPER. For more details on collations, see “Data Collation” in the chapter “InterSystems IRIS® SQL Basics” in Using InterSystems SQL.

Defining an Initial Expression for a Property

By default, when a new object is created, each property equals null. You can specify an ObjectScript expression to use as the initial value for a given property instead. The expression is evaluated when the object is created.

To specify an initial expression for a property, include the InitialExpression keyword in the property definition:

Property PropName as Classname [ InitialExpression=expression ] ;

Where expression is an ObjectScript expression (note that you cannot use any other language for this expression). For details, see InitialExpression in the Class Definition Reference.

Defining a Property As Required

This option applies only to properties in persistent classes. (Note that this option applies to any kind of property, not just literal ones.)

By default, when a new object is saved, InterSystems IRIS does not require it to have non-null values for its properties. You can define a property so that a non-null value is required. To do so, include the Required keyword in the property definition:

Property PropName as Classname [ Required ] ;

Then, if you attempt to save an object that has a null value for the property, InterSystems IRIS issues the following error:

ERROR #5659: Property required

The Required keyword also affects how you can insert or modify data for this class via SQL access. Specifically, an error occurs if the value is missing when you attempt to insert or update a record.

Defining a Computed Property

In InterSystems IRIS, you can define computed properties, whose values are computed via ObjectScript, possibly based on other properties. The generic phrase computed properties (or computed fields) includes both of the following variations:

  • Always computed — The value of this property is calculated when it is accessed. It is not stored in the database unless you defined an index, in which case that index is stored.

  • Triggered computed — The value of this property is recalculated when triggered (details given below).

    If the property is defined in a persistent class, its value is stored in the database.

In both cases, the recalculation is performed whether you use object access or an SQL query.

There are five property keywords (SqlComputed, SqlComputeCode, SqlComputeOnChange, Transient, Calculated) that control if and how a property is computed. Instead of specifying SqlComputeCode, you can write compute code in a PropertyComputation method, where Property is the name of the computed property. For more details, see Computed Values.

The following table summarizes the possibilities:

How to Tell if a Property Is Computed
SqlComputed Keyword Calculated Keyword Transient Keyword Compute Type of Property
True (and SqlCompute Code keyword or PropertyComputation method is defined) True True Always computed
False
False True
False Trigger computed (SqlComputeOnChange can also be specified in this case)
False True True Not computed
 
 
 
False
False True
False

To define a computed property, do the following:

  • Include the SqlComputed keyword in the property definition. (That is, specify the SqlComputed keyword as true.)

  • Include the SqlComputeCode keyword in the property definition. For the value of this keyword, specify (in curly braces) a line of ObjectScript code that sets the value of the property, according to rules given in SqlComputeCode. For example:

    Class Sample.Population Extends %Persistent
    {
    Property FirstName As %String;
    Property LastName As %String;
    Property FullName As %String [ SqlComputeCode = {set {*}={FirstName}_" "_{LastName}}, SqlComputed ];
    // ...
    
    }
    

    Alternatively, specify a PropertyComputation method using ObjectScript or another language, such as Python, to set the value of the property. For example:

    Class Sample.Population Extends %Persistent
    {
    Property FirstName As %String;
    Property LastName As %String;
    Property FullName As %String [ SqlComputed ];
    // ...
    
    ClassMethod FullNameComputation(cols As %Library.PropertyHelper) As %String
    {
        return cols.getfield("FirstName")_" "_cols.getfield("LastName")
    }
    // ...
    }
    
    Class Sample.Population Extends %Persistent
    {
    Property FirstName As %String;
    Property LastName As %String;
    Property FullName As %String [ SqlComputed ];
    // ...
    
    ClassMethod FullNameComputation(cols As %Library.PropertyHelper) As %String [ Language = python ]
    {
        return cols.getfield("FirstName") + " " + cols.getfield("LastName")
    }
    // ...
    }
    
  • If you want to make the property always computed, specify the Calculated keyword as true in the property definition.

    Or, if you want to make the property triggered computed, do not include the Calculated and Transient keywords in the property definition. (That is, make sure both keywords are false.)

  • If the property is triggered computed, optionally specify SqlComputeOnChange.

    This keyword can specify one or more properties. When any of these properties change in value, the triggered property is recomputed. Note that you must use the property names rather than the names given by SqlFieldName, which is discussed later in this chapter). For example (with artificial line breaks):

    Property messageId As %Integer [ 
    SqlComputeCode = { set {*}=$Select({Status}="":0,1:$List($List($Extract({Status},3,$Length({Status}))))) }, 
    SqlComputed, SqlComputeOnChange = Status ];

    For another example (with artificial line breaks):

    Property Test2 As %String [ SqlComputeCode = { set {*}={Refprop1}_{Refprop2}}, SqlComputed, 
    SqlComputeOnChange = (Refprop1, Refprop2) ];

    The value of SqlComputeOnChange can also include the values %%INSERT or %%UPDATE; for details, see SqlComputeOnChange.

If you intend to index this field, use deterministic codeOpens in a new tab, rather than nondeterministic code. InterSystems IRIS cannot maintain an index on the results of nondeterministic code because it is not possible to reliably remove stale index key values. (Deterministic code returns the same value every time when passed the same arguments. So for example, code that returns $h is nondeterministic, because $h is modified outside of the control of the function.)

Also see the Calculated keyword in the Class Definition Reference. And see “Controlling the SQL Projection of Computed Properties,” later in this chapter.

Defining a Multidimensional Property

You can define a property to be multidimensional, which means that you intend the property to act as a multidimensional array. To do so, include the MultiDimensional keyword in the property definition:

Property PropName as Classname [ MultiDimensional ] ;

This property is different from other properties as follows:

  • InterSystems IRIS does not provide property methods for it (see “Using and Overriding Property Methods,” later in this book).

  • It is ignored when the object is validated or saved.

  • It is not saved to disk, unless your application includes code to save it specifically.

  • It cannot be exposed to clients such as Java.

  • It cannot be stored in or exposed through SQL tables.

Multidimensional properties are rare but provide a useful way to temporarily contain information about the state of an object.

Also see “Specifying Values for a Multidimensional Property,” later in this chapter.

Common Data Type Classes

InterSystems IRIS provides a large number of data type classes. Of these, the classes in most common use are as follows:

Common Data Type Classes
Class Name Holds Notes
%BigIntOpens in a new tab A 64–bit integer This class is similar to %IntegerOpens in a new tab except for its OdbcType and ClientDataType.
%BinaryOpens in a new tab Binary data The actual binary data is sent to and from the client without any Unicode (or other) translations.
%BooleanOpens in a new tab A boolean value The possible logical values are 0 (false) and 1 (true).
%CharOpens in a new tab A fixed length character field  
%CounterOpens in a new tab An integer, meant for use as a unique counter Any property whose type class is %CounterOpens in a new tab will be assigned a value when a new object is saved or a new record is inserted via SQL, if no value is specified for that property. For details, see %CounterOpens in a new tab in the InterSystems Class Reference.
%CurrencyOpens in a new tab A currency value This class is defined only for migrating from Sybase or SQL Server to InterSystems IRIS.
%DateOpens in a new tab A date The logical value is in InterSystems IRIS $HOROLOG format.
%DateTimeOpens in a new tab A date and time This class is used mainly for T-SQL migrations and maps datetime/smalldatetime behavior to the %TimeStampOpens in a new tab datatype. In this class, the DisplayToLogical() and OdbcToLogical() methods provide logic to handle imprecise datetime values that are supported by T-SQL applications.
%DecimalOpens in a new tab A fixed point number The logical value is a decimal format number. See “Numeric Computing in InterSystems Applications” in the Orientation Guide for Server-Side Programming.
%DoubleOpens in a new tab An IEEE floating-point number The logical value is an IEEE floating-point number. See “Numeric Computing in InterSystems Applications” in the Orientation Guide for Server-Side Programming.
%EnumStringOpens in a new tab A string This is a specialized subclass of %StringOpens in a new tab that allows you to define an enumerated set of possible values (using the DISPLAYLIST and VALUELIST parameters). Unlike %StringOpens in a new tab, the display values for this property are used when columns of this type are queried via ODBC.
%ExactStringOpens in a new tab A string A subclass of %StringOpens in a new tab with the EXACT default collation.
%IntegerOpens in a new tab An integer  
%ListOpens in a new tab Data in $List format The logical value is data in $List format.
%ListOfBinaryOpens in a new tab Data in $List format, with each list item as binary data The logical value is data in $List format.
%NameOpens in a new tab A name in the form “Lastname,Firstname” The %NameOpens in a new tab data type has special indexing support when used in conjunction with the %Storage.Persistent class. For details, see %NameOpens in a new tab in the InterSystems Class Reference.
%NumericOpens in a new tab A fixed-point number  
%PosixTimeOpens in a new tab A value for a time and date The logical value of this data type is the number of seconds since (or before) January 1, 1970 00:00:00, encoded as a 64-bit integer. %PosixTimeOpens in a new tab uses less disk space and memory than %TimeStampOpens in a new tab data type, and is better for performance than %TimeStampOpens in a new tab.
%SmallIntOpens in a new tab A small integer value This class is the same as %IntegerOpens in a new tab except for its OdbcType.
%StatusOpens in a new tab An error status code Many methods in the InterSystems IRIS Class Library return values of type %StatusOpens in a new tab. For information on working with these values, see %StatusOpens in a new tab in the InterSystems Class Reference.
%StringOpens in a new tab A string  
%TimeOpens in a new tab A time value The logical value is the number of seconds past midnight.
%TimeStampOpens in a new tab A value for a time and date The logical value of the %TimeStampOpens in a new tab data type is in YYYY-MM-DD HH:MM:SS.nnnnnnnnn format. Note that if h is a date/time value in $H format, then you can use the $ZDATETIME as follows to obtain a valid logical value for a %TimeStampOpens in a new tab property: $ZDATETIME(h,3)
Also see the comments for %PosixTimeOpens in a new tab.
%TinyIntOpens in a new tab A very small integer value This class is the same as %IntegerOpens in a new tab except for its OdbcType and its maximum and minimum values.

There are many additional data type classes, intended for specialized uses; most of these types are subclasses of the classes listed here. See the InterSystems Class Reference for details.

Each data type class specifies several keywords that control how that data type is used in InterSystems SQL and how the data type is projected to client systems:

  • SqlCategory — Specifies the SQL category to use for the data type when the InterSystems SQL engine performs operations upon it.

  • OdbcType — Specifies the ODBC type used when the data type is accessed via ODBC.

  • ClientDataType — Specifies the type used when the data type is accessed via client applications.

Therefore, when you choose a data type class, you should choose a class that has the appropriate client projection, if applicable, for your needs. Use the following subsections to help choose a suitable data type class. If there is no suitable class, you can create your own data type class, as described in the chapter “Defining Data Type Classes.”

Data Type Classes Grouped by SqlCategory

For a data type class, the SqlCategory class keyword specifies the SQL category that InterSystems SQL uses when operating on values of properties of that type. Operations controlled by SqlCategory include comparison operations (such as greater than, less than, or equal to); other operations may also use it. The following table shows the SqlCategory values of the data types listed in this chapter.

Data Type Classes Grouped by SqlCategory
Value InterSystems IRIS Data Type
DATE %DateOpens in a new tab
DOUBLE %DoubleOpens in a new tab
INTEGER %BigIntOpens in a new tab, %BooleanOpens in a new tab, %CounterOpens in a new tab, %IntegerOpens in a new tab, %SmallIntOpens in a new tab, %TinyIntOpens in a new tab
NAME %NameOpens in a new tab
NUMERIC %CurrencyOpens in a new tab, %DecimalOpens in a new tab, %NumericOpens in a new tab
POSIXTS %PosixTimeOpens in a new tab
STRING %BinaryOpens in a new tab, %CharOpens in a new tab, %EnumStringOpens in a new tab, %ExactStringOpens in a new tab, %ListOpens in a new tab, %ListOfBinaryOpens in a new tab, %StatusOpens in a new tab, %StringOpens in a new tab
TIME %TimeOpens in a new tab
TIMESTAMP %DateTimeOpens in a new tab, %TimeStampOpens in a new tab

For further information on how literal properties are projected to SQL types, see “Data Types” in the InterSystems SQL Reference.

Data Type Classes Grouped by OdbcType

For a data type class, the OdbcType class keyword controls how InterSystems IRIS translates logical data values to and from values used by the InterSystems SQL ODBC interface. The following table shows the OdbcType values of the data types listed in this chapter.

Data Type Classes Grouped by OdbcType
Value InterSystems IRIS Data Type
BIGINT %BigIntOpens in a new tab
BIT %BooleanOpens in a new tab
DATE %DateOpens in a new tab
DOUBLE %DoubleOpens in a new tab
INTEGER %CounterOpens in a new tab, %IntegerOpens in a new tab
NUMERIC %CurrencyOpens in a new tab, %DecimalOpens in a new tab, %NumericOpens in a new tab
TIME %TimeOpens in a new tab
TIMESTAMP %DateTimeOpens in a new tab, %PosixTimeOpens in a new tab, %TimeStampOpens in a new tab
VARBINARY %BinaryOpens in a new tab
VARCHAR %CharOpens in a new tab, %EnumStringOpens in a new tab, %ExactStringOpens in a new tab, %ListOpens in a new tab, %ListOfBinaryOpens in a new tab, %NameOpens in a new tab, %StatusOpens in a new tab, %StringOpens in a new tab

Data Type Classes Grouped by ClientDataType

For a data type class, the ClientDataType class keyword controls how InterSystems IRIS projects a property (of that type) to Java or Active X. The following table show the ClientDataType values of the data types listed in this chapter.

Data Type Classes Grouped by ClientDataType
Value Used for
BIGINT %BigIntOpens in a new tab
BINARY %BinaryOpens in a new tab (or any property requiring that there is no Unicode conversion of data)
CURRENCY %CurrencyOpens in a new tab
DATE %DateOpens in a new tab
DOUBLE %DoubleOpens in a new tab
DECIMAL %DecimalOpens in a new tab
INTEGER %CounterOpens in a new tab, %IntegerOpens in a new tab, %SmallIntOpens in a new tab, %TinyIntOpens in a new tab
LIST %ListOpens in a new tab, %ListOfBinaryOpens in a new tab
NUMERIC %NumericOpens in a new tab
TIME %TimeOpens in a new tab
TIMESTAMP %DateTimeOpens in a new tab, %PosixTimeOpens in a new tab, %TimeStampOpens in a new tab
VARCHAR %CharOpens in a new tab, %EnumStringOpens in a new tab, %ExactStringOpens in a new tab, %NameOpens in a new tab, %StringOpens in a new tab

Core Property Parameters

Depending on the property, you can specify parameters of that property, to affect its behavior. For example, parameters can specify minimum and maximum values, formatting for use in display, collation, delimiters for use in specific scenarios, and so on. You can specify parameters either in the Inspector or by directly typing into the class definition. The following shows an example:

Property MyProperty as MyType (MYPARAMETER="some value");

Some parameters are available for all properties, of any type. These parameters are as follows:

  • CALCSELECTIVITY — Controls whether the Tune Table facility calculates the selectivity for a property. Usually it is best to leave this parameter as the default (1). For details, see “Tune Table” in the SQL Optimization Guide.

  • CAPTION — Caption to use for this property in client applications.

  • EXTERNALSQLNAME — Used in linked tables, this parameter specifies the name of the field in the external table to which this property is linked. The Link Table wizard specifies this parameter for each property when it generates a class. The name of the SQL field on the remote database may need to differ from property name on the InterSystems IRIS server for various reason, such as because the remote database field name is a reserved word in InterSystems IRIS. For information on linked tables, see “The Link Table Wizard” in Using the InterSystems IRIS SQL Gateway.

    Note that the property parameter EXTERNALSQLNAME has a different purpose than the SQLFieldName compiler keyword, and these items can have different values. SQLFieldName specifies the projected SQL field name in the InterSystems IRIS database, and EXTERNALSQLNAME is the field name in the remote database.

  • EXTERNALSQLTYPE — Used in linked tables, this parameter specifies the SQL type of the field in the external table to which this property is linked. The Link Table wizard specifies this parameter for each property when it generates a class. See EXTERNALSQLNAME.

  • JAVATYPE — The Java data type to which this property is projected.

Most property parameters are defined in data type classes and thus are class-specific; see the next section.

Class-Specific Property Parameters

The previous section lists the parameters that are available for all properties. The other available parameters depend on the class used by the property. The following table lists the parameters supported by the data type classes listed in this chapter. The parameters are grouped into three columns: 1) parameters that are found in many data type classes or that are otherwise commonly encountered, 2) parameters that have meaning only in XML and SOAP contexts, and 3) parameters that occur in only a few data type classes and that are rarely encountered.

Supported Parameters for System Data Type Classes
Data Type Class Common Parameters Parameters for XML and SOAP Less Common Parameters
%BigIntOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST XSDTYPE  
%BinaryOpens in a new tab MAXLEN, MINLEN CANONICALXML, MTOM, XSDTYPE  
%BooleanOpens in a new tab   XSDTYPE  
%CharOpens in a new tab COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST XMLLISTPARAMETER, XSDTYPE  
%CounterOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST XSDTYPE  
%CurrencyOpens in a new tab* DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST XSDTYPE  
%DateOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST XSDTYPE  
%DateTimeOpens in a new tab DISPLAYLIST, MAXVAL, MINVAL, VALUELIST XMLDEFAULTVALUE, XMLTIMEZONE, XSDTYPE DATEFORMAT
%DecimalOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST XSDTYPE  
%DoubleOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST XSDTYPE  
%EnumStringOpens in a new tab COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST XSDTYPE  
%ExactStringOpens in a new tab COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST XSDLISTPARAMETER, XSDTYPE  
%IntegerOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST XSDTYPE STRICT
%ListOpens in a new tab ODBCDELIMITER XSDTYPE  
%ListOfBinaryOpens in a new tab ODBCDELIMITER XSDTYPE  
%NameOpens in a new tab COLLATION,MAXLEN XSDTYPE INDEXSUBSCRIPTS
%NumericOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST XSDTYPE  
%PosixTimeOpens in a new tab MAXVAL, MINVAL XMLDEFAULTVALUE, XMLTIMEZONE, XSDTYPE DATEFORMAT, INDEXNULLMARKER
%SmallIntOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST XSDTYPE  
%StatusOpens in a new tab   XSDTYPE  
%StringOpens in a new tab COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST XMLLISTPARAMETER, XSDTYPE  
%TimeOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST XMLTIMEZONE, XSDTYPE PRECISION
%TimeStampOpens in a new tab DISPLAYLIST, MAXVAL, MINVAL, VALUELIST XMLDEFAULTVALUE, XMLTIMEZONE, XSDTYPE  
%TinyIntOpens in a new tab DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST XSDTYPE  

*This special-purpose class is only for use in migrations to InterSystems IRIS.

Note:

The term constraint refers to any keyword that applies a constraint on a property value. For example, MAXVAL, MINVAL, DISPLAYLIST, VALUELIST, and PATTERN are all constraints.

Common Parameters

The common parameters from the preceding table are as follows:

  • COLLATION — Specifies the manner in which property values are transformed for indexing.

    The allowable values for collation are discussed in “SQL Introduction” in Using InterSystems SQL.

  • CONTENT — Specifies the contents of the string, when the string is used in a context where it might be interpreted as XML or HTML. Specify "STRING" (the default), "ESCAPE", or "MIXED".

    For details, see Projecting Objects to XML.

  • DISPLAYLIST — Used in conjunction with the VALUELIST parameter for enumerated (multiple-choice) properties. For more information, see “Defining Enumerated Properties

  • ESCAPE — Specifies the type of escaping to be done, if the string is used in certain contexts. Use either "XML" (the default) or "HTML".

    By default, the less than, greater than, and ampersand characters are interpreted as < > and & respectively. For further details on "XML", see Projecting Objects to XML.

  • FORMAT — Specifies the format for the display value. For the value of FORMAT, use a format string as specified in the format argument of the $FNUMBER function. For properties of type %NumericOpens in a new tab or %DecimalOpens in a new tab, you can also use the option "AUTO", which suppresses any trailing zeroes.

  • MAXLEN — Specifies the maximum number of characters the string can contain. The default is 50. As with many other parameters, this parameter affects how InterSystems IRIS validates data. Note that it also affects how the field is projected to xDBC clients.

  • MAXVAL — Specifies the maximum allowed logical value for the data type.

  • MINLEN — Specifies the minimum number of characters the string can contain.

  • MINVAL — Specifies the minimum allowed logical value for the data type.

  • ODBCDELIMITER — Specifies the delimiter character used to construct a %List value when it is projected via ODBC.

  • PATTERN — Specifies a pattern that the string must match. The value of PATTERN must be a valid InterSystems IRIS pattern-matching expression. For an overview of pattern matching, see the “Pattern Matching” section in the “Operators” chapter of Using ObjectScript.

  • SCALE — Specifies the number of digits following the decimal point.

  • TRUNCATE — Specifies whether to truncate the string to MAXLEN characters, where 1 is TRUE and 0 is FALSE. This parameter is used by the Normalize() and IsValid() methods but is not used by xDBC clients.

  • VALUELIST — Used for enumerated (multiple-choice) properties. For more information, see “Defining Enumerated Properties

Parameters for XML and SOAP

For information on parameters in the column “Parameters for XML and SOAP,” see Projecting Objects to XML. Also see Creating Web Services and Web Clients.

Less Common Parameters

The less common parameters in the preceding table are as follows:

  • STRICT (for %IntegerOpens in a new tab) requires that value be an integer. By default, if a property is of type %IntegerOpens in a new tab, and you specify a non-integer numeric value, InterSystems IRIS converts the value to an integer. If STRICT is 1 for a property, in such a case, InterSystems IRIS does not convert the value; instead validation fails.

  • DATEFORMAT.

    • For %DateTimeOpens in a new tab, this parameter specifies the order of the date parts when a numeric date format is specified for the display or ODBC input value. Valid parameters are mdy, dmy, ymd, ydm, myd, and dym. The default DATEFORMAT is mdy.

    • For %PosixTimeOpens in a new tab, this parameter specifies the format for the display value. For allowed values, see the fformat parameter of the $zdatetime and $zdatetimeh functions.

  • PRECISION (for %TimeOpens in a new tab) specifies the number of decimal places to retain. If the value is "" (the default), the system retains the number of decimal places that are provided in the source value. If the value is 0, InterSystems IRIS rounds the provided value to the nearest second.

  • INDEXNULLMARKER (only for %PosixTimeOpens in a new tab) declares the default null marker value to use in index subscripts for properties of type %PosixTimeOpens in a new tab. The default is –1E19. See “Indexing a NULL” in the chapter “Defining and Building Indices” in SQL Optimization Guide.

  • INDEXSUBSCRIPTS (for %NameOpens in a new tab) specifies the number of subscripts used by the property in indices, using a comma as a delimiter in the property value; the %Storage.Persistent class uses this number. A value of 2 specifies that the first comma piece of the property value is stored as the first subscript and the second comma piece of the property value is stored as the second subscript.

Defining Enumerated Properties

Many properties support the parameters VALUELIST and DISPLAYLIST. You use these to define enumerated properties.

To specify a list of valid values for a property, use its VALUELIST parameter. The form of VALUELIST is a delimiter-separated list of logical values, where the delimiter is the first character. For instance:

Property Color As %String(VALUELIST = ",red,green,blue");

In this example, VALUELIST specifies that valid possible values are “red”, “green”, and “blue”, with a comma as its delimiter. Similarly,

Property Color As %String(VALUELIST = " red green blue");

specifies the same list, but with a space as its delimiter.

The property is restricted to values in the list, and the data type validation code simply checks to see if the value is in the list. If no list is present, there are no special restrictions on values.

DISPLAYLIST is an additional list that, if present, represents the corresponding display values to be returned by the LogicalToDisplay() method of the property.

For an example that shows how to obtain the display values, see the section “Using Property Methods,” later in this chapter.

Specifying Values for Literal Properties

To specify a value for a literal property, use the SET command, an OREF, and dot syntax as follows:

 SET oref.MyProp=value

Where oref is an OREF, MyProp is a property of the corresponding object, and value is an ObjectScript expression that evaluates to a literal value. For example:

 SET patient.LastName="Muggles"
 SET patient.HomeAddress.City="Carver"
 SET mrn=##class(MyApp.MyClass).GetNewMRN()
 set patient.MRN=mrn

The literal value must be a valid logical value for the property type. For example, use 1 or 0 for a property based on %BooleanOpens in a new tab. For another example, for an enumerated property, the value must be one of the items specified by the VALUELIST parameter.

Specifying Values for a Multidimensional Property

For a multidimensional property, you can specify values for any subscripts of the property. For example:

 set oref.MyStateProp("temp1")=value1
 set oref.MyStateProp("temp2")=value2
 set oref.MyStateProp("temp3")=value3

Multidimensional properties are useful for holding temporary information for use by the object. These properties are not saved to disk.

Using Property Methods

Each property adds a set of generated class methods to the class. These methods include propnameIsValid(), propnameLogicalToDisplay(), propnameDisplayToLogical(), propnameLogicalToODBC(), propnameODBCToLogical(), and others, where propname is the property name. Some of these methods are inherited from the %Property class and others are inherited from the data type class on which the property is based. For details and a list of the methods, see the chapter “Defining Data Type Classes.”

InterSystems IRIS uses these methods internally, and you can call them directly as well. In each case, the argument is a property value. For example, suppose that Sample.Person had a property named Gender with logical values M and F (and display values Male and Female). You could display the logical and display values for this property for a given record, as follows;

MYNAMESPACE>set p=##class(Sample.Person).%OpenId(1)
 
MYNAMESPACE>w p.Gender
M
MYNAMESPACE>w ##class(Sample.Person).GenderLogicalToDisplay(p.Gender)
Male

Controlling the SQL Projection of Literal Properties

A persistent class is projected as an SQL table, as described earlier in this book. For that class, all properties are projected to SQL, aside from the following exceptions:

This section discusses the details for literal properties.

Specifying the Field Names

By default, a property (if projected to SQL) is projected as an SQL field with the same name as the property. To specify a different field name, use the property keyword SqlFieldName. (You may want to use this keyword if the property name is an SQL reserved word). For instance, if there is a %StringOpens in a new tab property called “Select,” you could define its projected name with the following syntax:

Property Select As %String [ SqlFieldName = SelectField ];
Note:

If you do use a property name that is an SQL reserved word, you can also escape the corresponding field name with double quotes when using it in a SQL statement, for example:

SELECT ID, Name, "Select" FROM SQLUser.Person

Specifying the Column Numbers

The system automatically assigns a unique column number for each field. To control column number assignments, specify the property keyword SqlColumnNumber, as in the following example:

Property RGBValue As %String [ SqlColumnNumber = 3 ];

The value you specify for SqlColumnNumber must be an integer greater than 1. If you use the SqlColumnNumber keyword without an argument, InterSystems IRIS assigns a column number that is not preserved and that has no permanent position in the table.

If any property has an SQL column number specified, then InterSystems IRIS assigns column numbers for the other properties. The starting value for the assigned column numbers is the number following the highest SQL column number specified.

The value of the SqlColumnNumber keyword is inherited.

Effect of the Data Type Class and Property Parameters

The data type class used by a given property has an effect on the SQL projection. Specifically, the SQL category of the data type (defined with the SqlCategory keyword) control how the property is projected. Where applicable, the property parameters also have an effect:

For example, consider the following property definition:

Property Name As %String(MAXLEN = 30);

This property is projected as a string field with a maximum length of 30 characters.

Controlling the SQL Projection of Computed Properties

In InterSystems IRIS, you can define computed properties, whose values are computed via ObjectScript or Python, possibly based on other properties; for details, see “Defining Computed Properties,” earlier in this chapter. The following table summarizes the possibilities and indicates which variations are projected to SQL:

SqlComputed Keyword Calculated Keyword Transient Keyword Compute Type and Projection of Property
True (and SqlCompute Code keyword or PropertyComputation method is defined) True True Property is always computed and has an SQL projection*
False
False True
False Property is triggered computed and has an SQL projection*
False True True Property is not computed and has no SQL projection
False
True
False
False True
False
True
False Property is not computed but does have an SQL projection (default)*

*This table assumes that the property does not use other keywords that would prevent it from having an SQL projection. For example, it assumes that the property is not private.

FeedbackOpens in a new tab