


	Version www.capesoft.com Updated Friday 16 July 2010

Support

Installation

Distribution

How to read this manual

Example Program

Enabling WinEvent Functions

WinAlert Functions

Comm's Functions

Taskbar Functions

Window Behaviour Functions

Windows System Functions

RAM & Disk Functions

Registry Functions

Time & Date Functions

File & Directory Functions

Process & Thread Functions

DLL Functions

SMS Functions

Debugging & Error Reporting Functions

Auto-Shutdown Functions

Other Functions

Reference Section

Frequently Asked Questions (FAQ's)

Version History

Introduction

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

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

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

WinEvent functionality is divided into 5 areas:

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

Copyright

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

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

Support

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	support@capesoft.com
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Purchase WinEvent at $149.00 from:

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

Buy Online
	Web	www.clarionshop.com

Installation

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

Distribution

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

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

DLLs required (Standalone mode only)
	Clarion Version	DLL required
	Clarion 6	WE60X.DLL
	Clarion 5.5	WE55X.DLL
	Clarion 5	EVENT532.DLL

How To Read this Manual

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

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

Example Program

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

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

Enabling WinEvent Functions

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

enabling WineEvent functions screenshot

On the Settings tab of the WinEvent global extension template:

global extension template settings tab

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

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

Multi-DLL applications:

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

WinAlert Functions

The Concept

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

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

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

The Classic Example

One of the most frequently asked questions on the Internet's cw-talk mailing list, is "How do I get my application to terminate automatically when the user shuts down Windows ?" Using WinEvent the answer is both simple and elegant. you simply add the WinEvent global extension template and leave the defaults checked and away you go.

Using the Local WinEvent: Alert Windows Messages Template

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

If Auto Shutdown has been globally set for your application, this option will enable you to disable the Auto Shutdown for when a selected window is the focus window (i.e. a window that requires you to save information before closing).
Make this window visible on Desktop allows you to either use the Default option (i.e. the setting in the Global Extension template) - or force it to override the global default option using the Yes or No option.
You can also use the Append compile date to title bar - which by default is turned off as it would only be necessary on one of your windows in your application (if you require this functionality).

Using WinAlert in Applications

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

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

Action (group 1):

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

Action (group 2):

These options are telling WinAccept what to do with the event - in terms of forwarding it on to your Clarion procedure. There are 3 possible options you can select:

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	Event:MouseMove
WE::WM_NCMOUSEMOVE	Event:MouseMove
WE::WM_TIMER	Event:Timer
WE::WM_LBUTTONDOWN	Event:MouseDown
WE::WM_RBUTTONDOWN
WE::WM_NCRBUTTONDOWN
WE::WM_NCLBUTTONDOWN
WE::WM_NCMBUTTONDOWN
WE::WM_MBUTTONDOWN
WE::WM_LBUTTONUP	Event:MouseUp
WE::WM_RBUTTONUP
WE::WM_NCRBUTTONUP
WE::WM_NCLBUTTONUP
WE::WM_NCMBUTTONUP
WE::WM_MBUTTONUP

Please Note: If using the WE::WM_MouseWheel on a window with a listbox, then only the mouse wheel events occurring when the mouse wheel button is depressed will be passed to the WinAccept. Windows will only pass on the mouse wheel events when a list box is not present.

For those that care

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

Using WinAlert in a Hand Coded Project

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

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

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

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

Comm's Functions

The Comm's section of the WinEvent package provides some simple easy-to-use functions that allow you to read and write to Comm's ports (RS232).

Using Comm's functions in an Application

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

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

Functions supplied

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

For a detailed description of each of the functions, see the reference section. You will need to handcode the functions into your application where you need them.

Taskbar Functions

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

Template Supplied

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

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

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

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

Functions supplied

WinTaskbarAddIcon
WinTaskbarChangeIcon
WinTaskbarRemoveIcon
WinNotOnTaskbar
ds_WinTaskbarBalloon

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

Window Behaviour Functions

Functions Supplied

WinOnTop
WinNotOnTop
WinBringToFront
ds_WinTransparent
ds_VisibleOnDesktop
ds_ShowWindow
ds_HideWindow

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

Windows System Functions

Functions Supplied

ds_GetWinVersion
WindowsVersion
WindowsRelease
DosVersion
DosRelease
Sound
GetWindowsDir
GetSystemWindowsDir
ScreenWidth
ScreenHeight
ScreenDepth
ds_GetScreenDPI
ds_GetUserName
ds_GetWorkstationName
ds_IsMediaCenter
ds_IsTerminalServer
ds_IsTablet
ds_IsStarter
ds_OnNetwork
ds_RefreshDesktop

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

RAM & Disk Functions

Functions Supplied

GetFreeDiskSpace
GetDiskSpace
ds_GetDiskMegs
ds_Memory

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

Registry Functions

Functions Supplied

ds_GetReg
ds_PutReg

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

Time & Date Functions

Functions Supplied

ds_FastClock
ds_FormatFastTime
ds_Timer
ds_Sleep
ds_WeekDay
ds_ReadCPUTimeStamp

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

File and Directory Functions

Functions Supplied

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

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

Process & Thread Functions

Functions Supplied

ds_GetCurrentProcess
ds_GetCurrentThread
ds_GetProcessTime
ds_GetThreadTime
ds_SetRealTimePriority

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

DLL Functions

Functions Supplied

        ds_LoadDLLProc
        ds_UnloadDLLProc
        ds_GetDLLVersion

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

SMS Functions

Getting Started

Functions Supplied

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


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

Getting Started

First, some Important info:

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

Note: Only the standard Charset is supported at this stage. We will include the ability to change charsets as soon as possible.

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

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

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

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

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

Debugging & Error Reporting Functions

Functions Supplied

        ds_OutputDebugString
        ds_Debug
        ds_WineventDebug
        ds_ViewDebug
        ds_ViewDebugClose
        ds_Error
        ds_ErrorCode
        ds_ErrorReset
        ds_SaveStack
        ds_TestStack

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

Auto Shut-down Functions

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

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

For handcoded window procedures, you'll need to code the following:

After opening the window (before the accept loop):

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

If WindowOpened Then WinAlert().

Functions Supplied

        ds_SetOKToEndSessionHandler
        ds_SetEndSessionHandler
        ds_SetNoEndSession

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

Some Technical Details

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

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

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

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

Other Functions

Functions Supplied

        ds_FormatHex
        ds_SetClipboard
        ds_ShutDown
        ds_WineventVersion
        ds_Ulong64ToReal

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

Reference Guide

WinAlert functions

WinAlert
Winevent
WinControl
WinParam1
WinParam2
WinChangeUserEvent
WinSysEvent
WinSysParam1
WinSysParam2
WinWtsEvent
WinWtsID

Comms Functions

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

Taskbar Functions

WinTaskBarAddIcon
WinTaskBarRemoveIcon
WinTaskBarChangeIcon
WinNotOnTaskBar
ds_WinTaskbarBalloon

Window Behaviour Functions

WinOnTop
WinNotOnTop
WinBringToFront
ds_WinTransparent
ds_VisibleOnDesktop
ds_ShowWindow
ds_HideWindow

Windows System Functions

ds_GetWinVersion
WindowsVersion
WindowsRelease
DosVersion
DosRelease
GetFreeDiskSpace
GetDiskSpace
Sound
GetWindowsDir
GetSystemWindowsDir
ScreenWidth
ScreenHeight
ScreenDepth
ds_GetScreenDPI
ds_GetUserName
ds_GetWorkstationName
ds_IsMediaCenter
ds_IsTerminalServer
ds_IsTablet
ds_IsStarter
ds_OnNetwork

Time & Date Functions

          ds_FastClock
          ds_FormatFastTime
          ds_Timer
          ds_Sleep
          ds_WeekDay

File Functions

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

DLL Functions

ds_LoadDLLProc
ds_UnloadDLLProc

SMS Functions

Debugging & Error Reporting Functions

        ds_Debug
        ds_WineventDebug
        ds_ViewDebug
        ds_ViewDebugClose
        ds_Error
        ds_ErrorCode
        ds_ErrorReset
        ds_SaveStack
        ds_TestStack

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

Parameters

FromMessage short
The [first] Windows message to alert.

ToMessage short
The last Windows message to alert. If this parameter is omitted then only the FromMessage is alerted.

Action short
This defines the action required when the alerted message(s) are received. If this parameter is omitted then it defaults to PostUser + PassOn.

Purpose

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

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

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

Group 1
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.

NOTE : The PostClarion action is only available in the registered version of WinEvent.

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

Complication

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

Returns

Nothing

Example

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

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

Parameters

None

Purpose

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

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

WinChangeUserEvent (WinMessageEvent)

Parameters

WinMessageEvent short
The Event to post when an alerted windows message is received.

Purpose

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

code
WinChangeUser(WinMessageEvent)

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

Parameters

byte pClearAfterRead : Default FALSE. If set TRUE the WinSysEvent is reset to zero after reading.

Purpose

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

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

WinWtsEvent(byte pClearAfterRead=0), WinWtsID()

Parameters

byte pClearAfterRead : Default FALSE. If set TRUE the WinWtsEvent is reset to zero after reading.

Purpose

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

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

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

Purpose

Opens a port for sending or receiving.

Parameters

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

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

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

Comms transmit buffer empty event = WinEventMessage + 5601

Comms characters received = WinEventMessage + 5602

Comms handshaking lines changed = WinEventMessage + 5602

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

Examples

    PortId = NewPort('Com1:9600,n,8,1')
    PortId = NewPort('Com2:9600,n,8,1',1024)
    PortId = NewPort('Com3:9600,n,8,1',1024,1024)

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

ResetPort (mode string)

Purpose

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

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

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

ClosePort (PortId long)

Purpose

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

Parameters

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

Returns: long

Nothing

Example

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

KillAllPorts ( )

Purpose

Closes all open ports.

Returns

Nothing

Example

KillAllPorts()

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

Purpose

Writes a string into the transmission buffer.

Parameters

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

String (string) This is the handle for the string to send. Note: don't use string functions like clip, sub, etc when passing this string.

Length (long) This is the number of bytes to send. If 0 then the string is clipped and sent.

Returns: long

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

Example

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

Note: Do not use:

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

instead of:

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

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

Purpose

Read bytes out of the receive buffer.

Parameters

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

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

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

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

SetHandShake (PortId long, HandShake long)

Purpose

To Set or Remove port handshaking

Parameters

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

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

CtsHigh (Pid Long)

Purpose

Returns the current status of the CTS (Clear to Send) 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

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

DsrHigh (Pid Long)

Purpose

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

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

RingHigh (Pid Long)

Purpose

Returns the current status of the RI (Ring Indicator) 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

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

CdHigh (Pid Long)

Purpose

Returns the current status of the CD (Carrier Detect) 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

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

SetRts (Pid Long, Value Long)

Purpose

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

Parameters

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

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

SetDtr (Pid Long, Value Long)

Purpose

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

Parameters

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

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

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

Purpose

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

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

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(<Id longt>)

Purpose

Removes an Icon from the Taskbar's tray.

Parameters

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

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

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

Purpose

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

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

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:

Balloon open
Balloon close
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(<ulong pID>,string pText,<string pTitle>,uLong pFlags=1,ulong pTimeout=1500)

Purpose

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

pID (ulong) : Optional. Returned by WinTaskbarAddIcon. Is used to identify which icon to attach the balloon to.

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

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

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

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

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

Returns

Nothing

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 timeout or 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()

Purpose

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

code
WinNotOnTaskBar()
open(window)

WinOnTop()

Purpose

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

code
open(window)
WinOnTop()

Example 2

! -------------------------------------
! 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()

Purpose

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 1

code
open(window)
WinOnTop()
WinNotOnTop()

WinBringToFront()

Purpose

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

code
open(window)
WinBringToFront()

ds_ShowWindow(byte pGrabFocus=1)

Purpose

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

Parameters

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

Returns

Nothing

Example

code
open(window)
ds_ShowWindow()

ds_HideWindow

Purpose

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

Parameters

None.

Returns

Nothing

Example

code
open(window)
ds_HideWindow()

ds_WinTransparent(long Transparency)

NB: Only available for non-MDI windows.

Purpose

Adjusts the transparency of a window .

Parameters

Transparency (long) : This sets the transparency factor. 0 = Invisible, 255 = Normal.

Returns

Nothing

Example

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

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

Purpose

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

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

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

ds_GetWinVersion()

Purpose

Returns the version of windows that is running.

Parameters

None

Returns

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

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

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

Example

code
DisplayString = ds_GetWinVersion() ! Win 98 - 4.10.222 A
....
case sub(ds_GetWinVersion(),1,8)
of 'Win 3.1'
of 'Win 95'
of 'Win 98'
of 'Win NT'
of 'Win 2K'
of 'Win 2K3'
of 'Win XP'
of 'WinVista'
of 'Win 7'
of 'Win 2008'
else
end

WindowsVersion()

Purpose

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

Parameters

None

Returns

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

Example

code
ver = WindowsVersion()

WindowsRelease()

Purpose

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

Parameters

None

Returns

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

Example

code
ver = WindowsVersion()
rel = WindowsRelease()

DosVersion()

Purpose

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

code
ver = DosVersion()

DosRelease()

Purpose

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

code
ver = DosVersion()
rel = DosRelease()

GetFreeDiskSpace (<drive long>)

Purpose

Returns the amount of free disk space, in bytes.

Parameters

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

free real
code
free = GetFreeDiskSpace()

GetDiskSpace (<drive long>)

Purpose

Returns the total disk space, in bytes.

Parameters

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

total real
code
total = GetDiskSpace()

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

Purpose

Returns the specified disk space, in megabytes.

Parameters

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

total ulong
code
total = ds_GetDiskMegs()

ds_Memory(<string pSelector>)

Purpose

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

Parameters

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

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

Returns

Ulong. The RAM size in kilobytes.

Example

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

ds_GetReg(Long hKey, String SubKeyPath, String ValueName)

Purpose

Gets a value out the Windows System Registry.

Parameters

hKey (long)
The top level key containing the section of the registry to read. Valid values are;
WE::WM_HKEY_CLASSES_ROOT
WE::WM_HKEY_CURRENT_USER
WE::WM_HKEY_LOCAL_MACHINE
WE::WM_HKEY_USERS

SubKeyPath (string)
The path inside the registry to the item you want to read.

ValueName (String)
The name of the variable you want to read.

Returns

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

Example

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

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

Purpose

Writes a value to the Windows System Registry.

Parameters

hKey (long)
The top level key containing the section of the registry to write. Valid values are;
WE::WM_HKEY_CLASSES_ROOT
WE::WM_HKEY_CURRENT_USER
WE::WM_HKEY_LOCAL_MACHINE
WE::WM_HKEY_USERS

SubKeyPath (string)
The path inside the registry to the item you want to write.

ValueName (String)
The name of the variable you want to write.

Value (String)
The value you want to write into the registry.

Type (Long)
the type of the value you are writing. Valid values are;
WE::REG_SZ                  !!// Unicode nul terminated string
WE::REG_EXPAND_SZ           !!// Unicode nul terminated string
WE::REG_BINARY              !!// Free form binary
WE::REG_DWORD               !!// 32-bit number
WE::REG_DWORD_LITTLE_ENDIAN !!// 32-bit number (same as REG_DWORD)
WE::REG_DWORD_BIG_ENDIAN    !!// 32-bit number
WE::REG_MULTI_SZ            !!// Multiple Unicode strings

Default value for this parameter is WE::REG_SZ.

Returns

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

Example

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

Sound (WavFileName String)

Purpose

Plays a Wav file through the speaker.

Parameters

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

Returns

Nothing

Example

code
sound('alarm.wav')

GetWindowsDir ()

Purpose

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

a string(255)
code
a = GetWindowsDir()

GetSystemDir ()

Purpose

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

a string(255)
code
a = GetSystemDir()

ScreenWidth ()

Purpose

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

Parameters

None

Returns

A long containing the number of pixels.

Example

a long
code
a = ScreenWidth()

ScreenHeight ()

Purpose

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

Parameters

None

Returns

A long containing the number of pixels.

Example

a long
code
a = ScreenHeight()

ScreenDepth ()

Purpose

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

a long
code
a = ScreenDepth()

ds_GetScreenDPI (byte pDPIY=0)

Purpose

Gets the current DPI of the windows desktop.

Parameters

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

a long
code
a = ds_GetScreenDPI()

ds_GetUserName()

Purpose

Gets name of user currently logged into Windows.

Returns

A String containing the name.

ds_GetWorkstationName()

Purpose

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

Returns

A string containing the name.

ds_IsMediaCenter()

Purpose

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

Purpose

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

Purpose

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

Purpose

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

Purpose

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

Returns

A long, 1 if true 0 if false.

ds_RefreshDesktop()

Purpose

Refreshes the desktop. Typically called after calling ds_CreateShortcutEx..

Returns

Nothing.

ds_FastClock(byte UseCPUTimeStamp=0,byte ReSyncTime)

Purpose

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

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

ThisTime real

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

ds_FormatFastTime(real pFastTime,<long pDecimalPlaces>)

Purpose

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

Parameters

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

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

ds_Sleep(real pFastTime)

Purpose

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

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

Returns

None.

Example

code
ds_Sleep(100.1) ! wait 1.001 seconds

ds_Timer(long pTimerNumber,<real pFastTime>)

Purpose

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

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.

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(long pDate,<byte pShortFormatFlag>)

Purpose

Returns the English name for the day of the week.

Parameters

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

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

Returns

String containing the day of the week.

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(*real pSaveReal)

Purpose

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

Parameters

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

Returns

None.

Example

ThisTime    real

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

ds_ReadCPUTimeStampDelta(*real pSaveReal)

Purpose

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

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

ThisTime    real

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

ds_DeleteFile(string pFileName)

Purpose

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

Parameters

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

Returns

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

Example

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

ds_GetFileDirEntry(string pFileName,*string pEntryG)

Purpose

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

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

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

Returns

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

Example

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

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

ds_SetFileAttributes(string pFileName,byte pNewAttribs)

Purpose

Set the directory attributes of a file.

Parameters

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

pNewFileAttribs (byte) : Specify the new attributes.

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

Returns

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

Example

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

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

Purpose

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

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

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

ds_CreateDirectory(string pNewDirectoryName)

Purpose

Create a new directory.

Parameters

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

Returns

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

Example

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

ds_RemoveDirectory(string pDirectoryName)

Purpose

Remove a directory.
The directory must be empty.

Parameters

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

Returns

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

Example

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

ds_SetFileDateTime(string pFileName,long pNewDate,long pNewTime)

Purpose

Set the date and time of the files directory entry.

Parameters

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

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

ds_MoveFile(string pFileName,string pNewFileName)

Purpose

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

Parameters

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

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

ds_GetFolderPath(long pCSIDL,<byte pCreateFlag>)

Purpose

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

Parameters

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.

WE::CSIDL_DESKTOP equate(000h) ! C:\Documents and Settings\username\Desktop
WE::CSIDL_PROGRAMS equate(002h) ! C:\Documents and Settings\username\Start Menu\Programs
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_STARTMENU equate(00Bh) ! C:\Documents and Settings\username\Start Menu
WE::CSIDL_MYMUSIC equate(00Dh) ! C:\Documents and Settings\username\My Documents\My Music
WE::CSIDL_DESKTOPDIRECTORY equate(010h) ! C:\Documents and Settings\username\Desktop
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) !*
WE::CSIDL_COMMON_ALTSTARTUP equate(01Eh) !*
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_PROGRAM_FILES_COMMON equate(02Bh) !#C:\Program Files\Common
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_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_CDBURN_AREA equate(03Bh) !*C:\Documents and Settings\username\Local Settings\Application Data\Microsoft\CD Burning

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

Returns

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

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

Purpose

Returns the path to the windows temporary directory.

Parameters

None.

Returns

String containing the path.

Example

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

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

Purpose

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

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

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

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

Purpose

Reads a file into a string.

Parameters

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

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 (<string pModuleName>)

Purpose

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

Parameters

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

hModule ulong
code
hModule = ds_GetHModule() ! returns handle to current module.
hModule = ds_GetHModule('MyIcons.dll') ! returns handle to MyIcons.dll

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

Purpose

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

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

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 (string pTargetFile,<string pIconName>,long pIconIndex=0,string pDescription,long pHotKey=0,string pStartIn,string pShortCut,<string pShortCutPath>,<string pArguments>,<string pReserved>)

Purpose

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

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

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(<string pDescription>,<*string pFileName>)

Purpose

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

Parameters

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

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

ds_GetCurrentEXEDate()

Purpose

Used to return the current date of the EXE.

Parameters

None

Returns

Long. Returns the date of the EXE.

Example

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

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

Purpose

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

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

"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(*ulong pProcAddress,ulong pLibInstance)

Purpose

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

Parameters

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

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

Returns

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

Example

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

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

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

ds_GetDLLVersion(string pDLLName,*ds_DLLVersionG pDLLVerInf)

Purpose

Used to retrieve the version information from a windows DLL.

Parameters

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

DLLVerInf group(ds_DLLVersionG) .

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

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

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

Purpose

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

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

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(long pPID,string pPIN)

Purpose

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

Parameters

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

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

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

Returns

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

Example

PID long

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

ds_GSMEchoOFF(long pPID)

Purpose

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

Parameters

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

PID long

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

ds_GSMSetSMSTextmode(long pPID)

Purpose

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

Parameters

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

PID long

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

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

Purpose

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

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

PID long
ReplyString string(1024)

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

ds_EmptyPort(long pPID,long pTimeout=50)

Purpose

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

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

PID long

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

ds_GSMReadSMSInit(long pPID,string pPIN)

Purpose

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

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

PID long

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

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

Purpose

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

Parameters

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

PID        long
SMSIndex long

SMSG    group(ds_SMSMessageG)
              end

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

ds_GSMDeleteSMS(long pPID,long pSMSIndex)

Purpose

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

Parameters

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

PID        long

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

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

Purpose

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

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

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

Example

PID        long

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

ds_GSMSelectSR(long pPID,byte pSRMemory=1)

Purpose

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

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

PID        long

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

ds_GSMReadSMSReportInit(long pPID,string pPIN)

Purpose

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

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

PID long

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

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

Purpose

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

Parameters

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

PID        long
SMSReportIndex long

DRG    group(ds_SMSReportG)
              end

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

ds_GSMDeleteSMSReport(long pPID,long pSMSReportIndex)

Purpose

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

Parameters

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

PID        long

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

ds_GSMReadEvents(long pPID,*ds_GSMEventG pERG)

Purpose

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

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

PID        long

ERG    group(ds_GSMEventG)
              end

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

ds_GSMSetEvents(long pPID,long pEventsMask=255)

Purpose

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

Parameters

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

PID        long

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

ds_GSMReset(long pPID)

Purpose

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

Parameters

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

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(string pDebugString,byte pAddCRLF=1)

Purpose

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

Parameters

pDebugString (string) : Debug info string.

pAddCRLF (byte) : Add carriage return and line feed to the debugstring if set.

Returns

None.

Example

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

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

Purpose

Used to send (output) debug information to both the builtin 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

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

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

ds_WineventDebug(byte pEnable)

Purpose

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

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

fp_Testing ulong

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

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

ds_ViewDebug

Purpose

Opens the WinEvent built-in debug viewer.

Parameters

None.

Returns

None.

Example

fp_Testing ulong

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

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

ds_ViewDebugClose

Purpose

Closes the WinEvent built-in debug viewer.

Parameters

None.

Returns

None.

Example

fp_Testing ulong

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

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

ds_Error(<long pThisErrorCode>)

Purpose

Returns the error message for a ds_ErrorCode().

Parameters

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

fp_Testing ulong

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

ds_ErrorCode()

Purpose

Returns the current WinEvent error code.

Parameters

None.

Returns

Long. Error code.

Example

fp_Testing ulong
SaveErrorCode long

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

ds_ErrorReset(<string pCallingProcedure>)

Purpose

Clears ds_ErrorCode and sets the calling Procedure name.

Parameters

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

fp_Testing ulong
SaveErrorCode long

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

ds_SaveStack & ds_TestStack

Purpose

Use ds_SaveStack with ds_TestStack to check for stack / register corruption while calling external procedures.
If the ESP or EBP registers are corrupted then displays a messagebox after which a GPF is forced.
If other registers are corrupted then sends a warning message to OutputDebugString.
NOTE : ds_SaveStack must be matched with a ds_TestStack otherwise a mismatch error will be reported.

Parameters

None.

Returns

None.

Example

code
ds_SaveStack
! some external procedure call.
ds_TestStack

ds_FormatHex(ulong pDisplayValue,byte pPadSpaces)

Purpose

Returns a hexadecimal representation of the value.

Parameters

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

DisplayHex string(10)

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

ds_SetClipboard(ulong pClipFormat,string pNewContents)

Purpose

Places various format data into the windows clipboard.

Parameters

pClipFormat (ulong) : The format specifier.

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

pClipFormat Value	pNewContents requires:
WE::CF_BITMAP	a handle to a bitmap memory space.
WE::CF_DIB	a memory object containing a BITMAPINFO structure followed by the bitmap bits. DIB = Device-Independant Bitmap
WE::CF_DIBV5	a memory object containing a BITMAPV5HEADER structure followed by the bitmap color space information and the bitmap bits.
WE::CF_DIF
WE::CF_ENHMETAFILE	a handle to an enhanced metafile (HENHMETAFILE).
WE::CF_HDROP	a handle to type HDROP that identifies a list of files. (see example below)
WE::CF_LOCALE
WE::CF_METAFILEPICT	a handle to a metafile picture format as defined by the METAFILEPICT structure.
WE::CF_OEMTEXT	a Text format string. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
WE::CF_PALETTE
WE::CF_PENDATA
WE::CF_RIFF
WE::CF_SYLK
WE::CF_TEXT	a Text format string. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
WE::CF_TIFF	a Tagged-image file format.
WE::CF_UNICODETEXT	a Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
WE::CF_WAVE	an audio data string in one of the standard wave formats, such as 11 kHz or 22 kHz Pulse Code Modulation (PCM).

Returns

Byte. Returns 1 for success, 0 for failure

Example

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

data

hDropStruct group
pFiles             long ! offset from here to FileList
pt                   ulong ! drop point (in screen co-ords)
blank              ulong
fNC                 long   !Set for Non-Client area.
fWide              long
FileList            string(255) ! Null terminated list of null terminated file names.
                  end

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

ds_ShutDown(<byte pForce>)

Purpose

Requests a windows shutdown.

Parameters

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

code
ds_Shutdown() ! Request a windows shutdown.

ds_WinEventVersion()

Purpose

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

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

ds_Ulong64ToReal(long pULongHigh,long pULongLow),real

Purpose

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

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

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

Returns

Real. The ulong64 value.

Example

RealVar                    real
ulong64G                  group
High                           long
Low                            long
                                end

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

ds_SetOKToEndSessionHandler(ulong pCallBackAddress)

Purpose

Installs an OKToEndSessionHandler for the Auto-shutdown functionality.

Parameters

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

OldHandlerAddress ulong

code
OldHandlerAddress = ds_SetOKToEndSessionHandler(address(MyOKToEndSessionHandler))

ds_SetEndSessionHandler(ulong pCallBackAddress)

Purpose

Installs an EndSessionHandler for the Auto-shutdown functionality.

Parameters

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

OldHandlerAddress ulong

code
OldHandlerAddress = ds_SetEndSessionHandler(address(MyEndSessionHandler))

ds_SetNoEndSession(long pNoEndSession)

Purpose

Disables the Auto-Shutdown functionality.

Parameters

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

Returns

None.

Example

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

ds_GetCurrentProcess()

Purpose

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

Parameters

None.

Returns

long. hProcess, handle this process.

Example

long hProcess

code
hProcess = ds_GetCurrentProcess()

ds_GetCurrentThread()

Purpose

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

Parameters

None.

Returns

long. hThread, handle to this thread.

Example

long hThread

code
hThread = ds_GetCurrentThread()

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

Purpose

Returns the CPU usage of this process in clarion time.

Parameters

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

real UserTime

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

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

Purpose

Returns the CPU usage of this thread in clarion time.

Parameters

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

real UserTime

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

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

Purpose

Selects Real Time or Normal priority for a thread.

Parameters

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

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

Frequently Asked Questions (FAQ's)

I'm getting compile errors

TaskBar/SystemTray Questions:

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

Comport Questions:

C.1 How do I open a serial port cash drawer using WinEvent?
C.2 I use a virtual comport USB to COM convertor. After some time the comport closes down.

General Questions:

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

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

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

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

Answer: 1) Use the TaskBar extension
2) Use the 2 routines (WindowHide and WindowShow) in the example code for the WinOnTop function to Hide and Show your Window.

1.4 My icon does not appear in the SystemTray

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

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

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

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

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

Answer:

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

Version History

Click Here for the Version History

[End of document]

meatloaf@capesoft.com

Contents

Introduction

Copyright

Support

Installation

Distribution

How To Read this Manual

Example Program

Enabling WinEvent Functions

Multi-DLL applications:

WinAlert Functions

The Concept

The Classic Example

Using the Local WinEvent: Alert Windows Messages Template

Using WinAlert in Applications

For those that care

Using WinAlert in a Hand Coded Project

Comm's Functions

Using Comm's functions in an Application

Functions supplied

Taskbar Functions

Template Supplied

Functions supplied

Window Behaviour Functions

Functions Supplied

Windows System Functions

Functions Supplied

RAM & Disk Functions

Functions Supplied

Registry Functions

Functions Supplied

Time & Date Functions

Functions Supplied

File and Directory Functions

Functions Supplied

Process & Thread Functions

Functions Supplied

DLL Functions

Functions Supplied

SMS Functions

Functions Supplied

Getting Started

Debugging & Error Reporting Functions

Functions Supplied

Auto Shut-down Functions

Functions Supplied

Some Technical Details

Other Functions

Functions Supplied

Reference Guide

WinAlert functions

Comms Functions

Taskbar Functions

Window Behaviour Functions

Windows System Functions

Time & Date Functions

File Functions

DLL Functions

SMS Functions

Debugging & Error Reporting Functions

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

Purpose

Complication

Returns

Example

See Also

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

Parameters

Purpose

Complication

Returns

Example

See Also

WinChangeUserEvent (WinMessageEvent)

Parameters

Purpose

Returns

Example

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

Parameters

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

Parameters

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

Purpose