Given the name of a structure that defines an object class, the OBJ_NEW function returns an object reference to a new instance of the specified object type by carrying out the following operations in order:

  1. If the class structure has not been defined, IDL will attempt to find and call a procedure to define it automatically. (See Object Basics for details.) If the structure is still not defined, OBJ_NEW fails and issues an error.
  2. If the class structure has been defined, OBJ_NEW creates an object heap variable containing a zeroed instance of the class structure.
  3. Once the new object heap variable has been created, OBJ_NEW looks for a method function named Class ::INIT (where Class is the actual name of the class). If an INIT method exists, it is called with the new object as its implicit SELF argument, as well as any arguments and keywords specified in the call to OBJ_NEW. If the class has no INIT method, the usual method-searching rules are applied to find one from a superclass. For more information on methods and method-searching rules, see " Method Routines " in Chapter 2 of Objects and Object Graphics .

The INIT method is expected to initialize the object instance data as necessary to meet the needs of the class implementation. INIT should return a scalar TRUE value (such as 1) if the initialization is successful, and FALSE (such as 0) if the initialization fails.

If called without arguments, OBJ_NEW returns a NULL object reference. The NULL object reference is special value that never refers to a value object. It is primarily used as a placeholder in structure definitions, and as the initial value for elements of object arrays created via OBJARR. The null object reference is useful as an indicator that an object reference is currently not usable.

Calling Sequence

Result = OBJ_NEW( [ObjectClassName [, Arg1......Argn]] )



String giving the name of the structure type that defines the object class for which a new object should be created.

If ObjectClassName is not provided, OBJ_NEW does not create a new heap variable, and returns the Null Object , which is a special object reference that is guaranteed to never point at a valid object heap variable. The null object is a convenient value to use when defining structure definitions for fields that are object references, since it avoids the need to have a pre-existing valid object reference.


Any arguments accepted by the INIT method for the class of object being created can be specified when the object is created.


Any keywords accepted by the INIT method for the class of object being created can be specified when the object is created.