NEW function (classes)

Creates an instance of a class (object) and returns an object reference to that instance. You can use this object reference to access the PUBLIC data members, properties, and methods of the instance. For more information on object references, see the reference entry for a Class-based object reference.

Syntax

NEW object-type-name ( [ parameter[ , parameter ]...] )

object-type-name

Specifies the type name of the ABL or .NET class you want to instantiate. Specify a class type name using the syntax as described in the Type-name syntax reference entry. If object-type-name specifies a .NET object, it can be most any .NET class, with a few restrictions. For more information, see the Notes of this reference entry. The value of object-type-name is restricted to alphanumeric characters plus the symbols #, $, %, and _.

If, without casting, you assign the NEW function value to a target data element, or pass the NEW function as input to a target routine parameter, object-type-name must specify one of the following classes:

The same class type that is defined for the target
A subclass of the class type that is defined for the target
A class type that implements the interface type defined for the target

If object-type-name specifies one of the following kinds of object types, ABL raises a compiler error:

An interface type
An abstract class type

( [ parameter[ , parameter ]...] )

Specifies zero or more parameters passed to a PUBLIC instance constructor that is defined for the class. You must provide the parameters identified by the specified constructor, matched with respect to number, data type, and mode. To invoke a constructor that is overloaded in the class, you must specify sufficient information for each parameter to disambiguate it from all other constructors in the class. Otherwise, ABL raises an error identifying the ambiguity.

For information on the parameter passing syntax and disambiguating overloaded constructors, see the Parameter passing syntax reference entry.

For information on defining a constructor for a class, see the CONSTRUCTOR statement reference entry.

Examples

The following example shows how the NEW function can instantiate a class within an expression:

DEFINE VARIABLE rObj AS Progress.Lang.Object.

IF ( NEW Progress.Lang.Object( ) ):ToString( ) BEGINS "Progress" THEN
  MESSAGE "This object is making Progress..." VIEW-AS ALERT-BOX.

This code fragment instantiates a Progress.Lang.Object in order to check if the string value returned from its ToString( ) method begins with "Progress", and displays a message if it does.

The following example shows three (3) invocations of the NEW function.

r-newclass.p

ROUTINE-LEVEL ON ERROR UNDO, THROW.

FUNCTION ClassFunc RETURNS CLASS Progress.Lang.Object 
  (INPUT iVal AS INTEGER):
  MESSAGE "iVal = " iVal VIEW-AS ALERT-BOX.
  IF iVal MODULO 2 = 0 THEN
    RETURN NEW Progress.Lang.Object( ).
  ELSE
    RETURN?.
END FUNCTION.

RUN DisplayClass( NEW Progress.Lang.Object( ) ).

PROCEDURE DisplayClass:
  DEFINE INPUT PARAMETER rObj AS CLASS Progress.Lang.Object.

  DEFINE VARIABLE cClass1 AS CHARACTER NO-UNDO.
  DEFINE VARIABLE cClass2 AS CHARACTER NO-UNDO.

  cClass1 = rObj:ToString( ).
  /* The ToString( ) call errors on an odd RANDOM input value */
  cClass2 = ( ClassFunc( RANDOM(1,100) ) ):ToString( ).

  MESSAGE "The " cClass1 " and " cClass2 " instances have the same 
  class type." 
    VIEW-AS ALERT-BOX.

  CATCH e AS Progress.Lang.SysError:
    UNDO, THROW NEW Progress.Lang.AppError( "Application Error", 555 ).
  END CATCH.
END PROCEDURE.

This r-newclass.p procedure runs an internal procedure (DisplayClass) that displays a message showing the ToString( ) values of two different objects instantiated as the same class type (Progress.Lang.Object). However, one of these objects is instantiated within a user-defined function (ClassFunc) that returns a valid object reference or the Unknown value (?) in order to generate an error, depending on the input value of a RANDOM function.

When a valid object reference is returned, it is used to access the ToString( ) method of the instance in an expression. When the Unknown value (?) is returned, this generates a run-time error when used as an object reference. The procedure then catches the error and responds by throwing a Progress.Lang.AppError object that is also instantiated by a NEW function invoked in an expression, and the error text is displayed as an error message when run in the OpenEdge Editor.

Notes

When you create an instance of a class, ABL invokes the specified constructor for the class. At this time, the object instance gets its own copy of the data members and properties defined in the class and in all classes within its inherited class hierarchy. In addition, the object instance is added to the session object chain referenced by the FIRST-OBJECT attribute or LAST-OBJECT attribute of the SESSION system handle.
The ABL Virtual Machine (AVM) automatically deletes (garbage collects) any class instance that you create with the NEW function some time after no reference to that object exists in the ABL session. However, you can force any class instance to be deleted immediately by using the DELETE OBJECT statement. For more information on garbage collection for class instances, see the DELETE OBJECT statement reference entry.
You can assign the object reference value returned by the NEW function to an ABL data element (or target of a passed parameter) defined as a class type or interface type when the destination data element (or parameter target) is defined as the same class as, as a super class of, or as an interface implemented by the instantiated class. In any case, the target data element retains its defined class or interface type. For more information on assigning object references to ABL data elements, see the NEW statement and Assignment (=) statement reference entries.
You can use an object reference as a parameter or return type for methods, internal and external procedures, and user-defined functions (see the example).
You can pass an object reference as a parameter between an AppServer and an ABL client, although there are restrictions on the types of object you can pass. See the Parameter definition syntax entry for the full list of restrictions.
You can pass a temp-table or ProDataSet containing an object reference field as a parameter between an AppServer and an ABL client, as long as the objects themselves satisfy the restrictions described in the Parameter definition syntax entry.
You can only access PRIVATE class members using an object reference in instances of the class where the members are defined. Likewise, you can only access PROTECTED class members using an object reference in an instance of the class or subclass where the member is defined. To allow access outside of these situations, you must provide PUBLIC methods or properties to do so. For information on accessing data members, properties, or methods using an object reference, see the Class-based object reference entry.
Class-based object instances are not associated with handle-based objects, such as socket or procedure objects, and object references are not compatible with object handles. Thus, for example, you cannot use an object reference in any statement or function that returns a value of type HANDLE, and you cannot pass a procedure handle to a method that expects an object reference.
You can compare two object references for equality using the EQ (=) operator, which determines if two object references are referencing the same object instance. Two object references can be equal even when you define their data types for different classes in the same class hierarchy as long as they each point to the same class instance. So, if ClassA is a super class of ClassB, and two object references point to the same ClassB instance, if one object reference is defined with the ClassA data type and the other object reference is defined with the ClassB data type, the two object references are equal. However, if the ClassA object reference points to a different class instance than the ClassB object reference, the two object references are not equal. Two object references are also equal if they are both set to the Unknown value (?).
You can use the Equals( ) method in the Progress.Lang.Object class to compare the data members and properties of two object references, as long as this class provides an implementation of the Equals( ) method.
If object-type-name specifies a .NET object, note that in ABL you cannot instantiate the following .NET classes:
- Any .NET class that is defined in the default namespace, that is, where the class name is the complete object type name
- System.Threading.Thread or any class derived from it
- System.Delegate or any delegate type derived from it
If object-type-name specifies a GUI or non-GUI .NET object type, you can instantiate it within a non-GUI ABL session on Windows, including a:
- Character mode (CHUI) client
- Batch-mode client
- AppServer agent session
- WebSpeed agent session
However, you cannot block for any .NET object events or visualize any GUI objects in a non-GUI ABL session.
This function can raise errors during the execution of constructors for the class being instantiated, or for any class in its inherited class hierarchy. For example:
- A constructor in the class hierarchy executes the RETURN statement with the ERROR option or the UNDO statement with the THROW or RETURN ERROR options.
- The class definition file for the class, a super class, or an interface could not be found.
- The run-time parameters of the constructor for the class, or a constructor for a class in the inherited class hierarchy, are not compatible.
When the AVM encounters one of these errors, and the constructor cannot create the class instance or its inherited class hierarchy, the AVM automatically invokes the destructor for any class that has already been constructed while building the class hierarchy for the object.

For more information on errors raised by instantiating classes, see OpenEdge Development: Object-oriented Programming.
Any errors returned during class instantiation, including application errors returned by constructors executing RETURN ERROR or UNDO, THROW, are handled by the statement that invokes the NEW function. In any case, if a RETURN ERROR in the constructor of the instantiating class also returns an optional character string value, this value is available using the RETURN-VALUE function following the statement where this NEW function appears.

NEW function (classes)

Syntax

Examples

Notes

See also