Script Service Reference
Program ID: newObjects.scpsvc.ScriptHolder 

Sample creation:
Set svc = CreateObject("newObjects.scpsvc.ScriptHolder")

If the service is not running it will be started.

Properties, methods and events

Script Returns the running script. The calling application use it to access the subs/functions and variables/properties of the running script.

Suppose in the script loaded in the Script Service you have a function defined as follows:

Function MyFunction(param1, param2)
' Function body
 MyFunction = something
End Function

Then it may be called from an ASP page running on the same machine:

Set svcObj = CreateObject("newObjects.scpsvc.ScriptHolder")
resultVariable = svcObj.Script.MyFunction(value1, value2)

This will invoke this function in the running script and return the result.

The script must be running in order to use this property. If it is unloaded, or failed to load (because of an error in the configuration or syntax error in the script) an error will occur.
Host Returns the script hosting object. The Script Service is implemented using the ScriptManager2 object, it is created and initialized by the service and can be obtained through this property. In general direct access to this object is not required, but through it some advanced operations can be performed over the script (see ScriptManager2 reference for detailed description of the members of the object). Special attention deserves the IsDefined method - if you prefer to avoid error handling in the application that calls methods of the script it can be used to determine if a given member is actually defined.

For example the above sample can be done this way:

Set svcObj = CreateObject("newObjects.scpsvc.ScriptHolder")
If svcObj.Host.IsDefined("MyFunction") Then
  resultVariable = svcObj.Script.MyFunction(value1, value2)
Else
  Response.Write "The method does not exists in the running script"
End If
Version Returns a version/about string.
Reload Immediately reloads the running script. Configuration is reloaded too. After making any changes instead of restarting the service you can call this method to apply the new settings and load the updated script. Method returns after starting the script therefore you can continue and call script functions immediately after it (see Script property). If the script fails to load because of a wrong configuration or syntax error in the script and error will occur (of course it can be trapped using OnError in VBScript or try .. catch in JScript)..
Unload Unloads the running script. After calling this method the script is unloaded and may no longer be called (through the Script property), nor OnTimer event occurs. This is rarely needed - for example you may need to correct urgently a fatal logical error in the script and you want to disable it temporarily. To load and start it again - call the Reload method.
Terminate Terminates/stops the Script service. The service is stopped after calling this method. In application mode the application exits. The service will be started automatically next time the CreateObject is called to create it. This method is provided for cases where the process must be stopped explicitly - for example the running script may be using an ActiveX DLL you want to replace/upgrade and you need to unlock it.
OnTimer Handling is required. You must implement function named OnTimer in the service script. Sample prototype: 
Function OnTimer
 ' Do the main tasks
 OnTimer = "Everything is ok ..."
End Function

(See also the preinstalled sample script). This function is called each time the interval specified elapses - see the Interval configuration option. The returned value is logged to the EventLog (if not disabled - see DiableEventLog configuration entry), to the log file (see ReportFile configuration entry) and shown in the application window if Script Service is running in application mode. The value must be string in order to be logged, if you return something else (for example Boolean value or nothing) it will be ignored.

The implementation may vary, but in general this event is supposed to give the script a chance to do some scheduled work. In other words OnTimer function is the only required element in the service script. You may ignore it and just return if you are designing a script that will provide only on-duty services (e.g. set of functions to be called from various applications). In most cases it is required because this gives to the script chance to do something on its own decision. If you need complex scheduling you can implement it by checking the current time (Now function in VBScript) and perform certain tasks if certain conditions, you choose, are met. Such a code can be implemented easily in VBScript or JScript. Leaving the detailed logic to the script allows you to create any scheduling scheme you want. Your scheduling scheme may need inspection of a DB and many other data sources there is no way to implement something that will cover all the possible needs in the service binary file. In the same time it is a matter of 2-3 lines of code to make time calculations in a script language thus you need only to set the interval to value that will be appropriate for the scheduling scheme. For example if you need to do something 2-3 times per day Interval can be set to one hour and this will be enough - the script will check the system time and see which task (if any) must be done this time. If you need to perform the tasks as soon as possible you will probably prefer smaller interval - 5 minutes for example.

One example. Suppose you want to perform something after midnight:

Dim lastTimeTaskPerformed
lastTimeTaskPerformed = Null
Function OnTimer
  ' Other code, checking for other tasks for example
  ' ...
  If Not IsNull(lastTimeTaskPerformed) And Day(Now) = Day(lastTimeTaskPerformed) Then
    ' Do nothing
  Else
    ' Do the task
    lastTimeTaskPerformed = Now
  End If
  ' ...
End Function

This will perform the task only once per day - at the first call of the OnTimer for that day.

 
newObjects Copyright 2001-2006 newObjects [ ]