HP-UX Event Manager Programmer's Guide HP-UX 11i v3 Edition 1 HP Part Number: 5991-6661 Published: February 2007
© Copyright 2007 Hewlett-Packard Development Company, L.P Legal Notices Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license.
Table of Contents About This Document ........................................................................................................9 Intended Audience.................................................................................................................................9 HP-UX Release Name and Release Identifier.........................................................................................9 Document Organization...................................................................
Sample EVM Programming Operations....................................................................37 Performing Simple Event Manipulations.............................................................................................37 Using Variable-Length Argument Lists................................................................................................38 Adding and Retrieving Variables.........................................................................................................
List of Figures 1-1 2-1 EVM Overview..............................................................................................................................12 Posted Event and Template Merging............................................................................................
List of Tables 1 2-1 2-2 2-3 2-4 2-5 2-6 3-1 6 HP-UX 11i Release...........................................................................................................................9 Standard Data Items......................................................................................................................15 Reserved Event Names..................................................................................................................17 Substituting Variables into Event Text......
List of Examples 2-1 2-2 4-1 4-2 4-3 4-4 4-5 4-6 4-7 4-8 4-9 4-10 4-11 Sample Event Explanation Text.....................................................................................................24 Event Template File.......................................................................................................................25 Performing Simple Event Manipulations......................................................................................38 Using Variable-Length Argument Lists....
About This Document This document describes how to use application programming interface (APIs) the Event Manager (EVM) supports. It also discusses the EVM events. The latest version of this document is available at: http://www.docs.hp.com The document printing date and part number indicate the document’s current edition. The printing date will change when a new edition is printed. Minor changes may be made at reprint without changing the printing date.
Book Title The title of a book. On the Web and on the Instant Information CD, it may be a link to the book itself. KeyCap The name of a keyboard key. Note that Return and Enter both refer to the same key. Emphasis Text that is emphasized. Emphasis Text that is strongly emphasized. Term The defined use of an important word or phrase. ComputerOut Text displayed by the computer. UserInput Commands and other text that you type. Command A command name or qualified command phrase.
1 Introduction The Event Manager is a comprehensive event management system. It includes a full set of command-line utilities that enable you to filter, sort, and format events. An event is an indication that some changes have happened in the system that may be of interest to a class of users or different entities within a system.
NOTE: EVM is a facility for broadcasting messages and must not be used to implement a private point-to-point communication channel between two processes. Using EVM for such purposes can impact the system performance negatively. To establish communication with another process and send the information that is not relevant to the system administrators, HP recommends that you use a more direct channel, for example, use sockets or pipes communication channel.
5. 6. EVM passes the merged event to all processes that have subscribed to receive the event. Subscribers handle the event in an appropriate way. For example, they may store it, send mail to the system administrator, or initiate an application failover.
2 Event Manager Events This chapter discusses EVM events. It also describes how to design these events and templates to capture specific events generated on the system. This chapter addresses the following topics: • • • “EVM Event Content” (page 15) “Designing a Set of Events” (page 22) “Designing Event Templates” (page 24) EVM Event Content The format, type, and purpose of the data carried in events varies widely. In a simple case, an event is a simple text message.
Table 2-1 Standard Data Items (continued) Data Item Description Priority (Event Priority Data Item) Indicates the importance of the event to its subscribers. Does not affect the order of event distribution. I18N catalog (I18N Catalog Name, Message Set ID, and Message ID Data Items) Specifies the name of the I18N catalog file for internationalized events. I18N msgset ID (I18N Catalog Name, Message Set ID, and Message ID Data Items) Identifies the message set within the I18N message catalog.
viewing and monitoring: the more detail you include in the event name, the more precise the specification criteria can be. For example, given the event name myco.myprod.env.temp.ok and myco.myprod.env.temp.high, a system administrator can monitor all temperature-related events by specifying myco.myprod.env.temp or restrict monitoring to events that report a high temperature by specifying myco.myprod.env.temp.high.
extending the name with the hardware ID that is assigned to each device that it registers. If the hardware ID is 2, you can search for related events with the following command: evmget -A -f "[name sys.unix.hw.*.2]" This example, the asterisk (*) wildcard character ensures that you find all events posted by the hardware subsystem that include the identifier 2, regardless of what they are reporting.
Comparing Event Names Use EVM's API functions to compare the name of an event with the name you are looking for. Do not use strcmp; the name of the incoming event may have more components than you expected. For more information on event name matching, see “Matching Event Names” (page 50). Event Format Data Item The format data item is a human-readable character string that summarizes the event.
Table 2-3 Substituting Variables into Event Text Format Data Item Variable Data Item Resulting Text Application started None Application started Debug message: $msg msg (string) = "Checkpoint reached" Debug message: Checkpoint reached Temperature too high: $temp temp (float) = 87.2 Temperature too high: 87.
NOTE: You must still include the text within the event, if the catalog file is not available when the event text is viewed. The catalog file must be located according to normal I18N rules, and you must include the name of the file in your event specifications. You can provide different versions of the catalog file for different language locales. For more information, see the System Administration document.
A variable name can be made up of any combination of uppercase or lowercase alphanumeric characters and the underscore (_) character. Names must be meaningful. The variable name is carried inside the event. Large physical events have longer names. A variable data item can be extracted and used directly by the subscriber, or combined with the event format text string to produce a formatted version of the event for display. Table 2-4 lists the variable types that EVM supports.
4. Write a detailed description of each event for documentation purpose, and include information about the following: • • • • What the event means When the event can occur Any actions the user or responsible subscriber must take in response to the event, and The contents of the event (particularly any variable data items) The explanation text is usually captured in a catalog file and can be accessed for display. For more information about explanation text, see “Writing Event Explanation Text” (page 24).
• • • In response to an error made by a user in a session that is under your control, and where you have direct communication with the user. For example, a configuration program must not post an event because a user responded incorrectly to a prompt. If you are dealing with an “error” that meets the following criteria: the error is expected and is normal behavior, you know why the error is displayed, and the error does not cause a system administrator to take any action.
from the need to provide the information repeatedly during the post requests. For information on how to decide what to include in an event template, see “Deciding What to Put in an Event Template” (page 25). For information about how the contents of event templates are merged with the contents of a posted event, see “Merging Data Items from Templates and Posted Events” (page 26). Templates are stored in files that are held in a central database.
Matching the Names of Posted Events with Event Template Names Each time an attempt is made to post an event, EVM searches its template database for the template whose event name matches the name of the posted event. If no match is found, EVM returns an error code to the program that posted the event. If a match is found, EVM then combines the data items held in the template with the items supplied by the posting program. This operation generates the merged event that is distributed to subscribers.
Figure 2-1 Posted Event and Template Merging If the same data item is supplied in both the template and the posted event, the posted value is used in the merged event. The merge process yields a binary event structure that contains a combination of the data items from the posted event and the template.
NOTE: The evmwatch command does not return the templates of any events for which you do not have access authorization. Hence, you must log in as superuser to view your templates. Establishing Translations for Event Text (I18N) The objective of event internationalization (I18N) is to enable an event's format data item, and the values of any string variables contained in the event, to be converted to another language for display.
— — — 541:La temperature du senseur $sensor est $temperature 542:haute 543:basse If the format function cannot interpret the events from a catalog, it uses values that are carried in the event and returns the following message regardless of the user's locale: "Temperature at sensor S27 is high" If an event file is passed to another system for analysis, the associated catalog file may not be available.
3 The EVM Programming Interface The EVM events are opaque data structures that can be accessed and manipulated by using EVM's application programming interface (API) functions.
Signal Handling The EVM API does not use signals in its normal processing and does not interfere with an application program's use of signals. However, because the system's default action is to silently terminate a process that attempts to write to a local connection if no process exists to read the data, a client process can exit without trace if the EVM daemon terminates before or during activity on the connection.
The EvmEvent_t type defines a pointer to a short handle structure that holds some control information and a pointer to the event body.
outside the callback function, after you have finished using the event; otherwise, you may encounter memory leak. For information about assigning an event, see “Reassigning and Replicating EVM Events” (page 32). Choosing a Connection Policy If your program is a posting client, you must choose a policy for connecting to the EVM daemon. You can choose one of the following options: • Create a connection when the program starts, and maintain it until the program terminates (permanent connection).
NOTE: Not all error codes returned by the connection functions indicate a disconnect. In particular, the program can drop out of EvmConnWait as a result of a signal. If this is indicated, the correct action is to return immediately to the EvmConnWait call. If your program is a posting client, you must deal with a disconnection only if you are using a permanent connection. For more information about connection, see “Choosing a Connection Policy” (page 34).
receive. To limit the set of events returned, filters can also be used by several command-line utilities as start options. For information on the use of filters by command-line utilities, see the HP-UX System Administration document, and for more information about filter syntax, see EvmFilter(5). For example on how to use filters, see “Using Filter Evaluators” (page 48).
4 Sample EVM Programming Operations This chapter describes how to write programs for performing EVM operations.
Example 4-1 Performing Simple Event Manipulations #include #include int main() { EvmEvent_t event; EvmItemValue_t itemval,itemval_local; EvmStatus_t status; /* You can create an empty event with EvmEventCreate() function. When you use this function, you supply a pointer to the event handle, and you receive an event that contains no standard data items. Even though the event is empty, it does take up memory, and you must eventually use EvmEventDestroy() to free the space.
You can reduce the size and improve the efficiency of your code by creating an event and adding items to it in a single step, using the varargs (variable-length argument list) version of the create function. You can add items to an existing event efficiently by using the varargs version of theitem-setfunction. Example 4-2 introduces the following functions: • EvmEventCreateVa — Creates an event, and supplies item names and values in a single call.
• • • 40 EvmVarSet — Sets the value of a named variable data item in an event. This function is used both for adding a variable and for altering the value of an existing variable. For more information about this function, see EvmVarSet(3). EvmVarGet — Returns information of the specified event variable in a given variable structure. The calling function must free any memory used by the variable by calling EvmVarRelease(). For more information about this function, see EvmVarGet(3).
Example 4-3 Adding and Retrieving Variables #include #include int main() {EvmEvent_t event; EvmStatus_t status; /* When using a primitive function to add a variable to the event, you must first place the value in a union of type EvmVarValue_t. The members of the union have the same names as the EVM variable types.*/ EvmVarValue_t varval_1, varval_2; EvmVarStruct_t varinfo; EvmString_t progname; EvmUint16_t exit_code; EvmItemValue_t itemval_name; itemval_name.NAME="sys.unix.
• • for each type of connection: posting, listening (subscribing), or availing service. For more information about this function, see EvmConnection(5) and EvmConnCreate(3). EvmEventPost — Posts an event to EVM. For more information about this function, see EvmEventPost(3). EvmConnDestroy — Destroys a specified connection. For more information about this function, see EvmConnDestroy(3). You can use the simpler EvmConnCreatePoster macro in place of EvmConnCreate to create a posting connection.
change each time the event is modified. Conversely, when you read an event, it is not enough to read the body; a handle must be created to enable you to reference the event through the API functions. Example 4-5 shows how to write events to a file, to read them from a file into your program, and to validate them. Example 4-5 introduces the following functions: • EvmEventWrite — Writes an event to an open file descriptor. For more information about this function, see EvmEventWrite(3).
• • • • 44 EvmConnSubscribe — Requests notification of any posted events that match the supplied filter. For more information about this function, see EvmConnSubscribe(3). EvmConnWait — Blocks until activity is detected on a specified connection. When activity is detected, the calling program can call EvmConnDispatch to handle the activity. For more information about this function, see EvmConnWait(3).
NOTE: You can use the simpler EvmConnCreateSubscriber macro in place of EvmConnCreate to create a subscribing connection. This macro requires fewer arguments than EvmConnCreate. Although it offers fewer connection options, it is suitable for use by most subscribing applications. For more information about this function, see EvmConnCreate(3).
Example 4-6 Subscribing for Event Notification #include #include void EventCB(EvmConnection_t conn, EvmCallbackArg_t cbarg, EvmCallbackData_t *cbdata); /*====================================================* Function: main()*==========================================*/ int main() {EvmConnection_t conn; EvmStatus_t status; /* Use EvmConnCreate() to establish a connection to the EVM daemon, this time specifying a listening connection.
it has finished with the event. */ EvmEventDestroy(cbdata->event); break; /* Because we made a subscription request earlier, the function will also be invoked with a callback reason of EvmREASON_SUBSCRIBE_COMiPLETE. In this example, all the reason codes can be ignored.*/ default: break; }} Handling Multiple I/O Sources You must not use EvmEventWait()to write a program that perform functions other than listening for events.
Example 4-7 Handling Multiple I/O Sources #include #include #include #include
events on a single connection. The combined string can then be discarded, but the original set of strings must be retained. It can be used to resubscribe later if the connection has to be re-established, or if the filter has to change. However, when an event arrives, you need to know which of the original filter strings it matches, so that you can decide about how to handle the events. You can use an EVM filter evaluator to do this.
Example 4-8 Using Filter Evaluators #include #include #include #include void EventCB(EvmConnection_t conn, EvmCallbackArg_t cbarg, EvmCallbackData_t *cbdata); /* This section of code defines three simple filter strings. The first two filter by name alone, but the third stringselects events with either of the two names, provided they have a priority of at least 300.*/ #define FILTER_1 "[name *.user]" #define FILTER_2 "[name *.msg]" #define FILTER_3 "([name *.
Matching Event Names The EVM naming policy enables you to extend an event name with any number of trailing components, yet still match its base name. This means that you cannot depend on an event with exactly the name you expect it to have, because it may have extra trailing components. To compare an event's name against a known name, you must not use the usual string comparison functions because they incorrectly fail to match the name if components are added.
Example 4-10 Dealing with Missed Events #include #include #include
The process of taking an existing event channel and making it accessible through EVM is termed encapsulation. EVM event channels are configured through the channel configuration file. This file is read by the EVM channel manager when EVM starts, and is also used by command-line utilities when channel information is needed.
The form of a get script depends on the form in which the native events are stored. Complete the following steps: 1. 2. Use standard UNIX tools such as grep, awk, and sed, or a programming language such as perl, to select the event lines, removing blank lines and comments, and reformat them as necessary for the next step.
supply a get function, instead allow the events to be logged by the EVM logger as they are posted. This consumes more storage space, because the events are stored in two places, but it may significantly improve retrieval time and programming effort. If you supply your own get function for the channel, be sure to change the filter strings in the EVM logger's configuration file, so that your events are not duplicated in the EVM log.
- the optional set_number is the number of the message set containing the explanation, for example, cat:myprod.cat:3. • Each explanation in the catalog begins with the name of an event enclosed in braces, for example, {myco.myprod.myapp.startup}. The message catalog must be located according to normal I18N rules. To minimize search time, group the explanations into sets and provide the set numbers in the reference data items of the events.
the channel's log files. This function is always executed as superuser and must take appropriate security precautions. The cleanup function can be run from the command-line along with the arguments. The function is allowed to take whatever action is appropriate. It is executed with no stdout or stderr assigned to the channel manager's log file. Hence, any desired status messages must generally be issued in the form of EVM events by using evmpost, instead of being written to stderr.
Index EvmEventValidate, 43 EvmEventWrite, 43 EvmFilterCreate, 50 EvmFilterDestroy, 50 EvmFilterSet, 50 EvmFilterTest, 50 EvmItemGet, 38 EvmItemRelease, 38 EvmItemSet, 38 EvmItemSetVa, 39 EvmVarGet, 41 EvmVarRelease, 41 EvmVarSet, 41 B binlog and syslog interaction with EVM, 12 C callback functions (EVM), 13 D data types, variable (EVM), 22 E Event Manager (see EVM) event poster (EVM) definition, 11 event subscriber (EVM) definition, 11 event templates how to create, 24 events (EVM), 11 (see also EVM) co
