Dataworks Enterprise Enterprise Launcher

Although, RTLaunch is designed to work with Dataworks Enterprise Enterprise components, it can also be configured to manage third party processes whether related to Dataworks Enterprise Enterprise or not.

RTLaunch uses a combination of scripts and registry settings to determine the components that are to be run. These settings are typically installed as part of the installation program. During the lifetime of the system, RTLaunch monitors these applications (restarting them, if necessary).

RTLaunch provides a user interface to allow managers to monitor the system at any time. In addition, RTLaunch generates a log file to store important events that occurred during its lifetime. Upon logout or manual closedown, the launch application stops each component that it had started and then exits.

This document describes the Launcher in detail including information concerning its user interface, configuration files and programming interface.

Version Information and Legacy Support

There are two versions of the launch and monitor application. The original (“legacy”) version was superseded in Version 2.2 of Dataworks Enterprise Enterprise with a more advanced version. There are many differences between the two, in particular, relating to the ways in which the launcher is configured.

There is no backward compatibility support provided by the new launcher, since this will largely depend on the specifics of the installation. To assist in upgrades of existing installations, the Version 2.2 release also supplies the legacy launcher (renamed to RTLaunch.old). However, this will only be maintained for a small number of releases and new installations should use the new launcher.

The legacy launcher is described in detail in the documentation supplied with pre-2.2 releases. As a result, this document only describes the new version of the launcher.

Basic Operation

The launcher’s main purpose is to run Dataworks Enterprise Enterprise components as child processes and monitor them. During execution of the child process, the launcher also collects statistics and other information and makes this information available to the management system.

The launcher employs the event log and file logs to record information about common events. Each event placed in the event log has a unique identifier to allow automated management systems to identify specific errors. Where a child process has a UI, the launcher provides facilities to allow it to be displayed.

The launcher monitors the state of processes and can be configured to poll them on a regular basis to ensure that they have not hung. If a process fails, the launcher attempts to collect and log debug information much in the same way as Dr. Watson. During this event, the launcher generates log information, outbound notifications. Optionally, the launcher will also attempt to restart the process (up to a configurable number of times each minute).

Modes of Operation

There are two basic modes of operation that can be used with the Launcher. During installation, a prompt is provided requesting whether the launcher should be run as a service or not. If not installed as a service, the RTLaunch program is either available to be run interactively from the “Start Menu” or may be run automatically during user login (from the Start-Up group). This is known as User Mode. While the launcher is running in this mode, it can be controlled through its integrated monitoring tool, identified by the shuttle icon in the task bar. In this mode of operation, the whole system will be closed down automatically during logout. This is the only mode of operation available on Windows 95/98/Me systems.

The Launcher in User Mode

More commonly, the launcher is configured to run as a “system level” process by installing it as a Service. This is known as System Mode. When the launcher is run in this mode, it has, by default, the same UI and runs as a “background” process. Optionally, this built-in UI can be disabled. In this event, the system can be monitored and managed using a separate binary (RTMonitor.exe). This is run as a user process. System Mode is only available on NT/2000 systems.

The Launcher in System Mode with No UI

When the launcher is run in System Mode, it is run under the “Local System” account with access to the interactive terminal. This allows its child process to access the desktop for display of status information. In this instance, launched applications and the launcher itself do not close down during system logout. In System Mode, the launcher is configured to start automatically on boot of the host. This allows an entire system to be brought on line on a boot, possibly as part of the NT crash recovery process.

The launcher may be administered through its built-in monitor either "in-process" or using the RTMonitor application in System mode. In either case, the management interface appears almost identical.

This manual, chiefly, discusses the System Mode of operation.

Internal Structure

The central core of the launcher is a controller (RTLaunchAdmin) and a script host (RTScriptHost). The RTLaunchAdmin object is responsible for the basic operation of the launcher and exposes the object model to automation capable applications. In user mode, it also maintains the administration user interface. The RTScriptHost object is responsible for the execution of scripts and for exposing some global functions accessible through automation. The script host imports the object model of the launcher and makes it accessible to launch scripts.

Associated with the RTLaunchAdmin object is a collection of module objects (RTLaunchModule) representing installed software under the control of the launcher. Modules are used for install and upgrade aspects of the system.

Each module object has a collection of program instances (RTLaunchProgram) each of which represent a currently managed process. The RTLaunchAdmin object also has a global list of these programs. The RTLaunchProgram object is responsible for monitoring the state of a managed process, for collecting statistics and for configuration of the process.

In addition, the RTLaunchAdmin object also maintains collections of tools (RTLaunchTool) and tasks (RTLaunchTask). The tools collection is used to populate the administration tool interface with useful related tools. Typically, these tools are added, on the fly, through scripting and can be configured on site.

The RTLaunchAdmin object also has a basic scheduler (similar to “cron” or “at”) that can be used to schedule specific tasks (in the form of scripted subroutines) to take place at specific times. Each of these tasks is stored in the tasks collection. Like the tools collection, tasks are also, typically, added on the fly through scripting.

Object Model

Each of the objects in the launcher is accessible through automation either from external processes or from the internal scripting engine. All launcher behaviour is controlled through this object model.

The monitor and management tools (RTMonitor or Built-In Interface) use this interface to communicate with and control the launcher. The monitor provides a detailed view of the current state of the launcher and the processes that it manages. It also allows basic operations to be performed such as starting and stopping specific processes, viewing current process statistics, adding and deleting processes and so on. It can be seen as an example of what can be achieved using the launcher object model. It uses no internal knowledge of the launcher over and above that provided by the object model.

Controlling the Launcher through External Processes

External user processes, such as custom programs written in any automation capable language can also use the launcher object model. The object model provides both inbound properties and methods that are used to alter its behaviour and outbound events that provide monitoring information.

Additional monitor programs can be written to interface the launcher with WMI, SNMP or Dataworks Enterprise Enterprise-specific monitoring tools such as Source Monitor. Many such monitor programs can be run at once, possibly providing notifications to third party statistics analysis tools, pager and SMS devices or to generate trap notifications to management tools.

Scripting Engine

In a similar way, the launcher script host can also be used to control the launcher and is one of the means by which the launcher is initially configured.

Controlling the Launcher through the Script Engine

During system start-up, the script engine loads the script “RTLaunch.vbl”. Typically, the scripting language is VBScript. This script, by default, adds some tools to the tools menu and performs other basic configuration functions. Users can edit this script to load and execute other user scripts. Thus, the script files are extensible allowing the user to configure custom tasks and behaviours.

In some cases, it might be desirable to allow user processes to run in the context of the launcher itself. For instance, suppose that we wanted to set up an application that sends an SMS message to a manager whenever a process needed to be restarted by the launcher. This could be set up as a user process in VB or C++ and run on the same system as the launcher. However, the problem would be that the user application would be “logged out” with the current session. One solution is to run the program under the launcher. Another would be to develop the process in VBScript and run the script under the launcher’s scripting engine.

Note that in either case, the automation object model is the API to the launcher. Understanding the object model is key to understanding the behaviour of the launcher.

Security Provision

When the Launcher is invoked in User Mode, only the current interactive user may control it. On the other hand, in System Mode, the launcher is running under the privileged account “Local System”. Consequently, the launcher is allowed to perform virtually any operation. Interacting with the built-in UI allows the user to operate under the Local System account. It is possible to turn off this interface allowing interaction to only take place from the interactive user account. In this event the launcher protects itself against malicious/accidental interference using a series of internal integrity checks whenever the system is accessed. By default, any user is allowed to connect to the object model, query property values and receive outbound events. However, only users who are part of the “Administrators” group are allowed to change any aspect of the launcher.

Starting and Stopping Dataworks Enterprise Launcher

If the launcher is running in user mode, simply executing the program RTLaunch.exe with no command line arguments starts it.

However, on Windows NT/2000, the launcher is usually run as a System Service. This allows the launcher and it’s child processes to:

When configured as a service, the Service Control Manager (SCM) initiates start up and shutdown. This can be achieved either through the Services Control Panel applet or from the command line. If the latter, the command line to start is:

	net start pdp

The command line to stop the launcher is:

	net stop pdp

NOTE: When run as a System Service, the launcher may, optionally, have no user interface and gives no visual indication of whether it is running or not. To find out if it is running as a service refer to the Services Control Panel Applet, MMC, Task Manager or run the RTMonitor administration tool.

The launcher can be set up to run as a service directly from the installation program. Alternatively, it can be registered with the SCM using its command line arguments. See Appendix A for details of the launcher command line arguments.

Start Up Processing

When the launcher is invoked, the program connects to COM, initialises it’s security context, constructs its basic object model and makes it available to external programs such as the monitor program or third-party processes.

The launcher then reads the standard registry entries for Dataworks Enterprise software contained in HKLM\Software\Primark\Platform\Settings for the paths to binary and configuration files. The launcher adds the binary path to its current environment. This allows Dataworks Enterprise components to be referenced without needing to specify the full path name. Dataworks Enterprise "config" path is cached. The launcher uses this whenever it is searching for a script or other file.

Next, the launcher then reads its global configuration information from the registry. This information controls the most basic aspects of the launcher’s behaviour and rarely needs modification. This information is described in Appendix B.

The launcher then constructs the RTScriptHost. Internally, two objects are made accessible to the script engine; the controller referred to as the variable “LaunchAdmin” and a global functions object. This latter has the same interface as the RTScriptHost itself. For instance, the RTScriptHost.Message(...) method can be used simply by calling Message(...) in the script code. In addition, the script host loads the standard scripting runtime engine providing access to the file system and to use dictionaries.

The script host then finds and executes the start up script “RTLaunch.vbl”. The default script will be something like:

	option explicit

	Sub Main()
		LaunchAdmin.ReadRegistry
	End Sub

	Sub Load()
		LaunchAdmin.Tools.Add "Statistics", "Stats.exe"
		LaunchAdmin.Tools.Add "Dataworks Enterprise Client", "Client.exe"
		LaunchAdmin.Tools.Add "Separator", "Separator"
		LaunchAdmin.Tools.Add "Dataworks Enterprise Versions", "RTVers.exe"
		LaunchAdmin.Tools.Add "Configuration", "RTConfig.exe"
		LaunchAdmin.Tools.Add "Separator2", "Separator"
		LaunchAdmin.Tools.Add "Trace Manager", "TraceMgr.exe"
	End Sub

	Sub Unload()
	End Sub

Once the script is loaded, the launcher executes the Load() subroutine. This subroutine is used to set up the tools and tasks collections and to load event handlers. Monitoring interfaces, such as RTMonitor, can use the tools collection to configure their Tools menus. Each tool must have a unique name. Note, that the executable name “Separator” is simply used to indicate a separator in the launcher tools menu.

The Load() subroutine is also useful for loading tasks to be performed by the built-in scheduler. For instance, suppose the following code is added to the RTLaunch.vbl file:

	Sub TestTask1()
		Message RTLog, "TestTask1called"
	End Sub

	Sub TestTask2()
		Message RTLog, "TestTask2 called"
	End Sub

	Sub Load()
		LaunchAdmin.ScheduledTasks.Add "TestTask1", 0, 23, 1-5
		LaunchAdmin.ScheduledTasks.Add "TestTask2", 5
		...

	End Sub

The first task (TestTask1) specifies that at 11:00 pm on Monday to Friday the subroutine TestTask1 should be called. The second states that TestTask2 should be called at five minutes past each hour.

The RTLaunch.vbl file can also be edited to declare event handlers. For instance:

	Sub LaunchAdmin_OnStopProgram(program)
		Message RTLog, "OnStopProgram called for " & program.Name
	End Sub

The above is an event handler that will be called whenever a program stops either as a result of an error or because the user stopped it. Note, that although any number of external processes may receive these notifications, there can only be one event handler within the scripting engine for each event.

Typically, user code is placed in separate scripts and loaded from the launch script on the fly. For instance, suppose a script file called “MAPI.vbl” is created containing code to notify operations through email of a stopped processes. This could then be loaded by editing the Load() subroutine as follows:

	Sub Load()
		...
		LoadScript “MAPI.vbl”
		...
	End Sub

Example scripts are provided on Dataworks Enterprise Distribution CD. The launcher script host is intended solely as a script execution environment and provides a very little to assist in the development of scripts apart from reporting script errors through its normal logging mechanisms. VBScript routines of any complexity should, typically, be developed within the standard scripting development environments such as WScript or CScript.

Once the Load() subroutine has completed, the launcher fires the OnBoot() event and execute the Main() subroutine. Typically, this simply makes a call to load the registry configurations using the LaunchAdmin.ReadRegistry() method. The registry configurations set up the modules and programs that are to be managed by the launcher. This is described in detail in Appendix C.

Once the registry is read, the launcher then looks for a “user script” called “UserScript.vbl”. This script is created by the launcher during closedown and contains the instructions necessary to add the programs that are added interactively using the management tool. By default, this script does not exist. NOTE: do not edit the user script, as it will be overwritten by the launcher.

It is possible that the scripting engine is not installed on the host. In this event, the launcher generates a warning, disables scripting and adds the default tools to the tools collection and forces a read of the standard registry entries.

Shutdown Processing

Shutdown of the launcher is essentially the reverse of the start up procedure. First, the launcher finds and executes the Unload() subroutine. This is, by default, empty and is provided to allow users to unload code they initialised in the Load() subroutine, if necessary.

Next, the launcher finds all processes added through the automation model such as with the management tool (and that are marked persistent) and creates a user script so that it can restart them when it next starts up. The launcher then saves its global configuration information to the registry.

Finally, the launcher stops any processes and tasks executing, fires an OnShutdown() event and exits.

Monitoring The Launcher

The launcher is monitored using a combination of files, event logs and interactive user programs.

Launch Log Displays, Files and the Event Log

The launcher uses log files and the event log and fires automation events to provide information about its running state.

When an event of interest occurs in the launcher, it:

Note that it is frequently the case that the same log can appear in all three places (monitoring application, log file, event log). The following levels are defined:

The scripting engine makes logging accessible to script code through the Message() interface, see below.

Frequently, additional detailed information is provided in the log file. The log file is located in the Windows temporary directory and is called RTLaunch_<DATE>.log, where the date is the date of creation of the file. At the end of each day, the launcher creates a new file. Old files are maintained for analysis.

As with the event log, the log file contains details of the major events (e.g. starting and stopping a component, detecting a ‘dead’ component) that occurred during the lifetime of the system and the times at which these events occurred. However, the file also contains the details of failures when they occur. For instance, suppose the event log contained the following information:

	18/08/2001 20:01:39 : Application Exception Occurred
	18/08/2001 20:01:39 : App: APressApp (pid=0x704)
	18/08/2001 20:01:39 : Exit Code 0xc0000005 (Access Violation)

The log file might contain information as follows:

WARNING : 22/01/2002 08:19:45 : Application Exception Occurred
App: APressApp (pid=0x704)
Exit Code 0xc0000005 (Access Violation)

*----> System Information <----*
        Computer Name: KYOUNG
        User Name: YoungK2
        Number of Processors: 1
        Processor Type: x86 Family 6 Model 5 Stepping 1
        Windows Version: 5.0
        Current Build: 2195
        Service Pack: 2
        Current Type: Uniprocessor Free
        Registered Organization: Thomson Financial Ltd.
        Registered Owner: Keith Young

*----> Modules <----*
(00400000) D:\Dev\active2\RTLaunch\Tests\TestCrsh\Debug\TestCrsh.exe
(54be0000) RTProbe.dll
(75e60000) IMM32.dll
(77d40000) RPCRT4.dll
(77db0000) ADVAPI32.dll
(77e10000) USER32.dll
(77e80000) KERNEL32.dll
(77f40000) GDI32.dll
(77f80000) ntdll.dll

State Dump for Thread Id 0x8a4 (Handle 0x350) FAULTED

Registers
eax=78f8fef0 ebx=00000000 ecx=00423fe8 edx=6c6c6548 esi=0012f6cc edi=00000005
eip=00401931 esp=0012f664 ebp=0012f6c4 iopl=0         nv up ei pl zr na po nc
cs=001b  ss=0023  ds=0023  es=0023  fs=0038  gs=0000 efl=00000246

*----> Stack Back Trace <----*
0012f664 0040139d 00000005 00423fe4 0012f7e8 0012f6cc TestCrsh!strcat  (FPO: [2,0,0])
0012f6c4 00401519 00000111 00401014 00000000 cccccccc TestCrsh!AbortProg 
0012f7e8 77e12e98 000704ca 00000111 00008003 00000000 TestCrsh!WndProc 
0012f808 77e16a72 00401014 000704ca 00000111 00008003 USER32!GetRemoteKeyboardLayout (FPO: Non-FPO [1,1180,1])
0012f82c 77e16aee 00401014 000704ca 00000111 00008003 USER32!GetUpdateRect (FPO: Non-FPO [3,1,1])
0012f84c 54be124e 00401014 000704ca 00000111 00008003 USER32!SetForegroundWindow  (FPO: [1,0,0])
0012fe00 77e12e98 007c3b38 00000111 00008003 00000000 RTProbe!Wnd::WindowProc  (FPO: [EBP 0x0012ff14] [4,355,4])
0012ff30 00401cb3 00400000 00000000 00132379 0000000a USER32!GetRemoteKeyboardLayout (FPO: Non-FPO [1,1180,1])
0012ffc0 77e97d08 00000000 00000000 7ffdf000 c0000005 TestCrsh!WinMainCRTStartup 
0012fff0 00000000 00401ba0 00000000 000000c8 00000100 KERNEL32!GetVolumeNameForRoot (FPO: Non-FPO [3,146,3])

strcat
        004018ff 8d79ff           lea     edi,[ecx-0x1]          ds:01f414ce=????????
        00401902 eb0d             jmp     strcat+0x61 (00401911)
        00401904 8d79fe           lea     edi,[ecx-0x2]          ds:01f414ce=????????
        00401907 eb08             jmp     strcat+0x61 (00401911)
        00401909 8d79fd           lea     edi,[ecx-0x3]          ds:01f414ce=????????
        0040190c eb03             jmp     strcat+0x61 (00401911)
        0040190e 8d79fc           lea     edi,[ecx-0x4]          ds:01f414ce=????????
        00401911 8b4c240c         mov     ecx,[esp+0xc]          ss:01c4cb4b=????????
        00401915 f7c103000000     test    ecx,0x3
        0040191b 7419             jz      strcat+0x86 (00401936)
        0040191d 8a11             mov     dl,[ecx]                     ds:00423fe8=6f
        0040191f 41               inc     ecx
        00401920 84d2             test    dl,dl
        00401922 7464             jz      strcat+0xd8 (00401988)
        00401924 8817             mov     [edi],dl                     ds:00000005=??
        00401926 47               inc     edi
        00401927 f7c103000000     test    ecx,0x3
        0040192d 75ee             jnz     strcat+0x6d (0040191d)
        0040192f eb05             jmp     strcat+0x86 (00401936)
FAULT   00401931 8917             mov     [edi],edx              ds:00000005=????????
        00401933 83c704           add     edi,0x4
        00401936 bafffefe7e       mov     edx,0x7efefeff
        0040193b 8b01             mov     eax,[ecx]              ds:00423fe8=6874206f
        0040193d 03d0             add     edx,eax
        0040193f 83f0ff           xor     eax,0xff
        00401942 33c2             xor     eax,edx
        00401944 8b11             mov     edx,[ecx]              ds:00423fe8=6874206f
        00401946 83c104           add     ecx,0x4
        00401949 a900010181       test    eax,0x81010100
        0040194e 74e1             jz      strcat+0x81 (00401931)
        00401950 84d2             test    dl,dl
        00401952 7434             jz      strcat+0xd8 (00401988)
        00401954 84f6             test    dh,dh
        00401956 7427             jz      strcat+0xcf (0040197f)
        00401958 f7c20000ff00     test    edx,0xff0000
        0040195e 7412             jz      strcat+0xc2 (00401972)
        00401960 f7c2000000ff     test    edx,0xff000000
        00401966 7402             jz      strcat+0xba (0040196a)
        00401968 ebc7             jmp     strcat+0x81 (00401931)
        0040196a 8917             mov     [edi],edx              ds:00000005=????????
        0040196c 8b442408         mov     eax,[esp+0x8]          ss:01c4cb4b=????????
        00401970 5f               pop     edi
        00401971 c3               ret
        00401972 668917           mov     [edi],dx                   ds:00000005=????
        00401975 8b442408         mov     eax,[esp+0x8]          ss:01c4cb4b=????????
        00401979 c6470200         mov     byte ptr [edi+0x2],0x0       ds:01b1d4eb=??
        0040197d 5f               pop     edi
        0040197e c3               ret
        0040197f 668917           mov     [edi],dx                   ds:00000005=????
        00401982 8b442408         mov     eax,[esp+0x8]          ss:01c4cb4b=????????
        00401986 5f               pop     edi
        00401987 c3               ret
        00401988 8817             mov     [edi],dl                     ds:00000005=??
        0040198a 8b442408         mov     eax,[esp+0x8]          ss:01c4cb4b=????????
        0040198e 5f               pop     edi
        0040198f c3               ret
        00401990 55               push    ebp
        00401991 8bec             mov     ebp,esp
        00401993 51               push    ecx
        00401994 894dfc           mov     [ebp-0x4],ecx          ss:01c4cbaa=????????

This is information very useful for port mortem analysis of failed programs.

The RTMonitor Interface

On start up, RTLaunch/RTMonitor adds an icon (a small picture of a rocket or shuttle) to the system tray. This image is ‘updated’ every second allowing the user to quickly check that the launch monitoring function is operating. The icon is shown with a red border if an error has recently been detected.

The Launcher Icon

Right-clicking on the shuttle, displays a menu offering options to:

If the launcher is running as a service, the exit menu simply closes the monitor application. If running in User Mode, the exit selection closes down the launcher itself.

Alternatively, the icon can be double-clicked allowing easy access to the Launch Status Dialog.

The Launch Status Dialog

The Launch Status Dialog shown below provides details of the launcher configurations, the current log information and the currently managed programs. Note that what you see may be different from the picture in some details. The user interface adapts itself depending on the access permissions of the user, the current state of the system and the facilities available from the version of the OS being run.

Dataworks Enterprise Launcher Main Dialog

The dialog has a close button that simply hides the dialog (it does not close down the launcher).

Dialog Menu

At the top of the dialog, there is a menu bar. The File menu has options for:

The Tools menu is a configurable menu of commonly used tools. Tools are added to the Tools menu through the Launcher object model (see the LaunchAdmin.Tools() collection). This provides a convenient place to get access to additional management tools from a single interface. This is the same Tools menu as provided on the taskbar.

The Log menu provides options to allow the log to be cleared, saved to file or copied to the clipboard. This menu is also available by right clicking on the log window below.

The Help menu displays copyright information.

Dialog Controls

The two combo boxes at the top of the dialog control global configurations of the launcher. The combo boxes control the rate at which statistics are collected and the maximum number of restarts per minute.

The rest of the dialog is divided into three panes.

At the bottom of the dialog is the log window. This provides information as the current running of the launcher. It is colour coded. Logs in red indicate errors, those in Black status information and those in Green the result of messages sent from scripting modules or detailed logs.

The upper half of the dialog is taken up with the modules pane and the processes pane. The modules pane shows a list of the currently selected modules. As you click on each module, the programs list on the right updates to reflect all the programs in this module. If you select the “All” node, the pane shows all processes running. Right clicking on a module name allows you to initiate the upgrade process where this is configured.

The processes pane contains lists of programs being managed by the launcher (possibly filtered by module, see above).

Processes managed by the launcher fall into three categories, those which are installed into the registry, those which are launched through scripting and those which are invoked through user interaction. Programs that are installed can be identified by the Installed property. Editing an installed process will update the registry configurations when the launcher is closed down or the current settings saved either from the File menu or through automation.

The behaviour of the launcher for non-installed programs depends on the value of the Persistent property. When the launcher saves its settings, it checks the Persistent property and, if true, writes script to the UserScript.vbl file. This file is loaded when the launcher is restarted causing the process to be added again. Consequently, programs added to the user script are also marked Persistent in that script.

If a program is added using the dialogs, the user can choose whether to save the program settings on exit (effectively marking the program “persistent”). Typically, programs launched from the custom scripts are not marked to be persistent, since it is assumed that the custom script itself will be invoked during start-up.

Right clicking on the pane background allows you to hide or show all processes, start/stop all processes or to add a new process. Selecting an individual process (by clicking in the ID column) and then right clicking adds additional options to allow you to control each process individually.

The interface allows the user to:

If you add or edit a process, you will be presented with this dialog:

The Add/Edit Process Dialog

This allows you to enter details of the new process. Pay particular attention to the Persistant check box. This tells the launcher whether you want the process to be restarted when the launcher starts up. When adding a process you must give it a unique name. Processes added in this manner are assigned to a default module.

The option to add a new instance of an existing process (or clone) duplicates the configuration of the selected process and presents an edit dialog in a single operation.

Right Clicking on the header line in the Processes pane allows you to sort the process list by the currently selected column. Sorting is a one-shot task and is designed to help locate a specific process. The list will not re-sort on each update. This menu also allows you to select the columns that are to be displayed. There are a large number of pieces of statistical information that can be collected and displayed through the launch monitor program.

Statistics Available for each Process (under Windows 2000)

The amount of statistical information available depends on the version of Windows being run. Consequently, some of these boxes may be disabled for specific target operating systems.

The Service Probe and the Debugger

By default, the launcher launches programs in the context of a debugger. This allows the launcher much finer control over the child process as well as the ability to generate detailed reports on failures, if they occur. However, running a process under a debugger changes some of the behaviour of the operating system with respect to the child process. For instance, some exceptions are generated only in the context of a debugger. This means that a program that may appear to run perfectly well outside a debugger may have bugs that are only reported within it. For instance, the Invalid Handle Exception (0xC0000008) is only generated in the context of a debugger. In addition, some programs test whether they are being run under a debugger and modify their behaviour accordingly. Consequently, the launcher allows the debugger to be disabled. The side effect of this is that the launcher provides a reduced service.

The service probe is a DLL that is loaded into the process space of each program it launches. It has three functions:

The service probe is only employed where the child process is being debugged (the default) and where the program Probed property is true (also the default). As with the debugger, in some rare circumstances, the probe may cause a conflict in the child process and, consequently, can be disabled.

Scripting the Launcher

Overview

As stated above, the Launcher hosts an internal script engine. It uses to parse and execute user scripts. Scripts can be used for a wide variety of purposes. In general, the launcher uses the scripts to load and execute processes.

An example of a typical user script would be:

	Dim my_prog

	Set my_prog = LaunchAdmin.Programs.Add(“MyProgram”)
	my_prog.CommandLine = “c:\SysMgr\MgrAgent.exe”
	my_prog.Start

Preloaded Objects and Libraries

To aid the user, the launcher preloads common libraries of objects and functions including the Windows Scripting Runtime library and the Launchers own object model. In addition, the launcher defines global functions (using the application object “Engine”). These methods and properties can be accessed through the script host object. They include:

Sub Message(Level As RTLaunchLogLevel, msg As String)

Displays the given message according to the log level. This can have the following values:

Sub LoadScript(ScriptPath As String)

Loads and executes the given script in the script engine.

Function FindProcess(Pattern As String) As Long

Finds the first process that matches the given pattern and returns its process ID. The pattern language uses regular expression syntax.

Sub RunProcess(Name As String, SeparateVDM As Boolean, ShowState As RTShowState, WorkingDirectory As String)

Runs a discreet process separate from the “launcher managed” context.

Sub KillProcess(Index As Variant)

Takes either a process ID or a pattern (as FindProcess), finds the given process and terminates that process.

Sub RegisterModule(Name As String, Register As Boolean)

Registers or unregisters the given ActiveX DLL Server.

Property Environment(Name As String) As String

Sets or gets the named environmental variable. From Version 2.2.1, the launcher adds additional entries to the environment for the IP name and address of the host. This is intended to assist in deployment where host configurations share scripts whose actions are controlled by the specific host on which they are run. Specifically, the following entries are added to the environment:

Property Registry(Name As String) As Variant

Sets or gets the named registry variable.

Property Running As Boolean

Returns true if the script engine is currently running.

The Launcher Object Model

The launcher object module is based around the central launcher component (known as “LaunchAdmin” in the scripting engine. To use the launcher object model typically involves getting the “Active Object” representing the launcher. This is achieved in VB using:

	Dim WithEvents launcher As RTLaunchAdmin
	On Error Resume Next

	Set launcher = GetObject(,"RTLaunch.RTLaunchAdmin.1")

	If launcher Is Nothing Then
		MsgBox "The launch service is not running"
	Else
		On Error GoTo 0
		' More code here
	End If

For C++ programmers, the supplied “RTLaunchAPI.h” provides code for automatically getting the launcher object and attaching to its events stream. This also wraps the object in a C++ native class.

RTLaunchAdmin

The Admin object provides for:

The main global properties relate to the rate at which to collect per-process statistics and the maximum number of attempts per minute to re-launch a failed process.

The launcher maintains four collections of information: Programs, Modules, Tasks and Tools. Associated with each collection are events that relate to changes to these collections. For instance, the Programs collection is a collection of all programs being managed by the launcher. Associated with the programs collection are the events: OnAddProgram, OnChangeProgram, OnDeleteProgram, On StartProgram and OnStopProgram. External applications can monitor these events though standard event handlers. In addition, event handlers can also be attached in the internal scripting engine during the OnLoad() phase of start-up.

When an OnChange... event is fired the application is passed the object that was being changed along with the id of the property being changed. The object provides a PropertyName property that can be used to retrieve the name of the property being changed. (For the technical user, this id is the same as the DISPID of the property in question).

Each of the Admin object collections contain items which have the following common properties:

Function Admin() As RTLaunchAdmin
Function Parent() As RTLaunchAdmin

Allowing external programs to navigate between the collection elements and the launcher Admin object itself. Note: these properties are also available from the Admin object itself and simply return another reference to it.

None of the objects in the Launcher object model are directly creatable. Instead, they can only be accessed through the launcher Admin object itself. To add or remove elements, use the appropriate methods on the collection interfaces.

RTLaunchAdmin Methods and Properties

Property Item (Index As Variant, Optional IndexIsProgId As Boolean) As RTLaunchProgram

Returns a program from the launcher’s programs collections. This is functionally the same as using the Programs.Item() method.

Property StatsTimeout As Long

This property gets or sets the rate at which statistics are collected for each child process of the launcher.

Property MaxRestartsPerMinute As Long

This property gets or sets the number of times a failing process will be restarted in a given minute interval.

Property ScriptHost As RTScriptHost

Returns the script host object.

Property CanUpdate As Boolean

Returns true if the calling user has permissions to update the launcher.

Property ScheduledTasks As RTLaunchTasks

Returns the collection of scheduled tasks.

Property Alerted As Boolean

Returns true if any process has recently failed.

Property Tools As RTLaunchTools

Returns the collection of configured tools.

Property Modules As RTLaunchModules

Returns the collection of configured modules.

Property Programs As RTLaunchPrograms

Returns the collection of configured programs.

Property Admin As RTLaunchAdmin

Returns a reference to the launcher object (i.e. itself).

Property Parent As RTLaunchAdmin

Returns a reference to the parent object (i.e. itself).

Sub ReadRegistry(Optional RootKey As String)

Reads the registry area for installed programs. By default this property reads the default launch key using “HKLM\System\CurrentControlSet\Control\RTLaunch\Launch”. Other registry areas may also be read. However, these will have degraded functionality with respect to loading and saving configurations.

Property Verbose As Boolean

Gets or sets the amount of log messages emitted by the launcher itself (as opposed to the child programs). Most launcher logs relate to start and closedown of the launcher, as opposed to messages that relate to the running of individual programs.

Sub SaveSettings

Causes the launcher to save it current settings.

RTLaunchModules/RTLaunchModule

The modules collection is a collection of the modules identified by the launcher from the registry entries described below. A module is perceived to be a collection of programs and scripts that form a single installable unit of Dataworks Enterprise. Modules must be upgraded as a single unit.

The modules collection supports standard collection syntax including the default item method and the VB “ForEach” syntax. Modules are indexed by index and by name. The modules collection is, however, read-only and is derived from registry information.

Each module provides a collection of dependent modules and a collection of programs that form this module, both sourced from the registry entries. The module object has properties relating to the installation and upgrade of the module and a method that is used to request that the module upgrade itself. Much of this functionality is unimplemented in the first release.

RTLaunchModule Methods and Properties

Property Name As String

Returns the name of the module.

Property ConfigurationName As String

Gets or sets the name of the configuration interface.

Property UpgradeModule As String

Returns the name of the upgrade module.

Property UpgradePath As String

Returns the path of the upgrade module.

Property UpgradeCommand As String

Returns the command to be run to perform the upgrade.

Property InstalledVersion As String

Returns the currently installed version.

Property UpgradeVersion As String

Returns the version to be upgraded to.

Property Upgrading As Boolean

Returns true if the upgrade process is in operation.

Property UpgradeProgress As String

Returns the current state of the upgrade process.

Property PropName(RTModuleDispIds prop) As String

For a given RTModuleDispId returns the name of the property. This can be useful when handling module change events.

Property Admin As RTLaunchAdmin

Returns a reference to the launcher object.

Property Parent As RTLaunchAdmin

Returns a reference to the parent object (i.e. the Admin Object).

Sub Upgrade

Performs an upgrade on the module.

Property Programs As RTLaunchPrograms

Returns the collection of programs associated with this module.

Property Dependencies As RTLaunchModules

Returns a collection of modules dependent on this module.

Property CanUpgrade As Boolean

Returns true if the module can be upgraded.

Property Verbose As Boolean

Gets or sets the amount of log messages emitted by the module.

RTLaunchPrograms/RTLaunchProgram

There are two ways in which a programs collection can be accessed. The main programs collection is a property of the Admin object. This collection is fully editable and representing the entire list of programs currently being managed by the launcher.

In addition, a secondary collection of programs is available from the RTLaunchModule object. This represents the list of programs that form the module.

The programs collection supports standard collection syntax including the default item method and the VB “ForEach” syntax. Programs are indexed by index and by name.

Each program in the programs collection, provides properties and methods to control the program itself as well a large number of properties containing statistics information related to the program under control.

RTLaunchProgram Methods and Properties

Property Id As Long

Returns a unique Id for the program that is constant across processes.

Property Name As String

Returns the unique name for the program.

Property CommandLine As String

Gets or sets the command line associated with the program.

Property Restart As Boolean

Gets or sets whether the launcher will restart the process on failure.

Property Poll As Boolean

Gets or sets whether the launcher is configured to poll the process to attempt to detect if it has hung.

Property CmdShow As RTShowState

Gets or sets the default show state for the launched program.

Property Persistant As Boolean

Gets or sets whether the program state should be saved across launcher sessions.

Property PollTimeout As Long

Gets or sets the time after which a not responsing program is considered to have hung.

Property PropName(RTProgramDispIds prop) As String

For a given RTProgramDispId, returns the name of the property. This can be useful when handling program change events.

Property Admin As RTLaunchAdmin

Returns a reference to the launcher object.

Property Parent As RTLaunchAdmin

Returns a reference to the parent object (i.e. the Admin Object).

Property Object As Object

Gets or sets a process specific object in the launcher’s object tree. Only child processes of the launcher should use this property.

Property Configurable As Boolean

Returns true if the process can be configured.

Property ModuleName As String

Returns the name of the module associated with this program.

Property ProgramName As String

Returns the name of the program.

Property Probed As Boolean

Gets or sets whether the program is to be probed or not.

Property Debugged As Boolean

Gets or sets whether the program is to be debugged or not.

Property Verbose As Boolean

Gets or sets the amount of log messages emitted by the program.

Property Alerted As Boolean

Returns true if the program failed in the recent past.

Property Installed As Boolean

Returns true if the program was installed in the registry.

Property SeparateVDM As Boolean

If a 16-bit process, runs the program in a separate VDM.

Property WorkingDirectory As String

Gets or sets the working directory for the program.

Sub Show(Show As Boolean)

Either shows or hides the program depending on the Show argument. If Show is True the program is revealed.

Sub Start

Starts the program if it is not already started.

Sub Stop

Stops the program if it is started.

Sub Configure (X As Long, Y As Long, hwndOwner As long)

If the program is configurable, then pops up the program’s configuration dialog.

Property Verbose As Boolean

Gets or sets the amount of log messages emitted by the program.

In addition, the following read-only properties contain statistics about the program:

Property PID As Long

Property State As RTProgramState

Property NumRestarts As Long

Property KernelTime As Variant

Property UserTime As Variant

Property ExecutionTime As Variant

Property CPU As Long

Property ThreadCount As Long

Property PriorityClassAs String

Property ReadIOCount As Long

Property WriteIOCount As Long

Property OtherIOCount As Long

Property ReadIOBytes As Long

Property WriteIOBytes As Long

Property OtherIOBytes As Long

Property PrivateSize As Long

Property CommitSize As Long

Property VMSize As Long

Property MinWorkingSetSize As Long

Property MaxWorkingSetSize As Long

Property PageFaults As Long

Property DeltaKernelTime As Variant

Property DeltaUserTime As Variant

Property DeltaExecutionTime As Variant

Property DeltaReadIOCount As Long

Property DeltaWriteIOCount As Long

Property DeltaOtherIOCount As Long

Property DeltaReadIOBytes As Long

Property DeltaWriteIOBytes As Long

Property DeltaOtherIOBytes As Long

Property DeltaPrivateSize As Long

Property DeltaCommitSize As Long

Property DeltaVMSize As Long

Property DeltaPageFaults As Long

RTLaunchTasks/RTLaunchTask

The tasks collection is a collection of scheduled tasks currently active with the launcher. A task is a unit of work associated with a time or times that (when executed) calls a given script subroutine. Tasks are useful for performing regular (or occasional) system functions.

The tasks collection supports standard collection syntax including the default item method and the VB “ForEach” syntax. Tasks are indexed by index and by name.

The task contains properties that describe when the task is scheduled and the name of the routine to execute when the task is fired. When adding a task, the application supplies the name of a subroutine to call and a time specification. This string can contain either an asterisk (‘*’) meaning all values or a comma-separated list of values that are either numbers or hyphen-separated ranges. There is a value for Minute, Hour, either Day or Date and Month. For instance:

If you don’t specify an argument for a date,* is assumed.

RTLaunchTask Methods and Properties

Property Name As String

Returns the name of the script routine to be executed.

Property Minute As String

Gets or sets the minute specification for the task.

Property Hour As String

Gets or sets the hour specification for the task.

Property Day As String

Gets or sets the day specification for the task.

Property Date As String

Gets or sets the date specification for the task.

Property Month As String

Gets or sets the month specification for the task.

Property CallCount As Long

Returns the number of times the task has executed.

Property LastTime As Variant

Returns the time at which the task was last executed.

Property PropName(RTTaskDispIds prop) As String

For a given RTTaskDispId, returns the name of the property. This can be useful when handling task change events.

Property Admin As RTLaunchAdmin

Returns a reference to the launcher object.

Property Parent As RTLaunchAdmin

Returns a reference to the parent object (i.e. the Admin Object).

Property Verbose As Boolean

Gets or sets the amount of log messages emitted by the program.

RTLaunchTools/RTLaunchTool

The tools collection is a collection of tools used by monitor applications to populate its Tools menu. Although this is strictly a collection of elements related to the monitor program, the launcher provides a convenient central location for storing this information. By default, the tools collection (and, consequently, the menu) is populated by the default start up scripts.

The tools collection supports standard collection syntax including the default item method and the VB “ForEach” syntax.

RTLaunchTool Methods and Properties

Property Name As String

Returns the name of the tool.

Property CommandLine As String

Gets or sets the command line associated with the tool.

Property PropName(RTToolDispIds prop) As String

For a given RTToolDispId returns the name of the property. This can be useful when handling tool change events.

Property Admin As RTLaunchAdmin

Returns a reference to the launcher object.

Property Parent As RTLaunchAdmin

Returns a reference to the parent object (i.e. the Admin Object).

Property Verbose As Boolean

Gets or sets the amount of log messages emitted by the program.

The Launcher API

The standard software installation disk contains the API for the launcher application to allow customers to implement components that interact with the launcher. By default, the launcher should be able to monitor and manage user code out of the box. However, additional levels of integration with the object model are possible through the API. For instance, it is possible to connect user objects into the launcher object tree on the fly providing a single navigational model for end users. In this way, users can advertise the ability to be configured on the fly and other internal functionality.

The launcher API is contained in RTLaunchApi.h in the Examples/C++/Include directory. It consists of a class wrapper for the RTLaunchAdmin object plus some primitive access code and can form the basis of more sophisticated monitoring applications.

Appendix A: The Launcher Command Line Options

The launcher supports the following command line options:

/register

Registers the launcher as a system service. The service is only registered: it is not started. It is, however, started on the next reboot of the host.

/unregister

If the launcher is currently running as a service it is stopped and then removed from the Service Control Manager (SCM).

/start

If the launcher is not registered as a service, it is registered. It is then automatically started. Note that the instance of the launcher with the /start command line option will return immediately and a new instance run in the background using the SCM.

/stop

If the launcher is currently registered and running it is stopped.

All the command line options are mutually exclusive. Running the launcher without command line options causes it to be run in UserMode. Only one instance of the launcher can be run at any given time.

Appendix B: Launcher Global Configurations

The launcher has a number of basic configurations stored in the registry key HKLM\SYSTEM\CurrentControlSet\Control\RTLaunch\. Where the default is being used, the entry may not exist. The entries are:

Appendix C: Dataworks Enterprise Configurations

As stated above, the launcher start-up attempts to read configurations from the registry. The installation program creates these configurations depending on which components are installed.

By default, the launcher assumes that installed modules are contained in the registry key:

HKLM\SYSTEM\CurrentControlSet\Control\RTLaunch\Launch

Each installed module has a key under “Launch” containing installation and other per-module information:

For each module entry that is enabled, the launcher creates an entry in its modules list.

For each module, the launcher opens the “Instances” key. The instances key contains a list of sub-keys each representing a program or script to run as part of the module. Each of these keys has a name, which is used as the program instance name in the monitor program. By default, this name is “Default”.

The launcher cycles through each installed component and loading the program or script and executing them.

The following is an example of this registry structure.

	Launch\

		Remote Client\
			Enabled				dword:00000001
			KeyFile				RemoteClnt.exe"
			Instances\
				Default\
					Enabled		dword:00000001
					RunProgram		RemoteClnt.exe –config RemoteClnt
				Backup\
					Enabled		dword:00000001
					RunProgram		RemoteClnt.exe –config RemoteClnt2
			Upgrade\
				UpgradePath		http://upgrade_host/Upgrade"
				UpgradeModule		RemoteClnt.inf

		Remote Server
			Enabled				dword:00000001
			KeyFile				RemoteSvr.exe"
			Instances\
				Default\
					Enabled		dword:00000001
					RunProgram		RemoteSvr.exe
			Upgrade\
				UpgradePath		http://upgrade_host/Upgrade"
				UpgradeModule		RemoteSvr.inf
		WAP Alerter\
			Enabled				dword:00000001
			Dependencies			Remote Client
			Instances\
				Default\
					RunScript		InvokeWAP.vbl
					Enabled		dword:00000001

Appendix D: Launcher Log Messages

At the time of writing the following log messages are defined: