Capesoft Self Service Complete Documentation
	Version www.capesoft.com Updated 26 October 2009

Contents

Introduction
Installation
Ground Rules (recommended reading) [updated for Windows Vista]
JumpStart- start here - (recommended reading)
Examples
Global Extension Options (recommended reading)
Control Templates - the easiest way to add Service buttons to your app (recommended reading)
Object Properties
Object Methods
FAQ
Support
Purchasing SelfService
Distribution
License & Copyright & Credits
Version History

Introduction

Installation

To download the latest installation please visit www.capesoft.com/selfserviced.htm

Please note: SelfService is only available for Clarion 6
(It is not available for Clarion 5 and Clarion 5.5 as the threading model in these Clarion versions does not support multi-threaded services).

Ground Rules (recommended reading)

This section explains some of the concepts that you'll need to consider in order to effectively use Services. Note that Windows Vista changes a number of things about the manner in which services work, and what is allowed, along with how logins work. This is covered in the notes below.

1) With SelfService added, your program can run either as a Service, or as a normal EXE. When running as an EXE it behaves like any windows program. However when running as a Service it may behave slightly differently. The items below only refer to the time while it is running as a Service.

2) Your service runs in a user account of your choice. In the SelfService global extension you can specify which user your service must run in. It's important to choose the correct user as it will affect the behaviour and functionality of your service. SelfService offers you two options:
 

	a)	Local System - This is the default user and allows your service to be Interactive (i.e. in Windows versions prior to Vista the GUI will appear to the first user who logs in), but it will not allow network access to other machines shared folders (unless they are accessible to Guest via a null session). This user also cannot open HKEY_CURRENT_USER in the Windows registry. NOTE: In Vista, the GUI will not be visible while the program is running as a Service.
	b)	Custom - This allows you to specify a user and password. Your service will then run with the privileges of that user. If you give that user account access to shared network folders, then your service can access these folders. However the GUI of your program will not be visible to any user, while running as a service (regardless of the Windows version.) Note: the user account you choose must have a password (it won't work without one). Note: The user account may need to be preceded by a .\ for example: .\administrator Note: You'll need to give your account "log in as service rights". (See also Microsoft Information). Which can be done two ways: a) If you type the account details in to the Windows XP/2003/Vista Service Manager, the Service manager automatically adds "Log in as a Service" rights. b) You can the Group Policy Editor (gpedit.msc). Local Computer Policy | Computer Configuration | Windows Settings | Security Settings | Local Policies | User Rights Assignments | Log on as a service.

There are also two other built in account types that you can use (you can enter them in the custom fields), but these do not work with NetTalk, and are therefore not recommended:

	i)	Network Service (enter NT Authority\NetworkService as the username, no password) - Shared Network folder access, no interactive and not compatible with NetTalk.
	ii)	Local Service (enter NT Authority\LocalService as the username, no password) - Limited access user (no networking), no interactive and not compatible with NetTalk

It's important to choose the correct account type, depending on whether you want an interactive service, or a service that has access to network files. Another thing to bear in mind is that if you are using Proxy client software (e.g. Microsoft Proxy) to access the Internet, this may not be available to the Local System account.

3) Windows XP/Vista Fast User switching allows users to switch from one user's desktop to another without requiring that the user logs out. Under Windows Vista this doesn't affect you. Under Windows XP the service GUI ( while running as a service) will only appear on the first user's Login. Thus an external method for managing the service is recommended (this is discussed in more detail in the JumpStart section of this document.)

4) Windows Vista and later versions of Windows, do not allow for the program's user interface to be visible, while the program is running as a service. Thus an external method for managing the service is recommended (this is discussed in more detail in the JumpStart section of this document.)

5) Your Service needs to be able to shutdown smoothly without displaying the "Application still active. Quit the application before quitting Windows" message. So you're going to need WinEvent to make sure your program automatically shuts down.

6) A Service can only have one instance started by the Service Manager. Although you can run multiple instances of the same executable by double clicking it, the Service Manager will only open one instance. i.e. If the Service Manager has already started your Service, it won't and can't start another instance.

7) Windows Vista, Services and Logins
Even when logged in as Administrator, Windows Vista use UAC (User Account Control). This means that the administrator is a normal user most of the time, except when prompted by Windows for elevated privileges, which allows them to perform an admin option. This is because the authentication token is actually split in two, so when logged in as an administrator you use a user level token until a task requires administrative access, in which case Vista will prompt the user and allow them to choose whether or not the elevate privileges for a specific task.

Unfortunately the implementation of UAC is not consistent. There are tasks that required administrative access (such as installing, starting and stopping a service), where UAC is not implemented. This means that in order to perform the task you need administrative privileges, but in order to get those privileges you need UAC to elevate you, which isn't implemented. Hence there are things in Vista which you simply cannot do with UAC turned on, unless the user does them manually, and MS has no mechanism for your program to inform the OS that it is going to do something that required privilege elevation.

There are three options to solve this problem:

1. Right click on the exe or shortcut and start it as administrator.
2. Go into the User control panel and untick the UAC box.
3. Create a separate EXE that Starts, Install, Stops and Uninstalls the service. When these functions are needed call this EXE using ShellExecute and start it as an administrator. We will be working on implementing this is future version of Self Service, so it is possible to do without having to write large amounts of additional code. This approach has the advantage that it works regardless of the UAC setting and does not require the user to right click and start the management program as an administrator. It also fits in with the manner in which Microsoft specify that services should work, and adheres to the Vista Certification requirements.

8) Adding to a Multi-DLL solution.
If you are adding SelfService to a Multi-DLL then you add it to the EXE app, not the Data DLL. There are no differences between adding SelfService to a multi-app solution.

(recommended reading)

Services are really easy to create, and administer. Using this Jump-Start we'll walk through all the steps you need to consider to turn your application into a Service.

If your program will run on Windows Vista, then it will not be visible while it is running as a Service. This adds a layer of complexity, which will be addressed in the second part of this Jump-Start.

Important: If you haven't already done so, read the Ground Rules section of this document now.

Part 1

1. Add the SelfService Global extension to your application

a) Open the application
b) Click on the Global button (or select Global Properties from the Application menu)
c) Click on the Extensions button
d) Click on the Insert button
e) Select Activate_SelfService from the list of available extensions.
f) Select the Settings tab
g) Enter your Service Name (this shouldn't contain any spaces). Your name should be unique to this application.
h) Then enter the Display Name and the Service Description.

The rest of the settings can be left at their default value for now.

That's all you have to do to make your application into a service. At this point you can install your program as a service just by running it with the command line switch (/ISS by default). After that you can manage it using the Windows Services Manager ( Services.Msc). You can run your program as a normal Exe (setting any settings you like) or as a Service. When running as a service you may not be able to interact with it. It still has Windows and timers, and so on, you just (possibly) won't be able to see them.

There are a few possibilities for interacting with the service itself. They are;
a) Include a Web Server inside the service. This allows you to interact with the Service using a browser. This is the easiest approach, that works on all versions of Windows, but does require that you have NetTalk.
b) Create a separate program that can Install, Start, Stop and Remove the Service. This program may also allow your user to change service related settings, and so on.
c) Include Service Management features in your application itself. While these won't be visible on all versions of Windows, they will be visible on older versions of Windows.

You can of course implement all 3 of the above, or any combination of approaches. Each of these methods will now be discussed in more detail.

2. Including Management controls inside the Service itself.

Remember this approach can not be used if the Service is running under Vista. However if you have some clients who are running the service on Windows 2003, or Windows XP, or even Windows 2000, then this approach is easy to add in, and can make management simpler for these users. However implementing one of the additional methods mentioned above in addition to this method is recommended.

a) Add the Self-Service Controls to a window in the application. This could be a new window in the app, or any existing window. To do this;
b) Go to the Window Formatter for the window.
c) Select Control Template from the Populate menu
d) Select SelfServiceControls from the list of available control templates.
e) Feel free to remove, or change, any text for the controls if you wish.

3. Creating a Separate Client Management application

The idea behind a separate manager is very simple. You add the SelfService global extension, and the Management controls to a different application, as per steps 1, and 2 above. The only difference between the Manager app, and the actual Service app, is that the Manager is set with the specific EXE name of the Service app.

Up to now the EXE name has been set (by default) to be the name of the application that is running. However, if you set the EXE name to be that of a different application, then all the commands to Start, Stop, Install and Remove services apply to the Service EXE, not the Manager EXE.

a) Create, or open, the new application that will act as the service manager.
b) Add the Global Extension as per step 1 above.
c) Add the Management controls as per step 2 above.
d) While still in the Window Formatter, Right-Click on one of the management controls, and select Actions...
e) In the Service EXE Name setting enter the name of the Service Exe. Include the .Exe in the name, and wrap the name in Quotes. For example
'JumpStartSelfService.Exe'
f) If the Service EXE is in a different folder to the Management Exe, then enter the Service EXE's folder here. However usually the Service EXE and Management EXE will be in the same folder, so usually this field will be blank.

Note that creating this separate Manager application does not in any way change the main service application. You can still include Management controls in the service program (as per step 2 above) or a web server (as per step 4 below) if you like.

4. Including a Web Server inside the program

 

Part 2

In Part 1, we added the Service mechanism to an application, now we are going to add some WinEvent functionality, that will allow our application to shut down without the Application still active. Quit the application before quitting Windows message. Please make sure you've read the Ground Rules section of the documentation. This part of the Jump Start should take you less than 5 minutes, to complete.

1) Add the WinEvent Global extension to your application.

a) Open the application
b) Click on the Global button (or select Global Properties from the Application menu)
c) Click on the Extensions button
d) Click on the Insert button
e) Select Activate_WinEvent from the list of available extensions.
f) Select the Settings tab
f) Tick ON the option Auto-Shutdown on

2) Optionally add taskbar support to the service.

Taskbar support is another WinEvent feature that is particularly useful for services. It allows an application to place an icon in the Tasktray, and respond to Mouse events on this icon. You can add it to the Service Exe itself (although the icon won't be visible on Windows Vista, or Terminal Services). You can also add it to the Management application (if you have one.)

To add this support, add the WinEvent TaskbarIcon - WinEvent: Add Icon to system tray extension to the window.

a) In the "Name of Icon to add" field enter the following (including the quotes): 'icon.ico'
b) In the "Icon Tip" field enter the following: 'CapeSoft SelfSevice JumpStart'
c) Click on the ... button to the right of the IconHandle(long) field.
d) Add a new long to the LOCAL DATA Main called something like TaskBarIcon
e) Choose the following options:
   -  Add Show|Hide|Close Menu to Right-Click Popup
   -  Not on Toolbar when Minimized
   -  Disable Titlebar Close
   -  Left-Click Icon Shows Window

Examples

There are SelfService examples in your \Clarion\3rdParty\Examples\SelfService\ directory.

• JumpStart 1 - This example has implemented Step 1, and Step 2 of the JumpStart documentation above
  
• JumpStart2 - This example includes an external Manager program, as per Step 3 of the JumpStart documentation above.
  
• WebServer - An Example is included with NetTalk 4.31 (and higher) which demonstrates adding a Web Server to a program using Self-Service.
  the example can be found in the \clarion6\3rdparty\examples\NetTalk\Web Server\ServicesRequiresSelfService (55) folder.
  
• Connection Checker - Service example that checks a TCP/IP connection and demonstrates a Web Server interface (using NetTalk). This example runs on port 88. On a regular basis the program opens a TCP/IP port to see if the server on the other end is still there. If not it can either run a program, or send an email. Because the (usual) interface is not visible on Vista, it uses a web server to allow you to set all the settings via a browser.
  
  
• NetTalk DIP Server - This is the NetTalk DIP Server, which has been configured to run as a service.
  
• Machine Status - This example uses NetTalk to send an email to you reporting when a machine boots or is shutdown.
  
• Legacy - Simple example using the Legacy - Clarion Template Chain.

SelfService Global Extension

Global Extension
		Disable All SelfService Features: removes template generated SelfService code from your app.
		Service Name: This is the service name (no spaces allowed). You can use this name in a DOS prompt to call: Net Start <ServiceName> Net Stop <ServiceName> Use quotes, or use a variable (which you can set in the  'SelfService - Initialize variables' global embed point). Service Display Name: This is the name displayed in the Windows Service Manager. Use quotes, or use a variable (which you can set in the  'SelfService - Initialize variables' global embed point). Service Description: This is the description of your service and is displayed in the Windows Service Manager in Windows 2000,  Windows XP, Windows Server 2003 and Windows Vista. Use quotes, or use a variable (which you can set in the  'SelfService - Initialize variables' global embed point). Allow command line usage: Allows you to run your app with /iss (Install and Start Service),  /is (Install Service) or /rs (Remove Service). Additionally you can add /silent if you do not wish to see the status messages. See the Command Line Switch Options if you want to customize the command line switches. Always make Path the same as the EXE folder: This option will set the path of a service to the same as the exe folder location. This is useful as when a service is started by the Service manager, the path is Windows\System32, which is probably not where your data is stored. So it's best to have this option turned on. Only allow One Instance to run at a time: Will allow only one copy of the application to be run at a time (either as a normal exe or a service) Service Installation Options: This is where you can choose which user the service should be run as. This is described in the Ground Rules section. (Please note the user account you choose must have a password (it won't work without one)). Interact With Desktop (does nothing in Vista): Allows the Service to display your Graphical User Interface (GUI) to the user, otherwise they are hidden. Single Dependency: This allows you to add one dependency for your service. This must be the ServiceName of the dependent service. (Should you wish to add multiple dependencies then please see DependenciesQueue)
		Turn on logging: Outputs log information to the system debugger. You can either use the default clarion debugger, or preferably use the free DebugView from www.sysinternals.com Work with WinEvent: This should be ticked on if you are using WinEvent. Use Dictionary.Construct/Destruct Fix: This option makes SelfService work with the Dictionary Class in Clarion 6.1 and above. Clarion 6.0 users may want to turn this option off. Don't check if running as an EXE SelfService does not always reliably detect if your app is running as a service or an exe. Check this checkbox to disable the check (i.e. it assumes that your app is always a service). Show Advanced Class Options:This option will display the Advanced Class Tabs. The default settings in the Advanced tabs work perfectly. But we included them in case you want to override any of the class behaviour.

 

Control Templates

SelfService ships with two Control Templates that make it easy to add buttons to your window that allow you to install (and start) your application as a Service.

Here's what these control templates will add to your window:
 

SelfServiceControls - SelfService - Service Button Controls

 

SelfServiceINstallAndStartButtonControl - SelfService - Install And Start Button Control

How to add these control templates:

Step One: Add the WinEvent and SelfService Global Extension to your window. Configure the name and description of your service. See the Jump Start for a step-by-step guide.

Step Two: Open the window in the Clarion IDE and choose the Populate menu | Control Template | Scroll down the Class SelfService (if it's not there then you didn't add the Global Extension - or you are already using all the SelfService Control Templates) - then choose either:
SelfServiceControls - SelfService - Service Button Controls
or
SelfServiceINstallAndStartButtonControl - SelfService - Install And Start Button Control
 

Tip 1: You can hide any buttons or controls that you don't want displayed in your application. You can also resize and move the controls about.

Tip 2: If you want to call any of these options from a menu item you can call them by adding the following embed code (for example calling the InstallButton):
post (event:accepted, ?InstallButton)
 

SelfService Object Properties

All the common and most useful SelfService settings are configurable via the SelfService Template options. But we've also listed the object properties here. It's more than likely that only advanced programmers will want to access these properties.

AllowCommandLine byte	Set in global template - Allows the /is and /rs to install / remove the services.
AllowOnlyOneInstance byte	Set in template.
AmService byte	Automatically set. Set to 1 if application is being run (started) as a service, otherwise 0.
Automatic byte	Defaults to 1 in Construct, this indicates the type of service (automatic or manual).
DependenciesQueue SSDependenciesQueueType	Set by template for one single dependency. This must be the ServiceName(s) of the Service(s) that your service is dependent on. This could be your SQL Server service for example. To add multiple dependencies you could use the following code: free (gSelfService.DependenciesQueue) gSelfService.DependenciesQueue.DependencyName = 'Themes' ! XP Themes add (gSelfService.DependenciesQueue) gSelfService.DependenciesQueue.DependencyName = 'W32Time' ! Windows Time Maintainer add (gSelfService.DependenciesQueue)   The best place to add additional dependancies is in the Global Objects|Capesoft Objects|gSelfService| Other Before Start Method Call.
Description cstring(256)	Set by template. Used in Install/Remove - the description that is displayed in the Windows Service Controller
DisplayName cstring(256)	Set by template. Used in Install/Remove - the name that is displayed in the Windows Service Controller
ErrorString string(1024)	Stores the last error - only reported by .InstallService() and .RemoveService()
Executable cstring(256)	Automatically generated. This is the full path to the executable. Used in Install/Remove
FirstInstance byte	Automatically set. Set to 1 if this is the first instance running on this machine. Will only work if self.NoMutex = 0
InstallAsUserName cstring(80)	Set in template, but you can change before you call InstallService. If blank it will use the Local Service account, otherwise specify a user e.g. '.\Jono'. See Ground Rules.
InstallAsPassword cstring(80)	See InstallAsUserName
InstallAndStartSwitch string(80)	Set in Template. Defaults to '/iss' - switch for Install And Start Service.
InstallSwitch string(80)	Set in Template. Defaults to '/is' - switch for Install Service.
InteractWithDesktop byte	Set in global template, but you can change this in your code. See Ground Rules.
LoadGroupOrder CString (256)	LoadGroupOrder. Used for bulding Kernel Services to specify when the service should be loaded. Normally this will be left blank.
LoggingOn byte	Set in Template. 0 = no logging, 1 = logging to DebugView (www.sysinternals.com)
NoMutex byte	Ability to turn off mutex (1). defaults to 0 (allow mutex)
RemoveSwitch string(80)	Set in Template. Defaults to '/rs' - switch for Remove Service
ServiceName cstring(256)	Set by template. Used in Install/Remove, and call to StartServiceCtrlDispatcher
SetPathToExeFolder byte	Set in template.
ShowErrors byte	0 = no message statements, 1 = show error statements
SilentSwitch string(80)	Set in Template. Defaults to '/silent' - switch for Silent Mode - ie no messages
SleepMilliSeconds long	If > 0 it will cause the service to sleep this period of time on starting as a service, before launching the global application code - see in _ServiceMain(). You'll have to set this in your own construct method.

SelfService Object Methods

All the common and most useful SelfService settings are configurable via the SelfService Template options. But we've also listed some of the object methods here.

GetServiceStatus (string p_ServiceName, *SS_SERVICE_STATUS p_ServiceStatus, long p_Silent=1),long	This method will return the status of a particular service. Returns 0 on success. p_ServiceName - the name of the service to Get the status of p_ServiceStatus - the handle to a SS_SERVICE_STATUS group (see the SelfService.inc file for the Clarion equivalent group declaration) that will contain the ServiceType, CurrentState, etc. For more info on these values, check http://msdn2.microsoft.com/en-us/library/ms685996.aspx. If you're wanting to query the status of a service, then check the SS_SERVICE_STATUS.CurrentState element of your ServiceStatus group. p_Silent - if set does not display a message when an error occurs.
InstallAndStartService (byte p_Silent=1),long,proc	This method will install your application as a service with the windows service manager and then it starts the application as a service. Returns 0 on success. This method can also be used to updated your Service settings with the Windows Service Manager.
InstallService (byte p_Silent=1),long,proc	This method will install your application as a service with the windows service manager. Returns 0 on success. This method can also be used to updated your Service settings with the Windows Service Manager.
LoadWindowsServiceManager ( ),long,proc	This method loads the Windows Service Manager. Works in NT, 2000, XP, 2003 and Vista.
MapDrive (string p_DriveName, string p_RemoteName, string p_UserName, string p_Password),long,proc	This method will map a network shared folder to a drive letter. For example to map \\penguin\l-drive to Y: call: gSelfService.MapDrive ('Y:', '\\penguin\y-drive', '', '') which will map it using the current user. Returns 0 on success. If the return value is non zero you can use the ._WinError() method in order to get the API error message associate with the error code. Below are a list of possible return values if an error occurs.
RemoveService (byte p_Silent=1),long,proc	This method will remove your application as a service from the windows service manager. Returns 0 on success. After calling this function you will need to close your application before you can call InstallService().
ReStartService (byte p_Silent=1),long,proc	This method will restart or start your application as a service. Returns 0 on success.
StartService (string p_ServiceName, long p_Silent=1),long,proc	This method will start a service specified by the p_ServiceName parameter. Returns 0 on success. Using this method enables you to start other services.
StopService (string p_ServiceName, long p_Silent=1),long,proc	This method will stop a service specified by the p_ServiceName parameter. Returns 0 on success. Using this method enables you to stop other services.
Return code Description ERROR_ACCESS_DENIED (5) The caller does not have access to the network resource. ERROR_ALREADY_ASSIGNED (85) The local device specified by the p_DriveName member is already connected to a network resource. ERROR_BAD_DEV_TYPE (66) The type of local device and the type of network resource do not match. ERROR_BAD_DEVICE (1200) The value specified by p_DriveName is invalid. ERROR_BAD_NET_NAME (67) The value specified by the p_RemoteName member is not acceptable to any network resource provider, either because the resource name is invalid, or because the named resource cannot be located. ERROR_BAD_PROFILE (1206) The user profile is in an incorrect format. ERROR_BAD_PROVIDER (1204) The value specified by the internal lpProvider member does not match any provider. Please contact CapeSoft Support if you get this error. ERROR_BUSY (142) The router or provider is busy, possibly initializing. The caller should retry. This is a not an error code that should be returned by MapDrive. ERROR_CANCELLED (1223) The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers, or by a called resource. This is a not an error code that should be returned by MapDrive. ERROR_CANNOT_OPEN_PROFILE (1205) The system is unable to open the user profile to process persistent connections. ERROR_DEVICE_ALREADY_REMEMBERED (1202) An entry for the device specified by p_DriveName is already in the user profile. ERROR_EXTENDED_ERROR (1208) A network-specific error occurred. (The WNetGetLastError API function can obtain a description of the error). ERROR_INVALID_PASSWORD (1216) The specified password is invalid and the CONNECT_INTERACTIVE flag is not set. ERROR_NO_NET_OR_BAD_PATH (1203) The operation cannot be performed because a network component is not started or because a specified name cannot be used. ERROR_NO_NETWORK (1222) The network is unavailable.

Advanced Methods:
It's more than likely that only advanced programmers will want to access these methods.

CheckCommandLine ( ),long,proc	Advanced programmers may want to override this method, which looks for the /is etc. Command line switches.
HandleStopShutdown (long p_ControlType),long	Advanced programmers may want to override this method, which is called when either a Service STOP or SHUTDOWN message are sent to the service. If you return 0 then the normal Shutdown code will report back to the SCM that a STOP_PENDING command, and then call .CloseDown. If you return 1 then you must talk to the SCM in your new code.
ManageInstances ( ),long	Advanced programmers may want to override this method, which manages the instances of this application using a mutex.
SessionChanged (ulong p_EventType, long p_TSID, long p_Context)	Advanced programmers may want to override this virtual notification method, which is called when SessionChange information is available.
WarnAboutOtherInstance ()	Advanced programmers may want to override this method which is called when multiple instances occur and the settings have been configured to warn the user.
CloseDown ( )	Advanced programmers may want to override this method which at the moment posts an event:closedown to the main thread. This method is called if the Service Manager issues either a STOP (Service must stop) or SHUTDOWN (machine is shutting down) command.

FAQ

I'm getting Compile Errors

SelfService - Introductory Questions

• A1) What operating systems can I run Services on?
• A2) What's the difference between SelfService and running my application from the Scheduled Tasks?
• A3) What's the difference between SelfService and Vince Sorensen's ABCFree NT_SVR template?

Operating Services

• B1) How can I install and/or remove my application as a Service?
• B2) How can I Start and Stop my Services?
• B3) If I call gSelfService.RemoveService() and then try and Install it again, I get error 1072.
• B4) In the Windows Service Manager, I get a "The specified service has been marked for deletion".
• B5) Can control(of query the status of) the service from another program - or other services from my program?
• B6) How do I know if my application is running as a service or a normal EXE?

Runtime Problems

• C1) I sometimes get a 15 second delay when starting my application, even though I am just running the exe.
• C2) I can't get the Task Tray Icon to work and/or my windows to display, when the application is loaded as a Service on boot up.
• C3) After windows installs updates and re-boots, my application is running, but no longer displays an icon in the tray.
• C4) My application runs as an application, but not as a service.
• C5) I cannot connect to my SQL backend when my app is compiled as a service.
• C6) I have a dependency service that is not starting up in time before my service starts.
• C7) I'm using SQL Server - and when my application runs as a service it locks up, but it runs fine as a normal EXE.
• C8) I can't install my service - it says access denied (errorcode 5).
• C9) Error 1053 - The service did not respond to the start or control request in a timely fashion.
• C10) I start my exe as a service, but the windows service manager is not saying it has started successfully, although the it is running.

Miscellaneous

• D1) How do I manage the one instance of the Service that is already running.
• D2) Is it possible to add a command line option when the application has been started as a service, so that I can change some of the wording on the window?
• D4) How can I install my application as a Service upon installation?
• D5) I'm having problems with my application running in windows Vista.
• I have a Multi-DLL application. Which app(s) must I add SelfService to?
• D6) Setting the datapath in Multi-DLL Service applications.

---

A1) What operating systems can I run Services on?

Answer: Windows Vista, Windows Server 2003, Windows XP, Windows 2000 and Windows NT 4. Your executables, will still however run on Windows 9x, but just not as a service.

---

A2) What's the difference between SelfService and running my application from the Scheduled Tasks?

Answer: There aren't any hard fast rules, but here are some points that you may want to weigh up when comparing Scheduled applications vs Services:

Scheduler:
1) You either need to add your application to the Scheduled Tasks list manually or find the API calls to do it yourself.
2) If you want to run your app under XP/Vista, the user that you use in the Scheduler should have a password. This now means that user has to type in a password if they manually log in.
3) If you choose to start on "Log In", you're no better off than just placing the application into the StartUp folder (which for some applications works pretty well too).
4) If you choose to start your application "at System Startup", then you can't see any windows, which is fine for some apps, but not for all.
5) You must make sure that the Task Scheduler has not been turned off, otherwise your app won't load.
6) Explaining to clients that your app runs in the Task Scheduler doesn't quite have the same prestige as saying it can run as a Service.

Services:
1) SelfService provides you with either a command line option to install your application as a Service, or a your application can programmatically install itself as a service via a method call.
2) You don't need a password to install an app as a service as it can use the Local System account.
3) SelfService does all the hard work for you and comes with full documentation, examples, support and so on.

---

A3) What's the difference between SelfService and Vince Sorensen's ABCFree NT_SVR template?

Answer: We've been working with Vince (ABCFree Author) on this project. So there are a number of similarities.

ABCFree is a fantastic product, and there are a number of Clarion programmers (ourselves included), who have benefited greatly from Vince's product.

---------
Changes 11/9/2003
...
- Added AttachThreadToClarion calls to "NT Service"
  template. This provides support for C5.5 and
  Clarion 5 application migration, but it is
  recommended that the new CapeSoft commercial
  template be used instead. (www.capesoft.com)
--------

One of the main reasons for creating the SelfService product was so that there was a commercially supported service product. While Vince's work is free, the templates are also unsupported.

The SelfService product, comes bundled with full documentation, examples and a jump start example. And there is information about service enabling your application, as well as FAQs etc.

There are a couple of things that we have done differently. Some of the changes include:

• We've moved 99% of the code into an object, which makes it easier to use, if you want to hand code
• We've added logging
• Your application runs as both an executable(i.e. user double clicks) and a Service.
• And we've added info about task tray icons, and auto shutdown issues, which are all relevant issues when you consider creating a Service.

---

B1) How can I install and/or remove my application as a Service?

Answer: You can either call the gSelfService.InstallService() or gSelfService.RemoveService() methods, or you can run the application with the /is (install server) or /rs (remove service). Additionally run the application with /silent if you do not want to see the error messages displayed. (Make sure you've ticked on the command line (/is and /rs) option in the Global SelfService Template).

Should you wish to you can change these command line parameters anything you prefer (for example /install). This can be done in the Global Extension.

---

B2) How can I Start and Stop my Services?

Answer: You can use the features you've added to your own program (see the JumpStart section of this document) or ...

Answer: You can start and stop your applications from the Windows Service Manager.

To load the Windows Service Manager in 2000/XP/2003/VISTA
Go to Computer Management and expand the "Services and Applications" icon or
Type services.msc in the Start | Run dialogue box.

To load the Windows Service Manager in Windows NT
Go to the Control panel and click on Services.



Alternatively, you can also call Net Start <ServiceName> or Net Stop <Service Name> from a command prompt. For example;
Net Start CapeSoftJumpStart

If your Service is installed with the Service Manager and is set to start automatically you can also reboot your computer and your service will start.

---

B3) If I call gSelfService.RemoveService() and then try and Install it again, I get error 1072.

Answer: You need to close your application after calling gSelfService.RemoveService(), before you can Install it again. This is a Windows Service limitation. See also FAQ B4.

---

B4) In the Windows Service Manager, I get a "The specified service has been marked for deletion".

Answer: You need to close your application after calling gSelfService.RemoveService(), before you can Install it again. This is a Windows Service limitation. See also FAQ B3.

---

B5) Is there a method where I can control (or query the status of) the service from another program?

Answer: Yes there is:

The following methods should help you in performing the various operations:

StartService, RestartService, StopService, GetServiceStatus

---

B6) How do I know if my application is running as a service or a normal EXE?

Answer: You can query the AmService property to determine whether your application is running as a service or not:

if gSelfService.AmService
  !App is running as a service.
else
  !App is running as an EXE.
end

---

C1) I sometimes get a 15 second delay when starting my application, even though I am just running the exe.

Answer: One of the Windows functions sometimes waits for 15 seconds before giving back control to your application. In version 1.10 some code was added to detect if the service was started in the same folder as the exe, if it was it was assumed to be a normal executable (not a service) and the service code was not executed. If you have to start your application in a folder other than the one that the exe is in, then run your application with a command line switch, /exe to tell SelfService not to call the Service code, when it is started by the user.

---

C2) I can't get the Task Tray Icon to work, when the application is loaded as a Service on boot up.

Note: Services are not permitted to interact with the desktop in Windows Vista, so you will need to create an application that interacts with your service that can display windows, and the icon in the task tray. You can add this app to the start up items so that the interactive app starts when a user logs in.

Answer:
a) Please make sure you are using WinEvent v3.35 or later.
b) If you turn off the "Interact with Desktop" option in the SelfService Template, the service won't have a taskbar icon.
c) If you turn off the "Allow service to interact with desktop" option in the Windows Service Manager, the service won't have a taskbar icon.
d) If you don't run the service as "Local System" in either the template or the Windows Service Manager, the service won't have a taskbar icon.
e) You can't access the Taskbar icon if you are using Remote Desktop. It's unfortunately one of the limitations of using Remote Desktop.
f) Your window (with the taskbar icon) needs a timer on it
g) You need to use a IconHandle (long) in the Settings tab of the of the WinEvent: Add Icon to System Tray window extension.
h) If you are not using an internal icon (~MyIcon.ico) then you need to make sure that your icon is shipped with the application.

---

C3) After windows installs updates and re-boots, my application is running, but no longer displays an icon in the tray.

Answer: If you are using WinEvent this is very easy to fix.

1) Make sure you are using the latest builds of SelfService & WinEvent

2) In the WinEvent TaskBarIcon window extension (that adds the TaskBar Icon to your window), make sure you've specified a Handle Variable (see the bits in bold in the template). You can just add a local data item for example:

MyHandle      LONG

WinEvent will also add a timer to your window if you didn't have one. With the Handle variable and the timer, WinEvent is then able to control and update the icon for you.

If all else fails - you can look at the code in the SelfService JumpStart example that ships in your Clarion\3rdParty\Examples\SelfService\JumpStart1 folder - as this works 100%.

---

C4) My application runs as an application, but not as a service.

Answer: If it's a Multi-DLL application, make sure that all application DLLs are being shipped in the application folder. This is most likely the case of the problem. You should not rely on DLL's being in the PATH, since the path belongs to a User, and there are no users at this point.

If you are using FastUser switching (a Windows setting) - then this can interfere with Service operation, particularly prior to logging in (as a user). Try turning Fast-user switching off as very often this will resolve this issue.

If you are running a multi-core processor, you may need to lock the process to one processor using imagecfg -a 0xn <Drive:>\Path\yourprogram.exe. Imagecfg.exe is a windows system utility. n is the value of the mask that you want to set the affiinity of your appoplication to.

If you are running your application in a mapped drive, then it will not run as a service. You must run your application from a physical drive in order to install it as a service.

In some older versions of Windows - your service was allowed to interact with the Desktop (hence the setting in the SelfService global extension template). However, this can cause operational issues when the service tries to interact with the desktop in some versions of windows - so it is much better not to allow your application to interact with the desktop, and create a separate application containing user interaction with the service.

---

C5) I cannot connect to my SQL backend when my app is compiled as a service.

Answer:

---

C7) I'm using SQL Server - and when my application runs as a service it locks up, but it runs fine as a normal EXE.

Answer:
Services can behave differently to EXEs, and often this shows up in internet connection, or database interaction. A good starting point is to play with some of the combinations of SQL driver settings: IsolationLevel, BusyHandling, MultipleActiveReulstSets, etc.

---

C8) I can't install my service - it says access denied (errorcode 5).

Answer: You need to be logged in as an administrator (or elevated with Administrator privileges in Windows Vista). IOW - the user that you're logged on to windows with, must belong to the administrators group.

---

C9) Error 1053 - The service did not respond to the start or control request in a timely fashion

There are a number of reasons which can cause this issue to occur (which we will add as cases arise).

1. You're using the wrong account to run the service. Either the account cannot run elevated - or you are interacting with a user's desktop that is not logged in (or someother reason). If the latter, then see the JumpStart section of the docs.
2. You could be running a service manager that is interfering with the operation of your service. Try disabling the "Service Health Manager" application.

---

C10) I start my exe as a service, but the windows service manager is not saying it has started successfully, although the it is running.

Answer: The most likely cause of this is that your application thinks it is running as an exe, and not as a service, and so it is not responding to the queries of the service manager. If your application is always a service, then you can force it to be a service (and not perform the running as exe check) - either in code as follows:

gSelfService._DontCheckForNonService = 1

or use the template prompt "Dont check if running as an EXE".

---

D1) How do I manage the one instance of the Service that is already running.

Answer: See the Ground Rules for more information and tips.

---

D2) Is it possible to add a command line option when the application has been started as a service, so that I can change some of the wording on the window?

Answer: If your program typically uses command line options then you have a few alternatives to consider when running it as a service.

a) Use the Clarion SETCOMMAND() function to "add" command line parameters to your app. Using this approach it is easy to change the behavior of your program to use an INI file (for example) as the source of the settings, rather than the command line.

b) If you wish to start the service, just this one time, with a specific command line, then you can set the parameters in the Service Manager. (See how to load the Windows Service Manager)

c) If you wish your service to register, so that it always starts with the same command line parameters, you need to change the .Executable property before the service is registered. By default this property defaults to
gSelfService.Executable = Command(0)
but you can change it to (for example)
gSelfService.Executable =Command(0) & ' ' & '/makeitfast'

Remember you need to set this property before the call to register the service.

---

D4) How can I install my application as a Service upon installation?

Answer: The easiest way to do this, is to get your installer to run your application with the command line parameter /is. Note: you must have allowed command line usage in the SelfService global extension template.

---

D5) I'm having problems with my application running in Windows Vista.

Answer: Services are not permitted to interact with the desktop in Windows Vista, so you will need to create an application that interacts with your service that can display windows, and the icon in the task tray. You can add this app to the start up items so that the interactive app starts when a user logs in.

---

D6) Setting the datapath in Multi-DLL Service applications.

Answer: Often you need to get the path that the exe is running in in the data dll - which loads before the exe (where the selfservice is activated). The best way to get the current path (and so load settings needed in the dll) is to do the following:

GLO:ProgramPath=COMMAND('0')
POS#=INSTRING('\',GLO:ProgramPath,-1,LEN(CLIP(GLO:ProgramPath)))
GLO:ProgramPath=SUB(GLO:ProgramPath,1,POS#)
SETPATH(GLO:ProgramPath)

---

Compile Errors associated with SelfService

Occasionally the template registry gets confused, and does not declare the SelfService classes, which will manifest itself with this error. You need to:

1. Open the Clarion IDE (close any apps that may be open if you the IDE is already open).
2. Go to Setup | Template Registry and select the SelfService template in the list.
3. Unregister it (using the Unregister button) and then re-register it again (using the Register button - go to the Clarion\3rdparty\Template directory and double-click the SelfService.tpl file).

If this does not resolve the problem, you will need to:

1. Close the Clarion IDE.
2. Delete the clarion\template\Registry.trf file.
3. Open the Clarion IDE, and register your templates:

• In the 'Setup' menu you will find a 'Template Registry' item - selecting this will open up the template registry.
• Click 'Register' (which will take you to the Clarion template directory by default) - you can register all the templates there in one pass, by doing a multi-select.
• Click 'Register' again and locate the Clarion\3rdparty\template directory (which should contain all your 3rdparty templates) - you can register all the templates there in one pass, by doing a multi-select - but make sure you do NOT register the NoNetTalk.tpl (if you have NetTalk installed).

Support

Your questions, comments and suggestions are welcome.
Keep an eye on our web page (www.capesoft.com) for new versions.
You can also contact us in one of the following ways:

CapeSoft Support
	Web Support Page	www.capesoft.com/support/index.htm
	Email	support@capesoft.com
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Address	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Purchasing SelfService

Buy Online
	Purchase CapeSoft SelfService for $149.00 from:	www.clarionshop.com

CapeSoft Sales
	Web	www.capesoft.com
	Email	sales@capesoft.com
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Address	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Distribution

CapeSoft SelfService ships as Clarion source code, so you can simply compile and ship your application. No external resources are necessary for SelfService.
However since your app may be using WinEvent and/or NetTalk you will need to ship those DLLs (and others) as required.

License & Copyright

This product is copyright 2003-2009 by CapeSoft Software (Pty) Ltd.

You are not allowed to copy any of the files, including but not limited to, Template (TPL & TPW) files, SelfService.clw, SelfService.inc and documentation files.

Each developer needs his own license to use SelfService. (Need to buy more licenses?)

This product is provided as-is. CapeSoft Software (Pty) Ltd (trading as CapeSoft), employees of CapeSoft, and Dealers of CapeSoft products, explicitly accept no liability for any loss or damages which may occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

Credits:
Many thanks to Vince Sorensen, firstly for his ABCFree templates that he makes available to Clarion programmers for free, and secondly for his help and support in this project.

Casey Rippon of Madrigal Soft Tools suggested the external Manager application, and showed how easy it was to implement.