(Download Code)  

Every serious Visual Basic programmer has faced, in one situation or another, the need to extend the intrinsic VB functionality with extra functions provided by the MS Windows Operating System.
To understand how we can use these OS functions, we should first understand the distinction between Static and Dynamic linking.

Let’s say that we have a VB program with just a TextBox. It’s easy to understand that the TextBox is in itself a program. Someone built this so-called "Object" and it’s there, on the Toolbox, available for us to put on every form we like it. But we know that all TextBoxes, be on our program or in any other program, have the same Properties, Methods and Events. That means that every program with TextBoxes running simultaneously on our computer, will need this same TextBox code.

To simplify, let’s assume that, in a certain moment in time, we are running 5 different programs on our computer that use TextBoxes. Where is the TextBox code? Will we have 5 different instances of the same code attached to our programs?

In fact, in the old days this was the only option available. Everytime we built an application we had to attach (link) the same piece of code to every application. The applications were almost self-contained with all the functionality required to fulfil their needs. On our example, this would be the result:

However, this is a waste of resources. Why don’t we put the TextBox code in a container where every program can dynamically load it and run it? This approach has another advantage: if we need to correct or extend the TextBox code we just have to replace its container. This is exactly the approach that is commonly used on MS Windows with DLL’s (Dynamic Link Libraries).

DLL’s are containers with pieces of code - like the TextBox. Therefore, we need to assign specifications to every piece of code contained in the DLL. These are called API’s (Application Programming Interfaces). With API’s, every programmer will know how to call these pieces of code and what to expect from them.

In this discussion, we are specially interested on the DLL’s readily available on our computers because they are a component of the MS Windows Operating System itself.

To go further, let’s take an example: let’s assume that we want to set, programmatically, the time and date of the computer where the program is running. On regular VB we have the Date and Time statements available to perform this. Unfortunately, these are not available on VBCE (Visual Basic for Windows CE) so lets search for an alternative method using a DLL API.

In fact there’s a system function already available that does exactly the same:

SetLocalTime

Now, let’s start our copy of the "API Text Viewer" and search for this function on the Win32api. We know that we have to specify system functions with Declare statements:

Public Declare Function SetLocalTime Lib "kernel32" _
( lpSystemTime As SYSTEMTIME) As Long

Now we know much about this particular system function:

	It’s contained in the "kernel32.dll" file
	Returns a Long value: "if the function succeeds, the return value is nonzero" (MSDN)
	We have to pass the date/time values through a User Defined Type called SYSTEMTIME

So we go again into our "API Text Viewer " and search for this Type:

Public Type SYSTEMTIME
wYear As Integer
wMonth As Integer
wDayOfWeek As Integer
wDay As Integer
wHour As Integer
wMinute As Integer
wSecond As Integer
wMilliseconds As Integer
End Type

And this is it. We just have to create a variable, fill in the desired values and call SetLocalTime. Let’s use it to check Y2K:

Dim sysTime as SYSTEMTIME
With sysTime
.wYear = 1999
.wMonth =12
.wDayOfWeek = 0 ‘This member of the SYSTEMTIME structure is ignored
.wDay = 31
.wHour = 24
.wMinute = 59
.wSecond = 59
.wMilliseconds = 0
End With
Call SetLocalTime(sysTime)

We would assume that we could do the same exact thing on Windows CE: we don’t! Why? Because on this version of the "Windows CE Toolkit for Visual Basic 6.0" there’s no UDT functionality. Period!

So we are still stuck on the same problem: how will we set programmatically the system date and time?

To solve this let’s first think about what it is, in fact, a User Defined Type. We may well call them also "structures" if we happened to use other programming languages. This is probably a much better term to describe this entity.

A UDT is nothing else then a contiguous block of memory containing sequential data, formatted as per its definition. On our SYSTEMTIME example, we should have an address in memory with 8 sequential integer values: from wYear to wMilliseconds:

That leads us to another problem: what is an Integer? Sure, we know it’s 2 bytes in memory. But which one is the first? The Most Significant Byte - MSB? The LSB? What about a Long, how do we fill in the 4 bytes? If we solve this problem we may probably mimic the UDT, creating a block of memory with exactly the same bytes as the UDT. And that can easily be done in a String!

Fortunately we can find on MSDN how to answer this question: "Windows was designed around the Little Endian architecture" which means "the little end is stored first". A number like &H1234 is stored in memory in two consecutive bytes: the first contains the Little End (&H34); the second the Big End (&H12). It works the same way for Long values - 4 bytes; for example, &H12345678 would be stored as (&H78 &H56 &H34 &H12).

The reason for this is historical: "on an Intel computer, the little end is stored first". It’s also stated on MSDN that Windows NT will never use "Big Endian architecture". That’s the reason why Windows NT was never ported to the PowerMac implementation of the PowerPC: the processor is stuck on Big Endian. Most of the other processors (RISC) are configurable to use either.

(Part II)