Article

A Dispatcher for Database Engine Alarms

Jon Alder and Ed Schaefer

What do you do if the database engine crashes at 3 a.m.? You could wait for a call from an irate user or you could have the database engine trigger an event to page you. Or what if your tape librarian has trouble remembering to secure last night's tape archive? You could rely on the librarian's memory or the database engine could trigger an event to send email informing the librarian when the archive is completed.

Informix has added just such an event-alarm facility to their Online Data Management System, version 6.0 and greater. The event-alarm facility calls a program or shell script pointed to by the ALARMPROGRAM configuration parameter and passes the event severity as parameters. Since the facility always calls the same program, that program must be a dispatcher controlling subsequent calls based on event severity. This article provides a dispatcher program.

Command-Line Arguments

When an event is triggered, Online calls the alarm program and passes five command-line arguments. From the Informix Online Dynamic Server Administrator's Guide, these arguments are defined as:

Arg	Parameter	Data Type
1	Event Severity	Integer
2	Event Class Id	Integer
3	Event Class Message	String
4	Event Specific Message	String
5	Event "see also" File	String

The Event Severity cases are:

Severity	Description
1	Not noteworthy. Will not be reported to the Alarm Program.
2	Information. No error has occurred but some routine event completed successfully.
3	Attention. This does not compromise data or prevent the use of the system; however, it warrants attention.
4	Emergency. Something unexpected occurred that might compromise data or access to data.
5	Fatal. Something unexpected occurred causing the database server to crash.

The second and third arguments are the class id and class message text, respectively, shown in Figure 1. The fourth parameter is additional information. Generally, this text is written to the Informix message log. Some events write additional information to another file. The fifth parameter is the full pathname of this file.

The ALARMPROGRAM

Configuration Parameter

Before an event can be triggered, you must set the ALARMPROGRAM parameter located in the Informix configuration file to the full path of the dispatcher program:

ALARMPROGRAM    /usr/ed/alarm/dispatcher.sh

Turn the engine off and back on to activate the new ALARMPROGRAM. Upon turning the engine back on, the following entry should be in the Informix log file:

init_alarm():  alarmprog = '/usr/ed/alarm/dispatcher.sh'
shell = '/bin/ksh'

The DISPATCHER Program

The DISPATCHER program is just an awk script. For each of the 24 classes of events, the dispatcher controls whether another program should be executed and whether a specific subprogram or the default program should be executed.

DISPATCHER performs the following steps:

1. Define each of the 24 Informix event classes in an awk array.

2. Set each event to active/inactive.

3. For each event, define an optional active program to call.

4. Set the default program parameter.

5. Set the debug parameter to false for production.

6. If the debug parameter is true, the awk array prints to standard output only and the program terminates.

7. The Informix class id is the index into the array. For each array element, if the subprogram is defined, this subprogram executes else the default program executes. All five command-line arguments are passed to the whatever program executes.

An Example

Event 23 is a logical log being archived. Upon archive completion, the program, /usr/lbin/testsh.sh, executes. The testsh.sh program simply displays a description and each of the command-line arguments passed:

severity:  2
class id:   23
class msg:  Logical Log 19 Complete.
event msg: Logical Log 19 Complete.
see also:

Conclusion

The dispatcher program is based primarily on the value of the Informix class id (argument 2). One enhancement might be to trap the severity code for other processing instead of passing it straight to the subprogram or default.

Dispatcher is a simple, yet elegant and functional, little design. Too bad all database environments do not provide an alarm mechanism.

References

Informix-OnLine Dynamic Server, Administrator's Guide, Volume 2. 1994. Informix Press: Menlo Park, CA.

About the Authors

Ed Schaefer is a frequent contributor to Sys Admin. He is an Informix Database Administrator and UNIX administrator for jeTech Data Systems of Moorpark, CA, where he develops Time and Attendance Software. He can be reached at olded@ix.netcom.com.

Jon Alder has been working on open systems for more than 10 years, most of the time in systems design and management. He is currently Director of Informix Technology for Meridian Technology Group, a firm of technical and business consultants located in the Pacific Northwest. He can be reached at jon@MeridianGroup.com.