[97] | 1 | .\"Copyright 2006-2008 Sun Microsystems, Inc. |
---|
| 2 | .\" Copyright (c) 1996 Thinking Machines Corporation |
---|
| 3 | .TH MPI_Unpack_external 3 "Dec 08, 2009" "1.4" "Open MPI" |
---|
| 4 | |
---|
| 5 | .SH NAME |
---|
| 6 | \fBMPI_Unpack_external\fP \- Reads data from a portable format |
---|
| 7 | |
---|
| 8 | .SH SYNTAX |
---|
| 9 | .ft R |
---|
| 10 | |
---|
| 11 | .SH C Syntax |
---|
| 12 | .nf |
---|
| 13 | #include <mpi.h> |
---|
| 14 | int MPI_Unpack_external(char *\fIdatarep\fP, void *\fIinbuf\fP, |
---|
| 15 | MPI_Aint \fIinsize\fP, MPI_Aint *\fIposition\fP, |
---|
| 16 | void *\fIoutbuf\fP, int \fIoutcount\fP, |
---|
| 17 | MPI_Datatype \fIdatatype\fP) |
---|
| 18 | |
---|
| 19 | .SH Fortran Syntax |
---|
| 20 | .nf |
---|
| 21 | INCLUDE 'mpif.h' |
---|
| 22 | MPI_UNPACK_EXTERNAL(\fIDATAREP, INBUF, INSIZE, POSITION, |
---|
| 23 | OUTBUF, OUTCOUNT, DATATYPE, IERROR\fP) |
---|
| 24 | |
---|
| 25 | INTEGER \fIOUTCOUNT, DATATYPE, IERROR\fP |
---|
| 26 | INTEGER (KIND=MPI_ADDRESS_KIND) \fIINSIZE, POSITION\fP |
---|
| 27 | CHARACTER*(*) \fIDATAREP\fP |
---|
| 28 | <type> \fIINBUF(*), OUTBUF(*)\fP |
---|
| 29 | |
---|
| 30 | .SH C++ Syntax |
---|
| 31 | .nf |
---|
| 32 | #include <mpi.h> |
---|
| 33 | void MPI::Datatype::Unpack_external(const char* \fIdatarep\fP, |
---|
| 34 | const void* \fIinbuf\fP, MPI::Aint \fIinsize\fP, |
---|
| 35 | MPI_Aint& \fIposition\fP, void *\fIoutbuf\fP, |
---|
| 36 | int \fIoutcount\fP) const |
---|
| 37 | |
---|
| 38 | .SH INPUT PARAMETERS |
---|
| 39 | .ft R |
---|
| 40 | .TP 1i |
---|
| 41 | datarep |
---|
| 42 | Data Representation (string). |
---|
| 43 | .ft R |
---|
| 44 | .TP 1i |
---|
| 45 | inbuf |
---|
| 46 | Input buffer start (choice). |
---|
| 47 | .TP 1i |
---|
| 48 | insize |
---|
| 49 | Size of input buffer, in bytes (integer). |
---|
| 50 | .TP 1i |
---|
| 51 | outcount |
---|
| 52 | Number of items to be unpacked (integer). |
---|
| 53 | .TP 1i |
---|
| 54 | datatype |
---|
| 55 | Datatype of each output data item (handle). |
---|
| 56 | |
---|
| 57 | .SH INPUT/OUTPUT PARAMETER |
---|
| 58 | .ft R |
---|
| 59 | .TP 1i |
---|
| 60 | position |
---|
| 61 | Current position in buffer, in bytes (integer). |
---|
| 62 | |
---|
| 63 | .SH OUTPUT PARAMETERS |
---|
| 64 | .ft R |
---|
| 65 | .TP 1i |
---|
| 66 | outbuf |
---|
| 67 | Output buffer start (choice). |
---|
| 68 | .ft R |
---|
| 69 | .TP 1i |
---|
| 70 | IERROR |
---|
| 71 | Fortran only: Error status (integer). |
---|
| 72 | |
---|
| 73 | .SH DESCRIPTION |
---|
| 74 | .ft R |
---|
| 75 | MPI_Unpack_external unpacks data from the external32 format, a |
---|
| 76 | universal data representation defined by the MPI Forum. This format is |
---|
| 77 | useful for exchanging data between MPI implementations, or when |
---|
| 78 | writing data to a file. |
---|
| 79 | .sp |
---|
| 80 | The input buffer is a contiguous storage area pointed to by |
---|
| 81 | \fIinbuf\fP containing \fIinsize\fP bytes. The output buffer can be |
---|
| 82 | any communication buffer allowed in MPI_Recv, and is specified by |
---|
| 83 | \fIoutbuf\fP, \fIoutcount\fP, and \fIdatatype\fP. |
---|
| 84 | .sp |
---|
| 85 | The input value of \fIposition\fP is the first position in \fIinbuf\fP |
---|
| 86 | to be read for unpacking (measured in bytes, not elements, relative to |
---|
| 87 | the start of the buffer). When the function returns, \fIposition\fP is |
---|
| 88 | incremented by the size of the packed message, so that it points to |
---|
| 89 | the first location in \fIinbuf\fP following the message that was |
---|
| 90 | unpacked. This way it may be used as input to a subsequent call to |
---|
| 91 | MPI_Unpack_external. |
---|
| 92 | |
---|
| 93 | .SH NOTES |
---|
| 94 | .ft R |
---|
| 95 | Note the difference between MPI_Recv and MPI_Unpack_external: In |
---|
| 96 | MPI_Recv, the \fIcount\fP argument specifies the maximum number of |
---|
| 97 | items that can be received. In MPI_Unpack_external, the \fIoutcount\fP |
---|
| 98 | argument specifies the actual number of items that are to be |
---|
| 99 | unpacked. With a regular receive operation, the incoming message size |
---|
| 100 | determines the number of components that will be received. With |
---|
| 101 | MPI_Unpack_external, it is up to the user to specify how many |
---|
| 102 | components to unpack, since the user may wish to unpack the received |
---|
| 103 | message multiple times into various buffers. |
---|
| 104 | .sp |
---|
| 105 | To understand the behavior of pack and unpack, it is convenient to |
---|
| 106 | think of the data part of a message as being the sequence obtained by |
---|
| 107 | concatenating the successive values sent in that message. The pack |
---|
| 108 | operation stores this sequence in the buffer space, as if sending the |
---|
| 109 | message to that buffer. The unpack operation retrieves this sequence |
---|
| 110 | from buffer space, as if receiving a message from that buffer. (It is |
---|
| 111 | helpful to think of internal Fortran files or sscanf in C for a |
---|
| 112 | similar function.) |
---|
| 113 | .sp |
---|
| 114 | Several messages can be successively packed into one packing |
---|
| 115 | unit. This is effected by several successive related calls to |
---|
| 116 | MPI_Pack_external, where the first call provides \fIposition\fP=0, |
---|
| 117 | and each successive call inputs the value of \fIposition\fP that was |
---|
| 118 | output by the previous call, along with the same values for |
---|
| 119 | \fIoutbuf\fP and \fIoutcount\fP. This packing unit now contains the |
---|
| 120 | equivalent information that would have been stored in a message by one |
---|
| 121 | send call with a send buffer that is the "concatenation" of the |
---|
| 122 | individual send buffers. |
---|
| 123 | .sp |
---|
| 124 | A packing unit can be sent using type MPI_PACKED. Any point-to-point |
---|
| 125 | or collective communication function can be used to move the sequence |
---|
| 126 | of bytes that forms the packing unit from one process to another. This |
---|
| 127 | packing unit can now be received using any receive operation, with any |
---|
| 128 | datatype: The type-matching rules are relaxed for messages sent with |
---|
| 129 | type MPI_PACKED. |
---|
| 130 | .sp |
---|
| 131 | A packing unit can be unpacked into several successive messages. This |
---|
| 132 | is effected by several successive related calls to |
---|
| 133 | MPI_Unpack_external, where the first call provides \fIposition\fP=0, |
---|
| 134 | and each successive call inputs the value of position that was output |
---|
| 135 | by the previous call, and the same values for \fIinbuf\fP and |
---|
| 136 | \fIinsize\fP. |
---|
| 137 | .sp |
---|
| 138 | The concatenation of two packing units is not necessarily a packing |
---|
| 139 | unit; nor is a substring of a packing unit necessarily a packing |
---|
| 140 | unit. Thus, one cannot concatenate two packing units and then unpack |
---|
| 141 | the result as one packing unit; nor can one unpack a substring of a |
---|
| 142 | packing unit as a separate packing unit. Each packing unit that was |
---|
| 143 | created by a related sequence of pack calls must be unpacked as a unit |
---|
| 144 | by a sequence of related unpack calls. |
---|
| 145 | |
---|
| 146 | .SH ERRORS |
---|
| 147 | .ft R |
---|
| 148 | Almost all MPI routines return an error value; C routines as |
---|
| 149 | the value of the function and Fortran routines in the last argument. C++ |
---|
| 150 | functions do not return errors. If the default error handler is set to |
---|
| 151 | MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism |
---|
| 152 | will be used to throw an MPI:Exception object. |
---|
| 153 | .sp |
---|
| 154 | Before the error value is returned, the current MPI error handler is |
---|
| 155 | called. By default, this error handler aborts the MPI job, except for |
---|
| 156 | I/O function errors. The error handler may be changed with |
---|
| 157 | MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN |
---|
| 158 | may be used to cause error values to be returned. Note that MPI does not |
---|
| 159 | guarantee that an MPI program can continue past an error. |
---|
| 160 | .sp |
---|
| 161 | See the MPI man page for a full list of MPI error codes. |
---|
| 162 | |
---|
| 163 | .SH SEE ALSO |
---|
| 164 | .ft R |
---|
| 165 | .nf |
---|
| 166 | MPI_Pack_external |
---|
| 167 | MPI_Pack_external_size |
---|
| 168 | MPI_Recv |
---|
| 169 | sscanf(3C) |
---|
| 170 | |
---|