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.

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

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.

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

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.

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

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.

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.

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.

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.

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.

If you invoke the NEW function in an expression, the class constructor cannot execute (directly or indirectly) any input-blocking statements, such as the WAIT-FOR statement (ABL only) or UPDATE statement. (The MESSAGE statement is the exception to this rule.) Otherwise, the AVM raises a run-time error. The only context in which the NEW function can call a constructor that executes these input-blocking statements is when you invoke the function in a NEW statement.

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 cannot pass an object reference as a parameter to an AppServer; nor can you pass a temp-table containing an object reference field as a parameter to an AppServer.

You can only access PUBLIC data members, properties, or methods using an object reference. You cannot access PRIVATE or PROTECTED class members using an object reference. If you want to make PRIVATE or PROTECTED class members available outside of a class instance where they are defined, you must provide PUBLIC methods or properties to do so. For information on accessing PUBLIC 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

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.