Component Database Manager

Jon Fincher
Microsoft Corporation

July 19, 2002

We've covered about everything there is to cover about components and Component Designer, so this month, let's dig into the next tool in our arsenal, Component Database Manager.

Components on their own aren't worth very much. They're small XML files that contain a set of data describing a concrete unit of functionality. We use Target Designer to collate that data into a set of files that represents a working runtime, but there's an in-between step—getting that data into a form Target Designer can work with. That's where Component Database Manager (DBMgr) comes in. Component Database Manager does a number of things for us, but its prime purpose is to take component definitions in the form of SLD files and put them in a component database that all Microsoft® Windows® XP Embedded tools can read.

Importing Components

When you first start Component Database Manager, the first two things you see are the current database location, and an Import button. We'll come back to the database server location in a minute, but what does that import button do?

Clicking Import brings up an Import dialog. (Fancy that!) Here, you can specify the name of a SLD file (you can use wildcards to import all SLDs in a folder), which repository root you want to use (more on that later), and whether you want to copy repository files to your database. You might uncheck this if you've updated your component but haven't updated the repository, in order to save some time copying files across a network.

The Database Server

The server listed in Component Database Manager is the server that all Windows XP Embedded tools will use. Its value is stored in the registry on the machine Component Database Manager is running on. You can have multiple databases across your network, and use Component Database Manager to switch between them. When switching databases, if you're the administrator on your system, you can specify that you want to switch databases for all users.

When Component Database Manager (or any Windows XP Embedded tool) first starts up, it first checks for the existence of the database specified. No database, no tool. However, Component Database Manager does one extra thing as well: It checks to see if the database it's connecting to is in use or not. Why? As we'll see a little later on, Component Database Manager allows you to delete components and other database objects. If we did that on a database that was in use, we might cause problems for whoever was using the database. (Imagine trying to build a configuration while someone else was deleting the component definitions you were building—yikes!)

If there's no one connected to the database, then Component Database Manager enters Exclusive Mode; it's got a hold on the database, and no one else can even look at it while Component Database Manager is running. If there is someone using the database, then Component Database Manager enters Shared Mode and disables all delete functionality—adding and viewing functionality is unchanged. And Component Database Manager automatically starts in Shared Mode when it's started from Target Designer or Component Designer; we already know another tool is running, so it doesn't check for Exclusive Mode access.

Platforms

Across the top of the Component Database Manager dialog is a series of tabs, the first of which is platforms. Here you can inspect all the information in the database about the platforms available to you. Right now, there's only one platform, so it's not much fun at this point.

Packages

Any and all packages defined in the database are here, including the packages you define. You can view all the members of a package, and if you delete a package, you delete all its members as well. It's a quick way to clean your database of unwanted objects.

Components

Here's the meat of the database; all the component definitions are here. Component Database Manager has a hard-coded visibility of 1000, so you won't see any lower visibility components here. You can filter the list, using filters defined in any tool. You can search the list, using the hidden CTL-F key. You can pare the list down by package using the drop down at the top. You can also inspect and delete components you select.

By the way, if you can navigate this Component Browser, you're ready to use Target Designer. It uses the same Component Browser.

Repositories

Here's the second most important part of Component Database Manager: the Repository tab. Every repository is listed here for inspection or deletion, and there are some extra things we can do with repositories as well.

At the bottom of the Repository tab are three buttons. The first is Repository Roots, which allows us to set the base folders into which we'll copy our repositories. This usually has only one entry, which corresponds to the Repositories share on the database server. You can add other roots, allowing you to copy repositories to different locations when you import their containing SLD files. Be careful, though: If you specify a local repository root, someone using your database over the network won't be able to build files from that repository.

You can even change the location of your repositories with the Change Location button. It acts upon the highlighted repository, and lets you move the repository wherever you want it. This allows you to do some simple load balancing by moving repositories to different locations to improve network performance. The same caution applies here as with repository roots: Moving a repository to a local folder (say, C:\foo) means that others using your database won't be able to build.

The last button, Delete Repository, should be self-explanatory.

Groups

All dependency groups and repository sets are listed here. That bears repeating: All repository sets and groups are listed here. In other words, this is the place to go if you want to view data on your dependency groups or your repository sets. (Okay, it's not important enough to repeat three times, but it's a small paragraph, and my English teacher always taught me that paragraphs need at least three sentences to be complete. Plus, I wanted to beef up my word count for this article.)

That's about all there is to Component Database Manager. I thought there was a lot more, but we covered most of it already. Let's go on to some questions from the newsgroups.

FAQ

Q: My application (or someone else's application) doesn't work in Windows XP Embedded, although it works fine in Windows XP. What's wrong?

A: This is a perennial favorite. If you're in the newsgroups regularly, you'll see this one every week or more. The difficulty usually stems from missing dependencies on the application in question.

If you've followed the steps from last month to componentize your application, then the next step is to use a tool like FileMon (available from https://www.sysinternals.com/) to monitor the embedded system while your application runs. Any files that appear in the FileMon log as FILE_NOT_FOUND are files you need in your system for the application to run properly. Beware, though: Windows XP searches a lot of places for necessary files, so be on the lookout for FILE_NOT_FOUND messages followed by a SUCCESS message when the file was found in another location. If there are files missing, you can use the filtering feature of Component Database Manager or Target Designer to find the component that contains that file and add it to your runtime.

If FileMon doesn't give you any relief, move to RegMon (available from the same location). This is a real-time registry monitoring tool. The output is similar to FileMon, but since the Windows XP registry is hit a lot more often than files, the log is much longer. The second problem is that there's no easy way to filter the component list based on who owns a registry key. In that case, post the key you're looking for to the newsgroup, and we'll help track it down for you.

One other technique useful for tracking down problems is to use a safe build. When we build runtimes in our lab, we do it on a second hard drive or partition in a normal Windows XP machine (the retail Windows XP image lives on C:\, and the embedded runtime goes on D:\). The C:\BOOT.INI is modified to point to the embedded image, and the configuration's Target Device Settings are set to point to D:\, with the boot drive at C:\. When the runtime is built, a DriveD folder appears in the build folder. This is copied to D:\ on the machine, and the machine is rebooted to the embedded image. This arrangement allows you to use and copy tools from C:\ (which is a full Windows XP build) for use on the embedded system. For example, if you need to look at the registry on the embedded system but didn't include the Registry Editor component, you can run the registry editor located on C:\Windows\System32. You can also store your monitoring tools on C:\, which allows you to quick format D:\ to install a new runtime.

Q: I ran TA.EXE, then imported it into Target Designer, and built my image, but it doesn't boot. What's wrong?

A: Ah, the joys of Target Analyzer! It's both a blessing and a curse for those who know and use it.

There are two Target Analyzer executables—TA.EXE and TAP.EXE. The differences are profound and subtle at the same time. TA.EXE will run on anything—DOS, Windows 95, Windows 2000, Windows XP, Windows PE, Win9x boot disks, you name it. TAP.EXE, however, only runs on Windows 2000 and Windows XP systems. The output from TAP.EXE is a complete list of all hardware in the system, while TA.EXE's output is woefully incomplete at times. Why?

TAP.EXE works so well because it relies on the work already done by the Windows XP or Windows 2000 setup programs. It scans the registry for the hardware that it installed and dumps that information into the PMQ file. We get a complete list of hardware that the system knows is there, including anything that was installed post-install like third-party drivers.

TA.EXE, on the other hand, makes no assumptions about the system it's running on. It simply sends queries to the system BIOS asking it to tell us what hardware is installed. Since most BIOSs don't know anything about PCI adapters or software-enumerated devices, the PMQ is mostly full of plug-and-play IDs for well-defined devices—keyboards, mice, floppy drives, standard video and disk drive controllers, and so on. Because it's going through the BIOS, TA.EXE won't see your Adaptec® 3940U PCI SCSI controller, nor any of the devices on the SCSI chain. We won't see your Intel® 82371FB PCI Bus Master IDE Controller, nor any of the devices on the IDE chain. And we won't see your NVIDIA® GeForce2 AGP 3D accelerator card, nor the monitor it's connected to.

In short, TA.EXE won't find any device the BIOS can't describe for us. That usually means we'll be missing critical boot devices (IDE controllers, Primary and Secondary IDE channels, and so on), most PCI devices (NICs, video cards, and so on), and a host of software-enumerated devices (multi-function cards, sound card, and so on). In order to turn a TA.EXE-generated PMQ into a workable configuration, you'll need to add these devices manually.

Q: My video resolution isn't being set. What's wrong?

A: Every video card has a Settings tab that allows you to set the resolution and color depth of the card in the runtime. These settings are read during FBA, and the driver is called to set the specified resolution, color depth, and refresh rate. However, sometimes those settings aren't actually set during FBA, and your runtime comes up in 640x480x8 mode.

This may sound like I'm avoiding the real issue, but bear with me. The answer lies in the video driver. FBA is calling well-known and well-defined APIs to set the video resolution—the same calls that are made when you manually change the resolution on a Windows XP system in Display Properties. If the driver doesn't like the settings, or fails the call, FBA logs it and moves on.

To troubleshoot this, try picking lower resolutions and lower color depths. Most cards will support a resolution of 800x600x16 (not every card can do 1600x1200x32). And remember, there's a monitor involved as well. If the monitor can't handle the refresh rate, it may veto the resolution change. Start small and work your way up. And if all else fails and you can't get out of 640x480x8, add the Display Control Panel component so you can change the resolution on the embedded system.

Summary

As much as I'd like to continue this column for a few more hours, I need to conclude now. Next month, we'll be talking about the features across all the Windows XP Embedded toolset.

Get Embedded

A native New Englander, Jon Fincher worked as a UNIX System Administrator and database programmer before joining Microsoft Product Support Services in 1995. In 1999 he started supporting Windows NT Embedded 4.0, and is now a Software Test Engineer for Windows XP Embedded. He can be seen year round, in all weather, riding his Harley to and from work and play.