Developers Guide

Borland

C++Builder 5

for Windows 2000 / 98 / 95 / NTInprise Corporation 100 Enterprise Way, Scotts Valley, CA 95066-3249

Refer to the file DEPLOY.TXT located in the root directory of your C++Builder product for a complete list of files that you can distribute in accordance with the C++Builder License Statement and Limited Warranty. Inprise may have patents and/or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. COPYRIGHT 1983, 2000 Inprise Corporation. All rights reserved. All Inprise and Borland brands and product names are trademarks or registered trademarks of Inprise Corporation. Other product names are trademarks or registered trademarks of their respective holders. Printed in the U.S.A. CPE1350WW21001 3E2R0100 0001020304-9 8 7 6 5 4 3 2 1 PDF

ContentsChapter 1

Introduction

1-1

Whats in this manual? . . . . . . . . . . . . . . 1-1 Manual conventions . . . . . . . . . . . . . . . . 1-2 Contacting developer support . . . . . . . . 1-3

Part I

Programming with C++BuilderChapter 2

Programming with C++BuilderThe integrated development environment Designing applications . . . . . . . . . . . Understanding the VCL. . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . Events . . . . . . . . . . . . . . . . . . . User events . . . . . . . . . . . . . . System events . . . . . . . . . . . . . Objects, components, and controls in the VCL . . . . . . . . . . . . . . . . . . . The TObject branch. . . . . . . . . . . . The TPersistent branch . . . . . . . . . The TComponent branch . . . . . . . . The TControl branch . . . . . . . . . . . The TWinControl branch . . . . . . . . Properties common to TControl . . . . Action properties . . . . . . . . . . . Position, size, and alignment properties . . . . . . . . . . . . . . Display properties . . . . . . . . . . Parent properties . . . . . . . . . . . A navigation property . . . . . . . . Drag-and-drop properties . . . . . . Drag-and-dock properties . . . . . . Standard events common to TControl . Properties common to TWinControl . . General information properties . . . Border style display properties . . . Navigation properties . . . . . . . . Drag-and-dock properties . . . . . . Events common to TWinControl . . . . Creating the application user interface Using components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-12-1 2-2 2-2 2-2 2-2 2-3 2-3 2-3 2-3 2-4 2-5 2-5 2-6 2-7 2-7 2-8

. 2-8 . 2-8 . 2-9 . 2-9 . 2-9 . 2-9 . 2-10 . 2-10 . 2-11 . 2-11 . 2-11 . 2-12 . 2-12 . 2-12 . 2-13

VCL standard components . . . . . . . Text controls . . . . . . . . . . . . . Specialized input controls. . . . . . Buttons and similar controls . . . . Button controls . . . . . . . . . . . . Bitmap buttons . . . . . . . . . . . . Speed buttons . . . . . . . . . . . . Check boxes . . . . . . . . . . . . . Radio buttons . . . . . . . . . . . . Toolbars . . . . . . . . . . . . . . . . Cool bars . . . . . . . . . . . . . . . Handling lists . . . . . . . . . . . . List boxes and check-list boxes . . . Combo boxes . . . . . . . . . . . . . Tree views. . . . . . . . . . . . . . . List views . . . . . . . . . . . . . . . Date-time pickers and month calendars . . . . . . . . . . . . . . Grouping components . . . . . . . Group boxes and radio groups . . . Panels . . . . . . . . . . . . . . . . . Scroll boxes . . . . . . . . . . . . . . Tab controls. . . . . . . . . . . . . . Page controls . . . . . . . . . . . . . Header controls . . . . . . . . . . . Visual feedback . . . . . . . . . . . Labels and static-text components . Status bars . . . . . . . . . . . . . . Progress bars . . . . . . . . . . . . . Help and hint properties . . . . . . Grids . . . . . . . . . . . . . . . . . Draw grids . . . . . . . . . . . . . . String grids . . . . . . . . . . . . . . Graphics display . . . . . . . . . . . Images. . . . . . . . . . . . . . . . . Shapes. . . . . . . . . . . . . . . . . Bevels . . . . . . . . . . . . . . . . . Paint boxes . . . . . . . . . . . . . . Animation control . . . . . . . . . . Windows common dialog boxes . . Using windows common dialog boxes. . . . . . . . . . . . . . . . . Using helper objects . . . . . . . . . . . . Working with lists . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-14 2-15 2-16 2-17 2-17 2-18 2-18 2-18 2-18 2-18 2-19 2-19 2-19 2-20 2-20 2-21 2-21 2-21 2-21 2-22 2-22 2-22 2-22 2-22 2-22 2-23 2-23 2-23 2-23 2-24 2-24 2-24 2-24 2-25 2-25 2-25 2-25 2-25 2-26

. . . 2-26 . . . 2-26 . . . 2-27

i

Working with string lists . . . . . . . . Loading and saving string lists . . . Creating a new string list . . . . . . Manipulating strings in a list . . . . Associating objects with a string list Windows registry and INI files . . . . . Using TINIFile . . . . . . . . . . . . Using TRegistry . . . . . . . . . . . . Using TRegINIFile . . . . . . . . . . Using TCanvas . . . . . . . . . . . . Using TPrinter. . . . . . . . . . . . . Using streams . . . . . . . . . . . . . . . Developing applications . . . . . . . . . . Editing code. . . . . . . . . . . . . . . . Debugging applications . . . . . . . . . Deploying applications . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. 2-27 . 2-27 . 2-28 . 2-29 . 2-31 . 2-31 . 2-32 . 2-33 . 2-33 . 2-34 . 2-34 . 2-35 . 2-35 . 2-35 . 2-35 . 2-36

Chapter 3

Building applications, components, and libraries 3-1Creating applications . . . . . . . . . . . . . . Windows applications . . . . . . . . . . . . User interface models . . . . . . . . . . Setting IDE, project, and compilation options . . . . . . . . . . . . . . . . . . Programming templates . . . . . . . . . . . Console applications . . . . . . . . . . . . . Using the VCL in console applications . Service applications . . . . . . . . . . . . . Service threads . . . . . . . . . . . . . . Service name properties . . . . . . . . . Debugging services . . . . . . . . . . . . Creating packages and DLLs . . . . . . . . . . When to use packages and DLLs . . . . . . Using DLLs in C++Builder . . . . . . . . . . . Creating DLLs in C++Builder . . . . . . . . . Creating DLLs containing VCL components . . . . . . . . . . . . . . . . . . . Linking DLLs . . . . . . . . . . . . . . . . . . . Writing database applications . . . . . . . . . Building distributed applications . . . . . . . Distributing applications using TCP/IP . . Using sockets in applications . . . . . . Creating Web server applications . . . . Distributing applications using COM and DCOM . . . . . . . . . . . . . . . . . COM and DCOM . . . . . . . . . . . . . MTS and COM+ . . . . . . . . . . . . . Distributing applications using CORBA. . . 3-1 . 3-1 . 3-2 . 3-2 . 3-3 . 3-3 . 3-3 . 3-4 . 3-6 . 3-8 . 3-8 . 3-9 . 3-9 . 3-10 . 3-10 . 3-11 . 3-14 . 3-14 . 3-15 . 3-15 . 3-15 . 3-16 . 3-16 . 3-16 . 3-17 . 3-17

Distributing database applications . . . Using data modules and remote data modules . . . . . . . . . . . . . . . . . . . Creating and editing data modules . . . Creating business rules in a data module . . . . . . . . . . . . . . . . Accessing a data module from a form . Adding a remote data module to an application server project . . . . . . . . Using the Object Repository . . . . . . . . . Sharing items within a project . . . . . . Adding items to the Object Repository . Sharing objects in a team environment . Using an Object Repository item in a project . . . . . . . . . . . . . . . . . . Copying an item . . . . . . . . . . . . Inheriting an item . . . . . . . . . . . Using an item. . . . . . . . . . . . . . Using project templates. . . . . . . . . . Modifying shared items . . . . . . . . . Specifying a default project, new form, and main form . . . . . . . . . . . . . .

. . 3-17 . . 3-17 . . 3-18 . . 3-18 . . 3-19 . . . . . . . . . . . . . . . . . . . . . . 3-19 3-19 3-19 3-20 3-20 3-20 3-20 3-21 3-21 3-21 3-21

. . 3-22

Chapter 4

Developing the application user interfaceUnderstanding TApplication, TScreen, and TForm . . . . . . . . . . . . . . . . . . . . Using the main form . . . . . . . . . . . . . Adding additional forms . . . . . . . . . . . Linking forms . . . . . . . . . . . . . . . Hiding the main form. . . . . . . . . . . . . Working at the application level . . . . . . . Handling the screen . . . . . . . . . . . . . . Managing layout . . . . . . . . . . . . . . . Working with messages . . . . . . . . . . . . . More details on forms . . . . . . . . . . . . . . Controlling when forms reside in memory. Displaying an auto-created form. . . . . Creating forms dynamically . . . . . . . Creating modeless forms such as windows . . . . . . . . . . . . . . . . . Using a local variable to create a form instance . . . . . . . . . . . . . . . . . . Passing additional arguments to forms . . . Retrieving data from forms. . . . . . . . . . Retrieving data from modeless forms . . Retrieving data from modal forms. . . .

4-1. 4-1 . 4-1 . 4-2 . 4-2 . 4-2 . 4-3 . 4-3 . 4-3 . 4-4 . 4-5 . 4-5 . 4-5 . 4-5 . 4-6 . 4-7 . 4-7 . 4-8 . 4-8 4-10

ii

Reusing components and groups of components . . . . . . . . . . . . . . . . . . Creating and using component templates . Working with frames . . . . . . . . . . . . . Creating frames. . . . . . . . . . . . . . . Adding frames to the Component palette . . . . . . . . . . . . . . . . . Using and modifying frames . . . . . . . Sharing frames . . . . . . . . . . . . . . . Creating and managing menus. . . . . . . . Opening the Menu Designer . . . . . . . Building menus . . . . . . . . . . . . . . . Naming menus . . . . . . . . . . . . . Naming the menu items . . . . . . . . Adding, inserting, and deleting menu items . . . . . . . . . . . . . . Creating submenus . . . . . . . . . . . Adding images to menu items . . . . Viewing the menu . . . . . . . . . . . Editing menu items in the Object Inspector . . . . . . . . . . . . . . . . . . Using the Menu Designer context menu. Commands on the context menu . . . Switching between menus at design time . . . . . . . . . . . . . . . . . . . Using menu templates . . . . . . . . . . . Saving a menu as a template . . . . . . . Naming conventions for template menu items and event handlers . . . Manipulating menu items at runtime . . Merging menus . . . . . . . . . . . . . . . Specifying the active menu: Menu property . . . . . . . . . . . . . . . . Determining the order of merged menu items: GroupIndex property . Importing resource files . . . . . . . . . . Designing toolbars and cool bars . . . . . . Adding a toolbar using a panel component. . . . . . . . . . . . . . . . . Adding a speed button to a panel. . . Assigning a speed buttons glyph. . . Setting the initial condition of a speed button . . . . . . . . . . . . . . Creating a group of speed buttons . . Allowing toggle buttons . . . . . . . . Adding a toolbar using the toolbar component. . . . . . . . . . . . . . . . . Adding a tool button . . . . . . . . . . Assigning images to tool buttons . . .

. . . . . . . . . . . . . . . .

. 4-12 . 4-12 . 4-13 . 4-13 . 4-14 . 4-14 . 4-15 . 4-15 . 4-16 . 4-17 . 4-18 . 4-18 . 4-19 . 4-20 . 4-22 . 4-22

. . 4-22 . . 4-23 . . 4-23 . . 4-24 . . 4-24 . . 4-25 . . 4-26 . . 4-27 . . 4-27 . . 4-27 . . 4-27 . . 4-28 . . 4-28 . . 4-29 . . 4-30 . . 4-30 . . 4-30 . . 4-31 . . 4-31 . . 4-31 . . 4-32 . . 4-32

Setting tool button appearance and initial conditions . . . . . . . . . . Creating groups of tool buttons . . Allowing toggled tool buttons . . . Adding a cool bar component . . . . . Setting the appearance of the cool bar . . . . . . . . . . . . . . . Responding to clicks . . . . . . . . . . Assigning a menu to a tool button . Adding hidden toolbars . . . . . . . . Hiding and showing toolbars . . . . . Using action lists . . . . . . . . . . . . . . Action objects . . . . . . . . . . . . . . Using Actions . . . . . . . . . . . . . . Centralizing code . . . . . . . . . . Linking properties . . . . . . . . . . Executing actions . . . . . . . . . . Updating actions. . . . . . . . . . . Pre-defined action classes . . . . . . . Standard edit actions . . . . . . . . Standard Window actions. . . . . . Standard Help actions. . . . . . . . DataSet actions . . . . . . . . . . . . Writing action components. . . . . . . How actions find their targets . . . Registering actions. . . . . . . . . . Writing action list editors . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . .

4-33 4-33 4-33 4-34 4-34 4-34 4-35 4-35 4-35 4-36 4-36 4-37 4-38 4-38 4-38 4-40 4-41 4-41 4-41 4-42 4-42 4-43 4-43 4-44 4-45

Chapter 5

Working with controlsImplementing drag-and-drop in controls . Starting a drag operation . . . . . . . . . Accepting dragged items . . . . . . . . . Dropping items . . . . . . . . . . . . . . Ending a drag operation . . . . . . . . . Customizing drag and drop with a drag object . . . . . . . . . . . . . . . . Changing the drag mouse pointer. . . . Implementing drag-and-dock in controls . Making a windowed control a docking site. . . . . . . . . . . . . . . . . . . . . Making a control a dockable child. . . . Controlling how child controls are docked . . . . . . . . . . . . . . . . . . Controlling how child controls are undocked . . . . . . . . . . . . . . . . . Controlling how child controls respond to drag-and-dock operations . . . . . . . . . . . . . . . .

5-1. 5-1 . 5-1 . 5-2 . 5-2 . 5-3

. . . 5-3 . . . 5-4 . . . 5-4 . . . 5-4 . . . 5-4 . . . 5-5 . . . 5-6 . . . 5-6

iii

Working with text in controls. . . . . . . . . Setting text alignment . . . . . . . . . . . Adding scroll bars at runtime . . . . . . . Adding the Clipboard object . . . . . . . Selecting text . . . . . . . . . . . . . . . . Selecting all text . . . . . . . . . . . . . . Cutting, copying, and pasting text . . . . Deleting selected text . . . . . . . . . . . Disabling menu items . . . . . . . . . . . Providing a pop-up menu . . . . . . . . . Handling the OnPopup event. . . . . . . Adding graphics to controls . . . . . . . . . Indicating that a control is owner-drawn Adding graphical objects to a string list . Adding images to an application . . . Adding images to a string list . . . . . Drawing owner-drawn items . . . . . Sizing owner-draw items . . . . . . . . . Drawing each owner-draw item . . . . .

. . . . . . . . . . . . . . . . . . .

. 5-6 . 5-6 . 5-7 . 5-7 . 5-8 . 5-8 . 5-8 . 5-9 . 5-9 . 5-10 . 5-10 . 5-11 . 5-11 . 5-12 . 5-12 . 5-12 . 5-13 . 5-14 . 5-14

Chapter 6

Saving a picture to a file. . . . . . . . Replacing the picture . . . . . . . . . Using the Clipboard with graphics . . . Copying graphics to the Clipboard . Cutting graphics to the Clipboard . . Pasting graphics from the Clipboard Rubber banding example . . . . . . . . . Responding to the mouse . . . . . . . Adding a field to a form object to track mouse actions . . . . . . . . . Refining line drawing . . . . . . . . . Working with multimedia . . . . . . . . . . Adding silent video clips to an application . . . . . . . . . . . . . . . . Example of adding silent video clips . . . . . . . . . . . . . . . . . . Adding audio and/or video clips to an application . . . . . . . . . . . . . . Example of adding audio and/or video clips . . . . . . . . . . . . . .

. . . . . . . .

. . . . . . . .

6-19 6-19 6-20 6-21 6-21 6-21 6-22 6-22

. . 6-25 . . 6-26 . . 6-28 . . 6-28 . . 6-29 . . 6-30 . . 6-32

Working with graphics and multimediaOverview of graphics programming. . . . . Refreshing the screen . . . . . . . . . . . Types of graphic objects . . . . . . . . . . Common properties and methods of Canvas . . . . . . . . . . . . . . . . . . . Using the properties of the Canvas object . . . . . . . . . . . . . . . . . . . Using pens. . . . . . . . . . . . . . . . Using brushes . . . . . . . . . . . . . . Reading and setting pixels . . . . . . . Using Canvas methods to draw graphic objects . . . . . . . . . . . . . . . . . . . Drawing lines and polylines. . . . . . Drawing shapes . . . . . . . . . . . . . Handling multiple drawing objects in your application . . . . . . . . . . . . . Keeping track of which drawing tool to use . . . . . . . . . . . . . . . . . . Changing the tool with speed buttons Using drawing tools . . . . . . . . . . Drawing on a graphic . . . . . . . . . . . Making scrollable graphics . . . . . . Adding an image control . . . . . . . Loading and saving graphics files . . . . Loading a picture from a file . . . . .

Chapter 7

6-1. . 6-1 . . 6-2 . . 6-2 . . 6-3 . . . . . . . . 6-4 6-5 6-7 6-9

Writing multi-threaded applications 7-1Defining thread objects. . . . . . . . . . . . . Initializing the thread . . . . . . . . . . . . Assigning a default priority . . . . . . Indicating when threads are freed . . . Writing the thread function . . . . . . . . Using the main VCL thread. . . . . . . Using thread-local variables . . . . . . Checking for termination by other threads . . . . . . . . . . . . . . . . . Writing clean-up code. . . . . . . . . . . . Coordinating threads . . . . . . . . . . . . . . Avoiding simultaneous access . . . . . . . Locking objects. . . . . . . . . . . . . . Using critical sections . . . . . . . . . . Using the multi-read exclusive-write synchronizer . . . . . . . . . . . . . . Other techniques for sharing memory. Waiting for other threads . . . . . . . . . . Waiting for a thread to finish executing . . . . . . . . . . . . . . . . Waiting for a task to be completed. . . Executing thread objects . . . . . . . . . . . . Overriding the default priority . . . . . . Starting and stopping threads . . . . . . . Debugging multi-threaded applications . . . . . . . . . . . . . . . . . 7-1 . 7-2 . 7-2 . 7-3 . 7-3 . 7-4 . 7-5 . 7-5 . 7-6 . 7-6 . 7-6 . 7-6 . 7-7

. . 6-9 . . 6-9 . . 6-10 . . 6-11 . . . . . . . . . 6-12 . 6-12 . 6-13 . 6-16 . 6-16 . 6-16 . 6-18 . 6-18

. . 7-7 . . 7-8 . . 7-8 . . . . . . . 7-8 . 7-9 7-10 7-10 7-11 7-11

iv

Chapter 8

Exception handlingC++ exception handling. . . . . . . . . . . . ANSI requirements for exception handling . . . . . . . . . . . . . . . . . . Exception handling syntax . . . . . . . . Exception declarations . . . . . . . . . . . Throwing an exception . . . . . . . . . . Examples. . . . . . . . . . . . . . . . . Handling an exception. . . . . . . . . . . Exception specifications . . . . . . . . . . Constructors and destructors in exception handling . . . . . . . . . . . . Unhandled exceptions . . . . . . . . . . . Setting exception handling options . . . Structured exceptions under Win32 . . . . . Syntax of structured exceptions. . . . . . Handling structured exceptions . . . . . Exception filters . . . . . . . . . . . . . . Mixing C++ with structured exceptions . C-based exceptions in C++ program example . . . . . . . . . . . . . . . . Defining exceptions . . . . . . . . . . . . Raising exceptions . . . . . . . . . . . . . Termination blocks . . . . . . . . . . . . . VCL exception handling . . . . . . . . . . . Differences between C++ and VCL exception handling . . . . . . . . . . . . Handling operating system exceptions . Handling VCL exceptions . . . . . . . . . VCL exception classes . . . . . . . . . . . Portability considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-1. . 8-1 8-1 8-2 8-2 8-3 8-3 8-6 8-9

. 8-10 . 8-10 . 8-11 . 8-11 . 8-12 . 8-12 . 8-13 . 8-15 . 8-16 . 8-17 . 8-17 . 8-18 . 8-19 . 8-20 . 8-20 . 8-21 . 8-21 . 8-22

Chapter 9

C++ language support for the VCLC++ and Object Pascal object models . . . . . Object identity and instantiation . . . . . . Distinguishing C++ and Object Pascal references . . . . . . . . . . . . . . . . Copying objects . . . . . . . . . . . . . . Objects as function arguments . . . . . Object construction for C++Builder VCL classes . . . . . . . . . . . . . . . . . C++ object construction . . . . . . . . . Object Pascal object construction . . . . C++Builder object construction . . . . .

9-1. 9-1 . 9-1 . 9-2 . 9-2 . 9-3 . . . . 9-4 9-4 9-4 9-4

Calling virtual methods in base class constructors . . . . . . . . . . . . . . . . Object Pascal model . . . . . . . . . . . C++ model . . . . . . . . . . . . . . . . C++Builder model . . . . . . . . . . . . Example: calling virtual methods . . . Constructor initialization of data members for virtual functions . . . . Object destruction . . . . . . . . . . . . . . Exceptions thrown from constructors . Virtual methods called from destructors . . . . . . . . . . . . . . . AfterConstruction and BeforeDestruction . . . . . . . . . . . . . Class virtual functions . . . . . . . . . . . Support for Object Pascal data types and language concepts. . . . . . . . . . . . . . . Typedefs . . . . . . . . . . . . . . . . . . . Classes that support the Object Pascal language . . . . . . . . . . . . . . . . . . C++ language counterparts to the Object Pascal language . . . . . . . . . . Var parameters . . . . . . . . . . . . . . Untyped parameters. . . . . . . . . . . Open arrays . . . . . . . . . . . . . . . . . Calculating the number of elements . . Temporaries . . . . . . . . . . . . . . . array of const . . . . . . . . . . . . . . . OPENARRAY macro . . . . . . . . . . EXISTINGARRAY macro . . . . . . . . C++ functions that take open array arguments. . . . . . . . . . . . . . . . Types defined differently . . . . . . . . . . Boolean data types. . . . . . . . . . . . Char data types . . . . . . . . . . . . . Resource strings . . . . . . . . . . . . . . . Default parameters . . . . . . . . . . . . . Runtime type information . . . . . . . . . Unmapped types . . . . . . . . . . . . . . 6-byte Real types . . . . . . . . . . . . . Arrays as return types of functions . . Keyword extensions. . . . . . . . . . . . . __classid . . . . . . . . . . . . . . . . . __closure . . . . . . . . . . . . . . . . . __property . . . . . . . . . . . . . . . . __published. . . . . . . . . . . . . . . .

. . . . .

. 9-6 . 9-6 . 9-7 . 9-7 . 9-7

. . 9-8 . . 9-9 . 9-10 . 9-11 . 9-11 . 9-11 . 9-11 . 9-12 . 9-12 . . . . . . . . . . . . . . . . . . . . . . . . 9-12 9-12 9-13 9-13 9-13 9-14 9-14 9-15 9-15 9-15 9-15 9-16 9-16 9-16 9-17 9-18 9-18 9-18 9-19 9-19 9-19 9-19 9-20 9-21

v

The __declspec keyword extension. . __declspec(delphiclass) . . . . . . __declspec(delphireturn). . . . . . __declspec(dynamic) . . . . . . . . __declspec(hidesbase) . . . . . . . __declspec(package) . . . . . . . . __declspec(pascalimplementation)

. . . . . . .

. . . . . . .

. . . . . . .

. 9-21 . 9-21 . 9-22 . 9-22 . 9-22 . 9-23 . 9-23

Chapter 11

Creating international applications 11-1Internationalization and localization . . . . Internationalization . . . . . . . . . . . . Localization . . . . . . . . . . . . . . . . Internationalizing applications . . . . . . . Enabling application code . . . . . . . . Character sets . . . . . . . . . . . . . OEM and ANSI character sets . . . . Double byte character sets . . . . . . Wide characters . . . . . . . . . . . . Including bi-directional functionality in applications . . . . . . . . . . . . BiDiMode property . . . . . . . . . . Locale-specific features . . . . . . . . Designing the user interface . . . . . . . Text . . . . . . . . . . . . . . . . . . . Graphic images . . . . . . . . . . . . Formats and sort order . . . . . . . . Keyboard mappings . . . . . . . . . . Isolating resources. . . . . . . . . . . . . Creating resource DLLs. . . . . . . . . . Using resource DLLs . . . . . . . . . . . Dynamic switching of resource DLLs . . Localizing applications . . . . . . . . . . . . Localizing resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 11-1 11-1 11-2 11-2 11-2 11-2 11-2 11-3

Chapter 10

Working with packages and componentsWhy use packages? . . . . . . . . . . . . . . Packages and standard DLLs . . . . . . . Runtime packages . . . . . . . . . . . . . . . Using packages in an application. . . . . Dynamically loading packages . . . . . . Deciding which runtime packages to use Custom packages . . . . . . . . . . . . . . Design-time packages . . . . . . . . . . . . . Installing component packages . . . . . . Creating and editing packages . . . . . . . . Creating a package . . . . . . . . . . . . . Editing an existing package . . . . . . . . Package source files and project option files. . . . . . . . . . . . . . . . . Packaging components. . . . . . . . . Understanding the structure of a package . . . . . . . . . . . . . . . . . . Naming packages . . . . . . . . . . . . The Requires list . . . . . . . . . . . . The Contains list . . . . . . . . . . . . Compiling packages . . . . . . . . . . . . Package-specific compiler directives . . . . . . . . . . . . . . . . Using the command-line compiler and linker . . . . . . . . . . . . . . . Package files created by a successful compilation . . . . . . . . . . . . . . Deploying packages . . . . . . . . . . . . . . Deploying applications that use packages . . . . . . . . . . . . . . . . . . Distributing packages to other developers . . . . . . . . . . . . . . . . . Package collection files . . . . . . . . . . . . . . . . . . . . . .

10-1. 10-2 . 10-2 . 10-2 . 10-2 . 10-3 . 10-3 . 10-4 . 10-4 . 10-5 . 10-6 . 10-6 . 10-7

. . 10-7 . . 10-8 . . . . . . 10-9 . 10-9 . 10-9 10-10 10-10

. 11-3 . 11-5 . 11-7 . 11-8 . 11-8 . 11-8 . 11-8 . 11-9 . 11-9 . 11-9 .11-10 .11-11 .11-12 .11-12

Chapter 12

Deploying applicationsDeploying general applications . . . Using installation programs . . . Identifying application files . Application files . . . . . . . . Package files . . . . . . . . . . ActiveX controls . . . . . . . . Helper applications . . . . . . DLL locations. . . . . . . . . . Deploying database applications . . Providing the database engine . . Borland Database Engine . . . Third-party database engines SQL Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12-1. . . . . . . . . . . . . 12-1 12-2 12-2 12-2 12-3 12-3 12-3 12-3 12-4 12-4 12-4 12-5 12-5

. 10-10 . 10-12 . 10-12 . 10-13 . 10-13 . 10-13 . 10-13

vi

Multi-tiered Distributed Application Services (MIDAS) . . . . . . . . . . . Deploying Web applications . . . . . . . Programming for varying host environments . . . . . . . . . . . . . . . Screen resolutions and color depths . Considerations when not dynamically resizing . . . . . . . . Considerations when dynamically resizing forms and controls . . . Accommodating varying color depths . . . . . . . . . . . . . . . Fonts . . . . . . . . . . . . . . . . . . . Windows versions . . . . . . . . . . . Software license requirements . . . . . . DEPLOY.TXT . . . . . . . . . . . . . . README.TXT . . . . . . . . . . . . . No-nonsense license agreement . . . Third-party product documentation .

. . . . 12-6 . . . . 12-6 . . . . 12-6 . . . . 12-7 . . . . 12-7 . . . . 12-7 . . . . . . . . . . . . . . . . . . . . . . . . . 12-8 . 12-9 . 12-9 12-10 12-10 12-10 12-10 12-10

Chapter 14

Building one- and two-tiered applicationsBDE-based applications . . . . . . . . . . BDE-based architecture . . . . . . . . . Understanding databases and datasets . . . . . . . . . . . . . . . Using sessions . . . . . . . . . . . . Connecting to databases . . . . . . . . Using transactions. . . . . . . . . . . . Explicitly controlling transactions . Using a database component for transactions . . . . . . . . . . . . . Using the TransIsolation property . Using passthrough SQL . . . . . . . Using local transactions . . . . . . . Caching updates. . . . . . . . . . . . . Creating and restructuring database tables . . . . . . . . . . . . . . . . . . ADO-based applications . . . . . . . . . . ADO-based architecture . . . . . . . . Understanding ADO databases and datasets. . . . . . . . . . . . . Connecting to ADO databases . . . . . Retrieving data . . . . . . . . . . . . . Creating and restructuring ADO database tables . . . . . . . . . . . . . Flat-file database applications . . . . . . . Creating the datasets . . . . . . . . . . Creating a new dataset using persistent fields. . . . . . . . . . . Creating a dataset using field and index definitions . . . . . . . . . . Creating a dataset based on an existing table . . . . . . . . . . . . Loading and saving data . . . . . . . . Using the briefcase model . . . . . . . Scaling up to a three-tiered application .

14-1. . . 14-2 . . . 14-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3 14-3 14-4 14-5 14-5 14-6 14-7 14-8 14-8 14-9

Part II

Developing database applicationsChapter 13

. . 14-10 . . 14-10 . . 14-10 . . .14-11 . . .14-11 . . 14-12 . . 14-12 . . 14-13 . . 14-14 . . 14-14 . . 14-14 . . . . . . . . 14-15 14-16 14-16 14-17

Designing database applicationsUsing databases . . . . . . . . . . . . . . . . Types of databases . . . . . . . . . . . . . Local databases . . . . . . . . . . . . . Remote database servers . . . . . . . . Database security. . . . . . . . . . . . . . Transactions . . . . . . . . . . . . . . . . . Data Dictionary . . . . . . . . . . . . . . . Referential integrity, stored procedures, and triggers . . . . . . . . . . . . . . . . Database architecture . . . . . . . . . . . . . Planning for scalability . . . . . . . . . . Single-tiered database applications . . . Two-tiered database applications. . . . . Multi-tiered database applications . . . . Designing the user interface . . . . . . . . . Displaying a single record. . . . . . . . . Displaying multiple records. . . . . . . . Analyzing data . . . . . . . . . . . . . . . Selecting what data to show . . . . . . . Writing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13-1. 13-1 . 13-2 . 13-2 . 13-2 . 13-3 . 13-3 . 13-4 . 13-5 . 13-6 . 13-7 . 13-8 . 13-9 . 13-9 13-11 13-11 13-12 13-12 13-13 13-15

Chapter 15

Creating multi-tiered applications

15-1

Advantages of the multi-tiered database model . . . . . . . . . . . . . . . . . . . . . . . 15-2 Understanding MIDAS technology . . . . . . . 15-2 Overview of a MIDAS-based multi-tiered application. . . . . . . . . . . 15-3

vii

The structure of the client application . . The structure of the application server. . Using transactional data modules . . Pooling remote data modules . . . . . Using the IAppServer interface . . . . Choosing a connection protocol . . . . . Using DCOM connections . . . . . . . Using Socket connections . . . . . . . Using Web connections. . . . . . . . . Building a multi-tiered application . . . . . Creating the application server. . . . . . . . Setting up the remote data module. . . . Configuring the remote data module when it is not transactional . . . . . . . . . . . . . . Configuring a transactional remote data module . . . . . . . . . . . . . . Creating a data provider for the application server. . . . . . . . . . . . . Extending the application servers interface . . . . . . . . . . . . . . . . . . Adding callbacks to the application servers interface . . . . . . . . . . . Extending a transactional application servers interface . . . . . . . . . . . Creating the client application . . . . . . . . Connecting to the application server. . . Specifying a connection using DCOM . . . . . . . . . . . . . . . . . Specifying a connection using sockets . . . . . . . . . . . . . . . . . Specifying a connection using HTTP . . . . . . . . . . . . . . . . . . Brokering connections . . . . . . . . . Managing server connections . . . . . . . Connecting to the server . . . . . . . . Dropping or changing a server connection . . . . . . . . . . . . . . . Calling server interfaces . . . . . . . . . . Managing transactions in multi-tiered applications . . . . . . . . . . . . . . . . . . Supporting master/detail relationships . . . Supporting state information in remote data modules . . . . . . . . . . . . . . . . . Writing MIDAS Web applications . . . . . . Distributing a client application as an ActiveX control . . . . . . . . . . . . . . Creating an Active Form for the client application . . . . . . . . . . .

. . . . . . . . . . . .

. 15-4 . 15-4 . 15-5 . 15-7 . 15-8 . 15-9 . 15-9 . 15-9 15-10 15-11 15-11 15-13

. 15-13 . 15-14 . 15-15 . 15-15 . 15-16 . 15-16 . 15-16 . 15-17 . 15-18 . 15-18 . . . . 15-19 15-19 15-20 15-20

Building Web applications using InternetExpress . . . . . . . . . . . . Building an InternetExpress application . . . . . . . . . . . . . Using the javascript libraries . . . . Granting permission to access and launch the application server . . . Using an XML broker . . . . . . . . . . Fetching XML data packets . . . . . Applying updates from XML delta packets . . . . . . . . . . . . Creating Web pages with a MIDAS page producer . . . . . . . . . . . . . Using the Web page editor . . . . . Setting Web item properties . . . . Customizing the MIDAS page producer template . . . . . . . . .

. . 15-27 . . 15-27 . . 15-28 . . 15-29 . . 15-30 . . 15-30 . . 15-31 . . 15-32 . . 15-32 . . 15-33 . . 15-34

Chapter 16

Using provider componentsDetermining the source of data . . . . . . . . Choosing how to apply updates . . . . . . . Controlling what information is included in data packets. . . . . . . . . . . . . . . . . Specifying what fields appear in data packets . . . . . . . . . . . . . . . . . . . Setting options that influence the data packets . . . . . . . . . . . . . . . . . . . Adding custom information to data packets . . . . . . . . . . . . . . . . . . . Responding to client data requests . . . . . . Responding to client update requests . . . . Editing delta packets before updating the database . . . . . . . . . . . . . . . . Influencing how updates are applied . . . Screening individual updates . . . . . . . Resolving update errors on the provider . Applying updates to datasets that do not represent a single table . . . . . . . . . . Responding to client-generated events . . . . Handling server constraints . . . . . . . . . .

16-1. 16-1 . 16-2 . 16-2 . 16-2 . 16-3 . 16-4 . 16-5 . 16-6 . . . . 16-6 16-7 16-9 16-9

. 15-20 . 15-21 . 15-21 . 15-22 . 15-23 . 15-24 . 15-26 . 15-26

. 16-9 16-10 16-10

Chapter 17

Managing database sessionsWorking with a session component. Using the default session . . . . . Creating additional sessions . . . Naming a session . . . . . . . . . Activating a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17-1. . . . . 17-1 17-2 17-3 17-4 17-4

viii

Customizing session start-up . . . . . . . Specifying default database connection behavior . . . . . . . . . . . . . . . . . . Creating, opening, and closing database connections . . . . . . . . . . . . . . . . Closing a single database connection. Closing all database connections . . . Dropping temporary database connections . . . . . . . . . . . . . . . . Searching for a database connection . . . Retrieving information about a session . Working with BDE aliases . . . . . . . . . Specifying alias visibility. . . . . . . . Making session aliases visible to other sessions and applications . . . Determining known aliases, drivers, and parameters . . . . . . . . . . . . Creating, modifying, and deleting aliases . . . . . . . . . . . . . . . . . Iterating through a sessions database components . . . . . . . . . . . . . . . . Specifying Paradox directory locations . Specifying the control file location . . Specifying a temporary files location . . . . . . . . . . . . . . . . . Working with password-protected Paradox and dBASE tables . . . . . . . Using the AddPassword method . . . Using the RemovePassword and RemoveAllPasswords methods . . . Using the GetPassword method and OnPassword event . . . . . . . . Managing multiple sessions . . . . . . . . . Using a session component in data modules . . . . . . . . . . . . . . . . . . . .

. . 17-5 . . 17-6 . . 17-6 . . 17-7 . . 17-7 . . . . . . 17-7 . 17-8 . 17-8 . 17-9 17-10

. 17-10 . 17-10 . 17-10 . 17-12 . 17-12 . 17-13 . 17-13 . 17-13 . 17-13 . 17-14 . 17-14 . 17-16 . 17-17

Setting BDE alias parameters . . . . . . Controlling server login . . . . . . . . . Connecting to a database server . . . . . Special considerations when connecting to a remote server . . . . . . . . . . . . Working with network protocols. . . Using ODBC . . . . . . . . . . . . . . Disconnecting from a database server . Closing datasets without disconnecting from a server . . . . . . . . . . . . . . . Iterating through a database components datasets . . . . . . . . . . Understanding database and session component interactions. . . . . . . . . . . Using database components in data modules . . . . . . . . . . . . . . . . . . . . Executing SQL statements from a TDatabase component . . . . . . . . . . . Executing SQL statements from TDatabase . . . . . . . . . . . . . . . . Executing parameterized SQL statements . . . . . . . . . . . . . . . .

. . 18-5 . . 18-6 . . 18-7 . . . . . . . . 18-8 18-8 18-8 18-9

. . 18-9 . . 18-9 . . 18-9 . 18-10 . 18-10 . 18-10 . .18-11

Chapter 19

Understanding datasetsWhat is TDataSet?. . . . . . . . . . . . . Types of datasets . . . . . . . . . . . . . Opening and closing datasets . . . . . . Determining and setting dataset states . Inactivating a dataset . . . . . . . . . Browsing a dataset . . . . . . . . . . Enabling dataset editing . . . . . . . Enabling insertion of new records . . Enabling index-based searches and ranges on tables . . . . . . . . . . . Calculating fields . . . . . . . . . . . Filtering records . . . . . . . . . . . . Updating records . . . . . . . . . . . Navigating datasets. . . . . . . . . . . . Using the First and Last methods . . Using the Next and Prior methods . Using the MoveBy method . . . . . . Using the Eof and Bof properties . . Eof . . . . . . . . . . . . . . . . . . Bof . . . . . . . . . . . . . . . . . . Marking and returning to records . . Searching datasets . . . . . . . . . . . . Using Locate . . . . . . . . . . . . . . Using Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19-1. . . . . . . . 19-2 19-2 19-3 19-3 19-5 19-6 19-7 19-7

Chapter 18

Connecting to databasesUnderstanding persistent and temporary database components. . . . . . Using temporary database components . Creating database components at design time . . . . . . . . . . . . . . . . Creating database components at runtime . . . . . . . . . . . . . . . . . . Controlling connections . . . . . . . . . . . . Associating a database component with a session . . . . . . . . . . . . . . . Specifying a BDE alias . . . . . . . . . . .

18-1. . 18-1 . . 18-2 . . 18-2 . . 18-3 . . 18-4 . . 18-4 . . 18-4

. 19-8 . 19-8 . 19-9 . 19-9 . 19-9 19-10 19-10 .19-11 .19-11 .19-11 19-12 19-13 19-15 19-15 19-16

ix

Displaying and editing a subset of data using filters . . . . . . . . . . . . . . . . . Enabling and disabling filtering . . . . Creating filters . . . . . . . . . . . . . . Setting the Filter property . . . . . . . . Writing an OnFilterRecord event handler. . . . . . . . . . . . . . . . . . Switching filter event handlers at runtime . . . . . . . . . . . . . . Setting filter options . . . . . . . . . . . Navigating records in a filtered dataset Modifying data. . . . . . . . . . . . . . . . Editing records . . . . . . . . . . . . . . Adding new records . . . . . . . . . . . Inserting records . . . . . . . . . . . Appending records . . . . . . . . . . Deleting records . . . . . . . . . . . . . Posting data to the database . . . . . . Canceling changes . . . . . . . . . . . . Modifying entire records . . . . . . . . Using dataset events. . . . . . . . . . . . . Aborting a method . . . . . . . . . . . . Using OnCalcFields . . . . . . . . . . . Using BDE-enabled datasets . . . . . . . . Overview of BDE-enablement . . . . . Handling database and session connections . . . . . . . . . . . . . . . Using the DatabaseName and SessionName properties . . . . . . Working with BDE handle properties . . . . . . . . . . . . . . Using cached updates . . . . . . . . . . Caching BLOBs . . . . . . . . . . . . . .

. . . .

. . . .

19-17 19-17 19-17 19-18

. . 19-19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-19 19-19 19-20 19-21 19-21 19-22 19-23 19-23 19-23 19-23 19-24 19-24 19-26 19-26 19-26 19-27 19-28

. . 19-28 . . 19-29 . . 19-29 . . 19-29 . . 19-30

Chapter 20

Working with field componentsUnderstanding field components . Dynamic field components . . . Persistent field components . . . Creating persistent fields . . . . . . Arranging persistent fields . . . . . Defining new persistent fields . . . Defining a data field . . . . . . . Defining a calculated field. . . . Programming a calculated field Defining a lookup field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

20-1. 20-2 . 20-3 . 20-4 . 20-5 . 20-6 . 20-6 . 20-7 . 20-8 . 20-9 . 20-9

Defining an aggregate field . . . . . . Deleting persistent field components . Setting persistent field properties and events . . . . . . . . . . . . . . . . . Setting display and edit properties at design time . . . . . . . . . . . . . Setting field component properties at runtime . . . . . . . . . . . . . . . Creating attribute sets for field components . . . . . . . . . . . . . . Associating attribute sets with field components . . . . . . . . . . . . . . Removing attribute associations . . . . Controlling and masking user input . Using default formatting for numeric, date, and time fields. . . . . . . . . . Handling events . . . . . . . . . . . . . Working with field component methods at runtime . . . . . . . . . . . . . . . . . Displaying, converting, and accessing field values. . . . . . . . . . . . . . . . . Displaying field component values in standard controls . . . . . . . . . . Converting field values . . . . . . . . . Accessing field values with the default dataset property . . . . . . . Accessing field values with a datasets Fields property. . . . . . . . . . . . . Accessing field values with a datasets FieldByName method. . . . . . . . . Checking a fields current value. . . . . . Setting a default value for a field . . . . . Working with constraints . . . . . . . . . Creating a custom constraint. . . . . . Using server constraints . . . . . . . . Using object fields . . . . . . . . . . . . . Displaying ADT and array fields . . . Working with ADT fields. . . . . . . . Accessing ADT field values. . . . . Working with array fields . . . . . . . Accessing array field values . . . . Working with dataset fields . . . . . . Displaying dataset fields . . . . . . Accessing data in a nested dataset . Working with reference fields . . . . . Displaying reference fields . . . . . Accessing data in a reference field .

. . .20-11 . . 20-12 . . 20-12 . . 20-12 . . 20-14 . . 20-14 . . 20-15 . . 20-15 . . 20-15 . . 20-16 . . 20-17 . . 20-17 . . 20-18 . . 20-18 . . 20-19 . . 20-20 . . 20-20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21 20-21 20-21 20-22 20-22 20-22 20-23 20-24 20-24 20-24 20-25 20-25 20-26 20-26 20-26 20-27 20-27 20-27

x

Chapter 21

Working with tablesUsing table components. . . . . . . . . . . . Setting up a table component. . . . . . . . . Specifying a database location . . . . . . Specifying a table name . . . . . . . . . . Specifying the table type for local tables. Opening and closing a table. . . . . . . . Controlling read/write access to a table. . . Searching for records . . . . . . . . . . . . . Searching for records based on indexed fields . . . . . . . . . . . . . . . Executing a search with Goto methods . . . . . . . . . . . . . . . . Executing a search with Find methods . . . . . . . . . . . . . . . . Specifying the current record after a successful search . . . . . . . . . . Searching on partial keys . . . . . . . Searching on alternate indexes . . . . Repeating or extending a search . . . Sorting records . . . . . . . . . . . . . . . . . Retrieving a list of available indexes with GetIndexNames . . . . . . . . . . Specifying an index with IndexName . . Specifying a dBASE index file . . . . . Specifying sort order for SQL tables . . . Specifying fields with IndexFieldNames . . . . . . . . . . . Examining the field list for an index . . . Working with a subset of data . . . . . . . . Understanding the differences between ranges and filters. . . . . . . . Creating and applying a new range . . . Setting the beginning of a range . . . Setting the end of a range . . . . . . . Setting start- and end-range values . . Specifying a range based on partial keys . . . . . . . . . . . . . . . . . . . Including or excluding records that match boundary values . . . . . Applying a range . . . . . . . . . . . . Canceling a range . . . . . . . . . . . . Modifying a range . . . . . . . . . . . . . Editing the start of a range. . . . . . . Editing the end of a range . . . . . . . Deleting all records in a table . . . . . . . . . Deleting a table. . . . . . . . . . . . . . . . . Renaming a table. . . . . . . . . . . . . . . . . . . . . . . .

21-1. 21-1 . 21-2 . 21-2 . 21-3 . 21-3 . 21-4 . 21-4 . 21-5

. . 21-5 . . 21-6 . . 21-7 . . . . . . . . . . 21-7 . 21-7 . 21-8 . 21-8 . 21-8 . 21-9 . 21-9 . 21-9 21-10

Creating a table . . . . . . . . . . . . . . Importing data from another table . . . Using TBatchMove . . . . . . . . . . . . Creating a batch move component . Specifying a batch move mode . . . Appending records . . . . . . . . Updating records . . . . . . . . . Appending and updating records Copying datasets. . . . . . . . . . Deleting records . . . . . . . . . . Mapping data types . . . . . . . . . . Executing a batch move. . . . . . . . Handling batch move errors . . . . . Synchronizing tables linked to the same database table . . . . . . . . . . . Creating master/detail forms . . . . . . Building an example master/detail form . . . . . . . . . . . . . . . . . . Working with nested tables . . . . . . . Setting up a nested table component

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

21-17 21-19 21-19 21-20 21-21 21-21 21-21 21-22 21-22 21-22 21-22 21-23 21-23

. . . 21-24 . . . 21-25 . . . 21-25 . . . 21-26 . . . 21-26

Chapter 22

Working with queriesUsing queries effectively . . . . . . . . . . Queries for desktop developers . . . . Queries for server developers . . . . . What databases can you access with a query component? . . . . . . . . . . . Using a query component: an overview . Specifying the SQL statement to execute . Specifying the SQL property at design time . . . . . . . . . . . . . . . Specifying an SQL statement at runtime . . . . . . . . . . . . . . . . . Setting the SQL property directly . Loading the SQL property from a file . . . . . . . . . . . . . . . . . Loading the SQL property from string list object. . . . . . . . . . . Setting parameters . . . . . . . . . . . . . Supplying parameters at design time . Supplying parameters at runtime . . . Using a data source to bind parameters . . . . . . . . . . . . . . . Executing a query . . . . . . . . . . . . . . Executing a query at design time . . . Executing a query at runtime . . . . . Executing a query that returns a result set. . . . . . . . . . . . . . .

22-1. . . 22-1 . . . 22-2 . . . 22-3 . . . 22-4 . . . 22-4 . . . 22-5 . . . 22-6 . . . 22-7 . . . 22-7 . . . 22-8 . . . . . . . . . . . . . . . . . 22-8 . 22-8 . 22-9 22-10 22-10 22-12 22-12 22-12

. 21-11 . 21-11 . 21-11 . . . . . 21-11 21-12 21-12 21-13 21-14

. 21-14 . . . . . . . . . 21-15 21-15 21-15 21-15 21-16 21-16 21-16 21-16 21-17

. . 22-13

xi

Executing a query without a result set . . . . . . . . . . . . . . . Preparing a query . . . . . . . . . . . . . . Unpreparing a query to release resources . Creating heterogeneous queries . . . . . . Improving query performance . . . . . . . Disabling bi-directional cursors. . . . . Working with result sets . . . . . . . . . . Enabling editing of a result set . . . . . Local SQL requirements for a live result set . . . . . . . . . . . . . . . . . Restrictions on live queries . . . . . Remote server SQL requirements for a live result set . . . . . . . . . . . . . Restrictions on updating a live result set. . . . . . . . . . . . . . . . . . . . . Updating a read-only result set . . . . .

. . . . . . . .

. . . . . . . .

22-13 22-13 22-14 22-14 22-15 22-15 22-16 22-16

Using the result parameter . . . . . . Accessing parameters at design time Setting parameter information at design time . . . . . . . . . . . . . . Creating parameters at runtime . . . Binding parameters . . . . . . . . . . Viewing parameter information at design time. . . . . . . . . . . . . . . . Working with Oracle overloaded stored procedures . . . . . . . . . . . . . . . .

. . . 23-12 . . . 23-12 . . . 23-13 . . . 23-14 . . . 23-15 . . . 23-15 . . . 23-16

. . 22-16 . . 22-17 . . 22-17 . . 22-17 . . 22-17

Chapter 24

Working with ADO componentsOverview of ADO components . . . . . . Connecting to ADO data stores . . . . . . Connecting to a data store using TADOConnection . . . . . . . . . . . Using a TADOConnection versus a datasets ConnectionString . . . Specifying the connection. . . . . . Accessing the connection object . . Activating and deactivating the connection . . . . . . . . . . . . . Determining what a connection component is doing . . . . . . . . Fine-tuning a connection . . . . . . . . Specifying connection attributes . . Controlling timeouts . . . . . . . . Controlling the connection login . . Listing tables and stored procedures . Accessing the connections datasets . . . . . . . . . . . . . . . Accessing the connections commands . . . . . . . . . . . . . Listing available tables . . . . . . . Listing available stored procedures Working with (connection) transactions. . . . . . . . . . . . . . . Using transaction methods . . . . . Using transaction events . . . . . . Using ADO datasets . . . . . . . . . . . . Features common to all ADO dataset components . . . . . . . . . . . . . . Modifying data. . . . . . . . . . . . Navigating in a dataset . . . . . . . Using visual data-aware controls . Connecting to a data store using ADO dataset components . . . . . Working with record sets . . . . . .

24-1. . . 24-1 . . . 24-2 . . . 24-3 . . . 24-3 . . . 24-3 . . . 24-4 . . . 24-4 . . . . . . . . . . . . . . . . . . 24-5 24-5 24-5 24-7 24-7 24-8

Chapter 23

Working with stored proceduresWhen should you use stored procedures? . Using a stored procedure . . . . . . . . . . . Creating a stored procedure component. Creating a stored procedure. . . . . . . . Preparing and executing a stored procedure . . . . . . . . . . . . . . . . . Using stored procedures that return result sets . . . . . . . . . . . . . . . . . Retrieving a result set with a TQuery . . . . . . . . . . . . . . . . . Retrieving a result set with a TStoredProc . . . . . . . . . . . . . . Using stored procedures that return data using parameters . . . . . . . . . . Retrieving individual values with a TQuery . . . . . . . . . . . . . . . . Retrieving individual values with a TStoredProc . . . . . . . . . . . . . . Using stored procedures that perform actions on data . . . . . . . . . . . . . . Executing an action stored procedure with a TQuery . . . . . . . . . . . . . Executing an action stored procedure with a TStoredProc . . . . . . . . . . Understanding stored procedure parameters . . . . . . . . . . . . . . . . . . Using input parameters . . . . . . . . . . Using output parameters . . . . . . . . . Using input/output parameters . . . . . . . . .

23-1. 23-2 . 23-2 . 23-3 . 23-4

. . 23-5 . . 23-5 . . 23-5 . . 23-6 . . 23-7 . . 23-7 . . 23-7 . . 23-8 . . 23-8 . . 23-9 . . . . 23-10 23-10 23-11 23-11

. . . 24-8 . . . 24-8 . . . 24-9 . . 24-10 . . . . . . . . . . . . . . . . 24-10 24-10 24-10 .24-11 .24-11 .24-11 24-12 24-12

. . 24-13 . . 24-13

xii

Using batch updates . . . . . . . . . Loading data from and saving data to files . . . . . . . . . . . . . . . . Using parameters in commands . . Using TADODataSet . . . . . . . . . . . Retrieving a dataset using a command . . . . . . . . . . . . . . Using TADOTable . . . . . . . . . . . . Specifying the table to use . . . . . . Using TADOQuery. . . . . . . . . . . . Specifying SQL statements . . . . . Executing SQL statements . . . . . . Using TADOStoredProc . . . . . . . . . Specifying the stored procedure . . Executing the stored procedure . . . Using parameters with stored procedures . . . . . . . . . . . . . . Executing commands . . . . . . . . . . . . Specifying the command . . . . . . . . Using the Execute method. . . . . . . . Canceling commands . . . . . . . . . . Retrieving result sets with commands . Handling command parameters . . . .

. . 24-14 . . 24-16 . . 24-17 . . 24-18 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-18 24-19 24-19 24-20 24-20 24-21 24-21 24-22 24-23 24-23 24-25 24-26 24-26 24-27 24-27 24-28

Chapter 25

Creating and using a client dataset 25-1Working with data using a client dataset . Navigating data in client datasets . . . Limiting what records appear. . . . . . Representing master/detail relationships. . . . . . . . . . . . . . . Constraining data values . . . . . . . . Making data read-only. . . . . . . . . . Editing data . . . . . . . . . . . . . . . . Undoing changes . . . . . . . . . . . Saving changes . . . . . . . . . . . . Sorting and indexing. . . . . . . . . . . Adding a new index . . . . . . . . . Deleting and switching indexes . . . Using indexes to group data. . . . . Representing calculated values . . . . . Using internally calculated fields in client datasets. . . . . . . . . . . Using maintained aggregates . . . . . . Specifying aggregates . . . . . . . . Aggregating over groups of records Obtaining aggregate values . . . . . Adding application-specific information to the data. . . . . . . . . . . . 25-2 . . . 25-2 . . . 25-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-3 . 25-3 . 25-4 . 25-4 . 25-5 . 25-5 . 25-6 . 25-6 . 25-7 . 25-7 . 25-8 . 25-9 . 25-9 25-10 25-11 25-11

Copying data from another dataset . . . . Assigning data directly . . . . . . . . . Cloning a client dataset cursor. . . . . Using a client dataset with a data provider . . . . . . . . . . . . . . . . . . Specifying a data provider . . . . . . . Getting parameters from the application server . . . . . . . . . . . Passing parameters to the application server . . . . . . . . . . . Sending query or stored procedure parameters . . . . . . . . . . . . . Limiting records with parameters . Overriding the dataset on the application server . . . . . . . . . . . Requesting data from an application server . . . . . . . . . . . . . . . . . . Handling constraints . . . . . . . . . . Handling constraints from the server . . . . . . . . . . . . . . . . Adding custom constraints . . . . . Updating records . . . . . . . . . . . . Applying updates . . . . . . . . . . Reconciling update errors. . . . . . Refreshing records. . . . . . . . . . . . Communicating with providers using custom events. . . . . . . . . . Using a client dataset with flat-file data . Creating a new dataset . . . . . . . . . Loading data from a file or stream . . Merging changes into data . . . . . . . Saving data to a file or stream . . . . .

. . 25-12 . . 25-12 . . 25-13 . . 25-14 . . 25-14 . . 25-15 . . 25-15 . . 25-16 . . 25-16 . . 25-17 . . 25-17 . . 25-18 . . . . . . . . . . . . . . . . . . . . . . . . 25-19 25-19 25-20 25-20 25-21 25-22 25-23 25-24 25-24 25-24 25-25 25-25

Chapter 26

Working with cached updatesDeciding when to use cached updates . . . Using cached updates . . . . . . . . . . . . Enabling and disabling cached updates Fetching records . . . . . . . . . . . . . . Applying cached updates . . . . . . . . Applying cached updates with a database component method . . . . Applying cached updates with dataset component methods . . . . Applying updates for master/detail tables . . . . . . . . . Canceling pending cached updates . . . Canceling pending updates and disabling further cached updates . . . . . .

26-1. . . . . 26-1 26-2 26-3 26-4 26-4

. . 26-5 . . 26-6 . . 26-6 . . 26-7 . . 26-8

. . 25-12

xiii

Canceling pending cached updates. Canceling updates to the current record . . . . . . . . . . . . . . . . Undeleting cached records . . . . . . . Specifying visible records in the cache . . . . . . . . . . . . . . . . . . . Checking update status . . . . . . . . . Using update objects to update a dataset . . . . . . . . . . . . . . . . . . . . Specifying the UpdateObject property for a dataset . . . . . . . . . Using a single update object . . . . . Using multiple update objects. . . . Creating SQL statements for update components . . . . . . . . . . . . . . . Creating SQL statements at design time . . . . . . . . . . . . . Understanding parameter substitution in update SQL statements . . . . . . . . . . . . . . Composing update SQL statements . . . . . . . . . . . . . . Using an update components Query property . . . . . . . . . . . Using the DeleteSQL, InsertSQL, and ModifySQL properties . . . . Executing update statements . . . . . . Calling the Apply method . . . . . . Calling the SetParams method . . . Calling the ExecSQL method . . . . Using dataset components to update a dataset . . . . . . . . . . . . . . . . . Updating a read-only result set . . . . . . Controlling the update process. . . . . . . Determining if you need to control the updating process . . . . . . . . . . Creating an OnUpdateRecord event handler. . . . . . . . . . . . . . . . . . Handling cached update errors . . . . . . Referencing the dataset to which to apply updates . . . . . . . . . . . . . . Indicating the type of update that generated an error . . . . . . . . . . . Specifying the action to take . . . . . . Working with error message text . . . . Accessing a fields OldValue, NewValue, and CurValue properties . . . . . . . . . . . . . . . .

. . . 26-8 . . . 26-8 . . . 26-9 . . . 26-9 . . 26-10 . . 26-11 . . 26-12 . . 26-12 . . 26-12 . . 26-13 . . 26-13

Chapter 27

Using data controlsUsing common data control features . . . . Associating a data control with a dataset . . . . . . . . . . . . . . . . . . Editing and updating data . . . . . . . . Enabling editing in controls on user entry . . . . . . . . . . . . . . . Editing data in a control. . . . . . . . Disabling and enabling data display . . Refreshing data display. . . . . . . . . . Enabling mouse, keyboard, and timer events . . . . . . . . . . . . . . . . . . . Using data sources . . . . . . . . . . . . . . Using TDataSource properties . . . . . . Setting the DataSet property . . . . . Setting the Name property . . . . . . Setting the Enabled property . . . . . Setting the AutoEdit property . . . . Using TDataSource events . . . . . . . . Using the OnDataChange event . . . Using the OnUpdateData event . . . Using the OnStateChange event . . . Controls that represent a single field . . . . Displaying data as labels . . . . . . . . . Displaying and editing fields in an edit box . . . . . . . . . . . . . . . . . . Displaying and editing text in a memo control . . . . . . . . . . . . . . Displaying and editing text in a rich edit memo control . . . . . . . . . Displaying and editing graphics fields in an image control . . . . . . . . . . . Displaying and editing data in list and combo boxes . . . . . . . . . . . . . . . Displaying and editing data in a list box. . . . . . . . . . . . . . . . . Displaying and editing data in a combo box . . . . . . . . . . . . . . Displaying and editing data in lookup list and combo boxes . . . . . . . . . . Specifying a list based on a lookup field . . . . . . . . . . . . . . . . . . Specifying a list based on a secondary data source . . . . . . . . Setting lookup list and combo box properties . . . . . . . . . . . . . . . Searching incrementally for list item values . . . . . . . . . . . . . .

27-1. . 27-1 . . 27-2 . . 27-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-3 27-3 27-4 27-5 27-5 27-5 27-6 27-6 27-6 27-7 27-7 27-7 27-7 27-7 27-7 27-8 27-8

. . 26-14 . . 26-15 . . 26-16 . . . . . . . . . . 26-17 26-18 26-18 26-19 26-19

. . 27-9 . . 27-9 . 27-10 . 27-10 . .27-11 . .27-11 . 27-12 . 27-12 . 27-13 . 27-13 . 27-14 . 27-14

. . 26-20 . . 26-21 . . 26-21 . . 26-22 . . 26-22 . . 26-23 . . 26-24 . . 26-24 . . 26-25 . . 26-26

. . 26-26

xiv

Handling Boolean field values with check boxes . . . . . . . . . . . . . . . Restricting field values with radio controls . . . . . . . . . . . . . . . . . Viewing and editing data with TDBGrid . Using a grid control in its default state . . . . . . . . . . . . . . . . . . . Creating a customized grid . . . . . . . Understanding persistent columns . Determining the source of a column property at runtime . . . . Creating persistent columns . . . . . Deleting persistent columns . . . . . Arranging the order of persistent columns . . . . . . . . . . . . . . . Defining a lookup list column . . . . Defining a pick list column . . . . . Putting a button in a column . . . . Setting column properties at design time . . . . . . . . . . . . . Restoring default values to a column . . . . . . . . . . . . . . . . Displaying ADT and array fields . . . . Setting grid options . . . . . . . . . . . Editing in the grid . . . . . . . . . . . . Rearranging column order at design time . . . . . . . . . . . . . . . Rearranging column order at runtime . . . . . . . . . . . . . . . . . Controlling grid drawing . . . . . . Responding to user actions at runtime. Creating a grid that contains other data-aware controls . . . . . . . . . . . . Navigating and manipulating records. . . Choosing navigator buttons to display Hiding and showing navigator buttons at design time . . . . . . . Hiding and showing navigator buttons at runtime . . . . . . . . . Displaying fly-over help. . . . . . . . . Using a single navigator for multiple datasets . . . . . . . . . . . . . . . . .

. . 27-14 . . 27-15 . . 27-16 . . 27-17 . . 27-17 . . 27-18 . . 27-19 . . 27-19 . . 27-20 . . . . . . . . 27-20 27-20 27-21 27-21

. . 27-21 . . . . . . . . 27-22 27-23 27-24 27-25

. . 27-26 . . 27-26 . . 27-26 . . 27-27 . . 27-28 . . 27-29 . . 27-30 . . 27-30 . . 27-30 . . 27-31 . . 27-31

Chapter 28

Using decision support components

28-1

Overview . . . . . . . . . . . . . . . . . . . . . . 28-1 About crosstabs . . . . . . . . . . . . . . . . . . 28-2 One-dimensional crosstabs . . . . . . . . . . 28-3

Multidimensional crosstabs . . . . . . Guidelines for using decision support components . . . . . . . . . . . . . . . . Using datasets with decision support components . . . . . . . . . . . . . . . . Creating decision datasets with TQuery or TTable . . . . . . . . . . . Creating decision datasets with the Decision Query editor . . . . . . Using the Decision Query editor . . Decision query properties . . . . . . . Using decision cubes . . . . . . . . . . . . Decision cube properties and events . Using the Decision Cube editor . . . . Viewing and changing dimension settings . . . . . . . . . . . . . . . Setting the maximum available dimensions and summaries. . . . Viewing and changing design options . . . . . . . . . . . . . . . Using decision sources . . . . . . . . . . . Properties and events . . . . . . . . . . Using decision pivots. . . . . . . . . . . . Decision pivot properties. . . . . . . . Creating and using decision grids . . . . Creating decision grids . . . . . . . . . Using decision grids . . . . . . . . . . Opening and closing decision grid fields . . . . . . . . . . . . . . Reorganizing rows and columns in decision grids . . . . . . . . . . Drilling down for detail in decision grids . . . . . . . . . . . . . . . . . Limiting dimension selection in decision grids. . . . . . . . . . . . Decision grid properties . . . . . . . . Creating and using decision graphs . . . Creating decision graphs . . . . . . . . Using decision graphs . . . . . . . . . The decision graph display. . . . . . . Customizing decision graphs . . . . . Setting decision graph template defaults . . . . . . . . . . . . . . . Customizing decision graph series Decision support components at runtime Decision pivots at runtime . . . . . . . Decision grids at runtime. . . . . . . . Decision graphs at runtime. . . . . . .

. . . 28-3 . . . 28-3 . . . 28-5 . . . 28-5 . . . . . . . . . . . . . . . . . . 28-6 28-6 28-7 28-7 28-7 28-8

. . . 28-8 . . . 28-9 . . . . . . . . . . . . . . . . . 28-9 . 28-9 . 28-9 28-10 28-10 .28-11 .28-11 .28-11

. . 28-12 . . 28-12 . . 28-12 . . . . . . . . . . . . . . . . . . . . . . . . . . 28-12 28-12 28-13 28-14 28-14 28-15 28-16 28-17 28-17 28-18 28-19 28-19 28-19

xv

Decision support components and memory control . . . . . . . . . . Setting maximum dimensions, summaries, and cells . . . . . . Setting dimension state . . . . . Using paged dimensions . . . .

. . . . . . 28-20 . . . . . . 28-20 . . . . . . 28-20 . . . . . . 28-21

Part III

Writing distributed applicationsChapter 29

Writing CORBA applicationsOverview of a CORBA application . . . Understanding stubs and skeletons . Using Smart Agents . . . . . . . . . . Activating server applications . . . . Binding interface calls dynamically . Writing CORBA servers . . . . . . . . . . Defining object interfaces . . . . . . . Using the CORBA Server Wizard. . . Generating stubs and skeletons from an IDL file . . . . . . . . . . . . . . . Using the CORBA Object Implementation Wizard . . . . . . . Instantiating CORBA objects . . . Using the delegation model . . . . Viewing and editing changes . . . Implementing CORBA Objects . . . . Guarding against thread conflicts. Changing CORBA interfaces . . . . . Registering server interfaces . . . . . Writing CORBA clients . . . . . . . . . . Using stubs . . . . . . . . . . . . . . . Using the dynamic invocation interface . . . . . . . . . . . . . . . . Testing CORBA servers . . . . . . . . . . Setting up the testing tool . . . . . . . Recording and running test scripts . . . . . . . . . . . . . . . . . . . . . . . . . .

29-1. 29-1 . 29-2 . 29-3 . 29-3 . 29-4 . 29-4 . 29-5 . 29-5

. . . . 29-6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-6 . 29-7 . 29-8 . 29-9 . 29-9 29-11 29-12 29-12 29-13 29-14 29-15 29-16 29-17 29-17

Chapter 30

Creating Internet server applicationsTerminology and standards. . . . . . . . Parts of a Uniform Resource Locator. URI vs. URL . . . . . . . . . . . . . HTTP request header information . . HTTP server activity. . . . . . . . . . . . Composing client requests . . . . . . . . . . . . . . . . . . . . . . . .

30-1. 30-1 . 30-2 . 30-2 . 30-3 . 30-3 . 30-3

Serving client requests . . . . . . . . . . Responding to client requests . . . . . . Web server applications . . . . . . . . . . . Types of Web server applications . . . . ISAPI and NSAPI . . . . . . . . . . . CGI stand-alone . . . . . . . . . . . . Win-CGI stand-alone . . . . . . . . . Creating Web server applications . . . . The Web module. . . . . . . . . . . . . . The Web Application object . . . . . . . The structure of a Web server application . The Web dispatcher. . . . . . . . . . . . . . Adding actions to the dispatcher . . . . Dispatching request messages . . . . . . Action items . . . . . . . . . . . . . . . . . . Determining when action items fire. . . The target URL . . . . . . . . . . . . . The request method type . . . . . . . Enabling and disabling action items. Choosing a default action item . . . . Responding to request messages with action items . . . . . . . . . . . . Sending the response . . . . . . . . . Using multiple action items . . . . . Accessing client request information . . . . Properties that contain request header information. . . . . . . . . . . . . . . . Properties that identify the target . . Properties that describe the Web client . . . . . . . . . . . . . . . . . . Properties that identify the purpose of the request . . . . . . . . Properties that describe the expected response . . . . . . . . . . Properties that describe the content . The content of HTTP request messages . Creating HTTP response messages . . . . . Filling in the response header . . . . . . Indicating the response status . . . . Indicating the need for client action . Describing the server application . . Describing the content . . . . . . . . Setting the response content . . . . . . . Sending the response . . . . . . . . . . . Generating the content of response messages . . . . . . . . . . . . . . . . . . . Using page producer components. . . . HTML templates . . . . . . . . . . . . Specifying the HTML template. . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. 30-4 . 30-4 . 30-5 . 30-5 . 30-5 . 30-5 . 30-5 . 30-6 . 30-6 . 30-7 . 30-7 . 30-8 . 30-9 . 30-9 30-10 30-10 30-10 30-10 .30-11 .30-11 30-12 30-12 30-12 30-13

. 30-13 . 30-13 . 30-13 . 30-14 . . . . . . . . . . . . . . . 30-14 30-14 30-15 30-15 30-15 30-15 30-16 30-16 30-16 30-16 30-17 30-17 30-18 30-18 30-19

xvi

Converting HTML-transparent tags . . . . . . . . . . . . . . . . . . Using page producers from an action item . . . . . . . . . . . . . . Chaining page producers together . Using database information in responses . Adding a session to the Web module . Representing database information in HTML . . . . . . . . . . . . . . . . . Using dataset page producers . . . . Using table producers . . . . . . . . Specifying the table attributes . . . . Specifying the row attributes . . . . Specifying the columns. . . . . . . . Embedding tables in HTML documents . . . . . . . . . . . . . . Setting up a dataset table producer . Setting up a query table producer . Debugging server applications . . . . . . . Debugging ISAPI and NSAPI applications . . . . . . . . . . . . . . . Debugging under Windows NT. . . Debugging with a Microsoft IIS server . . . . . . . . . . . . . . . . . Debugging under MTS . . . . . . . . Debugging with a Windows 95 Personal Web Server . . . . . . . . Debugging with Netscape Server Version 2.0 . . . . . . . . . . . . . . Debugging CGI and Win-CGI applications . . . . . . . . . . . . . . . Simulating the server. . . . . . . . . Debugging as a DLL . . . . . . . . .

. . 30-19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-19 30-20 30-21 30-22 30-22 30-22 30-23 30-23 30-23 30-24 30-24 30-24 30-24 30-25

. . 30-25 . . 30-25 . . 30-25 . . 30-26 . . 30-27 . . 30-28 . . 30-29 . . 30-29 . . 30-29

Using socket components . . . . . . . Using client sockets . . . . . . . . . Specifying the desired server . . Forming the connection . . . . . Getting information about the connection . . . . . . . . . . . Closing the connection . . . . . Using server sockets . . . . . . . . Specifying the port. . . . . . . . Listening for client requests . . Connecting to clients . . . . . . Getting information about connections . . . . . . . . . . . Closing server connections . . . Responding to socket events. . . . . . Error events . . . . . . . . . . . . . Client events . . . . . . . . . . . . . Server events. . . . . . . . . . . . . Events when listening . . . . . . Events with client connections . Reading and writing over socket connections . . . . . . . . . . . . . . Non-blocking connections . . . . . Reading and writing events . . Blocking connections . . . . . . . . Using threads with blocking connections . . . . . . . . . . . Using TWinSocketStream . . . . Writing client threads . . . . . . Writing server threads. . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

31-5 31-5 31-6 31-6 31-6 31-6 31-6 31-7 31-7 31-7 31-7 31-8 31-8 31-8 31-9 31-9 31-9 31-9

31-10 31-10 31-10 .31-11 .31-11 31-12 31-12 31-13

Part IV

Developing COM-based applicationsChapter 32

Chapter 31

Working with socketsImplementing services . . . . . . . . . . Understanding service protocols . . . Communicating with applications Services and ports . . . . . . . . . . . Types of socket connections. . . . . . . . Client connections . . . . . . . . . . . Listening connections . . . . . . . . . Server connections . . . . . . . . . . . Describing sockets . . . . . . . . . . . . . Describing the host . . . . . . . . . . . Choosing between a host name and an IP address . . . . . . . . . Using ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31-1. 31-1 . 31-2 . 31-2 . 31-2 . 31-2 . 31-3 . 31-3 . 31-3 . 31-3 . 31-4

Overview of COM technologiesCOM as a specification and implementation . . . . . . . . . COM extensions . . . . . . . . . . Parts of a COM application . . . . . . . COM interfaces . . . . . . . . . . . . The fundamental COM interface, IUnknown . . . . . . . . . . . . COM interface pointers . . . . . . COM servers . . . . . . . . . . . . . . CoClasses and class factories . . . In-process, out-of-process, and remote servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

32-1. . . . . . . . 32-1 32-2 32-2 32-3 32-4 32-4 32-5 32-6

. . . . 31-4 . . . . 31-5

. . . . 32-6

xvii

The marshaling mechanism . . Aggregation . . . . . . . . . . . COM clients . . . . . . . . . . . . . COM extensions . . . . . . . . . . . . Automation servers . . . . . . . . Active Server Pages . . . . . . . . ActiveX controls . . . . . . . . . . Active Documents . . . . . . . . . Transactional objects . . . . . . . . Type libraries . . . . . . . . . . . . The content of type libraries . . Creating type libraries . . . . . When to use type libraries . . . Accessing type libraries . . . . Benefits of using type libraries Using type library tools . . . . Implementing COM objects with wizards . . . . . . . . . . . . . . . . Code generated by wizards . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. 32-8 . 32-8 . 32-9 . 32-9 32-11 32-12 32-12 32-13 32-13 32-14 32-14 32-15 32-15 32-16 32-16 32-17

Adding an enumeration to the type library . . . . . . . . . . . . . Adding an alias to the type library Adding a record or union to the type library . . . . . . . . . . . . . Adding a module to the type library . . . . . . . . . . . . . . . . Saving and registering type library information . . . . . . . . . . . . . Saving a type library . . . . . . . . Refreshing the type library . . . . . Registering the type library. . . . . Exporting an IDL file . . . . . . . . Deploying type libraries . . . . . . . . . .

. . 33-15 . . 33-16 . . 33-16 . . 33-16 . . . . . . . . . . . . 33-17 33-17 33-18 33-18 33-18 33-18

Chapter 34

Creating COM clients. . . . . 32-17 . . . . . 32-20 Importing type library information . . . . Using the Import Type Library dialog Using the Import ActiveX dialog . . . Code generated when you import type library information . . . . . . . Controlling an imported object . . . . . . Using component wrappers . . . . . . ActiveX wrappers . . . . . . . . . . Automation object wrappers . . . . Using data-aware ActiveX controls . . Example: Printing a document with Microsoft Word . . . . . . . . . . . . Step 1: Prepare C++Builder for this example . . . . . . . . . . . . Step 2: Import the Word type library . . . . . . . . . . . . . Step 3: Use a VTable or dispatch interface object to control Microsoft Word . . . . . . . . . . . Step 4: Clean up the example . . . . Writing client code based on type library definitions . . . . . . . . . . . Connecting to a server . . . . . . . Controlling an Automation server using a dual interface . . . . . . . Controlling an Automation server using a dispatch interface . . . . . Handling events in an automation controller . . . . . . . . . . . . . . Creating Clients for servers that do not have a type library . . . . . . . . . . . .

34-1. . . 34-2 . . . 34-3 . . . 34-4 . . . . . . . . . . . . . . . . . . 34-5 34-6 34-6 34-7 34-7 34-8

Chapter 33

Working with type librariesType Library editor . . . . . . . . . . . . Parts of the Type Library editor. . . . Toolbar . . . . . . . . . . . . . . . . Object list pane . . . . . . . . . . . Status bar . . . . . . . . . . . . . . Pages of type information . . . . . Type library elements . . . . . . . . . Interfaces. . . . . . . . . . . . . . . Dispinterfaces . . . . . . . . . . . . CoClasses . . . . . . . . . . . . . . Type definitions . . . . . . . . . . . Modules . . . . . . . . . . . . . . . Using the Type Library editor. . . . . Valid types . . . . . . . . . . . . . . Creating a new type library . . . . Opening an existing type library . Adding an interface to the type library . . . . . . . . . . . . . . . Modifying an interface using the type library . . . . . . . . . . . . Adding properties and methods to an interface or dispinterface . Adding a CoClass to the type library . . . . . . . . . . . . . . . Adding an interface to a CoClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

33-1. 33-2 . 33-2 . 33-3 . 33-4 . 33-5 . 33-5 . 33-7 . 33-8 . 33-9 . 33-9 . 33-9 33-10 33-10 33-11 33-12 33-12

. . 34-10 . . 34-10 . . 34-10

. . .34-11 . . 34-12 . . 34-12 . . 34-12 . . 34-13 . . 34-13 . . 34-14 . . 34-16

. . . 33-13 . . . 33-13 . . . 33-14 . . . 33-15 . . . 33-15

xviii

Chapter 35

Creating simple COM serversOverview of creating a COM object . . . Designing a COM object . . . . . . . . . Using the COM object wizard . . . . . . Using the Automation object wizard . . Choosing a threading model . . . . . Writing an object that supports the free threading model . . . . . Writing an object that supports the apartment threading model . Writing an object that supports the neutral threading model . . . Specifying ATL options . . . . . . . . . . Defining a COM objects interface . . . . Adding a property to the objects interface . . . . . . . . . . . . . . . . Adding a method to the objects interface . . . . . . . . . . . . . . . . Exposing events to clients . . . . . . . Managing events in your Automation object . . . . . . . . Automation interfaces . . . . . . . . . . . Dual interfaces . . . . . . . . . . . . . Dispatch interfaces . . . . . . . . . . . Custom interfaces . . . . . . . . . . . Marshaling data . . . . . . . . . . . . . . Automation compatible types . . . . Type restrictions for automatic marshaling . . . . . . . . . . . . . . Custom marshaling . . . . . . . . . . Registering a COM object . . . . . . . . . Registering an in-process server . . . Registering an out-of-process server . Testing and debugging the application . . . . . . . . . . . . . . . .

35-1. 35-1 . 35-2 . 35-2 . 35-4 . 35-5

Registering an out-of-process server . . . . 36-8 Testing and debugging the Active Server Page application. . . . . . . . . . . . . 36-8

Chapter 37

Creating an ActiveX controlOverview of ActiveX control creation . Elements of an ActiveX control . . . VCL control. . . . . . . . . . . . . ActiveX wrapper. . . . . . . . . . Type library. . . . . . . . . . . . . Property page . . . . . . . . . . . Designing an ActiveX control . . . . . . Generating an ActiveX control from a VCL control . . . . . . . . . . . . . . . Generating an ActiveX control based on a VCL form . . . . . . . . . . . . . . Licensing ActiveX controls. . . . . . . . Customizing the ActiveX controls interface . . . . . . . . . . . . . . . . . Adding additional properties, methods, and events . . . . . . . . Adding properties and methods . Adding events . . . . . . . . . . . Enabling simple data binding with the type library. . . . . . . . . . . . Creating a property page for an ActiveX control . . . . . . . . . . . . . Creating a new property page . . . . Adding controls to a property page . Associating property page controls with ActiveX control properties . . Updating the property page . . . Updating the object . . . . . . . . Connecting a property page to an ActiveX control . . . . . . . . . . Registering an ActiveX control . . . . . Testing an ActiveX control . . . . . . . . Deploying an ActiveX control on the Web . . . . . . . . . . . . . . . . . . Setting options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

37-1. . . . . . . 37-2 37-2 37-3 37-3 37-3 37-3 37-4

. . . . 35-6 . . . . 35-7 . . . . 35-8 . . . . 35-8 . . . . 35-9 . . . . 35-9 . . . 35-10 . . . 35-10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-11 35-11 35-12 35-13 35-14 35-14 35-14 35-15 35-15 35-16 35-16 35-16 35-17

. . . . 37-4 . . . . 37-6 . . . . 37-7 . . . . 37-8 . . . . 37-9 . . . . 37-9 . . . 37-10 . . . .37-11 . . . 37-13 . . . 37-13 . . . 37-14 . . . 37-14 . . . 37-14 . . . 37-15 . . . 37-15 . . . 37-15 . . . 37-16 . . . 37-16 . . . 37-17

Chapter 36

Creating an Active Server PageCreating an Active Server Object. . Using the ASP intrinsics . . . . . Application . . . . . . . . . . Request. . . . . . . . . . . . . Response . . . . . . . . . . . . Session . . . . . . . . . . . . . Server . . . . . . . . . . . . . Creating ASPs for in-process or out-of-process servers . . . . . Registering an Active Server Object Registering an in-process server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

36-1. 36-2 . 36-3 . 36-3 . 36-4 . 36-4 . 36-5 . 36-6

Chapter 38

Creating MTS or COM+ objectsUnderstanding transactional objects Requirements for a transactional object . . . . . . . . . . . . . . . Managing resources . . . . . . . . . Accessing the object context . . .

38-1

. . . . . . 38-2 . . . . . . 38-2 . . . . . . 38-3 . . . . . . 38-3

. . . . . . . 36-7 . . . . . . . 36-7 . . . . . . . 36-7

xix

Just-in-time activation . . . . . . . . . Resource pooling . . . . . . . . . . . . Database resource dispensers . . . Shared property manager . . . . . Releasing resources . . . . . . . . . Object pooling . . . . . . . . . . . . . MTS and COM+ transaction support . . Transaction attributes . . . . . . . . . Setting the transaction attribute . . Stateful and stateless objects . . . . . Influencing how transactions end . . Initiating transactions . . . . . . . . . Setting up a transaction object on the client side . . . . . . . . . . . Setting up a transaction object on the server side . . . . . . . . . . . Transaction timeout . . . . . . . . . . Role-based security . . . . . . . . . . . . Overview of creating transactional objects . . . . . . . . . . . . . . . . . . . Using the Transactional Object wizard . Choosing a threading model for a transactional object . . . . . . . . . Activities . . . . . . . . . . . . . . . Generating events under COM+ . . . . . Using the Event Object wizard . . . . Firing events using a COM+ event object . . . . . . . . . . . . . . Passing object references . . . . . . . . . Using the SafeRef method . . . . . Callbacks. . . . . . . . . . . . . . . Debugging and testing transactional objects . . . . . . . . . . . . . . . . . . . Installing transactional objects . . . . . . Administering transactional objects . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. 38-4 . 38-5 . 38-5 . 38-6 . 38-9 . 38-9 . 38-9 38-10 38-11 38-12 38-12 38-13

. . . 38-13 . . . 38-14 . . . 38-15 . . . 38-16 . . . 38-17 . . . 38-17 . . . . . . . . . . . . . . . . . . . . . . . . 38-18 38-19 38-20 38-20 38-21 38-22 38-22 38-23

Subclassing Windows controls. . Creating nonvisual components . What goes into a component? . . . . Removing dependencies . . . . . Properties, methods, and events . Properties . . . . . . . . . . . . Events . . . . . . . . . . . . . . Methods. . . . . . . . . . . . . Graphics encapsulation . . . . . . Registration . . . . . . . . . . . . Creating a new component . . . . . Using the Component wizard . . Creating a component manually. Creating a unit file . . . . . . . Deriving the component . . . Declaring a new constructor . Registering the component . . Testing uninstalled components. . . Testing installed components . . . . Installing a component on the Component palette . . . . . . . . . Component file locations . . . . . Adding the component . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. 39-4 . 39-4 . 39-5 . 39-5 . 39-5 . 39-6 . 39-6 . 39-6 . 39-7 . 39-7 . 39-7 . 39-8 .39-11 .39-11 .39-11 39-12 39-12 39-14 39-16

. . . . . 39-16 . . . . . 39-17 . . . . . 39-17

Chapter 40

Object-oriented programming for component writersDefining new classes . . . . . . . . . . . Deriving new classes . . . . . . . . . To change class defaults to avoid repetition . . . . . . . . . To add new capabilities to a class Declaring a new component class . . Ancestors, descendants, and class hierarchies . . . . . . . . . . . . . . . . Controlling access. . . . . . . . . . . . . Hiding implementation details . . . Defining the component writers interface. . . . . . . . . . . . . . . . Defining the runtime interface . . . . Defining the design-time interface . Dispatching methods . . . . . . . . . . . Regular methods . . . . . . . . . . . Virtual methods . . . . . . . . . . . . Overriding methods . . . . . . . . Abstract class members . . . . . . . . . Classes and pointers . . . . . . . . . . .

40-1

. . . . 40-1 . . . . 40-2 . . . . 40-2 . . . . 40-2 . . . . 40-3 . . . . 40-3 . . . . 40-4 . . . . 40-4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40-6 . 40-6 . 40-7 . 40-8 . 40-8 . 40-9 . 40-9 40-10 40-10

. . . 38-23 . . . 38-24 . . . 38-25

Part V

Creating custom componentsChapter 39

Overview of component creationVisual Component Library . . . . Components and classes . . . . . How do you create components? Modifying existing controls . . Creating windowed controls . Creating graphic controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

39-1. 39-1 . 39-2 . 39-2 . 39-3 . 39-3 . 39-4

xx

Chapter 41

Creating propertiesWhy create properties? . . . . . . . . . . Types of properties. . . . . . . . . . . . . Publishing inherited properties . . . . . Defining properties . . . . . . . . . . . . The property declaration . . . . . . . Internal data storage . . . . . . . . . . Direct access. . . . . . . . . . . . . . . Access methods. . . . . . . . . . . . . The read method . . . . . . . . . . The write method . . . . . . . . . . Default property values . . . . . . . . Specifying no default value . . . . Creating array properties . . . . . . . . . Storing and loading properties . . . . . . Using the store-and-load mechanism Specifying default values . . . . . . . Determining what to store. . . . . . . Initializing after loading . . . . . . . . Storing and loading unpublished properties . . . . . . . . . . . . . . . Creating methods to store and load property values . . . . . . . Overriding the DefineProperties method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

41-1. 41-1 . 41-2 . 41-2 . 41-3 . 41-3 . 41-4 . 41-4 . 41-5 . 41-6 . 41-6 . 41-7 . 41-7 . 41-8 . 41-9 41-10 41-10 41-11 41-12

Defining the handler type . . . . Simple notifications . . . . . . Event-specific handlers . . . . Returning information from the handler . . . . . . . . . . Declaring the event . . . . . . . . Event names start with On . Calling the event. . . . . . . . . .

. . . . . . 42-7 . . . . . . 42-7 . . . . . . 42-7 . . . . . . . . . . . . . . . . . . . . . . . . 42-7 42-7 42-8 42-8

Chapter 43

Creating methodsAvoiding dependencies . . . . . . . . Naming methods . . . . . . . . . . . . Protecting methods . . . . . . . . . . . Methods that should be public. . . Methods that should be protected. Making methods virtual . . . . . . . . Declaring methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

43-1.