evmtemplate(4)						     Kernel Interfaces Manual						    evmtemplate(4)

NAME

       evmtemplate - Event Manager template file

SYNOPSIS

DESCRIPTION

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

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

	      o  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.

   File Format
       On startup, and each time the command is run, the EVM daemon reads all valid event template files stored in  the  template  directory  tree
       rooted at or in any directory tree linked to that directory, including the local template tree rooted at 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 and the files must be owned by or and must have permissions of or to be recognized.   If  tem-
       plate  files  are  added, deleted or modified while the daemon is running, the command should be used to instruct the daemon to reconfigure
       itself.	Refer to the evmreload(1M) manpage for more information.

       Every template event must contain a 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 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 template 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
		 command, or the library function.  See the evmshow(1) and EvmEventFormat(3) manpages.

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

		 If the format_specifier contains variable-specifier in the form 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
		 and the format_specifier:

		 then might display the event as:

		 If the format_specifier contains a data-item-specifier in the form the data-item-specifier is replaced with the value of the cor-
		 responding data item from the event.  For example, if an event contains a variable called and the format_specifier is:

		 then might display the event as:

		 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) manpage  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 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  sup-
		 plied.

       Identifies the I18N catalog message to be used in place of the
		 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 data item is used.

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

       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 template version will be seen if the
		 results of an command are piped into

		 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) manpage for a list of types.  All EVM variable types may be specified except for If this keyword is
			   omitted a type of is assumed.

		 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.

		 For	   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  speci-
			   fied,  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 group are global items, which will be included in each following template that does not include them explic-
       itly.

   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
       in place of the first two components 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.

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
       evmpost(1), evmshow(1), evmd(1M).

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

   Files
       evmdaemon.conf(4).

   Event Management
       EVM(5).

   EVM Events
       EvmEvent(5).

																    evmtemplate(4)