SETTMASK(3PVM)						       SETTMASK(3PVM)

NAME
  pvm_gettmask,	pvm_settmask - Get or set trace	mask of	a task or its chil-
  dren.

SYNOPSIS
  C	  #include <pvm3.h>
  	  #include <pvmtev.h>

	  int info = pvm_gettmask( int who, Pvmtmask mask )
	  int info = pvm_settmask( int who, Pvmtmask mask )

  Fortran Not Available

PARAMETERS

  who	  Specifies which trace	mask to	get or set:
	      PvmTaskSelf     The current task
	      PvmTaskChild    Children tasks to	be spawned

  mask	  Trace	mask (owned by caller),	which is filled	in with	the current
	  trace	vector on calling pvm_gettmask or used to set the current
	  trace	vector on calling pvm_settmask.

  info	  Status code returned.	 Values	less than zero indicate	an error.

DISCUSSION
  Each task has	a trace	mask, which can	be used	to individually	enable trac-
  ing of each libpvm function.	The mask is inherited from its parent task
  (or initially	all cleared if the task	has no parent).	 When calls are	made
  to functions in libpvm, the parameters and results are sent in messages to
  the trace sink of the	task (variable PvmTraceTid set by calling pvm_setopt
  - see	man page).

  The PVM console and XPVM use this system to get trace	data from application
  programs.

  A task can get or set	either its own trace mask, or the mask passed to
  children it spawns.  Note the	mask must be set before	the spawn call;	set-
  ting the child trace mask has	no effect on already-running children.

  The trace mask can be	kept in	a temporary variable, declared as:

      Pvmtmask mymask;

  Right	now, this is a character array with approximately 80 bits.

  There	are four macros	defined	to manipulate trace masks.  Along with the
  functions, these allow a program to get the current trace mask, modify or
  save it, and put it back:

      TEV_INIT_MASK(mask)
      TEV_SET_MASK(mask, kind)
      TEV_UNSET_MASK(mask, kind)
      TEV_CHECK_MASK(mask, kind)

  TEV_INIT_MASK	initializes a mask to all bits cleared and must	be used	to
  initialize a trace mask (unless that is done by setting it from
  pvm_gettmask).  TEV_SET_MASK sets a bit in a mask.  Bit values are defined
  in .  Likewise, TEV_UNSET_MASK clears a single bit and
  TEV_CHECK_MASK checks	to see if a bit	is set,	returning nonzero if true.

  Note:	Most events in the trace mask come in pairs, the first (ending in
  ...0)	is generated on	entry to a function and	the second (...1) on exit.
  The trace mask has only half as many bits as there are events; events	are
  enabled in pairs.  In	other words, if	you select TEV_SEND0, you'll also get
  TEV_SEND1.

  The trace mask is deliberately kept as a printable (and null-terminated)
  string, for two reasons.  First, it is passed	through	the environment
  between tasks, in the	form:

      PVMTMASK=@@AAOG@@NO@L@@@@@@@@

  so the pvmd doesn't have to explicitly manage	it.  Second, the mask vari-
  ables	can be passed between tasks using pvm_pkstr() or otherwise manipu-
  lated	as strings.

  pvm_gettmask and pvm_settmask	return PvmOk on	success, else a	negative
  value.

EXAMPLES
  C:
      #include <pvm3.h>
      #include <pvmtev.h>

      Pvmtmask m;

      pvm_gettmask( PvmTaskChild, m );
      TEV_SET_MASK(m, TEV_ADDHOSTS0 );
      pvm_settmask( PvmTaskChild, m );
      pvm_spawn( "worker", (char **)0, PvmTaskDefault, "", 1, (int *)0);

ERRORS
  The following	error condition	can be returned	by pvm_gettmask	or
  pvm_settmask:
       PvmBadParam    invalid value for	who argument.

SEE ALSO
  pvm(1PVM), pvm_getopt(3PVM), pvm_setopt(3PVM)