CapeSoft.Com
Clarion Accessories
WinEvent
Documentation
CapeSoft Logo

CapeSoft WinEvent
Documentation

Download Latest Version FAQ History
Installed Version Latest Version

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 and 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 © 2016 by CapeSoft Software. CapeSoft Software 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 and Purchase

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

WinEvent may be purchased from:

CapeSoft Sales
Web www.capesoft.com
Email sales at capesoft dot com
Telephone +27 21 715 4000
Fax +27 21 715 2535
Post PO Box 511, Plumstead, 7801, Cape Town, South Africa


Buy Online
Web Buy now at ClarionShop
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.

DLLs required (Standalone mode only)
Clarion VersionDLL required
Clarion 7.3 and 8claWE.DLL
Clarion 7.1 and 7.2c70WE.DLL
Clarion 6WE60X.DLL
Clarion 5.5WE55X.DLL

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.

enabling WineEvent functions screenshot

On the Settings tab of the WinEvent global extension template:

global extension template settings tab

The Auto-Shutdown on tick box to apply the automatic shutdown function to your application. This will then be globally applied to the application. By default, this feature is on, but you can disable it here if you'd like to. You can also disable it at a local level as well.

The Make windows visible on Desktop will ensure that when your windows open, they are visible on the desktop area. You can disable this locally if there are specific windows that don't require this feature (otherwise by default it will be on for all windows in your application).

Multi-DLL applications:

You need to add the WinEvent global extension template to each of your applications that use the WinEvent functions. If you are using the Auto-Shutdown or Make windows visible on desktop functionality, then you will need to add WinEvent to all the dlls with window procedures in them.

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. you simply add the WinEvent global extension template and leave the defaults checked and away you go.

Using the Local WinEvent: Alert Windows Messages Template

You can override some of the global defaults set in the Global WinEvent Extension template in the WinEvent: Alert Windows Messages local extension template that is populated onto each window:


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.





You can view a list of the Windows Messages to equate in the eventequ.clw file (which is found in your Clarion6\3rdparty\libsrc directory).

Action (group 1):

WinAccept is a event handler that will accept the windows event before it arrives at your window. Action (group 1) determines what reply WinAccept must do (for the Windows Kernel) when this event is received. If Return 1 or Return 0 is selected, then those values are returned to the Windows kernel, otherwise the event is passed on to Clarion for Clarion to return a value to the Windows kernel.

Action (group 2):

These options are telling WinAccept what to do with the event - in terms of forwarding it on to your Clarion procedure. There are 3 possible options you can select:
case Event() - WinMessageEvent
of 0 ! WinMessageEvent
  !Put your code in here to process when this event is received.
Windows MessageClarion Event posted
WE::WM_CLOSEEvent:CloseWindow
WE::WM_MOUSEMOVE
WE::WM_NCMOUSEMOVE
Event:MouseMove
WE::WM_TIMEREvent:Timer
WE::WM_LBUTTONDOWN
WE::WM_RBUTTONDOWN
WE::WM_NCRBUTTONDOWN
WE::WM_NCLBUTTONDOWN
WE::WM_NCMBUTTONDOWN
WE::WM_MBUTTONDOWN
Event:MouseDown
WE::WM_LBUTTONUP
WE::WM_RBUTTONUP
WE::WM_NCRBUTTONUP
WE::WM_NCLBUTTONUP
WE::WM_NCMBUTTONUP
WE::WM_MBUTTONUP
Event:MouseUp
Please Note: If using the WE::WM_MouseWheel on a window with a listbox, then only the mouse wheel events occurring when the mouse wheel button is depressed will be passed to the WinAccept. Windows will only pass on the mouse wheel events when a list box is not present. Also, in order to determine whether the mousewheel is scolled forward or backward, use the WinParam1() function. The positive value indicates a scroll up and the negative value indicates a scroll 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 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

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 (RS232).

Using Comm's functions in an Application

Add the Enable WinEvent Functions extension template to your Global extensions.

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. You will need to handcode the functions into your application where you need them.

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.



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. We've included some generic default behaviour, but you may like to add some more options. 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.


WE::CloseAllNow = 1
post(event:closewindow)

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).

Note: As from windows Vista the Timer parameter to ds_WinTaskBarBaloon no longer has any effect. Notification display times are now based on system accessibility settings. See https://msdn.microsoft.com/en-us/library/windows/desktop/bb773352(v=vs.85).aspx

Functions supplied

WinTaskbarAddIcon
WinTaskbarChangeIcon
WinTaskbarRemoveIcon
WinNotOnTaskbar
ds_WinTaskbarBalloon

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

Window Behaviour 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
ds_GetUserName
ds_GetWorkstationName
ds_IsMediaCenter
ds_IsTerminalServer
ds_IsTablet
ds_IsStarter
ds_OnNetwork
ds_RefreshDesktop

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.

Registry Functions

Functions Supplied

ds_GetReg
ds_PutReg

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 and Directory Functions

Functions Supplied

ds_DeleteFile
ds_GetFileDirEntry
ds_SetFileAttributes
ds_CreateDirectory
ds_CopyDirectory
ds_RemoveDirectory
ds_SetFileDateTime
ds_MoveFile
ds_GetFolderPath
ds_GetTempPath
ds_String2File
ds_File2String
ds_GetHModule
ds_GetHIcon
ds_CreateShortcutEx
ds_GetFileVersionInfo
ds_GetCurrentEXEDate

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

Getting Started

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.

Getting Started

First, some Important info:

Note: Using a GSM modem is really the only way to send and receive SMSes using WinEvent. Phones themselves vary widely in the ability to handle GSM and every manufacturer's GSM protocol (Commands, etc) are so widely varied, that they will be impossible to support (although you may be lucky - but to avoid the frustration, get a modem).

Note: Only the standard Charset is supported at this stage.

Note: Modems tested with WinEvent: Siemens TC35i, SonyEricson GT47 and Wavecom Wismo (serial only). Please let us know if you have tested with other models of Modems, and we'll add those to this list.

First call NewPort and wait for it to finish before sending an sms - it will look something like the following:

LOC:SMSPortID = NewPort('COM' &clip(left(pComport)) &':' &clip(left(pBaud)) &', ' &clip(left(pParity)) &', ' &clip(left(pPData)) &', ' &clip(left(pStop)))

You need to wait a couple of seconds between sending SMS's. You can use a window timer event for this. Have a look at the ds_GSMSendSMS function for details.

Make sure there is space on the SIM card (although you shouldn't need the space unless you are reading SMS's, but it's a good idea anyway). Take a look at the ds_GSMReadSMS and ds_GSMDeleteSMS functions.

Debugging & Error Reporting Functions

Functions Supplied

ds_OutputDebugString
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

Auto-shutdown gives your application the ability to automatically shutdown when windows performs a restart or shutdown or user logoff while your application is running. This is on by default when you add the WinEvent global extension template to your application.

Note: If you have a Multi-DLL application and require the Auto-shutdown throughout your application, then you need to add the global extension to each application in the Multi-DLL suite. You can override this locally at the template level by checking the 'Disable Auto Shutdown' checkbox - if there are specific windows where you would like to disable the auto-shutdown.

For handcoded window procedures, you'll need to code the following:
  1. After opening the window (before the accept loop):

    WinAlert(WE::WM_QueryEndSession,,Return1+PostUser)
  2. Before closing the window:

    If WindowOpened Then WinAlert().

Functions Supplied

ds_SetOKToEndSessionHandler
ds_SetEndSessionHandler
ds_SetNoEndSession

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

Some Technical Details

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.

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
ds_GetUserName
ds_GetWorkstationName
ds_IsMediaCenter
ds_IsTerminalServer
ds_IsTablet
ds_IsStarter
ds_OnNetwork

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

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

Parameters

Parameter Description
FromMessage shortThe [first] Windows message to alert.
ToMessage shortThe last Windows message to alert. If this parameter is omitted then only the FromMessage is alerted.
Action shortThis defines the action required when the alerted message(s) are received. If this parameter is omitted then it defaults to PostUser + PassOn.
Description

This function works in a very similar way to the normal Clarion ALERT function. Where the ALERT function traps keystrokes, the WINALERT function traps Windows Messages.
However in addition to merely spotting the messages you can also specify the action required when the message comes along. The messages are automatically trapped for the current window. In other words you must open the Window before alerting the Windows messages for that window.

NOTE : If all three parameters are omitted then the WinAlerts for that window are removed. This must be done before closing a window if any messages were alerted for that window.

The actions are split into two groups, and a single action from each group (i.e. up to 2 actions) are allowed. The actions are as follows:

Group 1
EquateMeaning
Return0 Return 0 to the function that sent the message.
Return1Return 1 to the function that sent the message.
PassOnPass the message on to the Clarion window for processing.
Group 2
EquateMeaning
PostUser Post a User Event to the Accept loop.
PostClarion Post an equivalent Clarion Event (if the is one) to the Accept loop. This action is only available in the registered version of the library.
NOTE : The PostClarion action is only available in the registered version of WinEvent.

Depending on the message, and the effect you require, the above options should cater for all eventualities. The only case where additional coding would be necessary would be when the action includes PostUser. This posts a user event (usually 500h, but can be changed) to the Accept loop. On receiving this event you can then call the function Winevent() to determine the actual event. WinEvent is described more fully below, but behaves essentially the same as the regular Clarion EVENT() function.

Complication

If more than one Windows message is alerted, and both alerted messages are received in close succession, then Winevent() returns only the last received of the messages. It should be noted here, that this applies only to alerted messages. Un-alerted messages (and there are plenty of those) have no effect whatsoever.

Returns

Nothing

Example
Example
code
open(window)
WinAlert(WM_QueryEndSession,Return0)
!!! All the normal processing goes here
WinAlert() ! DON'T FORGET THIS !!!!!
Close(Window)

See Also

WinChangeUserEvent () : To change the User event posted back to your App.

Winevent, WinControl, WinParam1, WinParam2

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


Parameters

None

Description

The WinEvent function is used when a User Event is received to determine which Windows message caused the event. It is not cleared after use and remains available until the next Alerted Windows message is received. The WinParam1 and WinParam2 functions return the windows parameters for that message. The WinControl function returns the handle of the specific window that received the message. You can then use this handle to check which control received the event.

Complication

If more than one Windows message is alerted, and both alerted messages are received in close succession, then Winevent() returns only the last received of the messages.

Returns

The last alerted Windows message received.

Example
Example
  code
  case Event() - WinMessageEvent
  of 0 ! WinMessageEvent
    case Winevent()
    of WM_MouseMove
  
    ! something goes here - can also use WinParam1() and WinParam2() here
    end
  of 5502 ! WM_SYSCOMMAND
  of 5506 ! WM_WTSSESSION_CHANGE 
  end

See Also

WinAlert : For alerting windows messages
WinSysEvent : For handling the wm_SYSCOMMAND windows message.
WinWtsEvent : For handling the wm_WTSSESSION_CHANGE windows message.

WinChangeUserEvent

WinChangeUserEvent (WinMessageEvent)

Parameters
Parameter Description
WinMessageEvent shortThe Event to post when an alerted windows message is received.

Description

WinMessageEvent is an equate defined in the WM.CLW file. If you want to change it from it's default value of 500h then change it in this file, and call the WinChangeUser function early in your application. Once changed, it remains changed for all alerted windows messages.

Returns

Nothing

Example
Example
code
WinChangeUser(WinMessageEvent)

WinSysEvent

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

Parameters
Parameter Description
byte pClearAfterReadDefault FALSE.  If set TRUE the WinSysEvent is reset to zero after reading.

Description

An extension of the WinEvent function. WinSysEvent is used instead of WinEvent when a wm_SYSCOMMAND message is alerted. WinEvent is still used for other windows messages. If the pClearAfterRead is not TRUE then WinSysEvent remains available until the next wm_SYSCOMMAND Windows message is received. The WinSysParam1 and WinSysParam2 functions return the windows parameters for that message.

Returns

ulong : wm_SYSCOMMAND

Example
Example
  code
  case Event() - WinMessageEvent
  of 0 ! WinMessageEvent
  of 5502 ! WM_SYSCOMMAND
    if WinSysEvent(TRUE) = WM_SYSCOMMAND
      if WinSysParam1() = 61824 ! SC_CONTEXTHELP
        QuestionMarkPressed = TRUE
      end
    end
  of 5506 ! WM_WTSSESSION_CHANGE 
  end
See Also

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

WinWtsEvent

WinWtsEvent(byte pClearAfterRead=0), WinWtsID()

Parameters
Parameter Description
byte pClearAfterReadDefault FALSE.  If set TRUE the WinWtsEvent is reset to zero after reading.

Description

An extension of the WinEvent function. WinWtsEvent is used instead of WinEvent when a wm_WTSSESSION_CHANGE message is alerted. WinEvent is still used for other windows messages. If the pClearAfterRead is not TRUE then WinWtsEvent remains available until the next wm_WTSSESSION_CHANGE Windows message is received. The WinWtsID function returns the session ID linked to the event.

Returns

WTS session change event.
ValueMeaning
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
Example
  code
  case Event() - WinMessageEvent
  of 0 ! WinMessageEvent
  of 5502 ! WM_SYSCOMMAND
  of 5506 ! WM_WTSSESSION_CHANGE 
    case WinWtsEvent(TRUE)
    of 5 !
WTS_SESSION_LOGON
      NewSessionID = WinWtsID()
    end
  end
See Also

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

NewPort

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

Description

Opens a port for sending or receiving.

Parameters
Parameter Description
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
Example
    PortId = NewPort('Com1:9600,n,8,1')
    PortId = NewPort('Com2:9600,n,8,1',1024)
    PortId = NewPort('Com3:9600,n,8,1',1024,1024)

Tip : The window structure must have the SYSTEM attribute. If it does not then ReadPort will fail.

ResetPort

ResetPort (mode string)

Description

Resets the parameters for a port while the port is open. Note that this function can only be called for a port that has already been opened using the NewPort command.

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

Returns: long

< 0 if an error occurred. Otherwise 0.

Example
Example
result = ResetPort('Com1:9600,n,8,1')

ClosePort

ClosePort(PortId long)

Description

Closes a port so it can be used by another program.

Parameters
Parameter Description
PortId (long)This is the port number as returned by the NewPort function.

Returns : long

Nothing

Example
Example
  pid = NewPort ('Com1:9600,n,8,1')
  ! some code goes here
  ClosePort(Pid)

KillAllPorts

KillAllPorts ( )

Description

Closes all open ports.

Returns

Nothing

Example
Example
KillAllPorts()

WritePort

WritePort(PortId long, *String string, Length long)

Description

Writes a string into the transmission buffer.

Parameters
Parameter Description
PortId (long) This is the port number as returned by the NewPort function.
String (string)This is the handle for the string to send. Note: don't use string functions like clip, sub, etc when passing this string.
Length (long)This is the number of bytes to send. If 0 then the string is clipped and sent.
Returns: long

< 0 if an error. Otherwise number of bytes sent.

Example
Example
    pid = NewPort ('Com1:9600,n,8,1')
    buf = 'abcdefghij'
    bytessent = WritePort(pid,buf,10)


Note: Do not use:

if WritePort(pid,buf,10) >= 0
  !Successful write
end


instead of:

bytessent = WritePort(pid,buf,10)
if bytessent
  !Successful write
end

ReadPort

ReadPort (PortId long, *String string, Length long)

Description

Read bytes out of the receive buffer.

Parameters
Parameter Description
PortId (long)This is the port number as returned by the NewPort function.
String (string)This is the handle of the string in which to put the received bytes. Note: don't use string functions like clip, sub, etc when passing this string.
Length (long)This is the maximum number of bytes to receive. If 0 then the receive string will be filled if possible.
Returns: long

< 0 if an error. Otherwise number of bytes received. If 0 then the receive buffer is empty.

Example
Example
pid = NewPort ('Com1:9600,n,8,1')
bytesreceived = ReadPort(pid,buf,0)

Tip: The window structure must have the SYSTEM attribute. If it does not then ReadPort will fail.
Tip: To monitor the port in the background (i.e. without hogging processing time) - you can put the ReadPort in a timer event (Timer set to at least 100 - unless for mission critical timing applications). If the ReadPort returns a 0 then just skip the code for handling the buffer code. In 32bit, windows has an almost unlimited COMPort buffer, so you don't have to worry about comms going missing (if it's not monitored in a tight loop).

SetHandShake

SetHandShake (PortId long, HandShake long)

Description

To Set or Remove port handshaking

Parameters
Parameter Description
PortId (long) This is the port number as returned by the NewPort function.
HandShake (long)This is one of the following : 0 = No Handshaking ; 1 = Xon/Xoff ;  2 = DSR/DTR ; 3 = CTS/RTS
Returns: long

0 if an error.
>0 if successful.
-1 if invalid PortId

Example
Example
pid = NewPort('Com1:9600,n,8,1')
result = SetHandShake(pid,1)

CtsHigh

CtsHigh (Pid Long)

Description

Returns the current status of the CTS (Clear to Send) line. For advanced programming only.

Parameters
Parameter Description
PortId (long)This is the port number as returned by the NewPort function.

Returns

1 if high. 0 if low.

Example
Example
pid = NewPort('Com1:9600,n,8,1')
result = CtsHigh(pid)

DsrHigh

DsrHigh(Pid Long)

Description

Returns the current status of the DSR (Data Send Ready) line. For advanced programming only.

Parameters

PortId (long) This is the port number as returned by the NewPort function.

Returns

1 if high. 0 if low.

Example
Example
pid = NewPort('Com1:9600,n,8,1')
result = DsrHigh(pid)

RingHigh

RingHigh (Pid Long)

Description

Returns the current status of the RI (Ring Indicator) line. For advanced programming only.

Parameters
Parameter Description
PortId (long)This is the port number as returned by the NewPort function.

Returns

1 if high. 0 if low.

Example
Example
pid = NewPort('Com1:9600,n,8,1')
result = RingHigh(pid)

CdHigh

CdHigh (Pid Long)

Description


Returns the current status of the CD (Carrier Detect) line. For advanced programming only.

Parameters
Parameter Description
PortId (long)This is the port number as returned by the NewPort function.

Returns

1 if high. 0 if low.

Example
Example
pid = NewPort('Com1:9600,n,8,1')
result = CdHigh(pid)

SetRts

SetRts (Pid Long, Value Long)

Description

Sets the current status of the RTS (Ready to Send) line. For advanced programming only.

Parameters
Parameter Description
PortId (long)This is the port number as returned by the NewPort function.
Value long)Set to 0 to Clear the RTS line, Set to 1 to Set the RTS line.
Returns

Nothing

Example
Example
pid = NewPort('Com1:9600,n,8,1')
tRts(pid,1)

SetDtr

SetDtr(Pid Long, Value Long)

Description

Sets the current status of the DTR (Data Terminal Ready) line. For advanced programming only.

Parameters
Parameter Description
PortId (long)This is the port number as returned by the NewPort function.
Value (long) Set to 0 to Clear the DTR line, Set to 1 to Set the DTR line.
Returns

Nothing

Example
Example
pid = NewPort('Com1:9600,n,8,1')
SetDtr(pid,1)

WinTaskbarAddIcon

WinTaskbarAddIcon(IconName String,< Tips String>,byte pSetVersion5=0,<string pIconModule>), long

Description

Adds an Icon to the TaskBar's "Tray" area. This icon belongs to the window that's open when the function is called. At least one window must be open when this function is called. When the user clicks on this icon then an event is generated and sent to the owner window. The event generated is the WinUserEvent ( usually 0500h ). This event is generated whenever a WinAlerted message is received. You can then use the Winevent() function to return the specific message that triggered the event. If the user clicked on an icon in the tray, then the Winevent() function will return the number 25000.

Parameters
Parameter Description
IconName (string) This is the name of the icon to display. The icon is an ICO file stored on the disk (or prefix with a '~' to use an icon in the project).
Tips (string)This parameter is optional. If you put a string in here, then this will be the tip displayed when the mouse rests on the icon in the tray.
pSetVersion5 (byte)
pIconModule (string) this is the name of the module containing the icon (if the icon is in the project). Blank will default to the EXE. This is only required if: 1) this is not an EXE and 2) the IconName is prefixed with a '~' and 3) the icon is not in the EXEs project (but in this or another loaded DLL).
Returns : long

Icon Id. This Id is used by the Remove and Change functions

Example
Example
id long
  code
  open(window)
  id = WinTaskBarAddIcon('happy.ico','click on me....')
  accept
   
!! usual window processing goes here
    case event()
    of 5513       !MouseLeftDown
       
! the user has clicked on the icon in the tray.
       
! do something here, like a popup menu...
    of 5514       !MouseLeftUp
    of 5515       !double left click
    of 5516       !mouserightdown
    of 5517       !mouserightup
    of 5510       !load icon
    of 5501       !refresh icon
    of 6026       ! balloon opened
    of 6027       ! balloon closed
    of 6028       ! balloon timeout, closed
    end
  end
  close(window)

WinTaskbarRemoveIcon

WinTaskbarRemoveIcon(<Id long>)

Description

Removes an Icon from the Taskbar's tray.

Parameters
Parameter Description
Id (long)This is the Id number as returned by the Add function. If this parameter is omitted then all icons placed by this window will be removed.
Returns

Nothing

Example
Example
id long
  code
  open(window)
  id = WinTaskBarAddIcon('happy.ico','click on me....')
  WinTaskBarRemoveIcon(id)
! or ....
  WinTaskBarRemoveIcon()

WinTaskbarChangeIcon

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

Description

Changes the icon and / or tool tip for a specific icon that is already placed in the tray. Use this function to update the icon to display your program status.

Parameters
Parameter Description
Id (long) The Icon identifier as returned by the Add function.  If omitted then the first icon added by this window will be changed.
IconName (string)The name of the icon to use.
Tips ( string )The new tool tip for the icon.  If omitted then the tip will be cleared.
pIconModule (string)this is the name of the module containing the icon (if the icon is in the project). Blank will default to the EXE. This is only required if: 1) this is not an EXE and 2) the IconName is prefixed with a '~' and 3) the icon is not in the EXEs project (but in this or another loaded DLL).
Returns

Nothing

Example
Example
id long
  code
  open(window)
  id = WinTaskBarAddIcon('happy.ico','click on me....')
  WinTaskBarChangeIcon(id,'sad.ico','Im sooo sad')

Additional notes:

There are 3 events available for event tracking:
  1. Balloon open
  2. Balloon close
  3. Balloon close on timeout.
To track these events, you can place code in the relative embed point to run when one of these events occurs:

ds_WinTaskbarBalloon

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

Description

This opens a "balloon" linked to the system tray icon. The balloon will stay open until either the user closes it or the user gives focus to the application.
There is a minimum time that the balloon will be open. This is used in cases where another balloon (different application) is requested.

Balloons are not supported in win95 or win98 so WinEvent supplies a XP/Vista "look alike".

Parameters
Parameter Description
pID (ulong)Optional.  Returned by WinTaskbarAddIcon.  Is used to identify which icon to attach the balloon to.
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).

WE::NIIF_ERROR EQUATE(003h) An error icon.
WE::NIIF_INFO EQUATE(001h) An information icon. (Default)
WE::NIIF_NONE EQUATE(000h) No icon.
WE::NIIF_WARNING EQUATE(002h) A warning icon.
WE::NIIF_NOSOUND EQUATE(010h) XP/Vista 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)
Note: As from windows Vista the Timer parameter no longer has any effect. Notification display times are now based on system accessibility settings. See
https://msdn.microsoft.com/en-us/library/windows/desktop/bb773352(v=vs.85).aspx
Returns

Nothing

Example
Example
ID        long

  code
  ID = WinTaskbarAddIcon('~MyAppIcon.ico','This is my tip text.<13,10>This is on line 2.')
  ds_WinTaskbarBalloon(ID,'This is the balloon text.<13,10>This is on line 2.','This is the title.')
  ......
  ds_WinTaskbarBalloon(ID,'')
! This closes the balloon.

!In the TakeEvent procedure:

  case Event() - WinMessageEvent
  of 6026
! balloon opened
  of 6027
! balloon closed     - using code
  of 6028
! balloon closed (using the balloon close button)
  of 6029
! balloon clicked, closed
  end ! case


Faultfinding

If the balloon is not displaying, then try the winevent demo application (Go to Taskbar Functions - and you will find the show|hide balloon buttons that you can use to test this functionality). If it is not working, then you have balloontips turned off in your windows registry. Search for BalloonTips, and change the value of the key you find from 0 to 1.

WinNotOnTaskbar

WinNotOnTaskbar()

Description

Applications using this function do not appear on the Windows 95 Task bar. This is normally
used in conjunction with the WinTaskBarAddIcon when you want a background program to
appear on the Taskbar's tray, and not on the taskbar itself. It must be called before the first
window of the application is opened.

IMPORTANT Note : WinNotOnTaskBar is not compatible with auto-shutdown.
If you are using WinTaskBarAddIcon then the following code may be used as an alternative.
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

None

Returns

Nothing

Example
Example
code
WinNotOnTaskBar()
open(window)

WinOnTop

WinOnTop()

Description

Makes your window float on top of other windows applications. Note: you can't use this function for MDI applications on MDI-child windows.

Parameters

None

Returns

Nothing

Example 1
Example
code
open(window)
WinOnTop()
Example 2
Example
! -------------------------------------
! Hides Window (opposite of WindowShow)
! Useful for use with the TaskBar icon code

WindowHide Routine
  window{prop:iconize} = true
  window{prop:hide} = true
 
! -------------------------------------
! Shows Window (opposite of WindowHide)

! Useful for use with the TaskBar icon code
WindowShow Routine
  if window{prop:iconize} = false
    window{prop:iconize} = true
  end
  window{prop:hide} = false
  window{prop:iconize} = false

! -------------------------------------
! Shows Window (opposite of WindowHide)

! Useful for use with the TaskBar icon code
! No Focus is gained

WindowShow_NoFocus Routine
  window{prop:iconize} = false
  window{prop:hide} = false
  WinOnTop()
  WinNotOnTop()

WinNotOnTop

WinNotOnTop()

Description

Reverses the effect of the WinOnTop() function. Note: you can't use this function for MDI applications on MDI-child windows.

Parameters

None

Returns

Nothing

Example
Example
  code
  open(window)
  WinOnTop()
  WinNotOnTop()

WinBringToFront

WinBringToFront()

Description

Brings your window to the front of the open windows. This would be used if your program wanted to bring itself to the front because some event has occurred that needs action. Note: you can't use this function for MDI applications on MDI-child windows.

Parameters

None

Returns

Nothing

Example
Example
  code
  open(window)
  WinBringToFront()

ds_ShowWindow

ds_ShowWindow(byte pGrabFocus=1)

Description

Unhides your window.  This is used in conjunction with ds_HideWindow.

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

Nothing

Example
Example
  code
  open(window)
  ds_ShowWindow()

ds_HideWindow

Description

Hides your window.  This is used in conjunction with ds_ShowWindow.

Parameters

None

Returns

Nothing

Example
Example
  code
  open(window)
  ds_HideWindow()

ds_WinTransparent

ds_WinTransparent(long Transparency)

NB: Only available for non-MDI windows.

Description

Adjusts the transparency of a window .

Parameters
Parameter Description
Transparency (long)This sets the transparency factor.  0 = Invisible,  255 = Normal.
Returns

Nothing

Example
Example
  code
  open(window)
    ds_WinTransparent(255) ! normal window display
    ds_WinTransparent(0) ! window will be invisible 

ds_VisibleOnDesktop

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

Description

Repositions and resizes the window to be visible on the desktop. This is particularly useful if the window position was saved off the desktop (in a previously visible place that is now no longer visible). WinEvent will move the window onto the visible desktop area.

Parameters
Parameter Description
pWinX (*long)Optional.  If omitted then the current target window is used.  If supplied then the variable is updated.
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

Nothing

Example
Example
  code
  open(window)
  Open(Window)
  ds_VisibleOnDesktop()

ds_GetWinVersion

ds_GetWinVersion()

Description

Returns the version of windows that is running.

Parameters

None

Returns

String formatted with Windows version, Windows edition, major version number, minor version number, build number and then service pack description.

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

Note: At least up to Clarion 6.3 9056, the Clarion IDE is run in XP compatibility mode on Windows Vista. This means that when running an application from within the IDE, the ds_GetWinVersion will return Win XP, and not Win Vista. The same application run from a normal shortcut will return the correct windows version (i.e. Win Vista).

Note: As from Windows 8.1 this function will return the OS that the app is manifested for. In other words if you are running on version 8.1, but the app is only manifested for Windows 8, then this function will return Windows 8.

Example
Example
  code
  DisplayString = ds_GetWinVersion()

  case sub(ds_GetWinVersion(),1,8)
  of 'Win 3.1'
  of 'Win 95'
  of 'Win 98'
  of 'Win NT'
  of 'Win 2K'
  of 'Win 2K3'
  of 'Win XP'
  of 'WinVista'
  of 'Win 7'
  of 'Win 2008'
  of 'Win 8'
  of 'Win 8.1'
  of 'Win 2012'
  of 'Win 2012 R2'
  of 'Win 10'
  else
  end

WindowsVersion

WindowsVersion()

Description

Returns the version of windows that is running. This may return a different number for 16 and 32 bit programs. For example a 16 bit program, running under Windows 95 will return 3 as the windows version number. The version release number is 95. A 32 bit program running under windows 95 will return 4 as the windows version number. The release number is 0.

Parameters

None

Returns

Long containing Windows version number. This together with the release number (WindowsRelease() ) gives you the version number of windows.

Example
Example
  code
  ver = WindowsVersion()

WindowsRelease

WindowsRelease()

Description

Returns the release of windows that is running. This may return a different number for 16 and 32 bit programs. For example a 16 bit program, running under Windows 95 will return 3 as the windows version number. The version release number is 95. A 32 bit program running under windows 95 will return 4 as the windows version number. The release number is 0.

Parameters

None

Returns

Long containing Windows release number. This together with the version number (WindowsVersion() ) gives you the version number of windows.

Example
Example
  code
  ver = WindowsVersion()
  rel = WindowsRelease()

DosVersion

DosVersion()

Description

Returns the version of Dos that is running. This is only valid for 16 bit programs. For example a 16 bit version of a program running on Windows 95 will return 7 as the version number, and 0 as the release number.

Parameters

None

Returns

Long containing Dos version number. This together with the release number (DosRelease() ) gives you the version number of Dos.

Example
Example
  code
  ver = DosVersion()

DosRelease()

DosRelease()

Description

Returns the release of Dos that is running. This is only valid for 16 bit programs. For example a 16 bit version of a program running on Windows 3.11 and Dos 6.22 will return 6 as the version number, and 22 as the release number.

Parameters

None

Returns

Long containing Dos release number. This together with the version number (DosVersion() ) gives you the version number of dos.

Example
Example
code
ver = DosVersion()
rel = DosRelease()

GetFreeDiskSpace

GetFreeDiskSpace (<drive long>)

Description

Returns the amount of free disk space, in bytes.

Parameters
Parameter Description
DriveOptional. 0 = current drive. 1 = A, 2 = B etc.

Returns

Real containing number of free bytes on the disk. In version 2.6 and earlier of WinEvent this was a Long.

Example
Example
free real
  code
  free = GetFreeDiskSpace()

GetDiskSpace

GetDiskSpace (<drive long>)

Description

Returns the total disk space, in bytes.

Parameters
Parameter Description
DriveOptional. 0 = current drive. 1 = A, 2 = B etc.

Returns

Real containing total number of bytes on the disk. However maximum value is currently 2 gigs.

Example
Example
total real
  code
  total = GetDiskSpace()

ds_GetDiskMegs

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

Description

Returns the specified disk space, in megabytes.

Parameters
Parameter Description
pDrive (string)Optional. Defaults to current directory.
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

Ulong. The disk space in megabytes.

Example
Example
total ulong
  code
  total = ds_GetDiskMegs()

ds_Memory

ds_Memory(<string pSelector>)

Description

Returns the specified RAM space, in kBytes. (Ram sizes up to 2 terabytes are supported.)

Parameters
Parameter Description
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

Ulong. The RAM size in kilobytes.

Example
Example
total ulong
  code
  total = ds_Memory()
  ! Returns the virtual memory used by this application in Kilobytes

ds_GetReg

s_GetReg(Long hKey, String SubKeyPath, String ValueName)

Description

Gets a value out the Windows System Registry.

Parameters
Parameter Description
hKey (long)The top level key containing the section of the registry to read. Valid values are;
WE::WM_HKEY_CLASSES_ROOT
WE::WM_HKEY_CURRENT_USER
WE::WM_HKEY_LOCAL_MACHINE
WE::WM_HKEY_USERS
SubKeyPath (string)The path inside the registry to the item you want to read.
ValueName (String)The name of the variable you want to read.
Returns

Any. the value stored in the string. If the read failed the the value 0 is returned, and the Winevent extended error is set. The Winevent error can be retrieved using ds_Error and ds_Errorcode functions.

Example
Example
htmleditor string(255)
  code
  htmleditor = ds_GetReg(we::wm_hkey_current_user, |
               'Software\Microsoft\Internet Explorer\Default HTML Editor','Description')

ds_PutReg

ds_PutReg(Long hKey, String SubKeyPath, String ValueName, String Value, <Long Type>)

Description

Writes a value to the Windows System Registry.

Parameters
Parameter Description
hKey (long)The top level key containing the section of the registry to write. Valid values are;
WE::WM_HKEY_CLASSES_ROOT
WE::WM_HKEY_CURRENT_USER
WE::WM_HKEY_LOCAL_MACHINE
WE::WM_HKEY_USERS
SubKeyPath (string)The path inside the registry to the item you want to write.
ValueName (String)The name of the variable you want to write.
Value (String)The value you want to write into the registry.
Type (Long)the type of the value you are writing. Valid values are;
WE::REG_SZ                  !!// Unicode nul terminated string
WE::REG_EXPAND_SZ           !!// Unicode nul terminated string
WE::REG_BINARY              !!// Free form binary
WE::REG_DWORD               !!// 32-bit number
WE::REG_DWORD_LITTLE_ENDIAN !!// 32-bit number (same as REG_DWORD)
WE::REG_DWORD_BIG_ENDIAN    !!// 32-bit number
WE::REG_MULTI_SZ            !!// Multiple Unicode strings


Default value for this parameter is WE::REG_SZ.
Returns

0 if successful, non zero if not successful. Additional error information can be read using the ds_Error and ds_ErrorCode functions.

Example
Example
htmleditor string(255)
  code
  htmlEditor = 'Microsoft Expression Web'
  ds_PutReg(we::wm_hkey_current_user, |
            'Software\Microsoft\Internet Explorer\Default HTML Editor','Description',htmlEditor,we::reg_sz)

Sound

Sound (WavFileName String)

Description

Plays a Wav file through the speaker.

Parameters
Parameter Description
WavFileName (string)The name of the Wav file on the disk, including path if necessary.

Returns

Nothing

Example
Example
  code
  sound('alarm.wav')

GetWindowsDir

GetWindowsDir ()

Description

Gets the directory where Windows is installed. For multi-user systems this returns the Windows directory that is personal to the logged in user.

Parameters

None

Returns

A string containing the path to the Windows directory.

Example
Example
a string(255)
  code
  a = GetWindowsDir()

GetSystemDir

GetSystemDir ()

Description

Gets the Windows system directory.

NOTE : This is usually \windows\system

Parameters

None

Returns

A string containing the path to the Windows system directory.

Example
Example
a string(255)
  code
  a = GetSystemDir()

ScreenWidth

ScreenWidth ()

Description

Gets the current width, in pixels, of the windows desktop.

Parameter

None

Returns

A long containing the number of pixels.

Example
Example
a long
  code
  a = ScreenWidth()

ScreenHeight

ScreenHeight ()

Description

Gets the current height, in pixels, of the windows desktop.

Parameters

None

Returns

A long containing the number of pixels.

Example
Example
a long
  code
  a = ScreenHeight()

ScreenDepth

ScreenDepth ()

Description

Gets the current color depth, in bits, of the windows desktop.

Parameters

None

Returns

A long containing the number of bits. For example 8 = 256 colors, 24 = true color and so on.

Example
Example
a long
  code
  a = ScreenDepth()

ds_GetScreenDPI (byte pDPIY=0)

ds_GetScreenDPI (byte pDPIY=0)

Description

Gets the current DPI of the windows desktop.

Parameters
Parameter Description
pDPIY (optional) Defaults to X DPI. If set to TRUE then returns Y DPI. These are usually the same.
Returns

A long containing the DPI setting. For example 96 = Small fonts, 120 = Large fonts.

Example
Example
a long
  code
  a = ds_GetScreenDPI()

ds_GetUserName

ds_GetUserName()

Description

Gets name of user currently logged into Windows.

Returns

A String containing the name.

ds_GetWorkstationName

ds_GetWorkstationName()

Description

Gets the name of the computer as used by Windows networking.

Returns

A string containing the name.

ds_IsMediaCenter()

ds_IsMediaCenter()

Description

Detects if the current version of Windows is a Media Center edition.

Returns

A long set to 1 if the machine is running a Media Center version of Windows, 0 otherwise.

ds_IsTerminalServer

ds_IsTerminalServer()

Description

Detects if the current machine is running on a terminal server.

Returns

A long , Set to 1 if the current machine is a terminal server. Set to 2 if the current machine is a terminal server, and the current session is a remote session.

ds_IsTablet

ds_IsTablet ()

Description

Detects if the current version of Windows is a Tablet edition.

Returns

A long set to 1 if the machine is running a Tablet version of Windows, or the Tablet PC Input Service has been started. 0 otherwise.

ds_IsStarter

ds_IsStarter()

Description

Detects if the current version of Windows is a Starter edition.

Returns

A long set to 1 if the machine is running a Starter version of Windows, 0 otherwise.

ds_OnNetwork

ds_OnNetwork ()

Description

Detects if the current machine is conencted to a network or not.

Returns

A long, 1 if true 0 if false.

ds_RefreshDesktop

ds_RefreshDesktop()

Description

Refreshes the desktop. Typically called after calling ds_CreateShortcutEx..

Returns

Nothing

ds_FastClock

ds_FastClock(byte UseCPUTimeStamp=0,byte ReSyncTime)

Description

Gets the current time down to a resolution of 1µs. This depends on the presence of a highspeed hardware timer chip in the PC.

Defaults to clock() if no highspeed chip is present. If the UseCPUTimeStamp flag is set then the ds_ReadCPUTimeStamp() function is used. NB this will only work on Pentium or better processors.

Parameters
Parameter Description
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

A real containing the time in clarion time format (100 = 1 second) .

Example
Example
  ThisTime    real

  code
  ThisTime - ds_FastClock()
  DisplayTime = ds_FormatFastTime(ThisTime,4) ! 16:23:31.0124

ds_FormatFastTime

ds_FormatFastTime(real pFastTime,<long pDecimalPlaces>)

Description

Used with ds_FastClock() to display the time including fractions of a second.

Parameters
Parameter Description
pFastTime (real)The time in 100 ths of a second (clarion time).
pDecimalPlaces (long) Optional.  The number of decimal places to display.

Returns

String containing the time.

Example
Example
code
DisplayTime = ds_FormatFastTime(ds_FastClock(),4) ! 16:23:31.0124

ds_Sleep

ds_Sleep(real pFastTime)

Description

Executes a yield for the duration specified in 100 ths of a second (clarion time).
This is an API call. The resolution of the time is 1 ms (0.1 in clarion time).

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

Returns

None

Example
Example
code
ds_Sleep
(100.1) ! wait 1.001 seconds

ds_Timer

ds_Timer(long pTimerNumber,<real pFastTime>)

Description

General purpose timer.
Note : you are limited to 999 timers per thread.
the WinEvent SMS functions use ds_Timer(999) and ds_Timer(998).

Parameters
Parameter Description
pTimerNumber (long)Used to specify multiple timers (per thread)
pFastTime (real) The time in 100 ths of a second (clarion time).
Returns

Byte, TRUE (1) if timer has elapsed. FALSE (0) if timer has not yet elapsed.

NOTE: you need to keep checking the timer to see if it is elapsed. There is no event fired when the timer elapses.

Example
Example
  code
  ds_Timer(1,100.1)
! init timer 1 to 1.001 seconds
  loop until ds_Timer(1) ! break when timer 1 elapses.
   .....
  ds_Timer(1,50) ! Restart timer 1 at 0.5 seconds
  .....
  end

ds_WeekDay

ds_WeekDay(long pDate,<byte pShortFormatFlag>)

Description

Returns the English name for the day of the week.

Parameters
Parameter Description
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

String containing the day of the week.

Example
Example
  code
  DisplayDay = ds_WeekDay(today()) ! Returns the current day of the week, i.e. "Wednesday"
  DisplayDay = ds_WeekDay(today(),1) ! Returns the current day of the week, i.e. "Wed"

ds_ReadCPUTimeStamp

ds_ReadCPUTimeStamp(*realpSaveReal)

Description

Reads the Time Stamp Register of the CPU. NB this will only work on Pentium or better processors.

Parameters
Parameter Description
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

None

Example
Example
  ThisTime    real

  code
  ds_ReadCPUTimeStamp(ThisTime)         ! Save TimeStamp into real
   ......
  ds_ReadCPUTimeStampDelta(ThisTime)    ! CPU Cycles elapsed. 
 

ds_ReadCPUTimeStampDelt

ds_ReadCPUTimeStampDelta(*real pSaveReal)

Description

Reads the Time Stamp Register of the CPU and subtract the last saved value. NB this will only work on Pentium or better processors.

Parameters
Parameter Description
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

None

Example
Example
  ThisTime    real

  code
  ds_ReadCPUTimeStamp(ThisTime)         ! Save TimeStamp into real
   ......
  ds_ReadCPUTimeStampDelta(ThisTime)    ! CPU Cycles elapsed.

ds_DeleteFile

ds_DeleteFile(string pFileName)

Description

Delete a file. Any read-only attributes are cleared and then the file is deleted.

Parameters
Parameter Description
pFileName (string)Specify the file (with path) to delete.
Returns

Byte, TRUE (1) for success, FALSE (0) for failure.

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

ds_GetFileDirEntry

ds_GetFileDirEntry(string pFileName,*string pEntryG)

Description

Fills the supplied EntryG structure with the data from the specified file.
This procedure calls the clarion DIRECTORY command. See clarion help for more info.

Parameters
Parameter Description
pFileName (string)Specify the file (with path) for which the directory entry data is required.
pEntryG (*string) Provide the label of an EntryG structure.  See example below.

Returns

Byte, TRUE (1) for success, FALSE (0) for failure.

Example
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

ds_SetFileAttributes(string pFileName,byte pNewAttribs)

Description

Set the directory attributes of a file.

Parameters
Parameter Description
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

Byte, TRUE (1) for success, FALSE (0) for failure.

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

ds_CopyDirectory

ds_CopyDirectory(string Source,string Destination, string Mask, [Long IncludeSubDirectories], [Long IncludeHiddenFiles], [Long IncludeSystemFiles], [Long ProgressControl], [Long StringControl]),long

Description

Copy the contents of one folder to another folder. The contents of the original folder are not deleted. ie this is a Copy, not a Move.

Parameters
Parameter Description
Source (string)The name of the source directory to copy from.
Destination (string)The name of the destination directory to copy to. If the destination directory does not exist it will be created.
Mask (string)The mask for files in the source folder(s) to copy. For example *.htm will copy only files with the htm extension. If this parameter is left blank then the default mask, *.*, will be used.
IncludeSubDirectories (long)Set to 1 for sub-directories to be copied as well. Set to 0 if only files must be copied. This parameter is option, the default value is 0 (ie by default sub-directories are not copied.)
IncludeHiddenFiles (long) This parameter is optional, the default value is 1. If you do not want to copy hidden files then set this parameter to 0.
IncludeSystemFiles (long)This parameter is optional, the default value is 1. If you do not want to copy system files then set this parameter to 0.
ProgressControl (long)The Use Equate number of a progress control on the window. If this is set then the progress bar will be updated as the Copy command progresses. If it is set to 0 or omitted then no progress control will be updated.
StringControl (long) The Use Equate number of a string control on the window that will be updated with the name of the file currently being copied. If set to 0, or omitted, then no string control will be updated.
Returns

Long: The number of files successfully copied. Or a negative number if the copy failed at a specific file (the numeric value contains the number of files that were successfully copied before failure).

Example
Example
code
ans = ds_CopyDirectory(FileSelected,CopyTo,'*.*',1,1,1,?Progress1,?String1)

ds_CreateDirectory

ds_CreateDirectory(string pNewDirectoryName)

Description

Create a new directory.

Parameters
Parameter Description
pNewDirectoryName (string)Specify the name (including path) of the new directory to create.

Returns

Byte, TRUE (1) for success, FALSE (0) for failure.

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

ds_RemoveDirectory

ds_RemoveDirectory(string pDirectoryName)

Description

Remove a directory.

The directory must be empty.

Parameters
Parameter Description
pDirectoryName (string)Specify the name (including path) of the directory to remove.

Returns

Byte, TRUE (1) for success, FALSE (0) for failure.

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

ds_SetFileDateTime

ds_SetFileDateTime(string pFileName,long pNewDate,long pNewTime)

Description

Set the date and time of the files directory entry.

Parameters
Parameter Description
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

Byte, TRUE (1) for success, FALSE (0) for failure.

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

ds_MoveFile

ds_MoveFile(string pFileName,string pNewFileName)

Description

Moves (renames) a file by changing its directory entry.

Parameters
Parameter Description
pFileName (string)Specify the file (with path) to be moved.
pNewFileName (string) Specify the new file (with new path).
Returns

Byte, TRUE (1) for success, FALSE (0) for failure.

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

ds_GetFolderPath

ds_GetFolderPath(long pCSIDL,<byte pCreateFlag>)

Description

Returns the specified windows folder path.  If the optional CreateFlag is TRUE then the directory will be created if it does not exist.

Parameters
Parameter Description
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.
NOTE: Some of these equates (in Windows Vista and up) no longer return the common area folder, but the user folder. This is not a WinEvent issue, as WinEvent just makes use of the API calls in windows. This is a change in spec for the API call value parameter by Windows. See: http://msdn.microsoft.com/en-us/library/dd378457%28v=vs.85%29.aspx

WE::CSIDL_DESKTOP equate(000h) ! C:\Documents and Settings\username\Desktop
WE::CSIDL_INTERNET equate(001h)
! Virtual folder that represents the internet
WE::CSIDL_PROGRAMS equate(002h)
! C:\Documents and Settings\username\Start Menu\Programs
WE::CSIDL_CONTROLS equate(003h)
! Virtual folder that contains icons for Control Panel applications.
WE::CSIDL_PRINTERS equate(004h)
! Virtual folder that contains installed printers.
WE::CSIDL_PERSONAL equate(005h)
! C:\Documents and Settings\username\My Documents
WE::CSIDL_FAVORITES equate(006h)
! C:\Documents and Settings\username\Favorites
WE::CSIDL_STARTUP equate(007h)
! C:\Documents and Settings\username\Start Menu\Programs\Startup
WE::CSIDL_RECENT equate(008h)
! C:\Documents and Settings\username\My Recent Documents
WE::CSIDL_SENDTO equate(009h)
! C:\Documents and Settings\username\SendTo
WE::CSIDL_BITBUCKET equate(00Ah)
! Virtual folder that contains the objects in the user's Recycle Bin.
WE::CSIDL_STARTMENU equate(00Bh)
! C:\Documents and Settings\username\Start Menu
WE::CSIDL_MYDOCUMENTS equate(00Ch)
! Virtual folder that contains the objects in the user's My Documents folder.
WE::CSIDL_MYMUSIC equate(00Dh)
! C:\Documents and Settings\username\My Documents\My Music
WE::CSIDL_MYVIDEO equate(00Eh)
! File system directory that serves as a common repository for video files.
WE::CSIDL_DESKTOPDIRECTORY equate(010h)
! C:\Documents and Settings\username\Desktop
WE::CSIDL_DRIVES equate(011h)
! My Computer virtual folder that contains everything on the local computer: storage devices, printers, and Control Panel. The folder can also contain mapped network drives.
WE::CSIDL_NETWORK equate(012h)
! Network Neighborhood virtual folder that represents the root of the network namespace hierarchy.
WE::CSIDL_NETHOOD equate(013h)
! C:\Documents and Settings\username\NetHood
WE::CSIDL_FONTS equate(014h)
! C:\Windows\Fonts
WE::CSIDL_TEMPLATES equate(015h)
! C:\Documents and Settings\username\Templates
WE::CSIDL_COMMON_STARTMENU equate(016h)
!*C:\Documents and Settings\All Users\Start Menu
WE::CSIDL_COMMON_PROGRAMS equate(017h)
! C:\Documents and Settings\All Users\Start Menu\Programs
WE::CSIDL_COMMON_STARTUP equate(018h)
!*C:\Documents and Settings\All Users\Start Menu\Programs\Startup
WE::CSIDL_COMMON_DESKTOPDIRECTORY equate(019h)
!*C:\Documents and Settings\All Users\Desktop
WE::CSIDL_APPDATA equate(01Ah)
! C:\Documents and Settings\username\Application Data
WE::CSIDL_PRINTHOOD equate(01Bh)
! C:\Documents and Settings\username\PrintHood
WE::CSIDL_LOCAL_APPDATA equate(01Ch)
! C:\Documents and Settings\username\Local Settings\Application Data
WE::CSIDL_ALTSTARTUP equate(01Dh)
! File system directory that corresponds to the user's nonlocalized Startup program group.
WE::CSIDL_COMMON_ALTSTARTUP equate(01Eh)
!*File system directory that corresponds to the nonlocalized Startup program group for all users.
WE::CSIDL_COMMON_FAVORITES equate(01Fh) !*C:\Documents and Settings\All Users\Favorites
WE::CSIDL_INTERNET_CACHE equate(020h)
! C:\Documents and Settings\username\Local Settings\Temporary Internet Files
WE::CSIDL_COOKIES equate(021h)
! C:\Documents and Settings\username\Cookies
WE::CSIDL_HISTORY equate(022h)
! C:\Documents and Settings\username\Local Settings\History
WE::CSIDL_COMMON_APPDATA equate(023h)
! C:\Documents and Settings\All Users\Application Data
WE::CSIDL_WINDOWS equate(024h)
! C:\Windows
WE::CSIDL_SYSTEM equate(025h)
! C:\Windows\System32
WE::CSIDL_PROGRAM_FILES equate(026h)
! C:\Program Files
WE::CSIDL_MYPICTURES equate(027h)
! C:\Documents and Settings\username\My Documents\My Pictures
WE::CSIDL_PROFILE equate(028h)
!*C:\Documents and Settings\username
WE::CSIDL_SYSTEMX86 equate(029h)
!*C:\Windows\System32
WE::CSIDL_PROGRAM_FILESX86 equate(02Ah)
! The x86 Program Files folder
WE::CSIDL_PROGRAM_FILES_COMMON equate(02Bh)
!#C:\Program Files\Common
WE::CSIDL_PROGRAM_FILES_COMMONX86 equate(02Ch)
! The x86 Program Files Common folder
WE::CSIDL_COMMON_TEMPLATES equate(02Dh)
!*C:\Documents and Settings\All Users\Templates
WE::CSIDL_COMMON_DOCUMENTS equate(02Eh)
! C:\Documents and Settings\All Users\Documents
WE::CSIDL_COMMON_ADMINTOOLS equate(02Fh)
! C:\Documents and Settings\All Users\Start Menu\Programs\Administrative Tools
WE::CSIDL_ADMINTOOLS equate(030h)
! C:\Documents and Settings\username\Start Menu\Programs\Administrative Tools
WE::CSIDL_CONNECTIONS equate(031h)
! Virtual folder that contains network and dial-up connections.
WE::CSIDL_COMMON_MUSIC equate(035h)
!*C:\Documents and Settings\All Users\Documents\My Music
WE::CSIDL_COMMON_PICTURES equate(036h)
!*C:\Documents and Settings\All Users\Documents\My Pictures
WE::CSIDL_COMMON_VIDEO equate(037h)
! My Video folder for all users. For more information, see WE::CSIDL_MYVIDEO
WE::CSIDL_RESOURCES equate(038h)
!*C:\Windows\Resources. System resource directory.
WE::CSIDL_RESOURCES_LOCALIZED equate(039h) !*C:\Windows\Resources\0409 ! Localized resource directory. For more information, see WE::CSIDL_RESOURCES
WE::CSIDL_COMMON_OEM_LINKS equate(03Ah)
!*Folder containing links to OEM specific applications for all users.
WE::CSIDL_CDBURN_AREA equate(03Bh) !*C:\Documents and Settings\username\Local Settings\Application Data\Microsoft\CD Burning
WE::CSIDL_COMPUTERSNEARME equate(03Dh)
! Computers Near Me folder. Virtual folder that contains links to nearby computers on the network. Nearness it is established by common work group membership.


Note: You cannot use CSIDL_CONTROLS, CSIDL_PRINTERS, and CSIDL_DRIVES as these are all virtual drives, and the windows API returns empty strings for these equates.

Returns

String with specified path (in shortpath format). To convert to a longpath, use the longpath() function.

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

Note (a comparison for XP and Vista returns):

WE::CSIDL_Common_Appdata
    XP    C:\Documents and Settings\All Users\Application Data
    Vista    C:\ProgramData

WE::CSIDL_AppData
    XP    C:\Documents and Settings\user.domain\Application Data
    Vista    C:\Users\user\Roming

WE::CSIDL_Local_Appdata
    XP    C:\Documents and Settings\user.domain\Local Settings\Applicatin
Data
    Vista    C:\Users\user\AppData\Local

WE::CSIDL_Program_Files
    XP    C:\Program Files
    Vista    C:\Program Files

ds_GetTempPath

ds_GetTempPath()

Description

Returns the path to the windows temporary directory.

Parameters

None

Returns

String containing the path.

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

ds_String2File

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

Description

Takes a string and saves it to a file.
The file is created if it does not exist. The file is emptied if it does exist.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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_File2String(ds_StringRef pStringRef,<long pMaxLen>,string pFileName)

Description

Reads a file into a string.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode.
See ds_ErrorCode for more info.

NB: You must dispose the returned string after using the contents in order to avoid memory leaks (if the function succeeds):

dispose(TestFileRead.bin)

Example
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())
       !No need to dispose if it failed
  else
    DisplayString = TestFileRead.bin ! string read from file.
    DisplayLength = TestFileRead.len ! Length of string read from file.
    dispose(TestFileRead.bin)
  end

ds_GetHModule

ds_GetHModule (<string pModuleName>)

Description

Gets a handle to the specified module or if omitted to the current module. This is used with the ds_GetHIcon function.

Parameters
Parameter Description
pModuleName (string)Optional string containing the name of the required module.

Returns

A ulong handle to the the specified module or if omitted to the current module.

Example
Example
hModule ulong
  code
  hModule = ds_GetHModule() ! returns handle to current module.

  hModule = ds_GetHModule('MyIcons.dll') ! returns handle to MyIcons.dll

ds_GetHIcon

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

Description

Gets a handle to the compiled-in icon. If the icon is not in the current module then a handle to the module must be supplied. The icon size may be specified ie 16X16 or 32X32 or 48X48. If the icon size is not specified then the first icon in the resource is loaded.

Parameters
Parameter Description
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

A ulong handle to the the specified icon. Zero is returned if the function fails.

Example
Example
hIcon ulong
  code
  hIcon = ds_GetHIcon('~MyIcon.ico') ! returns handle to compiled-in icon called 'MyIcon.ico'.

  hIcon = ds_GetHIcon('~MyIcon.ico',ds_GetHModule('MyIcons.dll') ! returns handle to 'MyIcon.ico' in the DLL MyIcons.dll
  hIcon = ds_GetHIcon('MyIcon.ico',,48) ! returns handle to 48X48 icon inside the file 'MyIcon.ico'.
  ......
  ds_DestroyIcon(hIcon) ! Free memory

ds_CreateShortcutEx

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

Description

Create a shortcut to a file.  The shortcut can be placed on the desktop or in the START menu. Usually followed with a call to ds_RefreshDesktop.

Parameters
Parameter Description
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
pArguments (<string>)if you would like to add arguments (i.e. command line parameters) to the shortcut command line, then you can pass these in this parameter.
pReserved (<string>)reserved for future functionality.
Returns

Zero is returned if the function succeeds.

Example
Example
  code
  ds_CreateShortcutEx(clip(ds_GetFolderPath(WE::CSIDL_SYSTEM ,1)) & '\CALC.EXE',,,'Calculator!',CTRLALTC,clip(ds_GetFolderPath(WE::CSIDL_SYSTEM ,1)),'Calculator.LNK')

  ds_CreateShortcutEx('
C:\WINDOWS\SYSTEM32\CALC.EXE',,,'Calculator!',CTRLALTC,'C:\WINDOWS\SYSTEM32','Calculator.LNK','C:\Documents and Settings\Derek\Desktop','/debugfmall')
ds_RefreshDesktop()
This function replaces the deprecated ds_CreateShortCut function (which has no parameter for additional arguments).

ds_GetFileVersionInfo

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

Description

Used to return the file version data compiled into the EXE / DLL.

Parameters
Parameter Description
pDescription (string)Default='FileVersion'  The name version data required.

Standard descriptions are as follows:
CommentsInternalNameProductName
CompanyNameLegalCopyrightProductVersion
FileDescriptionLegalTrademarksPrivateBuild
FileVersionOriginalFilenameSpecialBuild
pFileName (*string)Default=Current Module.  The name including path of the file from which version data is required.

Returns

String. Returns info if found. If fails then returns empty string, see ds_Error() for more info.

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

ds_GetCurrentEXEDate

ds_GetCurrentEXEDate()

Description

Used to return the current date of the EXE.

Parameters

None

Returns

Long. Returns the date of the EXE.

Example
Example
  code
  CurrentEXEDate = ds_GetCurrentEXEDate()  ! returns the EXE date by default.

ds_LoadDLLProc

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

Description

Used to load a DLL into memory if it is not already loaded and then to return the call address of the specified DLL function.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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
Note: To use an external clarion DLL you need to do the following:

1. You must use the real procedure name from the Clarion DLL (this normally ends with @F - but you will need to check this using a tool such as libmaker.exe to find out the exact name of the function that is exported).

2. You need to add the pascal attribute to your procedure prototype.

ds_UnloadDLLProc

ds_UnloadDLLProc(*ulong pProcAddress,ulong pLibInstance)

Description

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

Parameters
Parameter Description
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GetDLLVersion(string pDLLName,*ds_DLLVersionG pDLLVerInf)

Description

Used to retrieve the version information from a windows DLL.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

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

Description

Used to send an SMS via a GSM modem.

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
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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
Note: If you want to use non-standard chars (like æøåÆØÅ) then you'll need to use their ASCII value equivalents in the string.

ds_GSMEnterPin

ds_GSMEnterPin(long pPID,string pPIN)

Description

Used to gain access to a SIM card in a GSM modem.

Parameters
Parameter Description
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMEchoOFF(long pPID)

Description

Used to turn off the echoing of commands sent to the GSM modem.

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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMSetSMSTextmode(long pPID)

Description

Used to set the GSM modem into text mode for the SMS send function.

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

Returns

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

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)

Description

Used to send an command to the GSM modem and wait for a response.

Note : Uses ds_Timer(999).

leading '<13>' (CR) and '<10>' (LF) characters in the modem response are discarded.
If the modem response starts with the command sent then this is also discarded. (modem echo)
ds_GSMGetReply starts with a call to ds_EmptyPort(pPID) before sending the command string.


Parameters
Parameter Description
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 =50 (0.50 secs).  This is the timeout for the first character of the modem response. You might need to increase this to  quite large (depending on the service provider). Some Providers require as much as 90 seconds (i.e. this timeout set to 9000). If you are getting intermittent or failed replies, then this is one possibility that should be adjusted.
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_EmptyPort(long pPID,long pTimeout=50)

Description

Used to save any unsolicited modem responses into an internal queue and to empty the com port input buffer.
Note : Uses ds_Timer(999).

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMReadSMSInit(long pPID,string pPIN)

Description

Used to prepare the GSM modem for reading the SMS list.

Note : ds_GSMReadSMSInit calls the following.

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

Parameters
Parameter Description
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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)

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

Description

Used to read the SMS memory from the GSM modem at the specified memory index.

Parameters
Parameter Description
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMDeleteSMS(long pPID,long pSMSIndex)

Description

Used to read the clear the SMS memory from the GSM modem at the specified memory index.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

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

Description

Used to enable SMS delivery reporting.
If the mobile to which the SMS is sent is turned off or out of range then the delivery report will be delayed until either the SMS is sent or the timeout lapses.

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

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMSelectSR(long pPID,byte pSRMemory=1)

Description

Used to select the SIM / device memory where the SMS delivery reports are stored.
Most GSM modems use a common area for SMS delivery reports and received SMS's. This command is necessary for those devices that use a separate memory area.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMReadSMSReportInit(long pPID,string pPIN)

Description

Used to prepare the GSM modem for reading the SMS delivery report list.
Note : ds_GSMReadSMSReportInit calls the following.

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

Parameters
Parameter Description
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

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

Description

Used to read the SMS delivery report memory from the GSM modem at the specified memory index.

Parameters
Parameter Description
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMDeleteSMSReport(long pPID,long pSMSReportIndex)

Description

Used to read the clear the SMS delivery report memory from the GSM modem at the specified memory index.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMReadEvents(long pPID,*ds_GSMEventG pERG)

Description

Used to check the GSM modem port for any unsolicited event reports. Returns the oldest event from the internal event queue.
This event is simultainiously deleted from the internal queue. The following call to ds_GSMReadEvents will return the next event if any.

Note : ds_GSMReadEvents calls ds_EmptyPort(pPID).

Parameters
Parameter Description
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

Long. Returns 0 for Success  else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMSetEvents(long pPID,long pEventsMask=255)

Description

Used to enable the sending of unsolicited event reports by the GSM modem.

Parameters
Parameter Description
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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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

ds_GSMReset(long pPID)

Description

Used to set the GSM modem back to factory settings.
This issues a AT&F command.

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

Long. Returns 0 for Success else ds_ErrorCode. See ds_ErrorCode for more info.

Example
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_OutputDebugString

ds_OutputDebugString(string pDebugString,byte pAddCRLF=1)

Description

Used to send (output) debug information to any windows debug viewer (like SysInternals' DebugViewer).

Parameters
Parameter Description
pDebugString (string) Debug info string.
pAddCRLF (byte)Add carriage return and line feed to the debugstring if set.
Returns

None

Example
Example
code
ds_OutputDebugString('Test to debug - view in something like DebugViewer from SysInternals)

ds_Debug

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

Description

Used to send (output) debug information to both the built-in debug viewer and any windows debug viewer (rather use ds_OutputDebugString if only sending to the windows debugviewer).
Note : Output suppressed unless command line switch "/debug" or ds_ViewDebug open.

Parameters
Parameter Description
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

None

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

ds_WineventDebug

ds_WineventDebug(byte pEnable)

Description

Used to send (output) debug information to both the builtin debug viewer and any windows debug viewer.
Note : Output suppressed unless command line switch "/debug" or ds_ViewDebug open.

Parameters
Parameter Description
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

None

Example
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

Description

Opens the WinEvent built-in debug viewer.

Parameters

None

Returns

None

Example
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

Description

Closes the WinEvent built-in debug viewer.

Parameters

None

Returns

None

Example
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

ds_Error(<long pThisErrorCode>)

Description

Returns the error message for a ds_ErrorCode().

Parameters
Parameter Description
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

String. Error message.

Example
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

ds_ErrorCode()

Description

Returns the current WinEvent error code.

Parameters

None

Returns

Long. Error code.

Example
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>)

ds_ErrorReset(<string pCallingProcedure>)

Description

Clears ds_ErrorCode and sets the calling Procedure name.

Parameters
Parameter Description
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

None

Example
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

Description

Use ds_SaveStack with ds_TestStack to check for stack corruption while calling external procedures.
If the ESP or EBP registers are corrupted then it sends an error to DebugView, displays a messagebox and a GPF is forced.

If other registers are changed then sends a message to DebugView. This is not necessarily an error - registers can be changed by a procedure call, but it may be useful to inspect this when debugging.

NOTE :
ds_SaveStack must be matched with a ds_TestStack otherwise a mismatch error will be reported.

Parameters

None

Returns

None

Example
Example
  code
  ds_SaveStack()
  ! some external procedure call.
  ds_TestStack()

ds_FormatHex

ds_FormatHex(ulong pDisplayValue,byte pPadSpaces)

Description

Returns a hexadecimal representation of the value.

Parameters
Parameter Description
pDisplayValue (ulong)The number to format as hex.
pPadSpaces (byte) The length of the hex number to return (leading zeros).
Returns

String. The hex string for the value.

Example
Example
DisplayHex    string(10)

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

ds_SetClipboard

ds_SetClipboard(ulong pClipFormat,string pNewContents)

Description

Places various format data into the windows clipboard.

Parameters
Parameter Description
pClipFormat (ulong)The format specifier.
pNewContents (string)The data to be placed in the clipboard.
pClipFormat ValuepNewContents requires:
WE::CF_BITMAPa handle to a bitmap memory space.
WE::CF_DIBa memory object containing a BITMAPINFO structure followed by the bitmap bits. DIB = Device-Independant Bitmap
WE::CF_DIBV5a memory object containing a BITMAPV5HEADER structure followed by the bitmap color space information and the bitmap bits.
WE::CF_DIF
WE::CF_ENHMETAFILEa handle to an enhanced metafile (HENHMETAFILE).
WE::CF_HDROPa handle to type HDROP that identifies a list of files. (see example below)
WE::CF_LOCALE
WE::CF_METAFILEPICTa handle to a metafile picture format as defined by the METAFILEPICT structure.
WE::CF_OEMTEXTa Text format string. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
WE::CF_PALETTE
WE::CF_PENDATA
WE::CF_RIFF
WE::CF_SYLK
WE::CF_TEXT a Text format string. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
WE::CF_TIFFa Tagged-image file format.
WE::CF_UNICODETEXTa Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
WE::CF_WAVEan audio data string in one of the standard wave formats, such as 11 kHz or 22 kHz Pulse Code Modulation (PCM).

Returns

Byte. Returns 1 for success, 0 for failure

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.
Example
data

hDropStruct group
pFiles             long  ! offset from here to FileList
pt                   ulong  ! drop point (in screen co-ords)
blank              ulong
fNC                 long   !Set for Non-Client area.
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>)

ds_ShutDown(<byte pForce>)

Description

Requests a windows shutdown.

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

Byte. Returns 1 for success, 0 for failure

Example
Example
  code
  ds_Shutdown() ! Request a windows shutdown.

ds_WinEventVersion

ds_WinEventVersion()

Description

Returns the current WinEvent version number.
This is handy for checking that the WinEvent DLL is the correct version for the application.

Parameters

None

Returns

Real. Returns the WinEvent version number.

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

ds_Ulong64ToReal

ds_Ulong64ToReal(long pULongHigh,long pULongLow),real

Description

Converts a long64 into a real. Use this function when working with API calls that return 64 bit longs.
Note that ulongs bigger than 52 bits will become approximate values when converted to reals. Ulongs up to 52 bits will be exact values.

Parameters
Parameter Description
pUlongHigh (long)The first 4 bytes of the ulong64.
pUlongLow (long)The last 4 bytes of the ulong64.

Returns

Real. The ulong64 value.

Example
Example
RealVar                    real
ulong64G                  group
High                           long
Low                            long
                                end

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

ds_SetOKToEndSessionHandler

ds_SetOKToEndSessionHandler(ulong pCallBackAddress)

Description

Installs an OKToEndSessionHandler for the Auto-shutdown functionality.

Parameters
Parameter Description
pCallBackAddress (ulong)The address of the OKToEndSessionHandler.
The OKToEndSessionHandler must be prototyped as :
MyOKToEndSessionHandler(long pLogoff),long,pascal

Returns

Ulong. Returns the old OKToEndSessionHandler.

Example
Example
OldHandlerAddress        ulong

  code
  OldHandlerAddress = ds_SetOKToEndSessionHandler(address(MyOKToEndSessionHandler))

ds_SetEndSessionHandler

ds_SetEndSessionHandler(ulong pCallBackAddress)

Description

Installs an EndSessionHandler for the Auto-shutdown functionality.

Parameters
Parameter Description
pCallBackAddress (ulong)The address of the EndSessionHandler.

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

Returns

Ulong. Returns the old EndSessionHandler.

Example
Example
OldHandlerAddress        ulong

  code
  OldHandlerAddress = ds_SetEndSessionHandler(address(MyEndSessionHandler))

ds_SetNoEndSession

ds_SetNoEndSession(long pNoEndSession)

Description

Disables the Auto-Shutdown functionality.

Parameters
Parameter Description
pNoEndSession (long)When set (1) then the Auto-Shutdown is disabled.

Returns

None

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

ds_GetCurrentProcess

ds_GetCurrentProcess()

Description

Return a windows handle to the current process often required for API calls.

Parameters

None

Returns

long. hProcess, handle this process.

Example
Example
long     hProcess

  code
  hProcess = ds_GetCurrentProcess()

ds_GetCurrentThread

ds_GetCurrentThread()

Description

Return a windows handle to the current thread often required for API calls.

Parameters

None

Returns

long. hThread, handle to this thread.

Example
Example
long     hThread

  code
  hThread = ds_GetCurrentThread()

ds_GetProcessTime

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

Description

Returns the CPU usage of this process in clarion time.

Parameters
Parameter Description
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

real. Time in 1/100 seconds.

Example
Example
real    UserTime

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

ds_GetThreadTime

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

Description

Returns the CPU usage of this thread in clarion time.

Parameters
Parameter Description
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

real. Time in 1/100 seconds.

Example
Example
real    UserTime

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

ds_SetRealTimePriority

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

Description

Selects Real Time or Normal priority for a thread.

Parameters
Parameter Description
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

None

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

Frequently Asked Questions (FAQ's)

I'm getting compile errors

TaskBar/SystemTray Questions:

1.1 I'd like to also change the taskbar button tooltip - how do I do this?
1.2 My application still appears on the Taskbar.
1.3 I want to hide my application to the taskbar, what's the best way to do this
1.4 My icon does not appear in the SystemTray

Comport Questions:

C.1 How do I open a serial port cash drawer using WinEvent?

C.2 I use a virtual comport USB to COM convertor. After some time the comport closes down.

General Questions:

2.1 Cannot get my application to auto-shutdown.
2.2 Instances of the WinEvent template appear after importing procedures from another application.
2.3. Are there any parallel port functions included in WinEvent?

1.2 Question: I am trying to use the 'WinNotOnTaskBar' extension template on my frame so that my application does not appear on the task bar, but it still appears.

Answer: This extension template places a call to a function called WinNotOnTaskBar before the open window command. If you have a 3rdparty or source coded call to open a different window before this function is called, it will not work. You may need to manually code a call to this function before the 3rdparty/source coded window is called.

1.3 Question: I want to hide my application to the taskbar, what's the best way to do this

Answer:
  1. Use the TaskBar extension
  2. Use the 2 routines (WindowHide and WindowShow) in the example code for the WinOnTop function to Hide and Show your Window.
1.4 My icon does not appear in the SystemTray

Answer: Your application is not finding the icon to place in the system tray. Rather include the icon into the project and use ~myicon.ico (in the AddIcon to system tray). If in doubt - check the example (that ships with WinEvent) for how it's done in there.

C.1 Question: How do I open a serial port cash drawer using WinEvent?

Answer: You need to find out the character to pass on the port to the cash drawer (to perform the open) and handle this in a normal coms port operation:

Portid = newport('com' & left(port) & ':' & baudrate & ',n,8,1')
!Handle error here.
bytesent=writeport(portid,drcode,0)
closeport(portid)


C.2 Question: I use a virtual comport USB to COM convertor. After some time the comport closes down.

Answer: 2.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).

2.2 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)


    Do a search for NAME WinEvent WinEvent and the immediately preceding [ADDITION] marks the start of the template prompts and the next [ADDITION], [WINDOW] or [CALLS] statement marks the end of the template prompts.
2.3. Question: Are there any parallel port functions included in WinEvent?

Answer: No. WinEvent does not include a parallel port library in it's functions.

Compile Errors

Compile Error screenshot

This means that you're still using old equates (before the WinEvent equates were changed in 3.37). Basically you need to add the WE:: prefix to all handcoded: WM_, CSIDL_, WTS_, NIIF_ and CF_ variables so:

WM_QUERYENDSESSION will become WE::WM_QUERYENDSESSION

Compile Error screenshot

You are compiling in LIB mode and you have another LIB file that includes the WinEvent LIB file (like the ezHelp LIB). You must check the 'Don't link in the WinEvent lib' checkbox on the settings tab of the WinEvent global template.

Unresolved External $WE::CANTCLOSENOW in globa002.obj
Unresolved External $WE::MUSTCLOSE in globa002.obj
Unresolved External $WE::CANTCLOSENOW in globa006.obj
Unresolved External $WE::MUSTCLOSE in globa006.obj
Unresolved External $WE::CANTCLOSENOW in globa024.obj
Unresolved External $WE::MUSTCLOSE in globa024.obj
Unresolved External $WE::CANTCLOSENOW in globa031.obj
Unresolved External $WE::MUSTCLOSE in globa031.obj


You must add WinEvent to your data dll, and in the Multi-DLL tab of the global template, check both the "This is part of a Multi-DLL program" and the "Export WinEvent data from this DLL" checkboxes. In all your other DLLs, you should check the "This is part of a Multi-DLL program" checkbox, leaving the "Export WinEvent data from this DLL" checkbox unchecked.

Version History

Download latest version here

Version 3.99 (29 February 2016)
Version 3.98 (29 February 2016) Version 3.97 (17 August 2015) Version 3.97 (17 August 2015) Version 3.96 (28 March 2015) Version 3.95 (24 March 2015) Version 3.94 (25 February 2015) Version 3.93 (18 February 2015) Version 3.92 (10 February 2015) Version 3.91 (4 February 2015) Version 3.90 (8 January 2015) Version 3.89 (25 November 2014) Version 3.88 (20 September 2014) Version 3.87 (22 August 2014)
Version 3.86 (20 January 2014) Version 3.85 (28 October 2013) Version 3.84 (27 August 2013) Version 3.83 (24 April 2013) Version 3.82 (31 January 2013) Version 3.81 (14 January 2013) Version 3.80 (9 October 2012) Version 3.79 (7 May 2012) Version 3.78 (13 March 2012) Version 3.77 (5 October 2011) Version 3.76 (20 July 2011) Version 3.75 (15 April 2011) Version 3.73 (19 July 2010) Version 3.72 (25 May 2010) Version 3.71 (13 May 2010) Version 3.70 (25 February 2010) Version 3.69 (24 February 2010)
Clarion 7.1 issue: Was not shutting down in a non-MDI with Global Shutdown. Version 3.68 (22 January 2010) Version 3.67 (21 January 2010) Version 3.66 (20 January 2010) Version 3.65 (29 December 2009) Version 3.64 (27 October 2009) Version 3.63 (12 August 2009) Version 3.62 (28 July 2009) Version 3.61 (15 July 2009) Version 3.60 (19 June 2009) Version 3.59 (18 March 2009) Version 3.58 (13 March 2009) Version 3.57 (10 November 2008) Version 3.56 (30 October 2008) Version 3.55 (23 October 2008) Version 3.54 (3 July 2008) Version 3.53 (24 June 2008) Version 3.52 (15 November 2007) Version 3.51 (9 November 2007) Version 3.50 (6 November 2007) Version 3.49 (22 June 2007) Version 3.48 (26 April 2007) Version 3.47 (25 April 2007) Version 3.46 (23 November 2006) Version 3.45 (13 October 2006) Version 3.44 (20 July 2006) Version 3.43 (12 July 2006) Version 3.42 (6 June 2006) Version 3.41(22 May 2006) Version 3.40 (10 May 2006) Version 3.39 (12 April 2006) Version 3.38 (27 March 2006) Version 3.37 (20 March 2006) Version 3.36 (16 March 2006) Version 3.35 (20 February 2006) 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)