Description

 

Create a unique mutex returning its handle.

 

Syntax

 

Mutex_Handle = APP_MutexCreate(AUniqueMutexName)

 

Returns

 

Number

If Zero it can mean either that a mutex with the same name already exists or current user has no enough authorization to create a mutex.

 

Parameters

 

 

Remarks

 

The Mutex object is a synchronization objects. Its basic purpose is to provide a synchronization method. For example if you want to be sure that a script is executed just once, try to create a mutex with a unique name. If you cannot create a mutex with that name (return value is zero), it can mean the same script is already running in your system so stop current one. If instead you can create a mutex, it means the same script is not running.

 

It is important to store returned handle in order to be able, later, to close it.

It is programmer responsibility to close all created mutex.

If return value is zero it can mean either that a mutex with the same name already exists or current user has no enough authorization to create a mutex.

 

Restrictions

 

See also

 

App Object, App_MutexClose,

 

Examples

 

Dim hMutex      As DWORD

Dim Mutex_Name  As String = "AVeryUniqueStringToNameMutex"

 

'---Better if MutexName has script name inside so it will be specific to this script

Mutex_Name += app_scriptname

 

hMutex = APP_MutexCreate(Mutex_Name)

 

If hMutex = 0 Then

  MSGBOX 0, _

            "I was not able to create a Mutex named: " & Mutex_Name & $crlf & _

            "This means that another instance of the same script is already running" & $crlf & _

            "or you have not enough user authorization to create a Mutex." & $crlf & _

            "In any case script execution is aborted. Sorry", %MB_ICONERROR

  STOP

Else

  MSGBOX 0, _

            "I was able to create a Mutex named: " & Mutex_Name & $crlf & _

            "Mutex handle is " & hMutex & "" & $crlf & _

            "Script will continue. Perfect", %MB_ICONINFORMATION

 

End If

 

'...

'------

'---Here code for script ...

'---

'...

 

'---At the end close the mutex handle to release it for new script execution

APP_MutexClose(hMutex)