NAME

       pvm_notify - Request notification of PVM event such as host failure.

SYNOPSIS

       C    int info = pvm_notify( int what, int msgtag, int cnt, int *tids )

       Fortran   call pvmfnotify( what, msgtag, cnt, tids, info )

PARAMETERS

       what    Type of event to trigger the notification.  Presently one of:
                    Value               Meaning
                    PvmTaskExit         Task exits or is killed
                    PvmHostDelete       Host is deleted or crashes
                    PvmHostAdd          New host is added

       msgtag  Message tag to be used in notification.

       cnt     For  PvmTaskExit  and  PvmHostDelete, specifies the length of the tids array.  For
               PvmHostAdd, specifies the number of times to notify.

       tids    For PvmTaskExit and PvmHostDelete, an array of length cnt of task or pvmd TIDs  to
               be notified about.  The array is not used with the PvmHostAdd option.

       info    Integer  status  code  returned by the routine.  Values less than zero indicate an
               error.

DESCRIPTION

       The routine pvm_notify requests PVM to notify the caller on detecting certain events.  One
       or  more  notify  messages  (see  below)  are  sent  by PVM back to the calling task.  The
       messages have tag msgtag supplied to notify.

       The notification messages have the following format:

       PvmTaskExit
              One notify message for each TID requested.  The message body contains a single  TID
              of exited task.

       PvmHostDelete
              One  notify  message  for  each  TID requested.  The message body contains a single
              pvmd-TID of exited pvmd.

       PvmHostAdd
              cnt notify messages are sent, one each time the local pvmd's host table is updated.
              The  message body contains an integer length followed by a list of pvmd-TIDs of new
              pvmds.  The counter of PvmHostAdd messages yet to be sent is replaced by successive
              calls  to  pvm_notify.  Specifying a cnt of -1 turns on PvmHostAdd messages until a
              future notify; a count of zero disables them.

       TIDs in the notify messages are packed as integers.

       The calling task is responsible for receiving messages with the specified tag  and  taking
       appropriate action.

       Future versions of PVM may expand the list of available notification events.

EXAMPLES

       C:
            info = pvm_notify( PvmTaskExit, 9999, ntask, tids );

       Fortran:
            CALL PVMFNOTIFY( PVMHOSTDELETE, 1111, NUMHOSTS, DTIDS, INFO )

       To  "cancel"  a  notify  request  in PVM, the pvm_notify routine can be re-invoked with an
       additional PvmNotifyCancel flag in the what argument.  The  remaining  arguments  to  this
       cancelling  invocation  must  match  the  original  invocation  exactly,  aside  from  the
       additional PvmNotifyCancel which can be added(+) or OR-ed(|) to the what argument:

            pvm_notify( PvmTaskExit, 9999, ntask, tids );

            . . .

            pvm_notify( PvmTaskExit | PvmNotifyCancel, 9999, ntask, tids );

       Note that when a notify is cancelled, the notify message is delivered,  as  if  the  given
       event (i.e. task exit, host add or delete) had occurred.

ERRORS

       PvmSysErr
              pvmd not responding.

       PvmBadParam
              giving an invalid argument value.

SEE ALSO

       pvm_tasks(3PVM), pvm_config(3PVM)

                                         31 January, 1994                            NOTIFY(3PVM)