Open MPI logo

MPI_Unpack_external(3) man page (version 1.2.9)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



NAME

       MPI_Unpack_external - Reads data from a portable format

SYNTAX


C Syntax

       #include <mpi.h>
       int MPI_Unpack_external(char *datarep, void *inbuf,
            MPI_Aint insize, MPI_Aint *position,
            void *outbuf, int outcount,
            MPI_Datatype datatype)

Fortran Syntax

       INCLUDE 'mpif.h'
       MPI_UNPACK_EXTERNAL(DATAREP, INBUF, INSIZE, POSITION,
            OUTBUF, OUTCOUNT, DATATYPE, IERROR)

            INTEGER        OUTCOUNT, DATATYPE, IERROR
            INTEGER (KIND=MPI_ADDRESS_KIND) INSIZE, POSITION
            CHARACTER*(*)  DATAREP
            <type>         INBUF(*), OUTBUF(*)

C++ Syntax

       #include <mpi.h>
       void MPI::Datatype::Unpack_external(const char* datarep,
            const void* inbuf, MPI::Aint insize,
            MPI_Aint& position, void *outbuf,
            int outcount) const

INPUT PARAMETERS

       datarep   Data Representation (string).

       inbuf     Input buffer start (choice).

       insize    Size of input buffer, in bytes (integer).

       outcount  Number of items to be unpacked (integer).

       datatype  Datatype of each output data item (handle).

INPUT/OUTPUT PARAMETER

       position  Current position in buffer, in bytes (integer).

OUTPUT PARAMETERS

       outbuf    Output buffer start (choice).

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       MPI_Unpack_external  unpacks data from the external32 format, a univer-
       sal data representation defined by the MPI Forum. This format is useful
       for  exchanging  data between MPI implementations, or when writing data
       for unpacking (measured in bytes, not elements, relative to  the  start
       of  the  buffer). When the function returns, position is incremented by
       the size of the packed message, so that it points to the first location
       in  inbuf  following  the message that was unpacked. This way it may be
       used as input to a subsequent call to MPI_Unpack_external.

NOTES

       Note  the  difference  between  MPI_Recv  and  MPI_Unpack_external:  In
       MPI_Recv, the count argument specifies the maximum number of items that
       can be received. In MPI_Unpack_external, the outcount  argument  speci-
       fies the actual number of items that are to be unpacked. With a regular
       receive operation, the incoming message size determines the  number  of
       components that will be received. With MPI_Unpack_external, it is up to
       the user to specify how many components to unpack, since the  user  may
       wish  to  unpack  the  received  message  multiple  times  into various
       buffers.

       To understand the behavior of pack and  unpack,  it  is  convenient  to
       think  of  the data part of a message as being the sequence obtained by
       concatenating the successive values sent  in  that  message.  The  pack
       operation  stores  this sequence in the buffer space, as if sending the
       message to that buffer. The unpack operation  retrieves  this  sequence
       from  buffer  space, as if receiving a message from that buffer. (It is
       helpful to think of internal Fortran files or sscanf in C for a similar
       function.)

       Several messages can be successively packed into one packing unit. This
       is effected by several successive related calls  to  MPI_Pack_external,
       where  the  first  call  provides  position=0, and each successive call
       inputs the value of position that was  output  by  the  previous  call,
       along  with  the same values for outbuf and outcount. This packing unit
       now contains the equivalent information that would have been stored  in
       a  message  by one send call with a send buffer that is the "concatena-
       tion" of the individual send buffers.

       A packing unit can be sent using type MPI_PACKED. Any point-to-point or
       collective  communication  function can be used to move the sequence of
       bytes that forms the packing unit from one  process  to  another.  This
       packing  unit can now be received using any receive operation, with any
       datatype: The type-matching rules are relaxed for  messages  sent  with
       type MPI_PACKED.

       A  packing  unit can be unpacked into several successive messages. This
       is effected by several successive related calls to MPI_Unpack_external,
       where  the  first  call  provides  position=0, and each successive call
       inputs the value of position that was output by the previous call,  and
       the same values for inbuf and insize.

       The  concatenation  of  two  packing units is not necessarily a packing
       unit; nor is a substring of a packing unit necessarily a packing  unit.
       Thus,  one  cannot  concatenate  two  packing units and then unpack the
       result as one packing unit; nor can one unpack a substring of a packing
       unit  as a separate packing unit. Each packing unit that was created by
       a related sequence of pack calls must  be  unpacked  as  a  unit  by  a
       sequence of related unpack calls.

       called. By default, this error handler aborts the MPI job,  except  for
       I/O   function   errors.   The   error  handler  may  be  changed  with
       MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN
       may  be  used  to cause error values to be returned. Note that MPI does
       not guarantee that an MPI program can continue past an error.

       See the MPI man page for a full list of MPI error codes.

SEE ALSO

       MPI_Pack_external
       MPI_Pack_external_size
       MPI_Recv
       sscanf(3C)

Open MPI 1.2                    September 2006   MPI_Unpack_external(3OpenMPI)

« Return to documentation listing