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:
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, ... )
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.
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).
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.
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.
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.
set ClassName = "%Dictionary.ClassDefinition"
set ClassmethodName = "NormalizeClassname"
set SingleArgument = "%String"
write $ZOBJCLASSMETHOD(ClassName, ClassmethodName, SingleArgument), !
$ZOBJMETHOD
Synopsis
$ZOBJMETHOD (Instance, Methodname, Arg1, Arg2, Arg3... )
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.
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.
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.
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.
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.
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... )
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.
An expression which evaluates to an oref. The value of the expression must be
that of an in-memory instance of the desired class.
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.
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.
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.
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"), !