On The Cover: August 1998, Volume 4, Number 8

August 1998, Volume 4, Number 8
Cover Art By: Tom McKeith and Doug Smith
ON THE COVER 29 The API Calls

7 Delphi 4 Multi-Tier Bill Todd Delphi and TAPI: Part II Major Ken Kyler and
Delphi 4 sports many new features for multi-tier applications, while Alan C. Moore, Ph.D.
making it easier to use MIDAS components for single- and two-tier Kyler and Moore continue their Telephony API series: This month it’s
applications. The MIDAS components now provide a flexible new determining the existing capabilities of the particular TAPI implemen-
architecture for any database application, as Mr Todd explains. tation and monitoring changes to the COMM port.
35 At Your Fingertips
Better Coding through APIs Robert Vivrette
Less is more, as our own Mr Vivrette explains. This time around he
FEATURES discusses simple, useful API routines that few developers even realize
exist, yet can save considerable programming effort.
12 On the ’Net
IE4’s DOM Advantage Ron Loewy
IE4 introduced DHTML and the Document Object Model, greatly REVIEWS
expanding the control a Windows app can have over a Web browser
control. Now Mr Loewy puts it to use from Delphi. 37 ODBCExpress
Product Review by Steve Garland
17 Algorithms
Vivid Equations Rod Stephens
42 Nathan Wallace’s Delphi 3 Example Book
Book Review by Warren Rachele
Mr Stephens introduces 3-D graphics programming, including transla-
tion, scaling, projection, and rotation, and — as usual — provides
hands-on examples to get you started.
DEPARTMENTS
24 DBNavigator 2 Symposium by Zack Urlocker
Delphi Database Development Cary Jensen, Ph.D. 3 Delphi Tools
Dr Jensen closes a three-year circle and re-examines database pro- 5 Newsline
gramming from a Delphi perspective. A lot has changed since version 44 From the Trenches by Dan Miser
1, but one thing has not: Delphi is still the best tool for the job. 45 File | New by Alan C. Moore, Ph.D.
1 August 1998 Delphi Informant
Symposium
By Zack Urlocker
Life after Borland; Long Live Delphi!
I t’s been a busy, but exciting time in Scotts Valley the past several months. The company has continued to
grow revenues and maintain profitability, we’re shipping new products every quarter, oh, and we
changed our name. I’m sure there was a collective “What?” heard when Delphi developers around the
world fired up their browsers to www.borland.com and saw an announcement about INPRISE Corporation.
The Borland brand name is a good one. edge in this area that’s hard to beat. At depending on who we were talking to.
It’s associated with high quality, high pro- the same time, we’ve made sure to add Delphi was variously known as VIP,
ductivity development tools such as some of the latest productivity features to Visual Foo, Del Mar, Del Rio, Del Fuego,
Delphi, C++Builder, and JBuilder. Delphi 4, including more debugging VBK, and Wasabi (Don’t ask!). Internally,
However, development is just one part of tools, a more modern user interface with the compiler was “Version 8” but we
what INPRISE Corp. is focused on. Our dockable toolbars and windows, a sophis- wanted a name that showed just how far
mission is to radically simplify the devel- ticated application browser, more com- the product had evolved from Borland
opment, deployment, and management of ponents, and much improved documen- Pascal. We struggled with such convoluted
distributed enterprise applications. That tation, among other things. names as Visual App Builder, but in the
makes development tools, including end, we decided to go with the name that
Delphi, critical to our strategy, but it also Ongoing change. One of the things I’ve our beta testers liked best: Delphi.
reinforces the need for additional products learned in my years at Borland is that
that support deployment and management you must keep innovating, or you’ll fall So what’s it all mean? For Delphi devel-
of enterprise applications. For example, we by the wayside. It’s as true in program- opers, the company name change should
have the Entera RPC-based middleware, ming as it is in business. If you look be pretty minor. We’ll continue to create
the VisiBroker CORBA Object Request back at programming techniques and new versions of our development tools
Broker, ITS Integrated Transaction Service, tools five years ago and compare them and try to have innovative features for
AppCenter application management, and with the state of the art today, it’s a hobbyists, individual developers, consul-
a forthcoming Enterprise Application pretty radical change. Not only have the tants, and corporate developers. The most
Server. We will make sure that these prod- tools and techniques changed, but so significant aspect of the name change is
ucts are accessible from our development have the applications being built. Five that it symbolizes how much the compa-
environments, including Delphi, years ago, when the Delphi project first ny has changed over the last 18 months
C++Builder, and JBuilder. began, we were attempting to bring with a broader focus of integrating the
Borland Pascal into a new era of growth enterprise. We believe the name
The Delphi team has been particularly by solving much more difficult prob- INPRISE better reflects our overall
innovative in its support for COM, lems. We decided (though I had to drag strategy and direction than the Borland
CORBA, and RPC-based middleware. the R&D team kicking and screaming) name did. That being said, the Borland
Delphi 4 Client/Server Suite has all of that we needed to simplify both brand name will continue to be used for
the facilities to make it the most produc- Windows and client/server program- our development tools under the
tive development environment for any ming. It was quite a gamble, but it INPRISE Corp. umbrella. This is similar
distributed infrastructure. Because helped Borland launch into some new to what other large companies have done
INPRISE doesn’t have a platform agen- growing markets with our most success- when bringing to market multiple differ-
da, we’ll continue to support all the plat- ful product in years. Along the way, well ent product lines. For example, Network
forms our customers are asking for. That beyond a million copies of Delphi were Associates has the McAfee brand of anti-
means you can expect ongoing support sold, and hundreds of thousands of pro- virus software as one of its brand names.
for the latest Microsoft technologies, grammers made the transition to learn-
such as Windows 98, MTS, IIS, as well ing client/server programming skills and Delphi remains the product that I’m
as the latest cross-platform standards. became more successful in their careers. most proud of in my career, and you
Delphi has certainly exceeded our can expect Delphi will continue to play
In fact, I think people will be surprised expectations, and the Delphi team con- a pivotal role in our overall corporate
at how much innovation there is in tinues to amaze me with their dedica- strategy. After eight years of working at
Delphi 4. Delphi will continue growing tion and insight into programming. Borland International, I’m pleased to
and attracting even more new customers report that there is life after Borland.
who want to develop distributed applica- At the time, there was a lot of debate There’s INPRISE.
tions, as well as desktop and client/server about what Delphi should be called.
applications. Certainly, no tools have Many of you know the name Delphi was Zack Urlocker is Vice President of
made distributed development easy originally chosen as a code name. In fact, Marketing at INPRISE Corp., developer
before, and we think Delphi’s got an we used a lot of different code names, of Borland and VisiBroker products.

Delphi ForeFront Announces ForeHelp 3 and ForeHelp Premier 98
ForeFront, Inc.
T O O L S announced ForeHelp 3 and
ForeHelp Premier 98,
New Products updated releases of the
and Solutions company’s help-authoring
program and suite of help-
authoring tools. The prod-
ucts offer an indexing
application, a development
tool that keeps dialog-box
help synchronized with
software applications, and a
content management sys-
tem that allows developers
to create help for Windows
95 and Windows 98 from
one project database. on a floating palette; a addition to ForeHelp 3,
ForeHelp 3 offers new Related Topics Wizard, three tools are introduced:
project management and which creates “See Also” Index Expert, QuickFix, and
automation features, buttons; and a Contents QuickContext.
including Topic Navigator, Editor, which visually cre-
which provides a customiz- ates and edits a table of ForeFront, Inc.
able navigation window; contents. Price: ForeHelp 3, US$395; ForeHelp
Reporter, which produces ForeHelp Premier 98 pack- Premier 98, US$699; users of competing
customized management ages ForeFront’s line of help- help-authoring suites can purchase
reports; Paste Palette, which authoring tools into a suite ForeHelp Premier 98 for US$249.
stores frequently used for WinHelp and HTML- Phone: (800) 357-8507
graphics, text, and buttons based help development. In Web Site: http://www.ff.com
Catalyst Releases SocketTools 2.1
Catalyst Development Terminal Emulator, Time Catalyst Development Corp.
Corp., provider of WinSock- Protocol, Web Browser, Price: US$247
compliant TCP/IP custom Whois Protocol, and Phone: (800) 766-3818
controls for VBX/ActiveX Windows Sockets. Web Site: http://www.catalyst.com
products, announced
SocketTools 2.1. Enterprise ONE Releases Jaadu
SocketTools 2.1 provides Enterprise ONE, Inc. together, and serves it to
18 controls, including 32-bit announced Jaadu, a Delphi the user.
ActiveX versions (supported component that adds Web Jaadu is a solution for
by Delphi 2 or later). server functionality to an Delphi 3 developers who
SocketTools 2.1 supports all application, using Delphi require rapid implementa-
Windows platforms, includ- Web components to extend tion of Web applications
ing Windows NT 4.0. the functionality. without dealing with the
SocketTools 2.1 compo- By employing Jaadu, limitations of CGI-shell,
nents include Audio Player, developers can fully exploit Win-CGI, ISAPI,
Domain Name Service, File built-in Delphi Web tech- and/or NSAPI program-
Transfer Protocol, Finger nologies, such as the ming.
Protocol, Gopher Protocol, WebDispatcher, In addition, the Jaadu
Image Viewer, Internet PageProducer, server component works as
Control Message Protocol, TableProducer, and a multi-threaded HTTP
Mail Message (MIME), QueryTableProducer com- server and programming
Network News Protocol, Post ponents. gateway.
Office Protocol, Remote The Jaadu package
Access Service, Remote includes the JaaduProducer, Enterprise ONE, Inc.
Command Execution, Simple a component that takes an Price: US$199
Mail Transfer Protocol, HTML template and a few Phone: (916) 947-9012
Telnet Network Terminal, data sources, puts them Web Site: http://www.jaadu.com

Delphi Raize Software Solutions Releases CodeSite
Raize Software Solutions,
T O O L S Inc. announced CodeSite, a
Delphi debugging tool that
New Products sends messages from an
and Solutions application to a message
viewer.
CodeSite is comprised of
the CodeSite Object and
the CodeSite Viewer. The
CodeSite Object is accessed
through an interface unit,
and is used to send mes-
sages to the viewer. The
messages can contain
objects, streams, string lists,
and standard data types,
such as integers and
Boolean values. CodeSite
also supports common data and recursive methods, CodeRush panel plug-in.
structures, such as TColor functions, and procedures. CodeSite supports 16- and
and TRect. Also, CodeSite provides 32-bit Delphi development.
Each CodeSite message is features for CodeRush CodeSite Viewers are pro-
associated with one of 15 users; 25 keyboard tem- vided for Windows 3.x and
types, including csmInfo, plates and a message expert Windows 95/NT.
csmCheckPoint, and make it easier to enter
csmObject. In addition, CodeSite statements into Raize Software Solutions, Inc.
each CodeSite message is source code. Also, the Price: US$79.95
time-stamped. CodeSite Viewer integrates Phone: (630) 717-7217
CodeSite offers the ability into the Delphi 3 IDE as a Web Site: http://www.raize.com
to group messages by
method. Method groupings
South Pacific Info Services Announces
can be nested, making them TWebCompress Component 2.0
effective for debugging South Pacific Information defined application on the
event-driven applications Services, Ltd. announced .EXE under remote control. A
TWebCompress Component “refresh” signal is also defined,
Lingscape Announces MultLang Suite 2 2.0, a site management com- forcing TWebCompress to re-
Lingscape announced MultLang Suite 2 extends ponent for Delphi and read its .INI file.
MultLang Suite 2, a set of the NLS API functions of WebHub. TWebCompress has TWebCompress 2.0 is con-
globalization tools for Delphi Windows with support for been rewritten to be a generic figurable (by site) for location
and C++. MultLang is based distributed locales, making it Delphi component, so it can of uploads, signal/report files,
on the Unicode 2.1 standard possible to produce multi- be used for remote site/com- “gather” archive, encryption
and works with a conversion language applications pression management in any passwords, etc. This configura-
engine to provide support for supporting several character Web site application. Source tion can be changed from
Japanese, Chinese, Arabic, sets on any Windows code for a WebDeploy appli- HTML, FTP control files,
Hebrew, Hungarian, Russian, localized edition. cation, which turns or via the panel user interface.
and all European languages. In addition, MultLang Suite TWebCompress 2.0 into a The Gather function can be
MultLang Suite 2 provides a 2 offers the Universal stand-alone application on a completely data-driven and
quality assurance wizard that Language Modules (ULM), a Web server, is provided for can be used to build ad hoc
keeps projects from showing self-describing dictionary managing compression/archive LHA/WinZip-compatible
defects in user interfaces, with its own interface. deploying tasks for multiple archives of particular files or
such as overlapping text, sites. A UserSignal property sets of files.
workable shortcuts, incorrect Lingscape and event hook have been
character sets, and non-trans- Price: US$998; upgrade from MultLang added to allow developer- South Pacific Information
lated items. The wizard 1.x, US$849. defined remote signaling. In Services, Ltd.
ensures that projects conform E-Mail: info@lingscape.com the WebDeploy application, Price: Free for download; licensing con-
to standards defined by the Web Site: http://www. this is implemented as a way ditions apply.
developer. lingscape.com to have the server run a Web Site: http://www.spis.co.nz

News INPRISE Releases Borland JBuilder 2
Scotts Valley, CA —
INPRISE Corp. announced
tions, applets, servlets, and
JavaBeans.
JBuilder 2 is available in
three versions: JBuilder 2
L I N E the release of Borland Corporations and govern- Client/Server Suite,
JBuilder 2, a new version of ment agencies worldwide JBuilder 2 Professional,
August 1998 its family of visual develop- using JBuilder include and JBuilder 2 Standard.
ment tools for creating pure Volvo, Daiwa Securities, For more information
Java business and database MicroAge, NationsBank, about JBuilder 2 call
applications for the enter- the Ohio Department of INPRISE at (800) 233-
prise. Transportation, Eli Lilly, 2444, or visit the JBuilder
JBuilder 2 allows corpo- Nationwide Insurance, Web site at http://www.
rations to use 100% Pure Mercedes-Benz, and many inprise.com/jbuilder/.
Java technologies, including others.
JDK 1.1.6 and JFC/Swing,
to create platform-indepen- Delphi Prefix Registry Online
dent business applications. Manchester, England — registry/dpr.htm, promotes
The Borland JBuilder Steven J. Healey, an appli- component builders global-
product family features cations developer specializ- ly by registering not only
JavaBean component cre- ing in manufacturing sys- prefixes, but also the com-
ation, a scalable database tems, announced the ponents themselves.
architecture, visual “Two- Delphi Prefix Registry Developers can register
Way” development tools, (DPxR), hosted by HREF. their components, as well as
and the ability to produce DPxR, located at find other developers’ com-
100% Pure Java applica- http://developers.href.com/ ponents. The registry aims
to reduce the chances of
Apogee Extends Services to Include AS/400 naming conflicts with the
Marlboro, MA — Apogee Suite is a visual, high-perfor- use of prefixes. Conflicts
Information Systems, Inc. mance Windows develop- can occur when developers
announced support for ment tool that features visual build components in isola-
Borland Delphi/400 component-based design, a tion.
Client/Server Suite. 32-bit, native code compiler, For developers trying to
The move extends the and an open, scalable data- locate components, the reg-
company’s ability to deliver base architecture in an istry provides an alternative
multi-tier, enterprise appli- object-oriented environment. to checking Delphi news-
cations for corporations and Apogee Information groups, using Web search
governments by allowing Systems, Inc. is a custom engines, and visiting the
the company to include application consulting and Delphi Super Page. The site
native access to AS/400 development firm specializ- also contains links to major
databases in custom applica- ing in INPRISE technolo- component builders.
tions developed for its gy-based solutions. For Supporters of the registry
clients. more information on and/or the use of prefixes
INPRISE’s Borland Apogee, visit http://www. include Ray Konopka, Bob
Delphi/400 Client/Server apogeeis.com. Swart, and Marco Cantù.
InterBase Ports InterBase 4.0 to Linux
Scotts Valley, CA — Current InterBase cus- InterBase 5 for Linux is
InterBase Software Corp. tomers include the United planned to offer new SQL
announced the availability States Army, Motorola, and server 1999 features
of InterBase 4.0 for the Inc., the Philadelphia Stock that will give InterBase scal-
Linux operating system Exchange, Colorado ability, concurrency, and
(Red Hat 4.2) as a free Mountain Express, and improved productivity,
download on the InterBase others. including InterClient, an
Web site, located at InterBase 5, which is all-Java JDBC driver.
http://www.interbase.com. available for Windows Users will be able to pur-
InterBase 4.0, a relational 95/NT, Solaris, and HP- chase InterBase 5 for Linux
database, is designed to be UX, will be available for via download at the
embedded into VAR appli- Linux (Red Hat 5.0) in the InterBase Web site after its
cations. third quarter, 1998. release.

Triple Point Technology Uses Delphi
to Develop OutPost
INPRISE Appoints
John A. Racioppi
as VP/GM
News
Westport, CT — Triple Point TEMPEST 2000 is an office L I N E
Technology, Inc. introduced trading system for the physi- Scotts Valley, CA —
OutPost, a Web-enabled stor- cal and derivative energy INPRISE Corp. named
age and retrieval system for commodity markets. John A. Racioppi Vice August 1998
users of Triple Point’s TEM- FRANKLIN is a comprehen- President and General
PEST 2000 and FRANKLIN sive commodity trading sys- Manager, US, a newly
commodity trading systems. tem for the electricity and created position.
OutPost enables traders, trad- natural gas markets. Using Racioppi has over 17
ing managers, and executive OutPost, individuals can gen- years of sales and man-
management to access risk erate a report with TEM- agement experience, and
management data and trading PEST 2000 or FRANKLIN, will report to John
results remotely, via an and post it in the OutPost Floisand, Senior Vice
intranet or the Internet. database. Once in the data- President of Worldwide
OutPost has a three-tier base, authorized users can Sales. Racioppi is respon-
client/server architecture. The access reports for previewing sible for INPRISE’s US
client software’s graphical user or printing using Microsoft direct sales, channel sales,
interface components are Internet Explorer or Netscape educational sales, and
ActiveX controls developed Navigator browsers. OEM sales activities, as
using Delphi 3. The middle- For more information, con- well as customer service
ware software was also devel- tact Triple Point Technology organization.
oped with Delphi 3 and uti- at (203) 291-7979, or visit Racioppi joins the
lizes MIDAS middleware their Web site at INPRISE team from
technology. http://www.tpt.com. DASCOM Corp., a
developer of security,
INPRISE Teams with Referentia Systems authorization, and scala-
bility tools for intranet
for Java System and extranet applications,
San Francisco, CA — Try It feature, which allows where he was Vice
INPRISE Corp. announced users to work in JBuilder President of Worldwide
it has teamed with Referentia while following textual Sales. Prior to DAS-
Systems Inc. to create and/or narrated instructions. COM, Racioppi spent
Referentia for JBuilder: The system’s extensibility five years with Transarc
Volume 1, an integrated, allows users to add future Corp., an IBM subsidiary
extensible, multimedia learn- volumes of content to their and developer of distrib-
ing system for any software library of built-in JBuilder uted transaction process-
development tool. Referentia tutorials. ing and file systems mid-
for JBuilder is a separate Referentia for JBuilder: dleware, where he was
product from JBuilder. Volume I includes tutorials responsible for the com-
The system provides tips, authored by recognized pany’s international sales
tricks, and training using industry experts. and OEM source licens-
narrated lesson animations to For more information, ing business units.
teach JBuilder techniques. It contact Referentia Systems Racioppi’s experience
launches from JBuilder’s at (888) 983-6877 or also includes sales and
Help menu and includes a (808) 396-3319. management positions
with Network Systems
INPRISE Announces Entera 4 Integrators, Liberty
Scotts Valley, CA — Delphi, and integrates and Management Systems,
INPRISE Corp. announced automates application man- Ernst & Winney, and
the shipment of Entera 4, a agement and security services. AT&T Information
new version of the company’s Entera 4 supports the IBM Systems.
RPC-based middleware for AIX, Sun Solaris, HP-UX, He holds a Masters
corporations building large- and Windows NT platforms. degree in business admin-
scale, mission-critical, distrib- More information on Entera 4 istration and a Bachelor
uted applications. Entera 4 is available at http://www. of Arts degree from the
adds support for Java and inprise.com/entera/. University of Pittsburgh.

On the Cover
Delphi 4 / MIDAS
By Bill Todd
Delphi 4 Multi-Tier
MIDAS Reaches New Levels
U sing MIDAS components, Delphi 4 provides a host of new features for both
multi-tier and single-tier applications. It all begins with TClientDataSet; you
can now define aggregates for a ClientDataSet component. Figure 1 shows the
Multitier page of the Delphi 4 New Items dialog box.
As you already know if you’re familiar with Sum(Qty * Price)

SQL, an aggregate is the sum, minimum,
maximum, average, or count of a column in or
an answer set. In MIDAS, aggregates are
stored in the Aggregates property of Sum(TotalPrice) - Sum(TotalCost)
TClientDataSet. Aggregate expressions can
include calculations such as: Because the aggregate object’s expression is a
property, you can change it at run time. You
can also enable or disable any individual
aggregate, or all aggregates, to enhance per-
formance. A property editor for the new
Aggregates property of TClientDataSet, shown
in Figure 2, lets you quickly create aggregates
and set their properties at design time.
Figure 3 shows the Object Inspector with an

aggregate selected. Aggregates can also be
grouped on the first N fields of the active
index. To group an aggregate, set the
GroupingLevel property to the number of
index fields to group on, and set IndexName
to the index to use. Aggregates that group on
an index that isn’t active are not calculated.
Like all other datasets, TClientDataSet has a

Refresh method. Calling Refresh, however,
clears the change log so all unapplied
Figure 1: The Multitier page of the Delphi 4 New Items dialog box. changes are lost. The new RefreshRecords
On the Cover
method fetches a new set of records from the application fetched automatically, or must be specifically requested in
server and merges them with the changes in the change log code. You can also specify whether field properties, such as
as though the changes were originally made to the new Alignment, DisplayLabel, DisplayWidth, Visible, DisplayFormat,
records. If any conflicts occur, the ClientDataSet triggers an EditFormat, MaxValue, MinValue, Currency, and EditMask are
OnReconcileError event. included in the data packet.
Controlling Data Packet Contents If you’re working with tables that have a referential integrity
You now have three ways to control the contents of data relationship, you can specify that the server automatically han-
packets retrieved from the application server — including dle cascading updates and/or deletes. The Provider compo-
the ability to include custom information. Using the Fields nent’s Options property also lets you declare the dataset to be
Editor to create persistent field objects for the dataset on the read-only. This prevents the ClientDataSet from applying
application server lets you control which fields are supplied updates to the Provider. If you are working with a server that
to the client. Lookup and calculated fields will be returned may modify records with triggers when they are updated, you
to the client as read-only fields. The only restriction is that can include the poIncServerUpdates option. This tells the
you must include the primary key field(s) so each record can Provider that it must automatically retransmit all updated
be uniquely identified if the client will edit the data. records to the client, so the client will immediately see the final
state of the records — including the effects of any triggers.
TProvider has a new Options property, shown in Figure 4, that
lets you control whether BLObs and detail records will be One of the more potentially powerful new multi-tier fea-
tures is the ability to include custom information in the
data and delta packets passed between the application serv-
er and the client. This capability is implemented through a
new event, OnGetDataSetProperties, on the Provider side.
OnGetDataSetProperties passes three parameters. The first is
Sender, a pointer to the object that triggered the event. The
second, DataSet, is a pointer to the dataset that supplies
the Provider’s data.
The last, named Properties, is an OleVariant output parameter.

Properties is actually a variant array of three-element variant
Figure 2: Aggregates in the Property Editor.
Figure 4: The TProvider Options property in the

Figure 3: The properties of an aggregate. Object Inspector.

On the Cover
ResolveToDataSet set to True, TDataSetProvider
applies updates using the dataset component it’s
connected to. However, TDataSetProvider is inde-
pendent of the BDE, so it can apply updates to a
TClientDataSet or a custom dataset component
that does not use the BDE to connect to its
underlying database.
Applying updates to BDE datasets is slower

than using TProvider with ResolveToDataSet set
to False, because the updates must first be
processed by the dataset component and then
written to the database. With ResolveToDataSet
set to False, the updates are applied directly to
the database using SQL. However, the ability to
use the events of the dataset may be worth the
price in many situations.
Figure 5: An example local table application using TClientDataSet.
Building One- and Two-tier Applications
arrays. Each element in the array contains one custom proper- Building single-tier applications with TClientDataSet was a
ty that will be included in the data packet the Provider sends side effect of support for briefcase model applications in
to the client. Each element in the first array is itself a variant Delphi 3. It was interesting because there are still plenty of
array of three elements. The first element is the name of the applications that don’t require multi-user support, and do
property stored as a string. The second element is the value of not deal with huge amounts of data. So the ability to create
the property. The third element is a Boolean value that tells small, fast database applications that do not require the BDE
the ClientDataSet whether this property must be returned to was attractive. Creating these databases was laborious, how-
the Provider in the delta packet. This makes it possible for the ever, because you could not define the database structure at
Provider to not only send custom information to the design time. Creating the database had to be done with code.
ClientDataSet, but to also send a message to itself that will In Delphi 4, you can define your database at design time
come back with any changes. using the Fields Editor, and you can store multiple related
tables in a single file, thanks to the support for Oracle 8’s
On the ClientDataSet side, the new GetOptionalParam object relational database model.
method lets you retrieve the value of any optional parame-
ter from the dataset. If you’re working with a briefcase Drop a TClientDataSet on a form or data module, double-
model, or a single-tier application that saves the contents click to open the Fields Editor, press CN to add a new
of the ClientDataSet’s Data property locally using the field, and you can add as many fields of any type as you
SaveToFile method, you can still take advantage of optional need. Now when you run your application, the field objects
data packet parameters. Using the ClientDataSet’s are already defined — without code. Even more powerful is
SetOptionalParam method, you can add custom parameters the ability to add fields of type DataSet. These fields repre-
to Data in the client application and these parameters will sent a linked detail dataset. You can define as many linked
be saved to disk when you call SaveToFile. This gives you a datasets as you need; they will be stored in a single file as
very flexible way to store any information that must persist part of the Data property of the ClientDataSet component
between sessions. Adding parameters in the client applica- when you call SaveToFile.
tion is useful in another way. By setting the IncludeInDelta
member of the variant array to True, the client can send Using TClientDataSet in two-tier applications is now easier too.
information to the application server with any updates. You can drop any dataset component, a Provider component,
and a ClientDataSet component on a form or data module; set
The Events Are Back the Provider’s DataSet property and the ClientDataSet’s
One complaint of many developers using the Delphi 3 MIDAS Provider property, and your application is ready to run. While
components is that the events for the dataset components con- some of this functionality was added in the 3.02 update, you
nected to TProvider do not fire when updates are applied. Now, now have complete freedom to place the dataset, Provider, and
setting TProvider’s new ResolveToDataSet property to True causes ClientDataSet components on forms or data modules — or a
the Provider component to apply updates using the dataset com- mixture of the two — and connect them at design time.
ponent so that all of the dataset’s events work normally. Leaving
ResolveToDataSet set to False causes the provider to apply updates Figure 5 shows the main form from the sample applica-
directly to the database using SQL, just as in Delphi 3. tion, TwoTier, containing Table, Provider, and
ClientDataSet components linked to the sample Items
Another new component, TDataSetProvider, lets you table. The ResolveToDataSet property of TProvider
accomplish the same thing. Like TProvider with is set to True so updates will be applied through the
On the Cover
Table component. The Table’s BeforePost event handler gen- to the connection type. The classes for the new compo-
erates a beep and calls Abort to prevent the update from tak- nents are:
ing place, demonstrating that TTable’s events now fire. TDCOMConnection,
TCORBAConnection,
Working with Parameters TSocketConnection, and
Setting the parameters for a query or a stored procedure TOLEEnterpriseConnection
on the application server is easier in Delphi 4, thanks to
TClientDataSet’s new Params property. Using this property, Both the DCOMConnection and SocketConnection com-
you can define parameters at design time and set their val- ponents also have a new ObjectBroker property, which is a
ues, or other properties, in the Object Inspector. You can pointer to a descendant of the new TCustomObjectBroker
create parameters at run time with the CreateParams class. This allows you to implement a custom object broker
method. Each parameter is an object, so you can change that will determine the machine the client will connect to.
its Value, ParamType, Name, and DataType properties pro- The new TSimpleObjectBroker component lets you implement
grammatically at any time. automatic selection of the server the client will connect to
from a list of servers using a random assignment system to
Calling Methods on the Application Server provide load balancing among the servers.
In Delphi 3 you can add custom methods to the server
application’s interface and call those methods from the A socket server service for Windows NT has also been
client using the AppServer property of the client applica- added. With Delphi 4, it’s unnecessary to have a user
tion’s connection component. The AppServer property is a logged on to the NT machine to run SCKTSRVR.EXE; it
handle to the IDataBroker descendant interface added to runs as a service, so it starts automatically and does not
the server’s remote data module. Calls to custom methods require a user to be logged in. With the new Service wiz-
used late binding which is slower and does not provide ard (see Figure 6) you can now also write your server
compile-time error checking. application as a Windows NT service. This means you can
run an application server using sockets on an NT
In Delphi 4, you can get early binding of calls to the applica- machine, with no user logged in, to provide a much higher
tion server using DCOM or CORBA. To get early binding, level of security.
you must cast the AppServer property to the interface type of
the application server, and you must register the application Another significant addition to the sockets components is
server’s type library on the client. The following call illustrates support for callbacks. While any client has been able to call
the early binding syntax: custom methods on the application server in Delphi 3, you
could only implement callbacks from the server to the
TheConnection.( client if you used DCOM or OLE Enterprise for the con-
AppServer as IMyInterface).CustomMethod(aValue); nection protocol. Delphi 4 supports callbacks using sockets
in exactly the same way they are implemented using OLE
Although you cannot use true early binding with sockets, or Enterprise or DCOM.
OLE Enterprise, you can improve performance over late
binding by using the remote data module’s dispatch inter- Conclusion
face (dispinterface) to call server methods. The server’s Delphi 4 not only adds many new features for multi-tier
dispinterface always has the same name as the IDataBroker applications, but also adds features that make using the
descendant interface with the string “Disp”
appended. To use this method, you must add the
application server’s type library interface unit to
the uses clause in the client application. You can
then assign the AppServer property to a variable
whose type is the dispinterface, and use that vari-
able to call the server’s methods, as shown here:
var
dispinterface: IMyAppServerDisp;
begin
dispinterface := TheConnection.AppServer;
dispinterface.CustomMethod(aValue);
end;
New Connection Components and Features

Delphi 4 brings a more sensible architecture to
the MIDAS connection components by provid-
ing a specific component for each connection
type that includes only the properties applicable Figure 6: The New page of the Delphi 4 New Items dialog box.

On the Cover
MIDAS components for single- and two-tier applications
easier. You can now easily implement business rules on a
row-by-row basis, use MIDAS components in two-tier
applications as an alternative to local table transactions
and cached updates, and implement load balancing and
callbacks for sockets connections. The MIDAS compo-
nents now provide a flexible new architecture for any
database application. ∆
This article is based on a prerelease version of Delphi 4. Features

in the shipping version may differ or be absent.
Bill Todd is President of The Database Group, Inc., a database consulting and
development firm based near Phoenix, AZ. A Contributing Editor of Delphi
Informant, he is also co-author of four database programming books and a
member of Team Borland, providing technical support on the Borland Internet
newsgroups. He is a frequent speaker at Borland Developer Conferences in the
US and Europe. Bill is also a nationally known trainer, and has taught Paradox
and Delphi programming classes across the country and overseas. He was an
instructor on the 1995, 1996 and 1997 Borland/Softbite Delphi World Tours.
He can be reached at Bill_Todd@compuserve.com or (602) 802-0178.

On the ’Net
Delphi 3 / Internet Explorer 4 / DOM / HTML
By Ron Loewy
IE4’s DOM Advantage

Putting the Internet Explorer WebBrowser Control to Work
O ne of the big enhancements to Web/Windows integration was introduced

with the release of Microsoft’s Internet Explorer 3.0 (IE3). IE3 exposed an
ActiveX control named WebBrowser that can be embedded in Windows applications.
IE4 introduced Dynamic HTML (DHTML) This hierarchical object representation of an

and the Document Object Model (DOM), HTML document is the DOM. Given access
greatly expanding the amount of control a to an HTML “document,” your scripts can
Windows application can have over a Web access elements in the page, change them,
browser control. This article introduces some and have the changes reflected immediately in
ways that a Delphi application can take the browser window.
advantage of IE4’s programming interface.
Access to DHTML elements via scripts can
In Brief: DHTML and the DOM be accomplished using one of several “collec-
DHTML is an extension of HTML 3.2 that tions” published by the document object: The
provides greater programmability of HTML all collection provides access to all the tags in
pages with scripts. In DHTML, the HTML the document; the anchors collection provides
document is exposed as a hierarchical collec- access to all the <A> tags; and the scripts col-
tion of objects, where every element (usually a lection provides access to all the <SCRIPT>
tag) in the document is accessible as an object. elements in the document.
Individual items in a collection can be

accessed using a numeric index
(e.g. document.anchors(2) will access the sec-
ond link in the document), or by the ele-
ment’s name defined using the ID attribute.
For example:
<A HREF="..." ID=SecondLink>...</A>
can be accessed using

document.anchors.SecondLink; both
methods provide access to the same object.
DHTML offers many other features, such as

absolute and relative positioning, database inte-
gration, and expanded stylesheet control. My
goal in this article is not to introduce you to
DHTML — there are books devoted to that
subject; some of them are even good! With the
assumption that you know what DHTML is
and how it can be used in scripts, this article
will show how the DOM can be accessed and
Figure 1: Installing the WebBrowser control into Delphi. manipulated from a Delphi application.
On the ’Net
procedure TForm1.Button1Click(Sender: TObject); procedure TForm1.Button2Click(Sender: TObject);
var var
Flags, TargetFrameName, PostData, Headers: OleVariant; All: IHtmlElementCollection;
begin HtmlElement: IHtmlElement;
Flags := 0; i: Integer;
TargetFrameName := 0; begin
PostData := 0; Document := WebBrowser.Document as IHtmlDocument2;
Headers := 0; if (assigned(Document)) then
WebBrowser.Navigate('e:\src\homepage.html', Flags, begin
TargetFrameName, PostData, Headers); All := Document.All;
end; Memo1.Lines.Clear;
Figure 2: Navigating to view homepage.html stored on the E: drive. for i := 0 to All.length - 1 do begin
HtmlElement := All.Item(i, 0) as IHtmlElement;
if (Assigned(HtmlElement)) then
Memo1.Lines.Add(IntToStr(i) + ' ' +
HtmlElement.TagName);
end;
ShowMessage('Number of elements : ' +
IntToStr(All.Length));
end;
end;
Figure 4: Accessing the document and printing all tags to a

memo control.
In Delphi 3, you’ll need to use the Component | Import

ActiveX Controlmenu option and add the Microsoft Internet
Controls (Version 1.1) control to your component library, as
shown in Figure 1. You can now create a new project, switch
to the ActiveX Components tab in the component library,
and drop a TWebBrowser control on the form.
Figure 3: The result of the Navigate method on my
homepage.html file. The easiest way to start playing with the control is to call the
Navigate method to view a document saved on your file sys-
The DOM via COM tem. I use the code in Figure 2 to view an HTML file called
When Microsoft introduced the DOM in IE4, they provided homepage.html stored in E:\src, as shown in Figure 3.
a way to access it from external applications using standard
COM interfaces. Every HTML element in the DOM can be Accessing the DOM from Delphi
accessed using a COM interface. The hierarchy of interfaces The first step to accessing the DOM from Delphi is to
mimics the object model that can be used in scripting code. import the interfaces defined in the INetSDK.
Unfortunately, Delphi 3’s TypeLib import command cannot
If you’re not familiar with the DOM, it’s a good idea to read handle mshtml.dll where the interesting interfaces are
some of the articles or books about DHTML and the DOM, defined. You’ll need to download the 3.02 (Maintenance
and experiment with it using a scripting language, such as release 2) update from INPRISE’s Delphi updates Web page
JScript or VBScript, in your HTML code. When you (http://www.inprise.com/devsupport/delphi/downloads/
become comfortable with the DOM, take a look at the dpro302download.html) and apply it on top of version 3.01.
COM interfaces described in the Internet Client SDK One of the modules installed by this release is tlibimp.exe in
(INetSDK) and those mentioned later in this article. the \bin subdirectory of Delphi’s installation. You’ll need to
execute this program from the command line and import
The MSIE WebBrowser Control mshtml.dll to create mshtml_tlb.pas. This file includes most
When you install IE4, it registers an ActiveX control. This of the interesting interfaces you need to access the DOM.
browser control (implemented in shdocvw.dll) is a simple
wrapper around the HTML layout engine (implemented in The IHtmlDocument2 interface is your entry point into the
mshtml.dll) that provides a great way to start using IE4 in DOM. The WebBrowser control exposes this interface via
your applications. the Document property. The following code will retrieve the
interface in Delphi:
The WebBrowser control does a lot of the low-level work of
hosting an Active Document for you, but still allows you to Document := WebBrowser.Document as IHtmlDocument2;
access the DOM via COM interfaces. The INetSDK provides
documentation and samples that show how the mshtml.dll where Document has been defined as a variable of type
layout engine can be hosted directly in your application. For IHtmlDocument2.
the purpose of clarity, this article will not discuss the issues of
hosting mshtml.dll directly. All the samples and code snippets Assuming you have some content in the browser control, you
assume that you’ve installed the WebBrowser control in the can now start accessing the DOM and access the document’s
IDE, and that you use it to embed IE4 in your applications. content. The code in Figure 4 accesses the document and

On the ’Net
prints all the tags found in the content to a memo control. It An alternative method to ensure you do not access the DOM
uses the IHtmlElementCollection and IHtmlElement interfaces. before the control is ready is to define Document as a property
of type IHtmlDocument2, and to use a GetDocument read
The IHtmlDocument2 interface exposes several collections method such as the following:
you can use to access the content of the browser. This
example uses the All property to access all the tags in the function TForm1.GetDocument: IHtmlDocument2;
begin
document. You can find more information on the inter- while (WebBrowser.ReadyState <> ReadyState_Complete) do
faces exposed by IHtmlDocument2 in the INetSDK docu- Application.ProcessMessages;
mentation. Search on “IHtmlDocument2” to get the infor- Result := WebBrowser.Document as IHtmlDocument2;
end;
mation. (You’ll also notice that the All property of the
IHtmlDocument2 interface is the same as the all collection
Printing from the WebBrowser Control
of the Document object, if you are using scripting code.)
Printing is a common task you’ll want to perform from the
Figure 5 shows all the tags in homepage.html after “walk-
WebBrowser control. I prefer to read information retrieved
ing” the DOM.
from the Web on the screen, but I can assure you that your
users will want to be able to create a hard copy.
Using the WebBrowser Control Events
The WebBrowser control provides several events that can be
The browser control provides access to an IOleCommandTarget
used to track the user’s navigation. They’re also important to
interface that can be used to perform operations such as printing:
your application’s stability. The OnBeforeNavigate2 event is fired
before the control starts to navigate to a new URL after the user procedure THtmlPageEditorForm.ViewerPrint1Click(
clicks on a link in the browser display. The following code pro- Sender: TObject);
var
vides feedback that the browser is navigating to a new URL: VI, VO: OleVariant;
IECommand: IOleCommandTarget;
procedure TForm1.WebBrowserBeforeNavigate2(Sender: TObject; begin
pDisp: IDispatch; var URL, Flags, TargetFrameName, IECommand := Document as IOleCommandTarget;
PostData, Headers: OleVariant; var Cancel: WordBool); IECommand.Exec(nil, OLECMDID_PRINT,
begin OLECMDEXEOPT_DONTPROMPTUSER, VI, VO);
StatusBar1.SimpleText := 'Browser is opening ' + Url; end;
end;
Clipboard Support
The OnDocumentComplete event is used to inform your The IOleCommandTarget interface allows you to provide
application that the control finished navigating to a new copy functionality from your application. The following
URL, that it finished rendering the information, and that statement will copy the currently selected content in the
it’s safe for your application to retrieve the DOM entry browser to the Clipboard:
point via the Document property. It’s important you don’t
try to access the IHtmlDocument2 interface before the con- IECommand.Exec(nil, OLECMDID_COPY,
trol is in the ReadyState_Complete mode. Use code such OLECMDEXEOPT_DONTPROMPTUSER, VI, VO);
as the following to ensure the control is ready:

If you want to copy everything to the Clipboard, make sure
procedure TForm1.WebBrowserDocumentComplete( you select all the content before you copy it:
Sender: TObject; pDisp: IDispatch; var URL: OleVariant);
begin
IECommand.Exec(nil, OLECMDID_SELECTALL,
StatusBar1.SimpleText := 'Finished:' + Url;
OLECMDEXEOPT_DONTPROMPTUSER, VI, VO);
Document := WebBrowser.Document as IHtmlDocument2;
end;
Font Control
The WebBrowser control’s default fonts might surprise you;
an HTML document that doesn’t use stylesheets or a
<BASEFONT> tag might display differently in the
WebBrowser and IE. Apparently, there are two issues you
need to resolve in your code to set the default fonts:
You need to set the size of the font to a value between 0
and 4 (0 = smallest, 4 = largest). The values correspond to
the IE4 View | Fonts menu option. The code in Figure 6
sets the font size to 1.
To set the default font face, you need to implement the
IDocHostUIHandler interface. Unfortunately, I couldn’t
find a way to import this interface into Delphi; you’ll
have to translate it from C manually.
Figure 5: All the tags in the homepage.html file after “walking” In your IDocHostUIHandler, you need to implement the
the DOM. GetOptionKeyPath method and provide the registry path of
On the ’Net
procedure TForm1.Button3Click(Sender: TObject); procedure TForm1.MemLoadClick(Sender: TObject);
var var
IECommand: IOleCommandTarget; v: Variant;
V, O: OleVariant; begin
const if (assigned(Document)) then
OLECMDEXEOPT_DONTPROMPTUSER = 2; begin
begin v := VarArrayCreate([0, 0], varVariant);
V := 1; v[0] := '<html><head><title>Hello World</title>' +
IECommand := WebBrowser.Document as IOleCommandTarget; '</head><body>Start me up</body></html>';
IECommand.Exec(nil, OLECMDID_ZOOM, Document.Write(PSafeArray(TVarData(v).VArray));
OLECMDEXEOPT_DONTPROMPTUSER, V, O); Document.Close;
end; end;
end;
Figure 6: This code sets the font size to 1.
Figure 7: Using IHtmlDocument’s write and close methods to
write content directly from memory.
your browser defaults. The default font values should be writ-
ten under the International\CodePage key (where CodePage is
the code page Windows uses) in the IEPropFontName and
If you look at mshtml_tlb.pas, which was created when you
IEFixedFontName entries.
imported the TypeLib of mshtml.dll, you’ll see a dispatch
interface named HtmlDocumentEvents. To hook this events
Speeding up the WebBrowser
interface, you need to use the IConnectionPointContainer and
In my application, I need to provide fast updates to the con-
IConnectionPoint interfaces to connect the DOM entry point
tent of the page displayed by the browser control. The
to an object that implements HtmlDocumentEvents.
WebBrowser control’s functionality allows it to host Java
applets and ActiveX controls, handle style sheets, and execute
The method of connecting events using connection points
scripts. Unfortunately, all this functionality comes at a cost —
is beyond the scope of this article, but you can simply copy
speed. To speed the preview portion of my application, I need
the procedures InterfaceConnect and InterfaceDisconnect
to extract every bit of performance from the control.
that INPRISE includes as part of OleCtrls.pas in the
Source\VCL directory.
Instead of writing every change to the displayed page content
to a disk file and using the Navigate method, I use the
I used Delphi’s Automation Object Wizard to create a
IHtmlDocument interface’s write and close methods to write
TAutoObject descendant that implements the
the content directly from memory. The code in Figure 7
HtmlDocumentEvents interface (see Figure 8). Because this
demonstrates how this can be done.
is a dispatch interface, I used Delphi’s TypeLib Editor to
copy the dispatch IDs to the automation object I was cre-
It seems that Microsoft did not implement all the functionality
ating. The result is displayed in Figure 9.
of the Navigate method in write and close. For example, your font
defaults implemented using IDocHostUIHandler will be ignored.
My automation object implements the OnClick handler using
Another problem with close is that the OnDocumentComplete
the following code:
event is not fired. Instead, I use a Timer component, set it to 100
milliseconds, and use the following code to set the font size after function THtmlDocumentEventsHandler.OnClick: WordBool;
the document has been loaded into the control: begin
showMessage('Hello World!');
Result := True;
procedure THtmlPageEditorForm.Timer1Timer(Sender: TObject);
end;
begin
inherited;
if (WebBrowser.ReadyState = ReadyState_Complete) then
begin
Timer1.Enabled := False;
ZoomFont;
end;
end;
ZoomFont implements the font size code I just described. My

application can sometimes update the displayed page’s source code
several times before the control finishes the rendering of the last
update. I use a virtual semaphore to signal that the control is busy
and queue several changes into one rendering operation. The
ReadyState property should be your guide for this functionality.
Hooking into the DOM Event Model

The DOM allows you to hook into events that can be hooked in
scripting code, such as the Onclick, Onmouseover, and
Onmouseexit events you can handle in JScript or VBScript. Figure 8: Select File | New to create an automation object.

On the ’Net
IHtmlDocumentEventsHandlerDisp = dispinterface COM interfaces and incomplete documentation. The IE
['{ 016B5321-631C-11D1-A5E6-0040053BA735 }'] WebBrowser control is a very powerful tool for Internet-
function onhelp: WordBool; dispid -2147418102;
aware applications, and can be used to create non-traditional
function onclick: WordBool; dispid -600;
function ondblclick: WordBool; dispid -601; Internet applications.
procedure onkeydown; dispid -602;
procedure onkeyup; dispid -604;
function onkeypress: WordBool; dispid -603;
An example of a non-browser application I wish I had the
procedure onmousedown; dispid -605; time to write is an adventure game like the Ultima games.
procedure onmousemove; dispid -606; Instead of using complex graphic code to implement the
procedure onmouseup; dispid -607;
procedure onmouseout; dispid -2147418103; graphics and the game logic engine, you can use your favorite
procedure onmouseover; dispid -2147418104; HTML editor and graphic editor to easily create “rooms” in
procedure onreadystatechange; dispid -609;
the adventure, and apply the logic that takes the user in the
function onbeforeupdate: WordBool; dispid -2147418108;
procedure onafterupdate; dispid -2147418107; maze using Delphi code. I’m sure you’ll be able to think of
function onrowexit: WordBool; dispid -2147418106; other uses for the browser control. ∆
procedure onrowenter; dispid -2147418105;
function ondragstart: WordBool; dispid -2147418101;
function onselectstart: WordBool; dispid -2147418100;
function onerrorupdate: WordBool; dispid -2147418099;
end;
Figure 9: The result of using Delphi’s TypeLib Editor to copy dis-

patch IDs to an automation object. Ron Loewy is a software developer for HyperAct, Inc. He is the lead developer of
eAuthor Help, HyperAct’s HTML Help-authoring tool. For more information about
The code returns True, which tells the document object HyperAct and eAuthor Help, contact HyperAct at (515) 987-2910 or visit
http://www.hyperact.com.
model not to bubble the event; this will ensure the default
behavior of a click event will be carried. If we wanted to elim-
inate this behavior, we would have returned False; clicks on
links would be ignored.
Now comes the fun part. This statement connects the event
handler object to the document object model:
InterfaceConnect(Document, HtmlDocumentEvents,
DocHandler, DocConnectionID);
where Document is the IHtmlDocument2 instance, and

DocConnectionID is an integer variable used to keep tabs on the
connections performed. DocHandler is the TAutoObject descen-
dant instance that implements the HtmlDocumentEvents dis-
patch interface. When we’re done with the document, we must
disconnect from the event model using the following code:
InterfaceDisconnect(Document, HtmlDocumentEvents,
DocConnectionID);
Wrapping It Up
You should install the INetSDK, and acknowledge that a
large portion of your time will be spent reading the docu-
mentation, looking at the samples, and wondering why no
one documented the function you are interested in.
The following Usenet groups are some of the best places to

find information and ask questions about the DOM — and
how to handle it from Delphi:
borland.public.delphi.activex.controls.using
borland.public.delphi.internet
borland.public.delphi.oleautomation
microsoft.public.inetsdk.programming.html_objmodel
microsoft.public.inetsdk.programming.mshtml_hosting
microsoft.public.inetsdk.programming.webbrowser_ctl
As you can see, a lot can be done with IE4 from a Windows
application if you are willing to get down and dirty with
Algorithms
Delphi / 3-D Graphics
By Rod Stephens
Vivid Equations
An Introduction to 3-D Graphics Programming
T hree-dimensional graphics is a complicated subject. Entire books have been

written about generating three-dimensional images. There are even books
about software that generates three-dimensional images.
While you could spend years studying the To transform an object, a program trans-
topic, much of three-dimensional graphics is forms the points that define that object. It
based on fairly simple mathematics. This then connects the transformed points as
article describes the equations that are the they are connected in the original object
basis for three-dimensional graphics pro- using straight lines. For example, to trans-
gramming. It also shows how to use those form a rectangle, the program transforms
equations to draw simple three-dimensional the four corners of the rectangle, and then
objects and surfaces. connects them.
Transformations Translation and scaling transformations are

Transformations occur when computer straightforward. Translating the point (x, y, z)
operations take an object and transform it by the offset (tx, ty, tz) gives the point (x +
in some way. The most important transfor- tx, y + ty, z + tz). The point is moved dis-
mations in three-dimensional graphics are tance tx in the X direction, ty in the Y direc-
translation, scaling, projection, and rotation, and tz in the Z direction.
tion. Each of these modifies the coordi-
nates of a point in a different way. For Scaling or stretching by factors of (sx, sy, sz)
example, translation moves a point in gives the point (x * sx, y * sy, z * sz). The
three-dimensional space. new point lies sx times as far from the origin
as the old point in the X direction. Similarly,
Translation, scaling, projection, and rotation it lies sy times farther in the Y direction and
all preserve straight lines. After any combi- sz times farther in the Z direction.
nation of these transformations, a straight
line will still be straight. This is important A projection maps a point in a particular
because it allows a program to quickly trans- dimension into a lower dimensional space.
form and display complex objects. Usually, this means mapping a three-
Algorithms
dimensional point into a two-dimensional space so the point These equations show how to rotate a point around the
can be displayed on a two-dimensional computer monitor. origin. To rotate a point around another point, the pro-
gram can translate the point of rotation to the origin,
The simplest kind of projection is a parallel projection that rotate around the origin, and translate the point of rota-
projects a point onto the X-Y plane by ignoring the point’s Z tion back to its original position. This allows the
coordinate. The point (x, y, z) in three dimensions is trans- program to treat one complicated rotation as a simple
formed into the point (x, y) in two dimensions. To create translation, followed by a simple rotation, followed by
different parallel projections, the program can translate, another simple translation.
scale, and rotate points before applying the simple projection
onto the X-Y plane. In two dimensions, a program rotates a point around another
point. In three dimensions, it rotates a point around a line.
In practice, graphics programs often do not actually set a Rotating a point around a general line would be difficult to ana-
point’s Z coordinate to zero. Instead, they simply ignore the lyze directly. Rotating around one of the coordinate axes, howev-
Z coordinate when drawing the point. er, is straightforward. For example, when a program rotates a
point around the Z axis, the point’s X and Y coordinates change,
Rotation but its Z coordinate value is unchanged. The program can sim-
Rotation is a little more complex than translation, scaling, and ply treat the point as if it were rotating around the origin in the
projection. The simplest case is rotating a point around the ori- X-Y plane, and leave the point’s Z coordinate alone.
gin in two dimensions, as shown in Figure 1. Here the point
(x, y) lies distance R = Sqrt(x * x + y * y) from the origin. Similarly, a program can treat rotation around the X or Y axis
as rotation around the origin in the Y-Z or X-Z plane.
The line from the point to the origin makes some angle
a with the X axis, by the definition of the sine and Rotating around lines other than the origins requires more
cosine functions: steps, but is conceptually simple. Instead of calculating equa-
tions to rotate around the line directly, the program can build
x = R * Cos(a) the rotation out of simpler steps.
y = R * Sin(a)
First, the program translates the points so the line of rota-
Now suppose the point is rotated by angle q around the ori- tion intersects the origin. Next, it rotates around the Z
gin. The distance R from the point to the origin is unchanged, axis until the line lies in the Y-Z plane. It then rotates
so the point’s new coordinates (x’, y’) are given by: around the X axis until the line coincides with the Z axis.
Now, the program can rotate around the line by rotating
x’ = R * Cos(a + q) around the Z axis. The program finishes by reversing the
y’ = R * Sin(a + q) rotations, and translation is used to make the line of rota-
tion lie in the Z axis.
These equations can be rewritten using the equations:
Homogeneous Coordinates
Cos(a + q) = Cos(a) * Cos(q) - Sin(a) * Sin(q) Each of these transformations is understandable individually,
Sin(a + q) = Sin(a) * Cos(q) + Cos(a) * Sin(q) but combining them is difficult. Translation adds values to a
point’s coordinates, scaling multiplies; rotation uses a combi-
Making these substitutions gives: nation of more than one of the point’s coordinates multiplied
x’ = R * [Cos(a) * Cos(q) - Sin(a) * Sin(q)]

y’ = R * [Sin(a) * Cos(q) + Cos(a) * Sin(q)]
Recall that the point’s original coordinates were given by:
x = R * Cos(a)
y = R * Sin(a)
Then, substituting these values into the new equations gives:
x’ = x * Cos(q) - y * Sin(q)
y’ = y * Cos(q) + x * Sin(q)
The value q is the angle through which the point should be

rotated. If the program knows q, it can use these equations to
calculate the point’s new coordinates. Figure 1: Rotating a point (x, y) through the angle ?.

Algorithms
and added in a complex way. Combining the equations for a 1 0 0 0
more general transformation would be hard. 0 1 0 0
0 0 0 0
Homogeneous coordinates allow a program to treat all of these 0 0 0 1
transformations in a uniform (homogeneous) way. They allow a
program to combine any number of transformations easily. Multiply this matrix by the vector [a, b, c, s] and the resulting
vector [a, b, 0, s] has Z coordinate zero. As mentioned, most
In a three-dimensional homogeneous coordinate system, a programs don’t bother to perform this multiplication. Instead,
point is represented by a vector of four values [a, b, c, s]. The they simply ignore the points’ Z coordinates when drawing.
fourth value is a scaling factor. The first three values are the
point’s coordinates, multiplied by the scaling factor. For exam- Finally, rotation though the angle q around the Z axis in the X-
ple, the following vectors all represent the point (1, 2, 3): Y plane is represented by:
[1, 2, 3, 1] Cos(q) Sin(q) 0 0

[10, 20, 30, 10] -Sin(q) Cos(q) 0 0
[1.5, 3, 4.5, 1.5] 0 0 1 0
0 0 0 1
A vector is called normalized when its scaling factor is 1. A
program can normalize a vector by dividing each of its com- Multiplying the vector [a, b, c, s] by this matrix gives:
ponents by the scaling factor.
[a * Cos(q) - b * Sin(q), a * Sin(q) + b * Cos(q), c, s]
Transformations are represented by 4 x 4 matrices. To apply a
transformation to a point, a program multiplies the point’s vector This result agrees with the equations for rotation around the
by the transformation matrix. The identity transformation, which origin in two dimensions, as shown earlier.
leaves a point unchanged, is represented by the identity matrix:
Similarly, the matrix representing rotation around the X axis is:
1 0 0 0
0 1 0 0 1 0 0 0
0 0 1 0 0 Cos(q) Sin(q) 0
0 0 0 1 0 -Sin(q) Cos(q) 0
0 0 0 1
If you multiply this matrix by the vector [a, b, c, s], you get
[a, b, c, s], so the point is unchanged. and the matrix representing rotation around the Y axis is:
Translation by a distance of (tx, ty, tz) is represented by the matrix: Cos(q) 0 Sin(q) 0
0 1 0 0
-Sin(q) 0 Cos(q) 0
1 0 0 0
0 0 0 1
0 1 0 0
0 0 1 0
One of the nice things about these transformation matrices is
tx ty tz 1
that the product of two matrices represents the transforma-
tions applied one after each other. For example, if A and B
If you multiply this matrix by the point [a, b, c, s], you get:
are transformation matrices, and p is a vector, then:
1 0 0 0 (p * A) * B = p * (A * B)
[a, b, c, s] * 0 1 0 0 = [a + 1 * tx, b + 1 * ty, c + 1 * tz, s]
0 0 1 0 This means a program can multiply the matrices together
tx ty tz 1 first, and then apply the result to the point later.
This vector correctly represents the translation of the point. If the program is transforming a single point, this is no faster
Scaling by factors of sx, sy, and sz is represented by the matrix: than applying the matrices to the point one at a time. However,
if the program must transform hundreds or thousands of points,
sx 0 0 0 it can mean a large savings. Instead of applying both matrices to
0 sy 0 0 each point, the program need only apply the combined transfor-
0 0 sz 0 mation to each point. For more complex transformations involv-
0 0 0 1 ing many rotations and translations, the savings are even greater.
If you multiply this matrix by the vector [a, b, c, s], you get Drawing in Delphi
[a * sx, b * sy, c * sz, s], as desired. Projection along the Z Enough math! How can you use all this to draw three-
axis onto the X-Y plane is represented by: dimensional pictures in Delphi? One straightforward
Algorithms
method is to create an array of points representing the end this approach to draw the Platonic solids: tetrahedron,
points of line segments. The program transforms the cube, octahedron, dodecahedron, and icosahedron. It
points, and then connects them on the screen. defines the record type Point3D to hold a point’s original
and transformed coordinates:
The example program Platonic, shown in Figure 2 (and
available for download; see end of article for details), uses TPoint3D = record
Coord: TVector3D; // The untransformed coordinates.
Trans: TVector3D; // The transformed coordinates.
end;
The program declares a Segments array to contain the seg-

ments it will draw. The variable NumSegments records the
number of segments used:
Segments : array [0..1000, 1..2] of

TPoint3D;
NumSegments : Integer;
The Segment array’s first dimension gives a segment number.

The second gives the start and end points for a segment. For
Figure 2: The example program Platonic displaying a dodecahedron. // Build a transformation matrix for display.
procedure TPlatonicForm.BuildTransformation(
var T: TMatrix3D);
// Make M an identity matrix. var
procedure TPlatonicForm.MakeIdentity(var M: TMatrix3D); r1, r2, ctheta, stheta, cphi, sphi: Single;
var T1, T2, T3, T4, T12, T34: TMatrix3D;
i, j: Integer; begin
begin // Rotate around the Z axis until the eye lies in
for i := 1 to 4 do // the Y-Z plane.
for j := 1 to 4 do r1 := Sqrt(EyeX * EyeX + EyeY * EyeY);
if (i = j) then stheta := EyeX / r1;
M[i, j] := 1.0 ctheta := EyeY / r1;
else MakeIdentity(T1);
M[i, j] := 0.0; T1[1, 1] := ctheta;
end; T1[1, 2] := stheta;
T1[2, 1] := -stheta;
// Perform matrix-matrix multiplication. Set R = A * B. T1[2, 2] := ctheta;
procedure TPlatonicForm.MatrixMatrixMult(var R: TMatrix3D;
A, B: TMatrix3D); // Rotate around the X axis until the eye lies within
var // the Z axis.
i, j, k: Integer; r2 := Sqrt(EyeX * EyeX + EyeY * EyeY + EyeZ * EyeZ);
value: Single; sphi := -r1 / r2;
begin cphi := -EyeZ / r2;
for i := 1 to 4 do MakeIdentity(T2);
for j := 1 to 4 do begin T2[2, 2] := cphi;
// Calculate R[i, j]. T2[2, 3] := sphi;
value := 0.0; T2[3, 2] := -sphi;
for k := 1 to 4 do T2[3, 3] := cphi;
value := value + A[i, k] * B[k, j];
R[i, j] := value; // We could project along the Z axis here. Instead we
end; // just ignore the Z coordinate when drawing.
end;
// Make the picture reasonably large on the form.
// Perform vector-matrix multiplication. Set r = p * A. // Here we scale y by -50 to reverse its sign since
procedure TPlatonicForm.VectorMatrixMult(var r: TVector3D; // the Canvas starts with (0, 0) in the upper left.
p: TVector3D; A: TMatrix3D); MakeIdentity(T3);
var T3[1, 1] := 50;
i, j: Integer; T3[2, 2] := -50;
value: Single; T3[3, 3] := 50;
begin
for i := 1 to 4 do begin // Center the picture on the form.
value := 0.0; MakeIdentity(T4);
for j := 1 to 4 do r1 := SolidOption.Width + SolidOption.Left;
value := value + p[j] * A[j, i]; T4[4, 1] := (ClientWidth - r1) / 2 + r1;
r[i] := value; T4[4, 2] := ClientHeight / 2;
end;
// Combine the transformations.
// Normalize the point. Note value still holds r[4]. MatrixMatrixMult(T12, T1, T2);
r[1] := r[1] / value; MatrixMatrixMult(T34, T3, T4);
r[2] := r[2] / value; MatrixMatrixMult(T, T12, T34);
r[3] := r[3] / value; end;
r[4] := 1.0;
end;
Figure 4: BuildTransformation creates a transformation matrix for
Figure 3: Matrix and point manipulation procedures. viewing from point (EyeX, EyeY, EyeZ ) looking toward the origin.

Algorithms
example, the first line segment connects points Segments[0, // Draw the selected solid.
1] and Segments[0, 2]. procedure TPlatonicForm.FormPaint(Sender: TObject);
var
i, seg1, seg2: Integer;
When it starts, Platonic loads data into the Segments array. T: TMatrix3D;
rect: TRect;
FirstSegment is an array of integers indicating the indexes of begin
the first segment that belong in each Platonic solid. For // Build the transformation.
BuildTransformation(T);
example, FirstSegment[1] gives the index in the Segments
array of the first segment used to draw the tetrahedron. // Erase the form.
rect.Left := 0;
Figure 3 shows matrix and point manipulation routines rect.Top := 0;
used by the program. rect.Right := ClientWidth;
rect.Bottom := ClientHeight;
Canvas.Brush.Color := Color;
The procedure BuildTransformation, shown in Figure 4, cre- Canvas.FillRect(rect);
ates a transformation matrix for projecting the data. This // Draw the selected solid's segments.
transformation acts as if it were viewing the data from the Canvas.Pen.Color := clBlack;
i := SolidOption.ItemIndex + 1;
point (EyeX, EyeY, EyeZ ) and looking toward the origin. The seg1 := FirstSegment[i];
procedure applies rotations until the eye coordinates lie in the seg2 := FirstSegment[i + 1] - 1;
for i := seg1 to seg2 do begin
Z axis, and then it projects onto the X-Y plane. It also adds a // Apply the transformation to the points.
scaling and a translation to make the result fit nicely in the VectorMatrixMult(Segments[i, 1].Trans,
Segments[i, 1].Coord, T);
form’s pixel coordinate system.
VectorMatrixMult(Segments[i, 2].Trans,
When the program receives a Paint event, it calls // Draw the segment.
BuildTransformation. It applies the transformation to the seg- Canvas.MoveTo(Round(Segments[i, 1].Trans[1]),
ments that make up the selected solid. It then draws lines Round(Segments[i, 1].Trans[2]));
Canvas.LineTo(Round(Segments[i, 2].Trans[1]),
between the transformed points. It repeats these steps for the Round(Segments[i, 2].Trans[2]));
three segments that represent the coordinate axis if the pro- end;
gram’s Show Axes box is checked. Figure 5 shows the pro- // Draw the axes if desired.
gram’s Paint event handler. if (ShowAxesCheck.Checked) then
begin
Canvas.Pen.Color := clGreen;
On the Surface for i := FirstSegment[0] to FirstSegment[1] - 1 do
begin
The example program Platonic stores both end points for // Apply the transformation to the points.
each of the segments it draws. This wastes a little space VectorMatrixMult(Segments[i, 1].Trans,
since each of the segments in a Platonic solid connect to at VectorMatrixMult(Segments[i, 2].Trans,
least two others. For example, each corner of a cube is Segments[i, 2].Coord, T);
shared by three edges. For small data sets like this one, the // Draw the segments.
waste is not terribly important. Canvas.MoveTo(Round(Segments[i, 1].Trans[1]),
Round(Segments[i, 1].Trans[2]));
Canvas.LineTo(Round(Segments[i, 2].Trans[1]),
The Surface example program, shown in Figure 6, stores Round(Segments[i, 2].Trans[2]));
end;
the coordinates of each point for an array of X and Y val- end;
ues. This allows it to transform each point only once. end;
Figure 7 shows how the program transforms the data and Figure 5: When it receives a Paint event, the example program
draws the surface. Platonic builds a transformation matrix, transforms its data points,
and then draws the segments that make up the selected solid.
Below the Surface

If you look closely at Figure 6, you will see parts of the
surface overlapping each other. This picture shows the sur-
face at a high enough angle that the overlap is not a big
problem. On the other hand, when viewed closer to edge
on, the picture becomes hopelessly cluttered. Removing
hidden surfaces would make the image easier to under-
stand, but hidden-surface removal in general is a difficult
problem. For surfaces like this one, however, a special
algorithm lets a program remove the hidden surfaces from
the picture quickly and easily.
The program simply draws in order the rectangles that make

up the surface, drawing the rectangles farthest from the eye
coordinates (EyeX, EyeY, EyeZ ) first. As each rectangle is drawn,
it is filled with a surface color. This erases any previously drawn Figure 6: The example program Surface displaying a surface.

Algorithms
rectangles that should be hidden by the new one. As long as
the rectangles are drawn in order from farthest to nearest, the
newer rectangles erase the old ones that should be hidden.
The example program Hidden, shown in Figure 8, uses this

method to display the same surface drawn by the example
program Surface. The programs are very similar. The only
difference is in how the programs draw the surface. The code
used by Hidden, shown in Figure 9, does not actually sort the
rectangles. It simply draws them ordered by their X and Y
coordinates. If you rotate the image displayed by the program
until that ordering is incorrect, you will see parts of rectangles
overlapping other rectangles.
// Draw the surface.

Figure 8: The example program Hidden displaying a surface
procedure TSurfaceForm.FormPaint(Sender: TObject); with hidden surfaces removed.
var
x, y: Integer;
T: TMatrix3D; // Draw the surface.
procedure THiddenForm.FormPaint(Sender: TObject);
rect: TRect;
var
begin
x, y: Integer;
// Build the transformation.
T: TMatrix3D;
rect: TRect;
begin
// Apply the transformation to the points.
// Build the transformation.
for x := Xmin to Xmax do
for y := Ymin to Ymax do
VectorMatrixMult(Points[x, y].Trans,
// Apply the transformation to the points.
Points[x, y].Coord, T);
for x := Xmin to Xmax do
for y := Ymin to Ymax do
// Erase the form.
VectorMatrixMult(Points[x, y].Trans,
rect.Left := 0;
Points[x, y].Coord, T);
rect.Top := 0;
rect.Right := ClientWidth;
// Erase the form.
rect.Left := 0;
rect.Top := 0;
Canvas.FillRect(rect);
rect.Right := ClientWidth;
// Draw the lines that are parallel to the X axis.
Canvas.Pen.Color := clBlack;
Canvas.FillRect(rect);
for x := Xmin to Xmax do begin
Canvas.MoveTo(Round(Points[x, Ymin].Trans[1]),
// Draw the tiles that make up the surface.
Round(Points[x, Ymin].Trans[2]));
Canvas.Pen.Color := clBlack;
for y := Ymin + 1 to Ymax do
Canvas.Brush.Color := clWhite;
Canvas.LineTo(Round(Points[x, y].Trans[1]),
for x := Xmin to Xmax - 1 do begin
Round(Points[x, y].Trans[2]));
for y := Ymin to Ymax - 1 do begin
end; Canvas.Polygon([
Point(Round(Points[x , y ].Trans[1]),
// Draw the lines that are parallel to the Y axis. Round(Points[x , y ].Trans[2])),
for y := Ymin to Ymax do begin Point(Round(Points[x + 1, y ].Trans[1]),
Canvas.MoveTo(Round(Points[Xmin, y].Trans[1]), Round(Points[x + 1, y ].Trans[2])),
Round(Points[Xmin, y].Trans[2])); Point(Round(Points[x + 1, y + 1 ].Trans[1]),
for x := Xmin + 1 to Xmax do Round(Points[x + 1, y + 1].Trans[2])),
Canvas.LineTo(Round(Points[x, y].Trans[1]), Point(Round(Points[x , y + 1 ].Trans[1]),
Round(Points[x, y].Trans[2])); Round(Points[x , y + 1 ].Trans[2])) ]);
end; end;
end;
// Transform the origin.
VectorMatrixMult(Axes[0].Trans, Axes[0].Coord, T); // Transform the origin.
VectorMatrixMult(Axes[0].Trans, Axes[0].Coord, T);
// Transform and draw the axes.
Canvas.Pen.Color := clGreen; // Transform and draw the axes.
for x := 1 to 3 do begin Canvas.Pen.Color := clGreen;
VectorMatrixMult(Axes[x].Trans, Axes[x].Coord, T); for x := 1 to 3 do begin
Canvas.MoveTo(Round(Axes[0].Trans[1]), VectorMatrixMult(Axes[x].Trans, Axes[x].Coord, T);
Round(Axes[0].Trans[2])); Canvas.MoveTo(Round(Axes[0].Trans[1]),
Canvas.LineTo(Round(Axes[x].Trans[1]), Round(Axes[0].Trans[2]));
Round(Axes[x].Trans[2])); Canvas.LineTo(Round(Axes[x].Trans[1]),
end; Round(Axes[x].Trans[2]));
end; end;
end;
Figure 7: The example program Surface uses this code to trans-
form and display a surface. Figure 9: Hidden’s Paint event handler.

Algorithms
Conclusion
This is far from the end of the three-dimensional graphics story.
More advanced topics include more general hidden-surface
removal, shadows, color smoothing, transparency, reflectivity,
ambient lighting, and a host of other subjects. Using the tech-
niques described here, however, you can take your first steps into
the world of three-dimensional graphics. ∆
The files referenced in this article are available on the Delphi

Informant Works CD located in INFORM\98\AUG\DI9808RS.
Rod is the author of such programming classics as Visual Basic Graphics Programming
[John Wiley & Sons, 1997] and Ready-to-Run Delphi 3.0 Algorithms [John Wiley &
Sons, 1998]. He also writes algorithm columns in Visual Basic Developer and
Microsoft Office & Visual Basic for Applications Developer. You can find pictures creat-
ed using 3-D graphics techniques at his Web site (http://www.vb-helper.com). You can
reach Rod via e-mail at RodStephens@vb-helper.com.

DBNavigator
Delphi / Database Development / Borland Database Engine
By Cary Jensen, Ph.D.
Delphi Database Development

The BDE and the Components of
RAD Database Development
I have been writing this column in Delphi Informant since the premiere issue.
In that time, I have had the opportunity to cover a wide range of topics, from
creating local database names using the Database component (the very first
article), to cached updates; from OLE Automation to RTTI; from Code Insight to
QuickReports. In fact, in recent months I have wondered if the column title,
“DBNavigator,” continues to be appropriate.
I’ve decided to keep the “DBNavigator” of the role played by many of the most com-
name. Furthermore, with this issue, I am mon components used for data access.
beginning a series of columns focused on
database-related issues. This month’s column The BDE
begins with an overall introduction to data- Delphi provides you with access to your data
base development with Delphi. In coming using the BDE. From time to time, you’ll also
months, I will revisit and re-examine some see the BDE referred to as IDAPI (Integrated
topics I’ve covered in the past, as well as Database Application Programming Interface).
introduce new database-related topics I have
not yet had the opportunity to discuss. The BDE is a common data access layer for
all of INPRISE’s products, including Delphi,
While I still retain the right, and the desire, C++Builder, and JBuilder (through
to cover issues that extend beyond the DataGateway). Several Corel products,
realm of database development, I think the including Paradox 8 for Windows and
timing is right for an extended look at data- Quattro Pro, also use it. In addition, by
base applications. Over the past year, I have default, database applications written with
encountered numerous developers who are these products use the BDE. In other words,
new to Delphi, coming from languages Delphi uses the BDE, as well as those data-
such as Visual Basic, Clipper, and base applications you write with Delphi.
PowerBuilder. Consequently, although there
are many Delphi developers who are com- The BDE consists of a collection of DLLs.
pletely comfortable with the issues sur- Consequently, one installation of the BDE can
rounding database development, there is a be used by two or more BDE-aware applica-
growing number of programmers who are tions simultaneously. As a result, each individ-
new to these issues. ual Delphi application is smaller in size than it
would be if all data-accessing code needed to
Overview of Delphi Database Development be linked into the executable. Furthermore,
Delphi is not only a great language, it’s an because two or more applications can share
exceptional database development environ- the same copy of the BDE loaded into memo-
ment. This month, we begin with a general ry, overall RAM usage is reduced when two or
overview of the heart of database develop- more BDE-aware applications are running
ment in Delphi, the Borland Database Engine simultaneously (when compared to linking the
(BDE). We then continue with a discussion code into each .EXE).
DBNavigator
The purpose of the BDE is to insulate you from the mun- Finally, the BDE also supports access to any file type for
dane tasks of data access. These include table and record which there exists an ODBC driver. ODBC is a Microsoft
locking, SQL construction, record updates, and basic I/O, standard for accessing databases, and is based on the Open
just to mention a few. The BDE permits you to concentrate SQL CLI (call level interface). To use one of these drivers,
on what data you want to access, instead of how to access it. it must be installed and configured (using the ODBC 32-
Because of the BDE, your Delphi applications can just as eas- bit Administrator, available on the Control Panel).
ily use data in dBASE or Paradox tables, files on a remote
database server, and files supported by ODBC (Open Following are some of the benefits provided by the BDE:
DataBase Connectivity) drivers. It provides seamless access to any data source, whether
it’s Paradox, dBASE, InterBase, Oracle, Sybase,
The BDE API consists of approximately 200 procedures and Informix, Microsoft SQL Server, or data accessed
functions, all of which are available through the BDE unit. through ODBC drivers.
Fortunately, you almost never need to call any of these rou- It provides the basic data engine for all your applica-
tines directly. Instead, you use the BDE through Delphi’s tions. Your clients only need one copy of the BDE on
data access components, which are found on the Data Access their systems, and this can be accessed by all the appli-
page of the Component palette. These components encapsu- cations you write.
late calls to the BDE API, providing you with a much sim- It creates an OS (operating system)-independent layer for
pler interface. However, if you have special data needs not all your applications. The BDE manages all file I/O, net-
provided by these components, you can use the BDE API work access, and memory management for data access.
directly. It provides enhanced performance with BLOB (Binary
Large Object) data through caching services.
The relationship between Delphi (and other applications), It includes internal support for language drivers, provid-
the BDE, and underlying files is depicted in Figure 1. As you ing you with an easier path to creating applications for
can see, the BDE is a software layout that lies between BDE- the international market.
aware applications (Delphi and the database applications you It performs data translation between various data sources.
create with it) and the sources of your data. It also shows that It includes a SQL generator. Data requests, other than
the BDE can access local tables directly, such as Paradox and pass-through SQL, are translated into a common local
dBASE. Connecting to Microsoft Access or FoxPro tables SQL, which is a subset of ANSI92 SQL. Using the
requires that you have the Microsoft DAO (Data Access Borland SQL Links for Windows, these can be translated
Objects) DLLs installed. into the appropriate dialect of SQL, based on the SQL
driver to which the BDE is sending its data requests.
Connection to other data sources requires additional dri- It offers access to data stored in formats supported by
vers. For the best performance in connecting to a remote your installed ODBC drivers.
database server, such as Oracle, Microsoft SQL Server,
InterBase, and so forth, use Borland SQL Links drivers. One of the most important benefits provided by the BDE
These native language drivers are provided in the Delphi is that your Delphi applications don’t need to be written
Client/Server and Delphi Enterprise editions. In addition, to a particular database standard. Specifically, use the
SQL Links drivers must use an additional network protocol same, simple interface provided by data access components
to connect to the remote server. to access your data. Even if later you need to change the
underlying data type (e.g. from Paradox
to InterBase, or Microsoft SQL Server to
Oracle Server), your applications don’t
necessarily need to be recompiled. The
description of where to find the data,
and how to access the data, can be con-
figured outside your applications using
the BDE Administrator.
Understanding the BDE Administrator

You can define where your data is locat-
ed, and which driver to use to access it,
using the BDE Administrator. This pro-
gram can be accessed from the Delphi 3
folder, but it also appears on the
Control Panel.
The BDE Administrator consists of two

panes. The left pane has two pages. The
Figure 1: The relationship between BDE-aware applications, the BDE, and data sources. Databases page (see Figure 2) displays
DBNavigator
assigned to the DatabaseName property of the
DataSet component being used for the access), a
developer doesn’t need to know the physical loca-
tion of the table.
To create a new alias, right-click on Databases in

the Databases page and select New. From the New
Database Alias dialog box, select the driver that
corresponds to the type of data being accessed. For
local tables, including Paradox, dBASE, and
ASCII, select STANDARD. Otherwise, select one of
the other types available from the Database Driver
Name drop-down combo box.
Figure 2: The BDE Administrator. The BDE Administrator will generate a default
name for the driver. Select the driver in the
Databases page and enter the name you want to
use for the driver. Then, enter the appropriate
parameters for the new alias in the Definition page.
To change a given alias, select it in the Databases

page. To change the alias name, click on the cur-
rent name until it appears as an editable field. To
change parameters, select the name, and then mod-
ify the parameters in the Definition page.
To delete a global alias, select it in the Databases

page, right-click, and select Delete. You cannot
delete an alias when it is open. (An alias is open
when a green box appears surrounding the bitmap
to the left of the alias.) To close an alias, select it,
right-click, and select Close.
Configuring Drivers
Figure 3: The Configuration page of the BDE Administrator. Drivers are configured from the Configuration
page of the BDE Administrator. To change a particular dri-
aliases, and the Configuration page (see Figure 3) displays driver’s configuration, select that driver, then modify its attribut-
vers and settings. The right pane contains the Definition es in the Definition page.
page, which is used to display the various parameters of the
selected database name, driver, or setting. Native drivers, which include both local and SQL Links, are
installed when you install Delphi. You cannot add new native
Working with Global Aliases drivers from the BDE Administrator. These can only be
Aliases, or database names, are labels that reference a direc- installed from the installation disk supplied by INPRISE, or
tory (or server) and a driver that can be used to access data one created by InstallShield Express.
in that directory (or server). Aliases defined on the
Databases page of the BDE Administrator are available to The driver settings you enter on the Configuration page of
all Delphi applications on that machine. Consequently, the BDE Administrator provide default settings for global
they are referred to as global aliases. By comparison, aliases aliases. However, when configuring a particular alias, you
defined within an application using a Database component can override any of these parameters.
are referred to as local aliases, because they are available
only to that application. Database Applications That Don’t Use the BDE
Under normal circumstances, the database applications that
Global aliases defined here are especially useful for data that you create using Delphi use the BDE. However, there are
must be accessed by more than one application. For example, alternatives that don’t require the BDE. These include:
a company may maintain a single table for storing general Applications that make use of explicit file I/O. For
information about its employees. If more than one applica- example, you can define your own file structures, then
tion needs to access this information, an alias can be created take responsibility for reading and writing this data
that points to the directory in which that table is stored. If all manually. The drawback to this type of application is
applications access this table using the defined alias (which is that you cannot use the data access and data control
DBNavigator
components that ship with Delphi. Similarly, if you Session. The Session component represents a connection
want the data to be accessed in a multi-user environ- to the BDE. Conceptually, it represents the user for the
ment, you are responsible for programming the neces- purpose of file and record locking. Every database applica-
sary file- and record-locking mechanisms. tion has its own session, and Delphi creates this session
Applications that make use of an alternative database automatically. (The automatically-created session compo-
engine. Several third-party developers have created nent can be referenced by the instance variable named
add-on products for Delphi that provide for data Session.) It is because of the session that two applications
access. These either support file types not supported running on the same machine are seen by the BDE as two
directly by the BDE (such as Clipper or Btrieve) or different users (different sessions equate to different users).
have a smaller footprint than the BDE. Some of these Even if one user runs two copies of a given application,
third-party products can be used with Delphi’s data each copy will have a different session, and therefore will
access and data control components, while others appear to the BDE as two users.
provide their own component set for data access
and manipulation. There is a Session component on the Data Access page of
Applications that use the ClientDataSet component the Component palette. One of the few times you ever
that ships with the Client/Server and Enterprise edi- need to add Session components to a single project is
tions of Delphi. This component, which can be used in when that project is multi-threaded and data needs to be
place of other DataSet components, permits the reading accessed by more than one thread. Because each thread
and writing of single-user flat files. The ClientDataSet accesses data from a separate session, the BDE treats the
component relies on a 150KB DLL named threads as separate users. This provides a consistent mech-
DBCLIENT.DLL, but doesn’t make use of the BDE. anism for the resolution of record and table locking
Client applications that use INPRISE’s MIDAS between threads.
(Multi-Tier Distributed Application Services) technolo-
gy. With MIDAS, your Delphi client application Database. The Database component provides a pointer to a
receives data over a TCP/IP connection, or through the directory (on a stand-alone machine or a LAN), or to a
use of sockets. The data is provided by an application remote database server. Every database application will have
server, which you also write using Delphi. While the at least one Database component, and more if data in mul-
application server does make use of the BDE, the tiple directories and/or servers is being accessed.
client application does not. Client applications created
using MIDAS are often referred to as thin clients, If you use a DataSet, but have not specifically associated it
because they require less configuration and fewer files with a Database component, Delphi will create one
(specifically, no BDE). Database component for each directory and/or server
being accessed. It will do this in response to an attempt to
Delphi Database Components open the DataSet.
BDE-based database applications written in Delphi rely on
both data access and data control components that ship Unlike a Session component, you may need to use a Database
with Delphi. The relationship between these components is component if you want to control access to a database. For
depicted in Figure 4. The following sections describe each example, if you want to define custom parameters for access
of these sets of components. to a database server, store a username and password, or
explicitly control transactions, you will probably use at least
one Database component in your application.
Session
(default)
In a single-threaded application, all Database components
are associated with a single Session component. However,
Database many different DataSets can use one Database.
(default)
Database components, like Session components, are global-
DataSets ly available within your application. In other words, if your
(Table, Query, Database component appears on an auto-created form or
StoredProc) the main form, it’s available to all forms and data modules
in the application, without the need for a corresponding
DataSource
uses clause statement.
Data Controls (below)
DBGrid DBNavigator DBText DBEdit DBMemo DBImage DataSets. DataSets, which include the Table, Query, and
StoredProc components, are associated with individual
tables or SQL files. (In the case of Query and StoredProc
components, it’s possible for these entities to be associated
Figure 4: The relationship between the various data access with more than one, or even no, underlying data file. This
components and data aware controls. is the exception, however, rather than the rule.)
DBNavigator
Each DataSet has its own cursor. Furthermore, you use the Conclusion
methods and properties of the DataSets to get information Delphi has established itself as one of the leading develop-
about — and to control — a table. For example, using a ment tools for building database applications for the
DataSet you can read data from a table, modify existing Windows platform. Essential to this role is the Borland
records, insert new records, or delete records. Database Engine, which serves as an independent layout
for all data access. In addition, the data access and data
From a developer’s standpoint, DataSets greatly simplify control components provide a seamless and easy-to-use
access to data. Specifically, they encapsulate calls to the interface to the BDE, permitting you to quickly build
BDE from within an easy-to-use interface. For example, if complex interfaces.
you wanted to create a pointer to a record using BDE API
calls, you would have to call at least five different BDE API In next month’s “DBNavigator,” we’ll take a look at configuring
functions. By comparison, calling a Table component’s data access components, including tables and queries. ∆
Open method performs the identical operation.
DataSource. The DataSource component provides for interac-

tion between DataSets (which access data), and data controls
(which provide the user interface). This interaction is two- Cary Jensen is President of Jensen Data Systems, Inc., a Houston-based
way. For example, if a user tries to type a character into a database development company. He is co-author of 17 books, including
DBGrid component, the DBGrid will first inquire through Oracle JDeveloper [Oracle Press, 1998], JBuilder Essentials
the DataSource whether the Table is in a state that permits [Osborne/McGraw-Hill, 1998], and Delphi in Depth [Osborne/McGraw-Hill,
1996]. He is a Contributing Editor of Delphi Informant, and is an interna-
editing (such as dsEdit or dsInsert). If the Table is not, the
tionally-respected trainer of Delphi and Java. For information about Jensen
DataSource will attempt to place the Table in the dsEdit state. Data Systems consulting or training services, visit http://idt.net/~jdsi or e-mail
If successful, the DataSource will accept the data entered into Cary at cjensen@compuserve.com.
the DBGrid. Likewise, when a Table pointer is changed to
point to a new record, the DataSet informs the DataSource,
which instructs the DBGrid to repaint itself.
Beginning Delphi database developers often wonder why the

database functionality represented by the DataSet and
DataSource components are not combined into a single com-
ponent. The answer is that, from a component design stand-
point, it is often better to create two simple components that
perform well-defined tasks, as opposed to a more complex
single component. The simpler components are easier to
debug and use.
Because DataSource components are used primarily for

managing the interaction between data controls and
DataSets, you rarely need to use a DataSource for data
access that is entirely programmatic. In other words, if you
have no user interface, you probably don’t need a
DataSource.
Data Control Components. Data control components (i.e.

those that appear on the Data Controls page of the
Component palette) are used to display or manipulate data
being pointed to by a DataSet. For example, using either a
DBGrid or DBEdit, a user can view and edit data. Using a
DBNavigator component, a user can navigate a DataSet, as
well as insert and delete records.
Delphi’s data access and data control components play

an important role in rapid application development.
Specifically, rather than having to explicitly program how a
user interacts with data — including fetching, detecting
changes, and saving data — you can simply place the
appropriate data controls and data access components
onto your form, and most of this interaction will be taken
care of for you.
The API Calls
Delphi 2, 3 / TAPI / Line Communications
By Major Ken Kyler and Alan C. Moore, Ph.D.
Delphi and TAPI

Part II: Building a Telephony Application
L ast month, we discussed issues related to line communication in general and

telephony in particular. Introducing the four essential Windows communica-
tions classes — Win32 Communications API, WAVE API, Messaging API (MAPI),
and the Telephony API — we concentrated on the Telephony API, or TAPI. We
examined some of the basic TAPI functions in detail, and demonstrated how to
use them to initiate and manage phone calls.
This month, we’ll go further, building on that When we open a line for communications,
foundation in several ways. We’ll show you we could have a number of intentions: from
how to determine the existing capabilities of conducting a simple voice conversation to
the particular TAPI implementation and downloading a file. The most important
monitor changes to the COMM port. We’ll function in determining what communica-
also show you how to access one of the dialog tions operations our application will be able
boxes included in TAPI. To accomplish this, to perform is LineOpen. This function is
we’ll have to take some additional steps that declared in TAPI.pas as:
were unnecessary in the first article.
function LineOpen(hLineApp: HLINEAPP;
Opening Lines of Communication dwDeviceID: DWORD;

lphLine: LPHLINE; dwAPIVersion: DWORD;
You’ll recall that last month, we explained dwExtVersion: DWORD; dwCallbackInstance:
that initializing TAPI is a two-step process; DWORD;
dwPrivileges: DWORD; dwMediaModes: DWORD;
first, you call LineInitialize, then you call const lpCallParams: LPLINECALLPARAMS):
LineNegotiateAPIVersion. Among other things, LONG;
LineInitialize returns a handle to the usage
instance of TAPI in its first parameter, The first parameter, hLineApp, is a handle.
hLineApp. It also sets a pointer to a callback The second, dwDeviceID, is a line-device
function. The following statement from our identifier. The third, lphLine, is the line
sample application accomplishes this: device’s Windows handle. The fourth and
fifth parameters are negotiated: dwAPIVersion
ErrNo := LineInitialize(@ FLineApp, MainInstance,
LineCallback, '',
gets the proper API version, and
@FnumDevs); dwExtVersion returns the extended version.
The sixth parameter, dwCallbackInstance, is
We also need to call LineNegotiateAPIVersion an application’s instance data, which it passes
so the application knows which version of to a callback function, lineInitialize. The next
TAPI to use. As we discussed last month, since two, dwPrivileges and dwMediaModes, are
it has several versions, each with considerably probably the most important. The first deter-
different capabilities, TAPI is one of the few mines how an application handles different
Windows APIs that requires version negotia- kinds of calls; the latter specifies the types of
tion. This will become evident when we exam- calls. The final parameter, lpCallParams,
ine some of the TAPI data structures. Now points to a structure that provides Windows
we’re ready to explore some new territory. with criteria an application uses in selecting a
The API Calls
line. The LINECALLPARAMS record is defined in FMediaMode := LINEMEDIAMODE_DATAMODEM;
TAPI.pas, as shown in Figure 1. FBearerMode := LINEBEARERMODE_VOICE;
You’ll notice in this structure that many new options were Then, we make certain these default values are reflected in
added in version two of TAPI. Figure 2 describes the fields our two combo boxes with these statements:
used by LineOpen. If you’re making a data call, you’re
// Default to LINEMEDIAMODE_DATAMODEM.
required to set the default values; in a voice call, this is cboxMediaMode.ItemIndex := 3;
optional. In the FormCreate method of TAPIU_2.pas, we ini- // Default to LINEBEARERMODE_VOICE.
tialize FMediaMode and FBearerMode as follows: cboxBearerMode.ItemIndex := 0;
LPLINECALLPARAMS = ^TLINECALLPARAMS; Finally, we set the following values:

PLINECALLPARAMS = ^TLINECALLPARAMS;
TLINECALLPARAMS = record // Defaults:
with FLineCallParams do begin
dwTotalSize, // ---------
dwTotalSize := SizeOf(FLineCallParams);
dwBearerMode, // voice
dwBearerMode := FBearerMode;;
dwMinRate, // (3.1kHz)
dwMediaMode := FMediaMode;
dwMaxRate, // (3.1kHz)
end;
dwMediaMode, // interactiveVoice
dwCallParamFlags, // 0
dwAddressMode, // addressID Having initialized these and other values in the FormCreate
dwAddressID: DWORD; // (any available)
method, we can now call the LineOpen function and get things
DialParams: TLINEDIALPARAMS; // (0, 0, 0, 0)
dwOrigAddressSize, // 0 rolling. In the expanded application included with this article (see
dwOrigAddressOffset, end of article for download details), we’ve added this function to
dwDisplayableAddressSize,
the CreateCallManager method with the following statement:
dwDisplayableAddressOffset,
dwCalledPartySize, // 0
dwCalledPartyOffset, if cbLineMapper.Checked then
dwCommentSize, // 0 // Automatically select the device.
dwCommentOffset, ErrNo := LineOpen(FLineApp, LINEMAPPER, @FLine, FVersion,
dwUserUserInfoSize, // 0 0, 0, LINECALLPRIVILEGE_NONE,
dwUserUserInfoOffset, FMediaMode, @FLineCallParams)
dwHighLevelCompSize, // 0 else
dwHighLevelCompOffset, ErrNo := LineOpen(FLineApp, FDev, @FLine, FVersion,
dwLowLevelCompSize, // 0 0, 0, LINECALLPRIVILEGE_NONE,
dwLowLevelCompOffset, FMediaMode, nil);
dwDevSpecificSize, // 0
dwDevSpecificOffset: DWORD;
The use of the LineOpen function and its LINEMAPPER
{$IFDEF Tapi_Ver20_ORGREATER} parameter demonstrate a very different approach from the
dwPredictiveAutoTransferStates, one we took in the last article. If cbLineMapper is checked,
dwTargetAddressSize,
we let the system select its default line; otherwise we choose
dwTargetAddressOffset,
dwSendingFlowspecSize, from the list of available devices. LINEMAPPER identifies
dwSendingFlowspecOffset, the first device capable of making the kind of call we want.
dwReceivingFlowspecSize,
Let’s see how we determine these capabilities.
dwReceivingFlowspecOffset,
dwDeviceClassSize,
dwDeviceClassOffset, Is the Line Capable?
dwDeviceConfigSize,
Once we’ve made this function call and have called the
dwDeviceConfigOffset,
dwCallDataSize, CreateCallManager method, we can go about the business of
dwCallDataOffset, determining a line device’s capabilities. Information about
dwNoAnswerTimeout,
these capabilities is stored in another large TAPI structure,
dwCallingPartyIDSize,
dwCallingPartyIDOffset: DWORD; LINEDEVCAPS. This structure is defined in TAPI.pas as
{$ENDIF} shown in Figure 3.
end;
We can use the TAPI lineGetDevCaps function to retrieve this
Figure 1: LINECALLPARAMS, as defined in the TAPI unit. information. Because there can be more than one logical line on
Meaning Use of Field

dwTotalSize Informs Windows how much memory is available for returning TAPI information.
dwBearerMode Indicates the general class of data transfer the line supports, including passthrough mode.
dwMinRate Provides information bandwidth requirements; not all telephony drivers use this field.
dwMaxRate Provides information bandwidth requirements; not all telephony drivers use this field.
dwMediaMode Specifies the media mode the application will support. Can be one of the LINEMEDIAMODE_
constants (see TAPI.pas), or an extended media mode value defined by a service provider.
dwCallParamFlags Flags that control the behavior of a modem when making a call.
Figure 2: LineCallParams fields used by the LineOpen function.

The API Calls
a computer, we call lineGetDevCaps for each line to identify one of the structure actually contains relevant information.
that supports the type of data with which we want to work. In These two fields are set by Windows. You’ll notice that
our extended application, we call this function in the several other fields are the same as, or similar to, those in
EnumerateDevices method. LPLINECALLPARAMS, e.g. dwBearerModes and
dwMediaModes.
Let’s examine the structure itself. As in
LPLINECALLPARAMS, dwTotalSize provides Windows Several of the other fields are quite important. The
with the amount of memory needed for the structure. dwNumAddresses field contains the number of addresses a
Because this structure is variable in size, the next two particular logical device supports; the field
fields, dwNeededSize and dwUsedSize, indicate how much dwAddressModes indicates the manner in which the appli-
cation identifies a line’s address; and the field
LPLINEDEVCAPS = ^TLINEDEVCAPS; dwStringFormat (which we use in the sample application)
PLINEDEVCAPS = ^TLINEDEVCAPS;
TLINEDEVCAPS = record
indicates whether the string format is ASCII or Unicode.
dwTotalSize, Because we aren’t supporting Unicode in this application,
dwNeededSize, we exit if we discover the format is Unicode. Otherwise,
dwUsedSize,
dwProviderInfoSize,
we populate the cboxDevices combo box with the names of
dwProviderInfoOffset, the available line devices.
dwSwitchInfoSize,
dwSwitchInfoOffset,
dwPermanentLineID,
Monitoring a Modem: Beyond TAPI
dwLineNameSize, Often, we want or need to keep track of what a modem is
dwLineNameOffset, doing. To accomplish this, we must use lower-level commu-
dwStringFormat,
dwAddressModes,
nications API functions that aren’t part of TAPI. The
dwNumAddresses, GetCommModemStatus function is particularly useful. This
dwBearerModes, basic Windows communications function returns a modem’s
dwMaxRate,
dwMediaModes,
control-register values. It’s declared in Windows.pas as:
dwGenerateToneModes,
dwGenerateToneMaxNumFreq, function GetCommModemStatus(hFile: THandle;
dwGenerateDigitModes, var lpModemStat: DWORD): BOOL; stdcall;
dwMonitorToneMaxNumFreq,
dwMonitorToneMaxNumEntries,
dwMonitorDigitModes,
The parameters to GetCommModemStatus are hFile, the handle
dwGatherDigitsMinTimeout, of the communications port; and lpModemStat, which points to
dwGatherDigitsMaxTimeout, the current status of the modem, stored in a control-register.
dwMedCtlDigitMaxListSize,
dwMedCtlMediaMaxListSize,
Before we can call this function, we must set things up properly.
dwMedCtlToneMaxListSize,
dwMedCtlCallStateMaxListSize, First, we need to create a thread in which to do the monitor-
dwDevCapFlags,
dwMaxNumActiveCalls,
ing while the rest of our application continues to function.
dwAnswerMode, (See Jon Jacobs’ article “Threads Simplified” in the
dwRingModes, December, 1997 issue of Delphi Informant for an excellent
dwLineStates,
dwUUIAcceptSize,
introduction of working with threads.) The simple thread
dwUUIAnswerSize, class is defined in the CommStatus.pas:
dwUUIMakeCallSize,
dwUUIDropSize, type
dwUUISendUserUserInfoSize, TCommStatus = class(TThread)
dwUUICallInfoSize: DWORD; protected
MinDialParams, procedure Execute; override;
MaxDialParams, end;
DefaultDialParams: TLINEDIALPARAMS;
dwNumTerminals,
dwTerminalCapsSize, In the private declarations of our main form class, we declare
dwTerminalCapsOffset,
an instance of this thread as:
dwTerminalTextEntrySize,
dwTerminalTextSize,
dwTerminalTextOffset, FCommStatusThread: TCommStatus;
dwDevSpecificSize,
dwDevSpecificOffset,
dwLineFeatures: DWORD;
We instantiate it (in suspended form) in the Form.Create
method with the line:
{$IFDEF Tapi_Ver20_ORGREATER}
dwSettableDevStatus, FCommStatusThread := TCommStatus.Create(True);
dwDeviceClassesSize,
dwDeviceClassesOffset: DWORD;
{$ENDIF} Once we have successfully opened a line for communications,
we activate the thread with the following line of code:
end;
Figure 3: The TAPI structure, LINEDEVCAPS. FCommStatusThread.Resume;

The API Calls
Event Constant Description procedure TCommStatus.Execute;
var
EV_BREAK A break was detected during input. dwEvent: DWord;
EV_CTS State of the CTS (clear-to-send) dwStatus: DWord;
signal changed. begin
dwEvent := 0;
EV_DSR State of the DSR (data-set-ready) SetCommMask(FPort, EV_DSR or EV_CTS or SETDTR);
signal changed. repeat
EV_ERR A line-status error occurred WaitCommEvent(FPort, dwEvent, nil);
GetCommModemStatus(FPort, dwStatus);
(CE_FRAME, CE_OVERRUN, and case dwEvent of
CE_RXPARITY). EV_DSR: Form1.SetBitmap(Form1.DSR, green);
EV_RING Ring indicator detected. SETDTR: Form1.SetBitmap(Form1.DTR, green);
EV_CTS: Form1.SetBitmap(Form1.CTS, green);
EV_RLSD State of the RLSD (receive-line-signal- end;
detect) signal changed. // Form1.SetBitmap(Form1.AA, green);
EV_RXCHAR Character received and put in input until Terminated;
end;
buffer.
EV_RXFLAG Event character (specified in the device) Figure 5: The entire Execute method.
received and put in the input buffer.
EV_TXEMPTY Last character in the output buffer sent. To get extended error information, you should call the
Figure 4: lpEvtMask modem events and their meanings. GetLastError function.
Once we have terminated our call, we close the thread with: As we’ve seen, the WaitCommEvent function monitors events
on a particular communications resource. You can set or
FCommStatusThread.Terminate;
query the current event mask of the communications resource
by using the SetCommMask and GetCommMask functions. If a
Within the thread, all the work takes place in the Execute
requested overlapped operation cannot be completed immedi-
method. Here we call two low-level communications API
ately, the function returns False and GetLastError returns
functions, SetCommMask and WaitCommEvent. Let’s discuss
ERROR_IO_PENDING. This indicates that the communi-
each. The first, SetCommMask, is defined in Windows.pas as:
cations operation is continuing to execute in the background.
function SetCommMask(hFile: THandle; When this happens, the system will set the hEvent member of
dwEvtMask: DWORD): BOOL; stdcall; the OVERLAPPED structure to the not-signaled state before
the WaitCommEvent function returns. You can call
Its first parameter, hFile, is the handle of the communications GetOverlappedResult to determine the success or failure of the
port. The var parameter, lpEvtMask, is a mask containing one operation. The variable pointed to by the lpEvtMask parame-
or more events to monitor. The various modem events con- ter indicates the event that occurred. In the sample applica-
stants and their meanings are shown in Figure 4. tion, we used the non-overlapped approach.
Once we’ve told Windows the kind of communications events Putting It All Together
to monitor, we have to wait for one to occur. (Do you see In the CommStatus unit, we use these API functions in the
why we needed to do this in a separate thread?) The Execute method. As we stated earlier, GetCommModemStatus’
WaitCommEvent function waits for an event to occur on a second parameter, lpModemStat, points to the current status of
particular communications device. The WaitCommEvent func- the modem. The entire Execute method is shown in Figure 5.
tion is defined in Windows.pas as:
function WaitCommEvent(hFile: THandle; var lpEvtMask: DWORD;

You’ll notice that certain communications events are associated
lpOverlapped: POverlapped): BOOL; stdcall; with particular modem light indicators. We have tried to imitate
the indicator lights you generally see on external modems. If you
The monitored events contained in the lpEvtMask event mask study the source code, you’ll see how we initialize the modem
are associated with the device handle, hFile. The lpEvtMask lights and also notice that we are able to change some of them in
parameter points to a 32-bit variable that receives a mask indi- the main file (and not the thread). Figure 6 shows the expanded
cating the type of event that occurred. If there’s an error, zero application in action, with some of the lights active.
is returned; otherwise, it’s one of the values shown in Figure 4.
Now that we’ve explored some low-level communications
The next parameter, lpOverlapped, is either nil or points to the techniques to query the status of a modem, let’s return to
address of an overlapped structure. This structure is required if TAPI and take a look at one of its built-in dialog boxes.
hFile was opened with FILE_FLAG_OVERLAPPED. In that
case, the lpOverlapped parameter may not be nil. It must Back to TAPI: lineTranslateDialog
point to a valid OVERLAPPED structure. Under these cir- In addition to the functionality we’ve already discussed, TAPI
cumstances, you can use the CreateFile function to return also provides Windows with a number of dialog boxes for set-
the handle. The WaitCommEvent function can return vari- ting or viewing the properties of various devices. One of the
ous values. If the function fails, it returns a value of zero. most commonly used is the Dialing Properties dialog box.
The API Calls
Figure 6: The new sample application with modem lights activated.

Figure 7: TAPI’s lineTranslateDialog in action.
The lineTranslateDialog function displays a dialog box similar to
the Dialing Properties dialog box, but includes the dialable address Multiple instances of this dialog box can be opened using
(see Figure 7). If you study the TAPI.pas source, you’ll find this TAPI version 2.0 or later. In earlier TAPI versions,
dialog function comes in two flavors: lineTranslateDialogA and LINEERR_INUSE is returned if the dialog box is already
lineTranslateDialogW; the former for ASCII characters and the displayed by another application, and TAPI brings the
latter for wide characters (Unicode). We use lineTranslateDialogA existing dialog box to the front.
in this application; it’s defined in TAPI.pas as:
We call lineGetTranslateCaps after this function to get any
function lineTranslateDialogA(hLineApp: HLINEAPP; changes the user made to the telephony address translation
dwDeviceID: DWORD; dwAPIVersion: DWORD; hwndOwner: HWND;
lpszAddressIn: LPCSTR): LONG; stdcall;
parameters. You can call lineTranslateAddress to obtain a
dialable string based on the user’s new selections. If you
The first parameter, hLineApp, is the application handle returned call any function related to address translation
by lineInitializeEx. If the application has not yet called (lineGetTranslateCaps or lineTranslateAddress) and the func-
lineInitializeEx, it can set the hLineApp parameter to nil. The section returns LINEERR_INIFILECORRUPT, you should
ond parameter, dwDeviceID, is an identifier for the line device call lineTranslateDialog. The lineTranslateDialog function
upon which the call will be dialed. The third parameter, detects the errors and corrects them. It also reports to the
dwAPIVersion, indicates the highest TAPI version the application user the action taken.
supports (not necessarily the value negotiated by
lineNegotiateAPIVersion). The parameter hwndOwner is the han- Where to Go from Here
dle to the window to which the dialog box is to be attached. The We’ve gone considerably further than in the first article, but
next parameter, lpszAddressIn, is a PChar containing the phone we’ve still only scratched the surface. We’ve concentrated on
number shown in the lower portion of the dialog box. The simple voice calls to keep the whole discussion straightfor-
phone number must be in canonical format; if it isn’t, the phone ward. There are many other types of calls (voice and data) for
number won’t be displayed in the dialog box. This pointer can be which TAPI provides excellent support. You can study the
set to nil, in which case the phone number won’t be displayed. source code for these units, especially the TAPI.pas unit, and
extend the sample application’s functionality by implementing
The dialog box can return various values. If it returns zero, the additional TAPI functions.
function was successful. A negative error number in the return
values indicates an error. The possible return values are: We’re not quite finished. What we’ve demonstrated in the sam-
LINEERR_BADDEVICEID ple application is fine as an introduction. It’s enabled us to test
LINEERR_INVALPARAM and show many basic TAPI functions. However, if we want to
LINEERR_INCOMPATIBLEAPIVERSION use this kind of functionality in more than just one application,
LINEERR_INVALPOINTER we will find ourselves doing a lot of cutting and pasting, to say
LINEERR_INIFILECORRUPT the least. What we need to do is wrap all of this functionality
LINEERR_NODRIVER in a TAPI class or component that will be easily accessible in
LINEERR_INUSE any application we write. We’ll tackle that task next month. ∆
LINEERR_NOMEM
LINEERR_INVALADDRESS Important note: The TAPI unit has been brought to you by the
LINEERR_INVALAPPHANDLE volunteers of the JEDI project. To learn more about the JEDI
LINEERR_OPERATIONFAILED project, please visit http://www.delphi-jedi.org.
The API Calls
The files referenced in this article are available on the Delphi
Informant Works CD located in INFORM\98\AUG\DI9808AM.
Major Ken Kyler is the Air National Guard Systems Analyst for the Defense
Integrated Military Human Resources System (DIMHRS). He has been program-
ming with Delphi for two years. He is also a free-lance technical writer with arti-
cles published in several Delphi magazines. You can reach him at
KylerK@PR.OSD.MIL.
Alan Moore is a Professor of Music at Kentucky State University, specializing in

music composition and music theory. He has been developing education-related
applications with the Borland languages for more than 10 years. He has pub-
lished a number of articles in various technical journals. Using Delphi, he spe-
cializes in writing custom components and implementing multimedia capabili-
ties in applications, particularly sound and music. You can reach Alan on the
Internet at acmdoc@aol.com.

At Your Fingertips
By Robert Vivrette
Better Coding through APIs

Napping, Driving, and Personable Cursors
I t happens all the time: You’re adding a feature to your latest programming
work of art, when what you thought would be fairly simple quickly becomes
a code morass. “There has to be a simpler way!” you exclaim. There often is. In
fact, my Delphi philosophy is: “If it takes more than two or three lines of code to
achieve a desired effect, you’re probably doing it wrong.” I live by this state-
ment, and I have seen it hold true hundreds — if not thousands — of times. I’ll
complete some routine, then sit back and look at it. “Hmm ... looks a little over-
weight!” Then I start trimming it down: finding simpler ways to accomplish the
same thing, looking for API calls to eliminate much of my code. After a few pass-
es, pruning here and there, it happens! Two or three lines of code remain.
Windows has been around for quite a while, so value of zero causes the thread to relinquish any
it’s unusual that a programmer will write some- time left on its current time slice to any other
thing completely unique, something never running thread with the same priority.
coded before. The programming APIs available
to Windows developers are substantial, but we Be aware of some of the behavior you may
can’t always remember them all, and can wind see using Sleep. Because you are stopping
up re-coding what already exists in an API. CPU cycles to your application’s primary
thread, your application’s message processing
In this spirit, this month’s “At Your loop will take a nap as well. This means that
Fingertips” is devoted to existing API rou- mouse messages won’t be processed, keyboard
tines that sometimes fall through the cracks: input will be on hold, and Timers will stop
simple and useful routines that, in my experi- working, to name just a few. In most cases,
ence, few developers even realize exist, yet however, this is what you want anyway.
can save considerable programming effort.
There’s more. The SleepEx function extends
Take a Nap! this capability to allow the sleeping thread to
Back in the days of Turbo Pascal and DOS be alerted before the completion of its sleep
programming, programmers had a wonderful delay. This would enable you to put the thread
little routine named Delay that would pause to sleep pending the completion of some other
execution of the program for a specified peri- supported event, such as the I/O functions
od. Then Windows development came along, ReadFileEx and WriteFileEx. There’s more to
and Delay was gone. <sniff>. Or was it? It the SleepEx function than I can go into here,
turns out the Windows API has a Sleep rou- but Delphi Help discusses it fairly well.
tine that performs the same function.
Show a Little Drive
In a nutshell, the Sleep procedure pauses execu- Sometimes, developers need to obtain a list of
tion of the current thread for an indicated num- all available drive letters on the machine. I’ve
ber of milliseconds. It takes a single DWORD seen a lot of approaches to this, including build-
parameter that specifies the number of millisec- ing a loop from ‘A’ to ‘Z’ and looking at each
onds to wait before continuing. A value of 1000 drive individually. The problem with most of
equals one second, so to delay for three seconds, these approaches is that validating the existence
you would use Sleep(3000). Specifying a value of a drive in this manner often involves access-
of INFINITE (i.e. $FFFFFFFF) causes the ing the drive itself. This can generate unwanted
process to sleep forever (now that’s useful). A system errors for an empty floppy drive.
At Your Fingertips
You could use a DriveComboBox component and examine procedure TForm1.Button1Click(Sender: TObject);
var
its Items property to see what drive letters it’s populated
Buffer: array[0..500] of Char;
with. The disadvantage here is that DriveComboBox holds TmpPC : PChar;
a lot more code than you need. It’s also a visible control, Typ : Integer;
begin
so if you aren’t using it for any other purpose, you will
GetLogicalDriveStrings(SizeOf(Buffer),Buffer);
need to stash it out of the way and set its Visible property TmpPC := Buffer;
to False. Sloppy! while TmpPC[0] <> #0 do begin
Typ := GetDriveType(TmpPC);
with ListBox1.Items do
A much better solution is to use the Win32 API functions case Typ of
GetLogicalDrives and GetLogicalDriveStrings. GetLogicalDrives DRIVE_REMOVABLE : Add(TmpPC + ' (Removable)');
DRIVE_FIXED : Add(TmpPC + ' (Fixed)');
returns a 32-bit value that is bitmasked to indicate the valid
DRIVE_REMOTE : Add(TmpPC + ' (Remote)');
drives in the system. In the return value, bit position zero DRIVE_CDROM : Add(TmpPC + ' (CD-ROM)');
represents drive A, the next bit represents drive B, and so on. DRIVE_RAMDISK : Add(TmpPC + ' (RAM-Disk)');
else
If a bit is set to 1, the drive is present in the system. This
Add(TmpPC+' (Unknown)');
procedure adds the letters of all available drives to ListBox1: end;
TmpPC := StrEnd(TmpPC)+1;
procedure TForm1.Button1Click(Sender: TObject); end;
var end;
Drvs: DWord;
Figure 1: Use the GetDriveType function to determine the type
A : Integer;
of drive that GetLogicalDrives and GetLogicalDriveStrings returns.
begin
Drvs := GetLogicalDrives;
for A := 0 to 31 do The technique couldn’t be easier. Simply define a cursor con-
if (Drvs and (1 shl A)) > 0 then stant (anything greater than zero and not conflicting with
ListBox1.Items.Add(Chr(A+65));
end; another cursor constant) in the const section of your unit:
const
Note the use of the shl keyword to mask out only the bit crMyCursor = 5;
position I’m interested in. By taking a ‘1’ and shifting it left a
number of positions, I can mask out just the bit position I Then add this code to the FormCreate method:
am interested in using the and keyword.
procedure TForm1.FormCreate(Sender: TObject);
begin
The GetLogicalDriveStrings function is similar, but instead
Screen.Cursors[crMyCursor] :=
returns a string representing all the valid drives on the sys- LoadCursorFromFile('C:\WINNT\Cursors\sendmail.ani');
tem. After each drive reference, there is a null character; at Panel1.Cursor := crMyCursor;
end;
the end of the entire string, there is a pair of null characters.
This procedure can be used to extract the values returned in
a doubly null-terminated string: A standard Windows 95 or Windows NT installation will
have a number of animated cursor files located in the
procedure TForm1.Button1Click(Sender: TObject); Windows\Cursors or WinNT\Cursors directory, respectively.
var
Buffer: array[0..500] of Char;
TmpPC : PChar;
Conclusion
begin The various Windows APIs are chock-full of useful routines
GetLogicalDriveStrings(SizeOf(Buffer), Buffer); available to you as a Delphi programmer: It’s just a matter of
TmpPC := Buffer;
knowing where to look. The best way to find those interesting
while TmpPC[0] <> #0 do begin
ListBox1.Items.Add(TmpPC); new functions is to look up something you’re familiar with in
TmpPC := StrEnd(TmpPC) + 1; the Win32 API Help file, and then click on the “Group” link at
end;
the top of the page. This will show you a list of routines that fall
end;
into the same general category. Scan through them and you’ll be
amazed at what you find.
Alternatively, you could use the GetDriveType function to
determine the type of drive that GetLogicalDrives and
And remember: If it takes more than two or three lines of
GetLogicalDriveStrings returns (see Figure 1).
code to do anything in Delphi, there’s probably an API rou-
tine that does it all for you! ∆
Cursors Are Nice People Too
Most good Delphi programmers know they can create custom
cursors and load them into the Screen.Cursors array. But did
you know that you can also load animated cursors? You can Robert Vivrette is a contract programmer for Pacific Gas & Electric, and Technical
achieve this by using the LoadCursorFromFile API function. Editor for Delphi Informant. He has worked as a game designer and computer
This function returns a handle to the loaded cursor, which consultant, and has experience in a number of programming languages. He can
can be a standard cursor file (*.CUR), an Animated Cursor be reached via e-mail at RobertV@mail.com.
(*.ANI), or one of the system cursors.
New & Used
By Steve Garland
ODBCExpress
Catch the High-speed Train to Database Access
M ost of the non-Delphi world of C++, Visual Basic ( VB), and PowerBuilder
developers access client/server databases using ODBC. Delphi’s BDE
allows the same access, but why use the BDE when you can go to a pure
Pascal/ODBC solution using the ODBCExpress components from Datasoft?
What do you gain? Speed, control, and no DLLs to distribute with your applica-
tions. What do you lose? Over 1MB of BDE DLLs.
Why ODBC? architect, Kyle Geiger, entitled Inside ODBC

A couple of years ago, I was thumbing through (from Microsoft Press). Although this book
some VB magazines (to see how the other side was published in 1995, I still highly recom-
lives), and noticed an article on the “fastest” way mend it as an excellent introduction to
to access databases. DAO and RDO were dis- client/server programming. There are interest-
cussed, but ODBC smoked them all in leanness ing discussions about the concept of cursors
and performance. ODBC had earned a bad and their history, file server versus client/serv-
name with me because of its early, slow imple- er computing, and a fascinating byte-by-byte
mentation, but I was beginning to wonder if I account of what actually happens on a query
should give it another look. If the VB, C++, and to SQL Server. Not only the “hows” of
PowerBuilder crowds were satisfied with using ODBC are discussed, but also the “whys,”
ODBC API calls, why couldn’t I do the same? including some interesting industry history.
After I started using ODBC and the BDE with I’m going to sketch out the basics of ODBC
SQL Anywhere, I was running into several for you and, at the same time, detail the way
“gotchas” with INPRISE (nee Borland) and that Datasoft implemented the ODBC API
Sybase pointing fingers at each other. One of in ODBCExpress.
the problems was getting SQL Anywhere to
handle BLOBs greater than 32KB using What Is ODBC?
Delphi/ODBC/BDE. I knew that SQL ODBC is Microsoft’s set-oriented API for
Anywhere could handle this with pure ODBC, accessing databases. The set-oriented part is
so what was I missing? I needed to take the important as ODBC expects data sources to
BDE out of the equation. be able to handle SQL. This means the data
must reside in tables and have the concept of
Writing directly to the ODBC API seemed like rows and columns. (As a side note, Microsoft
a lot of work, until I came upon a South has realized that there is other data that doesn’t
African company that had used Delphi and fit the row/column metaphor, and has created
ODBC to develop a document management OLEDB for that. ODBC becomes a subset of
application using Microsoft SQL Server as their OLEDB in their current scheme.)
back end. That company was Datasoft, and the
product was ODBCExpress. I soon had SQL ODBC is a specification, not an implementa-
Anywhere eating large text files like candy, and I tion, and many who remember early ODBC
no longer heard that rising rumble of the BDE drivers as slow and buggy should wake up and
DLLs loading. I started to like ODBC. smell the new drivers — especially the ones for
Microsoft SQL Server and SQL Anywhere.
ODBC was a new creature to me, so I quickly The Microsoft SQL Server drivers are so fast
went out and found a book by the ODBC that Microsoft uses them for performance
New & Used
such as grids. ODBC
handles the buffering
and allocating of
memory to make this
possible, so when the
BDE allocates its own
buffering scheme, it
becomes redundant.
Why use both?
The Statement
Handle (Hstmt) is the
worker bee of ODBC.
All SQL statements
and requests for meta-
data require an
Hstmt, and each
Hstmt is associated
Figure 1: The building blocks for ODBC programming as imple- with one connection.
mented by ODBCExpress. Note that the GlobalHenv component Hstmt components
is now automatically instantiated at the unit level. handle the state infor-
mation of any query
benchmarks. It’s also important to note that you don’t need the activity. Hstmt is the
Delphi Client/Server version to access Microsoft SQL Server low-level equivalent of
using their ODBC driver. The promise of ODBC is that if you TQuery. DBCExpress Figure 2: Object Inspector view of
develop to the ODBC API, you can use the same code and has a THstmt class the THdbc component.
tools against any and all ODBC drivers. that implements the
Hstmt.
ODBC has a character all its own; it’s not the BDE. If you
are expecting ODBC to act as the BDE does with Paradox Pulling an Hdbc and
and dBASE tables, you’ll be disappointed. This isn’t to say Hstmt component
that one is better than the other; they’re just different. onto a form allows
you to query a data
ODBC uses the concept of Handles extensively. At the high- source or execute SQL
est level, there is an Environment Global Handle (Henv) that statements (see Figure
is much like the Delphi Session component. The Henv 3). At this level, you
Handle keeps track of the number of connections and their are just a thin wrapper
state, handles error messages that occur at the environment away from the native
level, and helps to manage transactions. In earlier versions of ODBC API calls, and
ODBCExpress, there was an Henv component, but it’s no ODBCExpress adds
longer needed, as it is created internally at unit initialization little overhead to your
to be used by the other components (see Figure 1). Again, application. Issuing
this is similar to the BDE’s Session component. update and insert
statements using
The Connection Handle (Hdbc or Handle to a database con- Hstmt components is
nection) manages the network connection, or tracks directory lean and fast.
and file information for file server databases. All function calls
are routed from the back-end database through the Connection Many developers pre-
Handle. This is equivalent to the Database component of the fer to stay at this level
BDE. ODBCExpress implements it in its THdbc class. Because to keep overhead
they exist independently, you can use Hdbc components to down, and that’s cer-
access the same table isolated in a separate thread (see Figure 2). tainly a choice you Figure 3: Object Inspector view of the
have with THstmt component.
It’s at the THdbc level that you set the isolation level and ODBCExpress.
other properties, such as cursor implementation. ODBC However, many of us like to use visual data aware controls;
has had a feature called a Cursor Library since version 1.2. after all, that’s one of Delphi’s great strengths.
ODBC does this by handling the buffering of data and ODBCExpress has two sets of visual components available,
providing a “moving window” of buffers for the database. but to explain them, we must first recap some Delphi VCL
This enables users to “browse” their data in visual controls, database history.
New & Used
Delphi Database History There’s a happy ending to this story. Borland/INPRISE
Delphi database access starts with the db unit (db.pas). In heard many of us screaming for them to redesign the db
Delphi 1 and 2, there were specific BDE calls in the db unit, and they delivered with Delphi 3. Delphi 3 has a
unit. Therefore, third-party vendors who wanted to provide new and vastly improved version of the db unit that uses
database access using engines and access to the Delphi data- no BDE calls and allows developers to create their own
aware controls other than the BDE were forced to “hack” TDataSet descendants that use the database controls that
their own versions of the db unit and distribute them as come with Delphi. Hallelujah! All the BDE calls were
binary (dcu) files. This led to all kinds of problems with moved to the dbtables unit, and vendors (like
other third-party controls. This method basically intercept- ODBCExpress) could finally plug in their database
ed the low-level BDE calls, and replaced them with proxy engines by simply implementing the virtual abstract
calls to their own engines. In addition to the BDE calls in methods from the db unit. No more hacking necessary.
the db unit, many parts were declared as private, and thus,
impossible to extend using OOP. It All Comes Together: TOEDataSet
The Delphi 3 open dataset architecture paved the way for the
When ODBCExpress 1.0 was released, there was no way ODBCExpress team to use their core ODBC components to
to provide access to the native Delphi database controls provide a component
without shipping a proprietary version of the db.dcu bina- that would make a
ry file. So, ODBCExpress came out with their own data- Delphi database
base controls, which you’ll find installed on the developer feel right at
OEControls tab of the Component palette. These controls home. It’s very similar
were written from scratch by the ODBCExpress team, and to the Delphi Query
let’s just say that they have their own way of doing things. component with a
The grid, for instance, descends from TStringGrid, and, SQL property and a
while it provides fast access, it doesn’t provide design-time Params property with
viewing of data, and generally doesn’t behave like a native which to use stored
Delphi control. procedures. But this
is ODBC, so there is
So, the ODBCExpress team set out in the second version to also an Hstmt proper-
hack the db unit and provide a way for us to use the native ty in case you need
Delphi database controls. (They actually finished the prod- more granular control
uct, but never released it.) The reasons for this are very telling of the TOEDataSet
in comparing ODBC and the BDE and how they differ in (see Figure 4).
their philosophy. Reason one was that the BDE architecture
was undocumented and extremely complex. The more inter- Pull a THdbc compo-
esting reason, however, is that the BDE and ODBC have dif- nent, a TOEDataSet,
ferent “access paradigms.” a Delphi DataSource
and Delphi DBGrid,
The important point is that ODBC is SQL and set- and connect them
oriented, and the BDE is procedural and file-server orient- just like you would a
ed. BDE desktop database users are accustomed to using Query component.
data-aware controls, and editing within a grid with no real What could be easier? Figure 4: Object Inspector view of the
concern for isolation-level or concurrency settings. The Populate the SQL TOEDataSet.
BDE handles it for them — including locking. This is cer- property, set Active to
tainly a wondrous thing, but for client/server develop- True, and the DBGrid is populated. Use the Fields Editor to
ment, one needs to make decisions as to concurrency and change display labels or other TFields of the DataSet.
isolation issues, and live result sets cannot be expected at
all times without some sort of trade-off. So, ODBC All the data-aware controls can be used, including DBEdit and
requires decisions to be made, as there is no “one-size fits DBMemo. The difference is that TOEDataSet provides a thin-
all” philosophy. Many that come to try ODBCExpress ner layer between you and ODBC than does the BDE. The
complain that it doesn’t work exactly like the BDE. Well, ODBCExpress documentation states that by providing ODBC
they’re right. They are different creatures. Driver cursor support, the TOEDataSet “eliminates the need
for a resource-heavy front-end cache as used by existing data-
A lot of marketing hype promises that you can easily convert base engines.” By implementing all the low-level ODBC con-
file-server databases to client/server databases, e.g. Paradox to trols (Thdbc, THstmt), then providing a TDataSet descendant
Microsoft SQL Server. I just don’t believe it. If you expect in the TOEDataSet, ODBCExpress gives you the best of both
ODBC to act like the BDE, you’ll be disappointed; but if worlds: ease-of-use and granularity. At the ODBC level, you
you take the time to understand ODBC and use the tools as can still control the way you do updates, inserts, and deletions.
they were designed, you will find a fast, direct, and lean way You still get complete control over transactions, and can set all
to develop client/server applications. the properties of the THstmt that are part of the grid.
New & Used
TOECatalog encapsulates many of the ODBC calls to get

information about tables and views. For example, it allows
you to easily get a list of all views or stored procedures avail-
able in your database.
TOEAdministrator gives you access to the ODBC

Administrator’s list of data sources, so you can add, delete,
and change them. It is equivalent to the BDE Administrator.
TOESetup helps in setting up and configuring ODBC itself,

as well as its drivers and translators.
There is another tab of components installed on the Delphi

palette under the OEControls tab. These are the old-style
Figure 5: Design-time view of THdbc, TOEDataSet, and a
TDataSource hooked to a SQL Anywhere query.
ODBCExpress controls that preceded TOEDataSet. I recom-
mend you avoid these controls; it’s much easier to use the
Delphi controls with the updated Delphi 3 open dataset
However, with power comes responsibility. There are two architecture (see Figure 5).
methods that can be used to insert, update, or delete a row
from a data source. You can create and execute a full SQL Third-party Support
statement, or you can do a positional insert, delete, or update This release of
of a row in a result set. I prefer the former method, and I cre- ODBCExpress also
ate a separate THstmt to execute a SQL string that I create. provides support for
There is very little overhead to this method, and I have found InfoPower and
it to be very fast. Using the positional method will depend on Orpheus controls, or
whether the result set is modifiable; there are extensive discus- any other third-party
sions of these issues in the ODBCExpress documentation. component library
that supports the open
One problem I have found with the TOEDataSet is appends. dataset architecture.
Because the TOEDataSet represents a result set, when you Also, you can use the
perform an insert, you must re-fire the statement if you want supplied IPREG unit
the inserted row to appear in the result set. This means the to install a
TOEDataSet must be closed and then opened. Because any TWwOEDataSet that
bookmarks are destroyed when the dataset is closed, you lose can be used with the
your position. ODBCExpress suggests you save the primary popular InfoPower
key values of the inserted row, then search the new result set control (see Figure 6).
to reposition the cursor. A procedure for this has been I was able to run the
promised in a future release. InfoPower Locate
Dialog, Filter Dialog,
Documentation and Record View
ODBCExpress comes with an online Help file, a text file of Dialog with no prob-
FAQs, a manual, a tutorial in Word format, and several direc- lem. Although there is
tories of sample programs. Much of the documentation no Filter property on
explains the lower-level ODBC controls and the older the TOEDataSet, Figure 6: InfoPower-enabled
ODBCExpress proprietary controls. Many of the demonstra- there is an ODBCExpress DataSet,
TwwOEDataSet.
tions use the older controls also. There is only a brief discus- OnFilterRecord event
sion on using the TOEDataSet, and its use in the samples is that the InfoPower
limited. I would hope that the future sample and documenta- component uses. I was impressed that it worked so easily, but
tion would focus more on the TOEDataSet. Again, ODBC curious enough to dig into the InfoPower source to find that
has its own way of operating, and it’s worthwhile to under- they call the OnFilterRecord event.
stand how they handle things at the API level.
Technical Support
Other ODBC Components ODBCExpress has an Internet user forum at
TOESchema lets you create tables and views. Pull the compo- http://www.odbcexpress.com. They also provide unlimited
nent on the form, connect it to the THdbc component, and support via e-mail, but you are encouraged to use the public
right-click on the component to go into a Schema Editor forums. I have found responses from the development team
where you can access all the tables and indexes to add fields to be prompt and complete. Datasoft is a South African com-
or change field attributes. pany, so phone support can be expensive.
New & Used
The product is distributed
electronically. There are ver-
sions for Delphi 1, 2, and 3,
as well as a version for
C++Builder. Version 3 sup-
ODBCExpress is a Delphi component ports Delphi 1 and 2. Version
library that allows access to any ODBC
data source, and compiles directly into 4.5 is the current version for
an executable. The Borland Database Delphi 3. ODBCExpress has
Engine is not required, and client/serv-
er applications can be written without
shareware (evaluation) and
the Delphi Client/Server Suite. Version purchased versions, with only
4 of ODBCExpress uses a Delphi a “nag” screen as the differ-
TDataSet descendant that allows
developers to use the normal Delphi ence between them.
data-aware components, as well as Applications developed with
third-party tools.
ODBCExpress can be com-
Datasoft (Pty) Ltd. piled directly into an exe-
P.O. Box 44633 cutable and distributed royal-
Claremont
7735 ty-free.
South Africa
Phone: + 27 21 683 4680

By the time you read this,
Fax: + 27 21 683 4695 the next version of
Web Site: http://www.datasoft.co.za
ODBCExpress should be
Price: ODBCExpress, US$299; full-
source version, US$699. released. It will include
enhancements such as calcu-
lated and look-up fields,
multiple field look-up, and the ability to locate other
improvements to the TOEDataSet. It will also fully imple-
ment the ODBC 3.0 API and include new ODBC 3.0 fea-
tures, such as connection pooling.
Conclusion
I guess it’s not hard to see that I like ODBCExpress. I find
it stays true to the ODBC API character, and allows me to
drop down to the API level when I want to make my own
ODBC calls, or use the TOEDataSet with the native
Delphi database controls. I’ve used these components from
version 1 to version 4, and have been impressed with how
they’ve evolved, the speed with which that evolution has
occurred, and the openness and availability of the
ODBCExpress development team. ∆
Steve Garland is a long-time Delphi developer who lives in Boise, ID with his
wife, 18-month-old son, and four wild pug dogs. He is the principal of Hyper
Logic Resource Group, a Boise-based custom software company. He is also
involved in developing thin-client technology for the Asta Technology Group
(http://www.astatech.com). He can be reached at steveg@hyper-logic.com.

TextFile
Nathan Wallace’s Delphi 3 Example Book

Don’t buy Nathan Wallace’s documentation. The books Consistency plays a large
Delphi 3 Example Book would line the programmer’s part in making this refer-
[Wordware, 1998], with the shelf, the pages of the func- ence so valuable. The pre-
intention of reading it. tion and procedure volume sentation of each compo-
Sitting down with the book, dog-eared and worn, the nent or object follows the
hoping to read it cover to spine of the book cracked same format and structure.
cover, you’ll quickly find the throughout. Sadly, we rarely A literate description of the
text monotonous and the get this opportunity for object is followed by a
format repetitive. On the enlightenment from the schedule of the properties,
other hand, do buy this book compiler vendor any longer; methods, and events, each
to write notes, carefully high- the library of books has been presented alphabetically. For
light often-used methods, replaced by a set of files on each item, the identifier is
mark pages with Post-Its for CD-ROM. A different listed, followed by its data
your current project, and to approach is required in con- type and a short contextual paper book must be consid-
flatten out on your desk so trasting online and printed discussion of the object. ered when attempting to
often that the spine becomes documentation — and the Separating the book further keep the work manageable
unrecognizable. The true printed word retains a dis- from the online documenta- and affordable, the same
value of this book is identi- tinct advantage in some tion is the inclusion of a reasons given by vendors
fied with its pragmatic areas. usage example with every justifying their skimpy doc-
approach to the function of item, a feature lacking in umentation. Rather than
Delphi and the consistency Example segments the docu- the software version. choose to not cover some
of its layout. It is highly like- mentation and examples aspects of the tool, Mr
ly that once this fine book is into logical chapters orga- The consistency advantage Wallace has supplied chap-
discovered and understood, it nized around the flow of extends to the component ters covering several of the
will not leave the side of any the VCL. A perusal of the families that originated out- VCL component tabs and
working Delphi 3 program- introduction to each chap- side of Borland. The best objects as HTML files on
mer. Mr Wallace, in explain- ter prepares the reader for example is found in the the CD-ROM. The author
ing his intentions for writing that section. Topics such as NEWT Internet compo- carefully chose the items
Example, describes his vision the Application object, and nent tab. The ActiveX com- that would receive HTML
of a “coffee rings book,” one the procedures and func- ponents have Help files that treatment, selecting those
that has its cover and pages tions that are a part of the differ in layout from the that had encountered little
branded by coffee cup rings RTL, are listed alphabeti- Borland-generated files. change from earlier releases
from being beside the com- cally. Chapters discussing This book irons out the dif- of the product or less-used
puter all the time. Example the component library are ferences. objects. Unfortunately, the
definitely achieves this goal. listed in the order in which advantages pointed out ear-
they appear on the specific Reality catches up to this lier with respect to the paper
Wallace’s book is a welcome tab. With the introductory paper-bound nirvana when version disappear when the
throwback to a bygone era in comments quickly out of it comes to the sheer depth text moves to HTML for
the programming profession the way, the reader is lead and breadth of the Delphi the last six chapters of the
when each compiler shipped directly to the meat of the environment. The physical book. Rather than retaining
with pounds and pounds of chapter. limitations of publishing a the concise, quick-reference
TextFile
format of the printed page, the design- the site has undergone considerable ren- Nathan Wallace’s Delphi 3 Example
er went on a button binge, requiring ovation, and the user will encounter Book belongs on the desk of all serious
the programmer to drill down through Page Not Found errors with the URL Delphi programmers, those who work
multiple interface layers to retrieve provided. Attempting to manually under the pressure of being consis-
information. Simple text pages with locate any updated files was also non- tently productive, and those with a
well thought out links would be productive, as the support pages for this more leisurely approach to develop-
preferable to this difficult tool. book appeared to remain under con- ment. Nathan Wallace has produced
struction. an extraordinary book, full of accurate
The example files provided for each and helpful information and in a for-
chapter are a minor disappointment. Mr Wallace has done an outstanding mat that is eminently useful. While
The component examples reviewed are job assembling this resource. The the HTML files are a disappointment
nothing more than the component Delphi community is well served by in comparison to the quality of the
placed on a form. There are no event this much-needed effort, which, in tan- rest of the book, the usefulness of the
procedures showing the use of the com- dem with the recently published Tomes collected data is excellent.
ponent, nor any properties set program- of Delphi 3 series [Wordware, 1998],
matically. A bit button linked to the brings an additional measure of — Warren Rachele
ShellExecute API function is featured respectability to the Delphi community.
that caused the compilation to fail on Books of this nature are commonplace Nathan Wallace’s Delphi 3 Example
every example attempted; the program in C/C++ circles. By documenting the Book by Nathan Wallace, Wordware
needed the ShellAPI unit included in depth of the Delphi environment, the Publishing, Inc., 2320 Los Rios Blvd.,
the uses directive. When that correction book positions the tool on the same #200, Plano, TX 75074,
is made, the examples will compile and, professional level as the more prevalent (800) 229-4949,
upon execution, the user can click on environments — an important consid- http://www.wordware.com.
this button. It will execute a Web eration because there are still developers
browser and attempt to connect to Mr who immediately dismiss any Pascal- ISBN: 1-55622-490-7
Wallace’s support site. Unfortunately, based tool. Price: US$54.95 (851 Pages, CD-ROM)

From the Trenches
Directions / Commentary
The Dawn of Distributed Computing
A s you read this issue of Delphi Informant, hopefully you are in Denver, the site of BorCon98. This
annual conference provides a chance to receive technical training, network with fellow developers,
and meet some of the people from INPRISE. Historically, this is also the time that INPRISE paints a pic-
ture of what it intends to do for the coming year. The entire conference is surrounded with an air of
optimism and enthusiasm for users of Borland products. To add to the ambiance, I thought I’d share
my views on why I think distributed computing will be a good thing for developers and INPRISE.
Regardless of how you feel about the technology. Essentially, an escalating the developers needed. The shift to
company’s name change, the focus of war between language and compiler distributed computing is no exception.
Borland/INPRISE has been clear over vendors was fought to regain the
the last 18 months: Distributed comput- ground Borland had clearly taken. Distributed computing is viewed by
ing is in the spotlight. Products such as Today, it’s physically impossible to some as a return to mainframe men-
MIDAS, AppCenter, and OLEnterprise, develop software without seeing some tality, but I see this as a golden
the focus on SAP and AS/400 integra- passing reference to OOP. Borland opportunity to share information
tion, and the acquisition of Visigenics didn’t invent OOP, but they certainly across previously impassable bound-
are clear examples of the commitment to brought it to the forefront. aries. Data can be made available
this emerging arena. around the world easily using existing
With the advent and necessity of dis- infrastructures — and at a very rea-
These developments were not pro- tributed computing, INPRISE has sonable cost. The benefits of this
posed and developed in a vacuum. identified the next technology to model are many: centralized business
The reason paradigm shifts occur in show as much promise as OOP did. logic, thin clients, fault tolerance, and
the software development industry is Borland products can continue to load balancing to name just a few.
due to programmers who demand grow and flourish for both small-
more from their compiler vendor, company development shops and The market for developing distributed
tool, and/or language. Think of it as enterprise developers alike, but the computing solutions is ready to explode.
survival of the fittest for development reality is that the computer industry The dawn of distributed computing is
products. As a result of this has shifted more toward enterprise here. You owe it to yourself, and your cus-
Darwinian evolution of development development and, as a result, distrib- tomers, to find out how distributed com-
tools, we no longer have to use things uted multi-tier computing. puting can make your applications better.
like command-line editors and tools. Isn’t that what all of us really want? ∆
In fact, we have the ability to become Rick LeFaivre, Senior Vice President
even more productive because of of Research and Development at — Dan Miser
things like integrated development INPRISE, has a write-up of the waves
environments (IDE), GUI tools, and of technology available at
visual editors. How many people http://www.inprise.com/about/ Dan Miser is a Design Architect for
would really rather be using EDLIN executive/rickmultitier.html. The com- Stratagem, a consulting company in
instead of a visual editor? mon thread through all these waves is Milwaukee. He has been a Borland
innovation. In each case, both end- Certified Client/Server Developer since
Borland captured the OOP market users and developers clamored for 1996, and is a frequent contributor to
nine years ago and spurred its growth more, and the development tools Delphi Informant. You can contact
by remaining on the leading edge of industry responded by providing what him at http://www.execpc.com/~dmiser.

File | New
Directions / Commentary
HTML as a Second Language

F or Delphi developers, the primary language is obviously Object Pascal. For many, assembler and SQL are
important second languages. Increasingly however, HTML is becoming important for all Windows program-
mers, and its implications go beyond the Web; HTML is becoming popular as a language for writing Windows
Help files. Like Rich Text Format (RTF), HTML consists of tags. Among other things, these tags indicate the for-
matting of the text. Recently, with the aim of sharpening my own skills and understanding, I had an opportunity
to examine several new HTML books. I’ll start with a brief overview of those references and then suggest how
HTML might be useful in your Delphi programming.
HTML references. Among the books I However, Dynamic Web Publishing 1996], Charles Calvert shows how to gener-
examined were two comprehensive refer- Unleashed, Second Edition includes useful ate HTML code. In Mastering Delphi 3
ences: Lois Patterson’s Using HTML 4 appendices on HTML 4 and Cascading [SYBEX, 1997], Marco Cantù demonstrates
[QUE, 1997], and HTML 4 Unleashed Style Sheets, one of the important HTML how to produce HTML tables with Delphi.
[Rick Darnell and John Pozadzides, SAMS, extensions. He also discusses CGI and ActiveX in build-
1997]. The former includes an excellent list- ing a “Web Application” with Delphi.
While these two books cover similar ground,
ing of HTML tags in one of its appendices; Finally, in Delphi 2 Multimedia Adventure
their emphasis is slightly different. Dynamic
the latter introduces the tags, systematically Set [The Coriolis Group, 1996], Chris D.
by function, throughout the text. Using Web Publishing Unleashed, Second Edition
Coppola, et al. devote several chapters to
HTML 4 includes a short appendix describ- provides an overview of the issues involved
building a multimedia Web browser. All
ing the tags new to HTML 4. A third work with creating a dynamic Web site; Dynamic
HTML Unleashed puts more emphasis on these examples have one important thing in
by Larry Aronson and Joseph Lowery, common: They use Delphi to create applica-
HTML 3.2 Manual of Style [Ziff Davis the techniques needed to accomplish that
goal. Besides HTML, publishing on the tions that read or write HTML files.
Press, 1997], is somewhat dated and consid-
erably shorter than the previous two. Web often involves additional technologies Hopefully, I’ve convinced you of the
Nevertheless, it provides a wonderful intro- and languages, including Java, ActiveX, need to develop an understanding of
duction to basic HTML. JavaScript, CGI, VRML, and more. While HTML, which, after all, isn’t that diffi-
some of these are specific to one of the two cult. By learning “another language” you
One of the newer developments in HTML major browsers, others are universal. increase your ability to work effectively
relates to building dynamic Web pages that Appropriately, another issue raised in in a field that is quickly becoming more
change in response to a surfer’s actions. The many of these volumes concerns the pro- multi-dimensional. ∆
new extensions to HTML that enable this prietary tags specific to a particular brows-
kind of flexibility are generally referred to as — Alan C. Moore, Ph.D.
er. But how does any of this relate to
Dynamic HTML. While each book men- Delphi programmers? Alan Moore is a Professor of Music at Kentucky
tioned so far deals with dynamic Web pages State University, specializing in music composi-
to some extent, there are two additional vol- The Delphi connection. There are several tion and music theory. He has been developing
umes that concentrate on these new devel- obvious ways we can use Delphi to work education-related applications with the
opments: Dynamic Web Publishing with HTML files: to generate HTML code, Borland languages for more than 10 years. He
Unleashed, Second Edition [Shelley Powers, et to parse and interpret HTML code, and to has published a number of articles in various
al., SAMS, 1997], and Dynamic HTML display HTML code in our own browser. technical journals. Using Delphi, he specializes
Unleashed [Rick Darnell, et al., SAMS, All these topics have come up in Delphi in writing custom components and implement-
1998]. As you might expect, neither of these books and some in articles. In the chapter ing multimedia capabilities in applications,
provides the same comprehensive introduc- “Introduction to CGI Programming with particularly sound and music. You can reach
tion to HTML the earlier books do. Delphi” in his Delphi 2 Unleashed [SAMS, Alan via e-mail at acmdoc@aol.com.
HTML Browser Script Related Cascading

Book Title Tags Issues Languages Technologies Style Sheets
HTML 4 Unleashed Excellent Excellent Excellent Very Good Excellent
Using HTML 4 Very Good Good Excellent Very Good Good
HTML 3.2 Excellent Good Fair Fair Good
Manual of Style
Dynamic HTML Fair Excellent Very Good Good Good
Unleashed
Dynamic Web Publishing Good Good Excellent Excellent Good
Unleashed, Second Edition

On The Cover: August 1998, Volume 4, Number 8

Uploaded by

Copyright:

Available Formats

On The Cover: August 1998, Volume 4, Number 8

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

On The Cover: August 1998, Volume 4, Number 8

Uploaded by

Copyright:

Available Formats

August 1998, Volume 4, Number 8

Cover Art By: Tom McKeith and Doug Smith

ON THE COVER 29 The API Calls

Life after Borland; Long Live Delphi!

2 August 1998 Delphi Informant

3 August 1998 Delphi Informant

4 August 1998 Delphi Informant

5 August 1998 Delphi Informant

6 August 1998 Delphi Informant

As you already know if you’re familiar with Sum(Qty * Price)

Figure 3 shows the Object Inspector with an

Like all other datasets, TClientDataSet has a

The last, named Properties, is an OleVariant output parameter.

Figure 2: Aggregates in the Property Editor.

Figure 4: The TProvider Options property in the

8 August 1998 Delphi Informant

Applying updates to BDE datasets is slower

New Connection Components and Features

10 August 1998 Delphi Informant

This article is based on a prerelease version of Delphi 4. Features

11 August 1998 Delphi Informant

IE4’s DOM Advantage

O ne of the big enhancements to Web/Windows integration was introduced

IE4 introduced Dynamic HTML (DHTML) This hierarchical object representation of an

Individual items in a collection can be

<A HREF="..." ID=SecondLink>...</A>

can be accessed using

DHTML offers many other features, such as

Figure 4: Accessing the document and printing all tags to a

In Delphi 3, you’ll need to use the Component | Import

13 August 1998 Delphi Informant

as the following to ensure the control is ready:

ZoomFont implements the font size code I just described. My

Hooking into the DOM Event Model

15 August 1998 Delphi Informant

Figure 9: The result of using Delphi’s TypeLib Editor to copy dis-

where Document is the IHtmlDocument2 instance, and

The following Usenet groups are some of the best places to

T hree-dimensional graphics is a complicated subject. Entire books have been

Transformations Translation and scaling transformations are

x’ = R * [Cos(a) * Cos(q) - Sin(a) * Sin(q)]

Recall that the point’s original coordinates were given by:

Then, substituting these values into the new equations gives:

The value q is the angle through which the point should be

18 August 1998 Delphi Informant

[1, 2, 3, 1] Cos(q) Sin(q) 0 0

The program declares a Segments array to contain the seg-

Segments : array [0..1000, 1..2] of

The Segment array’s first dimension gives a segment number.

20 August 1998 Delphi Informant

Below the Surface

The program simply draws in order the rectangles that make

21 August 1998 Delphi Informant

The example program Hidden, shown in Figure 8, uses this

// Draw the surface.

22 August 1998 Delphi Informant

The files referenced in this article are available on the Delphi

23 August 1998 Delphi Informant