Document last modified: 5/10/2001 (samc) ======= LAFitup ======= -------- Overview -------- LAFitup is a utility designed to allow programs that cannot normally run in the background to do so. LAFitup monitors the programs it starts and restarts them if they exit unexpectedly. LAFitup also provides a capability to send a monitored processes notice to exit gracefully without just killing it outright. Lastly, LAFitup exposes a COM interface to allow other programs to dynamically modify its configuration and interrogate its status. LAFitup monitors "profiles", which are a collection of attributes about a program -- its command line, its working directory, its startup priority and so on. Each profile has four defined "states" -- Start, Stop, Pause and Unpause. The Start state defines the action to be taken when the profile is started. A command line is executed, which produces a running process. That process is then monitored. If it exits, the command is run again. If LAFitup is told to change states -- to become paused, for instance -- the command from the Pause state is run. When LAFitup is paused, no monitoring is performed; if the process started by the Start state exits, it will not be restarted. When LAFitup is unpaused, the command from the Unpause state is run and monitoring resumes. If the process started by the Start state has exited, it will be restarted. NOTE: The Start state will be restarted _after_ the Unpause state has been run. Lastly, LAFitup can be told to Stop, which will run the command from the Stop state and wait for all the processes it is monitoring to exit. Once they've all exited, LAFitup will exit. It is important to note that LAFitup monitors the processes it starts for the Pause, Unpause and Stop states to ensure they exit. Because the Pause, Unpause and Stop states are most likely to be triggered by the NT Service Control Manager, a relatively short amount of time is available to complete the command before the SCM reports an error to the user. When the Pause and Unpause states are entered, the Pause and Unpause processes must exit within 35 seconds or LAFitup will forcibly kill them. When the Stop state is entered, the Stop process must exit within 35 seconds and the Start process must exit within 40 seconds or LAFitup will forcibly kill them. This last is particularly important, as it is most likely to occur during system shutdown when time is critical. LAFitup does all of this by running both as an NT service and an out-of-process COM server. It expects to be configured to run as the SYSTEM account and to have access to the desktop. This creates a series of problems for which it is necessary to review LAFitup's solutions. First, an out-of-process COM server is an EXE that is started by the system when an interface it exposes is created. NT services are EXEs started by the system either at boot-time or when it is signaled to do so. When LAFitup is started as an NT service, the expectation is that it will start up its profiles and begin monitoring them. However, when it is started as an out-of-process COM server, the only reason it is being started may be to stop the service if it is running. Therefore, it doesn't make sense to start any profiles until explicitly told to do so. Lastly, when LAFitup is started as a program at the command line, the only reason may be to discover how to uninstall it. Again, starting all the profiles doesn't make much sense. For those reasons, when LAFitup is started by the NT Service Control Manager, it starts all of its processes and begins monitoring them. When it is started as an out-of-process COM server, it does not start any processes and tells the NT Service Control Manager it is "Paused". NOTE: This "Paused" state is special: when "Unpause" is clicked in the NT Service Control Manager, LAFitup will only run the processes from the "Start" states, not the "Unpause" states. This is because it remembers it was never started in the first place, so there is nothing to unpause. Unfortunately, there is no way to indicate this to the user in the Service Control Manager. When LAFitup is started from the command line with no arguments, it displays a help message and exits. NOTE: All of this is in reference to when LAFitup is not running and is started. Simply instantiating an interface from LAFitup as an out-of-process COM server will not have any effect on an already-running service (unless that interface is explicitly used to change the service's state). ----- Usage ----- From the command line, the following parameters are available: -install Stops LAFitup if it is running, uninstalls it as an NT service and an out-of-process COM server and installs the invoked executable as an NT service and an out-of-process COM server. NOTE: This flag can safely be used to upgrade LAFitup -- it does not need to be "-uninstall"ed first. -uninstall Stops LAFitup if it is running and uninstalls it as an NT service and an out-of-process COM server. NOTE: This flag does not remove the profiles from the registry. -start Sends a "Start" signal to the LAFitup NT service. NOTE: This flag is provided for convenience only -- there is no difference between using it and starting the service through the NT Service Control Manager. -stop Sends a "Stop" signal to the LAFitup NT service. NOTE: This flag is provided for convenience only -- there is no difference between using it and stopping the service through the NT Service Control Manager. -pause Sends a "Pause" signal to the LAFitup NT service. NOTE: This flag is provided for convenience only -- there is no difference between using it and pausing the service through the NT Service Control Manager. -continue Sends a "Continue" signal to the LAFitup NT service. NOTE: This flag is provided for convenience only -- there is no difference between using it and unpausing the service through the NT Service Control Manager. -help Displays the usage instructions and does nothing else. Exactly one parameter must be given at the command line. ------------ Installation ------------ To install LAFitup as an NT service, run it with the "-install" flag. To start it, use the NT Service Control Manager or the "-start" flag. ------------- Configuration ------------- LAFitup stores all of its configuration information in the registry under the following key: HKEY_LOCAL_MACHINE\SOFTWARE\LAF\LAFitup To create a new profile, create a new key at the above location with the profile's name. For example, to create a profile named "Random Important Program", create the following key: HKEY_LOCAL_MACHINE\SOFTWARE\LAF\LAFitup\Random Important Program NOTE: A profile's name must be no longer than 256 characters. LAFitup looks for one value under each profile's key: FaultTolerance (DWORD) Whether LAFitup is to ignore errors in opening the files for stdin, stdout and stderr, whether LAFitup is to ignore an invalid working directory or both. The legal values are: 0 - Do not ignore file errors or invalid working directories 1 - Ignore file errors; do not ignore invalid working directories 2 - Ignore invalid working directories; do not ignore file errors 3 - Ignore both file errors and invalid working directories If this value is missing, the default value is 0 (do not ignore file errors or invalid working directories). Every profile must contain a key for each of its four states: "Start", "Stop", "Pause" and "Unpause". Continuing the above example, the following keys would need to be created: HKEY_LOCAL_MACHINE\SOFTWARE\LAF\LAFitup\Random Important Program\Start HKEY_LOCAL_MACHINE\SOFTWARE\LAF\LAFitup\Random Important Program\Stop HKEY_LOCAL_MACHINE\SOFTWARE\LAF\LAFitup\Random Important Program\Pause HKEY_LOCAL_MACHINE\SOFTWARE\LAF\LAFitup\Random Important Program\Unpause LAFitup looks for six values under each state's key: CommandLine (String) The full command line to start for the state. This should be entered exactly as it would be from the command line, including parameters, spaces, quotes, etc. The process will be started with access to LAFitup's desktop -- GUI applications can thus be started. If this value is empty or missing, the state will not be used. CommandLine must be no longer than 2048 characters. StartupPriority (DWORD) The "priority" the process will be started with. The legal values are: 0 - Idle 1 - Normal 2 - High 3 - Realtime NOTE: Always select 1 (Normal) unless you have a STRONG reason not to. LAFitup runs with Normal priority and will have a hard time trying to stop a High priority process that has entered an endless loop. If a Realtime priority process enters an endless loop, the operating system will begin having difficulty running or even shutting down. Conversely, if a process is started with Low priority, it may become resource-starved if the system becomes busy. If this value is missing, the default value is 1 (Normal). StderrFilename (String) The file to open as the process' stderr stream. This is useful to catch the process' output into a file for logging. If this file already exists, it will be appended to (not overwritten). This file must be openable or the process will fail to start unless the fault tolerance is set accordingly. NOTE: This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty, missing or the same as StdoutFilename, the process' stderr stream will be connected to the same file as its stdout stream. StderrFilename must be no longer than 512 characters. StdinFilename (String) The file to open as the process' stdin stream. This is useful if the process to be started requires some initial input to get going. NOTE: Do not attempt to use this file as a pipe to feed the process more input while it is running -- NT locks the file against other processes opening it for writing while the process is running. This file must exist or the process will fail to start unless the fault tolerance is set accordingly. This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty or missing, the process' stdin stream will be connected to LAFitup's stdin stream (no input possible). StdinFilename must be no longer than 512 characters. StdoutFilename (String) The file to open as the process' stdout stream. This is useful to catch the process' output into a file for logging. If this file already exists, it will be appended to (not overwritten). This file must be openable or the process will fail to start unless the fault tolerance is set accordingly. NOTE: This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty or missing, the process' stdout stream will be connected to LAFitup's stdout stream (the bit bucket). StdoutFilename must be no longer than 512 characters. WorkingDirectory (String) The directory the process should be started in. To the process, it will appear that a user started a command prompt, used "CD" to change to the WorkingDirectory, then started the process. NOTE: This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty or missing, the process will be started in LAFitup's working directory (probably C:\WINNT). WorkingDirectory must be no longer than 512 characters. Any values not detailed above will be ignored and will be erased if LAFitup's configuration is updated through its COM interface. NOTE: If LAFitup's configuration in the registry is modified while LAFitup is running, LAFitup will NOT load the changes until it is restarted. If the configuration must be modified without restarting LAFitup, the COM interface must be used. ============= COM Interface ============= LAFitup exposes six interfaces, only four of which should be instantiated directly. NOTE: Though LAFitup is internally thread-safe, its interfaces are not. The effect of calling properties or methods on a single object from multiple threads is undefined. --------------------- LAFitup.Configuration --------------------- LAFitup.Configuration is a collection that will enumerate all of the profiles, no matter what their current state may be. Enumerating LAFitup.Configuration in a "For Each" loop will return Profile objects. LAFitup.Configuration exposes the following properties: Integer Count (read-only) Count returns the number of profiles, no matter what their current state is. String ErrorMessage (read-only) ErrorMessage returns an English explanation of the outcome of the last operation if it produced a non-success result. If the last operation succeeded, ErrorMessage contains an empty string. Profile Item(String name) (read-only, default) Item returns a Profile object for the profile with the given name. If the profile is not found, an error results. NOTE: Item is the default property, meaning that the following code: Set config_obj = Server.CreateObject("LAFitup.Configuration") Set foo = config_obj.Item("bar") is equivalent to: Set config_obj = Server.CreateObject("LAFitup.Configuration") Set foo = config_obj("bar") Long LastResult (read-only) LastResult returns the last return code that was generated by a call to a method or property on this object. This is handy for making sure a property assignment was successful without having to set ThrowErrors to True. The value returned corresponds to one of the defined constant return code values in LAFitup's typelib and in lafitup_vbs.txt. Long NamedConstant(String name) (read-only) NamedConstant returns the numeric value of a named constant defined in LAFitup's typelib and in lafitup_vbs.txt for environments that cannot access either source (such as the Windows Scripting Host). NOTE: NamedConstant is _much_ slower than using the defined constants from the typelib or from lafitup_vbs.txt and should _only_ be used if no other technique is available to get the values. Boolean ThrowErrors (read/write) ThrowErrors controls how LAFitup's COM interface returns non-success result codes. When ThrowErrors is equal to True, LAFitup generates an ATL COM error for any non-success result. In ASP, this will stop the page processing at the line where the error occurs unless an "On Error Resume Next" statement is used. This can be very handy for debugging. The default is False. NOTE: Any objects returned by this interface have their ThrowErrors value set to this object's value (it is passed on during object creation). This includes objects returned when this object is enumerated in a "For Each" loop as well as objects returned by the Item property. LAFitup.Configuration exposes the following methods: Function DeleteProfile(String name) As Long Deletes the profile of the given name, if it exists. Any processes belonging to the profile are abandoned and the profile is removed from the active configuration in memory. The configuration is then saved into the registry. The return value is a return code detailed below. Function SaveProfile(Profile changed_profile) As Long Saves the new profile if the given object was instantiated directly or saves the changes to the existing profile if the given object was retrieved through enumerating this interface in a "For Each" loop or through the Item property. The profile is saved both to the active configuration in memory and to the registry. The profile's state is not changed, nor do any configuration changes effect the running profile unless it is signaled to change state. The return value is a return code detailed below. Sub VersionInfo(ByRef Variant file_major, ByRef Variant file_minor, ByRef Variant file_revision, ByRef Variant file_build, ByRef Variant product_major, ByRef Variant product_minor, ByRef Variant product_revision, ByRef Variant product_build, ByRef Variant additional_info) VersionInfo() provides information on the version of LAFitup that is running without requiring a visit to the server's console. The first eight parameters can be used to assemble the file version and the product version in the form W.X.Y.Z where W is the major version, X is the minor version, Y is the revision number and Z is the build number. The last parameter, additional_info, can be used to return other relevant information that the author saw fit to provide. --------------- LAFitup.Process --------------- LAFitup.Process is an object that is only meant to be returned by other objects. Though it is possible to instantiate an object from this interface directly, any methods or properties called on the object will return an error. LAFitup.Process exposes the following properties: Long CurrentState (read-only) The current state of the profile attached to this process is returned. The possible values are: LAFITUP_start The profile is running. LAFITUP_stop The profile is not running. LAFITUP_pause The profile was running but has been paused. The original "Start" process may have exited but will not be checked again until the process is unpaused. String ErrorMessage (read-only) ErrorMessage returns an English explanation of the outcome of the last operation if it produced a non-success result. If the last operation succeeded, ErrorMessage contains an empty string. Long LastResult (read-only) LastResult returns the last return code that was generated by a call to a method or property on this object. This is handy for making sure a property assignment was successful without having to set ThrowErrors to True. The value returned corresponds to one of the defined constant return code values in LAFitup's typelib and in lafitup_vbs.txt. Long NamedConstant(String name) (read-only) NamedConstant returns the numeric value of a named constant defined in LAFitup's typelib and in lafitup_vbs.txt for environments that cannot access either source (such as the Windows Scripting Host). NOTE: NamedConstant is _much_ slower than using the defined constants from the typelib or from lafitup_vbs.txt and should _only_ be used if no other technique is available to get the values. Long PID (read-only) If the process is started or paused, the Windows NT process identifier is returned. This is the same identifier shown in Task Manager's list of processes. Profile Profile (read-only) Returns the Profile object this Process object represents. Date StartDate (read-only) If the process is started or paused, the date and time at which the "Start" process was started is returned. Boolean ThrowErrors (read/write) ThrowErrors controls how LAFitup's COM interface returns non-success result codes. When ThrowErrors is equal to True, LAFitup generates an ATL COM error for any non-success result. In ASP, this will stop the page processing at the line where the error occurs unless an "On Error Resume Next" statement is used. This can be very handy for debugging. The default is False. NOTE: Any objects returned by this interface have their ThrowErrors value set to this object's value (it is passed on during object creation). This includes objects returned by the Profile property. LAFitup.Process exposes the following methods: Function ChangeState(Long new_state, Optional Long delay_secs = 0) As Long Signals the process to change to the state represented by new_state after delay_secs seconds. If delay_secs is not given or is equal to 0, the state change is signaled immediately. Otherwise, a worker thread waits delay_secs seconds before signalling the process to change state while ChangeState() returns immediately. The valid values for new_state are: LAFITUP_start Only valid when the process is stopped. LAFITUP_stop Only valid when the process is started or paused. LAFITUP_pause Only valid when the process is started. LAFITUP_unpause Only valid when the process is paused. An additional value exists that does not correspond with the four states in which a process may exist: LAFITUP_abandon Only valid when the process is started or paused. Abandoning a process stops the monitoring of the process but does not effect the process running on the host. If the process later exits, no actions will be taken to restart it. After a process has been abandoned, the Profile is considered to be Stopped. NOTE: If the abandoned process is still running, any files opened for its stdout and stderr streams will remain open until it exits. The profile may not be able to start again unless its fault tolerance is set to ignore file errors or its stdout and stderr targets are changed. The return value is a return code detailed below. Sub VersionInfo(ByRef Variant file_major, ByRef Variant file_minor, ByRef Variant file_revision, ByRef Variant file_build, ByRef Variant product_major, ByRef Variant product_minor, ByRef Variant product_revision, ByRef Variant product_build, ByRef Variant additional_info) VersionInfo() provides information on the version of LAFitup that is running without requiring a visit to the server's console. The first eight parameters can be used to assemble the file version and the product version in the form W.X.Y.Z where W is the major version, X is the minor version, Y is the revision number and Z is the build number. The last parameter, additional_info, can be used to return other relevant information that the author saw fit to provide. ----------------- LAFitup.Processes ----------------- LAFitup.Processes is a collection that will enumerate all of the processes currently being monitored -- the Start processes for each of the currently started profiles. Enumerating LAFitup.Processes in a "For Each" loop will return Process objects. LAFitup.Processes exposes the following properties: Integer Count (read-only) Count returns the number of currently monitored processes. String ErrorMessage (read-only) ErrorMessage returns an English explanation of the outcome of the last operation if it produced a non-success result. If the last operation succeeded, ErrorMessage contains an empty string. Profile Item(String name) (read-only, default) Item returns a Profile object for the profile with the given name. If the profile is not found, an error results. With the returned profile object, the associated process object can be accessed through the Process property. This property returns a Profile object instead of a Process object so an unstarted Profile can be started. NOTE: Item is the default property, meaning that the following code: Set processes_obj = Server.CreateObject("LAFitup.Processes") Set foo = processes_obj.Item("bar") is equivalent to: Set processes_obj = Server.CreateObject("LAFitup.Processes") Set foo = processes_obj("bar") Long LastResult (read-only) LastResult returns the last return code that was generated by a call to a method or property on this object. This is handy for making sure a property assignment was successful without having to set ThrowErrors to True. The value returned corresponds to one of the defined constant return code values in LAFitup's typelib and in lafitup_vbs.txt. Long NamedConstant(String name) (read-only) NamedConstant returns the numeric value of a named constant defined in LAFitup's typelib and in lafitup_vbs.txt for environments that cannot access either source (such as the Windows Scripting Host). NOTE: NamedConstant is _much_ slower than using the defined constants from the typelib or from lafitup_vbs.txt and should _only_ be used if no other technique is available to get the values. Boolean ThrowErrors (read/write) ThrowErrors controls how LAFitup's COM interface returns non-success result codes. When ThrowErrors is equal to True, LAFitup generates an ATL COM error for any non-success result. In ASP, this will stop the page processing at the line where the error occurs unless an "On Error Resume Next" statement is used. This can be very handy for debugging. The default is False. NOTE: Any objects returned by this interface have their ThrowErrors value set to this object's value (it is passed on during object creation). This includes objects returned when this object is enumerated in a "For Each" loop as well as objects returned by the Item property. LAFitup.Processes exposes the following method: Sub VersionInfo(ByRef Variant file_major, ByRef Variant file_minor, ByRef Variant file_revision, ByRef Variant file_build, ByRef Variant product_major, ByRef Variant product_minor, ByRef Variant product_revision, ByRef Variant product_build, ByRef Variant additional_info) VersionInfo() provides information on the version of LAFitup that is running without requiring a visit to the server's console. The first eight parameters can be used to assemble the file version and the product version in the form W.X.Y.Z where W is the major version, X is the minor version, Y is the revision number and Z is the build number. The last parameter, additional_info, can be used to return other relevant information that the author saw fit to provide. --------------- LAFitup.Profile --------------- LAFitup.Profile is used to examine or modify the configuration of a profile or to create a new profile. NOTE: No changes to a Profile object are saved until the profile is saved by passing it to LAFitup.Configuration.SaveProfile(). NOTE: An object instantiated directly from this interface is assumed to be a new profile and cannot be saved if a profile of the same name already exists. To modify an existing profile, the Profile object must be retrieved via LAFitup.Configuration.Item(). LAFitup.Profile exposes the following properties: String ErrorMessage (read-only) ErrorMessage returns an English explanation of the outcome of the last operation if it produced a non-success result. If the last operation succeeded, ErrorMessage contains an empty string. Long FaultTolerance (read/write) FaultTolerance returns or sets the fault tolerance of this profile, which controls whether LAFitup is to ignore errors in opening the files for stdin, stdout and stderr, whether LAFitup is to ignore an invalid working directory or both. The possible values are: LAFITUP_fault_tolerance_none Do not ignore file errors or invalid working directories LAFITUP_fault_tolerance_ignore_bad_files Ignore file errors; do not ignore invalid working directories LAFITUP_fault_tolerance_ignore_bad_working_directory Ignore invalid working directories; do not ignore file errors The values can be bitwise ORed together to produce new combinations. The default value is LAFITUP_fault_tolerance_none. Long LastResult (read-only) LastResult returns the last return code that was generated by a call to a method or property on this object. This is handy for making sure a property assignment was successful without having to set ThrowErrors to True. The value returned corresponds to one of the defined constant return code values in LAFitup's typelib and in lafitup_vbs.txt. String Name (read/write) The name of this Profile. Names are case-insensitive and limited to 256 characters in length. Each profile must have a unique name. The default value is an empty string. Long NamedConstant(String name) (read-only) NamedConstant returns the numeric value of a named constant defined in LAFitup's typelib and in lafitup_vbs.txt for environments that cannot access either source (such as the Windows Scripting Host). NOTE: NamedConstant is _much_ slower than using the defined constants from the typelib or from lafitup_vbs.txt and should _only_ be used if no other technique is available to get the values. Process Process (read-only) Returns the Process object associated with this Profile object. State States(Long state) (read-only) Returns the State object associated with the given state. Though this property is read-only, the objects returned by it are not and should be used to configure the settings for each of the profile's states. The valid values for the state are: LAFITUP_start The commands to use when the profile is started. LAFITUP_stop The commands to use when the profile is stopped. LAFITUP_pause The commands to use when the profile is paused. LAFITUP_unpause The commands to use when the profile is unpaused. Boolean ThrowErrors (read/write) ThrowErrors controls how LAFitup's COM interface returns non-success result codes. When ThrowErrors is equal to True, LAFitup generates an ATL COM error for any non-success result. In ASP, this will stop the page processing at the line where the error occurs unless an "On Error Resume Next" statement is used. This can be very handy for debugging. The default is False. NOTE: Any objects returned by this interface have their ThrowErrors value set to this object's value (it is passed on during object creation). This includes objects returned by the Process and States properties. LAFitup.Profile exposes the following method: Sub VersionInfo(ByRef Variant file_major, ByRef Variant file_minor, ByRef Variant file_revision, ByRef Variant file_build, ByRef Variant product_major, ByRef Variant product_minor, ByRef Variant product_revision, ByRef Variant product_build, ByRef Variant additional_info) VersionInfo() provides information on the version of LAFitup that is running without requiring a visit to the server's console. The first eight parameters can be used to assemble the file version and the product version in the form W.X.Y.Z where W is the major version, X is the minor version, Y is the revision number and Z is the build number. The last parameter, additional_info, can be used to return other relevant information that the author saw fit to provide. --------------- LAFitup.Service --------------- LAFitup.Service controls LAFitup as an NT service in the same way the NT SCM does. It provides the ability to query or signal the NT service on the host. LAFitup.Service exposes the following properties: Long CurrentState (read-only) The NT service's current state is returned. The possible values are: LAFITUP_start The service is started. LAFITUP_pause The service is paused or was instantiated as an out-of-process COM server and has never been started. String ErrorMessage (read-only) ErrorMessage returns an English explanation of the outcome of the last operation if it produced a non-success result. If the last operation succeeded, ErrorMessage contains an empty string. Long LastResult (read-only) LastResult returns the last return code that was generated by a call to a method or property on this object. This is handy for making sure a property assignment was successful without having to set ThrowErrors to True. The value returned corresponds to one of the defined constant return code values in LAFitup's typelib and in lafitup_vbs.txt. Long NamedConstant(String name) (read-only) NamedConstant returns the numeric value of a named constant defined in LAFitup's typelib and in lafitup_vbs.txt for environments that cannot access either source (such as the Windows Scripting Host). NOTE: NamedConstant is _much_ slower than using the defined constants from the typelib or from lafitup_vbs.txt and should _only_ be used if no other technique is available to get the values. Date StartDate (read-only) Returns the date and time the NT service was started. Boolean ThrowErrors (read/write) ThrowErrors controls how LAFitup's COM interface returns non-success result codes. When ThrowErrors is equal to True, LAFitup generates an ATL COM error for any non-success result. In ASP, this will stop the page processing at the line where the error occurs unless an "On Error Resume Next" statement is used. This can be very handy for debugging. The default is False. LAFitup.Service exposes the following method: Function ChangeState(Long new_state, Optional Long delay_secs = 0) As Long Signals the service to change to the state represented by new_state after delay_secs seconds. If delay_secs is not given or is equal to 0, the state change is signaled immediately. Otherwise, a worker thread waits delay_secs seconds before signalling the service to change state while ChangeState() returns immediately. The valid values for new_state are: LAFITUP_start Only valid when the service is stopped. LAFITUP_stop Only valid when the service is started or paused. LAFITUP_pause Only valid when the service is started. LAFITUP_unpause Only valid when the service is paused. NOTE: Signaling the service to stop will cause the LAFitup process to exit. This will invalidate the object handle used by the caller to signal the state change. For that reason, it is recommended that the service be stopped with a delay long enough to allow the calling script to exit first. The return value is a return code detailed below. Sub VersionInfo(ByRef Variant file_major, ByRef Variant file_minor, ByRef Variant file_revision, ByRef Variant file_build, ByRef Variant product_major, ByRef Variant product_minor, ByRef Variant product_revision, ByRef Variant product_build, ByRef Variant additional_info) VersionInfo() provides information on the version of LAFitup that is running without requiring a visit to the server's console. The first eight parameters can be used to assemble the file version and the product version in the form W.X.Y.Z where W is the major version, X is the minor version, Y is the revision number and Z is the build number. The last parameter, additional_info, can be used to return other relevant information that the author saw fit to provide. ------------- LAFitup.State ------------- LAFitup.State is an object that is only meant to be returned by other objects. Though it is possible to instantiate an object from this interface directly, any methods or properties called on the object will return an error. LAFitup.State exposes the following properties: String CommandLine (read/write) CommandLine is the command run when the profile enters this state. This must be an absolute path (including the drive letter) that includes all the parameters as they would be typed at the command line. Do not use mapped drives or UNC paths. CommandLine must be no longer than 2048 characters. String ErrorMessage (read-only) ErrorMessage returns an English explanation of the outcome of the last operation if it produced a non-success result. If the last operation succeeded, ErrorMessage contains an empty string. Long LastResult (read-only) LastResult returns the last return code that was generated by a call to a method or property on this object. This is handy for making sure a property assignment was successful without having to set ThrowErrors to True. The value returned corresponds to one of the defined constant return code values in LAFitup's typelib and in lafitup_vbs.txt. Long NamedConstant(String name) (read-only) NamedConstant returns the numeric value of a named constant defined in LAFitup's typelib and in lafitup_vbs.txt for environments that cannot access either source (such as the Windows Scripting Host). NOTE: NamedConstant is _much_ slower than using the defined constants from the typelib or from lafitup_vbs.txt and should _only_ be used if no other technique is available to get the values. Long StartupPriority (read/write) The "priority" the process will be started with. The legal values are: LAFITUP_startup_idle "Low" priority. LAFITUP_startup_normal "Normal" priority. LAFITUP_startup_high "High" priority. LAFITUP_startup_realtime "Realtime" priority. NOTE: Always select LAFITUP_startup_normal unless you have a STRONG reason not to. LAFitup runs with Normal priority and will have a hard time trying to stop a High priority process that has entered an endless loop. If a realtime priority process enters an endless loop, the operating system will begin having difficulty running or even shutting down. Conversely, if a process is started with Low priority, it may become resource-starved if the system becomes busy. The default value is LAFITUP_startup_normal. String StderrFilename (read/write) The file to open as the process' stderr stream. This is useful to catch the process' error output into a file for logging. If this file already exists, it will be appended to (not overwritten). This file must be openable or the process will fail to start unless the fault tolerance is set accordingly. NOTE: This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty, missing or the same as StdoutFilename, the process' stderr stream will be connected to the same file as its stdout stream. StderrFilename must be no longer than 512 characters. String StdinFilename (read/write) The file to open as the process' stdin stream. This is useful if the process to be started requires some initial input to get going. NOTE: Do not attempt to use this file as a pipe to feed the process more input while it is running -- NT locks the file against other processes opening it for writing while the process is running. This file must exist or the process will fail to start unless the fault tolerance is set accordingly. This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty or missing, the process' stdin stream will be connected to LAFitup's stdin stream (no input possible). StdinFilename must be no longer than 512 characters. String StdoutFilename (read/write) The file to open as the process' stdout stream. This is useful to catch the process' output into a file for logging. If this file already exists, it will be appended to (not overwritten). This file must be openable or the process will fail to start unless the fault tolerance is set accordingly. NOTE: This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty or missing, the process' stdout stream will be connected to LAFitup's stdout stream (the bit bucket). StdoutFilename must be no longer than 512 characters. Boolean ThrowErrors (read/write) ThrowErrors controls how LAFitup's COM interface returns non-success result codes. When ThrowErrors is equal to True, LAFitup generates an ATL COM error for any non-success result. In ASP, this will stop the page processing at the line where the error occurs unless an "On Error Resume Next" statement is used. This can be very handy for debugging. The default is False. String WorkingDirectory (read/write) The directory the process should be started in. To the process, it will appear that a user started a command prompt, used "CD" to change to the WorkingDirectory, then started the process. NOTE: This value should be an absolute path, including the drive letter. Do not use mapped drives or UNCs. If this value is empty or missing, the process will be started in LAFitup's working directory (probably C:\WINNT). WorkingDirectory must be no longer than 512 characters. LAFitup.State exposes the following method: Sub VersionInfo(ByRef Variant file_major, ByRef Variant file_minor, ByRef Variant file_revision, ByRef Variant file_build, ByRef Variant product_major, ByRef Variant product_minor, ByRef Variant product_revision, ByRef Variant product_build, ByRef Variant additional_info) VersionInfo() provides information on the version of LAFitup that is running without requiring a visit to the server's console. The first eight parameters can be used to assemble the file version and the product version in the form W.X.Y.Z where W is the major version, X is the minor version, Y is the revision number and Z is the build number. The last parameter, additional_info, can be used to return other relevant information that the author saw fit to provide. ============ Return Codes ============ LAFitup uses the following return codes, which have the following meanings: LAFITUP_success The operation succeded. LAFITUP_error_no_such_profile The operation referenced a profile by name that does not exist or used a Profile object associated with a profile that no longer exists. LAFITUP_error_queryinterface_failed A call to QueryInterface() failed. This is an internal COM error that may indicate a serious problem. The LAFitup process should probably be restarted. LAFITUP_error_mutex_timeout An attempt to lock a mutex failed due to a timeout. This may indicate the system is very busy. If the problem persists, it probably indicates a programming error. LAFITUP_error_bad_parameter A bad parameter was given -- this may be an object of the wrong type, an out-of-range numeric value or an oversized string. LAFITUP_error_no_such_constant A constant was requested through a NamedConstant property that does not exist. LAFITUP_error_internal An internal error occurred. The LAFitup process should probably be restarted. If the problem persists, it may indicate a programming error. LAFITUP_error_string_too_long A string parameter was given that is too long. LAFITUP_error_value_out_of_range A numeric parameter was given that is not within the valid range for the operation. LAFITUP_error_saving_configurations An error occurred while attempting to save the active configurations to the registry. This may be a permissions issue -- check to ensure that LAFitup is running as SYSTEM and its registry keys are accessible. LAFITUP_error_state_not_appropriate The LAFitup service or a profile was signaled to change to a state that is not appropriate. For example, the service cannot be unpaused if it is stopped. LAFITUP_error_date_not_available A start date for a profile is not available because the profile is stopped. LAFITUP_error_no_such_process The operation referenced a Process object that is linked to a process or profile that no longer exists. LAFITUP_error_duplicate_name A profile of the given name already exists -- the new profile must either be renamed or the existing profile must be deleted or renamed. LAFITUP_error_missing_name All profiles must have a unique, non-empty name. The given profile cannot be saved without a name. LAFITUP_error_improper_instantiation An interface was instantiated directly that is only meant to be returned by another object. The object should be destroyed and aquired through a property or method on another interface. LAFITUP_error_not_implemented The method or property is not (completely) implemented in this version of LAFitup. It cannot be used. ======== Wishlist ======== Start the different processes as different users. How can the passwords be stored securely in the registry? Maybe read them from a file? Pause and unpause individual profiles instead of the whole service. Probably have to maintain a list of paused profiles instead of leaving them on keepalive_list. Process-level time limits for maximum running times instead of the global MAIN_LOOP_SIGNALED_TTL_SECS and MAIN_LOOP_ABSOLUTE_TTL_SECS. Profile-level startup conditions to delay starting a profile until CPU usage, available memory, available disk, etc. reaches acceptable levels. Profile-level max restarts, restart delay secs, autostart and autostart delay secs. Generate a JNI interface for this thing. Create an ASP-based admin tool to make configuration and control easier. Provide profile-level event handling -- commands to run if the machine is low on memory, commands to run occasionally and subcommand to run depending on the exit codes, etc. ========== Known bugs ========== LAFitup leaks a small amount of memory when it runs with only one profile. The leak occurs somewhere in the process of being signaled through its COM interface.