NAME

       pvm_reg_hoster - Register task as PVM slave starter.

SYNOPSIS

       C    #include <pvmsdpro.h>

            int cc = pvm_reg_hoster()

       Fortran   Not Available

DESCRIPTION

       Registers  the  calling task as a PVM slave pvmd starter.  When the master pvmd receives a
       DM_ADD message, instead of starting the new slave  pvmd  processes  itself,  it  passes  a
       message to the hoster, which does the dirty work and sends a message back to the pvmd.

       Note:   This  function  isn't for beginners.  If you don't grok what it does, you probably
       don't need it.  For a more complete explanation of what's going on here, you should  refer
       to  the  PVM  source  code and/or user guide section on implementation; this is just a man
       page.  That said...

       When the master pvmd receives a DM_ADD message  (request  to  add  hosts  to  the  virtual
       machine),  it looks up the new host IP addresses, gets parameters from the host file if it
       was started with one, and sets default parameters.  It then either attempts to  start  the
       processes  (using  rsh  or  rexec())  or, if a hoster has registered, sends it a SM_STHOST
       message.

       The format of the SM_STHOST message is:
           int nhosts                // number of hosts
           {
               int tid               // of host
               string options        // from hostfile so= field
               string login          // in form ``[username@]hostname.domain''
               string command        // to run on remote host
           } [nhosts]

       The hoster should attempt to run each command on each  host  and  record  the  result.   A
       command usually looks like:
           $PVM_ROOT/lib/pvmd -s -d8 -nhonk 1 80a9ca95:0f5a 4096 3 80a95c43:0000

       and a reply from a slave pvmd like:
           ddpro<2312> arch<ALPHA> ip<80a95c43:0b3f> mtu<4096>

       When  finished,  the  hoster should send a SM_STHOSTACK message back to the address of the
       sender (the master pvmd).  The format of the reply message is:

           {
               int tid               // of host, must match request
               string status         // result line from slave or error code
           } []                      // implied count

       The TIDs in the reply must match those in the request.  They may be in a different  order,
       however.

       The  result  string  should  contain  the entire reply (a single line) from each new slave
       pvmd, or an error code if something went wrong.  Legal error codes are the  literal  names
       of  the  pvm_errno codes, for example ``PvmCantStart''.  The default PVM hoster can return
       PvmDSysErr or PvmCantStart, and the slave pvmd itself can return PvmDupHost.

       The hoster must use pvm_setmwid() to set the wait ID in the  reply  message  to  the  same
       value as in the request.  The wait ID in the request is obtained by calling pvm_getmwid().

       The  hoster  task  must use pvm_setopt(PvmResvTids, 1) to allow sending reserved messages.
       Messages should be packed using encoding PvmDataDefault to ensure  they  can  be  unpacked
       anywhere in the system.

       pvm_reg_hoster() returns PvmOk when successful.

SEE ALSO

       pvm_addhosts(3PVM), pvm_config(3PVM), pvm_setmwid(3PVM)

                                          4 March, 1994                          REG_HOSTER(3PVM)