CapeSoft RunOnce

Please Note:
You need NetTalk to use RunOnce in your application.
NetTalk is not included in the RunOnce purchase, so if you don't already own it you will need to purchase it as well.

Description

RunOnce ensures your application only opens in one instance. With a couple of easy steps, your application won't start up twice.

Feature list

• Only allows one instance of your exe to run.

• Brings the running exe to the front, when a second instance is run.

• Passes command line parameters from the second instance to the running instance.

Add RunOnce to your application in a few Easy Steps!

(For Multi-DLL apps - do this in the mainexe application).

1) Import the RunOnce_HandleSecondInstance window using the template utility. Open your application in the Clarion IDE, and select (from the Application menu) the Template Utility, and then select one of the following utilities (there's one for ABC and one for legacy):

2) Add the global extension (Global -> Extensions -> Insert -> Activate CapeSoft RunOnce).

3) On the Options tab of the Global Extension template, enter the port number (use a random number between 2000 and 32000.

4) Add the RunOnce - Server window Template extension template to your frame window (or another window that stays open continuously. (Procedure properties -> Extensions -> insert and select the RunOnceServer template)

5) Add NetTalk to this application (in the normal manner as prescribed in the NetTalk docs) if you have not yet added it. (Note: for multi-dll applications, you'll need to add the NetTalk extension to your data dll application as well - if you have not done so already).

For additional options, take a look at the RunOnce templates section of this document.

Problems in implementing RunOnce:

• If you are getting other instances of your application opening, make sure that you have completed all of the above steps (particularly the addition of the RunOnceServer local extension template).
• If you have a legacy application that GPFs on startup, see the NetTalk FAQs on how to add the dllmode and linkmode equates. This fix will be included in NetTalk 4.32.

The Global Extension template:

• On the General tab, you can disable RunOnce by checking the Disable all RunOnce Features checkbox. This is useful for debugging (without having to remove the template).
• On the Options tab:

	The Application Name is used to register the mutex to identify a unique application. By default this is the name of your application, but you can make it something else if you want to identify more than one exe to the same application name. Use 'Quotes' or a variable for this.
	The RunOnce Procedure is the procedure that is used to handle a second instance of the exe that is run. This procedure will pass focus to the main procedure and send any commandline parameters to the current instance of the application.
	The Port number is the winsock port that is used to communicate between the second instance and the first instance of the application. This should be unique (across all applications running) in order to enable communication between both instances of the application.
	If your Clarion 6 application will be used in Terminal Server (TS) environment, then you can check the Disable RunOnce for Terminal Server sessions checkbox to disable runonce when your application is running in a TS environment
	You can also enter an expression in the Disable RunOnce if prompt that (if evaluates to true) will disable RunOnce at runtime. This means that you can disable or enable runonce for different clients/environments. Use the Global embed point: 'RunOnce - Prime variables to disable RunOnce at runtime' to prime variables used in this expression - before RunOnce is activated at runtime.

The RunOnce Server local extension template

This template is added to a window in your application that is always running. This will handle communications for the first instance of the exe that are received from a second instance.

• The CommandLine value in field allows you to enter a field that will contain the commandline passed from the second instance.
• If you want to add code to when the second instance sends a commandline, then you can use the Handle notification of Second Instance embed button on the template to access the correct place in the code to do this. NOTE: You can add code to handle the arrival of the notification from the second instance using this same embed point:

To download the latest version of CapeSoft RunOnce please visit http://www.capesoft.com/accessories/Downloads.htm#RunOnce.

To purchase CapeSoft RunOnce, please click on the ClarionShop links below

Buy Online
	CapeSoft RunOnce is available for online purchase at $49 from our secure site: www.clarionshop.com www.clarionshop.com

Version 1.04 - 10 November 2008

• Clarion 7 compatible install.

Version 1.03 - 9 October 2008

• Template embed point descriptions tweaked (for clarification of where to place embed code on SecondInstance run).

Version 1.02 - 26 September 2008

• Template version number was not incremented correctly.
• Doc version number was pointing to the incorrect image file.
• Change Description of the 'Handle Notification of Second Instance' embed button (not just used for handling Command line)

Version 1.01 - 25 September 2008

• Included support for Runtime disabling of RunOnce (see Global Extension template options for details)
• Included support for runtime disabling of RunOnce in Terminal Services Environments (C6 only) - (see Global Extension template options for details)
• Fix - does not keep the window on top when SecondInstance runs.

Version 1.00 - 5 September 2008

• First release of CapeSoft RunOnce