MPI Subroutine Reference

MPI_FILE_SET_VIEW, MPI_File_set_view

Purpose

Associates a new view with the open file.

C synopsis

#include <mpi.h>
int MPI_File_set_view (MPI_File fh,MPI_Offset disp,
    MPI_Datatype etype,MPI_Datatype filetype,
    char *datarep,MPI_Info info);

C++ synopsis

#include mpi.h
void MPI::File::Set_view(MPI::Offset disp, const MPI::Datatype& etype,
                         const MPI::Datatype& filetype, const char* datarep, 
		         const MPI::Info& info);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_FILE_SET_VIEW (INTEGER FH,INTEGER(KIND=MPI_OFFSET_KIND) DISP,
    INTEGER ETYPE,INTEGER FILETYPE,CHARACTER DATAREP(*),INTEGER INFO,
    INTEGER IERROR)

Parameters

fh

is the file handle (handle) (IN).

disp

is the displacement (long long) (IN).

etype

is the elementary datatype (handle) (IN).

filetype

is the filetype (handle) (IN).

datarep

is the data representation (string) (IN).

info

is the info object (handle) (IN).

IERROR

is the FORTRAN return code. It is always the last argument.

Description

This subroutine associates a new view defined by disp, etype, filetype, and datarep with the open file referred to by fh. This is a collective operation. All participating tasks must specify the same values for datarep and the same extents for etype.

There are no further restrictions on etype and filetype, except those referred to in the MPI-2 standard. No checking is performed on the validity of these datatypes. If I/O operations are pending on fh, an error is returned to the participating tasks and the new view is not associated with the file.

The effective use of MPI_FILE_SET_VIEW by each task of a file group can be critical to obtaining the performance benefits of MPI-IO. When the tasks each set a file view that is complementary to the views set by other tasks and use collective MPI-IO operations in conjunction with these views, the MPI library has the information that will allow it to optimize the I/O. Without the information available in the file view settings, fewer opportunities for optimization by MPI-IO exist.

Valid values for datarep are:

external32

States that read and write operations convert all data from and to the external32 representation that is documented in the MPI-2 standard.

internal

Can be used for I/O operations in a homogeneous or heterogeneous environment. IBM has defined its internal format with the intent that any implementation of MPI provided by IBM can use this format.

native

Should be used in most situations. Data in this representation is stored in a file exactly as it is in memory. This representation is always suitable in a homogeneous MPI environment and does not incur conversion costs.

File hints can be associated with a file when a view is set on it. MPI_FILE_SET_VIEW ignores the hint value if it is not valid. Any info key, value pair the user provides will either be accepted or ignored. There will never be an error returned or change in semantic as a result of a hint.

See Table 3 for a list of supported file hints.

Notes

Note that when you specify a value for the disp argument, constants of the appropriate type should be used. In FORTRAN, constants of type INTEGER(KIND=8) should be used, for example, 45_8.

It is expected that a call to MPI_FILE_SET_VIEW will immediately follow MPI_FILE_OPEN in many instances.

Parameter consistency checking is only performed if the environment variable MP_EUIDEVELOP is set to yes. If this variable is set and the extents of the elementary datatypes specified are not identical, the error Inconsistent elementary datatypes will be raised on some tasks and the error Consistency error occurred on another task will be raised on the other tasks.

Errors

Fatal errors:

MPI not initialized

MPI already finalized

Returning errors (MPI error class):

Invalid displacement (MPI_ERR_ARG)

Invalid displacement.

Invalid file handle (MPI_ERR_FILE)

fh is not a valid file handle.

MPI_DATATYPE_NULL not valid (MPI_ERR_TYPE)

Either etype or filetype has already been freed.

Undefined datatype (MPI_ERR_TYPE)

etype or filetype is not a defined datatype.

Invalid datatype (MPI_ERR_TYPE)

etype or filetype can be neither MPI_LB nor MPI_UB.

Uncommitted datatype (MPI_ERR_TYPE)

Both etype or filetype must be committed.

Invalid data representation (MPI_ERR_UNSUPPORTED_DATAREP)

datarep is not a valid data representation.

Invalid info (MPI_ERR_INFO)

info is not a valid info object.

Pending I/O operations (MPI_ERR_OTHER)

There are pending I/O operations.

Locally detected error occurred on another task (MPI_ERR_ARG)

Local parameter check failed on other task(s).

Inconsistent elementary datatypes (MPI_ERR_NOT_SAME)

Local etype extent is not consistent with the elementary datatype extent of other task(s).

Consistency error occurred on another task (MPI_ERR_ARG)

Consistency check failed on other task(s).

Related information

MPI_FILE_GET_VIEW