NAME

       pvm_addmhf, pvm_delmhf - Install or remove message-handler functions.

SYNOPSIS

       C    int mhid = pvm_addmhf( int src, int tag, int ctx, int (*func)(int mid) )
            int info = pvm_delmhf( int mhid )

       Fortran   Not available

PARAMETERS

       src    The tid of the sender.

       tag    The tag sent with the message.

       ctx    The context sent with the message.

       func   Function to call when message received.

       mhid   Message handler id.

       info   Result code.

       mid    Message buffer identifier for new active receive buffer.

DESCRIPTION

       pvm_addmhf  specifies  a  function that will be called whenever libpvm copies in a message
       whose header fields of src, tag, and ctx match those provided to pvm_addmhf().

       The src and tag fields may be left unspecified (wildcard) by setting to -1.

       The calling sequence of the message handler function is:

            int handler( int mid )

       Where mid is the bufid of the received message.  The  handler  function  can  be  used  to
       unpack  and process the received message buffer.  PVM automatically saves the current send
       and receive buffers, so the handler need not worry about interfering with message  buffers
       in  the  regular  program  flow.  PVM also sets the current receive buffer to the received
       message (using pvm_setrbuf()) before invoking the message handler, so the message  can  be
       unpacked directly.  PVM will free this message buffer when the message handler returns, if
       the handler has not already done so.  But,  any  other  message  buffers  created  by  the
       handler routine should be freed using pvm_freebuf() before returning.

       Note:  Operation  in the message handler context is somewhat restricted.  The function may
       call some PVM functions, but not others.  For example, it may compose  and  send  a  reply
       message as shown:

            pvm_packf( "%+ %s", PvmDataDefault, "got your message" );
            pvm_send( tid, tag );
            pvm_freebuf( pvm_setsbuf( 0 ) );

       or equivalently:

            pvm_setsbuf( pvm_mkbuf( PvmDataDefault ) );
            pvm_pkstr( "got your message" );
            pvm_send( tid, tag );
            pvm_freebuf( pvm_setsbuf( 0 ) );

       but is not allowed to call certain other PVM communication functions, such as multicast or
       receive.

       pvm_addmhf returns the id number of the newly created message handler if successful;  this
       number  may  be  passed  to  pvm_delmhf to remove the entry.  There is no guarantee to the
       ordering of id values returned by pvm_addmhf, or to the order in  which  message  handlers
       will be invoked.  PvmExists is returned if the handler already exists.

       pvm_delmhf returns PvmOk if successful.  PvmBadParam if pvm_delmhf is passed a negative id
       value.  PvmNotFound if the id value is not found.

EXAMPLES

            /* Print a message when hosts are added to virtual machine */

            int
            hostAdded( int mid )
            {
                 int n;
                 pvm_unpackf( "%d", &n );
                 printf( "*** %d new hosts just added ***\n", n );
            }

            void
            main()
            {
                 int src, tag, ctx;

                 . . .

                 src = -1;
                 tag = 99;
                 ctx = -1;

                 pvm_addmhf( src, tag, ctx, hostAdded );
                 pvm_notify( PvmHostAdd, 99, -1, (int *) NULL );

                 . . .
            }

ERRORS

       The following error conditions can be returned by pvm_addmhf():

       PvmExists
              Can't insert as handler already exists with same (tag, ctx, src)  including  "wild-
              cards" (those set to -1)

       The following error conditions can be returned by pvm_delmhf():

       PvmBadParam
              Invalid (negative) mhid passed in.

       PvmNotFound
              Message handler mhid does not exist.

SEE ALSO

       pvm_setrbuf(3PVM), pvm_setsbuf(3PVM), pvm_freebuf(3PVM)

                                          1 April, 1997                              ADDMHF(3PVM)