MPI_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
these types of files.
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 .it 1 an-trap
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).
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.
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.
All MPI objects (for example, MPI_Datatype, MPI_Comm,
MPI_File) are of type INTEGER.
SEE ALSO
MPI_File_open(3), MPI_File_get_type_extent(3), MPI_IO(3)
Man(1) output converted with
man2html