Sun S3L 3.0 Programming and Reference Guide

Reading Data Into and Printing From S3L Parallel Arrays

The toolkit functions described in this section allow the user to read data from a file into a parallel array, to write data from a parallel array into a local file, and to print data from a parallel array to standard output.

`S3L_read_array` and `S3L_read_sub_array`

S3L_read_array causes the process with MPI rank 0 to read the contents of a distributed array from a local file and distribute them to the processes that own the parts (subgrids) of the array. The local file is specified by the filename argument.

S3L_read_sub_array reads a specific section of the array, within the limits specified by the lbounds and ubounds arguments. The strides argument specifies the stride along each axis; it must be greater than zero. The format argument is a string that specifies the format of the file to be read. It can be either "ascii" or "binary".

The values of lbounds and ubounds should refer to zero-based indexed arrays for the C interface and to one-based indexed arrays for the Fortran interface.

Syntax

The C and Fortran syntax for S3L_read_array and S3L_read_sub_array are shown below.

C/C++ Syntax

Example 7-41

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_read_array(a, filename, format)
S3L_read_sub_array(a, lbounds, ubounds, strides, filename, format)
    S3L_array_t        a
    int                *lbounds
    int                *ubounds
    int                *strides
    char               *filename
    char               *format

F77/F90 Syntax

Example 7-42

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_read_array(a, filename, format, ier)
S3L_read_sub_array(a, lbounds, ubounds, strides, filename, format, ier)
    integer*8          a
    integer*4          lbounds(*)
    integer*4          ubounds(*)
    integer*4          strides(*)
    character*1        filename(*)
    character*1        format(*)
    integer*4          ier

Input

S3L_read_array and S3L_read_sub_array accept the following arguments as input:

a - S3L array handle for the parallel array to be read. This array handle was returned when the array was declared.

lbounds - Integer vector specifying the lower bounds of the indices of a along each of its axes.

ubounds - Integer vector specifying the upper bounds of the indices of a along each of its axes.

strides - Integer vector specifying the strides on the indices of a along each of its axes.

filename - Scalar character variable specifing the name of the file from which the parallel array will be read.

format - Scalar character variable specifing the format of the data to be read. The value can be either "ascii" or "binary".

Output

S3L_read_array and S3L_read_sub_array use the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_read_array and S3L_read_sub_array return error status in ier.

Error Handling

On success, S3L_read_array and S3L_read_sub_array return S3L_SUCCESS.

S3L_read_array and S3L_read_sub_array perform generic checking of the validity of the arrays they accept 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_RANGE_INV - The given range of indices is invalid:
- A lower bound is less that the the smallest index of the array.
- An upper bound is greater than the largest index of an array along the given axis.
- A lower bound is larger than the corresponding upper bound.
- A stride is negative or zero.

S3L_ERR_FILE_OPEN - Failed to open the file with the file name provided.

S3L_ERR_EOF - Encountered EOF while reading an array from a file.

S3L_ERR_IO_FORMAT - Format is not one of "ascii" or "binary".

S3L_ERR_IO_FILENAME - The file name is equal to the NULL string (C/C++) or to an empty string (F77/F90).

Examples

../examples/s3l/io/ex_io.c
../examples/s3l/io-f/ex_io.f

Related Functions

S3L_print_array(3)
S3L_write_array(3)

`S3L_print_array` and `S3L_print_sub_array`

S3L_print_array causes the process with MPI rank 0 to print the parallel array represented by the array handle a to standard output.

S3L_print_sub_array prints a specific section of the parallel array. This array section is defined by the lbounds, ubounds, and strides arguments. lbounds and ubounds specify the array section's lower and upper index bounds. strides specifies the stride to be used along each axis; it must be greater than zero.

Note -

The values of lbounds and ubounds should refer to zero-based indexed arrays for the C interface and to one-based indexed arrays for the Fortran interface.

Syntax

The C and Fortran syntax for S3L_print_array and S3L_print_sub_array are shown below.

C/C++ Syntax

Example 7-43

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_print_array(a)
S3L_print_sub_array(a, lbounds, ubounds, strides)
    S3L_array_t        a
    int                *lbounds
    int                *ubounds
    int                *strides

F77/F90 Syntax

Example 7-44

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_print_array(a, ier)
S3L_print_sub_array(a, lbounds, ubounds, strides, ier)
    integer*8          a
    integer*4          lbounds(*)
    integer*4          ubounds(*)
    integer*4          strides(*)
    integer*4          ier

Input

S3L_print_array and S3L_print_sub_array accept the following arguments as input:

a - S3L array handle for the parallel array to be printed. This array handle was returned when the array was declared.
lbounds - Integer vector specifying the lower bounds of the indices of a along each of its axes.
ubounds - Integer vector specifying the upper bounds of the indices of a along each of its axes.
strides - Integer vector specifying the strides on the indices of a along each of its axes.

Output

S3L_print_array and S3L_print_sub_array use the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_print_array and S3L_print_sub_array return error status in ier.

Error Handling

On success, S3L_print_array and S3L_print_sub_array return S3L_SUCCESS.

S3L_print_array and S3L_print_sub_array perform generic checking of the validity of the arrays they accept 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 condition will cause the function to terminate and return the associated error code:

S3L_ERR_ARG_RANGE_INV - The given range of indices is invalid:
- A lower bound is less that the the smallest index of the array.
- An upper bound is greater than the largest index of an array along the given axis.
- A lower bound is larger than the corresponding upper bound.
- A stride is negative or zero.

Examples

../examples/s3l/io/ex_print1.c
../examples/s3l/io/ex_io.c
../examples/s3l/io-f/ex_io.f

Related Functions

S3L_read_array(3)
S3L_write_array(3)

`S3L_write_array` and `S3L_write_sub_array`

S3L_write_array causes the process with MPI rank 0 to write the parallel array represented by the array handle a into a file specified by the filename argument. The file filename resides on the process with rank 0.

S3L_write_sub_array writes a specific section of the parallel array to filename. This section is defined by the lbounds, ubounds, and strides arguments. lbounds and ubounds specify the array section's lower and upper index bounds. strides specifies the stride along each axis; it must be greater than zero.

Note -

The values of lbounds and ubounds should refer to zero-based indexed arrays for the C interface and to one-based indexed arrays for the Fortran interface.

Syntax

The C and Fortran syntax for S3L_write_array and S3L_write_sub_array are shown below.

C/C++ Syntax

Example 7-45

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_write_array(a, filename, format)
S3L_write_sub_array(a, lbounds, ubounds, strides, filename, format)
    S3L_array_t        a
    int                *lbounds
    int                *ubounds
    int                *strides
    char               *filename
    char               *format

F77/F90 Syntax

Example 7-46

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_write_array(a, filename, format, ier)
S3L_write_sub_array(a, lbounds, ubounds, strides, filename, format,
ier)
    integer*8          a
    integer*4          lbounds(*)
    integer*4          ubounds(*)
    integer*4          strides(*)
    character*1        filename(*)
    character*1        format(*)
    integer*4          ier

Input

S3L_write_array and S3L_write_sub_array accept the following arguments as input:

a - S3L array handle for the parallel array to be written. This array handle was returned when the array was declared.
lbounds - Integer vector specifying the lower bounds of the indices of a along each of its axes.
ubounds - Integer vector specifying the upper bounds of the indices of a along each of its axes.
strides - Integer vector specifying the strides on the indices of a along each of its axes.
filename - Scalar character variable specifying the name of the file to which the parallel array will be written.
format - Scalar character variable specifying the format of the data to be written. The value can be either "ascii" or "binary".

Output

S3L_write_array and S3L_write_sub_array use the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_write_array and S3L_write_sub_array return error status in ier.

Error Handling

On success, S3L_write_array and S3L_write_sub_array return S3L_SUCCESS.

S3L_write_array and S3L_write_sub_array perform generic checking of the validity of the arrays they accept 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_RANGE_INV - The given range of indices is invalid:
- A lower bound is less that the the smallest index of the array.
- An upper bound is greater than the largest index of an array along the given axis.
- A lower bound is larger than the corresponding upper bound.
- A stride is negative or zero.

S3L_ERR_FILE_OPEN - Failed to open the file with the file name provided.

S3L_ERR_IO_FORMAT - Format is not one of "ascii" or "binary".

S3L_ERR_IO_FILENAME - The file name is equal to the NULL string (C/C++) or to an empty string (F77/F90).

Examples

../examples/s3l/io/ex_io.c
../examples/s3l/io-f/ex_io.f

Related Functions

S3L_print_array(3)
S3L_read_array(3)

Reading Data Into and Printing From S3L Parallel Arrays

S3L_read_array and S3L_read_sub_array

Syntax

C/C++ Syntax

Example 7-41

F77/F90 Syntax

Example 7-42

Input

Output

Error Handling

Examples

Related Functions

S3L_print_array and S3L_print_sub_array

Syntax

C/C++ Syntax

Example 7-43

F77/F90 Syntax

Example 7-44

Input

Output

Error Handling

Examples

Related Functions

S3L_write_array and S3L_write_sub_array

Syntax

C/C++ Syntax

Example 7-45

F77/F90 Syntax

Example 7-46

Input

Output

Error Handling

Examples

Related Functions

`S3L_read_array` and `S3L_read_sub_array`

`S3L_print_array` and `S3L_print_sub_array`

`S3L_write_array` and `S3L_write_sub_array`