wntSvcCfgSet

Changes a configuration parameter for a service.

Syntax:

wntSvcCfgSet( server, service-name, flags, request, value)

Parameters:

(s) server-name: the UNC name of the server on which the function will execute (e.g., "\\MYSERVER"), or ("") for the local computer.

(s) service-name: the name of the service to be looked for.

(i) flags: specifies the type of name that "service-name" represents:
0  display name (the name shown in Control Panel)
1000 service name (the actual registry key name)

(i) request: specifies the parameter to be changed (see below).

(s/i) value: specifies the new value for the parameter.

Returns:

(i) always 1.

"request" specifies the parameter to be modified, and can be one of the following:

Please note: that the following service configuration parameters are not present on WinNT and an error will occur in any script that attempts to get/set these values on an inappropriate version of Windows. These new service configuration values are all related to Win2K [and newer] service recovery settings.

Further information on these values follows:

ServiceType:

Service type are the flags to indicate the type of service. In addition, for a SERVICE_WIN32 service, the SERVICE_INTERACTIVE_PROCESS flag might be set, indicating that the service process can interact with the desktop:

In addition to the SERVICE_WIN32 service, the SERVICE_INTERACTIVE_PROCESS flag may be set, indicating that the service process can interact with the desktop:

StartType:

Specifies when to start the service. One of the following values is specified:

ErrorControl:

Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

BinaryPathName:

The fully qualified path to the service binary file.

LoadOrderGroup:

The load ordering group of which this service is a member. If a blank string, the service does not belong to a group. The registry has a list of load ordering groups located at:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group. The order in which a service starts is determined by the following criteria:

1. The order of groups in the registry's load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list and then services that do not belong to a group.

2. The service's dependencies listed in the "Dependencies" parameter and the dependencies of other services dependent on the service.

TagId:

Specifies a unique tag value for this service in the group specified by the "LoadOrderGroup" parameter. A value of zero indicates that the service has not been assigned a tag. You can use a tag for ordering service startup within a load order group by specifying a tag order vector in the registry located at:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

Dependencies:

A tab-delimited list of names of services or load ordering groups that must start before this service. If a blank string, the service has no dependencies. If a group name is specified, it must be prefixed by a '+' character to differentiate it from a service name, because services and service groups share the same name space. Dependency on a service means that this service can only run if the service it depends on is running. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

ServiceStartName:

If the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, this name is the account name in the form of "DomainName\Username", which the service process will be logged on as when it runs. If the account belongs to the built-in domain, ".\Username" can be specified. To log on as the LocalSystem account, specify "LocalSystem".

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns) which the input and output (I/O) system uses to load the device driver.

You can specify both a ServiceStartName and a Password together, in the form "ServiceStartName|Password". If ServiceStartName does not contain a '\', then '.\' will automatically be prepended, unless ServiceStartName == "LocalSystem".

Password:

Password to the account name specified by the "ServiceStartName" parameter if the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS. If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this parameter is ignored.

DisplayName:

String that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the service control manager. Display name comparisons are always case-insensitive.

Service description: [valid on Win2K and newer]

Reset period: [valid on Win2K and newer]

Reset period is measured in seconds. This is the time period that must pass w/o a service failure before the failure count will be reset to zero.

Reboot message: [valid on Win2K and newer].

If a recovery action is defined to reboot the system then this message will be broadcast to all users who have connections to the system. After the delay period has passed the system will be restarted.

Command line: [valid on Win2K and newer].

If a recovery action is defined to run a command then this command line will be executed. The program specified in this string value should be enclosed in double quotes to make sure that it is properly parsed. Additional command line parameter values & switches may also be specified after the program specification. If "/fail=%1%" is specified [w/o the double quotes] as the final parameter on the command line then the value of "%1%" will be replaced with a number that represents how many times the service has failed.

TAB delimited list of service recovery actions: [valid on Win2K and newer].

The tab delimited list will contain 3 pairs of values, with the values in a pair delimited by the pipe "|" character and the pairs will be delimited by the TAB character.

Action values determine the types of recovery actions to be taken when a service fails. The delay values indicate how many milliseconds of time must pass between when the service fails and when the recovery action is taken. The first pair of values in the list represents the recovery action to be taken the first time that the service fails. The second pair of values in the list represents the recovery action to be taken the second time that the service fails. The third pair of values in the list represents the recovery action to be taken the third time [and all successive times] that the service fails before running w/o failure for the amount of time specified in the reset period setting.

The following action values are valid:

0 - no action

1 - restart the service

2 - reboot the system

3 - execute a command

Please note that the delay value is ignored for the "execute a command" recovery action.

Example:

; Load Appropriate Extender
AddExtender('wwwnt34i.dll',0,'wwwnt64i.dll')


wntSvcCfgSet("", "Spooler", 0, 1, 2)
Message("Done","Changed configuration parameter for Spooler 'Start-Type'[SERVICE_AUTO_START]")
Exit

See Also:

wntSvcCfgGet