1UNPACK(3PVM) PVM Version 3.4 UNPACK(3PVM)
2
6 pvm_unpack - Unpack the active message buffer into arrays of prescribed
7 data type.
8
11 C
12 int info = pvm_unpackf( const char *fmt, ... )
13 int info = pvm_upkbyte( char *xp, int nitem, int stride)
14 int info = pvm_upkcplx( float *cp, int nitem, int stride)
15 int info = pvm_upkdcplx( double *zp, int nitem, int stride)
16 int info = pvm_upkdouble( double *dp, int nitem, int stride)
17 int info = pvm_upkfloat( float *fp, int nitem, int stride)
18 int info = pvm_upkint( int *ip, int nitem, int stride)
19 int info = pvm_upkuint( unsigned int *ip, int nitem, int stride )
20 int info = pvm_upkushort( unsigned short *ip, int nitem, int stride )
21 int info = pvm_upkulong( unsigned long *ip, int nitem, int stride )
22 int info = pvm_upklong( long *ip, int nitem, int stride)
23 int info = pvm_upkshort( short *jp, int nitem, int stride)
24 int info = pvm_upkstr( char *sp )
25 Fortran
27 call pvmfunpack( what, xp, nitem, stride, info )
28
31 fmt Printf-like format expression specifying what to pack. (See
32 discussion)
33 nitem The total number of items to be unpacked (not the number of
35 bytes).
36 stride The stride to be used when packing the items. For example, if
38 stride = 2 in pvm_upkcplx, then every other complex number will
39 be unpacked.
40 xp Pointer to the beginning of a block of bytes. Can be any data
42 type, but must match the corresponding pack data type.
43 cp Complex array at least nitem*stride items long.
45 zp Double precision complex array at least nitem*stride items
47 long.
48 dp Double precision real array at least nitem*stride items long.
50 fp Real array at least nitem*stride items long.
52 ip Integer array at least nitem*stride items long.
54 jp Integer*2 array at least nitem*stride items long.
56 sp Pointer to a null terminated character string.
58 what Integer specifying the type of data being unpacked.
60 what options
62 STRING 0 REAL4 4
63 BYTE1 1 COMPLEX8 5
64 INTEGER2 2 REAL8 6
65 INTEGER4 3 COMPLEX16 7
66 info Integer status code returned by the routine. Values less than
69 zero indicate an error.
70
73 Each of the pvm_upk* routines unpacks an array of the given data type
74 from the active receive buffer. The arguments for each of the routines
75 are a pointer to the array to be unpacked into, nitem which is the
76 total number of items to unpack, and stride which is the stride to use
77 when unpacking.
78 An exception is pvm_upkstr() which by definition unpacks a NULL termi‐
80 nated character string and thus does not need nitem or stride argu‐
81 ments. The Fortran routine pvmfunpack( STRING, ... ) expects nitem to
82 be the number of characters in the string and stride to be 1.
83 If the unpacking is successful, info will be 0. If some error occurs
85 then info will be < 0.
86 A single variable (not an array) can be unpacked by setting nitem = 1
88 and stride = 1.
89 The routine pvm_unpackf() uses a printf-like format expression to spec‐
91 ify what and how to unpack data from the receive buffer. All variables
92 are passed as addresses. A BNF-like description of the format syntax
93 is:
94 format : null | init | format fmt
95 init : null | '%' '+'
96 fmt : '%' count stride modifiers fchar
97 fchar : 'c' | 'd' | 'f' | 'x' | 's'
98 count : null | [0-9]+ | '*'
99 stride : null | '.' ( [0-9]+ | '*' )
100 modifiers : null | modifiers mchar
101 mchar : 'h' | 'l' | 'u'
102 Formats:
104 + means initsend - must match an int (how) in the param list.
105 c pack/unpack bytes
106 d integer
107 f float
108 x complex float
109 s string
110 Modifiers:
112 h short (int)
113 l long (int, float, complex float)
114 u unsigned (int)
115 Future extensions to the what argument in pvmfunpack will include 64
119 bit types when XDR encoding of these types is available. Meanwhile
120 users should be aware that precision can be lost when passing data from
121 a 64 bit machine like a Cray to a 32 bit machine like a SPARCstation.
122 As a mnemonic the what argument name includes the number of bytes of
123 precision to expect. By setting encoding to PVMRAW (see pvmfinitsend)
124 data can be transferred between two 64 bit machines with full precision
125 even if the PVM configuration is heterogeneous.
126 Messages should be unpacked exactly like they were packed to insure
128 data integrity. Packing integers and unpacking them as floats will
129 often fail because a type encoding will have occurred transferring the
130 data between heterogeneous hosts. Packing 10 integers and 100 floats
131 then trying to unpack only 3 integers and the 100 floats will also
132 fail.
133
136 C:
137 info = pvm_recv( tid, msgtag );
138 info = pvm_upkstr( string );
139 info = pvm_upkint( &size, 1, 1 );
140 info = pvm_upkint( array, size, 1 );
141 info = pvm_upkdouble( matrix, size*size, 1 );
142 int count, *iarry;
144 double darry[4];
145 pvm_unpackf("%d", &count);
146 pvm_unpackf("%*d %4lf", count, iarry, darry);
147 Fortran:
149 CALL PVMFRECV( TID, MSGTAG, INFO );
150 CALL PVMFUNPACK( INTEGER4, NSIZE, 1, 1, INFO )
151 CALL PVMFUNPACK( STRING, STEPNAME, 8, 1, INFO )
152 CALL PVMFUNPACK( REAL4, A(5,1), NSIZE, NSIZE , INFO )
153
156 PvmNoData
157 Reading beyond the end of the receive buffer. Most likely cause
158 is trying to unpack more items than were originally packed into
159 the buffer.
160 PvmBadMsg
162 The received message can not be decoded. Most likely because
163 the hosts are heterogeneous and the user specified an incompati‐
164 ble encoding. Try setting the encoding to PvmDataDefault (see
165 pvm_mkbuf).
166 PvmNoBuf
168 There is no active receive buffer to unpack.
169
171 pvm_pack(3PVM) pvm_send(3PVM), pvm_recv(3PVM), pvm_pkmesg(3PVM)
172 30 August, 1993 UNPACK(3PVM)