Introduction
Welcome to WinEvent. This small library package allows
you to leverage the power of the Windows API. In addition to the WinAlert
functions (which allow you access to the native Windows messages) there
are also now Comm's (RS232) functions, Taskbar functions and Windows
Behaviour & System functions.
All the functionality provided in WinEvent is built into Windows itself in
one way or another. The main advantage of WinEvent is two fold.
| Main Advantages |
| It provides the functions in a simple easy-to-use manner,
avoiding the complexities of the Windows API. |
| The functions are (mostly) cross-compatible between 16 and 32
bit implementations of your program. The Taskbar functions and
some advanced Comm's functions are only available in 32 bit
programs, but all the other functions are the same in 16 and 32
bit programs. |
WinEvent functionality is divided into 5 areas:
| Functionality |
Windows message capturing functions
(WinAlert)
WinAlert allows your CW programs more access to the native Window
messages. This is in itself nothing new. Using the sub-classing
technique access to the Windows messages has been available since
almost the first days of CW.
WinAlert provides a simple wrapper to subclassing, which removes
the complexities and makes the code both simple to follow, easy to
implement, and consistent with the rest of the Clarion language.
In essence one new major function, and a couple of support
functions allow the flexibility and ease of use that we've come to
expect from Clarion.
In addition it comes with a template that makes adding this
wrapper to your applications even easier. You can use the template
to alert messages on individual windows. In addition a utility
template makes it possible to enable Auto Shut Down across your
entire application. |
RS 232 Port functions
Very often developers need simple access to a Comm's port. This
simple functionality is built into the Windows API, but is quite
complex and difficult to code. In addition to this the APIs for 16
bit and 32 bit Windows are very different. The Comm's section of
the WinEvent package provides some simple easy-to-use functions
that allow you to read and write to Comm's ports. In addition
almost all the functions are the same in 16 and 32 bit ( the
library takes care of the API differences ) so it's easier to move
from one platform to another. The library also corrects a bug in
the Windows functions that affect Comm's at speeds of greater than
19200. Some advanced functions to test specific hardware
handshaking lines for their current status are only supported in
32 bit as no 16 bit equivalent exists. |
Taskbar functions
Users of Windows 95, and Windows NT 4.0, will be familiar with the
Taskbar that usually sits at the bottom of the screen. The taskbar
functions allow you to add / change and delete an icon from the
"Tray" ( the area at the right hand side of the taskbar ) as well
as detect when the mouse has been clicked on an icon in the tray.
This is very useful for apps which are running in the background
on a full time basis. In addition, you can make use of a function
that prevents your program from appearing on the main area of the
Taskbar itself. |
Window behaviour functions
A small group of functions that allow you to change the behaviour
of a window. This includes the ability to make a window
permanently "on top", and also the ability to bring the window to
the front. |
System functions
These functions return system information to your application. The
Windows, and Dos (if applicable) version numbers are available to
your application. Also you are able to get the current free disk
space in 16 and 32 bit. This is useful for detecting low disk
space conditions before they occur. A function for playing a wav
file is also included. |
Copyright
WinEvent is copyrighted © 2016 by CapeSoft Software.
CapeSoft Software assumes no responsibility for applications created which
incorporate WinEvent. WinEvent is used entirely at your own risk. You may
not distribute any of the WinEvent files.
Each developer needs his own license to use WinEvent. (Need to
buy more licenses?)
Support and Purchase
We welcome your comments, suggestions, and criticisms.
Please do not hesitate to contact us if you have a problem, or a
suggestion.
You can contact CapeSoft in one of the following ways:
| CapeSoft Support |
| Email |
 |
| Telephone |
+27 87 828 0123 |
| Fax |
+27 21 715 2535 |
| Post |
PO Box 511, Plumstead, 7801, Cape Town, South Africa |
WinEvent may be purchased from:
| CapeSoft Sales |
| Web |
www.capesoft.com
|
| Email |
 |
| Telephone |
+27 87 828 0123 |
| Fax |
+27 21 715 2535 |
| Post |
PO Box 511, Plumstead, 7801, Cape Town, South Africa |
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 7.3 and 8 |
claWE.DLL |
| Clarion 7.1 and 7.2 |
c70WE.DLL |
| Clarion 6 |
WE60X.DLL |
| Clarion 5.5 |
WE55X.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.
On the Settings tab of the WinEvent global extension
template:
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
WE::WM_NCMOUSEMOVE |
Event:MouseMove |
| WE::WM_TIMER |
Event:Timer |
WE::WM_LBUTTONDOWN
WE::WM_RBUTTONDOWN
WE::WM_NCRBUTTONDOWN
WE::WM_NCLBUTTONDOWN
WE::WM_NCMBUTTONDOWN
WE::WM_MBUTTONDOWN |
Event:MouseDown |
WE::WM_LBUTTONUP
WE::WM_RBUTTONUP
WE::WM_NCRBUTTONUP
WE::WM_NCLBUTTONUP
WE::WM_NCMBUTTONUP
WE::WM_MBUTTONUP |
Event:MouseUp |
Please Note: If using the WE::WM_MouseWheel
on a window with a listbox, then only the mouse wheel events occurring
when the mouse wheel button is depressed will be passed to the WinAccept.
Windows will only pass on the mouse wheel events when a list box is not
present. Also, in order to determine whether the mousewheel is scolled
forward or backward, use the WinParam1() function. The positive value
indicates a scroll up and the negative value indicates a scroll down.
For those that care
Basically when you ask Windows to shut itself down it polls each running
application by sending it the WM_QueryEndSession message. If all the
applications respond by returning True, then they are each, in turn,
instructed to close. In the above line of code you are telling the
WinEvent library, that when the window receives this message, then it must
return True. The utility template automatically adds an instance of the
WinEvent extension template to each of your procedures.
Using WinAlert in a Hand Coded Project
This details how to add WinAlert functionality to a hand-coded project.
For a detailed description of each of the functions, see the Reference
section of this document.
| Adding WinAlert to a function |
| Use the WinAlert function to alert the message. This should be
called before the Accept command, but after the window is opened. |
| Use the WinAlert function, with no parameters, before Closing
the window. |
| Use the WinEvent's WinControl, WinParam1 and WinParam2 functions
to examine the message. |
| Enabling WinAlert in the root module |
| Include the (supplied in \clarion\libsrc ) map file,
EventMap.Clw, in your Global Map. |
| Include the (supplied in \clarion\libsrc ) equates file,
EventEqu.Clw in your main module's data section. |
Clarion 5: Add the Event532.Lib file
to your project for Stand-Alone compile mode or EvLib532.Lib for
Local compiles. All these library files are in your
\clarion5\3rdparty\lib directory.
Clarion 5.5: Add the we55x.Lib file to
your project for Stand-Alone compile mode or we55xL.Lib for Local
compiles. All these library files are in your \clarion
55\3rdparty\lib directory.
Clarion 6: Add the we60x.Lib file to
your project for Stand-Alone compile mode or we60xL.Lib for Local
compiles. All these library files are in your \clarion
60\3rdparty\lib directory. |
Note: A WinEvent Demo has been included
with WinEvent (\Clarion X\3rdParty\examples\WinEvent\Demo\windemo.app) and
can be used to view how these features can be used.
Comm's Functions
The Comm's section of the WinEvent package provides
some simple easy-to-use functions that allow you to read and write to
Comm's ports (RS232).
Using Comm's functions in an Application
Add the
Enable WinEvent Functions
extension template to your Global extensions.
| Using Comms functions in a hand-coded project |
| Include the (supplied in \clarion\libsrc ) map file,
EventMap.Clw, in your Global Map. |
| Include the (supplied in \clarion\libsrc ) equates file,
EventEqu.Clw in your main module's data section. |
Clarion 5: Add the Event532.Lib file
to your project for Stand-Alone compile mode or EvLib532.Lib for
Local compiles. All these library files are in your
\clarion5\3rdparty\lib directory.
Clarion 5.5: Add the we55x.Lib file to
your project for Stand-Alone compile mode or we55xL.Lib for Local
compiles. All these library files are in your
\clarion55\3rdparty\lib directory.
Clarion 6: Add the we60x.Lib file to
your project for Stand-Alone compile mode or we60xL.Lib for Local
compiles. All these library files are in your
\clarion6\3rdparty\lib directory. |
Functions supplied
Newport
ReadPort
WritePort
ResetPort
ClosePort
KillAllPorts
SetHandShake
CtsHigh
DsrHigh
RingHigh
CdHigh
SetRts
SetDtr
For a detailed description of each of the functions, see the reference
section. You will need to handcode the functions into your application
where you need them.
Taskbar Functions
There are a number of Taskbar functions which allow
your application to interact with the Windows Taskbar. These functions
allow you to add icons to the Taskbar's tray, add balloon text, menu
option and also allow you to prevent your application (icon) from
appearing on the taskbar.
Template Supplied
An Extension template has been provided to add an icon to the tray. This
icon will automatically be put in the tray when the window is opened, and
automatically removed when the window is closed. You can also use the
functions in hand code to add, change and remove icons at will.
If you place an Icon in the tray, then you will also probably want to
capture mouse events when the user interacts with this icon. We've
included some generic default behaviour, but you may like to add some more
options. In WinEvent this is done automatically for you. The template also
takes care of all the details - there are embed points so you can add your
code for the event, and there are buttons on the AddIcon template to
easily get to those embed points.
Tip: Use the Mouse Right Up embed point
for opening a Pop-up menu.
- The name of the icon to add is the
filename of the icon to add to the systemtray. You can use a ~ to use
icons included in the project.
- The Icon tip is the text for the default
tooltip that will appear. You can change this at runtime using the WinTaskBarChangeIcon function
- Note: For use with services, you must use the icon handle to change
the icon at runtime.
- Use the Code to Run when Events are received
button to get to the embed points to code in your handcode to run when
handling received events. If you used the old embed points (where
there was one button for each embed point on the template) - then
check the Show Old Event Buttons checkbox
and you will be able to edit your previous code through the Old
Embeds tab.
- The Add Show|Hide|Close Menu to right-click
Popup option allows the template to build this functionality
into the taskbar icon easily. These are pretty standard functions that
you will probably require when using the taskbar functionality.
- Checking the Hide Window on Startup
option will ensure that your application opens in minimized mode when
starting.
- Checking the Not on Toolbar when Minimized
will make sure that your window is removed from the taskbar when
minimizing (so that it will only appear in the systemtray).
- Checking the Only Close from popup menu
will mean that when clicking the X button (the red x on the right side
of the titlebar), the application is minimized instead of closing (as
well as all other CloseWindow controls). This means that the user must
exit through the correct option instead of merely clicking the X. If
you would like to allow your user another method of exiting the
application (like through a window option) then you can code the
following:
WE::CloseAllNow = 1
post(event:closewindow)
- Checking the Left click Icon shows window
option will restore the window if the user clicks on the icon in the
system tray.
- You can use the Add items to the popup
button to add other items to the popup menu. You will need to handcode
these calls in as follows:
WE::MouseRightPopup.AddItem('Process','Process
the Records')
You can use menus in the popup as well:
WE::MouseRightPopup.AddItem('Menu','Menu','-',1)
WE::MouseRightPopup.AddItem('Do it','Do it','Menu',2)
- You can use the Handle new popup items
button to add other items to the popup menu. You will need to handcode
these calls in as follows (the code needs to appear between the 'Run
popup for Show|Hide|Close' and the 'Perform Show|Hide|Close' embed
points):
of 'Process the Records'
ProcessTheRecords()
Note : The message is ultimately processed
by the Accept command. If your program spends a long time processing
between calls to the Accept loop then you may notice a delay between
clicking on the Icon, and the execution of your embedded code. For better
responses make sure your program frequently returns to the Accept command.
Note: If you have
hand-coded
handling these events then you should be aware that the method has changed
and
your old code will no longer work. In the
past the event came through as WinMessageEvent. This has been changed -
the mouse events are now separated and come through as
WinMessageEvent+500+x where x is 512 (mouse move) or 513(mouse left down)
or 514(mouse left up) or 515(double left click) or 516(mouse right down)
or 517(mouse right up).
Note: As from windows Vista the Timer
parameter to ds_WinTaskBarBaloon no longer has any effect. Notification
display times are now based on system accessibility settings. See
https://msdn.microsoft.com/en-us/library/windows/desktop/bb773352(v=vs.85).aspx
Functions supplied
WinTaskbarAddIcon
WinTaskbarChangeIcon
WinTaskbarRemoveIcon
WinNotOnTaskbar
ds_WinTaskbarBalloon
For a detailed description of each of the functions, see the reference
section.
Window Behaviour Functions
Windows System Functions
RAM & Disk Functions
Registry Functions
Functions Supplied
ds_GetReg
ds_PutReg
For a detailed description of each of the functions, see the reference
section.
Time & Date Functions
File and Directory Functions
Process & Thread Functions
DLL Functions
SMS Functions
Getting Started
Functions Supplied
ds_GSMSendSMS
ds_GSMEnterPin
ds_GSMEchoOFF
ds_GSMSetSMSTextmode
ds_GetGSMReply
ds_EmptyPort
ds_GSMReadSMSInit
ds_GSMReadSMS
ds_GSMDeleteSMS
ds_GSMSetSMSReporting
ds_GSMSelectSR
ds_GSMReadSMSReportInit
ds_GSMReadSMSReport
ds_GSMDeleteSMSReport
ds_GSMReadEvents
ds_GSMSetEvents
ds_GSMReset
For a detailed description of each of the functions, see the reference
section.
Getting Started
First, some Important info:
Note: Using a GSM modem is really the only
way to send and receive SMSes using WinEvent. Phones themselves vary
widely in the ability to handle GSM and every manufacturer's GSM protocol
(Commands, etc) are so widely varied, that they will be impossible to
support (although you may be lucky - but to avoid the frustration, get a
modem).
Note: Only the standard Charset is
supported at this stage.
Note: Modems tested with WinEvent: Siemens
TC35i, SonyEricson GT47 and Wavecom Wismo (serial only). Please
let
us know if you have tested with other models of Modems, and we'll
add those to this list.
First call NewPort and wait for it to finish before sending an sms - it
will look something like the following:
LOC:SMSPortID = NewPort('COM' &clip(left(pComport)) &':'
&clip(left(pBaud)) &', ' &clip(left(pParity)) &', '
&clip(left(pPData)) &', ' &clip(left(pStop)))
You need to wait a couple of seconds between sending SMS's. You can use a
window timer event for this. Have a look at the
ds_GSMSendSMS
function for details.
Make sure there is space on the SIM card (although you shouldn't need the
space unless you are reading SMS's, but it's a good idea anyway). Take a
look at the
ds_GSMReadSMS and
ds_GSMDeleteSMS
functions.
Debugging & Error Reporting
Functions
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
Reference Guide
WinAlert
WinAlert
(<FromMessage>, <ToMessage>, <Action> )
Parameters
| Parameter |
Description |
| 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.
|
Description
This function works in a very similar way to the normal Clarion ALERT
function. Where the ALERT function traps keystrokes, the WINALERT function
traps Windows Messages.
However in addition to merely spotting the messages you can also specify
the action required when the message comes along. The messages are
automatically trapped for the current window. In other words you must open
the Window before alerting the Windows messages for that window.
NOTE : If all three parameters are omitted
then the WinAlerts for that window are removed. This must be done before
closing a window if any messages were alerted for that window.
The actions are split into two groups, and a single action from each group
(i.e. up to 2 actions) are allowed. The actions are as follows:
Group 1
| 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
| Example |
code
open(window)
WinAlert(WM_QueryEndSession,Return0)
!!! All the normal processing goes
here
WinAlert() !
DON'T FORGET THIS !!!!!
Close(Window) |
See Also
WinChangeUserEvent () : To change the
User event posted back to your App.
Winevent, WinControl, WinParam1, WinParam2
Winevent()
WinControl()
WinParam1()
WinParam2()
Parameters
None
Description
The WinEvent function is used when a User Event is received to determine
which Windows message caused the event. It is not cleared after use and
remains available until the next Alerted Windows message is received. The
WinParam1 and WinParam2 functions return the windows parameters for that
message. The WinControl function returns the handle of the specific window
that received the message. You can then use this handle to check which
control received the event.
Complication
If more than one Windows message is alerted, and both alerted messages are
received in close succession, then Winevent() returns only the last
received of the messages.
Returns
The last alerted Windows message received.
Example
| Example |
code
case Event() - WinMessageEvent
of 0 ! WinMessageEvent
case Winevent()
of WM_MouseMove
! something goes here - can
also use WinParam1() and WinParam2() here
end
of 5502 ! WM_SYSCOMMAND
of 5506 ! WM_WTSSESSION_CHANGE
end |
See Also
WinAlert : For alerting windows messages
WinSysEvent : For handling the wm_SYSCOMMAND
windows message.
WinWtsEvent : For handling the
wm_WTSSESSION_CHANGE windows message.
WinChangeUserEvent
WinChangeUserEvent
(WinMessageEvent)
Parameters
| Parameter |
Description |
| WinMessageEvent short |
The Event to post when an alerted windows message is received. |
Description
WinMessageEvent is an equate defined in the WM.CLW file. If you want to
change it from it's default value of 500h then change it in this file, and
call the WinChangeUser function early in your application. Once changed,
it remains changed for all alerted windows messages.
Returns
Nothing
Example
| Example |
code
WinChangeUser(WinMessageEvent) |
WinSysEvent
WinSysEvent(byte
pClearAfterRead=0)
WinSysParam1()
WinSysParam2()
Parameters
| Parameter |
Description |
| byte pClearAfterRead |
Default FALSE. If set TRUE the WinSysEvent is reset to zero
after reading. |
Description
An extension of the WinEvent function. WinSysEvent is used instead of
WinEvent when a wm_SYSCOMMAND message is alerted. WinEvent is still used
for other windows messages. If the pClearAfterRead is not TRUE then
WinSysEvent remains available until the next wm_SYSCOMMAND Windows message
is received. The WinSysParam1 and WinSysParam2 functions return the
windows parameters for that message.
Returns
ulong : wm_SYSCOMMAND
Example
| Example |
code
case Event() - WinMessageEvent
of 0 ! WinMessageEvent
of 5502 ! WM_SYSCOMMAND
if WinSysEvent(TRUE) = WM_SYSCOMMAND
if WinSysParam1() = 61824 ! SC_CONTEXTHELP
QuestionMarkPressed = TRUE
end
end
of 5506 ! WM_WTSSESSION_CHANGE
end |
See Also
WinAlert : For alerting windows messages
WinEvent : For handling standard windows messages.
WinWtsEvent : For handling the
wm_WTSSESSION_CHANGE windows message.
WinWtsEvent
WinWtsEvent(byte
pClearAfterRead=0), WinWtsID()
Parameters
| Parameter |
Description |
| byte pClearAfterRead |
Default FALSE. If set TRUE the WinWtsEvent is reset to zero
after reading. |
Description
An extension of the WinEvent function. WinWtsEvent is used instead of
WinEvent when a wm_WTSSESSION_CHANGE message is alerted. WinEvent is still
used for other windows messages. If the pClearAfterRead is not TRUE then
WinWtsEvent remains available until the next wm_WTSSESSION_CHANGE Windows
message is received. The WinWtsID function returns the session ID linked
to the event.
Returns
WTS session change event.
| Value |
Meaning |
WTS_CONSOLE_CONNECT
0x1 |
A session was connected to the console session. |
WTS_CONSOLE_DISCONNECT
0x2 |
A session was disconnected from the console session. |
WTS_REMOTE_CONNECT
0x3 |
A session was connected to the remote session. |
WTS_REMOTE_DISCONNECT
0x4 |
A session was disconnected from the remote session. |
WTS_SESSION_LOGON
0x5 |
A user has logged on to the session. |
WTS_SESSION_LOGOFF
0x6 |
A user has logged off the session. |
WTS_SESSION_LOCK
0x7 |
A session has been locked. |
WTS_SESSION_UNLOCK
0x8 |
A session has been unlocked. |
WTS_SESSION_REMOTE_CONTROL
0x9 |
A session has changed its remote controlled status. To determine
the status, call GetSystemMetrics and check the SM_REMOTECONTROL
metric. |
Example
| Example |
code
case Event() - WinMessageEvent
of 0 ! WinMessageEvent
of 5502 ! WM_SYSCOMMAND
of 5506 ! WM_WTSSESSION_CHANGE
case WinWtsEvent(TRUE)
of 5 ! WTS_SESSION_LOGON
NewSessionID = WinWtsID()
end
end |
See Also
WinAlert : For alerting windows messages
WinEvent : For handling standard windows messages.
WinSysEvent : For handling the wm_SYSCOMMAND windows message.
NewPort
NewPort (string
pmode, <long pInb>, <long pOutb>,byte pUseEvents=0)
Description
Opens a port for sending or receiving.
Parameters
| Parameter |
Description |
| mode ( string ) |
This is a mode string such as would be accepted by the Dos MODE
command. |
in buffer size (long) ( optional parameter - default 512 bytes )
out buffer size (long) ( optional parameter - default 512 bytes )
These are the sizes Windows must use for the In and Out buffers.
pUseEvents (byte) (optional parameter - default = 0)
When set (TRUE) the current window will receive com events.
Comms transmit buffer empty event = WinEventMessage + 5601
Comms characters received = WinEventMessage + 5602
Comms handshaking lines changed = WinEventMessage + 5602
Returns: Long
<0 if an error has occurred. Otherwise a port number used by readport
and writeport.
Examples
| Example |
PortId = NewPort('Com1:9600,n,8,1')
PortId = NewPort('Com2:9600,n,8,1',1024)
PortId = NewPort('Com3:9600,n,8,1',1024,1024) |
Tip : The window structure must have the
SYSTEM attribute. If it does not then ReadPort will fail.
ResetPort
ResetPort (mode
string)
Description
Resets the parameters for a port while the port is open. Note that this
function can only be called for a port that has already been opened using
the NewPort command.
Parameters
| Parameter |
Description |
| mode (string) |
This is a mode string such as would be accepted by the Dos MODE
command. |
Returns: long
< 0 if an error occurred. Otherwise 0.
Example
| Example |
| result = ResetPort('Com1:9600,n,8,1') |
ClosePort
ClosePort(PortId
long)
Description
Closes a port so it can be used by another program.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
Returns : long
Nothing
Example
| Example |
pid = NewPort ('Com1:9600,n,8,1')
! some code goes here
ClosePort(Pid) |
KillAllPorts
KillAllPorts ( )
Description
Closes all open ports.
Returns
Nothing
Example
WritePort
WritePort(PortId
long, *String string, Length long)
Description
Writes a string into the transmission buffer.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
| String (string) |
This is the handle for the string to send. Note: don't use
string functions like clip, sub, etc when passing this string. |
| Length (long) |
This is the number of bytes to send. If 0 then the string is
clipped and sent.
|
Returns: long
< 0 if an error. Otherwise number of bytes sent.
Example
| Example |
pid = NewPort ('Com1:9600,n,8,1')
buf = 'abcdefghij'
bytessent = WritePort(pid,buf,10)
Note: Do not use:
if WritePort(pid,buf,10) >= 0
!Successful write
end
instead of:
bytessent = WritePort(pid,buf,10)
if bytessent
!Successful write
end |
ReadPort
ReadPort (PortId
long, *String string, Length long)
Description
Read bytes out of the receive buffer.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
| String (string) |
This is the handle of the string in which to put the received
bytes. Note: don't use string functions like clip, sub, etc when
passing this string. |
| Length (long) |
This is the maximum number of bytes to receive. If 0 then the
receive string will be filled if possible. |
Returns: long
< 0 if an error. Otherwise number of bytes received. If 0 then the
receive buffer is empty.
Example
| Example |
pid = NewPort ('Com1:9600,n,8,1')
bytesreceived = ReadPort(pid,buf,0) |
Tip: The window structure must have the
SYSTEM attribute. If it does not then ReadPort will fail.
Tip: To monitor the port in the
background (i.e. without hogging processing time) - you can put the
ReadPort in a timer event (Timer set to at least 100 - unless for mission
critical timing applications). If the ReadPort returns a 0 then just skip
the code for handling the buffer code. In 32bit, windows has an almost
unlimited COMPort buffer, so you don't have to worry about comms going
missing (if it's not monitored in a tight loop).
SetHandShake
SetHandShake (PortId
long, HandShake long)
Description
To Set or Remove port handshaking
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
| HandShake (long) |
This is one of the following : 0 = No Handshaking ; 1 = Xon/Xoff
; 2 = DSR/DTR ; 3 = CTS/RTS |
Returns: long
0 if an error.
>0 if successful.
-1 if invalid PortId
Example
| Example |
pid = NewPort('Com1:9600,n,8,1')
result = SetHandShake(pid,1) |
CtsHigh
CtsHigh (Pid Long)
Description
Returns the current status of the CTS (Clear to Send) line. For advanced
programming only.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
Returns
1 if high. 0 if low.
Example
| Example |
pid = NewPort('Com1:9600,n,8,1')
result = CtsHigh(pid) |
DsrHigh
DsrHigh(Pid Long)
Description
Returns the current status of the DSR (Data Send Ready) line. For advanced
programming only.
Parameters
PortId (long) This is the port number as returned by the NewPort function.
Returns
1 if high. 0 if low.
Example
| Example |
pid = NewPort('Com1:9600,n,8,1')
result = DsrHigh(pid) |
RingHigh
RingHigh (Pid Long)
Description
Returns the current status of the RI (Ring Indicator) line. For advanced
programming only.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
Returns
1 if high. 0 if low.
Example
| Example |
pid = NewPort('Com1:9600,n,8,1')
result = RingHigh(pid) |
CdHigh
CdHigh (Pid Long)
Description
Returns the current status of the CD (Carrier Detect) line. For advanced
programming only.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
Returns
1 if high. 0 if low.
Example
| Example |
pid = NewPort('Com1:9600,n,8,1')
result = CdHigh(pid) |
SetRts
SetRts (Pid Long,
Value Long)
Description
Sets the current status of the RTS (Ready to Send) line. For advanced
programming only.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
| Value long) |
Set to 0 to Clear the RTS line, Set to 1 to Set the RTS line. |
Returns
Nothing
Example
| Example |
pid = NewPort('Com1:9600,n,8,1')
tRts(pid,1) |
SetDtr
SetDtr(Pid Long,
Value Long)
Description
Sets the current status of the DTR (Data Terminal Ready) line. For
advanced programming only.
Parameters
| Parameter |
Description |
| PortId (long) |
This is the port number as returned by the NewPort function. |
| Value (long) |
Set to 0 to Clear the DTR line, Set to 1 to Set the DTR line. |
Returns
Nothing
Example
| Example |
pid = NewPort('Com1:9600,n,8,1')
SetDtr(pid,1) |
WinTaskbarAddIcon
WinTaskbarAddIcon(IconName
String,< Tips String>,byte pSetVersion5=0,<string
pIconModule>), long
Description
Adds an Icon to the TaskBar's "Tray" area. This icon belongs to the window
that's open when the function is called. At least one window must be open
when this function is called. When the user clicks on this icon then an
event is generated and sent to the owner window. The event generated is
the WinUserEvent ( usually 0500h ). This event is generated whenever a
WinAlerted message is received. You can then use the Winevent() function
to return the specific message that triggered the event. If the user
clicked on an icon in the tray, then the Winevent() function will return
the number 25000.
Parameters
| Parameter |
Description |
| IconName (string) |
This is the name of the icon to display. The icon is an ICO file
stored on the disk (or prefix with a '~' to use an icon in the
project). |
| Tips (string) |
This parameter is optional. If you put a string in here, then
this will be the tip displayed when the mouse rests on the icon in
the tray. |
| pSetVersion5 (byte) |
|
| pIconModule (string) |
this is the name of the module containing the icon (if the icon
is in the project). Blank will default to the EXE. This is only
required if: 1) this is not an EXE and 2) the IconName is prefixed
with a '~' and 3) the icon is not in the EXEs project (but in this
or another loaded DLL). |
Returns : long
Icon Id. This Id is used by the Remove and Change functions
Example
| Example |
id long
code
open(window)
id = WinTaskBarAddIcon('happy.ico','click on me....')
accept
!! usual window processing
goes here
case event()
of 5513 !MouseLeftDown
! the user has clicked on
the icon in the tray.
! do something here, like
a popup menu...
of 5514 !MouseLeftUp
of 5515 !double left click
of 5516 !mouserightdown
of 5517 !mouserightup
of 5510 !load icon
of 5501 !refresh icon
of 6026 ! balloon opened
of 6027 ! balloon closed
of 6028 ! balloon timeout, closed
end
end
close(window) |
WinTaskbarRemoveIcon
WinTaskbarRemoveIcon(<Id
long>)
Description
Removes an Icon from the Taskbar's tray.
Parameters
| Parameter |
Description |
| Id (long) |
This is the Id number as returned by the Add function. If this
parameter is omitted then all icons placed by this window will be
removed. |
Returns
Nothing
Example
| Example |
id long
code
open(window)
id = WinTaskBarAddIcon('happy.ico','click on me....')
WinTaskBarRemoveIcon(id) ! or
....
WinTaskBarRemoveIcon() |
WinTaskbarChangeIcon
WinTaskbarChangeIcon(<Id
long>, IconName string,<Tips string>,<string
pIconModule>)
Description
Changes the icon and / or tool tip for a specific icon that is already
placed in the tray. Use this function to update the icon to display your
program status.
Parameters
| Parameter |
Description |
| Id (long) |
The Icon identifier as returned by the Add function. If omitted
then the first icon added by this window will be changed. |
| IconName (string) |
The name of the icon to use. |
| Tips ( string ) |
The new tool tip for the icon. If omitted then the tip will be
cleared. |
| pIconModule (string) |
this is the name of the module containing the icon (if the icon
is in the project). Blank will default to the EXE. This is only
required if: 1) this is not an EXE and 2) the IconName is prefixed
with a '~' and 3) the icon is not in the EXEs project (but in this
or another loaded DLL). |
Returns
Nothing
Example
| Example |
id long
code
open(window)
id = WinTaskBarAddIcon('happy.ico','click on me....')
WinTaskBarChangeIcon(id,'sad.ico','Im sooo sad') |
Additional notes:
There are 3 events available for event tracking:
- 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
ds_WinTaskbarBalloon(<ulongpID>,string
pText,<string pTitle>,uLong pFlags=1,ulong pTimeout=1500)
Description
This opens a "balloon" linked to the system tray icon. The balloon will
stay open until either the user closes it or the user gives focus to the
application.
There is a minimum time that the balloon will be open. This is used in
cases where another balloon (different application) is requested.
Balloons are not supported in win95 or win98 so WinEvent supplies a
XP/Vista "look alike".
Parameters
| Parameter |
Description |
| pID (ulong) |
Optional. Returned by WinTaskbarAddIcon. Is used to identify
which icon to attach the balloon to. |
| pText (string) |
The balloon text. If no balloon text is supplied then any open
balloon is closed. Embedding '<13,10>' in the text produces
multiline text. |
| pTitle (string) |
Optional. The balloon title. Icons only appear if the title is
supplied. |
| pFlags (uLong) |
Optional. Default = 1 (An information icon).
WE::NIIF_ERROR EQUATE(003h) An error icon.
WE::NIIF_INFO EQUATE(001h) An information icon. (Default)
WE::NIIF_NONE EQUATE(000h) No icon.
WE::NIIF_WARNING EQUATE(002h) A warning icon.
WE::NIIF_NOSOUND EQUATE(010h) XP/Vista only. Do not play the
associated sound. |
| pTimeout (ulong) |
Optional. Default=1500 (15 seconds).
Balloon minimum display time in 100ths of a second. (clarion
time)
Note: As from windows Vista
the Timer parameter no longer has any effect. Notification display
times are now based on system accessibility settings. See
https://msdn.microsoft.com/en-us/library/windows/desktop/bb773352(v=vs.85).aspx |
Returns
Nothing
Example
| Example |
ID long
code
ID = WinTaskbarAddIcon('~MyAppIcon.ico','This is my tip
text.<13,10>This is on line 2.')
ds_WinTaskbarBalloon(ID,'This is the balloon
text.<13,10>This is on line 2.','This is the title.')
......
ds_WinTaskbarBalloon(ID,'')
case Event() - WinMessageEvent
of 6026
of 6027
of 6028
of 6029
end ! case
|
Faultfinding
If the balloon is not displaying, then try the winevent demo application
(Go to Taskbar Functions - and you will find the show|hide balloon buttons
that you can use to test this functionality). If it is not working, then
you have balloontips turned off in your windows registry. Search for
BalloonTips, and change the value of the key you find from 0 to 1.
WinNotOnTaskbar
WinNotOnTaskbar()
Description
Applications using this function do not appear on the Windows 95 Task bar.
This is normally
used in conjunction with the WinTaskBarAddIcon when you want a background
program to
appear on the Taskbar's tray, and not on the taskbar itself. It must be
called before the first
window of the application is opened.
IMPORTANT Note : WinNotOnTaskBar is not
compatible with auto-shutdown.
If you are using WinTaskBarAddIcon then the following code may be used as
an alternative.
To hide the window
window{prop:iconize} = TRUE
window{prop:hide} = TRUE
To unhide the window
window{prop:hide} = FALSE
window{prop:iconize} = FALSE
Note that the order of the hide / iconize
commands is important
Parameters
None
Returns
Nothing
Example
| Example |
code
WinNotOnTaskBar()
open(window) |
WinOnTop
WinOnTop()
Description
Makes your window float on top of other windows applications. Note: you
can't use this function for MDI applications on MDI-child windows.
Parameters
None
Returns
Nothing
Example 1
| Example |
code
open(window)
WinOnTop() |
Example 2
| Example |
! -------------------------------------
! Hides Window (opposite of WindowShow)
! Useful for use with the TaskBar icon code
WindowHide Routine
window{prop:iconize}
= true
window{prop:hide}
= true
! -------------------------------------
! Shows Window (opposite of WindowHide)
! Useful for use with the TaskBar icon code
WindowShow Routine
if window{prop:iconize} = false
window{prop:iconize}
= true
end
window{prop:hide}
= false
window{prop:iconize}
= false
! -------------------------------------
! Shows Window (opposite of WindowHide)
! Useful for use with the TaskBar icon code
! No Focus is gained
WindowShow_NoFocus Routine
window{prop:iconize}
= false
window{prop:hide}
= false
WinOnTop()
WinNotOnTop() |
WinNotOnTop
WinNotOnTop()
Description
Reverses the effect of the WinOnTop() function. Note: you can't use this
function for MDI applications on MDI-child windows.
Parameters
None
Returns
Nothing
Example
| Example |
code
open(window)
WinOnTop()
WinNotOnTop() |
WinBringToFront
WinBringToFront()
Description
Brings your window to the front of the open windows. This would be used if
your program wanted to bring itself to the front because some event has
occurred that needs action.
Note: you
can't use this function for MDI applications on MDI-child windows.
Parameters
None
Returns
Nothing
Example
| Example |
code
open(window)
WinBringToFront() |
ds_ShowWindow
ds_ShowWindow(byte
pGrabFocus=1)
Description
Unhides your window. This is used in conjunction with ds_HideWindow.
Parameters
| Parameter |
Description |
| pGrabFocus (byte) |
Optional. Defaults to TRUE. When set you window takes focus
and so keyboard input goes to your window. |
Returns
Nothing
Example
| Example |
code
open(window)
ds_ShowWindow() |
ds_HideWindow
Description
Hides your window. This is used in conjunction with ds_ShowWindow.
Parameters
None
Returns
Nothing
Example
| Example |
code
open(window)
ds_HideWindow()
|
ds_WinTransparent
ds_WinTransparent(long
Transparency)
NB: Only available for non-MDI windows.
Description
Adjusts the transparency of a window .
Parameters
| Parameter |
Description |
| Transparency (long) |
This sets the transparency factor. 0 = Invisible, 255 =
Normal. |
Returns
Nothing
Example
| Example |
code
open(window)
ds_WinTransparent(255) ! normal
window display
ds_WinTransparent(0)
! window will be invisible |
ds_VisibleOnDesktop
ds_VisibleOnDesktop(<*long
pWinX>,<*long pWinY>,<*long pWinWidth>,<*long
pWinHeight>,long pMode=1)
Description
Repositions and resizes the window to be visible on the desktop. This is
particularly useful if the window position was saved off the desktop (in a
previously visible place that is now no longer visible). WinEvent will
move the window onto the visible desktop area.
Parameters
| Parameter |
Description |
| pWinX (*long) |
Optional. If omitted then the current target window is used.
If supplied then the variable is updated. |
| pWinY (*long) |
Optional. If omitted then the current target window is used.
If supplied then the variable is updated. |
| pWinWidth (*long) |
Optional. If omitted then the current target window is used.
If supplied then the variable is updated. |
| pWinHeight (*long) |
Optional. If omitted then the current target window is used.
If supplied then the variable is updated. |
| pMode (long) |
Optional. Default=1 When set this flags that the window must
not be obscured by the taskbar. |
Returns
Nothing
Example
| Example |
code
open(window)
Open(Window)
ds_VisibleOnDesktop() |
ds_GetWinVersion
ds_GetWinVersion()
Description
Returns the version of windows that is running.
Parameters
None
Returns
String formatted with Windows version, Windows edition, major version
number, minor version number, build number and then service pack
description.
Win XXX ...............
Note: At least up to Clarion 6.3 9056, the
Clarion IDE is run in XP compatibility mode on Windows Vista. This means
that when running an application from within the IDE, the ds_GetWinVersion
will return Win XP, and not Win Vista. The same application run from a
normal shortcut will return the correct windows version (i.e. Win Vista).
Note: As from Windows 8.1 this function
will return the OS that the app is manifested for. In other words if you
are running on version 8.1, but the app is only manifested for Windows 8,
then this function will return Windows 8.
Example
| Example |
code
DisplayString = ds_GetWinVersion()
case sub(ds_GetWinVersion(),1,8)
of 'Win 3.1'
of 'Win 95'
of 'Win 98'
of 'Win NT'
of 'Win 2K'
of 'Win 2K3'
of 'Win XP'
of 'WinVista'
of 'Win 7'
of 'Win 2008'
of 'Win 8'
of 'Win 8.1'
of 'Win 2012'
of 'Win 2012 R2'
of 'Win 10'
else
end |
WindowsVersion
WindowsVersion()
Description
Returns the version of windows that is running. This may return a
different number for 16 and 32 bit programs. For example a 16 bit program,
running under Windows 95 will return 3 as the windows version number. The
version release number is 95. A 32 bit program running under windows 95
will return 4 as the windows version number. The release number is 0.
Parameters
None
Returns
Long containing Windows version number. This together with the release
number (WindowsRelease() ) gives you the version number of windows.
Example
| Example |
code
ver = WindowsVersion() |
WindowsRelease
WindowsRelease()
Description
Returns the release of windows that is running. This may return a
different number for 16 and 32 bit programs. For example a 16 bit program,
running under Windows 95 will return 3 as the windows version number. The
version release number is 95. A 32 bit program running under windows 95
will return 4 as the windows version number. The release number is 0.
Parameters
None
Returns
Long containing Windows release number. This together with the version
number (WindowsVersion() ) gives you the version number of windows.
Example
| Example |
code
ver = WindowsVersion()
rel = WindowsRelease() |
DosVersion
DosVersion()
Description
Returns the version of Dos that is running. This is only valid for 16 bit
programs. For example a 16 bit version of a program running on Windows 95
will return 7 as the version number, and 0 as the release number.
Parameters
None
Returns
Long containing Dos version number. This together with the release number
(DosRelease() ) gives you the version number of Dos.
Example
| Example |
code
ver = DosVersion() |
DosRelease()
DosRelease()
Description
Returns the release of Dos that is running. This is only valid for 16 bit
programs. For example a 16 bit version of a program running on Windows
3.11 and Dos 6.22 will return 6 as the version number, and 22 as the
release number.
Parameters
None
Returns
Long containing Dos release number. This together with the version number
(DosVersion() ) gives you the version number of dos.
Example
| Example |
code
ver = DosVersion()
rel = DosRelease() |
GetFreeDiskSpace
GetFreeDiskSpace
(<drive long>)
Description
Returns the amount of free disk space, in bytes.
Parameters
| Parameter |
Description |
| Drive |
Optional. 0 = current drive. 1 = A, 2 = B etc. |
Returns
Real containing number of free bytes on the disk. In version 2.6 and
earlier of WinEvent this was a Long.
Example
| Example |
free real
code
free = GetFreeDiskSpace() |
GetDiskSpace
GetDiskSpace
(<drive long>)
Description
Returns the total disk space, in bytes.
Parameters
| Parameter |
Description |
| Drive |
Optional. 0 = current drive. 1 = A, 2 = B etc. |
Returns
Real containing total number of bytes on the disk. However maximum value
is currently 2 gigs.
Example
| Example |
total real
code
total = GetDiskSpace() |
ds_GetDiskMegs
ds_GetDiskMegs
(<string pDrive>,<string pSelector>)
Description
Returns the specified disk space, in megabytes.
Parameters
| Parameter |
Description |
| pDrive (string) |
Optional. Defaults to current directory. |
| pSelector (string) |
Optional. Defaults to 'USER FREE' This modifies the returned
disk size.
'USER FREE' Returns the free disk space available to the
current user.
'TOTAL' Returns the total disk size.
'TOTAL FREE' Returns the free disk space on the drive. |
Returns
Ulong. The disk space in megabytes.
Example
| Example |
total ulong
code
total = ds_GetDiskMegs() |
ds_Memory
ds_Memory(<string
pSelector>)
Description
Returns the specified RAM space, in kBytes. (Ram sizes up to 2 terabytes
are supported.)
Parameters
| Parameter |
Description |
| pSelector (string) |
Optional. Defaults to 'USER' This specifies which RAM size is
returned.
'USER' Returns the virtual memory used by this
application.
'SWAP USED' Returns the page file used kBytes.
'SWAP FREE' Returns the page file free kBytes.
'SWAP TOTAL' Returns the page file total kBytes.
'RAM USED' Returns the physical RAM used kBytes.
'RAM FREE' Returns the physical RAM free kBytes.
'RAM TOTAL' Returns the physical RAM total kBytes.
'VMEM USED' Returns the virtual memory used kBytes.
'VMEM FREE' Returns the virtual memory free kBytes.
'VMEM TOTAL' Returns the virtual memory total kBytes. |
Returns
Ulong. The RAM size in kilobytes.
Example
| Example |
total ulong
code
total = ds_Memory() ! Returns the virtual memory used
by this application in Kilobytes |
ds_GetReg
s_GetReg(Long hKey,
String SubKeyPath, String ValueName)
Description
Gets a value out the Windows System Registry.
Parameters
| Parameter |
Description |
| hKey (long) |
The top level key containing the section of the registry to
read. Valid values are;
WE::WM_HKEY_CLASSES_ROOT
WE::WM_HKEY_CURRENT_USER
WE::WM_HKEY_LOCAL_MACHINE
WE::WM_HKEY_USERS |
| SubKeyPath (string) |
The path inside the registry to the item you want to read. |
| ValueName (String) |
The name of the variable you want to read. |
Returns
Any. the value stored in the string. If the read failed the the value 0 is
returned, and the Winevent extended error is set. The Winevent error can
be retrieved using ds_Error and ds_Errorcode functions.
Example
| Example |
htmleditor string(255)
code
htmleditor = ds_GetReg(we::wm_hkey_current_user, |
'Software\Microsoft\Internet Explorer\Default
HTML Editor','Description') |
ds_PutReg
ds_PutReg(Long hKey,
String SubKeyPath, String ValueName, String Value, <Long Type>)
Description
Writes a value to the Windows System Registry.
Parameters
| Parameter |
Description |
| hKey (long) |
The top level key containing the section of the registry to
write. Valid values are;
WE::WM_HKEY_CLASSES_ROOT
WE::WM_HKEY_CURRENT_USER
WE::WM_HKEY_LOCAL_MACHINE
WE::WM_HKEY_USERS |
| SubKeyPath (string) |
The path inside the registry to the item you want to write. |
| ValueName (String) |
The name of the variable you want to write. |
| Value (String) |
The value you want to write into the registry. |
| Type (Long) |
the type of the value you are writing. Valid values are;
WE::REG_SZ !!// Unicode
nul terminated string
WE::REG_EXPAND_SZ !!// Unicode nul terminated string
WE::REG_BINARY !!// Free form binary
WE::REG_DWORD !!// 32-bit number
WE::REG_DWORD_LITTLE_ENDIAN !!// 32-bit number (same as
REG_DWORD)
WE::REG_DWORD_BIG_ENDIAN !!// 32-bit number
WE::REG_MULTI_SZ !!// Multiple Unicode strings
Default value for this parameter is WE::REG_SZ. |
Returns
0 if successful, non zero if not successful. Additional error information
can be read using the ds_Error and ds_ErrorCode functions.
Example
| Example |
htmleditor string(255)
code
htmlEditor = 'Microsoft Expression Web'
ds_PutReg(we::wm_hkey_current_user, |
'Software\Microsoft\Internet Explorer\Default HTML
Editor','Description',htmlEditor,we::reg_sz) |
Sound
Sound (WavFileName
String)
Description
Plays a Wav file through the speaker.
Parameters
| Parameter |
Description |
| WavFileName (string) |
The name of the Wav file on the disk, including path if
necessary. |
Returns
Nothing
Example
| Example |
code
sound('alarm.wav') |
GetWindowsDir
GetWindowsDir ()
Description
Gets the directory where Windows is installed. For multi-user systems this
returns the Windows directory that is personal to the logged in user.
Parameters
None
Returns
A string containing the path to the Windows directory.
Example
| Example |
a string(255)
code
a = GetWindowsDir() |
GetSystemDir
GetSystemDir ()
Description
Gets the Windows system directory.
NOTE : This is usually \windows\system
Parameters
None
Returns
A string containing the path to the Windows system directory.
Example
| Example |
a string(255)
code
a = GetSystemDir() |
ScreenWidth
ScreenWidth ()
Description
Gets the current width, in pixels, of the windows desktop.
Parameter
None
Returns
A long containing the number of pixels.
Example
| Example |
a long
code
a = ScreenWidth() |
ScreenHeight
ScreenHeight ()
Description
Gets the current height, in pixels, of the windows desktop.
Parameters
None
Returns
A long containing the number of pixels.
Example
| Example |
a long
code
a = ScreenHeight() |
ScreenDepth
ScreenDepth ()
Description
Gets the current color depth, in bits, of the windows desktop.
Parameters
None
Returns
A long containing the number of bits. For example 8 = 256 colors, 24 =
true color and so on.
Example
| Example |
a long
code
a = ScreenDepth() |
ds_GetScreenDPI (byte pDPIY=0)
ds_GetScreenDPI
(byte pDPIY=0)
Description
Gets the current DPI of the windows desktop.
Parameters
| Parameter |
Description |
| pDPIY (optional) |
Defaults to X DPI. If set to TRUE then returns Y DPI. These are
usually the same. |
Returns
A long containing the DPI setting. For example 96 = Small fonts, 120 =
Large fonts.
Example
| Example |
a long
code
a = ds_GetScreenDPI() |
ds_GetUserName
ds_GetUserName()
Description
Gets name of user currently logged into Windows.
Returns
A String containing the name.
ds_GetWorkstationName
ds_GetWorkstationName()
Description
Gets the name of the computer as used by Windows networking.
Returns
A string containing the name.
ds_IsMediaCenter()
ds_IsMediaCenter()
Description
Detects if the current version of Windows is a Media Center edition.
Returns
A long set to 1 if the machine is running a Media Center version of
Windows, 0 otherwise.
ds_IsTerminalServer
ds_IsTerminalServer()
Description
Detects if the current machine is running on a terminal server.
Returns
A long , Set to 1 if the current machine is a terminal server. Set to 2 if
the current machine is a terminal server, and the current session is a
remote session.
ds_IsTablet
ds_IsTablet ()
Description
Detects if the current version of Windows is a Tablet edition.
Returns
A long set to 1 if the machine is running a Tablet version of Windows, or
the Tablet PC Input Service has been started. 0 otherwise.
ds_IsStarter
ds_IsStarter()
Description
Detects if the current version of Windows is a Starter edition.
Returns
A long set to 1 if the machine is running a Starter version of Windows, 0
otherwise.
ds_OnNetwork
ds_OnNetwork ()
Description
Detects if the current machine is conencted to a network or not.
Returns
A long, 1 if true 0 if false.
ds_RefreshDesktop
ds_RefreshDesktop()
Description
Refreshes the desktop. Typically called after calling
ds_CreateShortcutEx..
Returns
Nothing
ds_FastClock
ds_FastClock(byte
UseCPUTimeStamp=0,byte ReSyncTime)
Description
Gets the current time down to a resolution of 1µs. This depends on the
presence of a highspeed hardware timer chip in the PC.
Defaults to clock() if no highspeed chip is present. If the
UseCPUTimeStamp flag is set then the ds_ReadCPUTimeStamp() function is
used. NB this will only work on Pentium or better processors.
Parameters
| Parameter |
Description |
| UseCPUTimeStamp (byte) |
Optional, Default = FALSE. If set then the
ds_ReadCPUTimeStamp() function is used to return the time down to
a resolution of the CPU clock. (1 GHz = 1ns resolution) |
| ReSyncTime (byte) |
Optional, Default = FALSE. Use (once) when time has been
adjusted and so ds_FastClock <> Clock(). |
Returns
A real containing the time in clarion time format (100 = 1 second) .
Example
| Example |
ThisTime real
code
ThisTime - ds_FastClock()
DisplayTime = ds_FormatFastTime(ThisTime,4) ! 16:23:31.0124 |
ds_FormatFastTime
ds_FormatFastTime(real
pFastTime,<long pDecimalPlaces>)
Description
Used with ds_FastClock() to display the time including fractions of a
second.
Parameters
| Parameter |
Description |
| pFastTime (real) |
The time in 100 ths of a second (clarion time). |
| pDecimalPlaces (long) |
Optional. The number of decimal places to display. |
Returns
String containing the time.
Example
| Example |
code
DisplayTime = ds_FormatFastTime(ds_FastClock(),4) !
16:23:31.0124 |
ds_Sleep
ds_Sleep(real
pFastTime)
Description
Executes a yield for the duration specified in 100 ths of a second
(clarion time).
This is an API call. The resolution of the time is 1 ms (0.1 in clarion
time).
Parameters
| Parameter |
Description |
| pFastTime (real) |
The time in 100 ths of a second (clarion time) for which to
sleep. |
Returns
None
Example
| Example |
code
ds_Sleep(100.1) ! wait 1.001
seconds |
ds_Timer
ds_Timer(long
pTimerNumber,<real pFastTime>)
Description
General purpose timer.
Note : you are limited to 999 timers per
thread.
the WinEvent SMS functions use
ds_Timer(999) and
ds_Timer(998).
Parameters
| Parameter |
Description |
| pTimerNumber (long) |
Used to specify multiple timers (per thread) |
| pFastTime (real) |
The time in 100 ths of a second (clarion time). |
Returns
Byte, TRUE (1) if timer has elapsed. FALSE (0) if timer has not yet
elapsed.
NOTE: you need to keep checking the timer to see if it is elapsed. There
is no event fired when the timer elapses.
Example
| Example |
code
ds_Timer(1,100.1) ! init timer
1 to 1.001 seconds
loop until ds_Timer(1) !
break when timer 1 elapses.
.....
ds_Timer(1,50) !
Restart timer 1 at 0.5 seconds
.....
end |
ds_WeekDay
ds_WeekDay(long
pDate,<byte pShortFormatFlag>)
Description
Returns the English name for the day of the week.
Parameters
| Parameter |
Description |
| pDate (long) |
The date for which the week day is required. (Clarion date) |
| pShortFormatFlag (byte) |
Optional. If TRUE(1) then the short name for the day is
returned. "Wednesday" would return as "Wed" |
Returns
String containing the day of the week.
Example
| Example |
code
DisplayDay = ds_WeekDay(today()) ! Returns the current day of
the week, i.e. "Wednesday"
DisplayDay = ds_WeekDay(today(),1) ! Returns the current day
of the week, i.e. "Wed" |
ds_ReadCPUTimeStamp
ds_ReadCPUTimeStamp(*realpSaveReal)
Description
Reads the Time Stamp Register of the CPU. NB this will only work on
Pentium or better processors.
Parameters
| Parameter |
Description |
| pSaveREal (*real) |
The 64 bit number returned by the CPU is saved into this real.
Will overflow after 52 bits. (50 days at 1GHz) |
Returns
None
Example
| Example |
ThisTime real
code
ds_ReadCPUTimeStamp(ThisTime) ! Save TimeStamp into
real
......
ds_ReadCPUTimeStampDelta(ThisTime) ! CPU Cycles elapsed.
|
ds_ReadCPUTimeStampDelt
ds_ReadCPUTimeStampDelta(*real
pSaveReal)
Description
Reads the Time Stamp Register of the CPU and subtract the last saved
value. NB this will only work on Pentium or better processors.
Parameters
| Parameter |
Description |
| pSaveREal (*real) |
The 64 bit number returned by the CPU is saved into this real.
Will overflow after 52 bits. (50 days at 1GHz) |
Returns
None
Example
| Example |
ThisTime real
code
ds_ReadCPUTimeStamp(ThisTime) ! Save TimeStamp into
real
......
ds_ReadCPUTimeStampDelta(ThisTime) ! CPU Cycles elapsed. |
ds_DeleteFile
ds_DeleteFile(string
pFileName)
Description
Delete a file. Any read-only attributes are cleared and then the file is
deleted.
Parameters
| Parameter |
Description |
| pFileName (string) |
Specify the file (with path) to delete. |
Returns
Byte, TRUE (1) for success, FALSE (0) for failure.
Example
| Example |
code
ds_DeleteFile('c:\FileName.ext') |
ds_GetFileDirEntry
ds_GetFileDirEntry(string
pFileName,*string pEntryG)
Description
Fills the supplied EntryG structure with the data from the specified file.
This procedure calls the clarion DIRECTORY command. See clarion help for
more info.
Parameters
| Parameter |
Description |
| pFileName (string) |
Specify the file (with path) for which the directory entry data
is required. |
| pEntryG (*string) |
Provide the label of an EntryG structure. See example below. |
Returns
Byte, TRUE (1) for success, FALSE (0) for failure.
Example
| Example |
EntryG group,PRE(EntryG)
name STRING(256)
shortname string(13)
date LONG
time LONG
size LONG
attrib BYTE
end
code
ds_GetFileDirEntry('c:\FileName.ext',EntryG)
! fills the EntryG with the files directory
attributes. |
ds_SetFileAttributes
ds_SetFileAttributes(string
pFileName,byte pNewAttribs)
Description
Set the directory attributes of a file.
Parameters
| Parameter |
Description |
| pFileName (string) |
Specify the file (with path) for which the directory entry data
is required. |
| pNewFileAttribs (byte) |
Specify the new attributes.
ff_:NORMAL EQUATE(0) !Always active
ff_:READONLY EQUATE(1) !Not for use as attributes parameter
ff_:HIDDEN EQUATE(2)
ff_:SYSTEM EQUATE(4)
ff_:DIRECTORY EQUATE(10H)
ff_:ARCHIVE EQUATE(20H) ! NOT Win95 compatible |
Returns
Byte, TRUE (1) for success, FALSE (0) for failure.
Example
| Example |
code
ds_SetFileAttributes('c:\FileName.ext',0)
! clears files attributes. |
ds_CopyDirectory
ds_CopyDirectory(string
Source,string Destination, string Mask, [Long IncludeSubDirectories],
[Long IncludeHiddenFiles], [Long IncludeSystemFiles], [Long
ProgressControl], [Long StringControl]),long
Description
Copy the contents of one folder to another folder. The contents of the
original folder are not deleted. ie this is a Copy, not a Move.
Parameters
| Parameter |
Description |
| Source (string) |
The name of the source directory to copy from. |
| Destination (string) |
The name of the destination directory to copy to. If the
destination directory does not exist it will be created. |
| Mask (string) |
The mask for files in the source folder(s) to copy. For example
*.htm will copy only files with the htm extension. If this
parameter is left blank then the default mask, *.*, will be used. |
| IncludeSubDirectories (long) |
Set to 1 for sub-directories to be copied as well. Set to 0 if
only files must be copied. This parameter is option, the default
value is 0 (ie by default sub-directories are not copied.) |
| IncludeHiddenFiles (long) |
This parameter is optional, the default value is 1. If you do
not want to copy hidden files then set this parameter to 0. |
| IncludeSystemFiles (long) |
This parameter is optional, the default value is 1. If you do
not want to copy system files then set this parameter to 0. |
| ProgressControl (long) |
The Use Equate number of a progress control on the window. If
this is set then the progress bar will be updated as the Copy
command progresses. If it is set to 0 or omitted then no progress
control will be updated. |
| StringControl (long) |
The Use Equate number of a string control on the window that
will be updated with the name of the file currently being copied.
If set to 0, or omitted, then no string control will be updated. |
Returns
Long: The number of files successfully copied. Or a negative number if the
copy failed at a specific file (the numeric value contains the number of
files that were successfully copied before failure).
Example
| Example |
code
ans =
ds_CopyDirectory(FileSelected,CopyTo,'*.*',1,1,1,?Progress1,?String1) |
ds_CreateDirectory
ds_CreateDirectory(string
pNewDirectoryName)
Description
Create a new directory.
Parameters
| Parameter |
Description |
| pNewDirectoryName (string) |
Specify the name (including path) of the new directory to
create. |
Returns
Byte, TRUE (1) for success, FALSE (0) for failure.
Example
| Example |
code
ds_CreateDirectory('c:\My
New Directory') ! creates the
directory |
ds_RemoveDirectory
ds_RemoveDirectory(string pDirectoryName)
Description
Remove a directory.
The directory must be empty.
Parameters
| Parameter |
Description |
| pDirectoryName (string) |
Specify the name (including path) of the directory to remove. |
Returns
Byte, TRUE (1) for success, FALSE (0) for failure.
Example
| Example |
code
ds_RemoveDirectory('c:\My
New Directory') ! removes any
empty directory. |
ds_SetFileDateTime
ds_SetFileDateTime(string
pFileName,long pNewDate,long pNewTime)
Description
Set the date and time of the files directory entry.
Parameters
| Parameter |
Description |
| pFileName (string) |
Specify the file (with path) for which the directory is to be
modified. |
| pNewDate (long) |
New date (clarion date) for the file. |
| pNewTime (long) |
New time (clarion time) for the file. |
Returns
Byte, TRUE (1) for success, FALSE (0) for failure.
Example
| Example |
code
ds_SetFileDateTime('c:\MyFile.txt',today(),clock())
! Sets the files date and time to now. |
ds_MoveFile
ds_MoveFile(string
pFileName,string pNewFileName)
Description
Moves (renames) a file by changing its directory entry.
Parameters
| Parameter |
Description |
| pFileName (string) |
Specify the file (with path) to be moved. |
| pNewFileName (string) |
Specify the new file (with new path). |
Returns
Byte, TRUE (1) for success, FALSE (0) for failure.
Example
| Example |
code
ds_MoveFile('c:\MyFile.txt','c:\NewDirectory\NewFileName.ext')
! moves and renames the file to
the directory. |
ds_GetFolderPath
ds_GetFolderPath(long
pCSIDL,<byte pCreateFlag>)
Description
Returns the specified windows folder path. If the optional CreateFlag is
TRUE then the directory will be created if it does not exist.
Parameters
| Parameter |
Description |
| pCSIDL (long) |
A CSIDL equate specifying the windows folder. |
| pCreateFlag (byte) |
Optional. If TRUE (1) then the folder will be created if it does
not exist. |
NOTE: Some of these equates (in Windows Vista and up) no longer return the
common area folder, but the user folder. This is not a WinEvent issue, as
WinEvent just makes use of the API calls in windows. This is a change in
spec for the API call value parameter by Windows. See:
http://msdn.microsoft.com/en-us/library/dd378457%28v=vs.85%29.aspx
WE::CSIDL_DESKTOP equate(000h)
WE::CSIDL_INTERNET equate(001h)
WE::CSIDL_PROGRAMS equate(002h)
WE::CSIDL_CONTROLS equate(003h)
WE::CSIDL_PRINTERS equate(004h)
WE::CSIDL_PERSONAL equate(005h)
WE::CSIDL_FAVORITES equate(006h)
WE::CSIDL_STARTUP equate(007h)
WE::CSIDL_RECENT equate(008h)
WE::CSIDL_SENDTO equate(009h)
WE::CSIDL_BITBUCKET equate(00Ah)
WE::CSIDL_STARTMENU equate(00Bh)
WE::CSIDL_MYDOCUMENTS equate(00Ch)
WE::CSIDL_MYMUSIC equate(00Dh)
WE::CSIDL_MYVIDEO equate(00Eh)
WE::CSIDL_DESKTOPDIRECTORY equate(010h)
WE::CSIDL_DRIVES equate(011h)
WE::CSIDL_NETWORK equate(012h)
WE::CSIDL_NETHOOD equate(013h)
WE::CSIDL_FONTS equate(014h)
WE::CSIDL_TEMPLATES equate(015h)
WE::CSIDL_COMMON_STARTMENU equate(016h)
WE::CSIDL_COMMON_PROGRAMS equate(017h)
WE::CSIDL_COMMON_STARTUP equate(018h)
WE::CSIDL_COMMON_DESKTOPDIRECTORY equate(019h)
WE::CSIDL_APPDATA equate(01Ah)
WE::CSIDL_PRINTHOOD equate(01Bh)
WE::CSIDL_LOCAL_APPDATA equate(01Ch)
WE::CSIDL_ALTSTARTUP equate(01Dh)
WE::CSIDL_COMMON_ALTSTARTUP equate(01Eh) WE::CSIDL_COMMON_FAVORITES equate(01Fh)
WE::CSIDL_INTERNET_CACHE equate(020h)
WE::CSIDL_COOKIES equate(021h)
WE::CSIDL_HISTORY equate(022h)
WE::CSIDL_COMMON_APPDATA equate(023h)
WE::CSIDL_WINDOWS equate(024h)
WE::CSIDL_SYSTEM equate(025h)
WE::CSIDL_PROGRAM_FILES equate(026h)
WE::CSIDL_MYPICTURES equate(027h)
WE::CSIDL_PROFILE equate(028h)
WE::CSIDL_SYSTEMX86 equate(029h)
WE::CSIDL_PROGRAM_FILESX86 equate(02Ah)
WE::CSIDL_PROGRAM_FILES_COMMON equate(02Bh)
WE::CSIDL_PROGRAM_FILES_COMMONX86 equate(02Ch)
WE::CSIDL_COMMON_TEMPLATES equate(02Dh)
WE::CSIDL_COMMON_DOCUMENTS equate(02Eh)
WE::CSIDL_COMMON_ADMINTOOLS equate(02Fh)
WE::CSIDL_ADMINTOOLS equate(030h)
WE::CSIDL_CONNECTIONS equate(031h)
WE::CSIDL_COMMON_MUSIC equate(035h)
WE::CSIDL_COMMON_PICTURES equate(036h)
WE::CSIDL_COMMON_VIDEO equate(037h)
WE::CSIDL_RESOURCES equate(038h) . WE::CSIDL_RESOURCES_LOCALIZED equate(039h)
WE::CSIDL_COMMON_OEM_LINKS equate(03Ah) WE::CSIDL_CDBURN_AREA equate(03Bh)
WE::CSIDL_COMPUTERSNEARME equate(03Dh)
Note: You cannot use CSIDL_CONTROLS,
CSIDL_PRINTERS, and CSIDL_DRIVES as these are all virtual drives, and the
windows API returns empty strings for these equates.
Returns
String with specified path (in shortpath format). To convert to a
longpath, use the longpath() function.
Example
| Example |
code
DisplayPath =
ds_GetFolderPath(WE::CSIDL_PROGRAMS,1) !
C:\Documents and Settings\username\Start Menu\Programs
DisplayLongPath =
longpath(DisplayPath)
|
Note (a comparison for XP and Vista
returns):
WE::CSIDL_Common_Appdata
XP C:\Documents and Settings\All Users\Application Data
Vista C:\ProgramData
WE::CSIDL_AppData
XP C:\Documents and Settings\user.domain\Application Data
Vista C:\Users\user\Roming
WE::CSIDL_Local_Appdata
XP C:\Documents and Settings\user.domain\Local Settings\Applicatin
Data
Vista C:\Users\user\AppData\Local
WE::CSIDL_Program_Files
XP C:\Program Files
Vista C:\Program Files
ds_GetTempPath
ds_GetTempPath()
Description
Returns the path to the windows temporary directory.
Parameters
None
Returns
String containing the path.
Example
| Example |
code
DisplayPath = ds_GetTempPath() !
C:\WINDOWS\TMP |
ds_String2File
ds_String2File(string
pWriteString,<long pWriteLen>,string pFileName)
Description
Takes a string and saves it to a file.
The file is created if it does not exist. The file is emptied if it does
exist.
Parameters
| Parameter |
Description |
| pWriteString (string) |
String to be written to file. |
| pWriteLen (long) |
Optional. The length of the string to be written to file. If
omitted then the string is clipped before writing to file. |
| pFileName (string) |
The name of the file (including path). |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
code
if ds_String2File('Just
Testing',,'C:\MyTestFile.TXT') !
Creates / empties file and then writes data to file.
message('ds_string2file failed : ' & ds_error())
end |
ds_File2String
ds_File2String(ds_StringRef
pStringRef,<long pMaxLen>,string pFileName)
Description
Reads a file into a string.
Parameters
| Parameter |
Description |
| pStringRef (ds_StringRef) |
The label of a ds_StringRef structure. |
| pMaxLen (long) |
Optional. The max length of the string to be returned. File
contents truncated at this length if required. |
| pFileName (string) |
The name of the file (including path). |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
NB: You must dispose the returned string after
using the contents in order to avoid memory leaks (if the function
succeeds):
dispose(TestFileRead.bin)
Example
| Example |
TestFileRead GROUP(ds_StringRef)
END
code
if ds_string2file('testing 123...',,'c:\testing.txt')
message('ds_string2file failed : ' & ds_error())
end
if ds_file2string(TestFileRead,,'c:\testing.txt')
message('ds_file2string failed : ' & ds_error())
!No need to dispose if it failed
else
DisplayString = TestFileRead.bin ! string read from file.
DisplayLength = TestFileRead.len ! Length of string read from
file.
dispose(TestFileRead.bin)
end |
ds_GetHModule
ds_GetHModule
(<string pModuleName>)
Description
Gets a handle to the specified module or if omitted to the current module.
This is used with the ds_GetHIcon function.
Parameters
| Parameter |
Description |
| pModuleName (string) |
Optional string containing the name of the required module. |
Returns
A ulong handle to the the specified module or if omitted to the current
module.
Example
| Example |
hModule ulong
code
hModule = ds_GetHModule() ! returns handle to current module.
hModule = ds_GetHModule('MyIcons.dll')
! returns handle to MyIcons.dll |
ds_GetHIcon
ds_GetHIcon(string
pIconName,<ulong pHIconModule>,<long
pIconSize>),ds_DestroyIcon()
Description
Gets a handle to the compiled-in icon. If the icon is not in the current
module then a handle to the module must be supplied. The icon size may be
specified ie 16X16 or 32X32 or 48X48. If the icon size is not specified
then the first icon in the resource is loaded.
Parameters
| Parameter |
Description |
| pIconName (string) |
The name of the icon file or icon resource. Compiled-in icon
names must be prefixed with '~'. |
| pHIconModule (ulong) |
Optional. A handle to the module containing the icon. |
| pIconSize (long) |
Optional. The size required. Usually 16X16, 32X32 or 48X48.
Defaults to 16X16 if it exists. |
Returns
A ulong handle to the the specified icon. Zero is returned if the function
fails.
Example
| Example |
hIcon ulong
code
hIcon = ds_GetHIcon('~MyIcon.ico') ! returns handle to
compiled-in icon called 'MyIcon.ico'.
hIcon =
ds_GetHIcon('~MyIcon.ico',ds_GetHModule('MyIcons.dll') ! returns
handle to 'MyIcon.ico' in the DLL MyIcons.dll
hIcon = ds_GetHIcon('MyIcon.ico',,48) !
returns handle to 48X48 icon inside the file 'MyIcon.ico'.
......
ds_DestroyIcon(hIcon) ! Free memory |
ds_CreateShortcutEx
ds_CreateShortcutEx
(string pTargetFile,<string pIconName>,long pIconIndex=0,string
pDescription,long pHotKey=0,string pStartIn,string pShortCut,<string
pShortCutPath>,<string pArguments>,<string pReserved>)
Description
Create a shortcut to a file. The shortcut can be placed on the desktop or
in the START menu. Usually followed with a call to
ds_RefreshDesktop.
Parameters
| Parameter |
Description |
| pTargetFile (string) |
The file, including the path, to which a shortcut must be made.
Example C:\WINDOWS\SYSTEM32\CALC.EXE |
| pIconName (<string>) |
The file, including the path, which contains the icon to be used
with this shortcut. If omitted then the first icon in the
pTargetFile is used. |
| pIconIndex (long) |
The index of the icon within the pIconName file to use. If
omitted then the first icon is used. |
| pDescription (string) |
The tip which will appear if the cursor is held over the
shortcut. |
| pHotKey (long) |
The hot key to run the shortcut. Omit or use ZERO if not
required.
Example CTRLALTC |
| pStartIn (string) |
The path to the directory in which the file must be run /
opened. |
| pShortCut (string) |
The name for the shortcut.
Example 'Calculator.LNK' |
| pShortCutPath (<string >) |
The destination where the shortcut must be placed. If omitted
then defaults to the desktop.
Example C:\Documents and Settings\Derek\Desktop |
| pArguments (<string>) |
if you would like to add arguments (i.e. command line
parameters) to the shortcut command line, then you can pass these
in this parameter. |
| pReserved (<string>) |
reserved for future functionality. |
Returns
Zero is returned if the function succeeds.
Example
| Example |
code
ds_CreateShortcutEx(clip(ds_GetFolderPath(WE::CSIDL_SYSTEM
,1)) &
'\CALC.EXE',,,'Calculator!',CTRLALTC,clip(ds_GetFolderPath(WE::CSIDL_SYSTEM
,1)),'Calculator.LNK')
ds_CreateShortcutEx('C:\WINDOWS\SYSTEM32\CALC.EXE',,,'Calculator!',CTRLALTC,'C:\WINDOWS\SYSTEM32','Calculator.LNK','C:\Documents and
Settings\Derek\Desktop','/debugfmall')
ds_RefreshDesktop() |
This function replaces the deprecated ds_CreateShortCut function (which
has no parameter for additional arguments).
ds_GetFileVersionInfo
ds_GetFileVersionInfo(<string
pDescription>,<*string
pFileName>)
Description
Used to return the file version data compiled into the EXE / DLL.
Parameters
| Parameter |
Description |
| pDescription (string) |
Default='FileVersion' The name version data required.
Standard descriptions are as follows:
| Comments |
InternalName |
ProductName |
| CompanyName |
LegalCopyright |
ProductVersion |
| FileDescription |
LegalTrademarks |
PrivateBuild |
| FileVersion |
OriginalFilename |
SpecialBuild |
|
| pFileName (*string) |
Default=Current Module. The name including path of the file
from which version data is required. |
Returns
String. Returns info if found. If fails then returns empty string, see
ds_Error() for more info.
Example
| Example |
code
DisplayInfo = ds_GetFileVersionInfo() ! returns FileVersion by
default. |
ds_GetCurrentEXEDate
ds_GetCurrentEXEDate()
Description
Used to return the current date of the EXE.
Parameters
None
Returns
Long. Returns the date of the EXE.
Example
| Example |
code
CurrentEXEDate = ds_GetCurrentEXEDate() ! returns the EXE date
by default. |
ds_LoadDLLProc
ds_LoadDLLProc(string
ProcName,string pLibName,*ulong pProcAddress,<*ulong
pLibInstance>)
Description
Used to load a DLL into memory if it is not already loaded and then to
return the call address of the specified DLL function.
Parameters
| Parameter |
Description |
| pProcName (string) |
The name of the DLL procedure. This procedures call address will
be returned. |
| pLibName (string) |
The name of the DLL to load. |
| pProcAddress (ulong) |
The call address of the DLL procedure is saved here. Subsequent
calls to ds_LoadDLLProc will simply return if this is already set.
|
| pLibInstance (ulong) |
Optional. This is used by ds_UnloadDLLProc to unload the DLL
if it is no longer required. |
Windows will unload the DLL when your application quits and so this is not
required.
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
"Inside global map" - Global embed point
module('windows')
WC_GetDiskFreeSpaceEx(ulong,*dlong,*dlong,*dlong), byte, raw,
pascal, Dll(_fp_) ! The Dll(_fp_) tells the compiler not to
link in this function.
end
"Global Data" - Global embed point
fp_GetDiskFreeSpaceEx
ulong,static,name('WC_GetDiskFreeSpaceEx')
code
if
~ds_LoadDLLProc('GetDiskFreeSpaceExA','kernel32',fp_GetDiskFreeSpaceEx)
result =
WC_GetDiskFreeSpaceEx(0,dlongUserFree,dlongTotal,dlongTotalFree)
...
else
! lib or function not found
message('ds_LoadDLLProc failed : ' & ds_Error())
end |
Note: To use an external clarion DLL you
need to do the following:
1. You must use the real procedure name from the Clarion DLL (this
normally ends with @F - but you will need to check this using a tool such
as libmaker.exe to find out the exact name of the function that is
exported).
2. You need to add the pascal attribute to your procedure prototype.
ds_UnloadDLLProc
ds_UnloadDLLProc(*ulong
pProcAddress,ulong pLibInstance)
Description
Used to unload a DLL.
Windows will unload the DLL when your application quits and so this is not
required.
Parameters
| Parameter |
Description |
| pProcAddress (ulong) |
The call address of the DLL procedure will be reset. This will
force a subsequent call to ds_LoadDLLProc to reload the DLL. |
| pLibInstance (ulong) |
This must be set by ds_LoadDLLProc. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
"Inside global map" - Global embed point
module('windows')
WC_GetDiskFreeSpaceEx(ulong,*dlong,*dlong,*dlong), byte, raw,
pascal, Dll(_fp_) ! The Dll(_fp_) tells the compiler not to
link in this function.
end
"Global Data" - Global embed point
fp_GetDiskFreeSpaceEx
ulong,static,name('WC_GetDiskFreeSpaceEx')
LibInstance ulong,static
code
if
~ds_LoadDLLProc('GetDiskFreeSpaceExA','kernel32',fp_GetDiskFreeSpaceEx,LibInstance)
result =
WC_GetDiskFreeSpaceEx(0,dlongUserFree,dlongTotal,dlongTotalFree)
...
else
! lib or function not found
message('ds_LoadDLLProc failed : ' & ds_Error())
end
.....
if ds_UnloadDLLProc(fp_GetDiskFreeSpaceEx,LibInstance) ! Unload
DLL as no longer required
message('ds_UnloadDLLProc failed : ' & ds_Error())
end |
ds_GetDLLVersion
ds_GetDLLVersion(string
pDLLName,*ds_DLLVersionG pDLLVerInf)
Description
Used to retrieve the version information from a windows DLL.
Parameters
| Parameter |
Description |
| pDLLName (string) |
The name of the DLL from which version info is required. |
| pDLLVerInf (*ds_DLLVersionG) |
This structure is filled with the version info. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
DLLVerInf group(ds_DLLVersionG) .
code
if ~ds_GetDLLVersion('shell32.dll',DLLVerInf)
! ds_DLLVersionG group
! MajorVersion ulong
! MinorVersion ulong
! BuildNumber ulong
! PlatformID ulong
! String string(30)
! end
if DLLVerInf.MajorVersion > 4
! Taskbar balloons supported under shell version 5 and
higher.
else
! Taskbar balloons not supported.
end
end |
ds_GSMSendSMS
ds_GSMSendSMS(long
pPID,string pSMSText,string pSMSPhoneNumber,<string
pPIN>,<*long pSMSID>)
Description
Used to send an SMS via a GSM modem.
Note : Uses
ds_Timer(999).
ds_GSMSendSMS calls the following 4 procedures:
ds_GSMEchoOFF(pPID)
ds_GSMEnterPin(pPID,pPIN)
ds_GSMSetSMSTextmode(pPID)
ds_GSMGetReply...
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pSMSText (string) |
The SMS text string to send. Example 'Please call me. I am low
on airtime :)' |
| pSMSPhoneNumber (string) |
The mobile number to send the SMS to. |
| pPIN (string) |
Optional. The PIN number to gain access to the SIM card in the
GSM modem.
The PIN code request on the SIM card may be disabled. In this
case the PIN is not required.
NB : If you try the wrong PIN code
3 times then your SIM may be locked and will need the PUK number
to unlock it. This is not handled by WinEvent. |
| pSMSID (*long) |
Optional. Most GSM modems return an SMS identifier that may be
used with the SMS delivery report to identify which SMS was
delivered. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
SMSID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMSendSMS(PID,'Hello There','08XXXXXXXXX','1234',SMSID)
message = ds_Error()
else
message = 'Send Succeeded, SMSID=' & SMSID1
end |
Note: If you want to use non-standard chars (like æøåÆØÅ) then you'll need
to use their ASCII value equivalents in the string.
ds_GSMEnterPin
ds_GSMEnterPin(long
pPID,string pPIN)
Description
Used to gain access to a SIM card in a GSM modem.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pPIN (string) |
The PIN number to gain access to the SIM card in the GSM modem. |
The PIN code request on the SIM card may be disabled. In this case
ds_GSMEnterPin will return 0 (Success).
NB : If you try the wrong PIN code 3 times
then your SIM may be locked and will need the PUK number to unlock it.
This is not handled by WinEvent.
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMEchoOFF(PID)
message('ds_GSMEchoOFF failed : ' & ds_Error())
elsif ds_GSMEnterPIN(PID,PIN)
message('ds_GSMEnterPIN failed : ' & ds_Error())
else
message('PIN OK')
end |
ds_GSMEchoOFF
ds_GSMEchoOFF(long
pPID)
Description
Used to turn off the echoing of commands sent to the GSM modem.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMEchoOFF(PID)
message('ds_GSMEchoOFF failed : ' & ds_Error())
else
message('ECHO OFF')
end |
ds_GSMSetSMSTextmode
ds_GSMSetSMSTextmode(long
pPID)
Description
Used to set the GSM modem into text mode for the SMS send function.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMEchoOFF(PID)
message('ds_GSMEchoOFF failed : ' & ds_Error())
elsif ds_GSMSetSMSTextmode(PID)
message('ds_GSMSetSMSTextmode failed : ' & ds_Error())
else
message('ds_GSMSetSMSTextmode OK')
end |
ds_GetGSMReply
ds_GetGSMReply(long
pPID,string pCMD,long pCmdLen=0,*string pReplyString,long
pTimeout=25,long pTimeout2=25,byte pTrailingOK=FALSE,byte
pFindPrompt=FALSE,byte pIgnorePrompt=FALSE)
Description
Used to send an command to the GSM modem and wait for a response.
Note : Uses
ds_Timer(999).
leading '<13>' (CR) and '<10>' (LF) characters in the modem
response are discarded.
If the modem response starts with the command sent then this is also
discarded. (modem echo)
ds_GSMGetReply starts with a call to ds_EmptyPort(pPID) before sending the
command string.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pCMD (string) |
The command to send to the modem.
Tip : Most modems require a CR / LF terminator on the
command ie. 'AT+CPIN?<13,10>' where ascii 13 is CR and ascii
10 is LF. |
| pCmdLen (long) |
Optional. This is the command string length to send. If
omitted then the string is clipped before sending. |
| pReplyString (*string) |
The modem response is returned in this string. |
| pTimeout (long) |
Optional. Default =50 (0.50 secs). This is the timeout for the
first character of the modem response. You might need to increase
this to quite large (depending on the service provider). Some
Providers require as much as 90 seconds (i.e. this timeout set to
9000). If you are getting intermittent or failed replies, then
this is one possibility that should be adjusted. |
| pTimeout2 (long) |
Optional. Default =25 (0.25 secs). This is the timeout for
subsequent characters of the modem response. |
| pTrailingOK (byte) |
Optional. Default=FALSE. This flag when set specifies that the
modem response terminates with an '<13,10>OK<13,10>'
.
If not set then the first '<13,10>' will be taken as the
end of the modem response. |
| pFindPrompt (byte) |
Optional. Default=FALSE. This flag when set specifies that the
modem response terminates with an '> ' . |
| pIgnorePrompt (byte) |
Optional. Default=FALSE. This flag when set then leading '> '
characters in the modem response are discarded. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
ReplyString string(1024)
code
PID = NewPort('com1:9600,n,8,1')
ds_GetGSMReply(PID,'AT+CPIN?<13,10>',,ReplyString,,,1) !
Query +CPIN state and waits for OK response.
ds_GetGSMReply(PID,'AT+CMGS="082XXXXXX"<13,10>',,ReplyString,1000,,,1)
! Dials Mobile Number and waits for "> " response. |
ds_EmptyPort
ds_EmptyPort(long
pPID,long pTimeout=50)
Description
Used to save any unsolicited modem responses into an internal queue and to
empty the com port input buffer.
Note : Uses
ds_Timer(999).
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pTimeout (long) |
Optional. Default =50 (0.5 secs). This is the timeout for
attempting to empty the com port input buffer. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_ds_EmptyPort(PID)
message('ds_EmptyPort failed : ' & ds_Error())
else
message('ds_EmptyPort OK')
end |
ds_GSMReadSMSInit
ds_GSMReadSMSInit(long
pPID,string pPIN)
Description
Used to prepare the GSM modem for reading the SMS list.
Note : ds_GSMReadSMSInit calls the
following.
ds_GSMEchoOFF(pPID)
ds_GSMEnterPin(pPID,pPIN)
ds_GSMSetSMSTextmode(pPID)
ds_GSMSelectSR(pPID,FALSE)
ds_GSMGetReply.......
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pPIN (string) |
Optional. The PIN number to gain access to the SIM card in the
GSM modem. |
The PIN code request on the SIM card may be disabled. In this case the PIN
is not required.
NB : If you try the wrong PIN code 3 times
then your SIM may be locked and will need the PUK number to unlock it.
This is not handled by WinEvent.
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMReadSMSInit(PID)
message('ds_GSMReadSMSInit failed : ' & ds_Error())
else
message('ds_GSMReadSMSInit OK')
end |
ds_GSMReadSMS(long pPID,long
pSMSIndex,*ds_SMSMessageG pSMSG)
ds_GSMReadSMS(long
pPID,long pSMSIndex,*ds_SMSMessageG pSMSG)
Description
Used to read the SMS memory from the GSM modem at the specified memory
index.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pSMSIndex (long) |
Which memory index to read. |
| pSMSG (*ds_SMSMessageG) |
This structure is filled with the data from the memory index. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
SMSIndex long
SMSG group(ds_SMSMessageG)
end
code
SMSIndex = 0
PID = NewPort('com1:9600,n,8,1')
if ds_GSMReadSMSInit(PID,PIN)
message('ds_GSMReadSMSInit failed : ' & ds_Error())
else
loop
SMSIndex += 1
if ds_GSMReadSMS(PID,SMSIndex,SMSG) then break .
end
end |
ds_GSMDeleteSMS
ds_GSMDeleteSMS(long
pPID,long pSMSIndex)
Description
Used to read the clear the SMS memory from the GSM modem at the specified
memory index.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pSMSIndex (long) |
Which memory index to clear. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMDeleteSMS(PID,3) ! delete index 3
message('ds_GSMDeleteSMS failed : ' & ds_Error())
else
message('ds_GSMDeleteSMS OK')
end |
ds_GSMSetSMSReporting
ds_GSMSetSMSReporting(long
pPID,byte
pEnableReport=1,long pTimeout=1440,<string pPIN>)
Description
Used to enable SMS delivery reporting.
If the mobile to which the SMS is sent is turned off or out of range then
the delivery report will be delayed until either the SMS is sent or the
timeout lapses.
Note : ds_GSMReadSMSInit calls the following.
ds_GSMEnterPin(PID,PIN)
ds_GSMSetSMSTextmode(PID)
ds_GSMGetReply....
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pEnableReport (byte) |
Optional. Default=1 (TRUE) If this flag is reset (0) then the
SMS delivery reporting is disabled. |
| pTimeout (long) |
Optional. Default =1440 minutes (24 Hours). This is the length
of time in minutes that the network must try to send the SMS for
before sending a failed report.
The range of the timeout is from 5 minutes to 63 weeks.
if pTimeOut > 43200 ! 30 days
the resolution is weeks [5 to 63 weeks]
elsif pTimeOut > 1440 ! 1 day
the resolution is days [2 to 30 days]
elsif pTimeOut > 720 ! 12 hours
the resolution is 30 minute blocks [12:30 to 24:00]
else ! <= 12 hours
the resolution is 5 minute blocks [0:05 to 12:00]
end |
| pPIN (string) |
Optional. The PIN number to gain access to the SIM card in the
GSM modem. |
The PIN code request on the SIM card may be disabled. In this case the PIN
is not required.
NB : If you try the wrong PIN code 3 times
then your SIM may be locked and will need the PUK number to unlock it.
This is not handled by WinEvent.
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMSetSMSReporting(PID)
message('ds_GSMSetSMSReporting failed : ' & ds_Error())
else
message('ds_GSMSetSMSReporting OK')
end |
ds_GSMSelectSR
ds_GSMSelectSR(long
pPID,byte pSRMemory=1)
Description
Used to select the SIM / device memory where the SMS delivery reports are
stored.
Most GSM modems use a common area for SMS delivery reports and received
SMS's. This command is necessary for those devices that use a separate
memory area.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pSRMemory (byte) |
Optional. Default=1 (TRUE) If this flag is set then the SMS
delivery report storage area is selected.
If this flag is reset then the received SMS storage area is
selected. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMSelectSR(PID)
message('ds_GSMSelectSR failed : ' & ds_Error())
else
message('ds_GSMSelectSR OK')
end |
ds_GSMReadSMSReportInit
ds_GSMReadSMSReportInit(long
pPID,string pPIN)
Description
Used to prepare the GSM modem for reading the SMS delivery report list.
Note : ds_GSMReadSMSReportInit calls the
following.
ds_GSMEchoOFF(pPID)
ds_GSMEnterPin(pPID,pPIN)
ds_GSMSetSMSTextmode(pPID)
ds_GSMSelectSR(pPID,TRUE)
ds_GSMGetReply.......
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pPIN (string) |
Optional. The PIN number to gain access to the SIM card in the
GSM modem.
The PIN code request on the SIM card may be disabled. In this case
the PIN is not required.
NB : If you try the wrong PIN code 3 times then your SIM may be
locked and will need the PUK number to unlock it. This is not
handled by WinEvent. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMReadSMSReportInit(PID)
message('ds_GSMReadSMSReportInit failed : ' &
ds_Error())
else
message('ds_GSMReadSMSReportInit OK')
end |
ds_GSMReadSMSReport
ds_GSMReadSMSReport(long
pPID,long
pSMSReportIndex,*ds_SMSReportG pDRG)
Description
Used to read the SMS delivery report memory from the GSM modem at the
specified memory index.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pSMSReportIndex (long) |
Which memory index to read. |
| pDRG (*ds_SMSReportG) |
This structure is filled with the data from the memory index. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
SMSReportIndex long
DRG group(ds_SMSReportG)
end
code
SMSReportIndex = 0
PID = NewPort('com1:9600,n,8,1')
if ds_GSMReadSMSReportInit(PID,PIN)
message('ds_GSMReadSMSReportInit failed : ' &
ds_Error())
else
loop
SMSReportIndex += 1
if ds_GSMReadSMSReport(PID,SMSReportIndex,DRG) then break
.
end
end |
ds_GSMDeleteSMSReport
ds_GSMDeleteSMSReport(long
pPID,long pSMSReportIndex)
Description
Used to read the clear the SMS delivery report memory from the GSM modem
at the specified memory index.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pSMSReportIndex (long) |
Which memory index to clear. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMDeleteSMSReport(PID,3) ! delete index 3
message('ds_GSMDeleteSMSReport failed : ' & ds_Error())
else
message('ds_GSMDeleteSMSReport OK')
end |
ds_GSMReadEvents
ds_GSMReadEvents(long
pPID,*ds_GSMEventG pERG)
Description
Used to check the GSM modem port for any unsolicited event reports.
Returns the oldest event from the internal event queue.
This event is simultainiously deleted from the internal queue. The
following call to ds_GSMReadEvents will return the next event if any.
Note : ds_GSMReadEvents calls
ds_EmptyPort(pPID).
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pERG (*ds_GSMEventG) |
This structure is filled with any event data found. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
ERG group(ds_GSMEventG)
end
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMReadEvents(PID,ERG)
message('GSMReadEvents failed : ' & ds_Error())
else
end |
ds_GSMSetEvents
ds_GSMSetEvents(long
pPID,long pEventsMask=255)
Description
Used to enable the sending of unsolicited event reports by the GSM modem.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
| pEventsMask (long) |
Optional. Default=255. This long selects which events are
enabled. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMSetEvents(PID)
message('ds_GSMSetEvents failed : ' & ds_Error())
else
message('ds_GSMSetEvents OK')
end |
ds_GSMReset
ds_GSMReset(long
pPID)
Description
Used to set the GSM modem back to factory settings.
This issues a AT&F command.
Parameters
| Parameter |
Description |
| pPID (long) |
This is the PortID of the open com port to which the GSM modem
is connected. See the NewPort function. |
Returns
Long. Returns 0 for Success else
ds_ErrorCode.
See
ds_ErrorCode for more info.
Example
| Example |
PID long
code
PID = NewPort('com1:9600,n,8,1')
if ds_GSMReset(PID)
message('ds_GSMReset failed : ' & ds_Error())
else
message('ds_GSMReset OK')
end |
ds_OutputDebugString
ds_OutputDebugString(string
pDebugString,byte pAddCRLF=1)
Description
Used to send (output) debug information to any windows debug viewer (like
SysInternals' DebugViewer).
Parameters
| Parameter |
Description |
| pDebugString (string) |
Debug info string. |
| pAddCRLF (byte) |
Add carriage return and line feed to the debugstring if set. |
Returns
None
Example
| Example |
code
ds_OutputDebugString('Test to debug - view in something like
DebugViewer from SysInternals) |
ds_Debug
ds_Debug(string
pDebugString,<string pWindowLabel>,<long
pEventNumber>,<long pFieldNumber>)
Description
Used to send (output) debug information to both the built-in debug viewer
and any windows debug viewer (rather use
ds_OutputDebugString
if only sending to the windows debugviewer).
Note : Output suppressed unless command
line switch "/debug" or ds_ViewDebug open.
Parameters
| Parameter |
Description |
| pDebugString (string) |
Debug info string. |
| pWindowLabel (string) |
Optional. This label identifies which procedure is sending the
debug info. The thread number is added to the end of this string. |
| pEventNumber (long) |
Optional. Used by the template in order to display the window
events. |
| pFieldNumber (long) |
Optional. Used by the template to display which control received
the event. |
Returns
None
Example
| Example |
code
ds_ViewDebug ! opens the debug viewer.
ds_Debug('Just testing') |
ds_WineventDebug
ds_WineventDebug(byte
pEnable)
Description
Used to send (output) debug information to both the builtin debug viewer
and any windows debug viewer.
Note : Output suppressed unless command
line switch "/debug" or ds_ViewDebug open.
Parameters
| Parameter |
Description |
| pEnable (byte) |
If TRUE (1) then WinEvent internal debugging info is sent to the
debug viewer. If FALSE (0) then WinEvent internal debugging info
is suppressed. |
Returns
None
Example
| Example |
fp_Testing ulong
code
ds_WineventDebug(1)
ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)
Debug string ! ds_LoadDLLProc error, LoadLibrary failed
DLL=NoneExistant.dll The specified module could not be found. |
ds_ViewDebug
Description
Opens the WinEvent built-in debug viewer.
Parameters
None
Returns
None
Example
| Example |
fp_Testing ulong
code
ds_ViewDebug ! open debug viewer.
ds_WineventDebug(1)
ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)
Debug string |
ds_ViewDebugClose
Description
Closes the WinEvent built-in debug viewer.
Parameters
None
Returns
None
Example
| Example |
fp_Testing ulong
code
ds_DebugView ! open debug viewer.
ds_WineventDebug(1)
ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)
Debug string
ds_DebugViewClose ! close the debug viewer. |
ds_Error
ds_Error(<long
pThisErrorCode>)
Description
Returns the error message for a
ds_ErrorCode().
Parameters
| Parameter |
Description |
| pThisErrorCode (long) |
Optional. If omitted then the current ds_ErrorCode()
is used. This is the error code for which the text error message
is required. |
Returns
String. Error message.
Example
| Example |
fp_Testing ulong
code
if ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)
message('Error ' & ds_error())
end |
ds_ErrorCode
ds_ErrorCode()
Description
Returns the current WinEvent error code.
Parameters
None
Returns
Long. Error code.
Example
| Example |
fp_Testing ulong
SaveErrorCode long
code
if ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)
SaveErrorCode = ds_ErrorCode()
message('Error ' & ds_error())
end |
ds_ErrorReset(<string
pCallingProcedure>)
ds_ErrorReset(<string
pCallingProcedure>)
Description
Clears
ds_ErrorCode and sets the calling
Procedure name.
Parameters
| Parameter |
Description |
| pCallingProcedure (string) |
Optional. This procedure name will be returned with any
ds_Error() message string. Useful for identifying the parent
procedure where a procedure is called from various procedures. |
Returns
None
Example
| Example |
fp_Testing ulong
SaveErrorCode long
code
if ds_LoadDLLProc('Testing','NoneExistant.dll',fp_Testing)
SaveErrorCode = ds_ErrorCode()
message('Error ' & ds_error())
end |
ds_SaveStack& ds_TestStack
Description
Use ds_SaveStack with ds_TestStack to check for stack corruption while
calling external procedures.
If the ESP or EBP registers are corrupted then it sends an error to
DebugView, displays a messagebox and a GPF is forced.
If other registers are changed then sends a message to DebugView. This is
not necessarily an error - registers can be changed by a procedure call,
but it may be useful to inspect this when debugging.
NOTE : ds_SaveStack must be matched with a ds_TestStack otherwise
a mismatch error will be reported.
Parameters
None
Returns
None
Example
| Example |
code
ds_SaveStack()
ds_TestStack() |
ds_FormatHex
ds_FormatHex(ulong
pDisplayValue,byte pPadSpaces)
Description
Returns a hexadecimal representation of the value.
Parameters
| Parameter |
Description |
| pDisplayValue (ulong) |
The number to format as hex. |
| pPadSpaces (byte) |
The length of the hex number to return (leading zeros). |
Returns
String. The hex string for the value.
Example
| Example |
DisplayHex string(10)
code
DisplayHex = ds_FormatHex(31,4) ! 001F |
ds_SetClipboard
ds_SetClipboard(ulong
pClipFormat,string pNewContents)
Description
Places various format data into the windows clipboard.
Parameters
| Parameter |
Description |
| pClipFormat (ulong) |
The format specifier. |
| pNewContents (string) |
The data to be placed in the clipboard. |
| pClipFormat 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-Independent 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.
| Example |
data
hDropStruct group
pFiles long
pt ulong
blank ulong
fNC long
fWide long
FileList string(255)
end
code
hDropStruct.filelist = 'C:\autoexec.bat<0,0>'
hDropStruct.pFiles = 20
hDropStruct.fWide = 0
if ~ds_SetClipboard(WE::CF_hDrop,hDropStruct)
message('SetClipboardFailed')
end
|
ds_ShutDown(<byte pForce>)
ds_ShutDown(<byte
pForce>)
Description
Requests a windows shutdown.
Parameters
| Parameter |
Description |
| pForce (byte) |
Optional. When set (1) then any processes that do not "respond"
are terminated by windows. |
Returns
Byte. Returns 1 for success, 0 for failure
Example
| Example |
code
ds_Shutdown() ! Request a windows shutdown. |
ds_WinEventVersion
ds_WinEventVersion()
Description
Returns the current WinEvent version number.
This is handy for checking that the WinEvent DLL is the correct version
for the application.
Parameters
None
Returns
Real. Returns the WinEvent version number.
Example
| Example |
code
if ds_WinEventVersion < 3.21
message('Error old WinEvent DLL in use')
end |
ds_Ulong64ToReal
ds_Ulong64ToReal(long
pULongHigh,long
pULongLow),real
Description
Converts a long64 into a real. Use this function when working with API
calls that return 64 bit longs.
Note that ulongs bigger than 52 bits will become approximate values when
converted to reals. Ulongs up to 52 bits will be exact values.
Parameters
| Parameter |
Description |
| pUlongHigh (long) |
The first 4 bytes of the ulong64. |
| pUlongLow (long) |
The last 4 bytes of the ulong64. |
Returns
Real. The ulong64 value.
Example
| Example |
RealVar real
ulong64G group
High long
Low long
end
code
RealVar = ds_Ulong64toReal(ulong64G:High,ulong64G:Low)
|
ds_Round
ds_Round(real
pValue,string pOrder),real
Description
Returns the rounded (to Order) of the Value. This function allows rounding
to Orders other than straight 1 decimal and force up or force down (using
plus or minus) as well as true rounding.
Parameters
| Parameter |
Description |
| pValue (real) |
The value to be rounded. |
| pOrder (string) |
The order to round the value. The order value must be prepended
with '+','-' or nothing.
'+' (and then the order) - returns the higher order closest to the
value.
'-' (and then the order) - returns the lower order closest to the
value.
Nothing (and then the order) - rounds the value up or down
depending on the closest order. |
Returns
Real. The rounded value.
Example
| Example |
code
RealVar = ds_Round(89.494,'-0.02') !Returns 89.48
RealVar = ds_Round(89.494,'0.02') !Returns 89.50
RealVar = ds_Round(89.484,'+0.02') !Returns 89.50 |
ds_SetOKToEndSessionHandler
ds_SetOKToEndSessionHandler(ulong
pCallBackAddress)
Description
Installs an OKToEndSessionHandler for the Auto-shutdown functionality.
Parameters
| Parameter |
Description |
| pCallBackAddress (ulong) |
The address of the OKToEndSessionHandler. |
The OKToEndSessionHandler must be prototyped as :
MyOKToEndSessionHandler(long pLogoff),long,pascal
Returns
Ulong. Returns the old OKToEndSessionHandler.
Example
| Example |
OldHandlerAddress ulong
code
OldHandlerAddress =
ds_SetOKToEndSessionHandler(address(MyOKToEndSessionHandler)) |
ds_SetEndSessionHandler
ds_SetEndSessionHandler(ulong
pCallBackAddress)
Description
Installs an EndSessionHandler for the Auto-shutdown functionality.
Parameters
| Parameter |
Description |
| pCallBackAddress (ulong) |
The address of the EndSessionHandler.
The EndSessionHandler must be prototyped as :
EndSessionHandler(long pLogoff),long,pascal |
Returns
Ulong. Returns the old EndSessionHandler.
Example
| Example |
OldHandlerAddress ulong
code
OldHandlerAddress =
ds_SetEndSessionHandler(address(MyEndSessionHandler)) |
ds_SetNoEndSession
ds_SetNoEndSession(long
pNoEndSession)
Description
Disables the Auto-Shutdown functionality.
Parameters
| Parameter |
Description |
| pNoEndSession (long) |
When set (1) then the Auto-Shutdown is disabled. |
Returns
None
Example
| Example |
code
ds_SetNoEndSession(TRUE)
! Do backup routine here
ds_SetNoEndSession(FALSE) |
ds_GetCurrentProcess
ds_GetCurrentProcess()
Description
Return a windows handle to the current process often required for API
calls.
Parameters
None
Returns
long. hProcess, handle this process.
Example
| Example |
long hProcess
code
hProcess = ds_GetCurrentProcess() |
ds_GetCurrentThread
ds_GetCurrentThread()
Description
Return a windows handle to the current thread often required for API
calls.
Parameters
None
Returns
long. hThread, handle to this thread.
Example
| Example |
long hThread
code
hThread = ds_GetCurrentThread() |
ds_GetProcessTime
ds_GetProcessTime(long
hProcess=0,long IncludeFlags=0),real
Description
Returns the CPU usage of this process in clarion time.
Parameters
| Parameter |
Description |
| hProcess (long) |
Optional. The windows handle to the process. Defaults to the
current process. |
| IncludeFlags (long) |
Optional. 1 = User Time, 2 = Kernal Time, 0 = Total Time
(Default) |
Returns
real. Time in 1/100 seconds.
Example
| Example |
real UserTime
code
UserTime = ds_GetProcessTime(,1)
DisplayTime = ds_FormatFastTime(UserTime,6) |
ds_GetThreadTime
ds_GetThreadTime(long
hThread=0,long IncludeFlags=0),real
Description
Returns the CPU usage of this thread in clarion time.
Parameters
| Parameter |
Description |
| hThread (long) |
Optional. The windows handle to the thread. Defaults to the
current thread. |
| IncludeFlags (long) |
Optional. 1 = User Time, 2 = Kernal Time, 0 = Total Time
(Default) |
Returns
real. Time in 1/100 seconds.
Example
| Example |
real UserTime
code
UserTime = ds_GetThreadTime(,1)
DisplayTime = ds_FormatFastTime(UserTime,6) |
ds_SetRealTimePriority
ds_SetRealTimePriority(long
hProcess=0,long hThread=0,byte RealTimeFlag=1)
Description
Selects Real Time or Normal priority for a thread.
Parameters
| Parameter |
Description |
| hProcess (long) |
Optional. The windows handle to the process. Defaults to the
current process. |
| hThread (long) |
Optional. The windows handle to the thread. Defaults to the
current thread. |
| RealTimeFlag (byte) |
Optional. When set (Default) then Real Time Priority is
selected. When clear then Normal Priority is selected. |
Returns
None
Example
| Example |
code
ds_SetRealTimePriority(,,TRUE) ......
ds_SetRealTimePriority(,,FALSE) |
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:
- Use the TaskBar extension
- 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):
- 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.
- 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
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
You are compiling in LIB mode and you have another LIB file that
includes the WinEvent LIB file (like the ezHelp LIB). You must check the
'Don't link in the WinEvent lib' checkbox on the settings tab of the
WinEvent global template.
Unresolved External $WE::CANTCLOSENOW in
globa002.obj
Unresolved External $WE::MUSTCLOSE in globa002.obj
Unresolved External $WE::CANTCLOSENOW in globa006.obj
Unresolved External $WE::MUSTCLOSE in globa006.obj
Unresolved External $WE::CANTCLOSENOW in globa024.obj
Unresolved External $WE::MUSTCLOSE in globa024.obj
Unresolved External $WE::CANTCLOSENOW in globa031.obj
Unresolved External $WE::MUSTCLOSE in globa031.obj
You must add WinEvent to your
data dll, and in the
Multi-DLL tab of the global template,
check both
the "This is part of a Multi-DLL program" and the "Export WinEvent data
from this DLL" checkboxes. In
all your other DLLs, you
should
check the "This is part of a Multi-DLL program"
checkbox, leaving the "Export WinEvent data from this DLL" checkbox
unchecked.
Version History
Download latest version
here
Version 4.02 (24 May 2021)
- Add: Clarion11.1 to install.
Version 4.01 (13 September 2018)
- Add: Clarion11 to install.
Version 4.00 (14 September 2016)
Version 3.99 (29 February 2016)
- Installer signed with SHA2 certificate
Version 3.98 (29 February 2016)
- Change: TestStack now outputs a ESP or EBP error to Debugview
before displaying the MESSAGE and GPF'ing.
Version 3.97 (17 August 2015)
- Internal: Slight adjustment to ds_SetFileDateTime. May fix
possible Memory Freed Twice error.
Version 3.97 (17 August 2015)
Version 3.96 (28 March 2015)
- References to %EnableWheelMouse removed from the template
Version 3.95 (24 March 2015)
- If a window is not set as resizable, then ds_VisibleOnDesktop
won't resize it.
Version 3.94 (25 February 2015)
- Clarion 10 Install.
- Removed unnecessary calls to %cwversion
Version 3.93 (18 February 2015)
- Template allows local setting to EnableMouseWheel.
Version 3.92 (10 February 2015)
- Refactor: (Internal) Code for making the window visible on
desktop, and visible inside a frame separated into separate
functions.
- Add: ds_SetApplicationWindow and ds_GetApplicationWindow methods.
Used to store pointer to AppFrame window.
- Fix: ds_VisibleOnDesktop method improved.
Version 3.91 (4 February 2015)
- Fixed regression in 3.90 for missing template variable declaration
Version 3.90 (8 January 2015)
- Added function WinAlertMouseZoom.
- Support for iDash Widget procedures added
Version 3.89 (25 November 2014)
- ds_VisibleOnDesktop could allow windows to float underneath the
MDI bar.
Version 3.88 (20 September 2014)
- Some embeds were not respecting the "disable winevent here"
setting.
Version 3.87 (22 August 2014)
Version 3.86 (20 January 2014)
- Clarion 9.1 build
- Possible Fix: Some static variables in ds_FastClock were not
marked as Threaded.
Version 3.85 (28 October 2013)
- Suppressed Undeclared Symbol %locCloseDownWhenWindowClosesSet
Error. (Thanks to Russ Eggen for submitting a fix.)
Version 3.84 (27 August 2013)
- Recompiled for Clarion 9, Build 10324. To use this build of
WinEvent, in Clarion 9, you must be on build 10324 or later.
Version 3.83 (24 April 2013)
- Tidied up PROJECTion of DLL's in template for Clarion 8.
- C8 fix - remove %pClassMethod where clause, and use embed point
directly.
- Template change - template generated text for the Hide, Show, Ext
options from the system tray only set if there is text entered in
the template, otherwise hide.
- Extended COM Port range. Current maximum port number is now
COM255:, was COM99: (Actually it's been 255 for a while, but it's
not clear when this was extended.)
Version 3.82 (31 January 2013)
- ds_GetWinVersionEx expanded to support Windows 8.
Version 3.81 (14 January 2013)
- ds_OnNetwork function did not BAND on the LSB as it should (to
return just 0 or 1).
Version 3.80 (9 October 2012)
- Template could generate code into Program Setup, column 1, in
legacy apps.
Version 3.79 (7 May 2012)
- Extended MAXPORTS to 255. Allows from Com1 to Com255 to be
available.
Version 3.78 (13 March 2012)
- Clarion 8 support for linking in C8 lib.
Version 3.77 (5 October 2011)
- Clarion 8 support for lib mode compiles (where ezHelp is added to
the application): Don't link in the Winevent Lib checkbox.
- Fix for ds_GetUserAccountName: Only calls the API function if
secur32 dll can be loaded. Uses NameServicePrincipal and cleans out
the '\'
Version 3.76 (20 July 2011)
- Fixed: ds_GetWinVersion was returning 'Media Center' for Vista and
up.
- ds_GetWinVersionEx - takes a long - if set returns description,
else returns the version number in Major.Minor.BuildNumber format.
- Remove unconditional debug output.
- ds_GetUserAccountName returns the GetUserNameExA. Use
NameServicePrincipal or NameCanonicalEx.
Version 3.75 (15 April 2011)
- Fixed: The Show Windows On Desktop code is now no longer generated
for a procedure when the local "Disable WinEvent in This Procedure"
option is enabled for that procedure.
- Fix: Project correct WinEvent lib for C7.3
- Fix - force make visible after window opens (checkbox on the
Global Extension template). WorkAround in C7.3 resizer.
- Remove debug code.
- ds_ParseTip was chopping string at 128 chars.
Version 3.73 (19 July 2010)
- Windows 2008 R2 reported correctly.
Version 3.72 (25 May 2010)
- ResetPort (when called by NewPort) sets the baud rate, etc for a
port above Port10 correctly.
Version 3.71 (13 May 2010)
- Project DOS lib into MultiProj generated local projects.
Version 3.70 (25 February 2010)
- Fix typo project in the template for DOS driver in C6 and earlier
builds.
Version 3.69 (24 February 2010)
Clarion 7.1 issue: Was not shutting down in a non-MDI with Global
Shutdown.
- Added debug to DOS file (instead of std_debug output if required).
- ds_CopyDirectory returns negative if an error occurs (the negative
contains the number of files that were successfully copied prior to
the error).
Version 3.68 (22 January 2010)
- Net_wsock32.lib was removed from WinEvent requirements (DLL
projects as well as template). New function APIs mapped internally:
GetHostname and WSAGetLastError.
Version 3.67 (21 January 2010)
- Net_wsock32.lib was not removed from the C55 winevent lib (in
3.66)
Version 3.66 (20 January 2010)
- Include the net_wsock32.lib in the install, and project it into
LIB projects (removed from the compiled WinEvent libs). Fix for
duplicate compile errors (where other libs use the net_wsock23.lib).
- Template change - don't project the winevent lib when Winevent is
disabled.
Version 3.65 (29 December 2009)
- Template tweak to project cwsynchc.clw (for Clarion7.1 support in
legacy local mode apps)
Version 3.64 (27 October 2009)
- ds_String2File - If StringLen is 0 then checked a clipped length
of the string to write.
- ds_GetIDETemperature - format parameter can be used to specify Deg
F or Deg C.
- ds_GetWinVersion - Fix for 64 bit OSes - returns Win 7, Win 2008
and WinVista correctly.
Version 3.63 (12 August 2009)
Version 3.62 (28 July 2009)
- Added function ds_RefreshDesktop,
which you can call to refresh the desktop, typically after a call to
ds_CreateShortcutEx.
(Thanks to Skip Williams for providing the code.)
- Added functions dsGetLocalTime, ds_GetLocalDate, ds_GetSystemTime,
ds_GetSystemDate
Version 3.61 (15 July 2009)
Version 3.60 (19 June 2009)
- Extended COM Port range. Current maximum port number is now
COM99:, was COM25:
Version 3.59 (18 March 2009)
- Fixed problem in ds_memory. Although the function was extended to
> 2 gigs in ver 3.53, there was a maths error which affected some
memory configurations.
Version 3.58 (13 March 2009)
- Template change - more embeds in the Add Icon to System tray
template - allowing additional handcode.
- Template change - embed point for a balloon clicked event.
- Template change - projects the C70 winevent lib files correctly.
- Dll fix - ds_ShowWindow calls the iconize last - some versions of
Clarion require prop:iconze to be called after the SetWindowPos
calls.
- Dll change - correctly display Windows 7 in the ds_GetWinversion
function.
Version 3.57 (10 November 2008)
- Clarion 7 compatible install.
Version 3.56 (30 October 2008)
- Auto-shutdown supports WinNotOnTaskbar - so removed erroneous
template turnoff (from Add Icon On taskbar template).
Version 3.55 (23 October 2008)
- Support for Clarion7 - links in the correct library.
- Fix - ds_OutputDebug uses created (and disposed) string for long
strings - was clipping strings > 1024
Version 3.54 (3 July 2008)
- Fix regression in WinEvent Template - was setting AutoShutdown off
when enabled (instead of off when disabled).
- Template change - allows specification of the module where an icon
is located (otherwise uses the EXE if not specified).
Version 3.53 (24 June 2008)
- Updated ds_memory function
to allow for numbers > 2 Gigs. (Remember though, that memory
functions return the number of Kb, not bytes).
Version 3.52 (15 November 2007)
- Fix - auto-generation of the VersionNumber box in the template was
missing a "section" - so was overwriting controls on the tab.
- Disable VersionNumber generation, changed to Enable Variable
Generation. This needs to be checked in order to be forced on.
Version 3.51 (9 November 2007)
- Fix - when not requiring auto-generation of the VersionNumber,
then you can omit this functionality in the WinEvent Global
Extension template.
Version 3.50 (6 November 2007)
- Fix in NewPort function - regression in 3.49. Was not newporting
an LPT port.
Version 3.49 (22 June 2007)
- Fix - supports com10 and up.
Version 3.48 (26 April 2007)
- ds_GetWinVersion() updated so that it returns "WinVista..." for
Vista.
- ds_ShutDown() updated so that it also calls PowerOff in Vista and
2003.
Version 3.47 (25 April 2007)
- ds_CreateShortcutEx -
allows command line parameters to be used in the shortcut. Replaces
the deprecated ds_CreateShortcut function.
Version 3.46 (23 November 2006)
- ds_Memory returns ULONG (instead of LONG) - this means that the
resultant value can be > 2.1 G reported (i.e. up to 4.2G - which
is what is returned by the windows API call).
Version 3.45 (13 October 2006)
- Clarified Template settings (in the local templates).
- Fix - ds_ShowWindow - was not showing a iconized, minimized window
correctly (required 2 calls).
Version 3.44 (20 July 2006)
Fix GPF for local mode compiles where a variable sync or we_sync was
defined in the application (the wrong address was being linked at
runtime).
Version 3.43 (12 July 2006)
Support for disabling ezHelp in the same application.
Version 3.42 (6 June 2006)
Change Global Extension template description.
Version 3.41(22 May 2006)
Template option to support ds_VisibleOnDesktop by default. You can
turn this off globally, or disable locally (for specific windows that
shouldn't have that feature).
Version 3.40 (10 May 2006)
Posts CloseDown event (for SelfService support) when exit from
tasktray is selected.
Version 3.39 (12 April 2006)
- Auto-Shutdown on check box is defaulted to on.
- Removed the font settings from the template (in order to correct
display in laptops with ClearType fonts settings turned off).
Version 3.38 (27 March 2006)
Version 3.37 (20 March 2006)
Changed the WinEvent equates to prefix with WE::. This means that
compile duplicates are prevented (when equates of the same name are
handcoded or used by other products). Check the Compile
Errors section for more details.
Version 3.36 (16 March 2006)
Improved Taskbar Icon Template - so that it's easier to see what you
need to do when making Services with Taskbar Icons.
Version 3.35 (20 February 2006)
No change - re-sync version numbers in DLL and template.
Version 3.34 (20 January 2006)
- Template Fix: Regression in 3.33 - RetryCreateIcon definition was
not always being generated.
- Fix: Regression in 3.33 - Message removed from COM initialisation.
Version 3.33 (11 January 2006)
- Template Fix: Taskbar icon now works with Services
- WinAccept (DLL) - optimised procedure
Version 3.32 (21 October 2005)
- Fixed bug in ds_Memory where 0 returned under clarion 6.x.
- Fixed bug in comms status pin functions CTSHigh, DSRHigh, RingHigh
and CDHigh. Broken in 3.31.
Version 3.31 (27 September 2005)
- Added ds_DestroyIcon(),
use with ds_GethIcon() to free memory.
- Added option "Left-Click Icon shows Window" to the TaskBarIcon
template.
- Added a separator to the TaskbarIcon popup menu.
- Fixed bug in ds_FormatFastTime
where times past midnight displayed incorrectly.
- Added a ReSyncTime optional parameter to ds_FastClock()
for use when the time has been adjusted.
Version 3.30 (1 September 2005)
Version 3.29 (21 July 2005)
- Fixed bug in ds_FormatFastTime where very small times, nano
seconds displayed as milliseconds.
- Added a template to open a com port. See Use com port template.
- Added support for com port events. See new com port template.
See modified newport command.
- Fixed a bug in the GSM Modem routines that caused a GPF under
clarion 6.X
- Modified template call to ds_DebugView, removed start(). This was
causing a GPF under 6.2
- Added ds_SetRealTimePriority().
- Added ds_QueryPerformance().
- Added ds_Ulong64ToReal().
- Modified "Add Icon to system tray" template to include optional
Show|Hide|Close popup. (Thank you Geoff)
- Added ds_HideWindow
procedure
- Added ds_ShowWindow
procedure
- Updated WinEvent() documentation.WinEvent
- Documented the WinSysEvent
and WinWtsEvent functions.
Version 3.28 (19 January 2005)
- Modified template so that importing a procedure with a WinEvent
template does not cause template errors.
- Modified template so that the Load Icon and Refresh Icon embed
points are correct. Refresh Icon was missing.
Version 3.27 (10 December 2004)
Version 3.26 (3 December 2004)
- Fixed bug in template where "Disable WinEvent in the application"
did not always work, some code was still generated
.
- Fixed bug in ds_SetClipboard().
Version 3.25 (25 November 2004)
- Fixed bug in
ds_GetFileVersionInfo where extra characters were returned
with the version string.
- Fixed bug in EzHelp version checking routine.
- Added priority attributes to template embed code. This is to
assist with souce comparison at Jim's request.
- Renamed WinEvent internal modules, prefixed with "ds_we". This is
to remove module naming conflicts.
- Added ds_SaveStack and ds_TestStack procedures.
These may help in locating stack corruptions.
Version 3.24 (3 November 2004)
Version 3.23 (2 November 2004)
- Added
ds_GetFileVersionInfo.
- Fixed bug in template where exporting multi-dll info caused a
compiler error.
Version 3.22 (23 October 2004)
- Major re-write of documentation.
- Added TaskbarShowBalloon and TaskbarHideBalloon code templates.
- Upgraded to new CapeSoft look.
- Added template help buttons.
- Modified WinEvent template to use EVENTMAP.CLW instead of adding
each procedure prototype to the global map.
- Added error reporting to most WinEvent functions. See ds_Error
- Modified ds_CreateDirectory
to work with relative paths ie ..\MyNewDirectory
Version 3.21 (8 September 2004)
- Fixed memory leak in ScreenWidth(), ScreenHeight()
&ScreenDepth()
- Added ds_GetScreenDPI() which returns the user screen DPI
settings. 96=Small Fonts, 120=Large Fonts or custom font setting.
- Added ds_CreateShortcut() which will create a shortcut to a file.
Version 3.20 (18 August 2004)
- Add Icon to the intray" template so that WinTaskBarAddIcon is now
called from a posted event. This is because sometimes the Icon does
not add.
- Added some compile warnings when WinNotOnTaskBar is used with
auto-shutdown as this is not compatible.
Version 3.19 (22 July 2004)
- Rebased DLL for faster loading.
- Added save to file / clipboard functionality to the builtin debug
viewer.
- Added embed points for TaskBar balloon events.
- Added the field equate labels to the builtin debug viewer.
- Updated CSIDL equates.
- Added ds_GetHModule() which returns a handle to the current module
or a specified DLL. Use with ds_GetHIcon().
- Added ds_GetHIcon() which returns a handle to icons that are
compiled into the EXE or DLL.
- Added ds_GetWindowsColour() which returns the current users
windows colour setting in clarion colour format.
Version 3.18 (3 June 2004)
Fixed bug in WinTaskbarAddIcon where line breaks were removed from tip
strings. Should only remove for WIN9x.
Version 3.17 (31 May 2004)
- Fixed bug in ds_MoveFile.
- Modified WinTaskbarAddIcon and WinTaskbarChangeIcon to ignore
calls with IconName blank.
Version 3.16 (16 April 2004)
Fixed bug where calling Sound(soundfilename) would fail under Win2k.
Version 3.15 (7 April 2004)
Fixed bug where calling Sound() with an empty wavefile name string
caused a GPF.
Version 3.14 (23 March 2004)
Modified WinSysEvent() and WinWTSEvent() functions to optionally clear
the value after reading. New prototype!
Version 3.13 (18 March 2004)
Fixed bug in template where the Sound function was incorrectly
prototyped. Sound would cause app to close without GPF, just gone
Version 3.12 (3 March 2004)
Fixed bug in GSM Modem SMS delivery Reporting where some Siemens
modems were not properly supported.
Version 3.11 (16 February 2004)
- Fixed bug in template where WinEvent events were not handled
.
- WinEvent examples upgraded. (Thank you Jono)
Version 3.10 (5 February 2004)
Fixed conflict with Secwin.
Version 3.09 (3 February 2004)
Fixed bug in ds_WinTaskbarBalloon where Win2000 balloons did not work.
Version 3.08 (2 February 2004)
Fixed bug in ds_WinTaskbarBalloon where Win2000 and Win NT4 Balloons
were positioned off the visible desktop.
Version 3.07 (28 January 2004)
- Added TaskbarIcon "Balloon" support. See ds_WinTaskbarBalloon
- Modified WinTaskbarAddIcon to accept "compiled in" icons. Example
WinTaskbarAddIcon('~MyAppIcon.ico'...
- Modified Auto-Shutdown. Added Callback functions
MyOKToEndSessionHandler & MyEndSessionHandler
Added WinEvent functions ds_SetOKToEndSessionHandler &
ds_SetEndSessionHandler.
See Auto-Shutdown for details.
Version 3.06 (12 January 2004)
- Fixed bug where WinEvent could not be linked into a non data DLL.
WinEvent now has a DLL !!!!!
- Modified GSM Modem SMS delivery reporting.
- Added GSM Modem Event monitoring. See example.
Version 3.05 (5 January 2004)
- Fixed bug where WinEvent could not be linked into a data DLL.
- Fixed bug in ds_VisibleOnDesktop where window would remain
obscured on the right side.
Version 3.04 (11 December 2003)
- Modified the NewPort function to cater for using LPTx as a
parameter.
- Fixed bug in (don't laugh) ds_debug.
- Added new function ds_VisibleOnDesktop.
Version 3.03 (22 September 2003)
Added GSM Modem SMS delivery reporting support.
Version 3.01 (21 August 2003)
- Modified the ds_GSMGetReply function. Added an extra optional
parameter.
- Added GSM Modem SMS read support. See ds_GSMReadSMS
- Added an date format string to the "Append compile date to title
bar" option on WinEvent extension general tab.
Version 3.00 (30 July 2003)
Added a batch of new functions.
Version 2.99 (9 July 2003)
- Fixed bug introduced in 2.98 where ReadPort caused a GPF.
- Added alternate Auto-Shutdown method. This allows you to execute
closing down code but will exit even if user cancels the shutdown.
See option under the Auto-Shutdown option on WinEvent extensions.
Version 2.98 (3 July 2003)
Fixed bugs in WindowsRelease function.
Version 2.97 (26 June 2003)
- Fixed bugs in ScreenWidth, ScreenHeight and ScreenDepth functions.
- Added a new function. ds_WinTransparent() . This function is
completely useless but looks really cool. WinXP and Win2000 only.
(Not Win98).
ds_WinTransparent(255) = Normal window
ds_WinTransparent(0) = Transparent window
ds_WinTransparent(128) = recommended.
Version 2.96 (24 June 2003)
Added new example code to the WinOnTop
function. This is the ideal code for hiding and showing a window from
the Task Bar.
Version 2.94 (2 June 2003)
- Fixed bug in Modified NewPort (2.93) where an error on opening a
port (port in use) caused a stop .
- Fixed bug in SetRTS and SetDTR functions. Was causing linker
error.
- Problems with Wheel Mouse Support. Some mouse drivers are not
compatible with WinEvent Wheel Mouse support and cause random GPF's.
Version 2.93 (1 May 2003)
Modified NewPort to support buffer size setting.
Version 2.92 (8 April 2003)
- Modified WinTaskBarAddIcon so that the Icon is redrawn whenever a
new taskbar is started. Note the new "Refresh icon event" embed
point.
- Added function GetSystemDir. This returns c:\windows\system
- Removed GetSystemWindowsDir as this only works under terminal
server.
Version 2.91 (24 March 2003)
Fixed bug where WinEvent events were suppressed while running EzHelp.
