PKMESG(3PVM)							  PVM Version 3.4						      PKMESG(3PVM)

NAME

       pvm_pkmesg, pvm_pkmesgbody, pvm_upkmesg - Pack messages into other messages.

SYNOPSIS

       C    int info = pvm_pkmesg( int bufid )
	    int info = pvm_pkmesgbody( int bufid )
	    int newbufid = pvm_upkmesg( )

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

PARAMETERS

       bufid	 Message buffer to pack.

       newbufid  New message buffer unpacked or result code.

       info	 Result code.

DESCRIPTION

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

       pvm_pkmesg  packs  the  specified  message  into  the  current  send  buffer.   The entire body of the message is packed, along with header
       attributes:
	    length
	    context tag
	    message tag
	    wait identifier
	    encoding
	    checksum
	    source and destination addresses
       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.

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

       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 mes-
       sages 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: pvm_upkmesgbody doesn't exist, because PVM doesn't keep track of the boundary between the two messages.

EXAMPLES

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

ERRORS

       The following error conditions can be returned by pvm_pkmesg, pvm_pkmesgbody or pvm_upkmesg:

       PvmBadParam
	      An invalid value was specified for bufid argument, or bufid is the current send buffer.

       PvmNoSuchBuf
	      Message buffer bufid doesn't exist.

       PvmNoMem
	      Libpvm is unable to allocate memory to pack data.

       PvmNoData
	      The end of the message has been reached, perhaps because pack and unpack calls were mismatched.

       PvmNoBuf
	      There is no current send (or receive) buffer.

       PvmMismatch
	      pvm_pkmesgbody was called and the encoding types of bufid and the current send buffer don't match.

SEE ALSO

       pvm_getrbuf(3PVM), pvm_getsbuf(3PVM), pvm_pack(3PVM),

								 10 February, 1995						      PKMESG(3PVM)