ALLOCATE

Purpose

The ALLOCATE statement dynamically provides storage for pointer targets and allocatable objects.

Syntax


>>-ALLOCATE----------------------------------------------------->

>--(--+-----------------------+--allocation_list--+-----------------------------+-->
      |                   (1) |                   '-,--STAT-- = --stat_variable-'   
      '-i_d_type_spec--::-----'                                                     

>--+-------------------------------------+--+-------------------------------------+--)-><
   |                                 (2) |  |             (3)                     |      
   '-,--ERRMSG-- = --errmsg_variable-----'  '-,--+-SOURCE-----+-- = --source_expr-'      
                                                 |      (4)   |                          
                                                 '-MOLD-------'

Notes:

Fortran 2003
Fortran 2003
Fortran 2003
Fortran 2008

stat_variable: A scalar integer variable.

errmsg_variable (Fortran 2003): A scalar character variable.
source_expr (Fortran 2003): An expression that is scalar or has the same rank as allocate_object.
i_d_type_spec (Fortran 2003): Is an intrinsic_type_spec or derived_type_spec. See Type Declaration for a list of possible type specifications.

allocation_list


   .-,--------------------------------------------------------------.   
   V                                                                |   
>>---allocate_object--+-------------------------------------------+-+-><
                      |    .-,-------------------------------.    |     
                      |    V                                 |    |     
                      '-(----+----------------+--upper_bound-+--)-'     
                             '-lower_bound--:-'

allocate_object: A variable name or structure component that must be a data pointer or an allocatable object.
lower_bound: A scalar integer expression.
upper_bound: A scalar integer expression.

Constraints

You cannot specify i_d_type_spec and source_expr at the same time.

If any allocate_object has deferred type parameters, is unlimited polymorphic F2008 begins , or is of an abstract type F2008 ends , i_d_type_spec or source_expr must appear.

i_d_type_spec must specify a type with which each allocate_object is type compatible.

A type parameter value in i_d_type_spec must be an asterisk if and only if each allocate_object is a dummy argument whose corresponding type parameter is assumed.

The kind type parameter values of each allocate_object must be the same as the corresponding type parameter values of i_d_type_spec.

If allocate_object is an array, you must specify either the array bounds or source_expr with the same rank as allocate_object. If allocate_object is scalar, array bounds cannot be specified.

F2008 begins If source_expr appears, each allocate_object must be type-compatible with source_expr. F2008 ends

Corresponding kind type parameters of allocate_object and source_expr must have the same values.

Rules

Execution of an ALLOCATE statement for a pointer causes the pointer to become associated with the target allocated. Execution of an ALLOCATE statement for an allocatable object causes the object to become definable.

If you specify bounds for an array, the number of dimensions specified (that is, the number of upper bounds in allocation_list) must be equal to the rank of allocate_object. F2008 begins Otherwise, you must specify SOURCE= or MOLD=, and the bounds of source_expr determine the bounds of the array. Subsequent changes to the bounds of source_expr do not affect the array bounds after they are determined. F2008 ends

F2003 begins If i_d_type_spec is specified, each allocate_object is allocated with the specified dynamic type and type parameter values. If source_expr is specified, each allocate_object is allocated with the dynamic type and type parameter values of source_expr. Otherwise, each allocate_object is allocated with the same dynamic type as its declared type.

When an ALLOCATE statement is executed for an array, the values of the bounds are determined at that time. Subsequent redefinition or undefinition of any entities in the bound expressions does not affect the array specification. Any lower bound, if omitted, is assigned a default value of 1. If any lower bound value exceeds the corresponding upper bound value, that dimension has an extent of 0 and allocate_object is zero-sized.

Any allocate_object or a specified bound of an allocate_object must not depend on the value of stat_variable or errmsg_variable, or on the value, bounds, length type parameters, allocation status, or association status of any allocate_object in the same ALLOCATE statement.

stat_variable,source_expr, and errmsg_variable must not be allocated within the ALLOCATE statement in which they appear. They also must not depend on the value, bounds, length type parameters, allocation status, or association status of any allocate_object in the same ALLOCATE statement. F2003 ends

F2008 begins If you specify MOLD= and source_expr is a variable, its value need not be defined. In addition, MOLD= does not copy the value of source_expr to the variable to be allocated. F2008 ends

If the STAT= specifier is not present and an error condition occurs during execution of the statement, the program terminates. If the STAT= specifier is present, the stat_variable is assigned one of the following values:

Stat value	Error condition
0	No error
1	Error in system routine attempting to do allocation
2	An invalid data object has been specified for allocation
3	Both error conditions 1 and 2 have occurred

If an error condition occurs during execution of the ALLOCATE statement and the ERRMSG=specifier is present, an explanatory message is assigned to errmsg_variable. If no such condition occurs, the value of errmsg_variable is not changed.

Allocating an allocatable object that is already allocated causes an error condition in the ALLOCATE statement.

Pointer allocation creates an object that has the TARGET attribute. Additional pointers can be associated with this target (or a subobject of it) through pointer assignment. If you reallocate a pointer that is already associated with a target:

A new target is created and the pointer becomes associated with this target.
Any previous association with the pointer is broken.
Any previous target that had been created by allocation and is not associated with any other pointers becomes inaccessible.

When an object of derived type is created by an ALLOCATE statement, any allocatable ultimate components have an allocation status of not allocated.

Use the ALLOCATED intrinsic function to determine if an allocatable object is allocated. Use the ASSOCIATED intrinsic function to determine the association status of a pointer or whether a pointer is associated with a specified target.

Examples

CHARACTER, POINTER :: P(:,:)
CHARACTER, TARGET :: C(4,4)
INTEGER, ALLOCATABLE, DIMENSION(:) :: A
P => C
N = 2; M = N
ALLOCATE (P(N,M),STAT=I)         ! P is no longer associated with C
N = 3                            ! Target array for P maintains 2X2 shape
IF (.NOT.ALLOCATED(A)) ALLOCATE (A(N**2))
END

The following example uses the MOLD= specifier in an ALLOCATE statement in which the bounds are determined by reference to another object:

INTEGER, ALLOCATABLE :: NEW(:)
INTEGER, POINTER :: OLD(:)
ALLOCATE(OLD(4))
ALLOCATE (NEW, MOLD=OLD) ! Allocate NEW with the bounds of OLD
END

Related information

Voice your opinion on getting help information

Ask IBM compiler experts a technical question in the IBM XL compilers forum