MPI_File_set_view(3)MPI_File_set_view(3)NAMEMPI_File_set_view - Sets the file view
SYNOPSIS
C:
#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)
Fortran:
INCLUDE "mpif.h" (or USE MPI)
INTEGER fh, etype, filetype, info, ierror
CHARACTER*(*) datarep
INTEGER(KIND=MPI_OFFSET_KIND) disp
CALL MPI_FILE_SET_VIEW(fh, disp, etype, filetype,
datarep, info, ierror)
DESCRIPTION
The MPI_File_set_view routine changes the process view of the data in the
file and resets the individual file pointers and the shared file pointer
to zero.
MPI_File_set_view accepts the following arguments:
fh Specifies the file handle (handle). The user is responsible for
ensuring that all nonblocking requests and split collective
operations on fh have been completed before calling
MPI_File_set_view; otherwise, the call to MPI_File_set_view is
erroneous.
disp Specifies displacement (nonnegative integer), the position at
which the view begins. disp is specified as an absolute offset
in bytes from the beginning of the file.
If MPI_MODE_SEQUENTIAL mode was specified when the file was
opened, the special displacement, MPI_DISPLACEMENT_CURRENT,
must be passed in disp. This value sets the displacement to
the current position of the shared file pointer.
For some sequential files, such as those corresponding to
magnetic tapes or streaming network connections, the
displacement might not be meaningful. The
MPI_DISPLACEMENT_CURRENT displacement allows the view to be
changed for these types of files.
Page 1
MPI_File_set_view(3)MPI_File_set_view(3)
You can use the disp argument to skip headers or when the file
includes a sequence of data segments that are to be accessed in
different patterns. You can use separate views, each using a
different displacement and file type, to access each segment.
etype Specifies elementary data type (handle). Elementary data type
is the unit of data access and positioning. It can be any MPI
predefined or derived data type. The etype argument always
specifies the data layout in the file.
If etype is a portable data type, you can compute the extent of
etype by scaling any displacements in the data type to match
the file data representation. If etype is not a portable data
type, no scaling is done when the extent of etype is computed.
The user must be careful when using a nonportable etype in a
heterogeneous environment (see the .ft3 Ensuring
Interoperability in a Heterogeneous Environment subsection).
You can construct derived elementary data types by using any of
the MPI data type constructor routines, provided all resulting
typemap displacements are nonnegative and monotonically
nondecreasing. Data access is performed in etype units, by
reading or writing whole data items of type etype. Offsets are
expressed as a count of etypes; file pointers point to the
beginning of etypes.
You must not use absolute addresses to construct the etype
argument.
filetype Specifies the file type (handle). filetype is either a single
etype or a derived MPI data type constructed from multiple
instances of the same etype. In addition, the extent of any
hole in filetype must be a multiple of the extent of etype.
These displacements are not required to be distinct, but they
cannot be negative, and they must be monotonically
nondecreasing.
You must not use absolute addresses to construct the filetype
argument.
datarep Specifies the representation of data in the file (string).
info Provides information regarding file access patterns and file
system specifics to direct optimization (handle). The constant,
MPI_INFO_NULL, refers to info that is null and can be used when
no information needs to be specified.
ierror Specifies the return code value for successful completion,
which is in MPI_SUCCESS. MPI_SUCCESS is defined in the mpif.h
file.
Page 2
MPI_File_set_view(3)MPI_File_set_view(3)MPI_File_set_view is collective; the values for datarep and the extents
of etype in the file data representation must be identical on all
processes in the group; values for disp, filetype, and info can vary.
The data types passed in etype and filetype must be committed.
If filetype has holes in it, the data in the holes is inaccessible to the
calling process. However, the disp, etype, and filetype arguments can be
changed by future calls to MPI_File_set_view to access a different part
of the file.
If the file is opened for writing, neither etype nor filetype is
permitted to contain overlapping regions. This restriction is equivalent
to the data type used in a receive cannot specify overlapping regions
restriction for communication. Note that file types from different
processes can still overlap each other.
It is expected that a call to MPI_File_set_view will immediately follow
MPI_File_open in numerous instances. A high quality implementation will
ensure that this behavior is efficient.
Ensuring Interoperability in a Heterogeneous Environment
To ensure interoperability in a heterogeneous environment, additional
restrictions must be observed when constructing the etype or filetype
arguments. Any of the data type constructor functions can be used;
however, for those functions that accept displacements in bytes, the
displacements must be specified in terms of their values in the file for
the file data representation being used. MPI interprets these byte
displacements as is; no scaling will be done. You can use the
MPI_File_get_type_extent function to calculate the extents of data types
in the file. For the etype and filetype arguments that are portable data
types, MPI will scale any displacements in the datatypes to match the
file data representation. Data types passed as arguments to read/write
routines specify the data layout in memory; therefore, when constructing
them, you must always use displacements that correspond to displacements
in memory.
Notes for Fortran
All MPI objects (for example, MPI_Datatype, MPI_Comm, MPI_File) are of
type INTEGER.
SEE ALSOMPI_File_open(3), MPI_File_get_type_extent(3), MPI_IO(3)
Page 3
