REG_HOSTER(3PVM)					     REG_HOSTER(3PVM)

NAME
  pvm_reg_hoster - Register task as PVM	slave starter.

SYNOPSIS
  C	  #include <pvmsdpro.h>

	  int cc = pvm_reg_hoster()

  Fortran Not Available

DISCUSSION

  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 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 must be packed using data format	PvmDataFoo.

  pvm_reg_hoster() returns PvmOk when successful.

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