ActiveX Data Objects v2.0 SDK for Windows CE 2.0

This document contains information you should read before installing and using the accompanying software. Note the expressions ADO and ADOCE are used interchangeably in this document to refer to ActiveX Data Objects for Windows CE.

Last updated 25-Sep-98.

Contents

1. What is installed?
2. How Do I Start?
3. Newsgroups
4. Runtime and setup issues
5. Frequently Asked Questions
6. Distribution

What is installed?

This setup installs:

NOTE: this ADOCE SDK will only work for Handheld PC's running Windows CE version 2.0.  It will not work with Palm Size PCs.

• ADOCE v2.0 - an ActiveX control that provides advanced database programmability for VBCE & VCCE programmers
• Desktop filters which enable transfer of Microsoft Access and Microsoft SQL Server tables to a H/PC running Windows CE 2.0
• Documentation and sample code for Visual Basic and Visual C++
• Links to documentation and code samples under a start menu group "Microsoft ADOCE 2.0"

^Return to top

How Do I Start?

Make sure you have Windows CE Services installed, Version 2.1 is recommended.

To get Windows CE Services 2.1 please go to the following web location:

http://www.microsoft.com/windowsce/hpc/basics/software/wceserv.asp

Note:  This upgrade to Windows CE Services 2.0 primarily adds support for Windows CE-powered Palm-size PC devices.  In addition it provides some enhancements which are utilized by ADOCE 2.0.

Recreate the partnership between your PC and H/PC, to allow the installation of the Table filters. To do this, simply delete your H/PC device icon from within the Mobile Devices window. When your H/PC reconnects to the host PC, you will be asked if you wish to recreate the partnership.

If you do not do this you will get an error message saying "Microsoft Table Service not installed."

Run the setup program.

^Return to top

Newsgroups

The newsgroup news:microsoft.public.ado.wincebeta has been created to exchange information about beta releases of ADOCE.

Other helpful newsgroups available at the time of writing are:

news:microsoft.public.windowsce ,

news:microsoft.public.win32.programmer.wince ,

news:comp.os.ms-windows.ce .

Please check http://www.microsoft.com/windowsce for news about updates to ADO for Windows CE, or subscribe to the Windows CE Developer News Flash at http://www.microsoft.com/windowsce/wce_devnews.htm to receive updates by e-mail.

^Return to top

Runtime and Setup Issues

General

• Using Windows CE Services version 2.0 will sometimes leak memory on the device during data transfer. Later versions of Windows CE Services remedy this.

Setup

• Uninstall does not remove files from the H/PC. You should do this yourself using CEAppMgr on the host, or Control Panel->Remove Programs on the H/PC. Until this is done, ActiveSync will report errors.

^Return to top

Frequently Asked Questions

Setup

Failed: Coredll.dll could not be found in the specified path

This message occurs when setup thinks it has found the Windows CE emulator on your machine and is trying to register the adoce.dll (or possibly other activities such as updating the object store with the empfile utility). The most recent cause of this has been an early beta version of the P/PC SDK which upsets various environment variables. To fix this you can try one of the following:

1. Update your Palm PC beta which has a fix for the empfile emulator sync tool
2. Set your target platform to H/PC rather than P/PC. Please see the section titled "Building for Emulation" in the Windows CE Platform SDK Release Notes (Start>Programs>Windows CE Platform SDK>Release Notes). If you are still not sure how to do this, please contact your Microsoft representative.

Another cause could be an old Windows CE Platform SDK setup that hasn't been fully deleted and/or has become corrupted due to multiple beta installs. If so, then doing an uninstall of the Windows CE Platform SDK and then a reinstall of it and reinstall of the ADOCE SDK should fix the problem. You could even skip the Platform SDK reinstall if you're only trying to make setup work on a device and not the emulator.

You may be able to work around this problem simply by starting the emulator on your machine before running setup. That will load coredll.dll which will then be found by adoce.dll when its trying to register itself for use in the emulator.

^Return to top

General

How does this release differ from the ADOCE SDK Beta releases?

This control is a lightweight version of the ADOCE control released in beta form, and excludes table synchronization.

We plan to release the complete version of the ADO CE control as part of the upcoming Windows CE 2.1 operating system release scheduled for later this year. At that time, we expect to provide additional features for the ADO CE control including Access MDB synchronization, SQL Server Table synchronization  and an expanded name space. Microsoft provided the beta release of the complete version of ADO CE to provide a preview and to help you get started with ADO, enabling developers to program database functionality in advance of a performance-optimized release.

^Return to top

General - Technical

Can I use ADOCE to access tables created directly with the Windows CE database APIs?

Yes, sort of. ADO provides more functionality than the underlying Windows CE database functions. The only way it can do this is by storing extra information about each table. If you create a table using CeCreateDatabase (sic) then ADO will not be able to "see" that table. Alternatively, if you create a table using ADO's "CREATE TABLE" syntax then both ADO and the CeOpenDatabase (etc) functions will be able to use the data. Note, though, that accessing a table using both ADO and the Ce database functions is "not supported". However this is mostly because CeWriteRecordProps allows you to write different data types for a given field on different rows (it's also because we've never tested this scenario). If your application behaves "normally" then in practice you probably won't have any problems.

Note that all CE database specific features are supported by ADO even though other MS database engines don't have corresponding features (usually because they're not necessary). E.g., you can specify unsigned int or ulong datatypes and "case sensitive" or "unknown first" indexes. It is recommended that you stop using these features in new applications where possible - both for greater compatibility with desktop databases and future CE compatibility.

^Return to top

Will ADOCE work with SQL Server?

Yes. You have to go to the Tools>Import Database Tables menu on the Mobile Devices window and select ODBC datasources.

^Return to top

What are the system tables used for? Why aren't they explained in the documentation? What do they look like?

ADO uses the system tables to add functionality to the underlying Windows CE database engine, e.g. functionality like field names and new data types. They aren't explained in the documentation because they may change in future releases. They are explained here because many people will work it out anyway so why try to hide it.

The system table layouts are described in this section but should never be documented as being supported. They will definitely change in future releases, possibly deleting information and breaking programs that rely on them. Just to be clear: You should not tamper with the system tables.

The system tables created are:

Although it's impossible to modify any of the system tables from ADO (except MSysProcs) we cannot stop anybody from altering the system tables using CE APIs. If you do, though, regardless of apparent success or failure, your results afterwards are undefined. You should not tamper with the system tables. Warning: If you delete ADO-created tables directly via CE APIs or table-deletion utilites, then entries for those tables will be left in the system table. If you use ADO to create a table, then use ADO to delete it.

MSysTables consists of the following fields:

MSysIndexes consists of the following fields:

MSysFields consists of the following fields:

MSysProcs consists of the following fields

ADO code can update the data in MSysProcs. This allows programs to store new SQL statements by name that can be executed with a call to the Recordset Open method.

^Return to top

I have used a utility to delete ADO created tables, but they still show up in the Export Database tool.

The tables still show up, because they are still recorded in the ADOCE system tables! Don't delete ADOCE created tables except through ADOCE. You may have to "cold boot" your device, by removing batteries, and then reinstall ADOCE.

^Return to top

How can I transfer data in and out of the emulator?

Some sample VB code is supplied with the SDK in the folder ..\Samples\VB\EmulDB which demonstrates a method for accomplishing this task.

Can I use this SDK to access the Windows CE Appointments, Contacts or Tasks databases?

No, ADOCE provides a superset of features over the underlying database functions. It only "understands" tables created by ADOCE or transferred via ADOCE from a PC. The standard databases require an extra interface layer for ADOCE to understand them.

Programming

I get a "File not found" error when I run the C++ sample

If you load the C++ sample into Visual C++ 5.0 and run it you will get an error something like: "E:\Windows CE Platform SDK\wce\emul\HPC\ADODEMO.exe" File not found. This is because the compiled program hasn't been copied into the emulator. Go to the Build menu and choose "Update Emulation Output File" or turn on "Always Download"

How should I handle errors?

As a COM OLE Automation server, ADO should handle errors by calling CreateErrorInfo, setting the appropriate fields and then leave it up to your program to call GetErrorInfo after getting a bad HResult. However, in Windows CE 2.0 the GetErrorInfo function isn't available. This makes it hard to use the standard COM error mechanisms. (IDispatch will work of course, but if you're writing in C/C++ you should be using the vtable directly since ADO supports dual interfaces.)

See the function AdoError in the sample program file adodemo.cpp to see how errors are handled in the release of ADOCE you have.

• In this release we have a work around. A function on the end of the Recordset vtable called get_ErrorDescription returns the text string associated with an error. You'll have to remember the HResult yourself.
• In subsequent ADO CE releases we will have a function called get_GetErrorInfo or similar which returns an IErrorInfo object. This will minimize changes to your code in the future when the OS starts supporting GetErrorInfo since you'll still be dealing the same object - you'll just get it from the OS instead of ADO.
• Regardless of the mechanism by which you get the error, ADOCE will only fill in the HResult and the Description. There won't be a helpfile on the device.

Bottom line: Isolate your error handling, use the C++ sample code as a guide and watch this space.

How can I load a grid control from ADOCE?

Here is some sample VB code  to load a grid control from ADOCE. It takes a table name, entered through a text box and populates the grid

Private Sub CmdGetData_Click()

Dim record
Dim field
Dim records
Dim maxrecord
Dim maxfields
Dim rs
Dim sql
GridCtrl1.Clear
On Error Resume Next
If Len(Trim(Text1)) Then
    Set rs = CreateObject("adoce.recordset")
    sql = "select * from " & Text1
    rs.open sql, , 3, 4
    records = rs.getrows()
    maxrecord = rs.recordcount
    GridCtrl1.Rows = maxrecord
    maxfields = rs.fields.Count
    GridCtrl1.Cols = maxfields
    For record = 0 To maxrecord - 1
        For field = 0 To maxfields - 1
            GridCtrl1.TextMatrix(record, field) = records(field, record)
        Next
    Next
    GridCtrl1.FillStyle = 1
    GridCtrl1.Row = 0
    GridCtrl1.Col = 0
    rs.Close
    Set rs = Nothing
End If
End Sub

^Return to top

Distribution

If you are distributing Windows CE software which includes ADOCE, you should check that the target device does not include a more recent version of ADOCE. You risk breaking other applications which depend on new ADOCE features if you install over newer ADOCE libraries.