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.

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)