evmtemplate(4)						     Kernel Interfaces Manual						    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
	      var {
		   name    variable_name
		   type    variable_type
		   value   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 components.  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 database 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 posting attempt.  Otherwise, the daemon  merges  the  data
       items held in the two versions of the event, yielding a merged event which it distributes to subscribers.

       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 compo-
       nents than the posted event, a template event is still considered a match if all components in the template name exactly match their equiv-
       alent  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.temp.high.70   myco.myprod.env	    Yes
	    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: This keyword introduces an event group.  The body of the group is delimited by braces.  Names the tem-
       plate  event.  The name must be made up of two or more components containing only alphanumeric and underscore (_) characters, and separated
       by dot (.) characters.  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 as the event's message text.  For example, if evmshow encoun-
	      ters 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
	      contains	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 contains 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 formatted for display.  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.  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 Common Desktop Environment: Programmer's Guide for more information.  Identifies the message
	      set within the i18n_cat to be used for translation of all internationalized strings in the  event.   This  item  is  ignored  if	no
	      i18n_cat	is  supplied.  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 mes-
	      sage 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.  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 spec-
	      ified in the template version, it is usually helpful to include the variables in the template event as well, specifiying dummy  val-
	      ues  such as zero, to provide documentation of the expected contents.  For example, the template 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: The name must be made up of alphanumeric and underscore characters.   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 for the variable.  A value must be specified in the tem-
	      plate,  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.	For STRING variables, the i18n_msg
	      identifies the I18N catalog message 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 supplied for the event.  If an i18n_set has been specified, the i18n_msg must refer to a  message  identi-
	      fier  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 cata-
	      log, the variable_value is used.	Any items specified outside an event group are global items, which will be included in	each  fol-
	      lowing 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 system 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

       The  root  of  the  directory  tree containing system event template files.  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: evmd(8), evmpost(1), evmshow(1), 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)

       Common Desktop Environment: Programmer's Guide System Administration delim off

																    evmtemplate(4)