[97] | 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 | |
---|