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