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 message, 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  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:  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)