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)