pvm_pkstr(3)

1PACK(3PVM)                      PVM Version 3.4                     PACK(3PVM)
2
3
4

NAME

6       pvm_pack  -  Pack  the  active message buffer with arrays of prescribed
7       data type.
8
9

SYNOPSIS

11       C
12            int info = pvm_packf( const char *fmt, ... )
13            int info = pvm_pkbyte( char *xp, int nitem, int stride )
14            int info = pvm_pkcplx( float *cp, int nitem, int stride )
15            int info = pvm_pkdcplx( double *zp, int nitem, int stride )
16            int info = pvm_pkdouble( double *dp, int nitem, int stride )
17            int info = pvm_pkfloat( float *fp, int nitem, int stride )
18            int info = pvm_pkint( int *ip, int nitem, int stride )
19            int info = pvm_pkuint( unsigned int *ip, int nitem, int stride )
20            int info = pvm_pkushort( unsigned short *ip, int nitem, int stride )
21            int info = pvm_pkulong( unsigned long *ip, int nitem, int stride )
22            int info = pvm_pklong( long *ip, int nitem, int stride )
23            int info = pvm_pkshort( short *jp, int nitem, int stride )
24            int info = pvm_pkstr( char *sp )
25
26       Fortran
27            call pvmfpack( what, xp, nitem, stride, info )
28
29

PARAMETERS

31       fmt     Printf-like format expression specifying  what  to  pack.  (See
32               discussion).
33
34       nitem   The  total  number  of  items  to  be packed (not the number of
35               bytes).
36
37       stride  The stride to be used when packing the items.  For example,  if
38               stride  = 2 in pvm_pkcplx, then every other complex number will
39               be packed.
40
41       xp      Pointer to the beginning of a block of bytes. Can be  any  data
42               type, but must match the corresponding unpack data type.
43
44       cp      Complex array at least nitem*stride items long.
45
46       zp      Double  precision  complex  array  at  least nitem*stride items
47               long.
48
49       dp      Double precision real array at least nitem*stride items long.
50
51       fp      Real array at least nitem*stride items long.
52
53       ip      Integer array at least nitem*stride items long.
54
55       jp      Integer*2 array at least nitem*stride items long.
56
57       sp      Pointer to a null terminated character string.
58
59       what    Integer specifying the type of data being packed.
60                    what options
61                    STRING         0    REAL4          4
62                    BYTE1          1    COMPLEX8       5
63                    INTEGER2       2    REAL8          6
64                    INTEGER4       3    COMPLEX16      7
65
66       info    Integer status code returned by the routine.  Values less  than
67               zero indicate an error.
68
69

DESCRIPTION

71       Each of the pvm_pk* routines packs an array of the given data type into
72       the active send buffer.  The arguments for each of the routines  are  a
73       pointer to the first item to be packed, nitem which is the total number
74       of items to pack from this array, and stride which is the stride to use
75       when packing.
76
77       An exception is pvm_pkstr() which by definition packs a NULL terminated
78       character string and thus does not need nitem or stride arguments.  The
79       Fortran  routine pvmfpack( STRING, ... ) expects nitem to be the number
80       of characters in the string and stride to be 1.
81
82       A null string ("") can be packed; this is just a string with no charac‐
83       ters  before  the  terminating  '\0'.   However,  packing a null string
84       pointer, (char *)0, is not allowed.
85
86       If the packing is successful, info will be 0. If some error occurs then
87       info will be < 0.
88
89       A single variable (not an array) can be packed by setting nitem = 1 and
90       stride = 1.
91
92       The routine pvm_packf() uses a printf-like format expression to specify
93       what  and  how  to  pack  data into the send buffer.  All variables are
94       passed as addresses if count and stride are specified otherwise,  vari‐
95       ables  are  assumed to be values.  A BNF-like description of the format
96       syntax is:
97           format : null | init | format fmt
98           init : null | '%' '+'
99           fmt : '%' count stride modifiers fchar
100           fchar : 'c' | 'd' | 'f' | 'x' | 's'
101           count : null | [0-9]+ | '*'
102           stride : null | '.' ( [0-9]+ | '*' )
103           modifiers : null | modifiers mchar
104           mchar : 'h' | 'l' | 'u'
105
106       Formats:
107         +  means initsend - must match an int (how) in the param list.
108         c  pack/unpack bytes
109         d  integers
110         f  float
111         x  complex float
112         s  string
113
114       Modifiers:
115         h  short (int)
116         l  long  (int, float, complex float)
117         u  unsigned (int)
118
119
120
121       Future extensions to the what argument in pvmfpack will include 64  bit
122       types  when  XDR encoding of these types is available.  Meanwhile users
123       should be aware that precision can be lost when passing data from a  64
124       bit  machine  like a Cray to a 32 bit machine like a SPARCstation. As a
125       mnemonic the what argument name includes the number of bytes of  preci‐
126       sion  to  expect. By setting encoding to PVMRAW (see pvmfinitsend) data
127       can be transferred between two 64 bit machines with full precision even
128       if the PVM configuration is heterogeneous.
129
130       Messages  should  be  unpacked  exactly like they were packed to insure
131       data integrity.  Packing integers and unpacking  them  as  floats  will
132       often  fail because a type encoding will have occurred transferring the
133       data between heterogeneous hosts. Packing 10 integers  and  100  floats
134       then  trying  to  unpack  only  3 integers and the 100 floats will also
135       fail.
136
137

EXAMPLES

139       C:
140            info = pvm_initsend( PvmDataDefault );
141            info = pvm_pkstr( "initial data" );
142            info = pvm_pkint( &size, 1, 1 );
143            info = pvm_pkint( array, size, 1 );
144            info = pvm_pkdouble( matrix, size*size, 1 );
145            msgtag = 3 ;
146            info = pvm_send( tid, msgtag );
147
148           int count, *iarry;
149           double darry[4];
150           pvm_packf("%+ %d %*d %4lf", PvmDataRaw, count, count, iarry, darry);
151
152       Fortran:
153            CALL PVMFINITSEND(PVMRAW, INFO)
154            CALL PVMFPACK( INTEGER4, NSIZE, 1, 1, INFO )
155            CALL PVMFPACK( STRING, 'row 5 of NXN matrix', 19, 1, INFO )
156            CALL PVMFPACK( REAL8, A(5,1), NSIZE, NSIZE , INFO )
157            CALL PVMFSEND( TID, MSGTAG, INFO )
158
159

WARNINGS

161       Strings cannot be packed when using the PvmDataInPlace encoding, due to
162       limitations  in  the implementation.  Attempting to pack a string using
163       pvm_pkstr or pvm_packf will cause error code PvmNotImpl to be returned.
164

ERRORS

166       PvmNoMem
167              Malloc has failed. Message buffer size has exceeded  the  avail‐
168              able memory on this host.
169
170       PvmNoBuf
171              There  is  no  active  send  buffer  to  pack into.  Try calling
172              pvm_initsend before packing message.
173
174       PvmOverflow
175              Attempt to pack a value too large.  E.g. packing an 8-byte  long
176              with XDR encoding if the value won't fit into 4 bytes.
177