NAME

       pvm_trecv - Receive with timeout.

SYNOPSIS

       C    #include <sys/time.h>
            int bufid = pvm_trecv( int tid, int msgtag, struct timeval *tmout )

       Fortran   call pvmftrecv( tid, msgtag, sec, usec, bufid )

PARAMETERS

       tid     Integer to match task identifier of sending process.

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

       tmout   (or sec and usec) Time to wait before returning without a message.

       bufid   Integer  returns  the  value  of the new active receive buffer identifier.  Values
               less than zero indicate an error.

DESCRIPTION

       The routine pvm_trecv blocks the process until a message with  label  msgtag  has  arrived
       from tid.  pvm_trecv then places the message in a new active receive buffer, also clearing
       the current receive buffer.  If no matching message arrives within the  specified  waiting
       time, pvm_trecv returns without a message.

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

       In  C,  the  tmout  fields tv_sec and tv_usec specify how long pvm_trecv will wait without
       returning a matching message.  In Fortran, two  separate  parameters,  sec  and  usec  are
       passed.  With both set to zero, pvm_trecv behaves the same as pvm_nrecv, which is to probe
       for messages and return immediately even if none  are  matched.   In  C,  passing  a  null
       pointer  in  tmout  makes pvm_trecv act like pvm_recv, that is, it will wait indefinitely.
       In Fortran, setting sec to -1 has the same effect.

       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_trecv is successful, bufid will be the new active receive buffer identifier.  If no
       message is received, pvm_trecv returns 0.  If some error occurs then bufid will be < 0.

       Once pvm_trecv returns, the data in the message can be unpacked  into  the  user's  memory
       using the unpack routines.

EXAMPLES

       C:
            struct timeval tmout;

            tid = pvm_parent();
            msgtag = 4 ;
            tmout.tv_sec = 60;
            tmout.tv_usec = 0;
            if ((bufid = pvm_trecv( tid, msgtag, &tmout )) > 0) {
                 pvm_upkint( tid_array, 10, 1 );
                 pvm_upkint( problem_size, 1, 1 );
                 pvm_upkfloat( input_array, 100, 1 );
            }

       Fortran:
            CALL PVMFTRECV( -1, 4, 60, 0, BUFID )
            IF (BUFID .EQ. 0) GO TO 666
            CALL PVMFUNPACK( INTEGER4, TIDS, 25, 1, INFO )
            CALL PVMFUNPACK( REAL8, MATRIX, 100, 100, INFO )
       666  CONTINUE

ERRORS

       These error conditions can be returned by pvm_trecv

       PvmBadParam
              giving an invalid tid value, or msgtag < -1.

       PvmSysErr
              pvmd not responding.

SEE ALSO

       pvm_bufinfo(3PVM),  pvm_getminfo(3PVM), pvm_nrecv(3PVM), pvm_recv(3PVM), pvm_unpack(3PVM),
       pvm_probe(3PVM), pvm_send(3PVM), pvm_mcast(3PVM)

                                         8 February, 1994                             TRECV(3PVM)