Technical Resources at AEGIS

PowerBuilder Tips

Determining if an Application is already running

Tip By: Mike Barlotta

Sometimes we need to make sure that only one instance of our Windows-based application is running at a time. This was an easy task in the 16 bit Windows operating systems. The following code in the application open event would handle this:

// Check to see if application is already running
IF Handle( This, TRUE) > 0 THEN
   HALT CLOSE
END IF

However, in a Win32-based application this method does not work, the return value of Handle will always be 0. This is because each application runs in its own memory-space and the API function GetModuleUsage is no longer supported.Here are four methods to determine if there is a Win32 application instance already running:

• Use the FindWindow Win32 API function.
• Use file mapping (Recommended approach).
• Use a global atom.
• Use DDE.

Using the FindWindow API call

This method uses the Find Window API function to search for the Window Title specified. If a window is found with a title matching the search string than the window handle is returned. The idea here is to search for the window title of the MDI Frame or main window of the application. As long as we don't find the window we can assume the application is not open and continue opening our application.

The first thing we need to do is declare the external function (you will need to decide if you are using a NVO or declaring it as global). The function declaration is as follows:

FUNCTION ulong FindWindowA(ulong classname, REF string winname) LIBRARY "USER32.DLL"

Note: This function declaration is different than the one in the Win32 SDK and FaxBack document #47615.

Here is a sample of code used to search for other instances of the application placed in the application open event:

ulong ll_handle
string ls_win_title

ls_win_title = "Application Window Title"
ll_handle = FindWindowA(0, ls_win_title)

IF ll_handle > 0 THEN
	// it's already running
	HALT CLOSE
ELSE
	// Open Window
END IF

Back To List

Using the File Mapping Method

This method relies on the application opening a file and maintaining an exclusive lock. The application maintains the lock on the file until the user exits from the application so that when another instance of the application is opened it will try to open the file and fail.

The example shown below creates a file named FileMap.txt using FileOpen. If FileMap.txt can not be opened, then you know that there is already a running instance of this application. The following code fragment demonstrates how a file mapping can be used to allow only one instance of a Win32-based application. It was placed in the application open event.

Note: Using the defaults on FileOpen requires the file to exist prior to running the application (as stated in FaxBack # 47615). The following code example opens the file in write mode so if the file does not exist, a new file is created.

 
integer li_file_num
li_file_num = FileOpen("FileMap.txt", LineMode!, Write!, LockWrite!)
IF li_file_num = -1 THEN
	// Error creating file - assume
	// that application is already open.
	HALT CLOSE
ELSE
	// Open Window
END IF 

This method is one of the better choices since it can work on any platform.

Back To List

Using the Global Atom Method

This method uses the Windows global atom table. An application can place a string into the global atom table and get a unique id. Any application can access the string by querying the global atom table for it.

When an application starts it checks the global atom table for an occurence of the application name. If it exists than the application already is opened.

The following Win32 API functions are required:

FUNCTION uint GlobalAddAtomA(string s) LIBRARY "Kernel32.dll"
FUNCTION uint GlobalFindAtomA(string s) LIBRARY "Kernel32.dll"
FUNCTION uint GlobalDeleteAtom(uint iAtom) LIBRARY "Kernel32.dll"

The following code sample is placed in the application open event:

IF GlobalFindAtomA("APPNAME") > 0 THEN
	HALT CLOSE
ELSE
	g_atom = GlobalAddAtomA("APPNAME")
	// Open Window
END IF

The following code is placed in the application close event:

IF g_atom > 0 THEN
GlobalDeleteAtom(g_atom)

Back To List

Using the DDE Method

This method requires that the application be able to operate as a DDE server. To do this we need a window which is always open to be our server window, the MDI frame is an excellent choice for most applications. When the application opens it checks to see if it can open a DDE channel. If this succeeds, we know that an instance of our application is running since it can connect to the DDE server. In order to open a DDE channel we need to have a client window, a channel can not be opened from the application object.

Use the application name as the DDE Server name.

The following code trys to open a channel to the DDE Server. If it fails it starts itself as the DDE Server. It should be placed in the open event of the server window (the MDI Frame). If the server window is not the first window opened in the application than the open channel logic should be placed in the open event of that window. The StartServerDDE function should always be placed in the open event of the server window.

long ll_Channel

ll_Channel = OpenChannel("APPNAME","test")

IF ll_Channel > 0 THEN
	CloseChannel(ll_Channel)
	HALT CLOSE
ELSE
	StartServerDDE( this, "APPNAME", "test" )
END IF

Add this line of code to the close event of the server window:

StopServerDDE( this, "APPNAME", "test" )

Note: This method does not work on a Macintosh.

Back To List