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 | |
---|