Using Caché Objects
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. It discusses the following topics:
Where noted, some topics also apply to properties of other kinds.
When viewing this book online, use the
preface of this book to quickly find other topics.
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) ;
-
-
-
-
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.
Property Count As %Integer;
You can use data type parameters to place constraints on the allowed values of data type properties. For example, for a property of type
%Integer, 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)
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 ] ;
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, Caché 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, Caché 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.
In Caché, 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 never stored in the database.
-
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.
To define a computed property, do the following:
-
Include the
SqlComputed keyword in the property definition. (That is, specify the
SqlComputed keyword as true.)
-
Property FullName As %String [ SqlComputeCode = {set {*}={FirstName}_" "_{LastName}}, SqlComputed ];
-
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.)
-
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) ];
If you intend to index this field, use
deterministic code, rather than nondeterministic code. Caché 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.)
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:
-
-
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 through ActiveX or 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.
Caché 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 |
%BigInt |
A 64bit integer |
This class is similar to %Integer except for its OdbcType and ClientDataType. |
%Binary |
Binary data |
The actual binary data is sent to and from the client without any Unicode (or other) translations. |
%Boolean |
A boolean value |
The possible logical values are 0 (false) and 1 (true). |
%Char |
A fixed length character field |
|
%Counter |
An integer, meant for use as a unique counter |
Any property whose type class is %Counter 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 %Counter in the InterSystems Class Reference. |
%Currency |
A currency value |
This class is defined only for migrating from Sybase or SQL Server to Caché. |
%Date |
A date |
The logical value is in Caché $HOROLOG format. |
%DateTime |
A date and time |
This class is used mainly for T-SQL migrations and maps datetime/smalldatetime behavior to the %TimeStamp datatype. In this class, the DisplayToLogical() and OdbcToLogical() methods provide logic to handle imprecise datetime values that are supported by T-SQL applications. |
%Decimal |
A fixed point number |
The logical value is a decimal format number. See Numeric Computing in InterSystems Applications in the Caché Programming Orientation Guide. |
%Double |
An IEEE floating-point number |
The logical value is an IEEE floating-point number. See Numeric Computing in InterSystems Applications in the Caché Programming Orientation Guide. |
%EnumString |
A string |
This is a specialized subclass of %String that allows you to define an enumerated set of possible values (using the DISPLAYLIST and VALUELIST parameters). Unlike %String, the display values for this property are used when columns of this type are queried via ODBC. |
%ExactString |
A string |
A subclass of %String with the EXACT default collation. |
%FilemanDate |
A date in FileMan format |
This class is defined for use with FileMan. See Converting FileMan Files into Caché Classes in Caché Specialized System Tools and Utilities. |
%FilemanTimeStamp |
A time stamp in FileMan format |
This class is defined for use with FileMan. See Converting FileMan Files into Caché Classes in Caché Specialized System Tools and Utilities. |
%Float |
A floating-point number |
This class is deprecated; use %Double or %Decimal instead. |
%Integer |
An integer |
|
%List |
Data in $List format |
The logical value is data in $List format. |
%ListOfBinary |
Data in $List format, with each list item as binary data |
The logical value is data in $List format. |
%Name |
A name in the form Lastname,Firstname |
The %Name data type has special indexing support when used in conjunction with the %CacheStorage class. For details, see %Name in the InterSystems Class Reference. |
%Numeric |
A fixed-point number |
|
%SmallInt |
A small integer value |
This class is the same as %Integer except for its OdbcType. |
%Status |
An error status code |
Many methods in the Caché Class Library return values of type %Status. For information on working with these values, see %Status in the InterSystems Class Reference. |
%String |
A string |
|
%Text |
Searchable text |
This class supports word-based searching and relevance ranking. For details, see %Text and %Text.Text in the InterSystems Class Reference. |
%Time |
A time value |
The logical value is the number of seconds past midnight. |
%TimeStamp |
A value for a time and date |
The logical value of the %TimeStamp 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 %TimeStamp property: $ZDATETIME(h,3) |
%TinyInt |
A very small integer value |
This class is the same as %Integer except for its OdbcType and its maximum and minimum values. |
%MV.Date |
A MultiValue date |
The logical value is a MultiValue date. To convert a Caché date to a MultiValue date, subtract 46385. |
%MV.Numeric |
A number |
This data type class handles the MultiValue masked decimal (MD) conversion codes. |
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 Caché SQL and how the data type is projected to client systems:
-
SqlCategory Specifies the SQL category to use for the data type when the Caché SQL engine performs operations upon it.
-
OdbcType Specifies the ODBC type used when the data type is accessed via ODBC.
-
ClientDataType Specifies the Java or ActiveX 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.
For a data type class, the SqlCategory class keyword specifies the SQL category that Caché 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
For a data type class, the OdbcType class keyword controls how Caché translates logical data values to and from values used by the Caché SQL ODBC interface. The following table shows the OdbcType values of the data types listed in this chapter.
Data Type Classes Grouped by OdbcType
For a data type class, the ClientDataType class keyword controls how Caché 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 |
%BigInt |
BINARY |
%Binary (or any property requiring that there is no Unicode conversion of data) |
CURRENCY |
%Currency |
DATE |
%Date |
DOUBLE |
%Double and %Float |
DECIMAL |
%Decimal |
FDATE |
%FilemanDate |
FTIMESTAMP |
%FilemanTimeStamp |
INTEGER |
%Counter, %Integer, %SmallInt, %TinyInt |
LIST |
%List, %ListOfBinary |
MVDATE |
%MV.Date |
NUMERIC |
%Numeric, %MV.Numeric |
TIME |
%Time |
TIMESTAMP |
%DateTime, %TimeStamp |
VARCHAR |
%Char, %EnumString, %ExactString, %Name, %String, %Text |
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:
-
-
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 Caché server for various reason, such as because the remote database field name is a reserved word in Caché. For information on linked tables, see
The Link Table Wizard in
Using Caché SQL.
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 Caché 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.
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 |
%BigInt |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XSDTYPE |
|
%Binary |
MAXLEN, MINLEN |
CANONICALXML, MTOM, XSDTYPE |
|
%Boolean |
|
XSDTYPE |
|
%Char |
COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST |
XMLLISTPARAMETER, XSDTYPE |
|
%Counter |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XSDTYPE |
|
%Currency* |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST |
XSDTYPE |
|
%Date |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XSDTYPE |
|
%DateTime |
DISPLAYLIST, MAXVAL, MINVAL, VALUELIST |
XMLDEFAULTVALUE, XMLTIMEZONE, XSDTYPE |
DATEFORMAT |
%Decimal |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST |
XSDTYPE |
|
%Double |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST |
XSDTYPE |
|
%EnumString |
COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST |
XSDTYPE |
|
%ExactString |
COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST |
XSDLISTPARAMETER, XSDTYPE |
|
%FilemanDate |
|
XSDTYPE |
STRICTDATA |
%FilemanTimeStamp |
|
XSDTYPE |
STRICTDATA |
%Float |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST |
XSDTYPE |
|
%Integer |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XSDTYPE |
STRICT |
%List |
ODBCDELIMITER |
XSDTYPE |
|
%ListOfBinary |
ODBCDELIMITER |
XSDTYPE |
|
%Name |
COLLATION,MAXLEN |
XSDTYPE |
INDEXSUBSCRIPTS |
%Numeric |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST |
XSDTYPE |
|
%SmallInt |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XSDTYPE |
|
%Status |
|
XSDTYPE |
|
%String |
COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST |
XMLLISTPARAMETER, XSDTYPE |
|
%Text |
COLLATION, CONTENT, DISPLAYLIST, ESCAPE, MAXLEN, MINLEN, PATTERN, TRUNCATE, VALUELIST |
XMLLISTPARAMETER, XSDTYPE |
LANGUAGECLASS, SIMILARITYINDEX |
%Time |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XMLTIMEZONE, XSDTYPE |
PRECISION |
%TimeStamp |
DISPLAYLIST, MAXVAL, MINVAL, VALUELIST |
XMLDEFAULTVALUE, XMLTIMEZONE, XSDTYPE |
|
%TinyInt |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XSDTYPE |
|
%MV.Date |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, VALUELIST |
XSDTYPE |
|
%MV.Numeric |
DISPLAYLIST, FORMAT, MAXVAL, MINVAL, SCALE, VALUELIST |
XSDTYPE |
DESCALE |
*This special-purpose class is only for use in migrations to Caché.
The common parameters from the preceding table are as follows:
-
COLLATION Specifies the manner in which property values are transformed for indexing.
-
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".
-
-
ESCAPE Specifies the type of escaping to be done, if the string is used in certain contexts. Use either
"XML" (the default) or
"HTML".
-
-
MAXLEN Specifies the maximum number of characters the string can contain. The default is 50. As with many other parameters, this parameter affects how Caché 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.
-
-
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.
-
The less common parameters in the preceding table are as follows:
-
STRICT (for
%Integer) requires that value be an integer. By default, if a property is of type
%Integer, and you specify a non-integer numeric value, Caché converts the value to an integer. If
STRICT is 1 for a property, in such a case, Caché does not convert the value; instead validation fails.
-
DATEFORMAT (for
%DateTime) 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.
-
PRECISION (for
%Time) 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, Caché rounds the provided value to the nearest second.
-
-
INDEXSUBSCRIPTS (for
%Name) specifies the number of subscripts used by the property in indices, using a comma as a delimiter in the property value; the
%CacheStorage 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.
-
-
-
STRICTDATA (for
%FilemanDate and
%FilemanTimeStamp) affects the generation of the
LogicalToDisplay() and
LogicalToOdbc() methods When STRICTDATA=1, imprecise or invalid dates are not changed to a valid FileMan Date value. The default is 0. For example, if Logical FileMan Date value is 31110, by default, this will translate to 3111001 (Sept 01, 2011). If STRICTDATA=1, this transformation does not take place and the invalid/imprecise Logical value gets an error when converted to display or Odbc format.
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.
To specify a value for a literal property, use the SET command, an OREF, and dot syntax as follows:
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
%Boolean. For another example, for an enumerated property, the value must be one of the items specified by the
VALUELIST parameter.
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.
Caché uses these methods internally, and you can call them directly as well. In each case, the argument is a property value. For example:
SAMPLES>set p=##class(DeepSee.Study.Patient).%OpenId(1)
SAMPLES>w p.Gender
M
SAMPLES>w ##class(DeepSee.Study.Patient).GenderLogicalToDisplay(p.Gender)
Male
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.
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. (Note that it is necessary to use this keyword if the property name is an
SQL reserved word). For instance, if there is a
%String property called select, you would define its projected name with the following syntax:
Property select As %String [ SqlFieldName = selectfield ];
If the name of a property is an
SQL reserved word, you need to specify a different name for its projection.
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, Caché 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 Caché 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.
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.
In Caché, you can define computed properties, whose values are computed via ObjectScript, 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:
*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.