This document describes Caché-supplied (intrinsic) functions that can be used to generalize processing of objects by allowing a reference to a class and one of its methods or properties to be computed at runtime.
This article describes the following intrinsic functions:
For more information on ObjectScript functions generally, see the section Functions in the Caché ObjectScript Guide.
The function names are shown here in all uppercase letters, but they are, in fact, case-insensitive.
$ZOBJCLASSMETHOD
Synopsis
$ZOBJCLASSMETHOD (Classname, Methodname, Arg1, Arg2, Arg3, ... )
Parameters
Classname The name of an existing, accessible class.
Methodname The name of a classmethod in the designated class.
Arg1, Arg2, Arg3, ... Values to be substituted for the arguments of the classmethod when it is invoked.
Description
This function permits a Caché ObjectScript program to invoke an arbitrary classmethod in an arbitrary class. Both the class name and the method name may be computed at runtime or supplied as string constants.
If the method takes arguments, they are supplied by the list of arguments that follow the methodname. A maximum of 255 argument values may be passed to the method.
Parameters
Classname
An expression which evaluates to a string. The content of the string must match exactly the name of an existing, accessible, previously-compiled class. In the case of references to Caché classes, the name may be either in its canonical form (%Library.String), or its abbreviated form (%String).
Methodname
An expression which evaluates to a string. The value of the string must match the name of an existing ClassMethod in the class identified by Classname.
Arg1, Arg2, Arg3, ...
A series of expressions that will be substituted sequentially for the arguments to the designated method. The values of the expressions can be of any type. It is the responsibility of the implementor to make sure that the type of the supplied expressions match what the method expects, and have values within the bounds declared.
If the specified method expects no arguments then no arguments beyond the MethodName need be given in the function invocation. Extra arguments are ignored.
Remarks
The invocation of $ZOBJCLASSMETHOD as a function or a procedure will determine the invocation of the target method. See the examples for more detail.
An attempt to invoke a method which is non-existent, or one which is not declared to be a ClassMethod, will result in a <METHOD DOES NOT EXIST> error.
Examples
The following example shows $ZOBJCLASSMETHOD used as a function:
    set ClassName = "%Dictionary.ClassDefinition"
    set ClassmethodName = "NormalizeClassname"
    set SingleArgument = "%String"
    write $ZOBJCLASSMETHOD(ClassName, ClassmethodName, SingleArgument), !
$ZOBJMETHOD
Synopsis
$ZOBJMETHOD (Instance, Methodname, Arg1, Arg2, Arg3... )
Parameters
Instance An instance of the class containing the method name.
Methodname The name of a method in the designated class.
Arg1, Arg2, Arg3, ... Values to be substituted for the arguments of the methodname when it is invoked.
Description
This function permits a Caché ObjectScript program to call an arbitrary method in an existing instance of some class. Since the first argument must be a reference to an object, it is computed at execution time. The method name may be computed at runtime or supplied as a string literal. If the method takes arguments, they are supplied from the list of arguments that follow the methodname. A maximum of 255 argument values may be passed to the method. Extra arguments beyond those expected by the method are ignored.
Parameters
Instance
An expression which evaluates to an object reference. The value of the expression must be that of an in-memory instance of the desired class.
Methodname
An expression which evaluates to a string. The value of the string must exactly match the name of an existing method in the instance of the class given as the first argument.
Arg1, Arg2, Arg3, ...
A series of expressions that will be substituted in turn for the arguments to the designated method. The values of the expressions can be of any type. It is the responsibility of the implementor to make sure that the supplied expressions both match in type and have values with the bounds that the method expects.
If the specified method expects no arguments then nothing beyond Classname and MethodName need be used in the function invocation. In other words, extra arguments are ignored.
Remarks
The invocation of $ZOBJMETHOD as a function or a procedure will determine the invocation of the target method. See the examples for more detail.
When used within one method of a class instance to refer to another method of that instance, the $ZOBJMETHOD may omit Instance. The comma that would normally follow Instance is still required, however.
An attempt to invoke a method which is non-existent, or one which is declared to be a ClassMethod, will result in a <METHOD DOES NOT EXIST> error.
Examples
The following example shows $ZOBJMETHOD used as a function:
    set ListOfStuff = ##class(%Library.ListOfDataTypes).%New()
    for i = "First", "Second", "Third", "Fourth"
    {
        do ListOfStuff.Insert((i _ "-Element"))
    }
    set MethodName = "Count"
    set Elements = $ZOBJMETHOD(ListOfStuff, MethodName)
    write "Elements: ", Elements, !
    set i = $RANDOM(Elements) + 1
    write "Element #", i , " = " , $ZOBJMETHOD(ListOfStuff, "GetAt", i), !
$ZOBJPROPERTY
Synopsis
$ZOBJPROPERTY (Instance, Propertyname, Index1, Index2, Index3... )
Parameters
Instance An instance of the class containing the method name.
Propertyname The name of a property in the designated class.
Index1, index2, index3, ... If the property named as the second argument is multidimensional, then the index<n> are treated as indexes into the array that constitutes the property.
Description
This function permits a Caché 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 sting literal. The contents of the string must match exactly the name of a property declared in the class.
If the property is declared to be multidimensional, then the arguments after the propertyname are treated as indexes into a multidimensional array. A maximum of 255 argument values may be used for the index.
The $ZOBJPROPERTY may also appear on the left side of an assignment. In this instance, it provides the location to which a value is assigned.
Parameters
Instance
An expression which evaluates to an oref. The value of the expression must be that of an in-memory instance of the desired class.
Propertyname
An expression which evaluates to a string. The value of the string must match the name of an existing property defined in the class identified by Classname.
Arg1, Arg2, Arg3, ...
If Propertyname is a multidimensional value, then this series of expressions will be 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.
Remarks
When $ZOBJPROPERTY appears to the left of an assignment operator, it is the location being set. When it appears to the right, it is the value being used in the calculation.
When used within a method to refer to a property of the current instance, the $ZOBJPROPERTY may omit Instance. The comma that would normally follow Instance is still required, however.
An attempt to get (set) a multidimensional value from (into) a property which is not declared to be multidimensional will result in a <FUNCTION> error.
Examples
The following example shows $ZOBJPROPERTY used as a function:
    set TestName = "%Library.File"
    set ClassDef = ##class(%Library.ClassDefinition).%OpenId(TestName)
    for i = "Name", "Super", "Persistent", "Final" 
    {
        write i, ": ", $ZOBJPROPERTY(ClassDef, i), !
    }
This one shows its use on both sides of an assignment operator:
    set TestFile = ##class(%Library.File).%New("AFile")
    write "Initial file name: ", $ZOBJPROPERTY(TestFile, "Name"), !
    set $ZOBJPROPERTY(TestFile, "Name") = $ZOBJPROPERTY(TestFile, "Name") 
                                        _ "Renamed"
    write "File name afterward: ", $ZOBJPROPERTY(TestFile, "Name"), !