42.1. new

new is used to allocate new dynamic records, dynamic ARRAYs, or data sections (collectively referred to as dynamic objects). area specifies the area in which the newly allocated object is to be put.

The CLASS form creates a new dynamic record of the CLASS c and returns a POINTER to it. All fields of the record are initialized to Zero. The returned POINTER is syntactically of the CLASS c.

If c has PROCEDURE fields, it is invalid to use them in a record created by the CLASS form of new. The compiler does not have enough information to issue an error message for p.proc, where proc is a PROCEDURE field and p is a POINTER to a record instead of a data section; however, the result of such a call is undefined.

The MODULE and STRING forms of new create a new nonbound data section for the MODULE m or the MODULE named by the STRING moduleName and return a POINTER to it. All storage within the data section is cleared. The MODULE's INITIAL PROCEDURE (if any) is invoked before returning from new. In the MODULE form, the returned POINTER is of the same CLASS as the MODULE; in the STRING form, it is unclassified. The control section associated with the allocated data section is found as described in Section 14.2.

The valid bits for ctrlBits in the MODULE and STRING forms are the same as for the system PROCEDURE bind. They are shown in Table 31–5, and apply to a MODULE allocated by new in the same way as to a MODULE allocated by bind. The msg parameter is set to an error message if new fails, as with bind.

NB: As with bind, a call to the MODULE or STRING form of new with errorOK set can return NULLPOINTER, so you should always check the return value if there is a chance it might fail.

The ARRAY forms create new ARRAY elements for a dynamic ARRAY and initialize the element values to Zero. l1, l2, and l3 are the lower bounds, and u1, u2, and u3 the upper bounds, of the first, second, and third dimension, respectively. If a bound of the ARRAY being allocated was declared as a constant, the compiler checks that the corresponding argument is the same constant. Any bound declared as a constant may be omitted, as long as all subsequent arguments are also omitted; omitted bounds are filled in by the compiler.

aryName gives the name of the ARRAY, and typeCode the type of the ARRAY. The compiler checks that typeCode is the same as the type of the ARRAY argument, unless the ARRAY argument is untyped. In practice, the programmer rarely specifies aryName or typeCode. If the ARRAY name is omitted, the compiler substitutes the name of the identifier used as the first argument. If typeCode is omitted, the compiler substitutes the type code for the type declared for the ARRAY; an error occurs if the ARRAY is untyped and typeCode is omitted.

42.1.1. Handling Errors from new

$HANDLE p := new("FOO")
$WITH
    IF $exceptionName = $systemExcpt THENB
        openLibrary("libWithFoo.olb");
        $raiseReturn; # new will try FOO again
        END
    EL  $raise;