Scripting Entry Points
A control script consists of a set of entry point functions (for example, IsAlive) for the Generic Script resource DLL. The Resource Monitor calls these scripted entry point functions during cluster operation. Except for the Open function, the scripted entry point functions serve the same purpose as the same-named resource DLL entry point functions implemented using the Failover Cluster API. For more information, see Implementing Resource DLLs.
A control script must implement the LooksAlive and IsAlive functions and can also implement the functions Open, Online, Offline, Close, and Terminate.
Note
You should not store control script files on cluster disks. Although these drives may seem to be the ideal location because all nodes in the cluster can access them, storing control script files there causes problems when you upgrade either the Cluster service or the application software, especially if the cluster is in a production environment. Such upgrades require the cluster to be shut down completely. If you choose instead to install control script files on all nodes in the cluster, you can use a rolling upgrade approach upgrading each node individually without affecting the operation of the cluster.
Script Execution
A Resource Monitor call to either of the time-critical entry point functions LooksAlive or IsAlive executes directly, without calling other entry point functions and without loading or unloading the script. A Resource Monitor call to any other entry point function (for example, Online) generates associated Resource Monitor entry point function calls (for example, to Open) and may cause the script to load or unload. For more information on the Resource Monitor actions for each entry point function call, see the following table.
In a control script, code within the script body, outside any of the entry point functions, is executed when the script is loaded. Code within an entry point function is executed whenever that function is called. For example, code within the Open function is executed not only when the script is opened, but also when Open is called prior to Online or Close.
| Function name | Resource monitor actions |
|---|---|
| [Open](/previous-versions/windows/desktop/api/ResApi/nc-resapi-popen_routine) | Perform when the script is opened. Resource Monitor will:
|
| [Online](/previous-versions/windows/desktop/api/ResApi/nc-resapi-ponline_routine) | Perform when the resource is placed online. Resource Monitor will:
|
| [LooksAlive](/previous-versions/windows/desktop/api/ResApi/nc-resapi-plooks_alive_routine) | Perform one or more very fast, cursory checks of the specified instance with the emphasis on detecting potential problems rather than verifying operational status. [IsAlive](/previous-versions/windows/desktop/api/ResApi/nc-resapi-pis_alive_routine) will determine whether the instance is really operational. Take no more than 300 milliseconds to return a value. Resource Monitor calls [LooksAlive](/previous-versions/windows/desktop/api/ResApi/nc-resapi-plooks_alive_routine) repeatedly at a specified time interval (for example, once every five seconds). |
| [IsAlive](/previous-versions/windows/desktop/api/ResApi/nc-resapi-pis_alive_routine) | Perform a complete check of the resource to see if it is functioning properly. The set of procedures you need to use depends on your resource. For example, a database resource should check to see that the database can write to the disk and perform queries and updates to the disk. If the resource has definitely failed, return FALSE. The Resource Monitor immediately sets the status of the resource to "ClusterResourceFailed" and calls the [Terminate](/previous-versions/windows/desktop/api/ResApi/nc-resapi-pterminate_routine) entry point function. Resource Monitor calls [IsAlive](/previous-versions/windows/desktop/api/ResApi/nc-resapi-pis_alive_routine) repeatedly at a specified time interval (for example, once every sixty seconds). |
| [Offline](/previous-versions/windows/desktop/api/ResApi/nc-resapi-poffline_routine) | Perform when the resource is placed offline. Resource Monitor will:
|
| [Close](/previous-versions/windows/desktop/api/ResApi/nc-resapi-pclose_routine) | Perform when the script is closed. Resource Monitor will:
|
| [Terminate](/previous-versions/windows/desktop/api/ResApi/nc-resapi-pterminate_routine) | Perform when terminating the script. Resource Monitor will:
|
Parameters and Return Values
Parameters are not passed in a call to an entry point function in a script.
An entry point function can optionally set a return value. A return value of zero (or "true") indicates success and does not appear in the cluster log. The functions LooksAlive and IsAlive should return the Boolean "true" rather than a numeric zero. Success is assumed if the return value is not set explicitly in the function.
A nonzero return value (or false) indicates failure and appears in the cluster log.
Accessing Resources
The Generic Script resource DLL creates a Resource object for each scripted resource instance. The Resource object enables a control script to log information, manipulate properties, and access the resource name. For more information, see Resource Object.
Note
To avoid deadlocks, do not use the Cluster Automation Server, the Failover Cluster WMI Provider, or otherwise make any calls to the Cluster API from your control script. All interaction with the cluster should be done through the Resource object.
Instance Management
For each instance of a scripted resource, the Generic Script resource DLL runs an instance of a control script in a separate thread. Thus there is no need to implement instance management in a control script; as far as a control script is concerned, there is one and only one resource instance.
Control Script Layout
The following example illustrates the layout of a control script in VBScript that implements all the supported entry point functions. For executable script resource examples, see Scripted Resource Example.
' ... Insert your script-level global variables and definitions here
' ... e.g. Resource.LogInformation("ScriptWide Global Stuff is Run")
' ... Code placed here is outside any entry point function.
' ... It is run once when the script is created
' ... and once when the script is placed online.
Function Open( )
' ... Insert your Open code here.
End Function
Function Online( )
' ... Insert your Online code here.
' ... Online is executed once when the resource is placed online.
End Function
Function LooksAlive( )
' ... Insert your LooksAlive code here.
' ... LooksALive is executed at specified intervals.
End Function
Function IsAlive( )
' ... Insert your IsAlive code here.
' ... IsAlive is executed at specified intervals
' ... or when a LooksAlive call fails.
End Function
Function Offline( )
' ... Insert your Offline code here.
' ... Offline is executed once when the resource is placed offline.
End Function
Function Close( )
' ... Insert your Close code here.
End Function
Function Terminate( )
' ... Insert your Terminate code here.
' ... Terminate is executed once when the script terminates.
End Function