Getting Started: Microsoft Windows CE Toolkit for Visual Basic 6.0

 

Dave Mendlen
Microsoft Corporation

July 27, 1999

Click here to download the Simple ADOCE sample file from the Downloads Center.

Summary: This document will walk you through the creation of your first Microsoft® Windows® CE application written in Microsoft Visual Basic® and expects that you don’t have a Windows CE device yet. We’ll help you set up an emulation environment and get you up and building your first database application quickly. (24 printed pages)

Overview of Windows CE

Microsoft Windows CE is an operating system, developed from scratch, that is designed to be the basis for many radically different types of devices. The approach was to create a foundation of software building blocks that could be assembled in many different ways to create new devices. This means that if you wanted to build a device, you could pick and choose only those pieces you needed and keep the size of your software consistent with the size of your device.

Rather than create new tools and new interfaces for programmers to use in their applications, Windows CE uses a subset of the Microsoft Win32® application programming interface (API) that is used on Windows-based desktop and server computers. This ensures that programmers can use the same development tools, such as the Microsoft Visual C++® or Microsoft Visual Basic development systems, and communications protocols to create applications for Windows CE-powered devices.

Companies that build electronic devices today can standardize on this open Windows CE platform, making it easier to find people with development expertise in Windows, get them up and running on a project, and have them easily shift between projects when needed.

Reducing cost, eliminating bugs, and simplifying application deployment are of great concern to developers. The Windows CE Toolkits have several features designed to make this phase of application development as painless as possible including the Windows CE emulation environments, a rich graphical debugger, and automatic application deployment.

What’s in this Product

The Windows CE Toolkit for Visual Basic 6.0 consists of 4 related components:

  • The Visual Basic add-in to target Windows CE.
  • The Windows CE Platform SDK.
  • Windows CE Services.
  • ActiveX® Data Objects for Windows CE (ADOCE).

The Windows CE Toolkit for Visual Basic 6.0 (VBCE) extends the Visual Basic 6.0 environment to accommodate the construction of Windows CE-based applications. It modifies the Visual Basic Integrated Development Environment (IDE) by limiting the functionality of Visual Basic to the features that are supported on the Windows CE device that you are targeting.

The Platform SDK provides the low-level APIs and additional tools to help you build Windows CE-based applications. The most important component in the SDK is a Windows CE emulator, which allows developers to test their Visual Basic applications without having a Windows CE device.

Windows CE Services is a software-based communication mechanism for transferring files between the PC and the Windows CE device. Windows CE Services runs on Windows 95, Windows 98, and Windows NT®. Even though you may not have a device, you still need Windows CE Services, as it is required for ADOCE.

ADOCE is a subset of the traditional ActiveX Data Objects that enable developers to create tables and to execute Structured Query Language (SQL) on the Windows CE device. It has a limited subset of the ADO that you use when developing traditional VB applications for Windows.

What’s in this Document

This document is designed to give you a head start on programming Visual Basic applications on Windows CE. It includes information on installing the various components and configuring the Visual Basic Integrated Development Environment and the Windows CE emulator to get you started building powerful Windows CE applications immediately.

This guide assumes that you DO NOT have a Windows CE device yet and explains how to set up a Windows CE emulator.

Software Requirements

To use the Windows CE toolkit, you need

  • Windows 95, Windows 98, or Windows NT 4.0 (with Service Pack 3).

    **Note   **Windows NT is required for Windows CE Emulation.

  • Microsoft Visual Basic 6.0.

  • Windows CE Services 2.1 or greater.

  • Windows CE Toolkit for Visual Basic 6.0.

  • ADOCE (optional).

Manual Conventions

This Getting Started guide uses the following special fonts:

Monospace   This type represents text that you type or text as it appears onscreen.

Italics   These are used to emphasize and introduce words, and to indicate variable names (identifiers), function names, class names, and structure names.

Bold This type indicates reserved keywords.

Keycap   This type represents a particular key you should press on your keyboard. For example, “Press Del to erase the character.”

***Key1+Key2   ***This indicates a command that requires you to press Key1 with Key2. For example, Shift+b (although not a command) indicates the uppercase letter “B.”

ALL CAPS   This type represents disk directories, file names, and application names.

Menu|Choice   This represents menu commands. Rather than use the phrase “choose the Print command from the File menu,” we’ll use the convention “choose File|Print.”

Installing VBCE

Before you can create Windows CE applications with Visual Basic, you need to install Visual Basic 6.0 (with Visual Studio® Service Pack 3 or later), Windows CE Services, and VBCE. If you want to take advantage of database functionality in the environment, you also need to install ADOCE. This chapter describes how to install the products you need. There is a recommended order for installing the products:

  1. Windows NT 4.0
  2. NT Service Pack 3
  3. Microsoft Visual Basic 6.0
  4. Microsoft Windows CE Toolkit for Visual Basic 6.0
  5. Windows CE Platform SDK
  6. Windows CE Services

Installing the Windows CE Toolkit for Visual Basic 6.0

To install VBCE from CD, follow these steps:

  1. Insert the VBCE disc into your CD-ROM drive.

  2. If the AutoRun application does not execute, then run SETUP.EXE from the \VBCE directory of your CD-ROM.

  3. Accept the defaults for all prompts. When prompted for your CD Key, you’ll find it on the back of your CE Toolkit CD envelope.

  4. When prompted for which type of install, press the Complete button.

  5. Press OK on the following dialog:

Installing the Platform SDK

  1. You will automatically be taken into the Setup application for the Platform SDK.

  2. Select the Typical installation option.

  3. When setup is complete, you will see the readme notes in your browser. When you are finished reading, close the browser window:

  4. Installation of the Platform SDK and the VB CE Toolkit is now complete.

Installing Windows CE Services

Windows CE Services provides the utilities and applications necessary for your desktop machine to communicate with external Windows CE devices and the emulation environments.

  1. Insert the Windows CE Services CD into your CD-ROM drive.

  2. The AutoRun setup application will launch. Click the Typical button.

  3. Click the Next button.

  4. The CE Services utilize RAS for communication and will need to install and configure it. Press the Yes button on this dialog.

  5. You will now need to restart your computer:

  6. After NT boots, rerun the Setup application. Click the Next button to continue installation.

  7. When the Setup application is complete, you will be prompted to add a shortcut to the desktop:

  8. You will then have to reboot NT again to complete Windows CE Services installation:

  9. Once you reboot, you will be prompted to set up Windows CE Services. This getting started guide presumes that you don’t actually have a Windows CE device. You’ll want to deviate from the directions to actually connect your device if you have one.

  10. You will then be prompted with the following dialog. Press the OK button to dismiss the “Welcome to Windows CE Services Dialog.” Then press the OK button to close the Windows CE Services Properties dialog.

Upon completion, the install program creates a program group called Windows CE Services that includes icons for Windows CE Services Help, Release Notes, and a shortcut to the Mobile Devices folder. You can also find your new Mobile Devices folder under the My Computer icon.

Installing the ADOCE Toolkit

If you plan on doing database access in your VBCE applications, you’ll need to install the ADOCE SDK. To install the ADOCE SDK from CD:

  1. Insert the Windows CE Toolkit for Visual Basic 6.0 into your CD-ROM drive.

  2. Run the ADO2CE2.EXE file from the \ADOCE directory.

  3. Choose a folder to extract the ADOCE setup application to:

  4. Click the Install ADOCE button.

  5. Click the Yes button to install the ADOCE emulation version.

  6. The ADOCE installation spawns the Windows CE Application Manager to install ADOCE on any Windows CE devices that establish partnerships with the desktop. Click OK to confirm that, the next time you synchronize a device, ADOCE will be installed.

  7. Installation of ADOCE is now complete.

Configuring the Environment

Setting the System Path

In order to get ADOCE to work properly, you need to update your Windows NT path.

  1. Open the Control Panel.

  2. Double-click the System icon.

  3. Switch to the Environment Tab:

    Highlight the Path System Variable in the list box at the top. You will see the current value for your Path in the Value textbox at the bottom. Move your cursor to the end of the current path and type the location of your \emulation\windows directory (see illustration above).

Moving a Database to Windows CE Emulation

To use ADO in the emulation environment, you need to copy tables from a PC data source (we’ll use the Microsoft Access Northwind sample database) to the Windows CE emulation environment. Unfortunately, this is a manual process. However if you follow the steps outlined below, you’ll be programming against ADOCE in minutes.

First, you need to run Visual Basic 6.0. Then File|Open the VBEMULDB.VBP project. See the picture below for the folder hierarchy where you will likely find the application:

Run the application (F5). Click the Select DB… button and navigate to the NWIND.MDB database that ships with the VBCE Toolkit. See the diagram below:

Click the Convert DB button. When you press the button, this application interrogates the structure of the database and creates a new file in the same directory as the NWIND.MDB called NWIND.TDB. The new file is made up of CREATE TABLE statements as well as INSERT statements. Later, we’ll use another Visual Basic application to execute these SQL statements to create the structures and insert the data on the Windows CE Emulation environment.

Click the Copy to Emulator button. If it works correctly, the emulator should launch. It will copy the NWIND.TDB file to the root of your emulated Windows CE environment, which is “\NWIND.TDB” Notice that there are no drive letters on the CE device. This step is copying the text file with all the SQL statements up to the Windows CE Emulator.

**Note   **If the emulator doesn't launch, simply go to the command prompt and run the EMPFile application:

The format is empfile -c sourcefile.tdb WCE: destinationfile.tdb

Close the VBEMUL.VBP project in Visual Basic 6.0. Open the EMUL.VBP project from the same directory in which you found VBEMUL.VBP. This application will run from within the emulated Windows CE environment. The application will execute the SQL statements in the NWIND.TDB file that was copied into the environment. When you open the project, you may be prompted with dialogs to specify the target platform (see dialogs below). Accept the defaults and click the OK button.

Run the application (F5). The Windows CE Emulator will launch in the upper left corner of your screen:

Shortly, the Visual Basic application will run inside that window. In the textbox at the top of the form type \NWIND.TDB and then click the Create Tables… button.

The application will then begin executing the Create Table statements, which will create tables in ADOCE on the emulator. It will also execute the Insert statements to populate the database with the data that was in the Access .MDB.

When you see the Message Box that states “Completed Processing,” you can close down the Windows CE Emulator by selecting Suspend from the Start menu in the emulator, not the Start menu from Windows NT. This stops the Visual Basic application.

Building Database Applications

VBCE provides you with the ability to develop database applications using ADOCE. It allows you to create, manipulate, and delete tables from within the VBCE environment. This is a subset of the full ADO (ActiveX Data Objects) that you may already be aware of. The two key objects that you will be working with are the Recordset and Field objects.

You will not be able to use ADOCE to get at the Pocket Office applications, like the appointments database. These applications are not yet accessible through ADOCE, but can be accessed using the Pocket Outlook Object Model (POOM) SDK, available on the Windows CE Tools Web site.

Requirements

You need to have installed VBCE, the Platform SDK, Windows CE Services, and ADOCE. You also need to have tables copied into the emulator. For instructions on configuring your environment to make ADOCE work, see the earlier section on "Configuring the Environment."

A Simple Database Program Example

The simple application that follows demonstrates how to retrieve a list of tables from the ADOCE database.

Example step-by-step

The following explains the steps taken to build your first VB database application:

  1. Launch Visual Basic 6.0. Select "Windows CE HPC Project" from the New Project dialog (see below) and click the Open button.

  2. Fill out the Project Properties dialog that pops up as you see below:

  3. Click the OK button.

  4. Drop a Command button, a Listbox, and a Label on the form as seen below:

  5. Rename the Command1 button to cmdExecute.

  6. Double-click the button to bring up the code editor.

  7. Open up the Project|References dialog and add a reference to Microsoft CE ADO Control (ADOCE) 2.0

  8. Click the OK button to close the dialog. Save the project.

  9. Time to code! First, we define a new object that connects with the typelibrary that we just added. Notice that the compiler actually implements Visual Basic, Scripting Edition (VBScript) on the Windows CE device and on the emulator. That means that this strong typing will be stripped out of the executing application. Why do it then? The answer is that it minimizes coding errors. Later, when we refer to this object, we’ll get an IntelliSense® list that limits the methods/properties that you can implement.

    There is also a variable definition (mytablename) where we will store the value of the field returned from ADOCE.

    Private Sub cmdExecute_Click()
    Dim myobj As ADOCELib.ADOCERecordset
    Dim mytablename As String
    
  10. This line instantiates ADOCE.

    Set myobj = CreateObject("ADOCE.Recordset")
    
  11. Set the data source to a SQL statement. In this case, we’re asking for a list of all the tables in the system catalog. We then open the recordset.

    myobj.Source = "Select * from MsysTables"
    myobj.Open
    

The next block of code checks to make sure the recordset is not empty.

If myobj.RecordCount = 0 Then
    Exit Sub
End If

This block of code will start looping through the recordset. We then assign the value of the TableName column to the mytablename variable. Finally, we add the value to the listbox.

Do Until myobj.EOF
    mytablename = myobj.Fields("TableName").Value
    'Check for nulls
    If mytablename <> "" Then
        'The Msys tables are system tables
        List1.AddItem mytablename
    End If
    myobj.MoveNext
Loop

Running the sample program

The code listed in the next section contains the complete sample program. To compile and run the application you must perform the following steps:

  1. Simply press F5.

The complete sample code

Private Sub cmdExecute_Click()
    'Use early binding so that IntelliSense works against the
    'objects in the IDE. Notice that the variable declaration 
    'and the CreateObject ProgID are slightly different. The
    'variable declaration gets converted to a variant at
    'compile/runtime.
    Dim myobj As ADOCELib.ADOCERecordset
    Dim mytablename As String
    Set myobj = CreateObject("ADOCE.Recordset")
    myobj.Source = "Select * from MsysTables"
    myobj.Open
    
    If myobj.RecordCount = 0 Then
        Exit Sub
    End If
    
    Do Until myobj.EOF
        mytablename = myobj.Fields("TableName").Value
        'Check for nulls
        If mytablename <> "" Then
            'The Msys tables are system tables
            List1.AddItem mytablename
        End If
        myobj.MoveNext
    Loop
End Sub

As you can see, it is very easy to develop powerful database-driven applications in Windows CE with Visual Basic. Although this application was a fairly simple ADO CE application, it should be easy to see how the application could be extended to build sophisticated mobile solutions that leverage corporate data that is synchronized with Oracle or SQL Server™ 7.0.

What’s Different than Typical VB Development?

This section highlights the big differences that you will discover between building Visual Basic 6.0 Windows applications and using the Windows CE Toolkit for Visual Basic 6.0.

Designing

There are some limitations you should be aware of when designing your VBCE applications. First, you can only have one .BAS file for your entire VBCE project. Also, you cannot use class modules in a VBCE project. Finally, MDI forms do not exist on Windows CE. Remember that most Windows CE devices have very limited screen real estate.

Coding

As mentioned earlier, the actual code running on the Windows CE device and in the emulator is VB Script which only supports one datatype: variant. Therefore all variable declarations will lose any strong data typing when they execute.

In order to terminate an application in VBCE, you must invoke the End method of the application object: App.End

You cannot unload forms in VBCE. In order to create the illusion of a form being unloaded, you can use the hide method: Form1.Hide

The VBCE Toolkit does not support the ability to use traditional Error Handling in a VBCE application. You should use the:

On Error Resume Next

syntax to allow errors to fall through. You will then need to interrogate the err object periodically to determine if there were errors.

The VBCE Toolkit does not support the ability to create applications that use API calls.

Debugging

One of the first things that you’ll notice when you start stepping through (F8) your first application is that the Windows CE Toolkit does not utilize the standard Visual Basic 6.0 debugger. See the diagram below to see the VBCE debugger.

You will find that you can’t use the keywords DEBUG.PRINT because the debug object doesn’t exist in VBCE. However the rest of the debugging tools are very comparable to what Visual Basic provides.