The NEW procedure allocates memory for the dynamic variable to
which a pointer variable refers. The value of the newly
allocated variable is set to the initial value of the base type
if defined; otherwise, the value of the variable is undefined.
Syntax:
NEW( p [[, {t1,...,tn | d1,...,dn} ]] )
The parameter 'p' is a 32-bit pointer variable. On OpenVMS
Alpha and OpenVMS I64, the parameter 'p' may also be a 64-bit
pointer variable.
The parameters 't1,...,tn' are constant expressions of an
ordinal type that represent nested tag-field values, where 't1'
is the outermost variant.
If the object of the pointer is a non-schema record type with
variants, then you have two ways of allocating memory. If you
do not specify 't' parameters, VSI Pascal allocates enough
memory to hold any of the variants of the record. If you do
specify 't' parameters, then VSI Pascal allocates enough memory
to hold only the variant or variants that you specify.
Since the 't' parameters cause VSI Pascal to allocate memory for
the variant alone and not for the whole record, you cannot
assign or evaluate the record as a whole; you can assign and
evaluate only the individual fields. Also, a call to NEW does
not set the tag fields of a variant record.
The paramters 'd1,...,dn' are compile-time or run-time ordinal
values that must be the same type as the formal discriminants of
the object.
If the object of the pointer is of an undiscriminated schema
type, you must specify a 'd' parameter for each of the formal
discriminants of the schema type. The 'd' parameters
discriminate the schema type in much the same way as actual
discriminants in a discriminated schema. HP Pascal bases the
size of the allocation on the value of the 'd' parameters.
If the object is a schema record type, then you must use 'd'
parameters; you cannot use 't' parameters or a combination of
the syntaxes. If the schema record type contains a variant
(which depends on one of the formal discriminants) then the 'd'
parameter discriminates the schema, determines the variant, and
allows VSI Pascal to compute the necessary size of the
allocation.
Note that if you specify 't' parameters to the NEW procedure,
you must specify the same 't' parameters to the DISPOSE
procedure that deallocates memory for the corresponding
variable.
If the parameter 'p' is a 64-bit pointer variable, the NEW
procedure will call LIB$GET_VM_64 to allocate memory from "P2"
space. Likewise, DISPOSE of a 64-bit pointer expression will
call LIB$FREE_VM_64 to return the memory.