GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


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
       universal data representation defined by the MPI Forum. This format  is
       useful for exchanging data between MPI implementations, or when writing
       data to a file.

       The input buffer is a contiguous  storage  area  pointed  to  by  inbuf
       containing  insize  bytes.  The  output buffer can be any communication
       buffer allowed in MPI_Recv, and is specified by outbuf,  outcount,  and
       datatype.

       The  input  value of position is the first position in inbuf to be read
       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
       specifies  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
       "concatenation" 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.

ERRORS

       Almost  all MPI routines return an error value; C routines as the value
       of the  function  and  Fortran  routines  in  the  last  argument.  C++
       functions  do not return errors. If the default error handler is set to
       MPI::ERRORS_THROW_EXCEPTIONS, 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
       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)



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.109 seconds. Last modified: November 04 2018 12:49:43.