PACK(3PVM)							   PACK(3PVM)

NAME
  pvm_pack - Pack the active message buffer with arrays	of prescribed data
  type.

SYNOPSIS
  C
	  int info = pvm_packf(	const char *fmt, ... )
	  int info = pvm_pkbyte( char *xp, int nitem, int stride )
	  int info = pvm_pkcplx( float *cp, int	nitem, int stride )
	  int info = pvm_pkdcplx( double *zp, int nitem, int stride )
	  int info = pvm_pkdouble( double *dp, int nitem, int stride )
	  int info = pvm_pkfloat( float	*fp, int nitem,	int stride )
	  int info = pvm_pkint(	int *ip, int nitem, int	stride )
	  int info = pvm_pkuint( unsigned int *ip, int nitem, int stride )
	  int info = pvm_pkushort( unsigned short *ip, int nitem, int stride
  )
	  int info = pvm_pkulong( unsigned long	*ip, int nitem,	int stride )
	  int info = pvm_pklong( long *ip, int nitem, int stride )
	  int info = pvm_pkshort( short	*jp, int nitem,	int stride )
	  int info = pvm_pkstr(	char *sp )

  Fortran
	  call pvmfpack( what, xp, nitem, stride, info )

PARAMETERS

  fmt	  Printf-like format expression	specifying what	to pack. (See discus-
	  sion).

  nitem	  The total number of items to be packed (not the number of bytes).

  stride  The stride to	be used	when packing the items.	 For example, if
	  stride = 2 in	pvm_pkcplx, then every other complex number will be
	  packed.

  xp	  Pointer to the beginning of a	block of bytes.	Can be any data	type,
	  but must match the corresponding unpack data type.

  cp	  Complex array	at least nitem*stride items long.

  zp	  Double precision complex array at least nitem*stride items long.

  dp	  Double precision real	array at least nitem*stride items long.

  fp	  Real array at	least nitem*stride items long.

  ip	  Integer array	at least nitem*stride items long.

  jp	  Integer*2 array at least nitem*stride	items long.

  sp	  Pointer to a null terminated character string.

  what	  Integer specifying the type of data being packed.
	       what options
		 STRING	      0	   REAL4	  4
		 BYTE1	      1	   COMPLEX8	  5
		 INTEGER2     2	   REAL8	  6
		 INTEGER4     3	   COMPLEX16	  7

  info	  Integer status code returned by the routine.	Values less than zero
	  indicate an error.

DISCUSSION
  Each of the pvm_pk* routines packs an	array of the given data	type into the
  active send buffer.  The arguments for each of the routines are a pointer
  to the first item to be packed, nitem	which is the total number of items to
  pack from this array,	and stride which is the	stride to use when packing.

  An exception is pvm_pkstr() which by definition packs	a NULL terminated
  character string and thus does not need nitem	or stride arguments.  The
  Fortran routine pvmfpack( STRING, ...	) expects nitem	to be the number of
  characters in	the string and stride to be 1.

  A null string	("") can be packed; this is just a string with no characters
  before the terminating '\0'.	However, packing a null	string pointer,	(char
  *)0, is not allowed.

  If the packing is successful,	info will be 0.	If some	error occurs then
  info will be < 0.

  A single variable (not an array) can be packed by setting nitem = 1 and
  stride = 1.

  The routine pvm_packf() uses a printf-like format expression to specify
  what and how to pack data into the send buffer.  All variables are passed
  as addresses if count	and stride are specified otherwise, variables are
  assumed to be	values.	 A BNF-like description	of the format syntax is:
      format : null | init | format fmt
      init : null | '%'	'+'
      fmt : '%'	count stride modifiers fchar
      fchar : 'c' | 'd'	| 'f' |	'x' | 's'
      count : null | [0-9]+ | '*'
      stride : null | '.' ( [0-9]+ | '*' )
      modifiers	: null | modifiers mchar
      mchar : 'h' | 'l'	| 'u'

  Formats:
    +  means initsend -	must match an int (how)	in the param list.
    c  pack/unpack bytes
    d  integers
    f  float
    x  complex float
    s  string

  Modifiers:
    h  short (int)
    l  long  (int, float, complex float)
    u  unsigned	(int)

  Future extensions to the what	argument in pvmfpack will include 64 bit
  types	when XDR encoding of these types is available.	Meanwhile users
  should be aware that precision can be	lost when passing data from a 64 bit
  machine like a Cray to a 32 bit machine like a SPARCstation. As a mnemonic
  the what argument name includes the number of	bytes of precision to expect.
  By setting encoding to PVMRAW	(see pvmfinitsend) data	can be transferred
  between two 64 bit machines with full	precision even if the PVM configura-
  tion is heterogeneous.

  Messages should be unpacked exactly like they	were packed to insure data
  integrity.  Packing integers and unpacking them as floats will often fail
  because a type encoding will have occurred transferring the data between
  heterogeneous	hosts. Packing 10 integers and 100 floats then trying to
  unpack only 3	integers and the 100 floats will also fail.

EXAMPLES
  C:
       info = pvm_initsend( PvmDataDefault );
       info = pvm_pkstr( "initial data"	);
       info = pvm_pkint( &size,	1, 1 );
       info = pvm_pkint( array,	size, 1	);
       info = pvm_pkdouble( matrix, size*size, 1 );
       msgtag =	3 ;
       info = pvm_send(	tid, msgtag );

      int count, *iarry;
      double darry[4];
      pvm_packf("%+ %d %*d %4lf", PvmDataRaw, count, count, iarry, darry);

  Fortran:
       CALL PVMFINITSEND(PVMRAW, INFO)
       CALL PVMFPACK( INTEGER4,	NSIZE, 1, 1, INFO )
       CALL PVMFPACK( STRING, 'row 5 of	NXN matrix', 19, 1, INFO )
       CALL PVMFPACK( REAL8, A(5,1), NSIZE, NSIZE , INFO )
       CALL PVMFSEND( TID, MSGTAG, INFO	)

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

ERRORS
       PvmNoMem	      Malloc has failed. Message buffer	size has exceeded
		      the available memory on this host.
       PvmNoBuf	      There is no active send buffer to	pack into.
		      Try calling pvm_initsend before packing message.
       PvmOverflow    A	data element is	too large for the encoding format.
		      This can happen when packing a long integer in
		      PvmDataDefault format on a machine with 8-byte long
		      ints.

SEE ALSO
  pvm_unpack(3PVM), pvm_initsend(3PVM)