MPIUnpack(3OpenMPI) MPIUnpack(3OpenMPI)

NAME
       MMPPIIUUnnppaacckk - Unpacks a datatype into contiguous memory.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIUnpack(void *inbuf, int insize, int *position,
            void *outbuf, int outcount, MPIDatatype datatype,
            MPIComm comm)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPIUNPACK(INBUF, INSIZE, POSITION, OUTBUF, OUTCOUNT,
            DATATYPE, COMM, IERROR)
                INBUF(*), OUTBUF(*)
            INTEGER   INSIZE, POSITION, OUTCOUNT, DATATYPE,
                 COMM, IERROR


CC++++ SSyynnttaaxx
       #include 
       void Datatype::Unpack(const void* inbuf, int insize,
            void *outbuf, int outcount, int& position,
            const Comm& comm) const


IINNPPUUTT PPAARRAAMMEETTEERRSS
       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).

       comm      Communicator for packed message (handle).


IINNPPUUTT//OOUUTTPPUUTT PPAARRAAMMEETTEERR
       position  Current position in bytes (integer).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       outbuf    Output buffer start (choice).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       Unpacks  a  message  into  the receive buffer specified by outbuf, out-
       count, datatype from the buffer space specified by  inbuf  and  insize.
       The  output buffer can be any communication buffer allowed in MPIRecv.
       The input buffer is a contiguous storage area containing insize  bytes,
       starting  at  address  inbuf.  The input value of position is the first
       location in the input buffer occupied by the packed  message.  position
       is  incremented  by  the size of the packed message, so that the output
       value of position is the first location in the input buffer  after  the
       locations occupied by the message that was unpacked. comm is the commu-
       nicator used to receive the packed message.


NNOOTTEESS
       Note the difference between MPIRecv and MPIUnpack: In  MPIRecv,  the
       count  argument  specifies  the  maximum  number  of  items that can be
       received. The actual number of items  received  is  determined  by  the
       length of the incoming message. In MPIUnpack, the count argument spec-
       ifies the actual number of items that are to be unpacked; the "size" of
       the  corresponding message is the increment in position. The reason for
       this change is that the "incoming message size"  is  not  predetermined
       since  the user decides how much to unpack; nor is it easy to determine
       the "message size" from the number of items to be unpacked.

       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 MPIPack, 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  outbuf, outcount, and comm. 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 "concatenation" of the
       individual send buffers.

       A packing unit can be sent using type MPIPacked. 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 MPIPacked.

       A  message  sent  with  any type (including MPIPacked) can be received
       using the type MPIPacked. Such a message can then be unpacked by calls
       to MPIUnpack.

       A packing unit (or a message created by a regular, "typed" send) can be
       unpacked into several successive messages. This is effected by  several
       successive  related  calls to MPIUnpack, 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,
       insize, and comm.

       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 or by a regular send must be unpacked
       as a unit, by a sequence of related unpack calls.


EERRRROORRSS
       Almost all MPI routines return an error value; C routines as the  value
       of  the  function  and Fortran routines in the last argument. C++ func-
       tions do not return errors. If the default  error  handler  is  set  to
       MPI::ERRORSTHROWEXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       Before the error value is returned, the current MPI  error  handler  is
       called.  By  default, this error handler aborts the MPI job, except for
       I/O  function  errors.  The  error  handler   may   be   changed   with
       MPICommseterrhandler; the predefined error handler MPIERRORSRETURN
       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 ALSO
       MPIPack
       MPIPacksize




Open MPI 1.2                    September 2006            MPIUnpack(3OpenMPI)