.\" $Id: pvm_pkmesg.3,v 1.1 1996/09/23 22:05:43 pvmsrc Exp $
.TH PKMESG 3PVM "10 February, 1995" "" "PVM Version 3.4"
.SH NAME
pvm_pkmesg,
pvm_pkmesgbody,
pvm_upkmesg \- Pack messages into other messages.

.SH SYNOPSIS
.nf
.ft B
C	int info = pvm_pkmesg( int bufid )
.br
	int info = pvm_pkmesgbody( int bufid )
.br
	int newbufid = pvm_upkmesg( )
.br

Fortran	call pvmfpkmesg( bufid, info )
	call pvmfpkmesgbody( bufid, info )
	call pvmfupkmesg( bufid, newbufid )
.fi

.SH PARAMETERS
.IP bufid 1.0i
Message buffer to pack.
.IP newbufid
New message buffer unpacked or result code.
.IP info
Result code.

.SH DESCRIPTION
These functions are used to include messages in other messages,
as data elements.

.I pvm_pkmesg
packs the specified message into the current send buffer.
The entire body of the message is packed, along with header attributes:
.nf
	length
	context tag
	message tag
	wait identifier
	encoding
	checksum
	source and destination addresses
.fi
The buffer specified must not be the same as the current send buffer.
Multiple messages can be packed into a single message,
and packed messages can be mixed with any other data types.

.I pvm_upkmesg
unpacks a message from the current receive buffer,
allocating a new message buffer for it.
The body of the newly created message, and header attributes listed
above, match
the one originally packed using pvm_pkmesg.

.I pvm_pkmesgbody
is similar to pvm_pkmesg,
but
packs only the body of the specified message,
omitting the header fields.
In other words,
it splices the messages together (the included message is left unaltered).
When calling pvm_pkmesgbody,
the encoding types of the two messages must match because the
included message body is simply appended to the send buffer.
Calls to pvm_pkmesgbody can be mixed with calls to pack any other data types.

Note: \fIpvm_upkmesgbody\fR doesn't exist,
because PVM doesn't keep track of the boundary between the two
messages.

.SH EXAMPLES
.nf
	pvm_recv(-1, -1);
	pvm_initsend(PvmDataDefault);
	pvm_pkstr("here is the message I received...");
	pvm_pkmesg(pvm_getrbuf());
.fi

.SH ERRORS
The following error conditions can be returned by
pvm_pkmesg, pvm_pkmesgbody or pvm_upkmesg:
.IP PvmBadParam
An invalid value was specified for \fIbufid\fR argument, or bufid is the current send buffer.
.IP PvmNoSuchBuf
Message buffer \fIbufid\fR doesn't exist.
.IP PvmNoMem
Libpvm is unable to allocate memory to pack data.
.IP PvmNoData
The end of the message has been reached, perhaps because pack and unpack calls were mismatched.
.IP PvmNoBuf
There is no current send (or receive) buffer.
.IP PvmMismatch
\fIpvm_pkmesgbody\fR was called and the encoding types of \fIbufid\fR and the current send buffer don't match.
.PP
.SH SEE ALSO
pvm_getrbuf(3PVM),
pvm_getsbuf(3PVM),
pvm_pack(3PVM),