| MPI_FILE_SET_VIEW(fh, disp, etype, filetype, datarep, info) | |
| INOUT fh | file handle (handle) |
| IN disp | displacement (integer) |
| IN etype | elementary datatype (handle) |
| IN filetype | filetype (handle) |
| IN datarep | data representation (string) |
| IN info | info object (handle) |
int MPI_File_set_view(MPI_File fh, MPI_Offset disp, MPI_Datatype etype, MPI_Datatype filetype, char *datarep, MPI_Info info)
The MPI_FILE_SET_VIEW routine changes the process's view
of the data in the file.
The start of the view is set to disp;
the type of data is set to etype;
the distribution of data to processes is set to filetype;
and the representation of data in the file is set to datarep.
In addition,
MPI_FILE_SET_VIEW resets the individual file pointers and the
shared file pointer to zero.
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 may vary.
The datatypes passed in etype and filetype must
be committed.
The etype always specifies the data layout in the file.
If etype is a portable datatype (see Section Semantic Terms
, page Semantic Terms
),
the extent of etype is computed by scaling any displacements
in the datatype to match the file data representation.
If etype is not a portable datatype,
no scaling is done when computing the extent of etype.
The user must be careful when using nonportable etypes
in heterogeneous environments;
see Section Datatypes for File Interoperability
, page Datatypes for File Interoperability
for further details.
If MPI_MODE_SEQUENTIAL mode was specified when the file was opened,
the special displacement MPI_DISPLACEMENT_CURRENT must be
passed in disp.
This sets the displacement to the current position
of the shared file pointer.
MPI_DISPLACEMENT_CURRENT is invalid unless the amode for the
file has MPI_MODE_SEQUENTIAL set.
For some sequential files,
such as those corresponding to magnetic tapes or streaming network connections,
the displacement may not be meaningful.
MPI_DISPLACEMENT_CURRENT allows the view to be changed
for these types of files.
( End of rationale.)
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.
( End of advice to implementors.)
disp can be used to skip headers or when the file includes a
sequence of data segments that are to be accessed in different patterns
(see Figure 27
).
Separate views,
each using a different displacement and filetype,
can be used to access each segment.
MPI_FILE_SET_VIEW(FH, DISP, ETYPE, FILETYPE, DATAREP, INFO, IERROR)
INTEGER FH, ETYPE, FILETYPE, INFO, IERROR
CHARACTER*(*) DATAREP
INTEGER(KIND=MPI_OFFSET_KIND) DISP
{ void MPI::File::Set_view(MPI::Offset disp, const MPI::Datatype& etype, const MPI::Datatype& filetype, const char* datarep, const MPI::Info& info) (binding deprecated, see Section Deprecated since MPI-2.2
) }
Rationale.
Advice
to implementors.
The disp displacement argument specifies the position
(absolute offset in bytes from the beginning of the file)
where the view begins.
Advice to users.
( End of advice to users.)
In order to ensure interoperability in a heterogeneous environment,
additional restrictions must be observed when constructing the etype
(see Section File Interoperability
, page File Interoperability
).
( End of advice to users.)
If the file is opened for writing,
neither the etype nor the filetype is permitted
to contain overlapping regions.
This restriction is equivalent to the ``datatype used in a receive
cannot specify overlapping regions'' restriction for communication.
Note that filetypes from different processes may still
overlap each other.
If filetype has holes in it,
then the data in the holes is inaccessible to the calling process.
However, the disp, etype and filetype
arguments can be changed via future calls to MPI_FILE_SET_VIEW
to access a different part of the file.
It is erroneous to use absolute addresses in the construction
of the etype and filetype.
The info argument is used to provide information
regarding file access patterns and file system specifics
to direct optimization
(see Section File Info
, page File Info
).
The constant MPI_INFO_NULL refers to the null info
and can be used when no info needs to be specified.
The datarep argument is a string that specifies
the representation of data in the file.
See the file interoperability section
(Section File Interoperability
, page File Interoperability
)
for details and a discussion of valid values.
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.
int MPI_File_get_view(MPI_File fh, MPI_Offset *disp, MPI_Datatype *etype, MPI_Datatype *filetype, char *datarep)
MPI_FILE_GET_VIEW returns the process's view
of the data in the file.
The current value of the displacement is returned in disp.
The etype and filetype are new datatypes
with typemaps equal to the typemaps
of the current etype and filetype, respectively.
The data representation is returned in datarep.
The user is responsible for ensuring that datarep is
large enough to hold the returned data representation string.
The length of a data representation string is limited to the value of
MPI_MAX_DATAREP_STRING.
In addition, if a portable datatype was used to set the current view,
then the corresponding datatype returned by MPI_FILE_GET_VIEW
is also a portable datatype.
If etype or filetype are derived datatypes,
the user is responsible for freeing them.
The etype and filetype returned are both in a
committed state.
An etype ( elementary datatype)
is the unit of data access and positioning.
It can be any MPI predefined or derived datatype.
Derived etypes can be constructed
by using any of the MPI datatype constructor routines,
provided all resulting typemap displacements are
non-negative and monotonically nondecreasing.
Data access is performed in etype units,
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.
Advice to users.
A filetype is either a single etype or a derived MPI datatype
constructed from multiple instances of the same etype.
In addition,
the extent of any hole in the filetype
must be a multiple of the etype's extent.
These displacements are not required to be distinct,
but they cannot be negative,
and they must be monotonically nondecreasing.
MPI_FILE_GET_VIEW(fh, disp, etype, filetype, datarep) IN fh file handle (handle) OUT disp displacement (integer) OUT etype elementary datatype (handle) OUT filetype filetype (handle) OUT datarep data representation (string)
MPI_FILE_GET_VIEW(FH, DISP, ETYPE, FILETYPE, DATAREP, IERROR)
INTEGER FH, ETYPE, FILETYPE, IERROR
CHARACTER*(*) DATAREP
INTEGER(KIND=MPI_OFFSET_KIND) DISP
{ void MPI::File::Get_view(MPI::Offset& disp, MPI::Datatype& etype, MPI::Datatype& filetype, char* datarep) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
Up: Contents
Next: Data Access
Previous: Reserved File Hints
Return to MPI-2.2 Standard Index
Return to MPI Forum Home Page
(Unofficial) MPI-2.2 of September 4, 2009
HTML Generated on September 10, 2009