TRECV(3PVM)							  TRECV(3PVM)

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 identif-
	  ier.	Values less than zero indicate an error.

DISCUSSION
  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 param-
  eters, 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 immedi-
  ately	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_nrecv(3PVM), pvm_recv(3PVM), pvm_unpack(3PVM), pvm_probe(3PVM),
  pvm_send(3PVM), pvm_mcast(3PVM)