CapeSoft.Com
Clarion Accessories
WinEvent
Documentation
Download Latest VersionIndex FAQ History
CapeSoft Logo

CapeSoft WinEvent
Documentation

Installed Version Latest Version

Introduction

Welcome to WinEvent.

WinEvent is a collection of useful functions that can be used to extend the functionality of your program, and save yourself a lot of time.

The functions are collected together into groups and include things like RS 232 (Serial Port) Reading and Writing, WinAlert for trapping windows messages, Taskbar function, System functions, Window behavior functions, and more. Most of the functionality provided by WinEvent is built into Windows itself in one way or another. WinEvent wraps these API calls into simple Clarion functions that you can easily use in your own code.

WinEvent requires StringTheory

WinEvent is shipped as source code, and does not include any black-box DLL's.

All WinEvent functions can be used in ABC or Clarion(Legacy) programs.

WinEvent functionality is broadly divided various areas:

Windows message capturing functions (WinAlert)

WinAlert allows your program more access to the native Window messages.

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 (Serial) Port functions (over USB)

With the demise of the popular Serial port from PC's in the early 2000's there has been a perception that RS 232 functions are no longer applicable to today's programs. However many hardware devices now connect to a computer using USB, and one subset of the ways USB interacts with those devices is still RS 232. In other words, the plug may be different, but many external hardware devices still communicate using RS 232 functions.

This simple functionality is built into the Windows API, but is quite complex and difficult to code. The Comms section of the WinEvent package provides some simple easy-to-use functions that allow you to read and write to Comm's ports. The library also corrects a bug in the Windows functions that affect communications at speeds of greater than 19200.

Taskbar functions

The taskbar functions allow you to add / change and delete an icon from the "System 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.
These tray icons can display notifications, and there is also a function that prevents your program from appearing on the main area of the Taskbar itself.

Window behavior functions

A small group of functions that allow you to change the behavior 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.
In addition a simple template exists which ensures that the window is always visible to the user (whether it is a non MDI window, or the child of a Frame) so that it does not appear outside the bounds of what the user can see. This is especially useful when users change monitor layout (like when disconnecting a laptop from an external monitor.)

System functions

These functions return system information to your application. The Windows version numbers are available to your application. Also you are able to get the current free disk space. This is useful for detecting low disk space conditions before they occur. A function for playing a wav file is also included.

Other

License and Copyright

WinEvent is copyrighted © 2024 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?)

This product is provided as-is. CapeSoft Software and CapeSoft Electronics (collectively trading as CapeSoft), their employees and dealers explicitly accept no liability for any loss or damages which may occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

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

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

Support

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

You can contact CapeSoft in one of the following ways:

CapeSoft Support
Email
Telephone 087 828 0123 or
+27 87 828 0123

Installation

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

Distribution

There are no WinEvent files that need to be distributed with your program.

How To Read this Manual

This manual is split into several sections.

The User guide discusses the functions in context, as they apply to each other. This covers specific functionality which is achieved when groups of functions are used together.

The Template guide covers all the templates, what they do, how they are used, and what each setting does.

The Reference section includes an index of functions grouped by context, as well as an alphabetical list of all the functions. Each function is explained in detail, along with parameters, return values and so on.

Example Programs

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

There is also an example of a barcode collector program, which uses a RS 232 Barcode reader attached via a USB cable. This is stored in \Clarion\Examples\Winevent\Barcode

Add WinEvent To Your Program

To use the WinEvent functions in your application you must first enable them by adding a global extension.

Open your application and go to the Global Extensions tab.
Click on the Insert button to add a new extension.
Select the EnableWinEvent extension from the list.

The Settings tab contains a number of common features which you may want to immediately add to your program. You can find more information on these settings in the template documentation.

Clarion Template (Legacy) applications

Programs based on the Clarion (Legacy) template chain need to Allow the use of ABC Classes, or they will GPF on startup. For more information on setting this, see here.

Multi-DLL applications

If your product is a set of apps, then you will need to add the WinEvent extension to each app in turn, enabling or disabling the options in each app.

In addition you will need to go to the Multi-DLL tab and set the settings there.

In the DATA DLL (the one that contains, and exports your dictionary) set both checkboxes on this tab ON.
This is part of a Multi DLL program and Export WinEvent from this DLL.

For all the other apps in the system, including the DLL apps and the EXE app, tick on only the first option;
This is part of a Multi DLL program

Hand-Code Applications

  1. WinEvent makes use of StringTheory. So make sure StringTheory is added as well per the instructions here.
  2. Add
    include('WinEvent.Inc'),Once
    to your main module
  3. Add the WinEventLinkMode and WinEventDllMode project defines to your project. Set 
    WinEventLinkMode=>1 
    if the class should be linked into the project, and 
    WinEventDllMode=>1
    if the object is exported from another DLL.
  4. WinEvent makes use of a CriticalSection, which is declared in CwSyncHC.Inc. This in turn makes use of the _ABCLinkMode_ and _ABCDllMode_ defines. So these must be set as well.

Note that's it's ultimately important to include ALL the settings, even the ones that are zero. For example;
StringTheoryLinkMode=>1;WinEventLinkMode=>1;StringTheoryDLLMode=>0;WinEventDLLMode=>0;_ABCLinkMode_=>1;_ABCDLLMode_=>0

 


Upgrading WinEvent

Upgrading WinEvent is usually trivial - just install the new build - however occasionally breaking changes are introduced. This section contains documentation for upgrading if you go past one of these boundaries.

Upgrading from WinEvent 4

Upgrading from one version of WinEvent to the next has always been simple. This update is no different. You can mostly just install the WinEvent 5 install file, recompile your application, and continue. Each program is different though, and this section however covers any common problems you may encounter.
  1. The deprecated variable WINEVENT:Version has been removed. Use WinEvent:TemplateVersion instead.
  2. If you are using SelfService then make sure you are on build 3.47 or later.
  3. If you are using GPF Reporter then make sure you are on build 2.34 or later.

Clarion Template (Legacy) applications

Programs based on the Clarion (Legacy) template chain need to Allow the use of ABC Classes, or they will GPF on startup. For more information on setting this, see here.

ds_SetClipBoard

The ds_SetClipBoard function has changed sufficiently that it has been renamed to ds_SetClipboardEx. If you have used this function in your applications then you will get a compile error when the call is encountered. This is deliberate so that you can review the call, and alter it if necessary. The primary change is as follows;
  1. When calling ds_SetClipBoard with WE::CF_HDROP as the first parameter, then you used to pass in a hDropStruct structure as the second parameter. This is no longer required. The second parameter in this instance is simply a filename (or list of filenames). For more information on this function see  ds_SetClipboardEx.
  2. ds_SetClipBoardEx can take either a STRING or a STRINGTHEORY object as the second parameter.

Legacy App Crashes on Startup

The WinEvent class makes use of Critical Sections. These require that the _ABCDllMode_ and _ABCLinkMode_ defines be added to your project. The best way to add these is
  1. Go to the Global Properties tab
  2. Actions button
  3. Classes Tab
  4. Tick on the option "Enable the use of ABC Classes". (This doesn't include ABC in your app, but it does set the project defines.)

Alt-Fix

Many years ago a problem surfaced in Clarion 6 programs running on Windows 7. The program would crash if the Right-Alt key on the
keyboard was pressed. Two (freeware) templates emerged (one by Carl Barnes, and one by Marius van den Berg) which solved the problem.

In 2017 a similar problem emerged again, this time with Clarion programs running on Windows 10 (version 1607 or later).

While both templates from the Clarion 6 days are still available, and work well, this seemed like a good addition to WinEvent as well.

The option can be turned on (or off) globally. Local windows can be set to either use the global setting (Default) or explicitly turn the feature on or off.

User Guide

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 used 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 two 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 ULong) and l for Long). On receiving the User event, WinMessageEvent you can use two 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.

Using WinAlert in Applications

The Local 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 winevent.inc file (which is found in your Clarion\accessory\libsrc\win folder).

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:
  • None will do nothing further with the event received.
  • Post WinMessageEvent will post the user event on to the Event handler (which means you can run code when that event is passed to the event handler).
    case Event() - WinMessageEvent
    of 0 ! WinMessageEvent
      !Put your code in here to process when this event is received.
  • Post Equivalent Event will assess the received windows message and post a suitable Clarion equivalent to the window as follows:
Windows Message Clarion Event posted
WE::WM_CLOSE Event:CloseWindow
WE::WM_MOUSEMOVE
WE::WM_NCMOUSEMOVE		 Event:MouseMove
WE::WM_TIMER Event: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, in order to determine whether the mousewheel is scrolled forward or backward, use the WinParam1() function. The positive value indicates a scroll up and the negative value indicates a scroll down.

Control
Use this to alert the messages for a specific control. Some controls process messages internally and don't pass them up to the window. For example, the WE::WM_KEYUP message is trapped by Text controls, and not passed up to the window, so you can't detect it there. In order to detect a WE::WM_KEYUP message on a Text control you would need to alert it for that specific control (or control type).

ControlType
Alerts the message for all the controls on the window of this specific type. For example set this to Text to trap the message for all Text controls on the window.

Using WinAlert in Hand Code or Embed Code

This details how to hand code WinAlert functionality in your window. This can be applied to a to a hand-coded project or just embedded code in a normal window procedure. 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.

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). Note that many devices will no longer use an actual RS232 Serial port connector, but will instead use a USB connector to connect to the PC. Regardless of the connector used the method a program uses to talk to Serial devices remains the same, and WinEvent comms functions make this easy.

Serial Port vs Keyboard Wedge

Barcode readers are one example of a serial device often connected to a PC. Typically these readers come in two forms. One approach is for the reader to act as a keyboard, often plugging into a PC between the keyboard itself, and the keyboard port in the PC. This kind of device is easy to manage in the program, since the input is exactly the same as if the user physically typed the information at the keyboard. the primary disadvantage is that the text goes to whatever program, window and control which has the focus. So it is easy for data to get lost if the user changes to another program or window.

The second approach is to use a serial port. This allows the data to come into the program in a completely different stream, and the data will arrive regardless of which program has the focus. This is more work for the programmer to manage but the result is a more reliable program. Given that the amount of effort is minimal, this is the approach which is recommended.

Port Number

When a device connects to a PC it is given a Port number. With a physical port this was usually Com1 or Com2 and so on. Think of this as the Address of the device. However with USB devices the device can be given a different port number if the device is disconnected and reconnected. Scanning for available devices can therefore be more important now than it used to be before. Some example code below of seeing which ports are allocated to a device is offered below.

Using Comm's functions in an Application

A local extension template is provided which generates some of the code below for you.

When a port is required it is opened with NewPort. This returns a PortID number, which is used in the later functions.

Writing to a port is done with WritePort. Bear in mind that Serial ports are very slow, so WritePort writes to an outgoing buffer, and returns immediately. The device has not actually received the data when this function returns.

Reading the port is done via a Timer event. As each event arrives the ReadPort function is called to see if any data is waiting. If it is then it can be processed. (Bear in mind that the serial port is really slow, so you may only have a partial message from the device at this point. You will need to buffer incoming data until a whole message has arrived.

Once communications have ended the port should be closed with ClosePort.

Example

In this annotated example, a port is opened and data is read from the port into a buffer. When a Carriage Return (chr(13)) is received in the buffer then a whole message has been received.

Tip: Use a String not a Cstring for the buffer. Cstrings can not handle chr(0).

portid         long        ! The "handle" of the port used after it is opened.
buf            string(1)   ! A string to hold incoming character
bytesreceived  long
mespos         long        ! The current incoming position in the message
message        string(255)
command        string(10)
  CODE
  OPEN(Window)
  portid = newport(clip(command(1)) &':9600,n,8,1') ! Open the port
  IF PortId >= 0
    command = 'next<13,10>'
    WritePort(portid,command,6)   ! write a string to the port
  END
  ACCEPT
     CASE EVENT()
     of Event:timer
        IF PortId >= 0
          LOOP
            bytesreceived = ReadPort(portid,buf,1) ! read 1 char from the comms buffer
            if bytesreceived = 0 then break.  ! nothing waiting
            if buf[1] = '<13>' ! is the char an 'end of message' ?
                ! handle completed message here
                mespos = 0
                WritePort(portId,command,6)
                cycle   
            end
            mespos += 1
            message[mespos] =  buf[1] ! add the char received to the message
          END
        END
    END
  END
  ClosePort(portId) ! Close the port when no longer needed

Functions supplied

Newport ; CountPort ;  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 hand code 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 behavior, 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.


  • The name of the icon to add is the filename of the icon to add to the systemtray. You can use a ~ to use icons included in the project.
  • The Icon tip is the text for the default tooltip that will appear. You can change this at runtime using the WinTaskBarChangeIcon function
  • Note: For use with services, you must use the icon handle to change the icon at runtime.
  • Use the Code to Run when Events are received button to get to the embed points to code in your handcode to run when handling received events. If you used the old embed points (where there was one button for each embed point on the template) - then check the Show Old Event Buttons checkbox and you will be able to edit your previous code through the Old Embeds tab.
  • The Add Show|Hide|Close Menu to right-click Popup option allows the template to build this functionality into the taskbar icon easily. These are pretty standard functions that you will probably require when using the taskbar functionality.
  • Checking the Hide Window on Startup option will ensure that your application opens in minimized mode when starting.
  • Checking the Not on Toolbar when Minimized will make sure that your window is removed from the taskbar when minimizing (so that it will only appear in the systemtray).
  • Checking the Only Close from popup menu will mean that when clicking the X button (the red x on the right side of the titlebar), the application is minimized instead of closing (as well as all other CloseWindow controls). This means that the user must exit through the correct option instead of merely clicking the X. If you would like to allow your user another method of exiting the application (like through a window option) then you can code the following:
WE::CloseAllNow = 1
post(event:closewindow)
  • Checking the Left click Icon shows window option will restore the window if the user clicks on the icon in the system tray.
  • You can use the Add items to the popup button to add other items to the popup menu. You will need to handcode these calls in as follows:
    WE::MouseRightPopup.AddItem('Process','Process the Records')

    You can use menus in the popup as well:

    WE::MouseRightPopup.AddItem('Menu','Menu','-',1)
    WE::MouseRightPopup.AddItem('Do it','Do it','Menu',2)
  • You can use the Handle new popup items button to add other items to the popup menu. You will need to handcode these calls in as follows (the code needs to appear between the 'Run popup for Show|Hide|Close' and the 'Perform Show|Hide|Close' embed points):
    of 'Process the Records'
    ProcessTheRecords()

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_WinTaskBarBalloon 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 Behavior Functions

Functions Supplied

WinOnTop ; WinNotOnTop ; WinBringToFront ; ds_WinTransparent ; ds_VisibleOnDesktop ; ds_ShowWindow ; ds_HideWindow

For a detailed description of each of the functions, see the Reference Section.

Windows System Functions

The goal of these functions is for your program to better understand the OS environment it is running on.

Some of the functions returns specifics about the version of Windows, or the way Windows is being used (via Terminal services, on a tablet and so on.)

Others return the machine name, user name, screen height and width, screen DPI settings and so on.

Windows Version Numbers

WinEvent provides the ds_GetWinVersion, WindowsVersion, WindowsRelease, DosVersion and DosRelease  functions so that your program can know what version of Windows it is running on. These in turn use the Windows API called GetVersion and GetVersionEx. It's important to note though that for backward compatibility reasons for these functions Windows returns a value that it believes your program will understand.

If your program does not include a manifest then the Windows version will be reported at (most) version 6.2, which is Windows 8. This is the value received even if the machine is really running Windows 8.1 or Windows 10 (or later.)

If the program does have a manifest, but the manifest does not indicate support for Windows 8.1 then again Windows 8 will be reported. 
IfIf the program has a manifest, and the actual Windows version is higher than the highest version support in your manifest, then the highest manifest version from your manifest will be reported.

You should use ds_GetWinVersion(), WindowsVersion, WindowsRelease, DosVersion, DosRelease if you are checking to see if some functionality is available or not.

Another function, ds_WindowsProductInfo is provided so that you can get the actual Windows version the program is running on. Use this for informational purposes only. Your program will behave as per the highest manifest version as described above.

Functions Supplied

ds_GetWinVersion ; WindowsVersion ; WindowsRelease ; DosVersion ; DosRelease ; Sound ; GetWindowsDir ; GetSystemWindowsDir ; ScreenWidth ; ScreenHeight ; ScreenDepth  ; ds_GetScreenDPI ; ds_GetUserName ; ds_GetUserAccountName ; ds_GetWorkstationName ; ds_IsMediaCenter ; ds_IsTerminalServer ; ds_IsTablet ; ds_IsStarter ; ds_OnNetwork ;
ds_OSBits ; 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 ; ds_DeleteValueReg

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_ExpandDirectory ; ds_SetFileDateTime ; ds_MoveFile ; ds_GetFolderPath ; ds_GetTempPath ; ds_String2File ; ds_GetFileSize
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 and 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

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.

Functions Supplied

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

For a detailed description of each of the functions, see the Reference Section.

Debugging and 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 ; GetWineventErrorCode ; GetWineventExtendedErr ; GetWineventErrProc
For a detailed description of each of the functions, see the Reference Section.

Auto Shutdown Functions

Concept

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.

Queue Functions

Concept

Records in queues that contains pointers need to be carefully deleted in order to avoid memory leaks. These functions make use of extended NAME attributes to identify pointers, and dispose them safely. For an extended discussion of this code, and the techniques it is using see ClarionLive Webinar #535.

Functions Supplied

 ds_DeleteQueue, ds_DisposeQueue, ds_FreeQueue

For a detailed description of each of the functions, see the Reference Section.

Other Functions

Functions Supplied

ds_FormatHex ; ds_SetClipboardEx ; ds_GetClipboardEx ; ds_ShutDown ; ds_WineventVersion ; ds_Ulong64ToReal ; ds_Round

For a detailed description of each of the functions, see the Reference Section.

Template Guide

Global Extension

Local Extension

Comm Port Extension

Taskbar Icon Extension

WinNotOnTaskbar Extension

Reference Guide

WinAlert functions

WinAlert
Winevent
WinControl
WinParam1
WinParam2
WinChangeUserEvent
WinSysEvent
WinSysParam1
WinSysParam2
WinWtsEvent
WinWtsID

Comms Functions

NewPort
ResetPort
ClosePort
KillAllPorts
WritePort
ReadPort
CountPort
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
ds_OSBits

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

Registry Functions

ds_GetReg
ds_PutReg
ds_DeleteValueReg

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
GetWineventErrorCode
GetWineventExtendedErr
GetWineventErrProc

Queue Functions

ds_DisposeQueue
ds_FreeQueue

Other Functions

ds_GetClipboardEx
 ds_SetClipboardEx

WinAlert

WinAlert (<Long FromMessage>, <Long ToMessage>, <Long Action>, <Long pField>, <Long pControlType> )

Parameters
Parameter Description
FromMessage The [first] Windows message to alert.
ToMessage The last Windows message to alert. If this parameter is omitted then only the FromMessage is alerted.
Action This defines the action required when the alerted message(s) are received. If this parameter is omitted then it defaults to PostUser + PassOn.
pField Only alert the message for a specific control on the window.
pControlType Only alert the message for all the controls of this type on the window
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 the 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
Equate Meaning
Return0  Return 0 to the function that sent the message.
Return1 Return 1 to the function that sent the message.
PassOn Pass the message on to the Clarion window for processing.
Group 2
Equate Meaning
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.
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

Examples

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

code
  open(window)
  WinAlert(WE::WM_KEYUP, WE::WM_KEYUP , PostUser + PassOn, ?SomeText ) ! alert all keys on ?someText control
  !!! All the normal processing goes here
  WinAlert()
  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 short The 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 pClearAfterRead Default 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 pClearAfterRead Default 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.
Value Meaning
WTS_CONSOLE_CONNECT
0x1		 A session was connected to the console session.
WTS_CONSOLE_DISCONNECT
0x2		 A session was disconnected from the console session.
WTS_REMOTE_CONNECT
0x3		 A session was connected to the remote session.
WTS_REMOTE_DISCONNECT
0x4		 A session was disconnected from the remote session.
WTS_SESSION_LOGON
0x5		 A user has logged on to the session.
WTS_SESSION_LOGOFF
0x6		 A user has logged off the session.
WTS_SESSION_LOCK
0x7		 A session has been locked.
WTS_SESSION_UNLOCK
0x8		 A session has been unlocked.
WTS_SESSION_REMOTE_CONTROL
0x9		 A session has changed its remote controlled status. To determine the status, call GetSystemMetrics and check the SM_REMOTECONTROL metric.
Example
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 pInBytes=512, long pOutBytes=512,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.
pInBytes Input buffer in bytes. If omitted then the default is 512 bytes.
pOutBytes Output buffer in bytes. If omitted then the default is 512 bytes.
pUseEvents Note: This feature is experimental and may not work.
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 which will be used by all the other functions.

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.

See Also

ReadPort, WritePort, CountPort, ResetPort, ClosePort, KillAllPorts

CountPort

CountPort(long PortId, long pWhichWay= buffer:in)

Description

Counts the number of characters in the incoming, or outgoing, port buffer.

Parameters
Parameter Description
PortId This is the port number as returned by the NewPort function.
pWhichWay One of buffer:in or buffer:out. If omitted or invalid then the default is buffer:in.

Returns: long

The number of bytes in the buffer.

Example
Example
result = CountPort(PortId)
result = CountPort(PortId,buffer:in)
result = CountPort(PortId,buffer:out)

See Also

NewPort, ReadPort, WritePort,  ResetPort, ClosePort, KillAllPorts

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

See Also

NewPort, ReadPort, WritePort, CountPort,  ClosePort, KillAllPorts

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)
See Also

NewPort, ReadPort, WritePort, CountPort, ResetPort, KillAllPorts


KillAllPorts

KillAllPorts ( )

Description

Closes all open ports.

Returns

Nothing

Example
Example
KillAllPorts()
See Also

NewPort, ReadPort, WritePort, CountPort, ResetPort, ClosePort

WritePort

WritePort(PortId long, *String pBuffer, Length long)
WritePort(PortId long, String pBuffer, Length long)
WritePort(PortId long, StringTheory pBuffer)

Description

Writes a string into the transmission buffer.

Parameters
Parameter Description
PortId (long) This is the port number as returned by the NewPort function.
pBuffer (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.
pBuffer (StringTheory) If the second parameter is a StringTheory object, then the length parameter does not need to be passed.
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

See Also

NewPort, ReadPort, CountPort, ResetPort, ClosePort, KillAllPorts

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

See Also

NewPort, WritePort, CountPort, ResetPort, ClosePort, KillAllPorts

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, <string pIconName>)

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) WE::NIIF_NONE  No icon.
WE::NIIF_INFO An information icon. (Default)
WE::NIIF_WARNING  A warning icon.
WE::NIIF_ERROR  An error icon.
WE::NIIF_USER The application icon.
WE::NIIF_NOSOUND   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
pIconName
(string)		 reserved - not currently used.
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
In Event:OpenWindow

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

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.

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 windows 10, but the app is only manifested for Windows 8, then this function will return Windows 8. If the app has no manifest then it will return Windows 8 for Windows 8 or higher.

Parameters

None

Returns

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

Win 10 - 10.0.17134


Example

  code
  DisplayString = ds_GetWinVersion()

See Also

WindowsVersion, WindowsRelease

WindowsVersion

WindowsVersion()

Description

Returns the major windows version number for the current version of windows.

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 windows 10, but the app is only manifested for Windows 8, then this function will return Windows 8. If the app has no manifest then it will return Windows 8 for Windows 8 or higher.

Parameters

None

Returns

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

The version number 5 is returned for Windows 2000, Windows XP, Windows 2003.

The version number 6 is returned for Windows Vista, Windows 2008, Windows 2008R2, Windows 7, Windows 2012, Windows 8, Windows 8.1 and Windows 2012R2.

The version number is 10 for Windows 10.

Example

  code
  ver = WindowsVersion()

See Also

ds_GetWinVersion, WindowsRelease

WindowsRelease

WindowsRelease()

Description

Returns the release number (minor version number) of the version of Windows that is running.

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 windows 10, but the app is only manifested for Windows 8, then this function will return Windows 8. If the app has no manifest then it will return Windows 8 for Windows 8 or higher.

Parameters

None

Returns

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

Windows 2000, Windows Vista, Windows 2008 and Windows 10 return 0

Windows XP, Windows 2008 R2 and Windows 7 return 1

Windows 2003, Windows 2012 and Windows 8 return 2

Windows 8.1 and Windows 2012 R2 return 3


Example

code
  ver = WindowsVersion()
  rel = WindowsRelease()

See Also

ds_GetWinVersion, WindowsVersion

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
Drive Optional. 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()

See Also

GetDiskSpace , ds_GetDiskMegs

GeGetDiskSpace

GetDiskSpace (<drive long>)

Description

Returns the total disk space, in bytes.

Parameters
Parameter Description
Drive Optional. 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()

See Also

GetFreeDiskSpace , ds_GetDiskMegs

ds_GetDiskMegs

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

Description

Returns the specified disk space, in megabytes.

Parameters
Parameter DeDescription
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
ExExample
total ulong
  code
  total = ds_GetDiskMegs()

See Also

GetDiskSpace, GetFreeDiskSpace

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

ds_GetReg(Long hKey, String SubKeyPath, String ValueName, Long p64=false)

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.
p64 (long) If True then the 64 bit registry is used. If false then the 32 bit registry is used.
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')

See Also

ds_PutReg

ds_PutReg

ds_PutReg(Long hKey, String SubKeyPath, String ValueName, String Value, Long Type=pType=REG_SZ, Long p64=false)

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.
p64 (Long) If True then the 64 bit registry is used. If false then the 32 bit registry is used.
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)

See Also

ds_GetReg, ds_DeleteValueReg

ds_DeleteValueReg

ds_DeleteValueReg(Long hKey, String SubKeyPath, String ValueName, Long p64=false)

Description

Deletes a value out the Windows System Registry (if the user has sufficient permissions to do so.)

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 delete.
ValueName (String) The name of the variable you want to delete.
p64 (long) If True then the 64 bit registry is used. If false then the 32 bit registry is used.
Returns

True if the delete is successful. If the read failed the the false is returned, and the Winevent extended error is set. The Winevent error can be retrieved using ds_Error and ds_Errorcode functions.

Example
Example


See Also

ds_PutReg, ds_GetReg

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

n long
  code
  n = ds_GetScreenDPI()

ds_GetUserAccountName

ds_GetUserAccountName(long pExtendedFormatOption=false)

Description

Retrieves the current user name for the process. Uses the Windows API call GetUserNameEx.

Parameters
Parameter Description
pExtendedFormatOption If false then the whole user name (including the domain) is returned. If true then only the user name part is returned.

Returns

A String containing the name.

ds_GetUserName

ds_GetUserName()

Description

Retrieves the current user name for the process. Uses the windows API call WNetGetUser.

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 connected to a network or not.

Returns

A long, 1 if true 0 if false.

Example

n  Long
  Code
  n = ds_OnNetwork()
  ! n = 0 or 1
 

ds_OSbits

ds_OSbits ()

Description

Detects if the current OS is a 32 bit or 64 bit OS.

Returns

32 if 32 bit, 64 if 64 bit.

Example

n  Long
  Code
  n = ds_OsBits()
  ! n =32 or 64

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
EntryGString string(size(EntryG)),over(EntryG)
 code
  ds_GetFileDirEntry('c:\FileName.ext',EntryGString) ! fills the EntryG with the files directory attributes.

ds_GetFileSize

ds_GetFileSize(string pFileName)

Description

Gets the size of the file on the disk

Parameters
Parameter Description
pFileName (string) Specify the file (with path) for which the size is required.

Returns

REAL - handles sizes over 2 gigabytes

Example
Example
r   Real
  code
  r = ds_GetFileSize('c:\FileName.ext')

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. This method is recursive, meaning that it will create multiple levels of folders in a single call if necessary to create the final folder.

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. If the directory already exists then the function returns true, for success. If you need to know if the folder preexists then use the Clarion EXISTS command before calling this function. If the path does preexist then the ds_ErrorCode() call will return WE:ERROR_ALREADY_EXISTS.

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_ExpandDirectory

ds_ExpandDirectory(String pFilename)

Description

Takes in a fully qualifies path & file name, and replaces tokens with the current user's details.

Parameters
Parameter Description
pFileName (string) A file name, including path.
Tokens
Token Example
%APPDATA% C:\Users\Bruce\AppData\Roaming
%COMMONDESKTOP% C:\Users\Public\Desktop
%COMMONDOCUMENTS% C:\Users\Public\Documents
%DESKTOP% C:\Users\Bruce\Desktop
%DROPBOX% c:\Users\Bruce\Dropbox
%LOCALAPPDATA% C:\Users\Bruce\AppData\Local
%ONEDRIVE% %USERPROFILE%\OneDrive
%PROGRAMDATA% C:\ProgramData
%PROGRAMFILES% C:\Program Files
%PROGRAMFILES86% C:\Program Files (x86)
%PROGRAMFILES(X86)% C:\Program Files (x86)
%USER% Bruce
%USERPROFILE% c:\Users\Bruce
%SYSTEM% C:\Windows\system32
%WINDOWS% C:\Windows
%WORKSTATION% Accounts
Returns

A string. Any tokens in the pFileName parameter are replaced. If no tokens exist then the pFileName parameter is returned unaltered.

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: https://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:
Comments InternalName ProductName
CompanyName LegalCopyright ProductVersion
FileDescription LegalTrademarks PrivateBuild
FileVersion OriginalFilename SpecialBuild
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-existent 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-existent 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-existent dll.  

  Debug string ! ds_LoadDLLProc error, LoadLibrary failed DLL=Non-Existent 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-existent 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-existent 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-existent 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_GetClipboardEx

ds_GetClipboard(Long pFormat)
ds_GetClipboard(Long pFormat, StringTheory rData)

Description

Retrieves various format data from the windows clipboard.

Parameters
Parameter Description
pFormat The format of the data.
pData A StringTheory object to receive the data which is currently on the clipboard.
pFormat Value pData requires:
WE::CF_BITMAP (subject to change) A handle to a bitmap memory space.
WE::CF_DIB (subject to change) A memory object containing a BITMAPINFO structure followed by the bitmap bits. DIB = Device-Independent Bitmap
WE::CF_DIBV5 (subject to change) A memory object containing a BITMAPV5HEADER structure followed by the bitmap color space information and the bitmap bits.
WE::CF_ENHMETAFILE (subject to change) a handle to an enhanced metafile (HENHMETAFILE).
WE::CF_HDROP A full path name (path and file name) to a file on the disk.
Alternatively a pipe-separated list of full path names.
WE::CF_METAFILEPICT a handle to a metafile picture format as defined by the METAFILEPICT structure.
WE::CF_OEMTEXT A string.
WE::CF_TEXT A string.
WE::CF_TIFF (subject to change) a Tagged-image file format.
WE::CF_UNICODETEXT A Unicode string encoded as UCS (utf-16).
WE::CF_WAVE (subject to change) An audio data string in one of the standard wave formats, such as 11 kHz or 22 kHz Pulse Code Modulation (PCM).

Returns

If not using the StringTheory parameter, then returns a String.
If using the StringTheory parameter: Long. Returns 1 for success, 0 for failure

Example

Example
str  StringTheory
code
If ds_GetClipboardEx(WE::CF_hDrop, str) = true
  str.split(',')
end

ds_SetClipboardEx

ds_SetClipboard(Long pFormat, String pData)
ds_SetClipboard(Long pFormat, StringTheory pData)

Description

Places various format data into the windows clipboard.

Parameters
Parameter Description
pFormat The format of the data.
pData The data to be placed in the clipboard.
pFormat Value pData requires:
WE::CF_BITMAP (subject to change) A handle to a bitmap memory space.
WE::CF_DIB (subject to change) A memory object containing a BITMAPINFO structure followed by the bitmap bits. DIB = Device-Independent Bitmap
WE::CF_DIBV5 (subject to change) A memory object containing a BITMAPV5HEADER structure followed by the bitmap color space information and the bitmap bits.
WE::CF_ENHMETAFILE (subject to change) a handle to an enhanced metafile (HENHMETAFILE).
WE::CF_HDROP A full path name (path and file name) to a file on the disk.
Alternatively a pipe-separated list of filenames - the first item in the list is the path, the second and subsequent items are the names of all the files.
WE::CF_METAFILEPICT a handle to a metafile picture format as defined by the METAFILEPICT structure.
WE::CF_OEMTEXT A Clarion string. The string is not clipped before putting it on the clipboard.
WE::CF_TEXT A Clarion string. The string is not clipped before putting it on the clipboard.
WE::CF_TIFF (subject to change) a Tagged-image file format.
WE::CF_UNICODETEXT A Unicode string encoded as UCS (utf-16).
WE::CF_WAVE (subject to change)  An audio data string in one of the standard wave formats, such as 11 kHz or 22 kHz Pulse Code Modulation (PCM).

Returns

Long. 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
filename   string(255)
  code
   filename = 'C:\autoexec.bat<' ! List of files
   if ~ds_SetClipboard(WE::CF_hDrop, filename ) ! 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_Round

ds_Round(real pValue,string pOrder),real

Description

Returns the rounded (to Order) of the Value. This function allows rounding to Orders other than straight 1 decimal and force up or force down (using plus or minus) as well as true rounding.

Parameters
Parameter Description
pValue (real) The value to be rounded.
pOrder (string) The order to round the value. The order value must be prepended with '+','-' or nothing.
'+' (and then the order) - returns the higher order closest to the value.
'-' (and then the order) - returns the lower order closest to the value.
Nothing (and then the order) - rounds the value up or down depending on the closest order.

Returns

Real. The rounded value.

Example
Example
  code
  RealVar = ds_Round(89.494,'-0.02')  !Returns  89.48
  RealVar = ds_Round(89.494,'0.02')  !Returns  89.50
  RealVar = ds_Round(89.484,'+0.02')  !Returns  89.50

 

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 Normal priority

ds_DeleteQueue

ds_DeleteQueue(*Queue pQueue)
Description

Queues that contain pointers (to strings, other queues, and StringTheory objects) need to be deleted carefully in order to avoid memory leaks. This function makes use of extended name attributes to identify pointers, and delete the row without leaking memory.

Recognized extended name attributes include &string, &pstring, &cstring, stringtheory, &stringtheory, queue, &queue.

Parameters
Parameter Description
pQueue The Queue. The currently loaded record in the queue will be deleted.
Returns

Nothing

Example
Example
InvoiceQueueType Queue,TYPE
Date               Long,name('Date | @D3')
Amount             Long,name('Amount')
Paid               Byte,name('Paid Amount | Boolean')
                 End
CustomerQueue    Queue,pre(cust)
Reference          &String, name('Reference | &String')
Remarks            &StringTheory, name('Remarks | StringTheory')
Date               Long, name('Date | @D010-')
Cstr               &Cstring, name('cstr | &CString')
Pstr               &Pstring, name('pstr | &PString')
Invoices           &InvoiceQueueType, name('Invoices| Queue')
                 End
  code
  get(CustomerQueue,2)
  ds_DeleteQueue(CustomerQueue)

See Also

ds_DisposeQueue, ds_FreeQueue

ds_DisposeQueue

ds_DisposeQueue(*Queue pQueue)
Description

Queues that contain pointers (to strings, other queues, and StringTheory objects) need to be deleted carefully in order to avoid memory leaks. This function makes use of extended name attributes to identify pointers, and deletes all the rows without leaking memory.

Once the rows are deleted the Queue pointer itself is DISPOSE'd

Parameters
Parameter Description
pQueue The Queue to Dispose
Returns

None

See Also

ds_FreeQueue, ds_DeleteQueue

ds_FreeQueue

ds_FreeQueue(*Queue pQueue)
Description

Queues that contain pointers (to strings, other queues, and StringTheory objects) need to be deleted carefully in order to avoid memory leaks. This function makes use of extended name attributes to identify pointers, and deletes all the rows without leaking memory.

Parameters
Parameter Description
pQueue The Queue to Free.
Returns

None

See Also

ds_DisposeQueue, ds_DeleteQueue

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:
  • It is possible the SYSTEM is not checked on the window controlling the USB port (take note, this has other ramifications, but may be required in order to control the USB to COM convertor). Window WINDOW(.., TIMER(1),SYSTEM,
  • Set the timer instead of 1 to 10 or higher.
  • Make sure that you are using the latest driver version for the hardware that you are using.
  • Some cheap hardware will manifest this behaviour.
  • Some pc settings allow screensaver to power down the USB ports.
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 5.44 - 23 October 2024
  • Add: Update to function ds_GetClipboardEx to use a pipe separated list, not a comma separated list.
Version 5.43 - 9 October 2024 Version 5.42 - 25 July 2024
  • Add: New function ds_GetFileSize which returns the file size as a REAL, ie handles files > 2 gigs in size.
Version 5.41 - 6 March 2024
  • Fix: WritePort could Duplicate Identifier in Data Dll.
  • Fix: Alternate WritePort calls were not being exported from the Data DLL
Version 5.40 - 5 March 2024
  • Add:  GetLastWindowsError() function to return the Windows LastErrorCode as set in ds_Error().
Version 5.39 - 13 February 2024
  • Reversion: Changes to ds_CreateDirectory caused problems. Documentation updated to reflect actual behavior.
Version 5.38 - 22 January 2024
  • Added GetWineventErrorCode(), GetWineventExtendedErr(), GetWineventErrProc() functions.
  • Fix: ds_CreateDirectory did not stop on first error, and did not set error values unless debugging was on.
  • Fix: Tidied up some error handling code.
  • Fix: ds_DeleteValueReg used wrong handle.
  • Internal: Update to Capexx.tpw version 4.31
Version 5.37 - 30 October 2023 Version 5.36 - 5 July 2023
  • Update: Allow longer names for Windows Messages
  • Fix: Possible redeclaration of %pd
Version 5.35 - 27 October 2021
  • Add: Support for Windows 11 to ds_GetWinVersion
  • Remap: WE::CSIDL_MYDOCUMENTS to WE::CSIDL_PERSONAL
Version 5.34 - 24 May 2021
  • Clarion 11.1 Install
Version 5.33 (17 February 2021)
  • Fix: name clash on TIMEDATE
Version 5.32 (13 October 2020)
  • Fix: Declaration of CapsLockKeyPressed moved to it's own embed so as not to clash with Secwin 7 when using Clarion 8.
Version 5.31 (14 September 2020)
  • Fix: ds_TimeZoneInformationG structure was incorrect.

Version 5.30 (24 August 2020)
  • Tweak: KEY_ALL_ACCESS Equate changed to use STANDARD_RIGHTS_REQUIRED not STANDARD_RIGHTS_ALL.
  • Change: New parameter to ds_GetReg and ds_PutReg to access 64 bit registry.
  • Fix: Passing a zero length to WritePort could cause a problem.
Version 5.29 (2 December 2019) Version 5.28 (20 June 2019)
  • Fix: CountPort exported by template in Data DLL.
Version 5.27 (18 June 2019)
  • Add: CountPort function.
  • Update: Formatting of Comms Port documentation.
Version 5.26 (8 March 2019)
  • Add: %USERPROFILE%, %DROPBOX% and %ONEDRIVE% to ds_ExpandDirectory.
  • Fix: ds_Focus in TPL should have been ds_SetFocus.
Version 5.25 (8 March 2019) Version 5.24 (10 December 2018)
  • Add: Section to documentation on using WinEvent in Hand-Coded projects.
  • Major Change : ds_SetClipboard method removed, replaced with ds_SetClipBoardEx. (see Upgrading section). (Many thanks to Sean Henessy
  • Fix: Problem with excessive handling of event:moved
Version 5.23 (12 November 2018)
  • Fix: Reversed change in 5.22 - causing other problems.
Version 5.22 (27 October 2018)
  • Fix: Problem with ds_VisibleonDesktop for MDI child windows with Maximize attribute set on.
Version 5.21 (12 October 2018)
  • Work-Around: Regression in Clarion 11 (PTSS 42753) which affects generate-date feature.
Version 5.20 (13 September 2018)
  • Add: Clarion11 to install.
Version 5.19 (15 August 2018)
  • Actual number values for some Event: equates have changed. Should not affect code which is using equates.
  • Keycode() is set when trapping various mouse events.
  • Init code set to come after EzHelp init code.
Version 5.18 (21 June 2018)
  • Some code tidy up, and new equates.
Version 5.17 (31 January 2018)
  • Tweak:  ds_GetUserAccountName doesn't just return first found name type.
  • Template: Cape common templates updated to version 4.12
Version 5.16 (30 January 2018)
  • Add: ReadPort and WritePort versions that take a StringTheory parameter.
  • Fix: ds_GetUserAccountName refactored (thanks to Mateusz Borowski)

Version 5.15 (7 December 2017)
  • Fix: DWORD equate in WinEvent.Inc changed from LONG to ULONG.
Version 5.14 (24 November 2017)
  • Fix: ds_OsBits not exported from Data DLL's.
Version 5.13 (30 October 2017)
  • Refactor: IconQueue renamed to we:IconQueue. IconHandleQueue renamed to we:IconHandleQueue to avoid naming conflict with UltraTree.
Version 5.12 (28 July 2017)
  • Add: Event:MousewheelPlus and Event:MouseWheelMinus
  • Add: Field to Events posted.
Version 5.11 (2 June 2017)
  • Add: ds_OSBits function.
  • Add ability to Alert messages for specific controls, or specific control types in WinAlert function.
Version 5.10 (31 May 2017)
  • Change: Template checks for controls with KEY settings before alerting F10, CtrlF10 and Shift F10.
Version 5.09 (26 April 2017)
  • Add: Support for Alt-Fix added. (On by default.)
Version 5.08 (24 April 2017)
  • Change: Some items relabeled with we: prefix to avoid linker clashes with other libraries.
  • Fix: ds_FormatFastTime removes trailing . if places parameter = 0.
Version 5.07 (1 February 2017)
  • Fix: If (non MDI) window was opened Maximized then it would resize to allow more space for the Windows Start bar.
  • Documented: Legacy programs need Allow Use of ABC ticked on.
Version 5.06 (24 November 2016)
  • Fix: GetFreeDiskSpace function could return the wrong value when value was large.
Version 5.05 (14 November 2016)
  • Fix: Fixed documentation in template to not refer to Clarion 6 anymore.
Version 5.04 (28 October 2016)
  • Change: Renamed GUID type to avoid clash with svcomdef.inc.
  • Fix: If Closedown support off, procedures did not export from Data DLL.
Version 5.03 (21 October 2016)
  • Edited: Problem comment in wineve.a
  • Change: added we: prefix to equates to avoid clash with Clacom. (we:NOPARITY, we:ODDPARITY, we:EVENPARITY, we:MARKPARITY, we:SPACEPARITY, we:ONESTOPBIT, we:ONE5STOPBITS, we:TWOSTOPBITS).
  • Change: Changed Equate ERROR_SUCCESS to we:ERROR_SUCCESS.
Version 5.02 (18 October 2016)
  • Add: Template code to remove reference to CLAWE from the solution. (Clarion 9 and up only.)
  • Change: IID renamed to ws:IID, CLSID renamed to we:CLSID. (conflict with Office Inside)
  • Change:  HKEY_LOCAL_MACHINE and HKEY_USERS Equates removed. (conflict with Office Inside)
Version 5.01 (17 October 2016)
  • Fix: WinEve.a file was missing from the installer.
Version 5.00 (14 October 2016)
  • New function ds_Round. Rounding on steroids.
  • DLL removed, now shipping as source code
Version 3.99 (29 February 2016)
  • Installer signed with SHA2 certificate
Version 3.98 (29 February 2016)
  • Change: TestStack now outputs a ESP or EBP error to Debugview before displaying the MESSAGE and GPF'ing.
Version 3.97 (17 August 2015)
  • Internal: Slight adjustment to ds_SetFileDateTime. May fix possible Memory Freed Twice error.
Version 3.97 (17 August 2015) Version 3.96 (28 March 2015)
  • References to %EnableWheelMouse removed from the template
Version 3.95 (24 March 2015)
  • If a window is not set as resizable, then ds_VisibleOnDesktop won't resize it.
Version 3.94 (25 February 2015)
  • Clarion 10 Install.
  • Removed unnecessary calls to %cwversion
Version 3.93 (18 February 2015)
  • Template allows local setting to EnableMouseWheel.
Version 3.92 (10 February 2015)
  • Refactor: (Internal) Code for making the window visible on desktop, and visible inside a frame separated into separate functions.
  • Add: ds_SetApplicationWindow and ds_GetApplicationWindow methods. Used to store pointer to AppFrame window.
  • Fix: ds_VisibleOnDesktop method improved.
Version 3.91 (4 February 2015)
  • Fixed regression in 3.90 for missing template variable declaration
Version 3.90 (8 January 2015)
  • Added function WinAlertMouseZoom.
  • Support for iDash Widget procedures added
Version 3.89 (25 November 2014)
  • ds_VisibleOnDesktop could allow windows to float underneath the MDI bar.
Version 3.88 (20 September 2014)
  • Some embeds were not respecting the "disable winevent here" setting.
Version 3.87 (22 August 2014)
Version 3.86 (20 January 2014)
  • Clarion 9.1 build
  • Possible Fix: Some static variables in ds_FastClock were not marked as Threaded.
Version 3.85 (28 October 2013)
  • Suppressed Undeclared Symbol %locCloseDownWhenWindowClosesSet Error. (Thanks to Russ Eggen for submitting a fix.)
Version 3.84 (27 August 2013)
  • Recompiled for Clarion 9, Build 10324. To use this build of WinEvent, in Clarion 9, you must be on build 10324 or later.
Version 3.83 (24 April 2013)
  • Tidied up PROJECTion of DLL's in template for Clarion 8.
  • C8 fix - remove %pClassMethod where clause, and use embed point directly.
  • Template change - template generated text for the Hide, Show, Ext options from the system tray only set if there is text entered in the template, otherwise hide.
  • Extended COM Port range. Current maximum port number is now COM255:, was COM99: (Actually it's been 255 for a while, but it's not clear when this was extended.)
Version 3.82 (31 January 2013)
  • ds_GetWinVersionEx expanded to support Windows 8.
Version 3.81 (14 January 2013)
  • ds_OnNetwork function did not BAND on the LSB as it should (to return just 0 or 1).
Version 3.80 (9 October 2012)
  • Template could generate code into Program Setup, column 1, in legacy apps.
Version 3.79 (7 May 2012)
  • Extended MAXPORTS to 255. Allows from Com1 to Com255 to be available.
Version 3.78 (13 March 2012)
  • Clarion 8 support for linking in C8 lib.
Version 3.77 (5 October 2011)
  • Clarion 8 support for lib mode compiles (where ezHelp is added to the application): Don't link in the Winevent Lib checkbox.
  • Fix for ds_GetUserAccountName: Only calls the API function if secur32 dll can be loaded. Uses NameServicePrincipal and cleans out the '\'
Version 3.76 (20 July 2011)
  • Fixed: ds_GetWinVersion was returning 'Media Center' for Vista and up.
  • ds_GetWinVersionEx - takes a long - if set returns description, else returns the version number in Major.Minor.BuildNumber format.
  • Remove unconditional debug output.
  • ds_GetUserAccountName returns the GetUserNameExA. Use NameServicePrincipal or NameCanonicalEx.
Version 3.75 (15 April 2011)
  • Fixed: The Show Windows On Desktop code is now no longer generated for a procedure when the local "Disable WinEvent in This Procedure" option is enabled for that procedure.
  • Fix: Project correct WinEvent lib for C7.3
  • Fix - force make visible after window opens (checkbox on the Global Extension template). WorkAround in C7.3 resizer.
  • Remove debug code.
  • ds_ParseTip was chopping string at 128 chars.
Version 3.73 (19 July 2010)
  • Windows 2008 R2 reported correctly.
Version 3.72 (25 May 2010)
  • ResetPort (when called by NewPort) sets the baud rate, etc for a port above Port10 correctly.
Version 3.71 (13 May 2010)
  • Project DOS lib into MultiProj generated local projects.
Version 3.70 (25 February 2010)
  • Fix typo project in the template for DOS driver in C6 and earlier builds.
Version 3.69 (24 February 2010)
Clarion 7.1 issue: Was not shutting down in a non-MDI with Global Shutdown.
  • Added debug to DOS file (instead of std_debug output if required).
  • ds_CopyDirectory returns negative if an error occurs (the negative contains the number of files that were successfully copied prior to the error).
Version 3.68 (22 January 2010)
  • Net_wsock32.lib was removed from WinEvent requirements (DLL projects as well as template). New function APIs mapped internally: GetHostname and WSAGetLastError.
Version 3.67 (21 January 2010)
  • Net_wsock32.lib was not removed from the C55 winevent lib (in 3.66)
Version 3.66 (20 January 2010)
  • Include the net_wsock32.lib in the install, and project it into LIB projects (removed from the compiled WinEvent libs). Fix for duplicate compile errors (where other libs use the net_wsock23.lib).
  • Template change - don't project the winevent lib when Winevent is disabled.
Version 3.65 (29 December 2009)
  • Template tweak to project cwsynchc.clw (for Clarion7.1 support in legacy local mode apps)
Version 3.64 (27 October 2009)
  • ds_String2File - If StringLen is 0 then checked a clipped length of the string to write.
  • ds_GetIDETemperature - format parameter can be used to specify Deg F or Deg C.
  • ds_GetWinVersion - Fix for 64 bit OSes - returns Win 7, Win 2008 and WinVista correctly.
Version 3.63 (12 August 2009) Version 3.62 (28 July 2009)
  • Added function ds_RefreshDesktop, which you can call to refresh the desktop, typically after a call to ds_CreateShortcutEx. (Thanks to Skip Williams for providing the code.)
  • Added functions dsGetLocalTime, ds_GetLocalDate, ds_GetSystemTime, ds_GetSystemDate
Version 3.61 (15 July 2009) Version 3.60 (19 June 2009)
  • Extended COM Port range. Current maximum port number is now COM99:, was COM25:
Version 3.59 (18 March 2009)
  • Fixed problem in ds_memory. Although the function was extended to > 2 gigs in ver 3.53, there was a maths error which affected some memory configurations.
Version 3.58 (13 March 2009)
  • Template change - more embeds in the Add Icon to System tray template - allowing additional handcode.
  • Template change - embed point for a balloon clicked event.
  • Template change - projects the C70 winevent lib files correctly.
  • Dll fix - ds_ShowWindow calls the iconize last - some versions of Clarion require prop:iconze to be called after the SetWindowPos calls.
  • Dll change - correctly display Windows 7 in the ds_GetWinversion function.
Version 3.57 (10 November 2008)
  • Clarion 7 compatible install.
Version 3.56 (30 October 2008)
  • Auto-shutdown supports WinNotOnTaskbar - so removed erroneous template turnoff (from Add Icon On taskbar template).
Version 3.55 (23 October 2008)
  • Support for Clarion7 - links in the correct library.
  • Fix - ds_OutputDebug uses created (and disposed) string for long strings - was clipping strings > 1024
Version 3.54 (3 July 2008)
  • Fix regression in WinEvent Template - was setting AutoShutdown off when enabled (instead of off when disabled).
  • Template change - allows specification of the module where an icon is located (otherwise uses the EXE if not specified).
Version 3.53 (24 June 2008)
  • Updated ds_memory function to allow for numbers > 2 Gigs. (Remember though, that memory functions return the number of Kb, not bytes).
Version 3.52 (15 November 2007)
  • Fix - auto-generation of the VersionNumber box in the template was missing a "section" - so was overwriting controls on the tab.
  • Disable VersionNumber generation, changed to Enable Variable Generation. This needs to be checked in order to be forced on.
Version 3.51 (9 November 2007)
  • Fix - when not requiring auto-generation of the VersionNumber, then you can omit this functionality in the WinEvent Global Extension template.
Version 3.50 (6 November 2007)
  • Fix in NewPort function - regression in 3.49. Was not newporting an LPT port.
Version 3.49 (22 June 2007)
  • Fix - supports com10 and up.
Version 3.48 (26 April 2007)
  • ds_GetWinVersion() updated so that it returns "WinVista..." for Vista.
  • ds_ShutDown() updated so that it also calls PowerOff in Vista and 2003.
Version 3.47 (25 April 2007)
  • ds_CreateShortcutEx - allows command line parameters to be used in the shortcut. Replaces the deprecated ds_CreateShortcut function.
Version 3.46 (23 November 2006)
  • ds_Memory returns ULONG (instead of LONG) - this means that the resultant value can be > 2.1 G reported (i.e. up to 4.2G - which is what is returned by the windows API call).
Version 3.45 (13 October 2006)
  • Clarified Template settings (in the local templates).
  • Fix - ds_ShowWindow - was not showing a iconized, minimized window correctly (required 2 calls).
Version 3.44 (20 July 2006)
    Fix GPF for local mode compiles where a variable sync or we_sync was defined in the application (the wrong address was being linked at runtime).
Version 3.43 (12 July 2006)
    Support for disabling ezHelp in the same application.
Version 3.42 (6 June 2006)
    Change Global Extension template description.
Version 3.41(22 May 2006)
    Template option to support ds_VisibleOnDesktop by default. You can turn this off globally, or disable locally (for specific windows that shouldn't have that feature).
Version 3.40 (10 May 2006)
    Posts CloseDown event (for SelfService support) when exit from tasktray is selected.
Version 3.39 (12 April 2006)
  • Auto-Shutdown on check box is defaulted to on.
  • Removed the font settings from the template (in order to correct display in laptops with ClearType fonts settings turned off).
Version 3.38 (27 March 2006)
    Minor tweaks.
Version 3.37 (20 March 2006)
    Changed the WinEvent equates to prefix with WE::. This means that compile duplicates are prevented (when equates of the same name are handcoded or used by other products). Check the Compile Errors section for more details.
Version 3.36 (16 March 2006)
    Improved Taskbar Icon Template - so that it's easier to see what you need to do when making Services with Taskbar Icons.
Version 3.35 (20 February 2006)
    No change - re-sync version numbers in DLL and template.
Version 3.34 (20 January 2006)
  • Template Fix: Regression in 3.33 - RetryCreateIcon definition was not always being generated.
  • Fix: Regression in 3.33 - Message removed from COM initialisation.
Version 3.33 (11 January 2006)
  • Template Fix: Taskbar icon now works with Services
  • WinAccept (DLL) - optimised procedure
Version 3.32 (21 October 2005)
  • Fixed bug in ds_Memory where 0 returned under clarion 6.x.
  • Fixed bug in comms status pin functions CTSHigh, DSRHigh, RingHigh and CDHigh. Broken in 3.31.
Version 3.31 (27 September 2005)
  • Added ds_DestroyIcon(), use with ds_GethIcon() to free memory.
  • Added option "Left-Click Icon shows Window" to the TaskBarIcon template.
  • Added a separator to the TaskbarIcon popup menu.
  • Fixed bug in ds_FormatFastTime where times past midnight displayed incorrectly.
  • Added a ReSyncTime optional parameter to ds_FastClock() for use when the time has been adjusted.
Version 3.30 (1 September 2005) Version 3.29 (21 July 2005)
  • Fixed bug in ds_FormatFastTime where very small times, nano seconds displayed as milliseconds.
  • Added a template to open a com port. See Use com port template.
  • Added support for com port events.  See new com port template.  See modified newport command.
  • Fixed a bug in the GSM Modem routines that caused a GPF under clarion 6.X
  • Modified template call to ds_DebugView, removed start().  This was causing a GPF under 6.2
  • Added ds_SetRealTimePriority().
  • Added ds_QueryPerformance().
  • Added ds_Ulong64ToReal().
  • Modified "Add Icon to system tray" template to include optional Show|Hide|Close popup. (Thank you Geoff)
  • Added ds_HideWindow procedure
  • Added ds_ShowWindow procedure
  • Updated WinEvent() documentation.WinEvent
  • Documented the WinSysEvent and WinWtsEvent functions.
Version 3.28 (19 January 2005)
  • Modified template so that importing a procedure with a WinEvent template does not cause template errors.
  • Modified template so that the Load Icon and Refresh Icon embed points are correct. Refresh Icon was missing.
Version 3.27 (10 December 2004) Version 3.26 (3 December 2004)
  • Fixed bug in template where "Disable WinEvent in the application" did not always work, some code was still generated
    • .
  • Fixed bug in ds_SetClipboard().
Version 3.25 (25 November 2004)
  • Fixed bug in ds_GetFileVersionInfo where extra characters were returned with the version string.
  • Fixed bug in EzHelp version checking routine.
  • Added priority attributes to template embed code. This is to assist with souce comparison at Jim's request.
  • Renamed WinEvent internal modules, prefixed with "ds_we". This is to remove module naming conflicts.
  • Added ds_SaveStack and ds_TestStack procedures. These may help in locating stack corruptions.
Version 3.24 (3 November 2004) Version 3.23 (2 November 2004) Version 3.22 (23 October 2004)
  • Major re-write of documentation.
  • Added TaskbarShowBalloon and TaskbarHideBalloon code templates.
  • Upgraded to new CapeSoft look.
  • Added template help buttons.
  • Modified WinEvent template to use EVENTMAP.CLW instead of adding each procedure prototype to the global map.
  • Added error reporting to most WinEvent functions. See ds_Error
  • Modified ds_CreateDirectory to work with relative paths ie ..\MyNewDirectory
Version 3.21 (8 September 2004)
  • Fixed memory leak in ScreenWidth(), ScreenHeight() &ScreenDepth()
  • Added ds_GetScreenDPI() which returns the user screen DPI settings. 96=Small Fonts, 120=Large Fonts or custom font setting.
  • Added ds_CreateShortcut() which will create a shortcut to a file.
Version 3.20 (18 August 2004)
  • Add Icon to the intray" template so that WinTaskBarAddIcon is now called from a posted event. This is because sometimes the Icon does not add.
  • Added some compile warnings when WinNotOnTaskBar is used with auto-shutdown as this is not compatible.
Version 3.19 (22 July 2004)
  • Rebased DLL for faster loading.
  • Added save to file / clipboard functionality to the builtin debug viewer.
  • Added embed points for TaskBar balloon events.
  • Added the field equate labels to the builtin debug viewer.
  • Updated CSIDL equates.
  • Added ds_GetHModule() which returns a handle to the current module or a specified DLL. Use with ds_GetHIcon().
  • Added ds_GetHIcon() which returns a handle to icons that are compiled into the EXE or DLL.
  • Added ds_GetWindowsColour() which returns the current users windows colour setting in clarion colour format.
Version 3.18 (3 June 2004)
    Fixed bug in WinTaskbarAddIcon where line breaks were removed from tip strings. Should only remove for WIN9x.
Version 3.17 (31 May 2004)
  • Fixed bug in ds_MoveFile.
  • Modified WinTaskbarAddIcon and WinTaskbarChangeIcon to ignore calls with IconName blank.
Version 3.16 (16 April 2004)
    Fixed bug where calling Sound(soundfilename) would fail under Win2k.
Version 3.15 (7 April 2004)
    Fixed bug where calling Sound() with an empty wavefile name string caused a GPF.
Version 3.14 (23 March 2004)
    Modified WinSysEvent() and WinWTSEvent() functions to optionally clear the value after reading. New prototype!
Version 3.13 (18 March 2004)
    Fixed bug in template where the Sound function was incorrectly prototyped. Sound would cause app to close without GPF, just gone
Version 3.12 (3 March 2004)
    Fixed bug in GSM Modem SMS delivery Reporting where some Siemens modems were not properly supported.
Version 3.11 (16 February 2004)
  • Fixed bug in template where WinEvent events were not handled
    • .
  • WinEvent examples upgraded. (Thank you Jono)
Version 3.10 (5 February 2004)
    Fixed conflict with Secwin.
Version 3.09 (3 February 2004)
    Fixed bug in ds_WinTaskbarBalloon where Win2000 balloons did not work.
Version 3.08 (2 February 2004)
    Fixed bug in ds_WinTaskbarBalloon where Win2000 and Win NT4 Balloons were positioned off the visible desktop.
Version 3.07 (28 January 2004)
  • Added TaskbarIcon "Balloon" support. See ds_WinTaskbarBalloon
  • Modified WinTaskbarAddIcon to accept "compiled in" icons. Example WinTaskbarAddIcon('~MyAppIcon.ico'...
  • Modified Auto-Shutdown. Added Callback functions MyOKToEndSessionHandler & MyEndSessionHandler
    Added WinEvent functions ds_SetOKToEndSessionHandler & ds_SetEndSessionHandler.
    See Auto-Shutdown for details.
Version 3.06 (12 January 2004)
  • Fixed bug where WinEvent could not be linked into a non data DLL. WinEvent now has a DLL !!!!!
  • Modified GSM Modem SMS delivery reporting.
  • Added GSM Modem Event monitoring. See example.
Version 3.05 (5 January 2004)
  • Fixed bug where WinEvent could not be linked into a data DLL.
  • Fixed bug in ds_VisibleOnDesktop where window would remain obscured on the right side.
Version 3.04 (11 December 2003)
  • Modified the NewPort function to cater for using LPTx as a parameter.
  • Fixed bug in (don't laugh) ds_debug.
  • Added new function ds_VisibleOnDesktop.
Version 3.03 (22 September 2003)
    Added GSM Modem SMS delivery reporting support.
Version 3.01 (21 August 2003)
  • Modified the ds_GSMGetReply function. Added an extra optional parameter.
  • Added GSM Modem SMS read support. See ds_GSMReadSMS
  • Added an date format string to the "Append compile date to title bar" option on WinEvent extension general tab.
Version 3.00 (30 July 2003)
    Added a batch of new functions.
Version 2.99 (9 July 2003)
  • Fixed bug introduced in 2.98 where ReadPort caused a GPF.
  • Added alternate Auto-Shutdown method. This allows you to execute closing down code but will exit even if user cancels the shutdown.
    See option under the Auto-Shutdown option on WinEvent extensions.
Version 2.98 (3 July 2003)
    Fixed bugs in WindowsRelease function.
Version 2.97 (26 June 2003)
  • Fixed bugs in ScreenWidth, ScreenHeight and ScreenDepth functions.
  • Added a new function. ds_WinTransparent() . This function is completely useless but looks really cool. WinXP and Win2000 only. (Not Win98).
    ds_WinTransparent(255) = Normal window
    ds_WinTransparent(0) = Transparent window
    ds_WinTransparent(128) = recommended.
Version 2.96 (24 June 2003)
    Added new example code to the WinOnTop function. This is the ideal code for hiding and showing a window from the Task Bar.
Version 2.94 (2 June 2003)
  • Fixed bug in Modified NewPort (2.93) where an error on opening a port (port in use) caused a stop .
  • Fixed bug in SetRTS and SetDTR functions. Was causing linker error.
  • Problems with Wheel Mouse Support. Some mouse drivers are not compatible with WinEvent Wheel Mouse support and cause random GPF's.
Version 2.93 (1 May 2003)
    Modified NewPort to support buffer size setting.
Version 2.92 (8 April 2003)
  • Modified WinTaskBarAddIcon so that the Icon is redrawn whenever a new taskbar is started. Note the new "Refresh icon event" embed point.
  • Added function GetSystemDir. This returns c:\windows\system
  • Removed GetSystemWindowsDir as this only works under terminal server.
Version 2.91 (24 March 2003)
    Fixed bug where WinEvent events were suppressed while running EzHelp.