PRECV(3PVM)							  PVM Version 3.4						       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.

DESCRIPTION

       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 matching 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 compatible 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 efficiency 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)

								  15 March, 1994						       PRECV(3PVM)