White Paper Series: #2
Author: Aaron Gilreath
 |
|
 Using NT Services for Tuxedo Domain Startup and ShutdownWhite Paper Sections
This White Paper's PurposeThe purpose of this paper is to discuss administrative considerations for starting and stopping a Tuxedo application on the Windows NT platform using NT Services. Two solutions for implementing NT Services will be presented to solve this problem. IntroductionPlease note that all mentions of "services" in this document refer to NT services, not to Tuxedo services. At first glance, you may think, "What is there to consider? You just boot the machine and start the Tuxedo domain." For the most part, that is all there is to it. However, before starting the Tuxedo application on a freshly booted NT machine, manual intervention is required to login the user to NT Security. For this same reason, the STARTUP folder, which executes programs when a user logs in, will not suffice to perform Tuxedo startup. Depending on the physical location of the machine, this can be an inconvenience for the administrator. What is needed is a way to start a Tuxedo domain without manual intervention at system startup and also a way to shutdown a Tuxedo domain from a remote machine. NT services can remedy some of the administrative headaches associated with manual intervention and remote access. The main benefits are:
NT services are usually thought of as system processes or device drivers. However, a service is just a Win32 process that provides additional features. These additional features, such as start, stop and pause/continue events, are standard components of a service and are implemented by the programmer. Services are managed by the Service Control Manager (SCM). The SCM executes the service and controls the behavior of the process. A service, which is usually executed in the background (no user interface), can be configured to run at system bootup before a user logs into the NT system security. Service ImplementationThis section explains two methods of implementing an NT Service. Method one uses Srvany while method two requires the implementation of the service using a C program. In both instances, the service will be installed into the SCM, and configured for startup behavior. The desired service functionality is to start a Tuxedo domain by executing a script containing, among other commands, tmboot. Also, the service will provide functionality to shutdown the Tuxedo domain also using a script containing tmshutdown. SrvanyThe easy method to create an NT service is to use Srvany, an NT Resource Kit utility. Srvany is a generic service that uses registry settings to receive command line arguments. The command line arguments specify a command script (.cmd) or Executable (.exe) program. Srvany then executes the command line arguments when the service is started. The down side to Srvany is that it implements only part of the service standard components, namely the START event. Since Srvany does not implement the STOP event, another service should be created to cause the Tuxedo application to shutdown. So in effect, you will start the STOP service to cause the Tuxedo domain to shutdown. Srvany is installed into the SCM and associated with a display name. After installation, the service’s startup settings must be configured in the Control Panel Services Applet where it is found under its display name. The login account and startup mode must be specified. Lastly, the command line arguments are placed into the NT Registry database. Detailed steps for installing the NT Services TuxedoStart, which boots the Tuxedo Domain, and TuxedoStop, which shuts down the Tuxedo Domain.
    See Administrator Usage for local and remote service administration. Custom ServiceThe second method to implement a service is much more involved. The programmer must implement the various elements of the service that were conveniently provided by Srvany such as installation, configuration and runtime behavior. But with the added difficulty, there is also more potential functionality that can be incorporated into the service when it is written using the C APIs for the Service Control Manager. The following discussion will focus on the basic makeup of service implementation. The code snippets are provided to aid understanding but are not intended to represent an entire service program. The major functions of an NT service are: main(), ServiceMain(), ServiceControlHandler(). The lifetime of service generally proceeds in the following manner. The Service Control Manger(SCM) launches the process that executes main(). The major responsibility of main() is to start the service control dispatcher passing the SERVICE_TABLE_ENTRY structure containing the service name and the function pointer to the service’s main processing function, usually called ServiceMain(). void main()
{
SERVICE_TABLE_ENTRY SvcTableEntry[] =
{
{_T("TuxedoDomain"), ServiceMain}
{NULL, NULL}
};
if( ! StartServiceCtrlDispatchrer(SvcTableEntry))
//log error
}
The service control dispatcher creates a thread for the service and calls the ServiceMain(). The ServiceMain() is required to register a service control handler callback function to process start/stop/pause/continue notifications from the SCM. Next, Tuxedo should be booted. The preferred method for accomplishing the Tuxedo Boot is to retrieve the command line from registry settings similar to those used by Srvany. Once the command line is retrieved, create a new process to execute the command. Then, the ServiceMain performs its work, which is nothing except wait for the STOP Event. The service loops until the STOP Event is signaled from the SCM via the handler. void ServiceMain(DWORD argc, LPTSTR argv[])
{
HANDLE hEvents[1];
hServiceStatus = RegisterServiceControlHandler(ServiceName, ServiceControlHandler)
//Retrieve the start command for booting Tuxedo
//from registry settings and start Tuxedo
//by creating a new process using CreateProcess() to run the command .
StartTuxedo();
SERVICE_STATUS ss;
//Fill out service status structure
//for SERVICE_START_PENDING,
SetServiceStatus(hServiceStatus, &ss)
//Create Event for STOP
g_hStopEvent = CreateEvent(NULL,FALSE,FALSE, _T("StopTuxedo"));
g_hEvents[0] = hStopEvent;
SERVICE_STATUS ss;
//Fill out service status structure for SERVICE_RUNNING,
SetServiceStatus(hServiceStatus, &ss)
//Do service work in a loop
// The service’s job is to sit in a loop until it’s time
// to shutdown Tuxedo on the STOP event
While(true)
{
WaitForMultipleObjects(1, hEvents, FALSE, INFINITE );
//Stop Tuxedo using the same method described
//for StartTuxedo() above
StopTuxedo();
//Close Event Handle
CloseHandle(g_hStopEvent);
}
}
When the handler thread is signaled by the SCM for a control request, the handler must use a inter-thread communication mechanism to pass the request to the ServiceMain(). Events are a good option for this type of application, but other methods may be used. ServiceMain creates the event for STOP and the handler sets the event when the SCM makes the request to stop the service. For this application, STOP is the only event that makes much sense. There is really no reason to implement a PAUSE or CONTINUE event because the Tuxedo domain will never be paused.
void WINAPI ServiceControlHandler(DWORD dwCtrl)
{
// Handle the requested control code.
switch(dwCtrl)
{
case SERVICE_CONTROL_STOP:
SetServiceStatus() //SERVICE_STOP_PENDING
SetEvent(g_hServerStopEvent);
return;
//SCM requests an update on the service status
case SERVICE_CONTROL_INTERROGATE:
break;
default:
break;
}
SetServiceStatus() //NO_ERROR
}
When the service is stopped, the service thread terminates. After all threads have terminated, the dispatcher returns control to the main() to exit the program. This simple service, though not quite as quick to implement as using Srvany, provides an administrator with a single service to both start and stop a Tuxedo domain from remote machine. The next section lists the various tools to administer NT services. Administrator UsageLocal Machine Administration
Local and Remote Machine Administration
ConclusionBoth services created using Srvany and a custom written service can provide an administrator with ability to administer the startup and shutdown of a Tuxedo domain from a remote machine. Also, the service can be configured to startup automatically without requiring a user to login to the machine. Srvany only provides startup functionality whereas a custom service can provide both startup and shutdown capabilities. ReferencesSrvany.wri, Windows NT Resource Kit, 1995-1997, Microsoft Corp. NT Services, Kevin Miller, 1998, WROX Press Windows NT Programming in Practice, "How to write an NT Service", Paula Tomlinson, 1997, Miller Freeman, Inc.
|
voice (407) 708-1040 . fax (407) 708-1039 |