ALLOCATE Statement

Developer Guide and Reference

Download PDF

ID 767251

Date 10/31/2024

Version

Public

Visible to Intel only — GUID: GUID-2E8BB6B6-6454-4DB6-9982-5BD97DEB47C1

View Details

ALLOCATE Statement

Statement: Dynamically creates storage for allocatable variables and pointer targets.

ALLOCATE ([type::] object[(s-spec[, s-spec]...)] [, object[(s-spec[, s-spec]...)] ]... [[coarray-spec]]...[, alloc-opt[, alloc-opt]...])

type

Is a data type specifier. If specified, the kind type parameters of each object must be the same as the corresponding type parameter values, and each object must be type compatible with the specified type.

You cannot specify type if you specify SOURCE= or MOLD=.

A type parameter value in type can be an asterisk if and only if each object is a dummy argument for which the corresponding type parameter is assumed.

object

Is the object to be allocated. It is a variable name or structure component, and must be a pointer or an allocatable object. The object can be of type character with zero length. The object cannot be coindexed.

If any object has a deferred type parameter, is unlimited polymorphic, or is of ABSTRACT type, either type or source-expr must appear.

If the object is a coarray and type is specified, type cannot be C_PTR, C_FUNPTR, or TEAM_TYPE.

If the object is a coarray and SOURCE= is specified, the declared type of source-expr cannot be C_PTR, C_FUNPTR, or TEAM_TYPE.

If object is an array, s-spec must appear and the number of s-specs must equal the rank of object, or source-expr must appear and have the same rank as object and the shape of object is that of source-expr.

If both s-spec and SOURCE=source-expr appear, source-expr must be scalar.

If object is scalar, no s-spec should appear.

If SOURCE=source-expr appears, object is initialized with the value of source-expr.

s-spec

Is an array shape specification in the form [lower-bound:]upper-bound. Each bound must be a scalar integer expression. The number of shape specifications must be the same as the rank of the object.

You can specify an s-spec list for each array object in an ALLOCATE statement.

coarray-spec

Is a coarray shape specification in the form:

[[lower-bound:] upper-bound, ] ... [lower-bound:] *

The brackets around coarray-spec are required.

A coarray shape specification can only appear if the object is a coarray. The number of coarray specifications must be one less than the corank of the coarray object.

alloc-opt

Can be any of the following keywords:

STAT=stat-var

(Output) The stat-var is a scalar integer variable in which the status of the allocation is stored.

If no STAT= stat-var is specified and an error condition occurs, the program initiates error termination.

ERRMSG=err-var

(Output) The err-var is a scalar default character variable in which an error condition is stored if such a condition occurs.

SOURCE=source-expr
MOLD=source-expr

(Input) The source-expr is an expression that is scalar or has the same rank as object.

If MOLD= or SOURCE= is specified, type cannot be specified and each object must have the same rank as source-expr unless source-expr is scalar.

Only one of MOLD= or SOURCE= can appear in the same ALLOCATE statement.

If MOLD= appears and source-expr is a variable, its value does not have to be defined.

If source-expr appears and its declared type is C_PTR, C_FUNPTR, or TEAM_TYPE, object cannot be a coarray.

If SOURCE is specified, source-expr cannot have a declared type of EVENT_TYPE or LOCK_TYPE from the intrinsic module ISO_FORTRAN_ENV, or have a potential subobject component that is a coarray, or have a type of EVENT_TYPE or LOCK_TYPE.

You can specify STAT=, ERRMSG=, and one of MOLD= or SOURCE= in the same ALLOCATE statement. The keywords can appear in any order.

Description

The storage space allocated is uninitialized unless SOURCE= is specified or the type of the object is default initialized.

A bound in s-spec must not be an expression containing an array inquiry function whose argument is any allocatable object in the same ALLOCATE statement; for example, in this code, the last line is not permitted:

INTEGER ERR
INTEGER, ALLOCATABLE :: A(:), B(:)
...
ALLOCATE(A(10:25), B(SIZE(A)), STAT=ERR)  ! A is invalid as an argument to function SIZE

If a STAT=stat-var, ERRMSG=err-var, or source-expr is specified, it must not be allocated in the ALLOCATE statement in which it appears; nor can it depend on the value, bounds, length type parameters, allocation status, or association status of any object in the same ALLOCATE statement.

If the allocation is successful, the STAT=stat-var becomes defined with the value zero, and the definition status of the ERRMSG=err-var remains unchanged. If the allocation is not successful, an error condition occurs, and the STAT=stat-var is set to a positive integer value (representing the runtime error); the ERRMSG=err-var contains a descriptive message about the error condition.

If the allocation is successful and source-expr is specified, the dynamic type and value of the allocated object becomes that of the source expression. If the value of a non-deferred length type parameter of object is different from the value of the corresponding type parameter of source-expr, an error condition occurs.

When an ALLOCATE statement is executed for an object that is a coarray, there is an implicit synchronization of all images. On each image, execution of the segment following the statement is delayed until all other images have executed the same statement the same number of times.

The following rules apply if the ALLOCATE object is a coarray:

The coarray's dynamic type and values of any type parameters must be the same in every active image of the current team.
The value of the bounds and cobounds must be the same in all those images.
If the coarray is an ultimate component of an array element, it must be the same array element in all those images.
If the coarray is an ultimate component of a polymorphic object, the object must have the same set of coarray components.
If the coarray is a dummy argument, the ultimate arguments in those images must be corresponding coarrays.
If the coarray is an ultimate component of a dummy argument, the ultimate arguments in those images must be declared with the same name in the same scooping unit.
If the ultimate argument is a local variable of a recursive procedure and it does not have the SAVE attribute, the execution of the ALLOCATE statement must be at the same depth of recursion of that procedure in each of the current teams active images.
If the coarray is an ultimate component of an array element, the element must have the same array element order position in all those images.
If the coarray is a local variable of a recursive procedure and does not have the SAVE attribute, execution of the ALLOCATE statement must be at the same dept of recursion of that procedure in all those images.

If an ALLOCATE or DEALLOCATE statement with a coarray allocatable object is executed when one or more images of the current team has initiated normal termination, the STAT=stat-var becomes defined with the processor-dependent positive integer value of the constant STAT_STOPPED_IMAGE from the intrinsic module ISO_FORTRAN_ENV. Otherwise, if an allocatable object is a coarray and one or more images of the current team has failed, the STAT=stat-var becomes defined with the processor-dependent positive integer value of the constant STAT_FAILED_IMAGE from the intrinsic module ISO_FORTRAN_ENV.

If any other error condition occurs during execution of the ALLOCATE or DEALLOCATE statement, the STAT=stat-var becomes defined with a processor-dependent positive integer value different from STAT_STOPPED_IMAGE or STAT_FAILED_IMAGE.

If an ALLOCATE or DEALLOCATE statement with a coarray allocatable object is executed when one or more images of the current team has failed, each allocatable object is successfully allocated or deallocated on the active images of the current team. If any other error occurs, the allocation status of each allocatable object is processor dependent:

Successfully allocated allocatable objects have the allocation status of allocated, or associated if the allocate object is has the POINTER attribute.
Successfully deallocated allocatable objects have the allocation status of deallocated, or disassociated if the allocatable object has the POINTER attribute.
An allocatable object that was not successfully allocated or deallocated has its previous allocation status, or its previous association status if it has the POINTER attribute.

To release the storage for an object, use DEALLOCATE.

To determine whether an allocatable object is currently allocated, use the ALLOCATED intrinsic function.

To determine whether a pointer is currently associated with a target, use the ASSOCIATED intrinsic function.

Example

The following example shows a method for creating and allocating deferred shape arrays:

  
  INTEGER,ALLOCATABLE::matrix(:,:)
  REAL, ALLOCATABLE:: vector(:)
  . . .
  ALLOCATE (matrix(3,5),vector(-2:N+2))
  . . .

The following example allocates the scalar character variable CH with character length N, an 81-element array A of type default real, and a J+5 x N element array B of type default real:

  INTEGER J, N, ALLOC_ERR
  CHARACTER(LEN=:),ALLOCATABLE :: CH
  REAL, ALLOCATABLE :: A(:), B(:,:)
  ...
  ALLOCATE(CH(N), A(0:80), B(-3:J+1, N), STAT = ALLOC_ERR)

In the above example, if an error occurs during allocation, the variable ALLOC_ERR will be assigned a non-zero error code and execution continues after the ALLOCATE statement. If no error occurs, the value of ALLOC_ERR will be zero upon completion of the ALLOCATE statement.

The following example allocates s and t to be 15 by 25 arrays with the values of r:

REAL(KIND=8) :: r(15, 25)
REAL(KIND=8), ALLOCATABLE :: s(:,:), t(:,:)
...
ALLOCATE(s,SOURCE=r)
ALLOCATE(t,SOURCE=r)

Parent topic: A to B

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Guide and Reference

ALLOCATE Statement

Description

Example

See Also