CapeSoft.Com
Clarion Accessories
RunOnce
Documentation
Download Latest Version Index History Templates
CapeSoft Logo

CapeSoft RunOnce
Documentation

Installed Version Latest Version


Please Note:

You need NetTalk (and by extension, StringTheory, jFiles 3 and Reflection) to use RunOnce in your application.

NetTalk et al are 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

Using CapeSoft RunOnce

Add RunOnce to your application in a few Easy Steps!

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

  1. Add the RunOnce global extension (Global -> Extensions -> Insert -> Activate CapeSoft RunOnce).
  2. On the Procedures Tab of the Global Exension template click on the Import Procedures button.
  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).
  6. Add the other Global Exension templates NetTalk requires to the app if you haven't already done so. These are StringTheory, Reflection and jFiles.
For additional options, take a look at the RunOnce templates section of this document.

Problems in implementing RunOnce:

Multiple Programs

When your program starts a Mutex (Mutual Exclusion object, offered by the Operating System) is created, using the Application Name (as set on the Global Extension Template.) Windows will refuse the mutex if it already exists, and so the program knows it is a "second instance".

If the Mutex suceeds, then this is the first instance, and so a listening listening port on the 127.0.0.1 (ie, "same machine") Network port is opened.

If the Mutex fails then a connection to the first instance is created, and a command (come to front) is passed, along with any other information you may want to pass, and the second instance then closes.
.

Template Reference

The Global Extension Template:

General Tab

Disable All RunOnce Features
Tick this on to disable all the RunOnce template code, and prevent the code from being generated into your application. Typically used for debugging when the RunOnce code is possibly causing conflicts in your app.

Options Tab

Application Name
This 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. If you want to prevent users from running multiple copies of the program (ie first user to run it is ok, but other users fail, then prefix the Application Name with Global\
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.
Port
This number is the NetTalk port that is used to communicate between the second instance and the first instance of the application. This port number should not be used by other protocols on the computer. Typically a "random" port of your choice, between 2000 and 32 000 should suffice.
Disable RunOnce For Remote Desktop sessions
If your application will be used in a Remote Desktop (RDP) environment, then you can check this checkbox to disable RunOnce when your application is running in a Terminal Server environment. The CWUTIL function IsTermServer() is used to identify such an environment.
Disable RunOnce IF
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.

Other Applications Tab

Other Applications to Call

Procedures Tab

Import RunOnce Procedures
This will import the default RunOnce_HandleSecondInstance procedure into your application.

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.
CommandLine Value In
This is the name of a field that will contain the commandline passed from the second instance.
Handle Notification of Second Instance
If you want to add code to when the second instance sends a command, then you can use this embed button on the template to access the correct place in the code to do this.

Support and Purchase

CapeSoft Support
Email
Telephone +27 87 828 0123
(087) 828 0123

Distribution

RunOnce ships as source so it is compiled into the application and there are no additional files needed for distribution. There are no runtime royalties for using RunOnce. Also see the License & Copyright section for more information.

License & Copyright

This template is copyright © 2003-2024 by CapeSoft Software. None of the included files may be distributed. Your programs which use RunOnce can be distributed without any RunOnce royalties.

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

This product is provided as-is. CapeSoft Software and CapeSoft Electronics (collectively trading as CapeSoft), their employees and dealers 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.

Use of this product implies your acceptance of this, along with the recognition of the copyright stated above. In no way will CapeSoft , their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

For the full EULA see https://capesoft.com/eula.html

Version History

Download latest version here

Version 1.13 - 25 May 2025
 Version 1.12 - 25 May 2021
 Version 1.11 - 18 September 2018
 Version 1.10 - 25 February 2015 Version 1.09 - 3 February 2014 Version 1.08 - 2 May 2013 Version 1.07 - 10 August 2011 Version 1.06 - 29 March 2010 Version 1.05 - 24 March 2010 Version 1.04 - 10 November 2008 Version 1.03 - 9 October 2008 Version 1.02 - 26 September 2008 Version 1.01 - 25 September 2008 Version 1.00 - 5 September 2008