Ubuntu Manpage: pvm_precv - Receive a message directly into a buffer.

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.