PRECV(3PVM)							  PRECV(3PVM)

NAME
  pvm_precv - Receive a	message	directly into a	buffer.

SYNOPSIS
  C	  int info = pvm_precv(	int tid, int msgtag, char *buf,
				int len, int datatype, int *atid,
				int *atag, int *alen )

  Fortran call pvmfprecv( tid, msgtag, buf, len, datatype,
			  atid,	atag, alen, info )

PARAMETERS

  tid	  Integer task identifier of sending process (to match).

  msgtag  Integer message tag (to match).  msgtag should be >= 0.

  buf	  Pointer to a buffer to receive into.

  len	  Length of buffer (in multiple	of data	type size).

  datatype
	  Type of data to which	buf points (see	below).

  atid	  Returns actual TID of	sender.

  atag	  Returns actual message tag.

  alen	  Returns actual message length.

  info	  Returns PvmOk	on success.  Values less than zero indicate an error.

DISCUSSION
  The routine pvm_precv	blocks the process until a message with	label msgtag
  has arrived from tid.	 pvm_precv then	places the contents of the message in
  the supplied buffer, buf, up to a maximum length of len * (size of data
  type).

  pvm_precv can	receive	messages sent by pvm_psend, pvm_send, pvm_mcast, or
  pvm_bcast.

  A -1 in msgtag or tid	matches	anything.  This	allows the user	the following
  options.  If tid = -1	and msgtag is defined by the user, then	pvm_precv
  will accept a	message	from any process which has a matching msgtag.  If
  msgtag = -1 and tid is defined by the	user, then pvm_precv will accept any
  message that is sent from process tid.  If tid = -1 and msgtag = -1, then
  pvm_precv will accept	any message from any process.

  In C the datatype parameter must be one of the following, depending on the
  type of data to be unpacked: [Version	3.3.0 -	This parameter only
  determines message length, not data conversion.  It only unpacks raw bytes]
      datatype	  Data Type
      PVM_STR	  string
      PVM_BYTE	  byte
      PVM_SHORT	  short
      PVM_INT	  int
      PVM_FLOAT	  real
      PVM_CPLX	  complex
      PVM_DOUBLE  double
      PVM_DCPLX	  double complex
      PVM_LONG	  long integer
      PVM_USHORT  unsigned short int
      PVM_UINT	  unsigned int
      PVM_ULONG	  unsigned long	int

  In Fortran the same data types specified for unpack should be	used.

  The PVM model	guarantees the following about message order.  If task 1
  sends	message	A to task 2, then task 1 sends message B to task 2, message A
  will arrive at task 2	before message B.  Moreover, if	both messages arrive
  before task 2	does a receive,	then a wildcard	receive	will always return
  message A.

  If pvm_precv is successful, info will	be = 0.	 If some error occurs then
  info will be < 0.

  pvm_precv is blocking	which means the	routine	waits until a message match-
  ing the user specified tid and msgtag	arrives	at the local pvmd.  If the
  message has already arrived then pvm_precv returns immediately with the
  message.

  pvm_precv does not affect the	state of the current receive message buffer
  (created by the other	receive	functions).

WARNINGS
  In some versions of PVM (CM5,	I860 and PGON),	messages sent using pvm_psend
  must be received only	by pvm_precv, likewise those sent with pvm_send	must
  be received by pvm_recv, pvm_nrecv or	pvm_trecv.  pvm_psend is not compati-
  ble with pvm_recv (nor pvm_send with pvm_precv).  In addition, pvm_probe is
  not interoperable with pvm_psend.

  This problem occurs because nonstandard message headers are used for effi-
  ciency in the	pvm_psend function.  In	the generic Unix version of PVM, the
  calls	are fully interoperable.

  The message tag space	is shared between pvm_send and pvm_psend, so you must
  be careful to	avoid selecting	the wrong message (for example by using	a
  wildcard to match the	message).

EXAMPLES
  C:
      info = pvm_precv(	tid, msgtag, array, cnt, PVM_FLOAT,
			&src, &rtag, &rlen );

  Fortran:
      CALL PVMFPRECV( -1, 4, BUF, CNT, REAL4,
     >		      SRC, RTAG, RCNT, INFO )

ERRORS
  These	error conditions can be	returned by pvm_precv
       PvmBadParam    giving an	invalid	tid, msgtag, or	datatype.
       PvmSysErr      pvmd not responding.

SEE ALSO
  pvm_psend(3PVM), pvm_recv(3PVM)