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)