S3L_DefineArray

Description

S3L_DefineArray associates an internal S3L array handle to a user-distributed parallel array. The array must be distributed in such a manner that it can be expressed as a block cyclic distribution. The array handle returned by S3L_DefineArray can then be used in subsequent calls by Sun MPI programs to S3L functions.

S3L_DefineArray does not allocate the memory required to store the local (process specific) part on the array. The user must allocate sufficient memory on each process to hold the local part of the parallel array before calling this function.

Syntax

The C and Fortran syntax for S3L_DefineArray are shown below.

C/C++ Syntax

Example 7-9

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
S3L_array_t
S3L_DefineArray(address, rank, type, extents, blocks,
sprocs, p_ext)
    void               address
    int                rank
    int                type
    int                *extents
    int                *blocks
    int                *sprocs
    int                *p_ext

F77/F90 Syntax

Example 7-10

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
integer*8 function
S3L_DefineArray(address,
rank, type, extents, blocks, sprocs, p_ext)
    <type>             array(1)
    integer*4          rank
    pointer            (addrr_a,array)
    integer*4          rank
    integer*4          type
    integer*4          extents(*)
    integer*4          blocks(*)
    integer*4          sprocs(*)
    integer*4          p_ext(*)

Input

S3L_DefineArray accepts the following arguments as input:

• address - The starting address of the local (within the process) portion of a parallel array. In C, the user must allocate this local memory (for example, via the malloc function). In F77, the address is defined as a pointer to a local storage area.

• rank - Specifies the number of dimensions the array will have. The range of legal values for rank is 1 <= rank <= 31.

• type - Denotes the parallel array's data type. In C, it is a variable of type S3L_data_type. In F77, it is a variable of type integer*4.

• extents - Specifies the extents of the parallel array.

• blocks - Specifies the blocksizes of the block cyclic distribution of the parallel array along each axis. Note that, block cyclic distribution is a general classification that includes other distribution types, such as CYCLIC(1) and BLOCK(n) distribution.

• sprocs - The starting processes of the block cyclic array distributions. If sprocs[i] = j, block 0 of the block cyclic distribution of the array along axis [i] is located in process j.

• p_ext - The extents of the process grid upon which the array is distributed. If, for example, p_ext[0] = 2, p_ext[1] = 3, p_ext[2] = 4, the three-dimensional parallel array will be distributed on a 2 x 3 x 4 process grid.

Note that process ordering within the process grid is always column major (F77 major) and that the product of the extents of the process grid must equal the total number of processes participating in the computation (that is, must equal the size of MPI_COMM_WORLD).

Error Handling

On success, S3L_DefineArray returns an S3L array handle that can be used for subsequent calls to other Sun S3L functions.

On error, it returns 0.

Examples

../examples/s3l/api
../examples/s3l/api-f

Related Functions

S3L_UnDefineArray(3)