Version www.capesoft.com Updated 01 October 2007

Contents

Introduction
Installation
JumpStart - start here - (recommended reading)
Examples
Ground Rules (recommended reading) [updated for Windows Vista]
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

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).

Upgrades are free. This may not always be the case, but upgrades have been free for our accessories for the past 10 years.

 

(recommended reading)

Using CapeSoft SelfService in your program used to be really easy (in the days before Vista) - but with the arrival of Vista your service applications do not display any user interaction. This means that you need to split your application into 2 apps - one that contains the user interface, and one that contains the processing part that is the Service functionality, and then create a communication channel between the two applications.

Code Example:
Work through the examples in your Clarion/3rdParty/Examples/SelfService/JumpStart folder. Typically the ClientApp and the VistaService app are the two that typify a very simple Client\Server scenario. We'll use these in the tutorial below.

What you need to do:

The biggest issue in moving your application to a service is separating the GUI from the processing part. In Vista, Services are no longer able to provide a user interface, which means that all user interfacing must be moved to a separate application. Your Vista Service application can still contain windows, they will simply not be displayed. Your interface application can be installed in the Startup programs when the user logs on.

Step 1 - identify the processing elements of your application which will be retained in the Server.

Step 2 - move the GUI (and user interaction) to a separate application.

Step 3 - create a communication channel between your Client app and the Server. Typically this would be with NetTalk.

Step 4 - add the SelfService template to your Server application.

JumpStart Tutorial:

What we are doing:
We are going to create a simple application set (a client which contains the user interface and a server that is the Service). The Service can run as a normal EXE - but in Service mode it will be controlled by the ClientApp. This appset will use NetTalk as the communication channel between the Client and the server apps. Here's a screenshot of what the Client application could look like:

1) Open Clarion 6, and either Open an existing application or Create a New Application for our server (In the Application Properties window make sure the Application Wizard checkbox is off. Press OK.).

2) Go to the Application menu - Global Properties. This opens the Global Properties window. Click on Extensions.

Insert the "Activate_SelfService" template.

Change the Service Name to 'CapeSoftJumpStart' (don't use spaces)
    and the Service Display Name to 'CapeSoft SelfService Jump Start'
    and the Service Description to 'CapeSoft SelfService Jump Start'

While we're in the Global Extensions, add the NetTalk global extension as well. This will be used for our communication channel between client and server, although you could use an alternative communication channel as well (like DDE).

    Press OK, and OK again.

3) Double click on the "Main (ToDo)" procedure and create a Window similar to the following (if you are creating a new application for the server):

4) Add the IncludeNetTalkObject to the Main window (if you're using NetTalk for your communication channel between client and server) and set the Object name to something like ThisSimpleServer. Set the Base Class to NetSimple and on the Settings tab, select the Server option.

Add the following to your data embed:

! We make a group to receive and send data
! This group structure must match exactly at the client so that communication
! will be possible between the server and the client.
ourData     group
command      long
time         long
date         long
AmService    byte
Automatic    byte
ServiceName  string(254)
            end

ourString string(size(ourData)),over(ourData)

!Equates for the command in the data. These equates must match at the client
           itemize,pre(equ)
InstallService         equate(100)
InstallAndStartService equate
RemoveService          equate
RequestStatus          equate
           end

In the ThisWindow.init method, you need to do the following (after the window is opened):

setcursor (CURSOR:Wait)
ThisSimpleServer.Open('localhost',2251)
setcursor

In the ThisSimpleServer.Process method, add the following code to handle the communication received from the child:

case self.Packet.PacketType
of NET:SimpleAsyncOpenSuccessful
of NET:SimpleIdleConnection
of NET:SimplePartialDataPacket
orof NET:SimpleWholeDataPacket
    ourString = self.packet.bindata[1 : size(ourString)]
    display()
    ourData.ServiceName = ''
    case ourdata.command
    of equ:InstallService
        gSelfService.InstallService(0) ! 0 = non-silent mode
        ourData.ServiceName = 'Reboot Required: '   !Additional text sent to the client
    of equ:InstallAndStartService
        gSelfService.InstallAndStartService() ! silent mode
        ourData.ServiceName = 'Reboot Required: '   !Additional text sent to the client
    of equ:RemoveService
        gSelfService.RemoveService(0) ! 0 = non-silent mode
        ourData.ServiceName = 'Reboot Required: '   !Additional text sent to the client
    of equ:RequestStatus
         !No reboot required in Vista, because the Service status has not changed.
    end
    ourData.time = clock() ! prime our data in the ourString
    ourData.date = today() ! which is "over" ourData
    ourData.AmService = gSelfService.AmService
    ourData.Automatic = gSelfService.Automatic
    ourData.ServiceName = clip(ourData.ServiceName) & ' ' & gSelfService.ServiceName
    self.packet.ToIP = self.packet.FromIP
    ! self.packet.SockID is same as sender
    ! self.packet.Socket is same as sender
    self.packet.bindata = ourString
    self.packet.bindatalen = size(ourString)
    self.send()
end

5) Click on the green tick to close the Window Editor, this will take you back to the Application Tree. Compile and Run the application.

Now we create the client application to contain the user interface

1) Open Clarion 6, and either Open an existing application or Create a New Application for the client(In the Application Properties window make sure the Application Wizard checkbox is off. Press OK.).

2) Go to the Application menu - Global Properties. This opens the Global Properties window. Click on Extensions.

Insert the  NetTalk global extension.

    Press OK, and OK again.

3) Double click on the "Main (ToDo)" procedure and create a Window similar to the following (if you are creating a new application for the server) - use the data in defined in step 4 below for the controls:

4) Add the IncludeNetTalkObject to the Main window (if you're using NetTalk for your communication channel between client and server) and set the Object name to something like ThisSimpleServer. Set the Base Class to NetSimple and on the Settings tab, select the Server option.

Add the following to your data embed:

ourString  string(size(ourData)),over(ourData)

           itemize,pre(equ)   !Equates must be the same in the client and the server
InstallService           equate(100)
InstallAndStartService   equate
RemoveService            equate
RequestStatus            equate
           end

Add the following to your local data

ourData       GROUP,PRE() ! This group must match the Server group
command         LONG 
time            LONG 
date            LONG 
AmService       BYTE 
Automatic       BYTE 
ServiceName     STRING(254) 
              END 
Port          LONG(2251) 

Add the following to your Procedure routines:

SendData Routine
  if ThisSimpleClient.openflag = 0
    ThisSimpleClient.open('localhost',Port)
    exit
  end
  setcursor (CURSOR:Wait)
  clear (ThisSimpleClient.Packet)

  ThisSimpleClient.Packet.BinData = ourString
  ThisSimpleClient.Packet.BinDataLen = size(ourString)

  ThisSimpleClient.Send()
  ourdata.Command = 0
  if ThisSimpleClient.Error = ERROR:ClientNotConnected
    Message ('Sorry the connection has already closed.')
  end
  setcursor

Now add the following to the ThisWindow.init method:

!Open the port first, so we can make sure that the service is running, and run it if it's not
setcursor (CURSOR:Wait)
ThisSimpleClient.DontErrorTrapInSendIfConnectionClosed = 1 ! We want to trap for this error ourselves. The error if it occurs is ERROR:ClientNotConnected
ThisSimpleClient.AsyncOpenUse = 0
ThisSimpleClient.InActiveTimeout = 9000
ThisSimpleClient.Open('localhost',Port)
setcursor

  !Install and start the service
ourdata.Command = equ:InstallAndStartService
do SendData
  !Install the service
ourdata.Command = equ:InstallService
do SendData
  !Remove the service
ourdata.Command = equ:RemoveService
do SendData
  !Request the service details
ourdata.Command = equ:RequestStatus
do SendData

In the ThisSimpleClient.ErrorTrap method, place the following code:

if self.error = 10061   !Connection refused
 !This means that the server is not running, so let's offer the ability to start it
  case Message ('Open communication channel Failed.|' & |
                'This probably means that the server is not running.|' & |
                'Error = ' & self.Error & '|' & |
                'Would you like to start your Service exe now?',|
                'NetTalk Error',icon:exclamation,button:yes+button:no,button:yes)
  of button:yes
    run('.\VistaService.exe')
  of button:no
    !Don't do anything
  end
end

In the ThisSimpleClient.Process method, place the following code after the parent call:

case self.Packet.PacketType
of NET:SimpleAsyncOpenSuccessful
  if ourdata.Command
      !We were waiting to send a command, but the channel needed to be opened
    do SendData
  end
of NET:SimpleIdleConnection
  self.abort()
of NET:SimplePartialDataPacket
orof NET:SimpleWholeDataPacket
      !We got a reply from the server, let's display the status on the screen
  if self.Error = 0
    if self.Packet.BinDataLen > 0
      ourString = self.packet.bindata[1 : size(ourString)]
      display()
    end
  end
end

5) Click on the green tick to close the Window Editor, this will take you back to the Application Tree. Compile and Run the application.

When the application launches, you can now click on the "Install" button. Run the "Windows Service Manager" (Windows Run: services.msc). You'll see a screen like the following appear.

You can now right click on the CapeSoft SelfService Jump Start entry (see above) and click Start.

Alternatively you can reboot the machine and watch your application start. (Note: You'll need to login before you see the window, but the application was started on boot up, not login.)

Important: Okay, now that that's working this is a great time to read the Ground Rules, and then we will return to completing your JumpStart application.

Part 2

What we are doing:
In Part 1, we add the Service mechanism to an application, now we are going to add some WinEvent functionality, that will allow our application to shut down with out the dreaded "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 10 minutes, to complete.

1) (do this in the server and client applications) Click on the Application menu (in Clarion 6) - Global Properties, and then click on the Extensions button in the "Global Properties" window. Insert the "Enable WinEvent" global extension. (If you can't find WinEvent in the list, then you haven't installed or acquired WinEvent - You'll need to do this first).

On the WinEvent template tick on the "Auto-Shutdown on" checkbox. (You can leave all the rest of the options on their default settings). (This option will prevent Windows from displaying the "Application still active. Quit the application before quitting Windows" message when Windows shuts down.

2) (this is recommended for your client application) Open your client app in the Clarion IDE. Right-click on your Main procedure and choose Extensions from the right-click menu. Insert the WinEvent "TaskbarIcon - WinEvent: Add Icon to system tray" extension:

In the "Name of Icon to add" field enter the following (including the quotes): 'icon.ico'
In the "Icon Tip" field enter the following: 'CapeSoft SelfSevice JumpStart'
Click on the ... button to the right of the IconHandle(long) field.
Add a new long to the LOCAL DATA Main called something like TaskBarIcon
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

7) Return to the Embedded Source window and Insert the following embed code after the "Local Objects - ABC Objects - Window Manager - Init - Open the window" section:

  window{prop:text} = 'SelfService JumpStart started at ' & |
                      clip(left(format(clock(),@T4)))

    (This will show you the time the service was started in the Title bar)

8) Now go back to the Window Editor of the Main window.

Add an "Exit" button or Menu item with the following code embedded into the Accepted code section:
post (event:closedown) ! Will close down the application

Add a Timer to the Window.
Right-click on the Window Title Bar | Properties. Then in the Extra Tab, add a timer value. (100 should be fine).
(You'll need a timer for the Icon to be refreshed correctly when/if your Service becomes visible on the Desktop)

9) Compile and run the application. You can also test starting (and stopping the application) from the Service Manager. You should now see your application running in the task tray as the red dot icon.

    

Examples

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

• JumpStart - This is the same code as used in the JumpStart
• Connection Checker - Service example that checks a TCP/IP connection and demonstrates a Web Server interface (using NetTalk)
• 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.
• Process and Threads - Simple example using the Process and Threads methods in SelfService.
• Legacy - Simple example using the Legacy - Clarion Template Chain.

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.

2) 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.

3) Including a user interface in a service is NOT recommended, and is not supported at all by Windows Vista and later versions of Windows. You should separate the user interface from the service and run it as a separate application which can communicate with your service and allow the user to manage it. You can do this using NetTalk, DDE etc. Note: You may still have a user interface in the Service application, it will simply not be displayed in Windows Vista - if it is running as a service.

4) 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.

5) Windows XP/Vista Fast User switching allows users to switch from one user's desktop to another without requiring that the user logs out. Please read the JumpStart section on creating a client/server Service pair to allow user interaction with your service.

6) If you are wanting to support Fast User switching, or are writing your service from scratch, or need to be able to run the service under Windows Vista and later, then you should implement your product as follows:
a) A server which does all the hard work, runs the whole time and has no GUI, and
b) A client which talks to the server, has the GUI and can have one client running for each Fast User Switched users.
The client and server can share data via any kind of inter-process communication (e.g. TCP/IP (We recommend NetTalk), RPC, Named Pipes).

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 to 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.

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. 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.

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.

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

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) Is there a method where I can control the service from another program?

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 Multi-DLL 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.

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?
• D3) Can I control other Services from within my application?
• D4) How can I install my application as a Service upon installation?
• D5) I'm having problems with my application running in windows Vista.

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: Firstly, let me say that there aren't any hard fast rules, but here are some points that you may want to weight up when comparing Scheduled applications vs Services:

NT/XP/2000/2003 Scheduler:
1) You either need to add your application to the Scheduled Tasks list manually or find the API calls to do it yourself. Sometimes this works really well, and other times it's a right well pain.
2) If you want to run your app under XP/Vista, the user that you use in the Scheduler needs to have a password. You may get it to work sometimes without, but to prevent it from haunting you this is a better idea. 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 poking 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) I don't know of any tools that do this all for you, so each programmer has to learn the ropes of the NT Scheduler for himself.
7) 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 <g>.

NT/XP/2000/2003 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) n/a
4) You can still interact with the GUI if you wish. (using the Interact with Desktop option).
5) n/a
6) SelfService does all the hard work for you and comes with full documentation, example, support etc.
7) Services are cool. <g>.

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. (Well done Vince).

Here's a little snippet from the ABCFree changes log
---------
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. i.e. People could request support.

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 fancy (for example /install). This can be done in the Global Extension.

B2) How can I Start and Stop my Services?

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

To load the Windows Service Manage in 2000/XP/2003
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.
e.g. 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 A3.

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 A2.

B5) Is there a method where I can control the service from another program?

Answer: Yes there is:

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

StartService PROCEDURE (string p_ServiceName, long p_Silent=1),long,proc ,VIRTUAL 
RestartService PROCEDURE (long p_Silent=1),long,proc ,VIRTUAL 
StopService PROCEDURE (string p_ServiceName, long p_Silent=1),long,proc ,VIRTUAL 
GetServiceStatus PROCEDURE (string p_ServiceName, *SS_SERVICE_STATUS p_ServiceStatus, long p_Silent=1),long,proc ,VIRTUAL

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 /exe to tell SelfService not to call the Service code, when it is started by the user from say a shortcut.

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 folder - as this works 100%.

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

Answer: Make sure that all application DLLs are being shipped in the application folder. This is most likely the case of the problem.

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

Answer:

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: Services can have Command line parameters, which you can customise when the service is stopped in the Windows Service Manager (see how to load the Windows Service Manager)
 

D3) Can I control other Services from within my application?

Answer: You can use the gSelfService.StartService PROCEDURE  (string p_ServiceName, long p_Silent=1) and specify the ServiceName in the parameter. This will start the other services.

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.

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. 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:

Purchasing SelfService

While SelfService is on sale for $149.00. It is available from:

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

Distribution

CapeSoft SelfService ships as pure Clarion source code, so you can simply compile and ship your application. No external resources are necessary for SelfService.

License & Copyright

This product is copyright 2003-2006 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.

 Version History

Version 3.18 Gold (21 September 2007)

• Includes an example for Vista compliant service, as well as documenting how to implement a vista compliant Client/Server application pair (one to contain the user interface and the other to contain the service).

Version 3.17 Gold (19 September 2007)

• Template fix - fix for legacy class generation regression introduced in 3.16 (includes SelfService.tpw 1.55)

Version 3.16 Gold (31 August 2007)

• Template - fix for legacy class generation (includes SelfService.tpw 1.54)
• Template - check that Command Line pars (template prompt) are not blank, before trying to use them.

Version 3.15 Gold (25 October 2006)

• Fix - tweak to allow variable ServiceName and description. These should be set in the 'SelfService - Initialize variables' embed point (if a variable is used).

Version 3.14 Gold (24 July 2006)

• Fix - tweak to template (another fix for the method headers not being generated (as in 3.13)).

Version 3.13 Gold (12 July 2006)

• Fix - in some cases the method headers were not being generated (caused by Read classes every generate being checked - this is an obsolete function that is no longer required).
• Included the new SelfService.tpw (1.53) - contains a fix for case sensitivity in derived methods from a base class.

Version 3.12 Gold (7 June 2006)

• Re-labeled the Global Extension template.

Version 3.11 Gold (5 June 2006)

• SelfService.tpw (version 1.51 - was 1.49) - fix for interference with other templates (using the Object01.tpw template)
• Template fix: %SSClassName defined correctly (was coming up with error when viewing embeds).

Version 3.10 Gold (18 May 2006)

• Template: Added new Control Template - "Service Buttons Controls" - This adds an "Install and Start Service" button to your window.
• Template: Updated Control Template - "Service Buttons Controls" - so that the Close button works with WinEvent.
• Documentation - added the Control Templates section to this documentation.

Version 3.09 Gold (10 May 2006)

• Template: Changed %ClassName to %SSClassName - #prepare was getting confused with multiple variable definitions of the same name (across different templates). This could result in initially getting the wrong class into the template (if you have xFiles or HotDates present in your application). In this case, go to the class tab and set the Base Class to MyService and the ClassHeader file to SelfService.inc.
• Requires GPFReporter 2.05 (if used in conjunction with GPFReporter).

Version 3.08 Gold (1 May 2006)

• Fixed missing SelfService:Version equate (regression in 3.07).

Version 3.07 Gold (24 April 2006)

• Changed 'Re-read class option' to default to 0.
• Template fix - changed control template to pick up the correct buttons placed by the template.

Version 3.06 Gold (13 April 2006)

• Updated Jump Start Documentation. 
• Corrected assert regression (introduced in 3.04)

Version 3.05 Gold (12 April 2006)

• Template Fix for Regression introduced in 3.04 (for fix with GPFReporter). 

Version 3.04 Gold (10 April 2006)

• Template Fix - when used with GPF Reporter, sometimes the class was being switched to use the GPF Reporter class instead (and visa-versa). 
• Template Fix - removed Tahoma font setting from all template prompts (except the General tab) - means that entry prompts are legible in PCs with Clear-Type fonts turned off.

Version 3.03 Gold (22 March 2006)

• Changed Thread32First and Thread32Next API calls load dynamically, so that it works on NT 4.0 systems.

Version 3.02 Gold (16 March 2006)

• Tweaked Jump Start and included these changes in the Docs. This makes it clearer on what to do so that the Taskbar Icon is displayed as a service.

Version 3.01 Gold (1 March 2006)

• Slight tweak to the template, so that it works with NetTalk v3.xx. (Was previously only working with NetTalk 4.xx).

Version 3.00 Gold (27 February 2006)

• New methods to setting and getting the thread and process priority as well as window information.
• New Control Template and Template Utility for adding buttons that will Install & Start, Install, Remove or open the Windows Service Manager.
• New Example using Process and Threads methods.
• Added NetTalk support so that the NetTalk DLL does not close itself down when you Log Off. This will work best with NetTalk v4.00 and above
• New Fix in WinEvent v3.35 which ensures the Task Icon is displayed. You'll need a timer on your window, and use a IconHandle (long) in the Settings tab of the WinEvent: Add Icon to System Tray window extension. See FAQ C2 for more details.

Version 2.05 Gold (10 May 2005)

• New method self.InstallAndStartService()
• New method self.RestartService()
• Silent options turned on by default (except from command line). So if you want InstallService() and RemoveService() to be non-silent please call then like this: InstallService(0) and RemoveService(0)
• Added functionality to work with GPF Reporter v2.05 so that GPF Reporter can restart services.
• Updated examples accordingly.

Version 2.04 Gold (15 November 2004)

• Fixed Example Connection Checker, that had a OS_ShellExecute clash with NetTalk.

Version 2.03 Gold (26 October 2004)

• New Property: DependenciesQueue - new property added. You can specify one dependency on the template now, or multiple dependencies using hand code. This is very useful if you want to load say SQL Server before your service loads.
• New Property: LoadGroupOrder. New property for building kernel services.
• Updated Example: Updates the TCP/IP Connection Checker Example
• Update Template to the new CapeSoft look and feel.

Version 2.02 Gold (13 September 2004)

• New Example: Connection Checker - This example demonstrates using a Web Server in a service to manage the configuration. The example will check a TCP/IP connection. Which can be useful for checking (a) Network route reachable, (b) if a machine is running, or (c) if a TCP/IP application is running. This example will be show-cased at the Florida DevCon 2004 in the session that Jono Woodhouse will be presenting on Services.

Version 2.01 Gold (7 September 2004)

• Fixed: Dictionary Class tweak so that your Service (which uses a Dictionary) doesn't GPF when you run it with the /is or /rs option or after the "cannot load as another instance is already running" warning.

Version 2.00 Gold (3 September 2004)

• InstallService: Now will update the service details if it was already installed. (Previously it produced an error).
• Minor Changes: To the log method and also DWORD aligned the properties and method variables.
• Fixed: Dictionary Class changes in Clarion 6.1 were causing a GPF (and Assert error on line 227 of ABFile.clw if you had debugging on) when you had a service application with a dictionary. This has now been fixed.
  (Incidentally, if you are still using Clarion 6.0 you will need to turn off the "Use Dictionary.Construct/Destruct Fix" checkbox in the template).
• Legacy: Fixed the templates so they work with Legacy apps again

Version 1.12 Beta (23 July 2004)

• Template: Minor tweak for use with Multi-Prj
• Docs: Updated to use '~icon.ico' option with WinEvent
• Template: Fix to stop the following Syntax errors:
  Prototype is :_RUNAPPLICATION(MYSERVICE)
  Procedure doesn't belong to module: GSELFSERVICE._RUNAPPLICATION
• Template: Changed from using Cape01.tpw to using SelfService.tpw (so now there are two template files SelfService.tpl and SelfService.tpw). Synchronized to the same code in Object Writer's Object User v2.09
• Template: Changed the template variable for the Base Class Name in the Advanced Tab in SelfService. This means that the Base Class will revert back to MyService when you upgrade to v1.12.. This will only affect really advanced users, and you will understand what to do, if that's you.

Version 1.11 Beta (23 January 2004)

• Template: Added a bit of code the the global application to check if you are using a compatible version of WinEvent.
• Object: New advanced method .HandleStopShutdown()
• New Example: New example - Machine status reporter, that reports when a machine boots and shuts down.
• Object Fix: Services now work in Windows 2000, previous version introduced some bugs that caused services not to load correctly in Windows 2000
• Object Fix: Fixed the .LoadWindowsServiceManager() method for Windows 2000.
• Template: Some tweaks and improvements.

Version 1.10 Beta (20 January 2004)

• Template: Added Only allow One Instance to run at a time option.
• Template: Now includes a Service Description, which is displayed in the Windows 2000, XP, 2003 and Vista Service Manager.
• Example: Added the NetTalk DIP Server as an example.
• Object: Added code to prevent the 15 second delay from happening, when you start your application in non-service mode (i.e. From a shortcut). See FAQ C1
• Documentation: The documentation has been improved, and now includes an Object Property and an Object Method section
• Object: Added the .MapDrive() method for creating maps like Y: to \\pengun\y-drive (see the Object Methods).

Version 1.03 Beta (18 December 2003)

• Template: Added Work with WinEvent option.
• WinEvent v3.04 fixes the problem with not being able to see the tasktray icon when you login.
• Template: Improvements to the template (thanks Geoff) regarding the way the object is generated into your application.
• Documents: Updated
• Object: Using HandlerEx for Windows XP/Vista
• Object: LoadWindowsServiceManager - now works for Windows NT as well.

Version 1.02 Beta (21 November 2003)

• Template: Note: Please remove the single quotes around your Service Name and Service Description in your Global Extension to avoid a compile error.
• Template: Added an extra option to the template so that the path is set to the EXE folder when the application is started as a Service.
• Template: Added an option to the template so that you can change the command line switches e.g. instead of using /is you could use -install

Version 1.01 Beta (18 November 2003)

• Documentation: Improvements to the Documentation & FAQ.
• JumpStart: Compacted the JumpStart.

Version 1.00 Beta (17 November 2003)

• First release of CapeSoft SelfService.

[End of document]