1 | .\"Copyright 2006-2008 Sun Microsystems, Inc. |
---|
2 | .\" Copyright (c) 1996 Thinking Machines Corporation |
---|
3 | .TH MPI_Pack_external 3 "Dec 08, 2009" "1.4" "Open MPI" |
---|
4 | |
---|
5 | .SH NAME |
---|
6 | \fBMPI_Pack_external\fP \- Writes data to a portable format |
---|
7 | |
---|
8 | .SH SYNTAX |
---|
9 | .ft R |
---|
10 | |
---|
11 | .SH C Syntax |
---|
12 | .nf |
---|
13 | #include <mpi.h> |
---|
14 | int MPI_Pack_external(char *\fIdatarep\fP, void *\fIinbuf\fP, |
---|
15 | int \fIincount\fP, MPI_Datatype\fI datatype\fP, |
---|
16 | void *\fIoutbuf\fP, MPI_Aint \fIoutsize\fP, |
---|
17 | MPI_Aint *\fIposition\fP) |
---|
18 | |
---|
19 | .SH Fortran Syntax |
---|
20 | .nf |
---|
21 | INCLUDE 'mpif.h' |
---|
22 | MPI_PACK_EXTERNAL(\fIDATAREP, INBUF, INCOUNT, DATATYPE, |
---|
23 | OUTBUF, OUTSIZE, POSITION, IERROR\fP) |
---|
24 | |
---|
25 | INTEGER \fIINCOUNT, DATATYPE, IERROR\fP |
---|
26 | INTEGER (KIND=MPI_ADDRESS_KIND) \fIOUTSIZE, 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::Pack_external(const char* \fIdatarep\fP, |
---|
34 | const void* \fIinbuf\fP, int \fIincount\fP, |
---|
35 | void* \fIoutbuf\fP, MPI::Aint \fIoutsize\fP, |
---|
36 | MPI::Aint& \fIposition\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 | incount |
---|
49 | Number of input data items (integer). |
---|
50 | .TP 1i |
---|
51 | datatype |
---|
52 | Datatype of each input data item (handle). |
---|
53 | .TP 1i |
---|
54 | outsize |
---|
55 | Output buffer size, in bytes (integer). |
---|
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 | .TP 1i |
---|
69 | IERROR |
---|
70 | Fortran only: Error status (integer). |
---|
71 | |
---|
72 | .SH DESCRIPTION |
---|
73 | .ft R |
---|
74 | MPI_Pack_external packs data into the external32 format, a universal |
---|
75 | data representation defined by the MPI Forum. This format is useful |
---|
76 | for exchanging data between MPI implementations, or when writing data |
---|
77 | to a file. |
---|
78 | .sp |
---|
79 | The input buffer is specified by \fIinbuf\fP, \fIincount\fP and |
---|
80 | \fIdatatype\fP, and may be any communication buffer allowed in |
---|
81 | MPI_Send. The output buffer \fIoutbuf\fP must be a contiguous storage |
---|
82 | area containing \fIoutsize\fP bytes. |
---|
83 | .sp |
---|
84 | The input value of \fIposition\fP is the first position in |
---|
85 | \fIoutbuf\fP to be used for packing (measured in bytes, not elements, |
---|
86 | relative to the start of the buffer). When the function returns, |
---|
87 | \fIposition\fP is incremented by the size of the packed message, so |
---|
88 | that it points to the first location in \fIoutbuf\fP following the |
---|
89 | packed message. This way it may be used as input to a subsequent call |
---|
90 | to MPI_Pack_external. |
---|
91 | .sp |
---|
92 | |
---|
93 | \fBExample:\fP An example using MPI_Pack_external: |
---|
94 | .sp |
---|
95 | .nf |
---|
96 | int position, i; |
---|
97 | double msg[5]; |
---|
98 | char buf[1000]; |
---|
99 | |
---|
100 | \&... |
---|
101 | |
---|
102 | MPI_Comm_rank(MPI_COMM_WORLD, &myrank); |
---|
103 | if (myrank == 0) { /* SENDER CODE */ |
---|
104 | position = 0; |
---|
105 | i = 5; /* number of doubles in msg[] */ |
---|
106 | MPI_Pack_external("external32", &i, 1, MPI_INT, |
---|
107 | buf, 1000, &position); |
---|
108 | MPI_Pack_external("external32", &msg, i, MPI_DOUBLE, |
---|
109 | buf, 1000, &position); |
---|
110 | MPI_Send(buf, position, MPI_PACKED, 1, 0, |
---|
111 | MPI_COMM_WORLD); |
---|
112 | } else { /* RECEIVER CODE */ |
---|
113 | MPI_Recv(buf, 1, MPI_PACKED, 0, 0, MPI_COMM_WORLD, |
---|
114 | MPI_STATUS_IGNORE); |
---|
115 | MPI_Unpack_external("external32", buf, 1000, |
---|
116 | MPI_INT, &i, 1, &position); |
---|
117 | MPI_Unpack_external("external32", buf, 1000, |
---|
118 | MPI_DOUBLE, &msg, i, &position); |
---|
119 | } |
---|
120 | |
---|
121 | .SH NOTES |
---|
122 | .ft R |
---|
123 | The \fIdatarep\fP argument specifies the data format. The only valid |
---|
124 | value in the current version of MPI is "external32". The argument is |
---|
125 | provided for future extensibility. |
---|
126 | .sp |
---|
127 | To understand the behavior of pack and unpack, it is convenient to |
---|
128 | think of the data part of a message as being the sequence obtained by |
---|
129 | concatenating the successive values sent in that message. The pack |
---|
130 | operation stores this sequence in the buffer space, as if sending the |
---|
131 | message to that buffer. The unpack operation retrieves this sequence |
---|
132 | from buffer space, as if receiving a message from that buffer. (It is |
---|
133 | helpful to think of internal Fortran files or sscanf in C for a |
---|
134 | similar function.) |
---|
135 | .sp |
---|
136 | Several messages can be successively packed into one packing |
---|
137 | unit. This is effected by several successive related calls to |
---|
138 | MPI_Pack_external, where the first call provides \fIposition\fP=0, |
---|
139 | and each successive call inputs the value of \fIposition\fP that was |
---|
140 | output by the previous call, along with the same values for |
---|
141 | \fIoutbuf\fP and \fIoutcount\fP. This packing unit now contains the |
---|
142 | equivalent information that would have been stored in a message by one |
---|
143 | send call with a send buffer that is the "concatenation" of the |
---|
144 | individual send buffers. |
---|
145 | .sp |
---|
146 | A packing unit can be sent using type MPI_PACKED. Any point-to-point |
---|
147 | or collective communication function can be used to move the sequence |
---|
148 | of bytes that forms the packing unit from one process to another. This |
---|
149 | packing unit can now be received using any receive operation, with any |
---|
150 | datatype. (The type-matching rules are relaxed for messages sent with |
---|
151 | type MPI_PACKED.) |
---|
152 | .sp |
---|
153 | A packing unit can be unpacked into several successive messages. This |
---|
154 | is effected by several successive related calls to |
---|
155 | MPI_Unpack_external, where the first call provides \fIposition\fP=0, |
---|
156 | and each successive call inputs the value of position that was output |
---|
157 | by the previous call, and the same values for \fIinbuf\fP and |
---|
158 | \fIinsize\fP. |
---|
159 | .sp |
---|
160 | The concatenation of two packing units is not necessarily a packing |
---|
161 | unit; nor is a substring of a packing unit necessarily a packing |
---|
162 | unit. Thus, one cannot concatenate two packing units and then unpack |
---|
163 | the result as one packing unit; nor can one unpack a substring of a |
---|
164 | packing unit as a separate packing unit. Each packing unit that was |
---|
165 | created by a related sequence of pack calls must be unpacked as a unit |
---|
166 | by a sequence of related unpack calls. |
---|
167 | |
---|
168 | .SH ERRORS |
---|
169 | .ft R |
---|
170 | Almost all MPI routines return an error value; C routines as |
---|
171 | the value of the function and Fortran routines in the last argument. C++ |
---|
172 | functions do not return errors. If the default error handler is set to |
---|
173 | MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism |
---|
174 | will be used to throw an MPI:Exception object. |
---|
175 | .sp |
---|
176 | Before the error value is returned, the current MPI error handler is |
---|
177 | called. By default, this error handler aborts the MPI job, except for |
---|
178 | I/O function errors. The error handler may be changed with |
---|
179 | MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN |
---|
180 | may be used to cause error values to be returned. Note that MPI does not |
---|
181 | guarantee that an MPI program can continue past an error. |
---|
182 | .sp |
---|
183 | See the MPI man page for a full list of MPI error codes. |
---|
184 | |
---|
185 | .SH SEE ALSO |
---|
186 | .ft R |
---|
187 | .nf |
---|
188 | MPI_Pack_external_size |
---|
189 | MPI_Send |
---|
190 | MPI_Unpack_external |
---|
191 | sscanf(3C) |
---|
192 | |
---|