The following is my first pass at a short subsection to be
added to the Data Access introduction. This section would replace
*all* text under the individual data access routines, except
for a single sentence each (e.g., "MPI_READ_EXPLICIT reads data
from the file at the position specified by offset.").
Comments and corrections are welcome,
- bill
\subsubsection{Data Access Conventions}
%- - - - - - - - - - - - - - - - - - -
Data is moved between files and processes
by calling read and write routines.
Read routines move data from a file into memory.
Write routines move data from memory into a file.
The file is designated by a file handle, \mpiarg{fh}.
The location of the file data is specified by an offset
into the current view.
The data in memory is specified by a triple:
\mpiarg{buf}, \mpiarg{count}, and \mpiarg{datatype}.
Upon completion, the amount of data accessed is returned
in a \mpiarg{status}.
An offset designates the starting position in the file for an access.
The offset is always in etype units relative to the current view.
Explicit offset routines pass \mpiarg{offset} as a parameter
(negative values are erroneous).
The file pointer routines use implicit offsets maintained by \MPI/.
A data access routine attempts to transfer (read or write)
a total number of \mpiarg{count} data items
having \mpiarg{datatype} type between the user's buffer \mpiarg{buf}
and the file.
The data is accessed
from those parts of the file specified by the current view.
The type signature of \mpiarg{datatype} must match
the type signature of some number of contiguous copies of the \mpiarg{etype}
of the current view.
As in a receive,
it is erroneous to specify a \mpiarg{datatype}
for reading which contains overlapping regions
(areas of memory which would be stored into more than once).
Data access operations, when completed,
return the amount of data accessed in \mpiarg{status}.
For blocking routines, \mpiarg{status} is returned directly.
For nonblocking routines and split collective routines,
\mpiarg{status} is returned when the operation is completed.
The number of \mpiarg{etype} or \mpiarg{datatype} elements accessed
can be extracted from \mpiarg{status}
using the routines \func{MPI\_GET\_COUNT} or \func{MPI\_GET\_ELEMENTS}.
If the data access operation was cancelled,
the \funci{MPI\_TEST\_CANCELLED} routine will return \mpiarg{flag = true}.
All other fields of \mpiarg{status} are undefined.
When reading, the end of file can be detected by noting
that the amount of data read is less than the amount requested.