Sun S3L 3.0 Programming and Reference Guide

Converting Between ScaLAPACK Descriptors and S3L Array Handles

The functions described in this section make it possible to convert ScaLAPACK descriptors to S3L array handles and vice versa.

`S3L_from_ScaLAPACK_desc`

Description

S3L_from_ScaLAPACK_desc converts the ScaLAPACK descriptor and subgrid address specified by scdesc and address into an S3L array handle, which is returned in s3ldesc.

Syntax

The C and Fortran syntax for S3L_from_ScaLAPACK_desc are shown below.

C/C++ Syntax

Example 7-49

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_from_ScaLAPACK_desc(s3ldesc, scdesc, data_type, address)
    S3L_array_t        *s3ldesc
    int                *scdesc
    S3L_data_type      data_type
    void               *address

F77/F90 Syntax

Example 7-50

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_from_ScaLAPACK_desc(s3ldesc, scdesc, data_type, address, ier)
    integer*8          s3ldesc
    integer*4          scdesc(*)
    integer*4          data_type
    pointer            address
    integer*4          ier

Input

S3L_from_ScaLAPACK_desc accepts the following arguments as input:

scdesc - ScaLAPACK descriptor for a parallel array.
data_type - Specifies the data type of the S3L array. It must specify a data type supported by Sun S3L.
address - This input argument holds the starting address of an existing array subgrid.

Note -
In Fortran programs, address should either be a pointer (see the Fortran documentation for details) or the starting address of a local array, as determined by the loc(3F) function.

Output

S3L_from_ScaLAPACK_desc uses the following arguments for output:

s3ldesc - S3L array handle that is the output of S3L_from_ScaLAPACK_desc.

ier (Fortran only) - When called from a Fortran program, S3L_from_ScaLAPACK_desc returns error status in ier.

Error Handling

On success, S3L_from_ScaLAPACK_desc returns S3L_SUCCESS.

S3L_from_ScaLAPACK_desc performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause the function to terminate and return the associated error code:

S3L_ERR_ARG_NULL - The scdesc argument is a NULL pointer (C/C++) or 0 (F77/F90).

S3L_ERR_NOT_SUPPORT - The ScaLAPACK descriptor data type is not supported by Sun S3L.

S3L_ERR_PGRID_NOPROCS - The ScaLAPACK descriptor has an invalid BLACS context.

Examples

../examples/s3l/utils/scalapack_conv.c
../examples/s3l/utils-f/scalapack_conv.f

Related Functions

S3L_to_ScaLAPACK_desc(3)

`S3L_to_ScaLAPACK_desc`

Description

S3L_to_ScaLAPACK_desc converts the S3L array handle specified by s3ldesc into a ScaLAPACK array descriptor and subgrid address, which are returned in scdesc and address, respectively.

The array referred to by s3ldesc must be two-dimensional; that is, it must be a rank 2 array.

Syntax

The C and Fortran syntax for S3L_to_ScaLAPACK_desc are shown below.

C/C++ Syntax

Example 7-51

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_to_ScaLAPACK_desc(s3ldesc, scdesc, data_type, address)
    S3L_array_t        *s3ldesc
    int                *scdesc
    int                data_type
    void               **address

F77/F90 Syntax

Example 7-52

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_to_ScaLAPACK_desc(s3ldesc, scdesc, data_type, address, ier)
    integer*8          s3ldesc
    integer*4          scdesc(*)
    integer*4          data_type
    pointer            address
    integer*4          ier

Input

S3L_to_ScaLAPACK_desc accepts the following arguments as input:

s3ldesc - Contains the S3L array handle that is provided as input to S3L_to_ScaLAPACK_desc.

Output

S3L_to_ScaLAPACK_desc uses the following argument for output:

scdesc - Contains the ScaLAPACK descriptor output generated by S3L_to_ScaLAPACK_desc.

data_type - Contains the data type of the S3L array. It must specify a data type supported by Sun S3L.

address - This argument will hold the starting address of an existing array subgrid.

ier (Fortran only) - When called from a Fortran program, S3L_from_ScaLAPACK_desc returns error status in ier.

Error Handling

On success, S3L_to_ScaLAPACK_desc returns S3L_SUCCESS.

S3L_to_ScaLAPACK_desc performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause the function to terminate and return the associated error code:

S3L_ERR_ARG_NULL - The s3ldesc argument is a NULL pointer (C/C++) or 0 (F77/F90).

S3L_ERR_ARG_RANK - The S3L array handle refers to an array with a rank not equal to 2.

S3L_ERR_PGRID_NOPROCS - The ScaLAPACK descriptor has an invalid BLACS context.

Examples

../examples/s3l/utils/scalapack_conv.c
../examples/s3l/utils-f/scalapack_conv.f

Related Functions

S3L_from_ScaLAPACK_desc(3)