.\" $Id: pvm_precv.3,v 1.1 1996/09/23 22:05:52 pvmsrc Exp $
.TH PRECV 3PVM "15 March, 1994" "" "PVM Version 3.4"
.SH NAME
pvm_precv \- Receive a message directly into a buffer.

.SH SYNOPSIS
.nf
.ft B
C	int info = pvm_precv( int tid, int msgtag, char *buf,
.br
	                      int len, int datatype, int *atid,
.br
	                      int *atag, int *alen )
.br

Fortran	call pvmfprecv( tid, msgtag, buf, len, datatype,
.br
                        atid, atag, alen, info )
.fi

.SH PARAMETERS
.IP tid 0.8i
Integer task identifier of sending process (to match).
.br
.IP msgtag
Integer message tag (to match).
msgtag should be >= 0.
.br
.IP buf
Pointer to a buffer to receive into.
.br
.IP len
Length of buffer (in multiple of data type size).
.br
.IP datatype
Type of data to which buf points (see below).
.br
.IP atid
Returns actual TID of sender.
.br
.IP atag
Returns actual message tag.
.br
.IP alen
Returns actual message length.
.br
.IP info
Returns PvmOk on success.
Values less than zero indicate an error.

.SH DESCRIPTION
The routine
.I pvm_precv
blocks the process until a message with label
.I msgtag
has arrived from \fItid\fR.
pvm_precv then places the contents of the message in the supplied buffer,
\fIbuf\fR,
up to a maximum length of \fIlen\fR * (size of data type).
.PP
pvm_precv can receive messages sent by pvm_psend, pvm_send,
pvm_mcast, or pvm_bcast.
.PP
A -1 in
.I msgtag
or
.I 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.
.PP
In C the \fIdatatype\fR 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]
.ta 4 16
.nf
	\fIdatatype\fR	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
.fi

In Fortran the same data types specified for unpack should be used.
.PP
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.
.PP
If pvm_precv is successful,
.I info
will be = 0.
If some error occurs then info will be < 0.
.PP
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.
.PP
pvm_precv does not affect the state of the current receive message buffer
(created by the other receive functions).
.SH 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.
.PP
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.
.PP
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).
.SH EXAMPLES
.nf
C:
	info = pvm_precv( tid, msgtag, array, cnt, PVM_FLOAT,
                      &src, &rtag, &rlen );
.sp
Fortran:
	CALL PVMFPRECV( -1, 4, BUF, CNT, REAL4,
   >                SRC, RTAG, RCNT, INFO )
.fi


.SH ERRORS
These error conditions can be returned by
.I pvm_precv
.IP PvmBadParam
giving an invalid tid, msgtag, or datatype.
.IP PvmSysErr
pvmd not responding.
.PP
.SH SEE ALSO
pvm_psend(3PVM),
pvm_recv(3PVM)