Version 3.34 © 1997-2005 by CapeSoft Software (Pty) Ltd www.capesoft.com Updated Friday 20 January 2006

Contents

Introduction

Copyright

Support

Installation

Distribution

How to read this manual

Example Program

Enabling WinEvent Functions
WinAlert Functions
Comm's Functions  
Taskbar Functions  
Window Behavior Functions
Windows System Functions
RAM & Disk Functions
Time & Date Functions
File Functions
Process & Thread Functions
DLL Functions
SMS Functions
Debugging & Error Reporting Functions
Auto-Shutdown Functions
Other Functions
Reference Section
Frequently Asked Questions (FAQ's)
Version History

Introduction

Welcome to WinEvent. This small library package allows you to leverage the power of the Windows API. In addition to the WinAlert functions (which allow you access to the native Windows messages) there are also now Comm's (RS232) functions, Taskbar functions and Windows Behaviour & System functions.

All the functionality provided in WinEvent is built into Windows itself in one way or another. The main advantage of WinEvent is two fold.

Main Advantages
		It provides the functions in a simple easy-to-use manner, avoiding the complexities of the Windows API.
		The functions are (mostly) cross-compatible between 16 and 32 bit implementations of your program. The Taskbar functions and some advanced Comm's functions are only available in 32 bit programs, but all the other functions are the same in 16 and 32 bit programs.

WinEvent functionality is divided into 5 areas:

Functionality
		Windows message capturing functions (WinAlert) WinAlert allows your CW programs more access to the native Window messages. This is in itself nothing new. Using the sub-classing technique access to the Windows messages has been available since almost the first days of CW. WinAlert provides a simple wrapper to subclassing, which removes the complexities and makes the code both simple to follow, easy to implement, and consistent with the rest of the Clarion language. In essence one new major function, and a couple of support functions allow the flexibility and ease of use that we've come to expect from Clarion. In addition it comes with a template that makes adding this wrapper to your applications even easier. You can use the template to alert messages on individual windows. In addition a utility template makes it possible to enable Auto Shut Down across your entire application.
		RS 232 Port functions Very often developers need simple access to a Comm's port. This simple functionality is built into the Windows API, but is quite complex ad difficult to code. In addition to this the APIs for 16 bit and 32 bit Windows are very different. The Comm's section of the WinEvent package provides some simple easy-to-use functions that allow you to read and write to Comm's ports. In addition almost all the functions are the same in 16 and 32 bit ( the library takes care of the API differences ) so it's easier to move from one platform to another. The library also corrects a bug in the Windows functions that affect Comm's at speeds of greater than 19200. Some advanced functions to test specific hardware handshaking lines for their current status are only supported in 32 bit as no 16 bit equivalent exists.
		Taskbar functions Users of Windows 95, and Windows NT 4.0, will be familiar with the Taskbar that usually sits at the bottom of the screen. The taskbar functions allow you to add / change and delete an icon from the "Tray" ( the area at the right hand side of the taskbar ) as well as detect when the mouse has been clicked on an icon in the tray. This is very useful for apps which are running in the background on a full time basis. In addition, you can make use of a function that prevents your program from appearing on the main area of the Taskbar itself.
		Window behaviour functions A small group of functions that allow you to change the behaviour of a window. This includes the ability to make a window permanently "on top", and also the ability to bring the window to the front.
		System functions These functions return system information to your application. The Windows, and Dos (if applicable) version numbers are available to your application. Also you are able to get the current free disk space in 16 and 32 bit. This is useful for detecting low disk space conditions before they occur. A function for playing a wav file is also included.

Copyright

WinEvent is copyrighted © 2004 by CapeSoft Software (Pty) Ltd. CapeSoft Software (Pty) Ltd assumes no responsibility for applications created which incorporate WinEvent. WinEvent is used entirely at your own risk. You may not distribute any of the WinEvent files.

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

Support

We welcome your comments, suggestions, and criticisms. Please do not hesitate to contact us if you have a problem, or a suggestion.

You can contact CapeSoft in one of the following ways:

CapeSoft Support
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Purchase WinEvent at $149.00 from:

Buy Online
	Web	www.clarionshop.com

Installation

To install WinEvent, run the supplied installation file and follow the prompts.

Distribution

You are free to distribute the WinEvent DLLs with any of your Applications without extra charge.

The DLLs your program require will depend on your version of Clarion. Note that programs compiled in Local Mode do not use DLLs and therefore there is nothing extra for you to distribute.

How To Read this Manual

This manual is split into two sections. This first section contains a general overview of the WinEvent features. Each of the WinEvent function areas is dealt with and the templates provided are discussed here.

The second section is the Technical Reference. In this section the individual functions are described, along with their syntax. This is particularly useful as most of these functions are designed to be used in simple embed points etc.
 

Example Program

Included in the WinEvent package is a simple example program that demonstrates all of WinEvent's features. This example is in the \Clarion\3rdParty\Examples\Winevent\Windemo directory and is called WinDemo.

There is also an example of a barcode collector program. This is stored in \Clarion\3rdParty\Examples\Winevent\Barcode
 

Enabling WinEvent Functions

To use the WinEvent functions in your application you must first enable them. This is done by selecting the Global Properties option from the Application dropdown menu, selecting the Extensions button then the Insert button, scrolling down the extension options and then selecting EnableWinEvent - Enable the WinEvent functions in your app.

Once the WinEvent functions have been enabled in your application, you can use the Auto-Shutdown on tick box to apply the automatic shutdown function to your application. This will then be globally applied to the application.

WinAlert Functions

The Concept

First some terminology. An Event is the Clarion word for a message that is provided to you via the ACCEPT loop. A Message is the Windows equivalent. Part of the job of the Accept command is to filter out many of these Messages, and pass on only those Events that are usually required.

The idea is to use a new function, called WinAlert in the same way you would use the Alert function for keystrokes. This allows you to get at the messages before the Accept command does, taking further action where it is required. In addition to simply spotting the message, you can also specify its action at the same time. Some messages require an immediate reply (usually True or False) to the procedure that sent the message. However most messages would be required simply so that you can gain more control over the things that are happening. In this case a user event, is posted to the Accept loop, after storing the value of the Message.

To further complicate the issue Messages can also have additional data tagged on with them. This data is stored in 2 variables, often going by the somewhat cryptic names of wParam and lParam. The w and l represent the data type (w for Word - ie a Short (16bit programs) or Long (32 bit programs) and l for Long). On receiving the User event, WinMessageEvent you can use 2 new support functions, WinParam1() and WinParam2() to get the values of these parameters when the message arrived, as well as the Winevent() function to see which windows message triggered the event.

The Classic Example

One of the most frequently asked questions on the Internet's cw-talk mailing list, is "How do I get my application to terminate automatically when the user shuts down Windows ?" Using WinEvent the answer is both simple and elegant.

Using the Template

Once the WinEvent functions have been enabled, use the Extension Alert Window Messages utility template to enable Auto Shutdown (only if has not been set globally).

If Auto Shutdown has been globally set for your application, this option will enable you to disable the Auto Shutdown for when a selected window is the focus window (i.e. a window that requires you to save information before closing).

Using Code

You simply add the following line of code in the "After Opening Window" embed of your window.

WinAlert(WM_QueryEndSession,,Return1)

and the following in the "Before Closing Window" embed.

WinAlert()

Note: You need to add these lines to all windows that may be open at the time that Windows is shut down. If a window without this code is open, and has the focus, then the application will not shut down.

For those that care

Basically when you ask Windows to shut itself down it polls each running application by sending it the WM_QueryEndSession message. If all the applications respond by returning True, then they are each, in turn, instructed to close. In the above line of code you are telling the WinEvent library, that when the window receives this message, then it must return True. The utility template automatically adds an instance of the WinEvent extension template to each of your procedures.

Using WinAlert in Applications

The WinEvent extension template, which is included, assist's you in using the WinAlert functions. It organizes in one place the three items that are required, namely Alerting the message, handling any action that may be required, and unAlerting the message before closing the window. The template leads you through the options that you have, and provides you with the required embed point for processing the WinMessageEvent. You may alert as many Windows messages as you like.

Using WinAlert in a Hand Coded Project

This details how to add WinAlert functionality to a hand-coded project. For a detailed description of each of the functions, see the Reference section of this document.

Adding WinAlert to a function
		Use the WinAlert function to alert the message. This should be called before the Accept command, but after the window is opened.
		Use the WinAlert function, with no parameters, before Closing the window.
		Use the WinEvent's WinControl, WinParam1 and WinParam2 functions to examine the message.

Enabling WinAlert in the root module
		Include the (supplied in \clarion\libsrc ) map file, EventMap.Clw, in your Global Map.
		Include the (supplied in \clarion\libsrc ) equates file, EventEqu.Clw in your main module's data section.
		Clarion 5: Add the Event532.Lib file to your project for Stand-Alone compile mode or EvLib532.Lib for Local compiles. All these library files are in your \clarion5\3rdparty\lib directory. Clarion 5.5: Add the we55x.Lib file to your project for Stand-Alone compile mode or we55xL.Lib for Local compiles. All these library files are in your \clarion 55\3rdparty\lib directory. Clarion 6: Add the we60x.Lib file to your project for Stand-Alone compile mode or we60xL.Lib for Local compiles. All these library files are in your \clarion 60\3rdparty\lib directory.

Note:  A WinEvent Demo has been included with WinEvent (\Clarion X\3rdParty\examples\WinEvent\Demo\windemo.app) and can be used to view how these features can be used.

Comm's Functions

Using Comm's functions in an Application

Using Comms functions in a hand-coded project
		Include the (supplied in \clarion\libsrc ) map file, EventMap.Clw, in your Global Map.
		Include the (supplied in \clarion\libsrc ) equates file, EventEqu.Clw in your main module's data section.
		Clarion 5: Add the Event532.Lib file to your project for Stand-Alone compile mode or EvLib532.Lib for Local compiles. All these library files are in your \clarion5\3rdparty\lib directory. Clarion 5.5: Add the we55x.Lib file to your project for Stand-Alone compile mode or we55xL.Lib for Local compiles. All these library files are in your \clarion55\3rdparty\lib directory. Clarion 6: Add the we60x.Lib file to your project for Stand-Alone compile mode or we60xL.Lib for Local compiles. All these library files are in your \clarion6\3rdparty\lib directory.

Functions supplied

Newport
ReadPort
WritePort
ResetPort
ClosePort
KillAllPorts
SetHandShake
CtsHigh
DsrHigh
RingHigh
CdHigh
SetRts
SetDtr

 

For a detailed description of each of the functions, see the reference section.
 

Taskbar Functions

There are a number of Taskbar functions which allow your application to interact with the Windows Taskbar. These functions allow you to add icons to the Taskbar's tray, add balloon text, menu option and also allow you to prevent your application (icon) from appearing on the taskbar.

Functions supplied

WinTaskbarAddIcon
WinTaskbarChangeIcon
WinTaskbarRemoveIcon
WinNotOnTaskbar
ds_WinTaskbarBalloon
 

For a detailed description of each of the functions, see the reference section.

Template Supplied

An Extension template has been provided to add an icon to the tray. This icon will automatically be put in the tray when the window is opened, and automatically removed when the window is closed. You can also use the functions in hand code to add, change and remove icons at will.

If you place an Icon in the tray, then you will also probably want to capture mouse events when the user interacts with this icon. In WinEvent this is done automatically for you. The template also takes care of all the details - there are embed points so you can add your code for the event, and there are buttons on the AddIcon template to easily get to those embed points.

Tip: Use the Mouse Right Up embed point for opening a Pop-up menu.

Note : The message is ultimately processed by the Accept command. If your program spends a long time processing between calls to the Accept loop then you may notice a delay between clicking on the Icon, and the execution of your embedded code. For better responses make sure your program frequently returns to the Accept command.

Note: If you have hand-coded handling these events then you should be aware that the method has changed and your old code will no longer work. In the past the event came through as WinMessageEvent. This has been changed - the mouse events are now separated and come through as WinMessageEvent+500+x where x is 512 (mouse move) or 513(mouse left down) or 514(mouse left up) or 515(double left click) or 516(mouse right down) or 517(mouse right up).

Window Behavior Functions

Functions Supplied

WinOnTop
WinNotOnTop
WinBringToFront
ds_WinTransparent
ds_VisibleOnDesktop
ds_ShowWindow
ds_HideWindow
 

For a detailed description of each of the functions, see the reference section.
 

Windows System Functions

Functions Supplied

ds_GetWinVersion
WindowsVersion
WindowsRelease
DosVersion
DosRelease
Sound
GetWindowsDir
GetSystemWindowsDir
ScreenWidth
ScreenHeight
ScreenDepth
ds_GetScreenDPI

For a detailed description of each of the functions, see the reference section.

 

RAM & Disk Functions

Functions Supplied

GetFreeDiskSpace
GetDiskSpace
ds_GetDiskMegs
ds_Memory  
 

For a detailed description of each of the functions, see the reference section.

 

Time & Date Functions

Functions Supplied

ds_FastClock
ds_FormatFastTime
ds_Timer
ds_Sleep
ds_WeekDay
ds_ReadCPUTimeStamp
 

For a detailed description of each of the functions, see the reference section.
 

File Functions

Functions Supplied

ds_DeleteFile
ds_GetFileDirEntry
ds_SetFileAttributes
ds_CreateDirectory
ds_RemoveDirectory
ds_SetFileDateTime
ds_MoveFile
ds_GetFolderPath
ds_GetTempPath
ds_String2File
ds_File2String
ds_GetHModule
ds_GetHIcon
ds_CreateShortcut
ds_GetFileVersionInfo

 

For a detailed description of each of the functions, see the reference section.
 

Process & Thread Functions

Functions Supplied

ds_GetCurrentProcess
ds_GetCurrentThread
ds_GetProcessTime
ds_GetThreadTime
ds_SetRealTimePriority

 

For a detailed description of each of the functions, see the reference section.
 

DLL Functions

Functions Supplied

        ds_LoadDLLProc
        ds_UnloadDLLProc
        ds_GetDLLVersion

For a detailed description of each of the functions, see the reference section.
 

SMS Functions

Functions Supplied

        ds_GSMSendSMS
        ds_GSMEnterPin
        ds_GSMEchoOFF
        ds_GSMSetSMSTextmode
        ds_GetGSMReply
        ds_EmptyPort
        ds_GSMReadSMSInit
        ds_GSMReadSMS
        ds_GSMDeleteSMS
        ds_GSMSetSMSReporting
        ds_GSMSelectSR
        ds_GSMReadSMSReportInit
        ds_GSMReadSMSReport
        ds_GSMDeleteSMSReport
        ds_GSMReadEvents
        ds_GSMSetEvents
        ds_GSMReset
       
       
        For a detailed description of each of the functions, see the reference section.


 

Debugging & Error Reporting Functions

Functions Supplied

        ds_Debug
        ds_WineventDebug
        ds_ViewDebug
        ds_ViewDebugClose
        ds_Error
        ds_ErrorCode
        ds_ErrorReset
        ds_SaveStack
        ds_TestStack
       

For a detailed description of each of the functions, see the reference section.
 

Auto Shut-down Functions

When you select Auto-Shutdown on your Global WinEvent Extension two callback functions MyOKToEndSessionHandler &  MyEndSessionHandler are added to your app.  These appear in your Global Embeds list as :
Winevent MyOKToEndSessionHandler
Winevent MyEndSessionHandler

Use MyOKToEndSessionHandler to tell windows whether it is OK to shut down now.  Set the return value variable OKToEndSession to FALSE if you do not what to allow shutdown now.

If you have given the go ahead to shutdown and no other program has refused then MyEndSessionHandler will be called before windows ends this application.  This is for you to save any settings etc.  Please note that windows ends all your app threads without allowing then to execute the closing window code you may have written.  This is your only chance to execute code. 

If either your MyEndSessionHandler or MyOKToEndSessionHandler code takes longer than 3 seconds to execute then windows (XP 2K etc) pops up a "Ending Application" window which gives you about 15 seconds.
 

Functions Supplied

        ds_SetOKToEndSessionHandler
        ds_SetEndSessionHandler
        ds_SetNoEndSession
         

For a detailed description of each of the functions, see the reference section.
 

Other Functions

Functions Supplied

        ds_FormatHex
        ds_SetClipboard
        ds_ShutDown
        ds_WineventVersion
        ds_Ulong64ToReal
             

For a detailed description of each of the functions, see the reference section.
 

Reference Guide

WinAlert functions

WinAlert
Winevent
WinControl
WinParam1
WinParam2
WinChangeUserEvent
WinSysEvent
WinSysParam1
WinSysParam2
WinWtsEvent
WinWtsID

 

Comms Functions

NewPort
ResetPort
ClosePort
KillAllPorts
WritePort
ReadPort
SetHandShake
CtsHigh
DsrHigh
RingHigh
CdHigh
SetRts  
SetDtr  

 

Taskbar Functions

WinTaskBarAddIcon
WinTaskBarRemoveIcon
WinTaskBarChangeIcon
WinNotOnTaskBar
ds_WinTaskbarBalloon

Window Behaviour Functions

WinOnTop
WinNotOnTop
WinBringToFront
ds_WinTransparent
ds_VisibleOnDesktop

ds_ShowWindow

ds_HideWindow
 

Windows System Functions

ds_GetWinVersion
WindowsVersion
WindowsRelease
DosVersion
DosRelease
GetFreeDiskSpace
GetDiskSpace  
Sound
GetWindowsDir
GetSystemWindowsDir
ScreenWidth
ScreenHeight
ScreenDepth
ds_GetScreenDPI

Time & Date Functions

          ds_FastClock
          ds_FormatFastTime
          ds_Timer
          ds_Sleep
          ds_WeekDay

File Functions

        ds_DeleteFile
        ds_GetFileDirEntry
        ds_SetFileAttributes
        ds_CreateDirectory
        ds_RemoveDirectory
        ds_SetFileDateTime
        ds_MoveFile
        ds_GetFolderPath
        ds_GetTempPath
        ds_String2File
        ds_File2String
        ds_GetHModule
        ds_GetHIcon
        ds_CreateShortcut
        ds_GetFileVersionInfo

 

DLL Functions

        ds_LoadDLLProc
        ds_UnloadDLLProc

SMS Functions

        ds_GSMSendSMS
        ds_GSMEnterPin
        ds_GSMEchoOFF
        ds_GSMSetSMSTextmode
        ds_GetGSMReply
        ds_EmptyPort
        ds_GSMReadSMSInit
        ds_GSMReadSMS
        ds_GSMDeleteSMS
        ds_GSMSetSMSReporting
        ds_GSMSelectSR
        ds_GSMReadSMSReportInit
        ds_GSMReadSMSReport
        ds_GSMDeleteSMSReport
        ds_GSMReadEvents
        ds_GSMSetEvents
        ds_GSMReset
       
       
 

Debugging & Error Reporting Functions

        ds_Debug
        ds_WineventDebug
        ds_ViewDebug
        ds_ViewDebugClose
        ds_Error
        ds_ErrorCode
        ds_ErrorReset
        ds_SaveStack
        ds_TestStack
       

WinAlert(<FromMessage>, <ToMessage>, <Action> )

Parameters

Purpose

Complication

Returns

Example

See Also

Winevent(), WinControl(), WinParam1(), WinParam2()

Parameters

Purpose

Complication

Returns

Example

See Also

WinChangeUserEvent (WinMessageEvent)

Parameters

Purpose

Returns

Example

WinSysEvent(byte pClearAfterRead=0), WinSysParam1(), WinSysParam2()

Parameters

Purpose

Returns

Example

WinAlert : For alerting windows messages
WinEvent : For handling standard windows messages.
WinWtsEvent : For handling the wm_WTSSESSION_CHANGE windows message.
 

WinWtsEvent(byte pClearAfterRead=0), WinWtsID()

Parameters

Purpose

Returns

Value	Meaning
WTS_CONSOLE_CONNECT 0x1	A session was connected to the console session.
WTS_CONSOLE_DISCONNECT 0x2	A session was disconnected from the console session.
WTS_REMOTE_CONNECT 0x3	A session was connected to the remote session.
WTS_REMOTE_DISCONNECT 0x4	A session was disconnected from the remote session.
WTS_SESSION_LOGON 0x5	A user has logged on to the session.
WTS_SESSION_LOGOFF 0x6	A user has logged off the session.
WTS_SESSION_LOCK 0x7	A session has been locked.
WTS_SESSION_UNLOCK 0x8	A session has been unlocked.
WTS_SESSION_REMOTE_CONTROL 0x9	A session has changed its remote controlled status. To determine the status, call GetSystemMetrics and check the SM_REMOTECONTROL metric.

Example

WinAlert : For alerting windows messages
WinEvent : For handling standard windows messages.
WinSysEvent : For handling the wm_SYSCOMMAND windows message.
 

NewPort (string pmode, <long pInb>, <long pOutb>,byte pUseEvents=0)

Purpose

Parameters

mode ( string ) : This is a mode string such as would be accepted by the Dos MODE
command.

in buffer size (long) ( optional parameter - default 512 bytes )
out buffer size (long) ( optional parameter - default 512 bytes )
These are the sizes Windows must use for the In and Out buffers.

pUseEvents (byte) (optional parameter - default = 0)
When set (TRUE) the current window will receive com events.

  Comms transmit buffer empty event = WinEventMessage + 5601

  Comms characters received = WinEventMessage + 5602

  Comms handshaking lines changed = WinEventMessage + 5602

Returns : Long
<0 if an error has occurred. Otherwise a port number used by readport and writeport.

Examples

ResetPort (mode string)

Purpose

Parameters

Returns : long

Example

ClosePort (PortId long)

Purpose

Parameters

Returns : long

Example

KillAllPorts ( )

Purpose

Returns

Example

WritePort (PortId long, String string, Length long)

Purpose

Parameters

Returns : long

Example

ReadPort (PortId long, String string, Length long)

Purpose

Parameters

Returns : long

Example

SetHandShake (PortId long, HandShake long)

Purpose

Parameters

Returns : long

Example

CtsHigh (Pid Long)

Purpose

Parameters

Returns

Example

DsrHigh (Pid Long)

Purpose

Parameters

Returns

Example

RingHigh (Pid Long)

Purpose

Parameters

Returns

Example

CdHigh (Pid Long)

Purpose

Parameters

Returns

Example

SetRts (Pid Long, Value Long)

Purpose

Parameters

Returns

Example

SetDtr (Pid Long, Value Long)

Purpose

Parameters

Returns

Example

WinTaskbarAddIcon(IconName String,< Tips String>),long

Purpose

Parameters

Returns : long

Example

WinTaskbarRemoveIcon(<Id longt>)

Purpose

Parameters

Returns

Example

WinTaskbarChangeIcon(<Id long>, IconName string,<Tips string>)

Purpose

Parameters

Returns

Example

ds_WinTaskbarBalloon(<ulong pID>,string pText,<string pTitle>,uLong pFlags=1,ulong pTimeout=1500)

Purpose

Parameters

pText (string) : The balloon text.  If no balloon text is supplied then any open balloon is closed. Embedding '<13,10>' in the text produces multiline text.

pTitle (string) : Optional.  The balloon title. Icons only appear if the title is supplied.

pFlags (uLong) : Optional.  Default = 1 (An information icon).

NIIF_ERROR EQUATE(003h) An error icon.
NIIF_INFO EQUATE(001h) An information icon. (Default)
NIIF_NONE EQUATE(000h) No icon.
NIIF_WARNING EQUATE(002h) A warning icon.
NIIF_NOSOUND EQUATE(010h) XP only. Do not play the associated sound.

pTimeout (ulong) : Optional.  Default=1500 (15 seconds). Balloon minimum display time in 100ths of a second. (clarion time)

Returns

Example

WinNotOnTaskbar()

Purpose

To hide the window
    window{prop:iconize} = TRUE
    window{prop:hide} = TRUE

To unhide the window
    window{prop:hide} = FALSE
    window{prop:iconize} = FALSE

Note that the order of the hide / iconize commands is important

Parameters

Returns

Example

WinOnTop()

Purpose

Parameters

Returns

Example 1

Example 2

WinNotOnTop()

Purpose

Parameters

Returns

Example 1

WinBringToFront()

Purpose

Parameters

Returns

Example

ds_ShowWindow(byte pGrabFocus=1)

Purpose

Parameters

pGrabFocus (byte) : Optional.  Defaults to TRUE.  When set you window takes focus and so keyboard input goes to your window.

Returns

Example

ds_HideWindow

Purpose

Parameters

None.

Returns

Example

ds_WinTransparent(long Transparency)

Purpose

Parameters

Returns

Example

ds_VisibleOnDesktop(<*long pWinX>,<*long pWinY>,<*long pWinWidth>,<*long pWinHeight>,long pMode=1)

Purpose

Parameters

pWinY (*long) : Optional.  If omitted then the current target window is used.  If supplied then the variable is updated.

pWinWidth (*long) : Optional.  If omitted then the current target window is used.  If supplied then the variable is updated.

pWinHeight (*long) : Optional.  If omitted then the current target window is used.  If supplied then the variable is updated.

pMode (long) : Optional.  Default=1  When set this flags that the window must not be obscured by the taskbar.

Returns

Example

ds_GetWinVersion()

Purpose

Parameters

Returns

Win XXX ...............

Example

WindowsVersion()

Purpose

Parameters

Returns

Example

WindowsRelease()

Purpose

Parameters

Returns

Example

DosVersion()

Purpose

Parameters

Returns

Example

DosRelease()

Purpose

Parameters

Returns

Example

GetFreeDiskSpace (<drive long>)

Purpose

Parameters

Returns

Example

GetDiskSpace (<drive long>)

Purpose

Parameters

Returns

Example

ds_GetDiskMegs (<string pDrive>,<string pSelector>)

Purpose

Parameters

pSelector (string) : Optional.  Defaults to 'USER FREE'  This modifies the returned disk size.

'USER FREE'       Returns the free disk space available to the current user.
'TOTAL'                Returns the total disk size.
'TOTAL FREE'      Returns the free disk space on the drive.

Returns

Example

ds_Memory(<string pSelector>)

Purpose

Parameters

pSelector (string) : Optional.  Defaults to 'USER'  This specifies which RAM size is returned.

'USER'                    Returns the virtual memory used by this application. 
'SWAP USED'        Returns the page file used kBytes.
'SWAP FREE'        Returns the page file free kBytes.
'SWAP TOTAL'       Returns the page file total kBytes.
'RAM USED'           Returns the physical RAM used kBytes.
'RAM FREE'           Returns the physical RAM free kBytes.
'RAM TOTAL'          Returns the physical RAM total kBytes.
'VMEM USED'        Returns the virtual memory used kBytes.
'VMEM FREE'        Returns the virtual memory free kBytes.
'VMEM TOTAL'       Returns the virtual memory total kBytes.

Returns

Example

Sound (WavFileName String)

Purpose

Parameters

Returns

Example

GetWindowsDir ()

Purpose

Parameters

Returns

Example

GetSystemDir ()

Purpose

Parameters

Returns

Example

ScreenWidth ()

Purpose

Parameters

Returns

Example

ScreenHeight ()

Purpose

Parameters

Returns

Example

ScreenDepth ()

Purpose

Parameters

Returns

Example

ds_GetScreenDPI (byte pDPIY=0)

Purpose

Parameters

Returns

Example

ds_FastClock(byte UseCPUTimeStamp=0,byte ReSyncTime)

Purpose

Parameters

UseCPUTimeStamp (byte) : Optional, Default = FALSE.  If set then the ds_ReadCPUTimeStamp() function is used to return the time down to a resolution of the CPU clock.  (1 GHz = 1ns resolution)

ReSyncTime (byte) : Optional, Default = FALSE.  Use (once) when time has been adjusted and so ds_FastClock <> Clock().

Returns

Example

ds_FormatFastTime(real pFastTime,<long pDecimalPlaces>)

Purpose

Parameters

pFastTime (real) : The time in 100 ths of a second (clarion time).

pDecimalPlaces (long) : Optional.  The number of decimal places to display.

Returns

Example

ds_Sleep(real pFastTime)

Purpose

Parameters

pFastTime (real) : The time in 100 ths of a second (clarion time) for which to sleep.
 

Returns

Example

ds_Timer(long pTimerNumber,<real pFastTime>)

Purpose

Parameters

pTimerNumber (long) : Used to specify multiple timers (per thread)

pFastTime (real) : The time in 100 ths of a second (clarion time).

Returns

Example

ds_WeekDay(long pDate,<byte pShortFormatFlag>)

Purpose

Parameters

pDate (long) : The date for which the week day is required.  (Clarion date)

pShortFormatFlag (byte) : Optional.  If TRUE(1) then the short name for the day is returned.  "Wednesday" would return as "Wed"

Returns

Example

ds_ReadCPUTimeStamp(*real pSaveReal)

Purpose

Parameters

pSaveREal (*real) : The 64 bit number returned by the CPU is saved into this real.  Will overflow after 52 bits.  (50 days at 1GHz)

Returns

Example

ds_ReadCPUTimeStampDelta(*real pSaveReal)

Purpose

Parameters

pSaveREal (*real) : The 64 bit number returned by the CPU is saved into this real.  Will overflow after 52 bits.  (50 days at 1GHz)

Returns

Example

ds_DeleteFile(string pFileName)

Purpose

pFileName (string) : Specify the file (with path) to delete.
 

Returns

Example

  code
 ds_DeleteFile('c:\FileName.ext')
 

ds_GetFileDirEntry(string pFileName,*string pEntryG)

Purpose

Parameters

pFileName (string) : Specify the file (with path) for which the directory entry data is required.

pEntryG (*string) : Provide the lable of an EntryG structure.  See example below.

Returns

Example

EntryG    group,PRE(EntryG)
name        STRING(256)
shortname   string(13)
date        LONG
time        LONG
size        LONG
attrib      BYTE
          end

  code
  ds_GetFileDirEntry('c:\FileName.ext',EntryG) ! fills the EntryG with the files directory attributes.
 

ds_SetFileAttributes(string pFileName,byte pNewAttribs)

Purpose

Parameters

pFileName (string) : Specify the file (with path) for which the directory entry data is required.

pNewFileAttribs (byte) : Specify the new attributes.

ff_:NORMAL EQUATE(0) !Always active
ff_:READONLY EQUATE(1) !Not for use as attributes parameter
ff_:HIDDEN EQUATE(2)
ff_:SYSTEM EQUATE(4)
ff_:DIRECTORY EQUATE(10H)
ff_:ARCHIVE EQUATE(20H) ! NOT Win95 compatible


Returns

Example

  code
 ds_SetFileAttributes('c:\FileName.ext',0) ! clears files attributes.
 

ds_CreateDirectory(string pNewDirectoryName)

Purpose

Parameters

pNewDirectoryName (string) : Specify the name (including path) of the new directory to create.

Returns

Example

  code
 ds_CreateDirectory('c:\My New Directory') ! creates the directory
 

ds_RemoveDirectory(string pDirectoryName)

Purpose

Parameters

pDirectoryName (string) : Specify the name (including path) of the directory to remove.

Returns

Example

  code
 ds_RemoveDirectory('c:\My New Directory') ! removes any empty directory.
 

ds_SetFileDateTime(string pFileName,long pNewDate,long pNewTime)

Purpose

pFileName (string) : Specify the file (with path) for which the directory is to be modified.

pNewDate (long) : New date (clarion date) for the file.

pNewTime (long) : New time (clarion time) for the file.

Returns

Example

  code
 ds_SetFileDateTime('c:\MyFile.txt',today(),clock()) ! Sets the files date and time to now.
 

ds_MoveFile(string pFileName,string pNewFileName)

Purpose

pFileName (string) : Specify the file (with path) to be moved.

pNewFileName (string) : Specify the new file (with new path).

Returns

Example

  code
 ds_MoveFile('c:\MyFile.txt','c:\NewDirectory\NewFileName.ext') ! moves and renames the file to the directory.
 

ds_GetFolderPath(long pCSIDL,<byte pCreateFlag>)

Purpose

pCSIDL (long) : A CSIDL equate specifying the windows folder.

pCreateFlag (byte) : Optional.  If TRUE (1) then the folder will be created if it does not exist.

CSIDL_DESKTOP equate(000h) ! C:\Documents and Settings\username\Desktop
CSIDL_PROGRAMS equate(002h) ! C:\Documents and Settings\username\Start Menu\Programs
CSIDL_PERSONAL equate(005h) ! C:\Documents and Settings\username\My Documents
CSIDL_FAVORITES equate(006h) ! C:\Documents and Settings\username\Favorites
CSIDL_STARTUP equate(007h) ! C:\Documents and Settings\username\Start Menu\Programs\Startup
CSIDL_RECENT equate(008h) ! C:\Documents and Settings\username\My Recent Documents
CSIDL_SENDTO equate(009h) ! C:\Documents and Settings\username\SendTo
CSIDL_STARTMENU equate(00Bh) ! C:\Documents and Settings\username\Start Menu
CSIDL_MYMUSIC equate(00Dh) ! C:\Documents and Settings\username\My Documents\My Music
CSIDL_DESKTOPDIRECTORY equate(010h) ! C:\Documents and Settings\username\Desktop
CSIDL_NETHOOD equate(013h) ! C:\Documents and Settings\username\NetHood
CSIDL_FONTS equate(014h) ! C:\Windows\Fonts
CSIDL_TEMPLATES equate(015h) ! C:\Documents and Settings\username\Templates
CSIDL_COMMON_STARTMENU equate(016h) !*C:\Documents and Settings\All Users\Start Menu
CSIDL_COMMON_PROGRAMS equate(017h) ! C:\Documents and Settings\All Users\Start Menu\Programs
CSIDL_COMMON_STARTUP equate(018h) !*C:\Documents and Settings\All Users\Start Menu\Programs\Startup
CSIDL_COMMON_DESKTOPDIRECTORY equate(019h) !*C:\Documents and Settings\All Users\Desktop
CSIDL_APPDATA equate(01Ah) ! C:\Documents and Settings\username\Application Data
CSIDL_PRINTHOOD equate(01Bh) ! C:\Documents and Settings\username\PrintHood
CSIDL_LOCAL_APPDATA equate(01Ch) ! C:\Documents and Settings\username\Local Settings\Application Data
CSIDL_ALTSTARTUP equate(01Dh) !*
CSIDL_COMMON_ALTSTARTUP equate(01Eh) !*
CSIDL_COMMON_FAVORITES equate(01Fh) !*C:\Documents and Settings\All Users\Favorites
CSIDL_INTERNET_CACHE equate(020h) ! C:\Documents and Settings\username\Local Settings\Temporary Internet Files
CSIDL_COOKIES equate(021h) ! C:\Documents and Settings\username\Cookies
CSIDL_HISTORY equate(022h) ! C:\Documents and Settings\username\Local Settings\History
CSIDL_COMMON_APPDATA equate(023h) ! C:\Documents and Settings\All Users\Application Data
CSIDL_WINDOWS equate(024h) ! C:\Windows
CSIDL_SYSTEM equate(025h) ! C:\Windows\System32
CSIDL_PROGRAM_FILES equate(026h) ! C:\Program Files
CSIDL_MYPICTURES equate(027h) ! C:\Documents and Settings\username\My Documents\My Pictures
CSIDL_PROFILE equate(028h) !*C:\Documents and Settings\username
CSIDL_PROGRAM_FILES_COMMON equate(02Bh) !#C:\Program Files\Common
CSIDL_COMMON_TEMPLATES equate(02Dh) !*C:\Documents and Settings\All Users\Templates
CSIDL_COMMON_DOCUMENTS equate(02Eh) ! C:\Documents and Settings\All Users\Documents
CSIDL_COMMON_ADMINTOOLS equate(02Fh) ! C:\Documents and Settings\All Users\Start Menu\Programs\Administrative Tools
CSIDL_ADMINTOOLS equate(030h) ! C:\Documents and Settings\username\Start Menu\Programs\Administrative Tools
CSIDL_COMMON_MUSIC equate(035h) !*C:\Documents and Settings\All Users\Documents\My Music
CSIDL_COMMON_PICTURES equate(036h) !*C:\Documents and Settings\All Users\Documents\My Pictures
CSIDL_CDBURN_AREA equate(03Bh) !*C:\Documents and Settings\username\Local Settings\Application Data\Microsoft\CD Burning
 

Returns

Example

  code
 DisplayPath = ds_GetFolderPath(CSIDL_PROGRAMS,1) ! C:\Documents and Settings\username\Start Menu\Programs


 

ds_GetTempPath()

Purpose

None.

Returns

Example

  code
 DisplayPath = ds_GetTempPath() ! C:\WINDOWS\TMP
 

ds_String2File(string pWriteString,<long pWriteLen>,string pFileName)

Purpose

pWriteString (string) : String to be written to file.

pWriteLen (long) : Optional.  The length of the string to be written to file.  If omitted then the string is clipped before writing to file.

pFileName (string) : The name of the file (including path).

Returns

Example

  code
 if ds_String2File('Just Testing',,'C:\MyTestFile.TXT') ! Creates / empties file and then writes data to file.
    message('ds_string2file failed : ' & ds_error())
  end

ds_File2String(ds_StringRef pStringRef,<long pMaxLen>,string pFileName)

Purpose

pStringRef (ds_StringRef) : The label of a ds_StringRef structure.

pMaxLen (long) : Optional.  The max length of the string to be returned.  File contents truncated at this length if required.

pFileName (string) : The name of the file (including path).

Returns

Example

TestFileRead   GROUP(ds_StringRef)
                      END

  code
  if ds_string2file('testing 123...',,'c:\testing.txt')
    message('ds_string2file failed : ' & ds_error())
  end

  if ds_file2string(TestFileRead,,'c:\testing.txt')
    message('ds_file2string failed : ' & ds_error())
  else
    DisplayString = TestFileRead.bin ! string read from file.
    DisplayLength = TestFileRead.len ! Length of string read from file.
  end
 

ds_GetHModule (<string pModuleName>)

Purpose

Parameters

Returns

Example

ds_GetHIcon(string pIconName,<ulong pHIconModule>,<long pIconSize>),ds_DestroyIcon()

Purpose

Parameters

pIconName (string) : The name of the icon file or icon resource.  Compiled-in icon names must be prefixed with '~'.

pHIconModule (ulong) : Optional.  A handle to the module containing the icon.

pIconSize (long) : Optional. The size required.  Usually 16X16, 32X32 or 48X48.  Defaults to 16X16 if it exists.

Returns

Example

ds_CreateShortcut (string pTargetFile,<string pIconName>,long pIconIndex=0,string pDescription,long pHotKey=0,string pStartIn,string pShortCut,<string pShortCutPath>)

Purpose

Parameters

pTargetFile (string) : The file, including the path, to which a shortcut must be made. 
Example  C:\WINDOWS\SYSTEM32\CALC.EXE

pIconName (<string>) : The file, including the path, which contains the icon to be used with this shortcut.  If omitted then the first icon in the pTargetFile is used.

pIconIndex (long) : The index of the icon within the pIconName file to use.  If omitted then the first icon is used.

pDescription (string) : The tip which will appear if the cursor is held over the shortcut.

pHotKey (long) : The hot key to run the shortcut.  Omit or use ZERO if not required. 
Example CTRLALTC

pStartIn (string) : The path to the directory in which the file must be run / opened.

pShortCut (string) : The name for the shortcut.
Example 'Calculator.LNK'

pShortCutPath (<string >) : The destination where the shortcut must be placed.  If omitted then defaults to the desktop. 
Example C:\Documents and Settings\Derek\Desktop
 

Returns

Example

ds_GetFileVersionInfo(<string pDescription>,<*string pFileName>)

Purpose

pDescription (string) : Default='FileVersion'  The name version data required.

Standard descriptions are as follows:

pFileName (*string) : Default=Current Module.  The name including path of the file from which version data is required.

Returns

Example

  code
  DisplayInfo = ds_GetFileVersionInfo()  ! returns FileVersion by default.
 

ds_LoadDLLProc(string pProcName,string pLibName,*ulong pProcAddress,<*ulong pLibInstance>)

Purpose

pProcName (string) : The name of the DLL procedure.  This procedures call address will be returned.

pLibName (string) : The name of the DLL to load.

pProcAddress (ulong) : The call address of the DLL procedure is saved here.  Subsequent calls to ds_LoadDLLProc will simply return if this is already set.

pLibInstance (ulong) : Optional.  This is used by ds_UnloadDLLProc to unload the DLL if it is no longer required.

Windows will unload the DLL when your application quits and so this is not required.

Returns

Example

"Inside global map" - Global embed point
  module('windows')
    WC_GetDiskFreeSpaceEx(ulong,*dlong,*dlong,*dlong), byte, raw, pascal, Dll(_fp_)       ! The Dll(_fp_) tells the compiler not to link in this function.
  end

"Global Data" - Global embed point
fp_GetDiskFreeSpaceEx     ulong,static,name('WC_GetDiskFreeSpaceEx')

  code
  if ~ds_LoadDLLProc('GetDiskFreeSpaceExA','kernel32',fp_GetDiskFreeSpaceEx)
    result = WC_GetDiskFreeSpaceEx(0,dlongUserFree,dlongTotal,dlongTotalFree)
     ...
  else
    ! lib or function not found
    message('ds_LoadDLLProc failed : ' & ds_Error())
  end
 

ds_UnloadDLLProc(*ulong pProcAddress,ulong pLibInstance)

Purpose

Parameters

pProcAddress (ulong) : The call address of the DLL procedure will be reset.  This will force a subsequent call to ds_LoadDLLProc to reload the DLL.

pLibInstance (ulong) : This must be set by ds_LoadDLLProc.

Returns

Example

"Inside global map" - Global embed point
  module('windows')
    WC_GetDiskFreeSpaceEx(ulong,*dlong,*dlong,*dlong), byte, raw, pascal, Dll(_fp_)       ! The Dll(_fp_) tells the compiler not to link in this function.
  end

"Global Data" - Global embed point
fp_GetDiskFreeSpaceEx     ulong,static,name('WC_GetDiskFreeSpaceEx')
LibInstance                         ulong,static

  code
  if ~ds_LoadDLLProc('GetDiskFreeSpaceExA','kernel32',fp_GetDiskFreeSpaceEx,LibInstance)
    result = WC_GetDiskFreeSpaceEx(0,dlongUserFree,dlongTotal,dlongTotalFree)
     ...
  else
    ! lib or function not found
    message('ds_LoadDLLProc failed : ' & ds_Error())
  end
  .....
  if ds_UnloadDLLProc(fp_GetDiskFreeSpaceEx,LibInstance) ! Unload DLL as no longer required
    message('ds_UnloadDLLProc failed : ' & ds_Error())
  end
 

ds_GetDLLVersion(string pDLLName,*ds_DLLVersionG pDLLVerInf)

Purpose

pDLLName (string) : The name of the DLL from which version info is required.

pDLLVerInf (*ds_DLLVersionG) : This structure is filled with the version info.

Returns

Example

DLLVerInf group(ds_DLLVersionG) .

  code
  if ~ds_GetDLLVersion('shell32.dll',DLLVerInf)
    ! ds_DLLVersionG group
    !   MajorVersion ulong
    !   MinorVersion ulong
    !   BuildNumber ulong
    !   PlatformID ulong
    !   String string(30)
    ! end

    if DLLVerInf.MajorVersion > 4
       ! Taskbar balloons supported under shell version 5 and higher.
    else
       ! Taskbar balloons not supported.
    end
  end

ds_GSMSendSMS(long pPID,string pSMSText,string pSMSPhoneNumber,<string pPIN>,<*long pSMSID>)

Purpose

Note : Uses ds_Timer(999).

ds_GSMSendSMS calls the following 4 procedures:

ds_GSMEchoOFF(pPID)
ds_GSMEnterPin(pPID,pPIN)
ds_GSMSetSMSTextmode(pPID)
ds_GSMGetReply...


Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pSMSText (string) : The SMS text string to send. Example 'Please call me.  I am low on airtime :)'

pSMSPhoneNumber (string) : The mobile number to send the SMS to.

pPIN (string) : Optional. The PIN number to gain access to the SIM card in the GSM modem.

The PIN code request on the SIM card may be disabled.  In this case the PIN is not required.
NB : If you try the wrong PIN code 3 times then your SIM may be locked and will need the PUK number to unlock it.  This is not handled by WinEvent.

pSMSID (*long) : Optional. Most GSM modems return an SMS identifier that may be used with the SMS delivery report to identify which SMS was delivered.

Returns

Example

PID        long
SMSID    long

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMSendSMS(PID,'Hello There','08XXXXXXXXX','1234',SMSID)
    message = ds_Error()
  else
    message = 'Send Succeeded, SMSID=' & SMSID1
  end
 

ds_GSMEnterPin(long pPID,string pPIN)

Purpose

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pPIN (string) : The PIN number to gain access to the SIM card in the GSM modem.

The PIN code request on the SIM card may be disabled.  In this case ds_GSMEnterPin will return 0 (Success).
NB : If you try the wrong PIN code 3 times then your SIM may be locked and will need the PUK number to unlock it.  This is not handled by WinEvent.

Returns

Example

PID        long
 

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMEchoOFF(PID)
    message('ds_GSMEchoOFF failed : ' & ds_Error())
  elsif ds_GSMEnterPIN(PID,PIN)
    message('ds_GSMEnterPIN failed : ' & ds_Error())
  else
    message('PIN OK')
  end
 

ds_GSMEchoOFF(long pPID)

Purpose

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

Returns

Example

PID        long
 

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMEchoOFF(PID)
    message('ds_GSMEchoOFF failed : ' & ds_Error())
  else
    message('ECHO OFF')
  end
 

ds_GSMSetSMSTextmode(long pPID)

Purpose

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

Returns

Example

PID        long
 

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMEchoOFF(PID)
    message('ds_GSMEchoOFF failed : ' & ds_Error())
  elsif ds_GSMSetSMSTextmode(PID)
    message('ds_GSMSetSMSTextmode failed : ' & ds_Error())
  else
    message('ds_GSMSetSMSTextmode OK')
  end

ds_GetGSMReply(long pPID,string pCMD,long pCmdLen=0,*string pReplyString,long pTimeout=25,long pTimeout2=25,byte pTrailingOK=FALSE,byte pFindPrompt=FALSE,byte pIgnorePrompt=FALSE)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pCMD (string) : The command to send to the modem. 

Tip : Most modems require a CR / LF terminator on the command ie. 'AT+CPIN?<13,10>' where ascii 13 is CR and ascii 10 is LF.

pCmdLen (long) : Optional.  This is the command string length to send.  If omitted then the string is clipped before sending.

pReplyString (*string) : The modem response is returned in this string.

pTimeout (long) : Optional.  Default =25 (0.25 secs).  This is the timeout for the first character of the modem response.

pTimeout2 (long) : Optional.  Default =25 (0.25 secs).  This is the timeout for subsequent characters of the modem response.

pTrailingOK (byte) : Optional.  Default=FALSE.  This flag when set specifies that the modem response terminates with an '<13,10>OK<13,10>' . 

If not set then the first '<13,10>'  will be taken as the end of the modem response.

pFindPrompt (byte) : Optional.  Default=FALSE. This flag when set specifies that the modem response terminates with an '> ' .

pIgnorePrompt (byte) : Optional.  Default=FALSE. This flag when set then leading '> ' characters in the modem response are discarded.

Returns

Example

PID        long
ReplyString    string(1024)

  code
  PID = NewPort('com1:9600,n,8,1')
  ds_GetGSMReply(PID,'AT+CPIN?<13,10>',,ReplyString,,,1) ! Query +CPIN state and waits for OK response.
  ds_GetGSMReply(PID,'AT+CMGS="082XXXXXX"<13,10>',,ReplyString,1000,,,1) ! Dials Mobile Number and waits for "> " response.

 

ds_EmptyPort(long pPID,long pTimeout=50)

Purpose

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pTimeout (long) : Optional.  Default =50 (0.5 secs).  This is the timeout for attempting to empty the com port input buffer.

Returns

Example

PID        long
 

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_ds_EmptyPort(PID)
    message('ds_EmptyPort failed : ' & ds_Error())
  else
    message('ds_EmptyPort OK')
  end

ds_GSMReadSMSInit(long pPID,string pPIN)

Purpose

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pPIN (string) : Optional. The PIN number to gain access to the SIM card in the GSM modem.

The PIN code request on the SIM card may be disabled.  In this case the PIN is not required.
NB : If you try the wrong PIN code 3 times then your SIM may be locked and will need the PUK number to unlock it.  This is not handled by WinEvent.

Returns

Example

PID        long
 

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMReadSMSInit(PID)
    message('ds_GSMReadSMSInit failed : ' & ds_Error())
  else
    message('ds_GSMReadSMSInit OK')
  end

ds_GSMReadSMS(long pPID,long pSMSIndex,*ds_SMSMessageG pSMSG)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pSMSIndex (long) : Which memory index to read.

pSMSG (*ds_SMSMessageG) : This structure is filled with the data from the memory index.

Returns

Example

PID        long
SMSIndex  long

SMSG    group(ds_SMSMessageG)
              end

  code
  SMSIndex = 0
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMReadSMSInit(PID,PIN)
    message('ds_GSMReadSMSInit failed : ' & ds_Error())
  else
    loop
      SMSIndex += 1
      if ds_GSMReadSMS(PID,SMSIndex,SMSG) then break .
        ! SMSIndex
        ! ds_SMSMessageG group,type
        !   Type string(20)
        !   MobileNumber string(50)
        !   Date long
        !   Time long
        !   TimeZone long
        !   Text string(255)
        ! end
    end
  end

ds_GSMDeleteSMS(long pPID,long pSMSIndex)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pSMSIndex (long) : Which memory index to clear.

Returns

Example

PID        long

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMDeleteSMS(PID,3) ! delete index 3
    message('ds_GSMDeleteSMS failed : ' & ds_Error())
  else
    message('ds_GSMDeleteSMS OK')
  end

ds_GSMSetSMSReporting(long pPID,byte pEnableReport=1,long pTimeout=1440,<string pPIN>)

Purpose

Note : ds_GSMReadSMSInit calls the following.
ds_GSMEnterPin(PID,PIN)
ds_GSMSetSMSTextmode(PID)
ds_GSMGetReply....  

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pEnableReport (byte) : Optional.  Default=1 (TRUE)  If this flag is reset (0) then the SMS delivery reporting is disabled.

pTimeout (long) : Optional.  Default =1440 minutes (24 Hours).  This is the length of time in minutes that the network must try to send the SMS for before sending a failed report.

The range of the timeout is from 5 minutes to 63 weeks.
if pTimeOut > 43200 ! 30 days
  the resolution is weeks [5 to 63 weeks]
elsif pTimeOut > 1440 ! 1 day
  the resolution is days [2 to 30 days]
elsif pTimeOut > 720 ! 12 hours
    the resolution is 30 minute blocks [12:30 to 24:00]
else ! <= 12 hours
    the resolution is 5 minute blocks [0:05 to 12:00]
end

pPIN (string) : Optional. The PIN number to gain access to the SIM card in the GSM modem.

The PIN code request on the SIM card may be disabled.  In this case the PIN is not required.
NB : If you try the wrong PIN code 3 times then your SIM may be locked and will need the PUK number to unlock it.  This is not handled by WinEvent. Returns

Example

PID        long

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMSetSMSReporting(PID)
    message('ds_GSMSetSMSReporting failed : ' & ds_Error())
  else
    message('ds_GSMSetSMSReporting OK')
  end
 

ds_GSMSelectSR(long pPID,byte pSRMemory=1)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pSRMemory (byte) : Optional.  Default=1 (TRUE)  If this flag is set then the SMS delivery report storage area is selected. 
If this flag is reset then the received SMS storage area is selected.

Returns

Example

PID        long

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMSelectSR(PID)
    message('ds_GSMSelectSR failed : ' & ds_Error())
  else
    message('ds_GSMSelectSR OK')
  end

ds_GSMReadSMSReportInit(long pPID,string pPIN)

Purpose

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pPIN (string) : Optional. The PIN number to gain access to the SIM card in the GSM modem.

The PIN code request on the SIM card may be disabled.  In this case the PIN is not required.
NB : If you try the wrong PIN code 3 times then your SIM may be locked and will need the PUK number to unlock it.  This is not handled by WinEvent.

Returns

Example

PID        long
 

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMReadSMSReportInit(PID)
    message('ds_GSMReadSMSReportInit failed : ' & ds_Error())
  else
    message('ds_GSMReadSMSReportInit OK')
  end

ds_GSMReadSMSReport(long pPID,long pSMSReportIndex,*ds_SMSReportG pDRG)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pSMSReportIndex (long) : Which memory index to read.

pDRG (*ds_SMSReportG) : This structure is filled with the data from the memory index.

Returns

Example

PID        long
SMSReportIndex  long

DRG    group(ds_SMSReportG)
              end

  code
  SMSReportIndex = 0
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMReadSMSReportInit(PID,PIN)
    message('ds_GSMReadSMSReportInit failed : ' & ds_Error())
  else
    loop
      SMSReportIndex += 1
      if ds_GSMReadSMSReport(PID,SMSReportIndex,DRG) then break .
        ! SMSReportIndex
        ! ds_SMSReportG group,type
        !   Type string(20)
        !   SMSID long
        !   MobileNumber string(50)
        !   SentDate long
        !   SentTime long
        !   SentTimeZone long
        !   DeliveredDate long
        !   DeliveredTime long
        !   DeliveredTimeZone long
        !   StatusCode long
        !   Status string(20)
        ! end
    end
  end

ds_GSMDeleteSMSReport(long pPID,long pSMSReportIndex)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pSMSReportIndex (long) : Which memory index to clear.

Returns

Example

PID        long

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMDeleteSMSReport(PID,3) ! delete index 3
    message('ds_GSMDeleteSMSReport failed : ' & ds_Error())
  else
    message('ds_GSMDeleteSMSReport OK')
  end

ds_GSMReadEvents(long pPID,*ds_GSMEventG pERG)

Purpose

Parameters

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pERG (*ds_GSMEventG) : This structure is filled with any event data found.

Returns

Example

PID        long

ERG    group(ds_GSMEventG)
              end

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMReadEvents(PID,ERG)
    message('GSMReadEvents failed : ' & ds_Error())
  else
    ! ds_GSMEventG group,type
    !   Date long
    !   Time long
    !   Text string(255)
    !   Type string(3)
    !   Index long
    ! end 
  end

ds_GSMSetEvents(long pPID,long pEventsMask=255)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

pEventsMask (long) : Optional.  Default=255.  This long selects which events are enabled. 

Returns

Example

PID        long

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMSetEvents(PID)
    message('ds_GSMSetEvents failed : ' & ds_Error())
  else
    message('ds_GSMSetEvents OK')
  end

ds_GSMReset(long pPID)

Purpose

pPID (long) : This is the PortID of the open com port to which the GSM modem is connected.  See the NewPort function.

Returns

Example

PID        long

  code
  PID = NewPort('com1:9600,n,8,1')
  if ds_GSMReset(PID)
    message('ds_GSMReset failed : ' & ds_Error())
  else
    message('ds_GSMReset OK')
  end

ds_Debug(string pDebugString,<string pWindowLabel>,<long pEventNumber>,<long pFieldNumber>)

Purpose

pDebugString (string) : Debug info string.

pWindowLabel (string) : Optional.  This label identifies which procedure is sending the debug info.  The thread number is added to the end of this string.

pEventNumber (long) : Optional.  Used by the template in order to display the window events.

pFieldNumber (long) : Optional.  Used by the template to display which control received the event.

Returns

Example

  code
  ds_ViewDebug ! opens the debug viewer.
  ds_Debug('Just testing') ! sends "Just Testing" to the windows debug viewer.   

ds_WineventDebug(byte pEnable)

Purpose

pEnable (byte) : If TRUE (1) then WinEvent internal debugging info is sent to the debug viewer.  If FALSE (0) then WinEvent internal debugging info is suppressed.

Returns

Example

fp_Testing    ulong

  code
  ds_WineventDebug(1)
  ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)   ! Attempt to locate a procedure in an non-existant dll.  

  Debug string ! ds_LoadDLLProc error, LoadLibrary failed DLL=NoneExistant.dll The specified module could not be found.
 

ds_ViewDebug

Purpose

None.

Returns

Example

fp_Testing    ulong

  code
  ds_ViewDebug ! open debug viewer.
  ds_WineventDebug(1)
  ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)   ! Attempt to locate a procedure in an non-existant dll.  

  Debug string ! ds_LoadDLLProc error, LoadLibrary failed DLL=NoneExistant.dll The specified module could not be found.
 

ds_ViewDebugClose

Purpose

None.

Returns

Example

fp_Testing    ulong

  code
  ds_DebugView ! open debug viewer.
  ds_WineventDebug(1)
  ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)   ! Attempt to locate a procedure in an non-existant dll.  

  Debug string ! ds_LoadDLLProc error, LoadLibrary failed DLL=NoneExistant.dll The specified module could not be found.
  ds_DebugViewClose ! close the debug viewer.

ds_Error(<long pThisErrorCode>)

Purpose

pThisErrorCode (long) : Optional.  If omitted then the current ds_ErrorCode() is used.  This is the error code for which the text error message is required.

Returns

Example

fp_Testing    ulong

  code
  if ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)   ! Attempt to locate a procedure in an non-existant dll.  
    message('Error ' & ds_error())
  end

ds_ErrorCode()

Purpose

None.

Returns

Example

fp_Testing           ulong
SaveErrorCode    long

  code
  if ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)   ! Attempt to locate a procedure in an non-existant dll.  
    SaveErrorCode = ds_ErrorCode()
    message('Error ' & ds_error())
  end

ds_ErrorReset(<string pCallingProcedure>)

Purpose

pCallingProcedure (string) : Optional.  This procedure name will be returned with any ds_Error() message string.  Useful for identifying the parent procedure where a procedure is called from various procedures.

Returns

Example

fp_Testing           ulong
SaveErrorCode    long

  code
  if ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)   ! Attempt to locate a procedure in an non-existant dll.  
    SaveErrorCode = ds_ErrorCode()
    message('Error ' & ds_error())
  end

ds_SaveStack & ds_TestStack

Purpose

None.

Returns

Example

  code
  ds_SaveStack
  ! some external procedure call.
  ds_TestStack
 

ds_FormatHex(ulong pDisplayValue,byte pPadSpaces)

Purpose

pDisplayValue (ulong) : The number to format as hex.

pPadSpaces (byte) : The length of the hex number to return (leading zeros).

Returns

Example

DisplayHex    string(10)

  code
  DisplayHex = ds_FormatHex(31,4) ! 001F
 

ds_SetClipboard(ulong pClipFormat,string pNewContents)

Purpose

pClipFormat (ulong) : The format specifier.

CF_TEXT                equate(1)
CF_BITMAP            equate(2)
CF_METAFILEPICT equate(3)
CF_SYLK               equate(4)
CF_DIF                  equate(5)
CF_TIFF                 equate(6)
CF_OEMTEXT        equate(7)
CF_DIB                  equate(8)
CF_PALETTE         equate(9)
CF_PENDATA        equate(10)
CF_RIFF                equate(11)
CF_WAVE             equate(12)
CF_UNICODETEXT equate(13)
CF_ENHMETAFILE equate(14)
CF_HDROP            equate(15)
CF_LOCALE           equate(16)
CF_DIBV5              equate(17)
 

pNewContents (string) : The data to be placed in the clipboard.

Returns

Example

This example places the name "C:\autoexec.bat" into the windows clipboard.
Using windows explorer you can then paste a copy of the file elsewhere.

hDropStruct group
pFiles             long  ! offset from here to FileList
pt                   ulong
                      ulong
fNC                 long
fWide              long
FileList            string(255) ! Null terminated list of null terminated file names.
                  end

  code
   hDropStruct.filelist = 'C:\autoexec.bat<0,0>' ! List of files.  Note the double null terminator.
   hDropStruct.pFiles = 20
   hDropStruct.fWide = 0 ! ASCII
   if ~ds_SetClipboard(CF_hDrop,hDropStruct) ! Place name in clipboard.
        message('SetClipboardFailed')
   end
 

ds_ShutDown(<byte pForce>)

Purpose

pForce (byte) : Optional.  When set (1) then any processes that do not "respond" are terminated by windows.

Returns

Example

  code
  ds_Shutdown() ! Request a windows shutdown.
 

ds_WinEventVersion()

Purpose

None.

Returns

Example

  code
  if ds_WinEventVersion < 3.21
    message('Error old WinEvent DLL in use')
  end
 
 

ds_Ulong64ToReal(long pULongHigh,long pULongLow),real

Purpose

pUlongHigh (long) : The first 4 bytes of the ulong64.

pUlongLow (long) : The last 4 bytes of the ulong64.

Returns

Example

RealVar                    real
ulong64G                  group
High                           long
Low                            long
                                end

  code
  RealVar = ds_Ulong64toReal(ulong64G:High,ulong64G:Low)
 

ds_SetOKToEndSessionHandler(ulong pCallBackAddress)

Purpose

pCallBackAddress (ulong) : The address of the OKToEndSessionHandler.

The OKToEndSessionHandler must be prototyped as :
MyOKToEndSessionHandler(long pLogoff),long,pascal

Returns

Example

OldHandlerAddress        ulong

  code
  OldHandlerAddress = ds_SetOKToEndSessionHandler(address(MyOKToEndSessionHandler))

ds_SetEndSessionHandler(ulong pCallBackAddress)

Purpose

pCallBackAddress (ulong) : The address of the EndSessionHandler.

The EndSessionHandler must be prototyped as :
EndSessionHandler(long pLogoff),long,pascal

Returns

Example

OldHandlerAddress        ulong

  code
  OldHandlerAddress = ds_SetEndSessionHandler(address(MyEndSessionHandler))

ds_SetNoEndSession(long pNoEndSession)

Purpose

pNoEndSession (long) : When set (1) then the Auto-Shutdown is disabled.

Returns

Example

  code
  ds_SetNoEndSession(TRUE)
  !  Do backup routine here
  ds_SetNoEndSession(FALSE)
 

ds_GetCurrentProcess()

Purpose

None.

Returns

Example

long     hProcess

  code
  hProcess = ds_GetCurrentProcess()

ds_GetCurrentThread()

Purpose

None.

Returns

Example

long     hThread

  code
  hThread = ds_GetCurrentThread()

ds_GetProcessTime(long hProcess=0,long IncludeFlags=0),real

Purpose

hProcess (long) : Optional.  The windows handle to the process.  Defaults to the current process.

IncludeFlags (long) : Optional.  1 = User Time, 2 = Kernal Time, 0 = Total Time (Default)

Returns

Example

real    UserTime

  code
  UserTime = ds_GetProcessTime(,1)
  DisplayTime = ds_FormatFastTime(UserTime,6)    ! HH:MM:SS.SSSSSS

ds_GetThreadTime(long hThread=0,long IncludeFlags=0),real

Purpose

hThread (long) : Optional.  The windows handle to the thread.  Defaults to the current thread.

IncludeFlags (long) : Optional.  1 = User Time, 2 = Kernal Time, 0 = Total Time (Default)

Returns

Example

real    UserTime

  code
  UserTime = ds_GetThreadTime(,1)
  DisplayTime = ds_FormatFastTime(UserTime,6)    ! HH:MM:SS.SSSSSS

ds_SetRealTimePriority(long hProcess=0,long hThread=0,byte RealTimeFlag=1)

Purpose

hProcess (long) : Optional.  The windows handle to the process.  Defaults to the current process.

hThread (long) : Optional.  The windows handle to the thread.  Defaults to the current thread.

RealTimeFlag (byte) : Optional.  When set (Default) then Real Time Priority is selected.  When clear then Normal Priority is selected.

Returns

Example

  code
  ds_SetRealTimePriority(,,TRUE)    ! Select Real Time priority
   ......
  ds_SetRealTimePriority(,,FALSE)    ! Select Nornal priority

Frequently Asked Questions (FAQ's)

(1) Question: I want my application to auto-shutdown. I have checked the 'Auto Shutdown Enabled' checkbox on the WinEvent extension template on my frame, but it still does not auto-shutdown.

Answer: Are you using 'WinNotOnTaskBar'?  auto-shutdown is not compatible with 'WinNotOnTaskBar'.  Use window{prop:hide} instead (click here for an example).  You need to either check the 'Auto shutdown on' checkbox in the WinEvent Global Extension template (the easiest way),  check each 'Auto shutdown enabled' checkbox on each of the windows or hand code the relevant function yourself. You may prefer to take the second option if there are windows which must be closed (like forms, etc) by the user before the application is automatically closed. In this case, you can leave those 'Auto shutdown enabled' checkbox cleared, so that your application won't auto-shutdown when these windows are open. For those more daring, you can do the hand coding method (click here for more details).

(4) Question: I'm trying to import a procedure from another application, but 2 instances of the WinEvent template appear after import on that procedure.

Answer: There are 2 possible solutions to this (depending on which may be better in your situation):

1. Delete the WinEvent global template from the application that you want to export the procedures from. Export the procedures to a txa file, and then add the WinEvent global template back into your application. You can the import the txa file into your new application.
Pros: Simpler and quicker.
Conns: Can lose some template settings (of the templates that were temporarily removed).
This should only be done in applications where the default template settings are used.

2. Export the procedures that you want to a txa file. You now need to manually edit the txa file and remove all WinEvent: Alert Windows Messages template instances in that file. Basically, what you need to delete is the following (wherever it occurs in the txa file:

[ADDITION]
NAME WinEvent WinEvent
[INSTANCE]
INSTANCE 2
OWNER 1
[PROMPTS]
%DisableWinEvent LONG (0)
%AutoDown LONG (0)
%NoAutoDown LONG (0)
%EnableWheelMouse LONG (0)
%AlertWinEventDebug LONG (0)
%DisplayCompileDate LONG (0)
%DisplayCompileDateFormat DEFAULT ('@D6')
%WinAlert MULTI LONG ()
%Mess DEPEND %WinAlert DEFAULT TIMES 0

%Act1 DEPEND %WinAlert DEFAULT TIMES 0

%act2 DEPEND %WinAlert DEFAULT TIMES 0

%SortListbox MULTI LONG ()
%ThisListbox DEPEND %SortListbox DEFAULT TIMES 0

%ThisListboxHeader DEPEND %SortListbox MULTI DEFAULT TIMES 0

%gloWinEventTesting LONG (0)
%gloWinEventTestingColor1 LONG (15728618)
%gloWinEventTestingColor2 LONG (16777215)

Version History

Version 3.34 (20 January 2006)

Version 3.33 (11 January 2006)

Version 3.32 (21 October 2005)

Version 3.31 (27 September 2005)

Version 3.30 (1 September 2005)

Version 3.29 (21 July 2005)

Version 3.28 (19 January 2005)

Version 3.27 (10 December 2004)

Version 3.26 (3 December 2004)

Version 3.25 (25 November 2004)

Version 3.24 (3 November 2004)

Version 3.23 (2 November 2004)

Version 3.22 (23 October 2004)

Version 3.21 (8 September 2004)

Version 3.20 (18 August 2004)

Version 3.19 (22 July 2004)

Version 3.18 (3 June 2004)

Version 3.17 (31 May 2004)

Version 3.16 (16 April 2004)

Version 3.15 (7 April 2004)

Version 3.14 (23 March 2004)

Version 3.13 (18 March 2004)

Version 3.12 (3 March 2004)

Version 3.11 (16 February 2004)

Version 3.10 (5 February 2004)

Version 3.09 (3 February 2004)

Version 3.08 (2 February 2004)

Version 3.07 (28 January 2004)

Version 3.06 (12 January 2004)

Version 3.05 (5 January 2004)

Version 3.04 (11 December 2003)

Version 3.03 (22 September 2003)

Version 3.01 (21 August 2003)

Version 3.00 (30 July 2003)

Version 2.99 (9 July 2003)

Version 2.98 (3 July 2003)

Version 2.97 (26 June 2003)

Version 2.96 (24 June 2003)

Version 2.94 (2 June 2003)

Version 2.93 (1 May 2003)

Version 2.92 (8 April 2003)

Version 2.91 (24 March 2003)