Using Property Methods

This topic describes and provides reference information for property methods, which are the actual methods that InterSystems IRIS® data platform uses when you use OREFs to work with the properties of objects. You can use these methods directly.

For information on how these methods are defined, see Overriding Property Methods.

Introduction

When a class has properties, the class compiler automatically generates a number of methods for each property and uses those internally. The names of the methods are based on the property names. In most cases, you cannot see these methods; access for simple properties is implemented directly within the virtual machine for optimal performance. The last section provides sample code you can use to list these methods.

For example, if we define a class Person with three properties:

Class MyApp.Person Extends %Persistent
{

Property Name As %String;

Property Age As %Integer;

Property DOB As %Date;
}

When compiled, this class includes the following methods:

NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
AgeDisplayToLogical(), AgeGet(), AgeGetStored(), AgeIsValid(), AgeLogicalToDisplay(), AgeLogicalToOdbc(), AgeNormalize(), AgeSet()
DOBDisplayToLogical(), DOBGet(), DOBGetStored(), DOBIsValid(), DOBLogicalToDisplay(), DOBLogicalToOdbc(), DOBNormalize(), DOBSet()

Most of these are instance methods that take one argument: the value of the property to be used. For example:

 Set x = person.DOBIsValid(person.DOB)
 Write person.DOBLogicalToDisplay(person.DOB)

The InterSystems IRIS dot syntax for referring to object properties is an interface for a set of accessor methods to retrieve and set values. For each non-calculated property, whenever the code refers to oref.Prop (where oref is an object and Prop is a property), it is executed as if a system-supplied PropGet() or PropSet() method were invoked. For example:

 Set person.DOB = x

acts as if the following method was called:

 Do person.DOBSet(x)

while:

 Write person.Name

acts like:

 Write person.NameGet()

Accessing the properties of an object by using the PropGet() and PropSet() methods requires that the object be loaded into memory. On the other hand, the PropGetStored() class method allows you to retrieve the property value of a stored object directly from disk, without having to load the entire object into memory. For example, to write the name of the person with ID 44, you could use:

 Write ##class(MyApp.Person).NameGetStored(44)

Data Formats

Many of the property methods translate data from one format to another, for example when displaying data in a human-readable format or when accessing data via ODBC. For reference, the formats are:

Display — The format in which data can be input and displayed. For instance, a date in the form of “April 3, 1998” or “23 November, 1977.”
Logical — The in-memory format of data, which is the format upon which operations are performed. While dates have the display format described above, their logical format is integer; for the sample dates above, their values in logical format are 57436 and 50000, respectively.
Storage — The on-disk format of data — the format in which data is stored to the database. Typically this is identical to the logical format.
ODBC — The format in which data can be presented via ODBC or JDBC. This format is used when data is exposed to ODBC/SQL. The available formats correspond to those defined by ODBC.
XSD — SOAP-encoded format. This format is used when you export to or import from XML. This applies only to classes that are XML-enabled.

Reference

All method signatures are examples that use a property named sampleprop.

BuildValueArray()

Method samplepropBuildValueArray(serializedcollection, byRef array) as %Status

Example name: samplepropBuildValueArray()

Where available: list and array properties.

Given the serialized form of a collection object, this method returns (by reference) a multidimensional array containing that collection. To obtain the serialized form of a collection property, call the Serialize() method of the collection object. For example, suppose that Sample.Person has a property defined as follows:

Property FavoriteColors As list Of %String;

The following example demonstrates serializing this property and obtaining a multidimensional array:

USER>set p=##class(Sample.Person).%OpenId(1)
 
USER>set serialized=p.FavoriteColors.Serialize()
 
USER>set status=p.FavoriteColorsBuildValueArray(serialized,.array)
 
USER>write status
1
USER>zw array
array(1)="red"
array(2)="pink"
array(3)="purple"

CollectionToDisplay()

Method samplepropCollectionToDisplay(serializedcollection) as ReturnValue

Where available: list and array properties.

Given the serialized form of a collection object, this method returns the value in display format. To obtain the serialized form of a collection property, call the Serialize() method of the collection object. For example, suppose that Sample.Person has a property defined as follows:

Property FavoriteColors As list Of %String;

The following example demonstrates serializing this property and obtaining the display value:

USER>set p=##class(Sample.Person).%OpenId(1)
 
USER>w p.FavoriteColorsCollectionToDisplay(p.FavoriteColors.Serialize())
red
pink
purple

CollectionToOdbc()

Method samplepropCollectionToOdbc(serializedcollection) as ReturnValue

Where available: list and array properties.

Given the serialized form of a collection object, this method returns the value in ODBC format. To obtain the serialized form of a collection property, call the Serialize() method of the collection object. For example, suppose that Sample.Person has a property defined as follows:

Property FavoriteColors As list Of %String;

The following example demonstrates serializing this property and obtaining the ODBC value:

USER>set p=##class(Sample.Person).%OpenId(1)
 
USER>w p.FavoriteColorsCollectionToDisplay(p.FavoriteColors.Serialize())
red,pink,purple

DisplayToCollection()

Method samplepropDisplayToCollection(delimitedstring) as ReturnValue

Where available: list and array properties.

This method accepts a delimited string and converts it to a serialized collection value.

DisplayToLogical()

Method samplepropDisplayToLogical(InputValue) as ReturnValue

Where available: literal properties and list and array properties containing literal values, if the data type class defines DisplayToLogical().

Given a display value, this method converts it to a logical value, as appropriate for the property definition.

For example, consider the following property definition:

Property Test(DISPLAYLIST = ",one,two,three", VALUELIST = ",1,2,3");

Given an instance of the class that contains this property, we can get the logical value corresponding to two, as follows:

USER>write x.TestDisplayToLogical("two")
2

Get()

Method samplepropGet() as ReturnValue

Where available: literal properties and object-valued properties.

This method returns the in-memory value of the property. This method is not used when you access the data via SQL.

For example (showing a literal property):

USER>set test=##class(Sample.Person).%OpenId(1)
 
USER>write test.NameGet()
Sample Name

For a object-valued property, the in-memory value is an OREF:

USER>set oref=test.AddressGet()

USER>write
oref=<OBJECT REFERENCE>[539@Sample.Address]
test=<OBJECT REFERENCE>[533@Sample.Person]
USER>w oref
539@Sample.Address
USER>w oref.Street
47 Pinkerton Way

GetObject()

Method samplepropGetObject() as OID

Where available: object-valued properties.

This method gets the OID associated with the property. This method is not used when you access the data via SQL. This is similar to GetObjectId() except that an OID is returned.

GetObjectId()

Method samplepropGetObjectId() as ID

Where available: object-valued properties.

This method gets the ID associated with the property. This method is not used when you access the data via SQL.

USER>set test=##class(Sample.Person).%OpenId(1000)

USER>write test.AddressGetObjectId()
5

In this case, the Address property of Sample.Person is the Sample.Address object whose ID is 5.

GetStored()

ClassMethod samplepropGetStored(id) as ReturnValue

Where available: literal properties and object-valued properties.

Given the ID of a saved object, this method returns the value of the given property directly from disk, without having to load the entire object into memory. This method is not used when you access the data via SQL. For example, to write the name of the person with ID 44, you could use:

USER>write ##class(Sample.Person).NameGetStored(44)
Sample Name

GetSwizzled()

Method samplepropGetSwizzled(onlyCheck as %Boolean) as OREF

Where available: object-valued properties.

Opens the given object instance, loading it into memory. This is known as swizzling.

If onlyCheck is omitted, this method swizzles the given object and returns an OREF for the object. If onlyCheck is 1, the method returns an OREF for the object, but only if it is already swizzled. Otherwise, it returns a null OREF.

For example:

USER>set emp = ##class(Sample.Employee).%OpenId(102)
 
USER>set co = emp.CompanyGetSwizzled(1)
 
USER>if (co = "") {write "Company is not swizzled"} else {write co.Name}
Company is not swizzled
USER>set co = emp.CarGetSwizzled()
 
USER>if (co = "") {write "Company is not swizzled"} else {write co.Name}
Acme Company, Inc.

IsEmpty()

Method samplepropIsEmpty() as %Boolean

Where available: serial properties. For example, suppose that Sample.Person has a property named SerialAddress of type Sample.SerialAddress, which is a serial class.

USER>set new=##class(Sample.Person).%New()
 
USER>write new.SerialAddressIsEmpty()
1
USER>set new.SerialAddress=##class(Sample.SerialAddress).%New()
 
USER>write new.SerialAddressIsEmpty()
1
USER>set new.SerialAddress.Street="17 Turnip Ave"
 
USER>write new.SerialAddressIsEmpty()
0

IsValid()

Method samplepropIsValid(InputValue) as %Status

Where available: literal properties, serial properties, and list and array properties.

Given an input value, this method performs validation as appropriate for the property definition.

For example, consider the following property definition:

Property Test(DISPLAYLIST = ",one,two,three", VALUELIST = ",1,2,3");

The value 3 is valid for this property, but the value 4 is not:

USER>set x=##class(Sample.Person).%New()
 
USER>set status=x.TestIsValid(3)

USER>write status
1
USER>set status=x.TestIsValid(4)

USER>write status
0 M%,1,2,36USER-$e^zTestIsValid+1^Sample.Person.1^1e^^
USER>d $system.OBJ.DisplayError()
 
ERROR #7205: Datatype value '4' not in VALUELIST ',1,2,3'

LogicalToDisplay()

Method samplepropLogicalToDisplay(InputValue) as ReturnValue

Where available: literal properties and list and array properties containing literal values, if the data type class defines LogicalToDisplay().

Given a logical value, this method converts it to a display value, as appropriate for the property definition.

For example, consider the following property definition:

Property Test(DISPLAYLIST = ",one,two,three", VALUELIST = ",1,2,3");

Given an instance of the class that contains this property, we can get the display value corresponding to 2, as follows:

USER>write x.TestLogicalToDisplay(2)
two

LogicalToOdbc()

Method samplepropLogicalToOdbc(InputValue) as ReturnValue

Where available: literal properties and list and array properties containing literal values, if the data type class defines LogicalToOdbc().

Given a logical input value, this method converts it to an ODBC value, as appropriate for the property definition.

For example, suppose that Integer is a property of type integer. Given an instance x of the class that contains this property, we can obtain the ODBC value for this property as follows:

USER>write x.IntegerLogicalToOdbc("000056")
56

LogicalToXSD()

Method samplepropLogicalToXSD(InputValue) as ReturnValue

Where available: literal properties and list and array properties containing literal values, if used in a class that extends %XML.AdaptorOpens in a new tab.

Given a logical input value, this method converts it to an SOAP-encoded value, as appropriate for the property definition.

For example, suppose that Sample.Person has a property named Boolean, which is a %BooleanOpens in a new tab value. Given an instance p of the class that contains this property, we can convert 1 to the appropriate SOAP-encoded value, as follows:

USER>set p=##class(Sample.Person).%OpenId(1)
USER>write p.BooleanLogicalToXSD(1)
true

OdbcToCollection()

Method samplepropOdbcToCollection(delimitedstring) as ReturnValue

Where available: list and array properties.

This method accepts a delimited string of ODBC values and converts it to a serialized collection value.

NewObject()

Method samplepropNewObject() as OREF

Where available: object-valued properties (except for list and array properties).

Returns an OREF that refers to a new instance of the given class and sets the property equal to this instance. For example:

USER>set p=##class(Sample.Person).%New()
 
USER>set address=p.AddressNewObject()
 
USER>write address
604@Sample.Address

The previous is equivalent to the following:

USER>set p=##class(Sample.Person).%New()
 
USER>set address=p.Address
 
USER>set address=##class(Sample.Address).%New()
 
USER>write address
604@Sample.Address

Normalize()

Method samplepropNormalize(InputValue) as ReturnValue

Where available: literal properties and list and array properties containing literal values.

Given an input value, this method normalizes the value as appropriate for the property definition.

For example, suppose that Integer is a property of type integer. Given an instance x of the class that contains this property, we can obtain a normalized value for this property as follows:

USER>write x.IntegerNormalize(000078.0000)
78

Set()

Method samplepropSet(InputValue) as %Status

Where available: literal properties and object-valued properties.

Given an input value, this method sets the property equal to this value. If the property is object-valued, the input value should be an OREF. This method returns a %StatusOpens in a new tab. This method is not used when you access the data via SQL. For example:

USER>set test=##class(Sample.Person).%New()
 
USER>set status=test.NameSet("Sample Name")
 
USER>write status
1

For another example, suppose that Sample.Person has a property named ObjectProp of type Sample.OtherClass:

USER>set test=##class(Sample.Person).%New()
 
USER>set other=##class(Sample.OtherClass).%New()
 
USER>set status=test.ObjectPropSet(other)
 
USER>write status
1

SetObject()

Method samplepropSetObject(Oid) as %Status

Where available: object-valued properties.

Given the OID of an object, this method sets the property using that OID. This is similar to SetObjectId() except for using the OID instead of the ID. This method is not used when you access the data via SQL.

SetObjectId()

Method samplepropSetObjectId(Id) as %Status

Where available: object-valued properties.

Given the ID of an object, this method sets the property using that ID. This method is not used when you access the data via SQL. For example, suppose Sample.Person has a Address property of type Sample.Address.

USER>set test=##class(Sample.Person).%New()

USER>set status=test.AddressSetObjectId(14)

This code sets the Address property equal to the Sample.Address instance whose ID is 14.

XSDToLogical()

Method samplepropXSDToLogical(InputValue) as ReturnValue

Where available: literal properties and list and array properties containing literal values, if used in a class that extends %XML.AdaptorOpens in a new tab.

Given a SOAP-encoded input value, this method converts it to an logical value, as appropriate for the property definition.

USER>set p=##class(Sample.Person).%OpenId(1)

USER>write p.BooleanXSDToLogical("true")
1

Listing Property Methods

The following sample code uses the %Dictionary API and displays the property methods generated for a given method of a given class:

ClassMethod DisplayPropertyMethods(className As %String = "", propertyName As %String = "")
{
    Set cdef=##class(%Dictionary.CompiledClass).%OpenId(className)
    Set propertynamelength=$LENGTH(propertyName)
    Set methodlist=cdef.Methods
    #dim item as %Dictionary.CompiledMethod
    For i=1:1:methodlist.Count() {
        Set item=methodlist.GetAt(i)
        Set methodname=item.Name
        Set extract=$extract(methodname,0,propertynamelength)
        // This checks that the method name starts with the property name.
        // There will be false positives when one property name 
        // starts with the same characters as another
        If (extract=propertyName) {
            Write !, methodname
        }
    }
}

For example:

USER>do ##class(Tools.Tools).DisplayPropertyMethods("Sample.Person","Test")
 
TestDisplayToLogical
TestGet
TestGetStored
TestIsValid
TestLogicalToDisplay
TestLogicalToOdbc
TestNormalize
TestSet

Using Property Methods

Introduction

Data Formats

Reference

Listing Property Methods

See Also