Using The Kick-off! Developers' Kit by Jamie Green July 31, 2003 The Kick-off! software includes the ability to monitor applications for crashes and other failures using "Rebound! Timer" technology. This package contains plug-ins and sample code for adding support for these Rebound! Timers to your applications. This support enables our Kick-off! product to monitor your application for failures and automatically take recovery steps. --------------------- FILES IN THIS PACKAGE --------------------- Kick-off SDK Readme.txt This document. Rebound.h Header file and library for C++ projects using load-time dynamic linking. Rebound.lib ReboundRuntime.h Header file and libraries for C++ projects using run-time dynamic linking. ReboundRuntime-ST.lib ReboundRuntime-MT.lib ReboundRuntime-D.lib ReboundRuntime-STd.lib ReboundRuntime-MTd.lib ReboundRuntime-Dd.lib VC++ Sample Sample project in Visual C++. VB Sample Sample project in Visual Basic. 4D Plug-in Plug-in for the 4th Dimension database. 4D Rebound Plugin.pdf Documentation on using the 4D Rebound Plugin. --------------------- ABOUT REBOUND! TIMERS --------------------- Rebound! Timers are the means by which Kick-off! monitors applications for failures. Applications can use Rebound! Timers to periodically "check in" with the Kick-off! software, letting it make sure applications are always running normally. The addition of application level failure detection complements Kick-off!'s native ability to detect and respond to system level failures. Together they provide a robust means of ensuring that critical applications are always available. The Kick-off! software keeps a separate Rebound! Timer for each application (and applications can create multiple timers if desired). Once set, the timer starts counting down to zero. If any active timer ever actually reaches zero, the Kick-off! software will restart the computer. It is the application's duty to periodically update ("tickle") its timer during normal operation and to close it when the application quits. For example, a web server application could set its Rebound! Timer to 60 seconds when it starts up. It then updates the timer to its original value once every 15 seconds. Under normal operation, the timer will never go far below 45 seconds before being reset. However, if the server application crashes, it will stop tickling. Its timer will continue counting down and will reach zero ("expire") within 60 seconds. Kick-off! will then restart the computer. ----------------------------------------------- SUPPORTING REBOUND! TIMERS IN YOUR APPLICATIONS ----------------------------------------------- Rebound! Timers were designed as a "dead-man's switch" to allow Kick-off! to take corrective action when an application fails for some reason. For this reason, you should ensure that your timers will only reach zero if something has actually gone wrong. We recommend the following: - Open a timer for your application when it first starts up. If you wish, you can open additional timers for critical sections of code, or for separate threads. - Periodically update your timer faster than it counts down. For most purposes, we recommend setting your timer to a value of 60 seconds, and resetting it every 15 seconds. This strikes a balance between adequate communication and system overhead, and gives your application several chances to set its timer in case the system is busy. - Before updating your timer, do some internal error-checking to ensure everything is running properly. For example, a web server might ensure that the network is still visible before setting the timer. If the network fails, this indicates all is not well, even though the application is still running. - IMPORTANT: When your application quits, it should close all timers. This will prevent Kick-off! from restarting the computer because it thinks your application has crashed. ------------------------------------------ IMPLEMENTING REBOUND! TIMERS IN VISUAL C++ ------------------------------------------ Refer to the Visual C++ sample project found in the "VC++ Sample' folder of the SDK. To implement Rebound! Timers in Visual C++, you must link the Rebound! library to your project, and periodically make calls to its functions to update the timer. The header files in this SDK contain detailed information on the Rebound! Timer functions. Linking the Rebound! library to your project -------------------------------------------- There are two ways to link to the Rebound! code in Visual C++. The first uses "load-time dynamic linking", and the second uses "run-time dynamic linking". In short, using the former method means your application will run only if the Kick-off! software is installed, and the latter means your application can still run in the absence of the Kick-off! software, but you will need to take a couple of extra steps when using Rebound! Timers. See for more information on load-time vs. run-time dynamic linking. If you're using load-time linking, it's simple: just link the "Rebound.lib" static library into your project, and include the "Rebound.h" header file in your source files which call the Rebound! functions. If you're using run-time linking, which library you link depends on which standard runtime library you're using. For example, in Visual C++ 6.0, look at the "Use runtime library" setting in the "Code Generation" section of the "C/C++" tab of the "Project Settings" dialog box. There are six possible values for this setting; link the matching Rebound! library from the following table: "Use Runtime Library" setting Matching Rebound! Library ----------------------------- ------------------------- Single-Threaded Static ReboundRuntime-ST.lib Multithreaded Static ReboundRuntime-MT.lib Multithreaded DLL ReboundRuntime-D.lib Debug Single-Threaded Static ReboundRuntime-STd.lib Debug Multithreaded Static ReboundRuntime-MTd.lib Debug Multithreaded DLL ReboundRuntime-Dd.lib In each case, you must also include the "ReboundRuntime.h" header file in your source files which call the Rebound! functions. Initializing the Rebound! code ------------------------------ If you are using run-time linking, your application must call the 'Rebound_Initialize' function before calling any of the timer functions. BOOL Rebound_Initialize(); This function will initialize communication between your application and the Kick-off! software. This function will return 'true' if the Kick-off! software is installed, and 'false' if not. NOTE: Retain the value returned by this function! If it returns false, you cannot call the other functions listed below, so any code which calls these functions must be preceded by a test of this return value. Creating and updating Rebound! Timers ------------------------------------- REBOUND_TIMER Rebound_OpenTimer( DWORD processId, LPCSTR pDescription ); To open a new Rebound! Timer, call the 'Rebound_OpenTimer' function. Pass it a process ID (from 'GetCurrentProcessId()') and a text description of the timer. The function will return a reference to a REBOUND_TIMER struct. Keep this struct for future updates. NOTE: The 'pDescription' parameter is displayed in the "Application Crashes" tab of the Kick-off! control panel. It should contain at least a brief name of your application. If your application opens multiple timers, each descripion should also contain appropriate distinguishing info. void Rebound_SetTimer( REBOUND_TIMER timerRef, unsigned long timerValue ); To update an existing Rebound! Timer, call the 'Rebound_SetTimer' procedure. Pass it the reference to your timer that you received from 'Rebound_OpenTimer' and the value you wish to set the timer to, in seconds. void Rebound_CloseTimer( REBOUND_TIMER timerRef ); When you are finished with the timer, call the 'Rebound_CloseTimer' procedure. Pass it the reference to the timer you wish to close. NOTE: Again, it is essential to properly close your timers before your application quits. Otherwise, the Kick-off! software will think it has crashed. -------------------------------------------- IMPLEMENTING REBOUND! TIMERS IN VISUAL BASIC -------------------------------------------- Refer to the Visual Basic project found in the "VB Sample" folder of the SDK. The Rebound! Timer functions in Visual Basic are essentially the same as those in C++, but are declared differently. (There is no need to include the Rebound! library, or to use the 'Rebound_Initialize' function.) To implement a Rebound! Timer in your Visual Basic application, your application must declare the following functions in your form's "(Declarations)" handler: Private Declare Function GetCurrentProcessId Lib "Kernel32" () As Long Private Declare Function Rebound_OpenTimer Lib "Rebound" (ByVal inProcessID As Long, ByVal inDescription As String) As Long Private Declare Sub Rebound_SetTimer Lib "Rebound" (ByVal inTimerRef As Long, ByVal inTimerValue As Long) Private Declare Sub Rebound_CloseTimer Lib "Rebound" (ByVal inTimerRef As Long) These functions are analogous to those described in the above section of this document. _________________ Revision History: Version 1.2: 7/31/03 Added the ability to use run-time dynamic linking. Version 1.1: 3/20/03 First public release. ________________________________ Copyright (C)1997-2003 Sophisticated Circuits, Inc. All rights reserved. Patents pending. Kick-off! and PowerKey Rebound! are registered trademarks of Sophisticated Circuits, Inc. All products mentioned are trademarks or registered trademarks of their respective holder(s).