unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



evmtemplate(4)						       evmtemplate(4)



NAME

  evmtemplate -	Event Manager template file

SYNOPSIS



  event	{
	  name		event_name
	  format	format_specifier
	  priority	priority
	  i18n_catalog	i18n_cat
	  i18n_set_id	i18n_set
	  i18n_msg_id	i18n_msg
	  reference	reference_string
	  cluster_event	cluster_event
	  var {
	       name    variable_name
	       type    variable_type
	       value   variable_value
	       i18n_msg_id   variable_value
	       }
	  }

DESCRIPTION

  A template event is a	description of an event	that is	held centrally by
  EVM.	The template is	used for the following purposes:

    +  To register the event with the EVM daemon, so that it will allow	the
       event to	be posted.

    +  To centralize event information.	 This makes it easy to review and
       maintain	details	such as	the associated message text and	the event
       priority, and minimizes the amount of information that must be hard-
       coded into an application.

  On startup, and each time the	evmreload -d command is	run, the EVM daemon
  reads	all valid event	template files stored in the template directory	tree
  rooted at /usr/share/evm/templates, or in any	directory tree linked to that
  directory, including the local template tree rooted at
  /var/evm/adm/templates.  There is no limit to	the number of template files
  that can be installed	in the tree, or	to the number of templates that	can
  be included in each file.

  Template file	names must end with the	suffix .evt, and the files must	be
  owned	by root	or bin,	and must have permissions of 0400, 0600, 0440 or 0640
  to be	recognized.  If	template files are added, deleted or modified while
  the daemon is	running, the evmreload -d command should be used to instruct
  the daemon to	reconfigure itself.  Refer to the evmreload(8) reference page
  for more information.

  Every	template event must contain a name data	item with at least two com-
  ponents.  A template typically also contains constant	items such as the
  event	priority and the message format	string.

  When a client	posts an event,	it must	include	in the posted event a name
  with at least	three components.  The posted event also typically contains
  any applicable variable data along with environmental	items such as a
  timestamp and	the name of the	posting	system.

  When the EVM daemon receives a posted	event, it searches its template	data-
  base for the template	event whose name best matches the name in the posted
  event.  If it	cannot find a matching template, the daemon rejects the	post-
  ing attempt.	Otherwise, the daemon merges the data items held in the	two
  versions of the event, yielding a merged event which it distributes to sub-
  scribers.

  A template event name	does not have to be identical to the name of a posted
  event	to be considered a match.  If it has fewer name	components than	the
  posted event,	a template event is still considered a match if	all com-
  ponents in the template name exactly match their equivalent components in
  the posted name.  If the template name is longer than	the name of the
  posted event however,	it cannot be a match.  In determining the template
  that best matches the	name of	the posted event, the daemon selects the
  matching template with the most components.

  The following	table shows some examples of event name	matching.  In the
  final	example, the template does not match the posted	event because the
  template has too many	components.

  ______________________________________________________________
  Posted Name			 Template Name		  Match?
  ______________________________________________________________
  myco.myprod.env		 myco.myprod.env	  Yes
				 myco.myprod.env	  Yes

  myco.myprod.env.temp.high.70
  myco.myotherprod		 myco.myprod		  No
  myco.myotherprod		 myco.myotherprod.start	  No
  ______________________________________________________________

  The syntax of	an event template file is identical to the syntax of a file
  given	as input to the	evmpost	command.  The following	keywords may be
  specified in a template file:

  event
      This keyword introduces an event group.  The body	of the group is	del-
      imited by	braces.

  name event_name
      Names the	template event.	 The name must be made up of two or more com-
      ponents containing only alphanumeric and underscore (_) characters, and
      separated	by dot (.) characters.

  format format_specifier
      Event format text.  The format_specifier is a string that	will be	used
      to produce a formatted message for display if the	event is passed
      through the evmshow(1) command, the sysman(8) event viewer, or the
      EvmEventFormat(3)	library	function.

      If a format_specifier contains no	special	characters, it is displayed
      unchanged	as the event's message text.  For example, if evmshow
      encounters an event containing the following simple format_specifier,
      it displays the string exactly as	specified:
	   EVM logger: Logger started

      If the format_specifier contains variable-specifier in the form
      $variable_name, and either the posted event or the template event	con-
      tains a variable with that name, the variable_value will be included in
      the formatted output in place of the variable_specifier.	If no such
      variable is present, the variable_specifier is included in the output.
      For example, if an event contains	a variable called logname and the
      format_specifier:


	   EVM logger: Started eventlog	$logname

      then evmshow might display the event as:
	   EVM logger: Started eventlog	/var/evm/evmlog/evmlog.20000228

      If the format_specifier contains a data-item-specifier in	the form
      @item_name, the data-item-specifier is replaced with the value of	the
      corresponding data item from the event.  For example, if an event	con-
      tains a variable called message and the format_specifier is:


	   EVM user msg	(@user_name): $message

      then evmshow might display the event as:
	   EVM user msg	(steve): Engineering group is off-site today

      If the data item is not present in the event, a hyphen character (-) is
      output in	its place.  An @ character that	is not associated with a
      valid item name is unchanged in the output.

      Any characters in	the format_specifier that are not part of a
      variable_name or data-item-specifier are output unchanged.

      If no format_specifier is	supplied in either the template	file or	the
      posted event, a default event message is used when the event is format-
      ted for display.

  priority priority
      Indicates	the importance of the event, but does not affect the order of
      event distribution.  The priority	must be	an integer value in the	range
      0	(lowest) to 700.  See the EvmEvent(5) reference	page for the meanings
      of specific priority values.

  i18n_catalog i18n_cat
      The name of an I18N catalog file holding text strings to be displayed
      in place of the strings contained	in the event.  This item is used for
      internationalizing events.  If it	is omitted, the	strings	contained in
      the event	will be	used when the event is formatted for display.  Refer
      to the Programmer's Guide	for more information.

  i18n_set_id i18n_set
      Identifies the message set within	the i18n_cat to	be used	for transla-
      tion of all internationalized strings in the event.  This	item is
      ignored if no i18n_cat is	supplied.

  i18n_msg_id i18n_msg
      Identifies the I18N catalog message to be	used in	place of the format
      data item	when the event is formatted for	display.  This item is
      ignored if no i18n_cat is	supplied.  If an i18n_set has been specified,
      the i18n_msg must	refer to a message identifier within the given set.
      If the catalog is	missing, or if the i18n_set or i18n_msg	values do not
      refer to a message in the	catalog, the event's format data item is
      used.

  reference reference_string
      This text	string is intended to be used by an event channel's explana-
      tion function to retrieve	explanation text for the event.	The format of
      the string is defined by the event channel.

  cluster_event	cluster_event
      If this Boolean value is set to TRUE, and	the event is posted in a
      cluster environment, the event is	distributed to all members of the
      cluster. The default value is FALSE.

  var This keyword introduces a	variable group,	with the body of the group
      being delimited by braces.  An event may include any number of variable
      groups.

      Although actual variable values are most likely to be included in	the
      posted version of	an event, and will override the	values specified in
      the template version, it is usually helpful to include the variables in
      the template event as well, specifying dummy values such as zero,	to
      provide documentation of the expected contents.  For example, the	tem-
      plate version will be seen if the	results	of an evmwatch -i command are
      piped into evmshow -d.

      The following keywords are recognized in a variable group:

      name variable_name
	  The name must	be made	up of alphanumeric and underscore characters.

      type variable_type
	  The type of the variable item.  See the EvmEvent(5) reference	page
	  for a	list of	types.	All EVM	variable types may be specified
	  except for OPAQUE.  If this keyword is omitted a type	of STRING is
	  assumed.

      value variable_value
	  Value	for the	variable.  A value must	be specified in	the template,
	  but usually should be	overridden by the value	in the posted version
	  of the event.	 Values	supplied in the	template should	be default or
	  nonnormal values that	will be	recognized as incomplete when the
	  event	is interpreted.

      i18n_msg_id i18n_msg
	  For STRING variables,	the i18n_msg identifies	the I18N catalog mes-
	  sage to be used in place of the variable_value when the event	is
	  formatted for	display.  This item is ignored if no i18n_cat is sup-
	  plied	for the	event.	If an i18n_set has been	specified, the
	  i18n_msg must	refer to a message identifier within the given set.
	  If the catalog is missing, or	if the i18n_set	or i18n_msg values do
	  not refer to a message in the	catalog, the variable_value is used.

  Any items specified outside an event group are global	items, which will be
  included in each following template that does	not include them explicitly.

NOTES

  If you are concerned with allowing your file to be used on other systems
  that support EVM in the future, you should use the built-in macro @SYS_VP@
  in place of the first	two components (sys.unix) of the name of any system
  event.  This will make it unnecessary	to change the file if the other	sys-
  tem uses a different event name prefix.

EXAMPLES

  The following	file is	an example of an event template	file.

       # My example event file
       priority	      200

       event {
	   name	      myco.myapp.env.humid
	   format     "myapp: Humidity is $humidity"
	   var	      {	name humidity	 type INT16    value 0 }
       }

       event {
	   name	      myco.myapp.env.temp.normal
	   format     "myapp: Temperature is normal ($temp)"
	   var	      {	name temp	 type FLOAT    value 0.0 }
       }

       event {
	   name	      myco.myapp.env.temp.high
	   priority   500
	   format     "myapp: Temperature exceeds 80F ($temp)"
	   var	      {	name temp	 type FLOAT    value 0.0 }
       }

       event {
	   name	      myco.myapp.env.app_terminated
	   priority   300
	   format     "myapp: Production monitoring terminated - code $exit_code"
	   var	      {	name exit_code	 type INT16    value 0 }
       }

FILES

  /usr/share/evm/templates
      The root of the directory	tree containing	system event template files.

  /var/evm/adm/templates
      The root of the directory	tree containing	local event template files.
      This directory is	accessed from the system template directory through a
      symbolic link.

SEE ALSO

  Commands: evmpost(1),	evmshow(1), evmd(8), sysman(8)

  Routines: EvmEventCreate(3), EvmEventDump(3),	EvmEventFormat(3),
  EvmEventPost(3), EvmItemSet(3)

  Files: evmdaemon.conf(4)

  Event	Management: EVM(5)

  EVM Events: EvmEvent(5)

  Programmer's Guide

  System Administration