$PROPERTY (ObjectScript)

Supports reference to a particular property of an instance.

Synopsis

$PROPERTY(instance,propertyname,index1,index2,index3... )

Arguments

Argument	Description
instance	Optional — An expression that evaluates to an object instance reference (OREF). The value of the expression must be that of an in-memory instance of the desired class. If omitted, defaults to the current object.
propertyname	An expression that evaluates to a string. The value of the string must match the name of an existing property defined in the class identified by instance.
index1, index2, index3, ...	Optional — If propertyname is a multidimensional value, then this series of expressions is treated as indexes into the array represented by the property. (If the specified property is not multidimensional, the presence of extra arguments causes an error at runtime.)

Description

$PROPERTY gets or sets the value of a property in an instance of the designated class. This function permits an ObjectScript program to select the value of an arbitrary property in an existing instance of some class. Since the first argument must be an instance of a class, it is computed at execution time. The property name may be computed at runtime or supplied as a string literal. The contents of the string must match exactly the name of a property declared in the class. Property names are case-sensitive.

If the property is declared to be multidimensional, then the arguments after the property name are treated as indexes into a multidimensional array. A maximum of 255 argument values may be used for the index.

$PROPERTY may also appear on the left side of an assignment. When $PROPERTY appears to the left of an assignment operator, it provides the location to which a value is assigned. When it appears to the right, it is the value being used in the calculation.

If instance is not a valid in-memory OREF, an <INVALID OREF> error occurs. If propertyname is not a valid property, a <PROPERTY DOES NOT EXIST> error occurs. If you specify an index1 and propertyname is not multidimensional, an <OBJECT DISPATCH> error occurs.

An attempt to get a multidimensional value from a property which is not declared to be multidimensional results in a <FUNCTION> error; likewise for attempting to set a multidimensional value into a property that is not multidimensional.

$PROPERTY and Methods

The $PROPERTY function calls the Get() or Set() methods of the property passed to it. It is functionally the same as using the “Instance.PropertyName” syntax, where “Instance” and “PropertyName” are equivalent to the arguments as listed in the function’s signature. Because of this, $PROPERTY should not be called within a property’s Get() or Set() method, if one exists. For more information on Get() and Set() methods, see Using and Overriding Property Methods.

When used within a method to refer to a property of the current instance, $PROPERTY may omit instance. The comma that would normally follow instance is still required, however.

Examples

The following example returns the current NLS Language property value:

USER>set nlsoref=##class(%SYS.NLS.Locale).%New()
 
USER>write $property(nlsoref,"Language")
English

The following example shows $PROPERTY used on both sides of an assignment operator:

USER>set TestFile = ##class(%Library.File).%New("AFile")
 
USER>write TestFile.Name
AFile
USER>set $property(TestFile,"Name") = $property(TestFile,"Name") _ "Renamed"
 
USER>write TestFile.Name
AFileRenamed

The following example returns a property value from the current object, in this case the SQL Shell. $PROPERTY is specified with its first argument omitted:

USER>DO $SYSTEM.SQL.Shell()
SQL Command Line Shell
----------------------------------------------------
 
The command prefix is currently set to: <<nothing>>.
Enter <command>, 'q' to quit, '?' for help.
[SQL]USER>>set path="a,b,c"

path="a,b,c"
[SQL]USER>>! WRITE "The schema search path is ",$PROPERTY(,"Path")
The schema search path is "a,b,c"
[SQL]USER>>

The following example uses the %Dictionary API to get the names of the properties of an object:

ClassMethod ShowProperties(oref As %RegisteredObject)
{
	set class = oref.%ClassName(1)
	set classdef=##class(%Dictionary.CompiledClass).%OpenId(class)
	set proplist=classdef.Properties
	for i=1:1:proplist.Count() {
		set prop=proplist.GetAt(i)
		write !, "Value of "_prop.Name_":"_$property(oref,prop.Name)
	}
}

The following shows this method in use:

%SYS>set db=##Class(SYS.Database).%OpenId("C:\InterSystems\SAMPLEINSTALL\mgr\irisaudit")
 
%SYS>d ##class(Demo.Demo).ShowProperties(db)                                
Value of %%OID: 'C:\InterSystems\SAMPLEINSTALL\mgr\irisauditSYS.Database
Value of %Concurrency: 0
Value of BlockFormat: 2
Value of BlockSize: 8192
Value of Blocks: 128
Value of BlocksPerMap: 62464
Value of ClusterMountMode: 0
Value of ClusterMounted: 0
Value of CurrentMaps: 1
Value of Directory: c:\intersystems\sampleinstall\mgr\irisaudit\
Value of DirectoryBlock: 3
Value of EncryptedDB: 0
Value of EncryptionKeyID:
Value of Expanding: 0
Value of ExpansionSize: 0
Value of Full: 0
Value of GlobalJournalState: 3
Value of InActiveMirror: 0
Value of LastExpansionTime:
Value of LastVolumeDirectory: c:\intersystems\sampleinstall\mgr\irisaudit\
Value of LastVolumeSize: 1
...