Provided by: pvm-dev_3.4.6-5_amd64 bug

NAME

       pvm_mkbuf - Creates a new message buffer.

SYNOPSIS

       C    int bufid = pvm_mkbuf( int encoding )

       Fortran   call pvmfmkbuf( encoding, bufid )

PARAMETERS

       encoding
               Integer specifying the buffer's encoding scheme.
               Options in C are:
                    Encoding value           MEANING
                    PvmDataDefault      0    XDR
                    PvmDataRaw          1    no encoding
                    PvmDataInPlace      2    data left in place

               Option names in Fortran are:
                    Encoding value           MEANING
                    PVMDEFAULT          0    XDR
                    PVMRAW              1    no encoding
                    PVMINPLACE          2    data left in place

       bufid   Integer  message  buffer  identifier  returned.  Values less than zero indicate an
               error.

DESCRIPTION

       The routine pvm_mkbuf creates a new  message  buffer  and  sets  its  encoding  status  to
       encoding.   If  pvm_mkbuf  is successful, bufid will be the identifier for the new buffer,
       which can be used as a send buffer.  If some error occurs then bufid will be < 0.

       With the default setting XDR encoding is used when packing the message because PVM can not
       know if the user is going to add a heterogeneous machine before this message is sent.  The
       other options to encoding allow the user to take advantage of knowledge about his  virtual
       machine  even  when  it  is  heterogeneous.  For  example, if the user knows that the next
       message will only be sent to a machine that understands the native format, then he can use
       PvmDataRaw encoding and save on encoding costs.

       PvmDataInPlace  encoding specifies that data be left in place during packing.  The message
       buffer only contains the sizes and pointers to the items to  be  sent.  When  pvm_send  is
       called  the  items are copied directly out of the user's memory. This option decreases the
       number of times a message is copied at the expense of requiring the user to not modify the
       items between the time they are packed and the time they are sent.

       pvm_mkbuf  is required if the user wishes to manage multiple message buffers and should be
       used in conjunction with pvm_freebuf.  pvm_freebuf should be  called  for  a  send  buffer
       after a message has been sent and is no longer needed.

       Receive  buffers  are  created automatically by the pvm_recv and pvm_nrecv routines and do
       not have to be freed unless they have been explicitly saved with pvm_setrbuf.

       Typically multiple send and receive buffers are not needed and the user can simply use the
       pvm_initsend routine to reset the default send buffer.

       There  are  several  cases  where multiple buffers are useful.  One example where multiple
       message buffers are needed involves libraries or graphical interfaces  that  use  PVM  and
       interact  with  a  running  PVM  application  but  do  not  want  to  interfere  with  the
       application's own communication.

       When multiple buffers are used they generally are made and freed for each message that  is
       packed.

RESTRICTIONS

       PvmDataInPlace  allows  only dense (stride = 1) data in version 3.3.  It cannot be used on
       shared memory (*MP) architectures; a PvmNotImpl error will occur at send time.

EXAMPLES

       C:
            bufid = pvm_mkbuf( PvmDataRaw );
            /* send message */
            info = pvm_freebuf( bufid );

       Fortran:
            CALL PVMFMKBUF(PVMDEFAULT, MBUF)
       *    SEND MESSAGE HERE
            CALL PVMFFREEBUF( MBUF, INFO )

ERRORS

       These error conditions can be returned by pvm_mkbuf
            PvmBadParam    giving an invalid encoding value.
            PvmNoMem       Malloc has failed. There is not enough memory
                           to create the buffer

SEE ALSO

       pvm_initsend(3PVM), pvm_freebuf(3PVM)

                                         30 August, 1993                              MKBUF(3PVM)