Directory listing of http: uap.unnes.ac.id ebook biblebook Visual Basic 6 com & Library Books
9
C H A P T E R
Programming
with Data
Environments
✦
✦
✦
✦
In This Cha pter
The Data Enviro nment
Desig ner
I
n this c hapter, I’m go ing to disc uss ho w to use the Data
Enviro nment Designer to c reate a Data Enviro nment, whic h
simplifies many o f the tasks o f building a database applic atio n. It explo its the ADO o bjec t mo del and helps yo u c reate
standardized ADO o bjec ts that simplify ac c ess to the
database.
The Data Environment Designer
The Data Enviro nment Designer is a to o l in the Visual Basic
IDE that helps a pro grammer c reate a database applic atio n
mo re quic kly than if they had to perfo rm the same tasks manually. The Designer c reates ADO o bjec ts c o rrespo nding to the
tables in yo ur database; it also pro vides o ther o bjec ts to help
yo u manipulate yo ur database. These o bjec ts are available as
part o f the Data Enviro nment o bjec t at runtime.
Note
CrossReference
ADO, not DAO and RDO: The Data Environm ent Designer
only w orks w ith the ADO object m odel. The DAO and RDO
object m odels are not supported. The UserConnection
designer is a subset of the Data Environm ent Designer and
supports the RDO object m odel.
See Chapter 6 for explanations of the ADO, DAO, and
RDO m odels.
Co nnecting to
databases
Creating and using
co mmands
Using the Data
View windo w
✦
✦
✦
✦
142
Part II ✦ Beginning Database Programming
Enabling the Data Environment Designer
To add the Data Enviro nment Designer to yo ur pro jec t, c ho o se Pro jec t ➪ Add Data
Enviro nment fro m the main menu. If yo u do n’t see it listed direc tly under the Pro jec t
menu, try lo o king under the Mo re Ac tiveX Designers menu (o r Pro jec t ➪ Mo re Ac tiveX
Designers ➪ Data Enviro nment fro m the main menu). This will display the main windo w fo r the Data Enviro nment Designer.
If the Data Enviro nment Designer do esn’t appear in either lo c atio n, yo u’ll need to
add it to Visual Basic . Cho o se Pro jec t ➪ Co mpo nents fro m the main menu to display
the Co mpo nents dialo g bo x, then selec t the Designer tab to see the windo w as
sho wn in Figure 9-1. Plac e a c hec k mark in the bo x next to Data Enviro nment and
press OK. This will add the Data Enviro nment Designer to the Pro jec t menu. If yo u
do n’t see Data Enviro nment listed o n the Designers tab, yo u need to install the Data
Enviro nment feature fro m yo ur Visual Basic CD-ROM.
Figure 9-1: Adding the Data Environm ent Designer
to the Visual Basic IDE
Exploring the Data Environment Designer
The main Data Enviro nment Designer windo w (see Figure 9-2) inc ludes a series o f
ic o ns that are used to perfo rm c o mmo n o peratio ns, plus an ic o n tree view o f the
o bjec ts used in the Data Enviro nment.
Chapter 9 ✦ Programming with Data Environments
Add
Command
Refresh
Add Child
Command
Options
Properties
Delete
Design
Insert Stored
Procedure
Arrange by Objects
Arrange by
Connections
View
Code
Icon tree
Add
Connection
Figure 9-2: Exploring the Data Environm ent Designer w indow
✦ Add Connection – adds a new Connection o bjec t to the data enviro nment,
whic h will be used to ac c ess a database.
✦ Add Command – adds a new Command o bjec t to the data enviro nment, whic h
will be used to exec ute an SQL c o mmand.
✦ Insert Stored Procedure – adds a Command o bjec t with the info rmatio n to c all
a sto red pro c edure o n the database server.
143
144
Part II ✦ Beginning Database Programming
✦ Add Child Command – adds a Command o bjec t to ano ther Command o bjec t to
c reate a hierarc hic al struc ture o f data.
✦ Delete – remo ves an o bjec t fro m the data enviro nment.
✦ Refresh – refreshes the selec ted o bjec t. Connection o bjec ts are c lo sed and
reo pened, while all o f the metadata asso c iated with a Command o bjec t will be
rebuilt.
✦ Design – ac c esses the SQL query designer when yo u spec ify an SQL statement
as the data so urc e fo r a Command o bjec t.
✦ Properties – displays the pro perties asso c iated with the selec ted o bjec t.
✦ View Code – displays the c o de asso c iated with a partic ular o bjec t.
✦ Options – displays the Optio ns dialo g bo x that c o ntro ls ho w the Data
Enviro nment Designer wo rks.
✦ Arrange by Connections – arranges the o bjec ts in the ic o n tree by the
Connection o bjec t they ac c ess.
✦ Arrange by Objects – arranges the o bjec ts in the ic o n tree by o bjec t type.
✦ Icon Tree – the list o f o bjec ts asso c iated with the data enviro nment.
Tip
Many of these functions are also available via a pop-up m enu that you can display
by right clicking on an object in the icon tree.
Data Environment building blocks
The Data Enviro nment Designer helps yo u c reate three main types o f o bjec ts:
Connections, Commands, and Recordsets. These o bjec ts are used at bo th design
time and runtime to ac c ess yo ur database. At design time, info rmatio n abo ut yo ur
database is extrac ted and made available to help yo u c reate yo ur pro gram. At runtime, these o bjec ts are used to perfo rm typic al database o peratio ns.
Tip
It’s not what it seems: While these objects appear to be part of the Data Environm ent Designer, they are really norm al ADO objects that the Data Environm ent
Designer helps you create. For m ore inform ation about all of the capabilities of
these objects, please refer to Chapter 11.
Connection objects
A Connection o bjec t c o ntains the pro perties and metho ds needed to ac c ess a
database. Sinc e the Connection o bjec t is used at bo th runtime and design time, a
related o bjec t c alled the DECconnection is used by the Data Enviro nment Designer
to trac k info rmatio n abo ut eac h mo de. This info rmatio n c o ntains the user name,
passwo rd, ho w to pro mpt fo r passwo rd info rmatio n, and whether to save passwo rd
info rmatio n at the end o f the sessio n fo r bo th runtime and design-time use.
Chapter 9 ✦ Programming with Data Environments
Command objects
A Command o bjec t c o ntains the info rmatio n nec essary to exec ute a c o mmand
against yo ur database. A c o mmand may be an SQL statement, a c all to a sto red pro c edure, o r the name o f a table. So me c o mmands will require yo u to inc lude a list o f
parameters when they are run. So me c o mmands will return a set o f ro ws, while o thers will return no thing but a status c o nditio n.
Recordset objects
Ro ws are returned fro m yo ur database in a Recordset o bjec t. The Rec o rdset o bjec t
presents a single ro w o f data, kno wn as the curre nt re co rd. A curso r is used to po int
to the c urrent rec o rd in the Recordset. Yo u c an manipulate the c urso r by using
vario us metho ds in the Recordset o bjec t.
If the ro ws in the Recordset o bjec t c an be updated, there are o ther metho ds that
allo w yo u to add a new ro w, delete a ro w, and update a ro w. If yo u need to update
multiple ro ws, yo u c an easily c reate a Command o bjec t, whic h will c all the appro priate SQL statement, o r yo u c an use the c urso r to mo ve thro ugh the ro ws in the
Recordset o bjec t o ne at a time and use the appro priate metho ds to perfo rm yo ur
updates.
Like the ADO Data Control, a Recordset o bjec t c an be used as a data so urc e
with bo und c o ntro ls. This means that yo u c an easily replac e the ADO Data
Control with the appro priate Recordset o bjec t by c hanging the DataSource
pro perty o n eac h o f the bo und c o ntro ls.
Hierarchical Recordsets
A hierarc hic al rec o rdset is based o n a no rmal Recordset, exc ept that in plac e o f
o ne o f the values in a ro w o f data is ano ther Recordset, kno wn as a child rec o rdset.
The c hild rec o rdset is c reated by a c hild Command, who se values are determined by
a relatio nship with the parent rec o rdset. It is also reaso nable fo r a c hild rec o rdset
to have its o wn c hild rec o rdsets, thus c reating a multi-level hierarc hy.
Hierarc hic al rec o rdsets are useful when yo u want to retrieve data fro m multiple
tables, but do n’t want to merge the data into a single table. The c lassic c ase o f a
hierarc hic al rec o rdset is the c usto mers, o rders, and o rder items. A c o mpany has a
c o llec tio n o f c usto mers, eac h c usto mer may have plac ed multiple o rders, and eac h
o rder a c usto mer has plac ed may have multiple items.
Connecting to Your Database
The first step in wo rking with the Data Enviro nment Designer is to define a c o nnec tio n to the database. By default the Data Enviro nment Designer c reates a single
Connection o bjec t c alled Connection1. This o bjec t is used at bo th design time
and runtime to ac c ess info rmatio n fro m the database.
145
146
Part II ✦ Beginning Database Programming
Setting Connection properties
Selec ting the Connection1 o bjec t and pressing the Pro perties butto n displays
the Data Link Pro perties dialo g bo x, as sho wn in Figure 9-3. While there are fo ur
tabs o n the dialo g bo x, o nly the Pro vider and Co nnec tio n tab are typic ally used.
The Advanc ed tab c o ntains info rmatio n regarding netwo rk settings, c o nnec tio n
timeo ut, and ac c ess permissio ns who se default settings are almo st always o kay.
The All tab lists all o f the initializatio n parameters that will be used when establishing the database c o nnec tio n.
Figure 9-3: Setting Data Link properties
for a Connection object
Selecting an OLE DB provider
The first step in defining yo ur c o nnec tio n to the database is to c ho o se an OLE DB
pro vider o n the Pro vider tab o f the Data Link Pro perties dialo g bo x. All o f the pro viders available fo r yo ur system will be listed. Yo u sho uld c ho o se the native OLE
DB pro vider fo r yo ur database server, if o ne is available. Otherwise, yo u sho uld
c ho o se the Mic ro so ft OLE DB Pro vider fo r ODBC Drivers. Onc e yo u selec t the
pro per OLE DB pro vider, press Next to c o ntinue defining the c o nnec tio n pro perties.
Entering connection information
Sinc e I c ho se the Mic ro so ft OLE DB Pro vider fo r SQL Server in the previo us step,
pressing Next will request the info rmatio n sho wn in Figure 9-4 using the Co nnec tio n
tab. In this c ase, my database server is o n Athena. I’m go ing to use Windo ws NT
integrated sec urity and I want to use the VB6DB database as my default database.
Chapter 9 ✦ Programming with Data Environments
Onc e I enter this info rmatio n, I c an press the Test Co nnec tio n butto n to verify that
everything is c o rrec t. If there is a pro blem, a message bo x will be displayed with
a desc riptio n o f the erro r; o therwise, a message bo x saying Test c o nnec tio n suc c eeded will be displayed. After pressing OK o n the test’s message bo x, press OK
to save the c o nnec tio n info rmatio n.
Figure 9-4: Entering connection
inform ation for the Microsoft
OLE DB Provider for SQL Server
CrossReference
The inform ation entered in the Data Link dialog boxes is used to build a connection
string . This value is used anytim e you w ant to connect an ADO object to a database.
For m ore inform ation about connection strings, see the ConnectionString property and the Connection object in Chapter 11. For details about how to connect to
a specific database, see Connecting to SQL Server in Chapter 23, Connecting to
Oracle8 i in Chapter 26, or Connecting to Jet in Chapter 29.
Creating Commands with the Designer
After yo u have defined a Connection o bjec t, yo u c an begin to define so me
Command o bjec ts. The Data Enviro nment Designer treats Command o bjec ts in two
different ways — as c o mmands and as sto red pro c edures. The differenc e is primarily ho w the info rmatio n fo r the o bjec ts is o btained. If yo u c ho o se to add a sto red
pro c edure, the designer will get a list o f sto red pro c edures fro m the database, yo u
will need to enter a single, dynamic ally exec uted SQL statement as o ne o f the pro perties o f the Command o bjec t. Sto red pro c edures are disc ussed later in this c hapter
under “Selec ting a Database Objec t.”
147
148
Part II ✦ Beginning Database Programming
Adding a command
Adding a Command o b jec t b y pressing the Add Co mmand b utto n o n the Data
Enviro nment Designer to o lb ar simply adds a new c o mmand o b jec t b eneath the
c urrently selec ted Connection. All o f the pro perties asso c iated with the Command
o b jec t are left at their default values and must b e c hanged in o rder to use the
c o mmand.
Setting general command properties
Pressing the Pro perties butto n o r right c lic king o n the Command o bjec t will display
the Command1 Pro perties dialo g bo x as sho wn in Figure 9-5. On the General tab, yo u
c an spec ify the name o f the c o mmand, whic h c o nnec tio n will be used by the c o mmand, and the So urc e o f Data fo r the c o mmand.
Figure 9-5: View ing the general
properties of the Com m and1 object
The So urc e o f Data sec tio n is so mewhat misleading sinc e a Command o bjec t need
no t return data. It really depends o n whether the database o bjec t yo u selec t o r the
SQL statement yo u enter returns any data.
Selecting a database object
Yo u have a c ho ic e o f fo ur different database o bjec ts: a Sto red Pro c edure, a Table, a
View, o r a Syno nym. A sto re d pro ce dure is no thing but a series o f o ne o r mo re SQL
statements that are exec uted o n the database server. Any data returned depends
o n whether the sto red pro c edure inc ludes a Select statement. Selec ting Table o r
View will always return all o f the data visible in the selec ted table o r view. A syno nym is an alternate name fo r a database o bjec t, suc h as a table o r view.
Onc e yo u selec t whic h type o f database o bjec t yo u want, yo u must spec ify the
o bjec t name. The designer makes this easy bec ause after yo u spec ify the type o f
database o bjec t yo u want, it will auto matic ally c o nnec t to the database server using
Chapter 9 ✦ Programming with Data Environments
the spec ified Connection o bjec t and retrieve the list o f available o bjec ts. These
o bjec ts are then made available in the Objec t Name dro p-do wn list direc tly belo w
the Database Objec t dro p do wn bo x. All yo u need to do is selec t the o ne yo u want.
Entering an SQL Statement
If yo u want the c o mmand to exec ute an SQL statement, simply enter the statement
in the SQL Statement area in the dialo g bo x. No o ther statement, exc ept fo r the
Select statement, will return data. To make it easier to c reate an SQL Select statement, yo u c an press the SQL Builder butto n to display the Design windo w, whic h
will help yo u build SQL queries.
One o f the side effec ts o f using an SQL statement o r a sto red pro c edure is that the
designer do esn’t kno w what fields will be returned. The o nly way fo r the Command
o bjec t to kno w what fields are returned is to exec ute the c o mmand. Befo re exec uting the c o mmand, the designer will ask yo u fo r permissio n (see Figure 9-6), sinc e
the c o mmand c o uld po tentially update yo ur database.
Figure 9-6: Asking for perm ission
to execute an SQL statem ent
Tip
Test it first: You should take the tim e to verify that the SQL statem ent w ill w ork
before you enter it into the SQL Statem ent area. The easiest w ay to do this is to
use a tool like SQL Server’s Query Analyzer.
Setting parameters
If yo u are using a sto red pro c edure as yo ur c o mmand, yo u will pro bably have o ne
o r mo re parameters asso c iated with it. Co nsider the sto red pro c edure in Listing 9-1.
It will retrieve all o f the info rmatio n abo ut the c usto mer spec ified in CustId.
Listing 9-1: The GetCustomer stored procedure
Create Procedure GetCustomer (@CustId Int)
As
Select *
From Customers
Where CustomerId = @CustId
149
150
Part II ✦ Beginning Database Programming
Figure 9-7 sho ws yo u the Parameters tab o f the Pro perties dialo g bo x. Yo u c an view
the details abo ut a partic ular parameter by c lic king o n it in the Parameters frame.
The info rmatio n related to it will be displayed in the Parameter Pro perties frame.
Figure 9-7: Looking at the
param eters of a stored
procedure
Eac h parameter has a number o f different pro perties asso c iated with it:
✦ Name – c o ntains the fo rmal name o f the parameter.
✦ Direction – c lassifies the parameter as input, o utput, o r input/ o utput parameter.
✦ Data_Type – spec ifies the data type asso c iated with the parameter.
✦ Precision – spec ifies the prec isio n o f a numeric data type.
✦ Scale – spec ifies the sc ale o f a numeric data type. This field is disabled fo r
no n-numeric data types.
✦ Size – spec ifies the size asso c iated with the data type. This field is disabled
fo r no n-numeric data types.
✦ Host Data Type – spec ifies the data type that will be used by the ho st. This
value must be c o mpatible with the value spec ified in the Data_Type field.
✦ Required – is TRUE when yo u must spec ify a value fo r the parameter befo re
the c o mmand c an be exec uted.
✦ Value – c o ntains the default value fo r the parameter. It will be used at design
time to test the Command o bjec t. At runtime, yo u will typic ally o verride this
value with the real value yo u wish to use.
Chapter 9 ✦ Programming with Data Environments
Note
I can’t change anything: If the type of com m and you are creating doesn’t allow
param eters, all of the fields on this tab w ill be blank, and even if the type of com m and does support param eters, som e of the properties of the param eter m ay be
disabled, m eaning that you can’t change them .
Setting advanced properties
The Advanc ed Pro perties tab (see Figure 9-8) c o ntains a number o f different pro perties that affec t ho w the c o mmand will be exec uted and ho w the results will be
returned. Depending o n the type o f c o mmand yo u c ho o se, so me o r mo st o f these
pro perties may be disabled.
Figure 9-8: Review ing
advanced properties
Reviewing Recordset management properties
The fo ur pro perties in the Re co rdSe t Manage me nt sec tio n ( CursorType,
CursorLocation, LockType and CacheSize) c o ntro l ho w the Recordset
o bjec t will be c reated and ho w it c an be ac c essed fro m yo ur pro gram.
CrossReference
See the Recordset object in Chapter 14 for a m ore com plete discussion of
cursors and locks.
The type o f c urso r used in a Recordset determines many o f its c harac teristic s.
Client-side c urso rs are restric ted to using o nly static c urso rs, while server-side
c urso rs c an use any o f these fo ur different types o f c urso rs:
✦ Forward Only c urso rs po int to a c o llec tio n o f ro ws that c an o nly be ac c essed
in a fo rward direc tio n. Mo ving bac kwards isn’t permitted. Otherwise, this c urso r type is identic al to Static .
✦ Keyset c urso rs po int to a c o llec tio n o f ro ws that see all c hanges (inc luding
deletio ns) to the database, exc ept fo r rec o rds that have been added after the
Recordset was c reated.
151
152
Part II ✦ Beginning Database Programming
✦ Dynamic c urso rs po int to a c o llec tio n o f ro ws that see all c hanges (inc luding
additio ns and deletio ns) to the database after the Recordset was c reated.
✦ Static c urso rs po int to a c o llec tio n o f ro ws that will no t c hange until the
Recordset is c lo sed. Any ro ws that have been added, deleted, o r updated
by any o ther database user are no t seen.
The CursorLocation pro perty desc ribes where the c urso r is lo c ated. Cho o sing
Use server-side c urso rs means that the c urso r will be managed by the database
management system, while c ho o sing Use c lient-side c urso rs means that the c urso r
will be managed by a c urso r library lo c ated o n the same c o mputer as the applic atio n. Client-side c urso rs are mo re flexible than server-side c urso rs, while serverside c urso rs are easier to use than c lient-side c urso rs.
The LockType pro perty determines ho w yo u and o ther users c an ac c ess the data
in the database.
✦ Read-only lo c ks mean that yo u c an’t alter any o f the data in the Recordset.
✦ Pessimistic lo c ks mean that the ro w is lo c ked immediately when yo u begin to
c hange the values in a ro w. The lo c k will be released when yo u c o mplete yo ur
c hanges.
✦ Optimistic lo c ks mean that the ro w is no t lo c ked until yo u have finished making yo ur c hanges. Then the ro w is lo c ked and the c urrent values o f the ro w in
the database are c hec ked against the o riginal values befo re yo u c hanged
them. If they are the same, yo ur c hanges will be saved to the database, o therwise an erro r will be returned to yo ur pro gram.
✦ Batch Optimistic lo c ks wo rk just like o ptimistic lo c ks, exc ept that multiple
ro ws o f info rmatio n are updated lo c ally and are sent to the database server in
a single batc h. Any erro rs will be returned to yo ur pro gram. Yo ur pro gram
must then identify the ro ws that weren’t updated and take the appro priate
ac tio n fo r eac h ro w.
Tip
Lock least: You should lock the least am ount of data possible in order to m ake it
easy to share data. If you don’t need to update any of the data, you should use a
read-only lock. In the beginning, you should use a pessim istic lock w ith a serverside cursor to prevent others from updating the data you are editing. Once you are
com fortable w ith database program m ing, you should consider using client-side
cursors w ith either optim istic or batch optim istic locking.
The CacheSize pro perty determines ho w many ro ws are buffered in the c lient
mac hine. Inc reasing this size allo ws the database server to o perate mo re effic iently
when returning data to the c lient system. It will also impro ve the perfo rmanc e o f
the c lient system, sinc e mo st o f the time, it will retrieve data fro m the lo c al c ac he
rather than request data fro m the server. Ho wever, the data in the c ac he will no t be
updated if c hanges are made to the same ro ws o n the database server. The mo re
ro ws yo u keep in the c ac he, the greater the c hanc e that so meo ne else may have
Chapter 9 ✦ Programming with Data Environments
updated the data. If yo u c ho o se pessimistic lo c king, yo u sho uld set the CacheSize
pro perty to o ne to prevent invalid rec o rds fro m sitting in yo ur c ac he.
Reviewing other advanced properties
Like the pro perties in the Re co rdSe t Manage me nt sec tio n, tho se in the Co mmand
Co nfiguratio n sec tio n are taken fro m the Command o bjec t disc ussed in Chapter 11.
Ho wever, the Command Timeout is impo rtant eno ugh to disc uss twic e. This pro perty c o ntains the number o f sec o nds the c o mmand is allo wed to run befo re it is
c anc eled. When dealing with large vo lumes o f data o r very c o mplex sto red pro c edures, the default value o f 30 sec o nds may no t be eno ugh to allo w the c o mmand to
finish. If this happens, yo u will need to inc rease this value.
The Call Syntax sec tio n desc ribes ho w a sto red pro c edure will be c alled, inc luding
the list o f parameters and the return value. While yo u c an edit this value to c hange
the number o f parameters and presenc e o f a return value, in general yo u sho uld
leave this field alo ne.
Saving the Command
To save yo ur pro perty settings and c o ntinue wo rking with the pro perties, press
the Apply b utto n, o r to save yo ur c hanges and c lo se the Co mmand1 Pro perties
dialo g b o x, press the OK b utto n. If the Apply b utto n is grayed o ut, it indic ates
that the saved versio n o f the enviro nment is the same as the o ne yo u are viewing.
Onc e yo ur Command has b een defined, yo u c an see the list o f fields that the c o mmand will return in the Data Enviro nment b y expanding the plus sign in fro nt o f
the c o mmand’s ic o n ( see Figure 9-9) .
Figure 9-9: View ing the fields
returned by a com m and
153
154
Part II ✦ Beginning Database Programming
Adding a Child Command
One o f the nic er features o f the Data Enviro nment Designer is its ability to c reate
hierarc hic al rec o rdsets easily. Simply selec t the c o mmand yo u want to add the
c hild to and press the Add Child Co mmand butto n. This c reates a new c o mmand
that is nested at the same level as the fields o n the parent c o mmand. No te that the
c o mmand yo u c ho o se as the parent c o mmand must return a Recordset, o therwise yo u will no t be able to add the c hild c o mmand.
After selec ting the c hild c o mmand, yo u c an press the Pro perties butto n to define its
pro perties. The first thing yo u must do in the Pro perties dialo g bo x is to define the
So urc e o f Data. As with the parent c o mmand, yo u must c ho o se a So urc e o f Data
that returns a Recordset. If yo u do n’t define a so urc e o f data, yo u’ll rec eive a warning message if yo u try to ac c ess any o f the o ther tabs in the Pro perties dialo g bo x.
Onc e yo u’ve defined the So urc e o f Data, yo u sho uld define any pro perties o n the
Parameters and Advanc ed tabs that are needed to retrieve the data. No te that the
Recordset o bjec t returned by the c hild c o mmand is always read-o nly. In fac t, mo st
o f the pro perties o n the Advanc ed tab will be disabled, and the pro perties will be
set to be c o mpatible with the pro perties selec ted fo r the parent c o mmand.
Defining a relationship
On the Relatio n tab (see Figure 9-10), yo u must define ho w the parent and c hild
c o mmands are related. At the to p o f the page, yo u’ll see the Relate to a Parent
Co mmand Objec t c hec k bo x and the Parent Co mmand dro p-do wn bo x. By default,
the c hec k bo x will be c hec ked, meaning that this c o mmand is a c hild c o mmand,
and its parent c o mmand will be the o ne that was selec ted when yo u pressed the
Add Child Co mmand butto n. Unc hec king the c hec k bo x will make this a regular
c o mmand that is independent o f any o ther c o mmands in the Designer, while selec ting a different parent c o mmand will make this c o mmand a c hild o f the selec ted
c o mmand.
Figure 9-10: Defining a relationship
betw een a child com m and and its
parent
Chapter 9 ✦ Programming with Data Environments
Onc e the parent has been selec ted, yo u need to c ho o se the fields that establish the
parent c hild relatio nship in the Relatio n Definitio n frame. Spec ifying pairs o f fields,
o ne in the parent and o ne in the c hild, defines the relatio nship between the two
c o mmands. Fo r eac h ro w retrieved by the parent c o mmand, the c hild c o mmand will
be exec uted and the values fro m the parent fields will be used to selec t o nly tho se
ro ws with matc hing values in the c hild c o mmand. Sinc e this is a so mewhat c o mplex
c o nc ept, let’s use an example fro m the sample database. Assume that the parent
c o mmand retrieves all o f the ro ws fro m the Custo mers table. Then the c hild c o mmand is set up to retrieve all o f the ro ws fro m the Orders table. The relatio nship
info rmatio n spec ified o n the Relatio n tab asso c iates the Custo merId value in the
Orders table with the Custo merId value in eac h ro w retrieved fro m the Custo mers
table.
On the
CD-ROM
The inform ation needed to build the sam ple database can be found in the
\ Sam pleDB directory on the CD-ROM.
The retrieved rec o rds wo uld lo o k like the info rmatio n in Table 9-1. No tic e that fo r
eac h ro w retrieved fro m the Custo mers table (Custo merId and Name), o ne o r mo re
ro ws o f info rmatio n will be retrieved fro m the Orders table (OrderNumber and
DateOrdered).
Table 9-1
A View of a Hierarchical Recordset
CustomerId
Name
OrderNumber
DateOrdered
0
Dexter Valentine
-
-
0
-
1000
1 Jan 2000
1
Malik Hubert
-
-
1
-
1001
1 Jan 2000
1
-
1004
1 Feb 2000
2
Lee Holt
-
-
2
-
1002
2 Jan 2000
2
-
1005
2 Feb 2000
3
Scotty Waltrip
-
-
3
-
1003
3 Jan 2000
3
-
1006
3 Feb 2000
3
-
1007
3 Mar 2000
155
156
Part II ✦ Beginning Database Programming
Using groupings
An alternate way to c reate a hierarc hic al rec o rdset is to define a gro uping using the
Gro uping tab o f the Pro perties dialo g bo x (see Figure 9-11). A gro uping allo ws yo u to
take a single rec o rdset and break it into two levels. A new level is c reated eac h time
the values o f the Fie lds Use d fo r Gro uping c hange.
Figure 9-11: Selecting fields
for grouping
To define yo ur gro uping, simply selec t the field o r fields yo u want to mo ve in the
Fie lds in Co mmand sec tio n o f the fo rm and press the > butto n to mo ve them to the
Fie lds Use d fo r Gro uping. Yo u c an mo ve a field in the reverse direc tio n by using the
< butto n. The >> and butto n to add them to the Add list. Yo u c an use the >>
butto n to add all o f the sto red pro c edures to the Add list. Pressing the < o r
C H A P T E R
Programming
with Data
Environments
✦
✦
✦
✦
In This Cha pter
The Data Enviro nment
Desig ner
I
n this c hapter, I’m go ing to disc uss ho w to use the Data
Enviro nment Designer to c reate a Data Enviro nment, whic h
simplifies many o f the tasks o f building a database applic atio n. It explo its the ADO o bjec t mo del and helps yo u c reate
standardized ADO o bjec ts that simplify ac c ess to the
database.
The Data Environment Designer
The Data Enviro nment Designer is a to o l in the Visual Basic
IDE that helps a pro grammer c reate a database applic atio n
mo re quic kly than if they had to perfo rm the same tasks manually. The Designer c reates ADO o bjec ts c o rrespo nding to the
tables in yo ur database; it also pro vides o ther o bjec ts to help
yo u manipulate yo ur database. These o bjec ts are available as
part o f the Data Enviro nment o bjec t at runtime.
Note
CrossReference
ADO, not DAO and RDO: The Data Environm ent Designer
only w orks w ith the ADO object m odel. The DAO and RDO
object m odels are not supported. The UserConnection
designer is a subset of the Data Environm ent Designer and
supports the RDO object m odel.
See Chapter 6 for explanations of the ADO, DAO, and
RDO m odels.
Co nnecting to
databases
Creating and using
co mmands
Using the Data
View windo w
✦
✦
✦
✦
142
Part II ✦ Beginning Database Programming
Enabling the Data Environment Designer
To add the Data Enviro nment Designer to yo ur pro jec t, c ho o se Pro jec t ➪ Add Data
Enviro nment fro m the main menu. If yo u do n’t see it listed direc tly under the Pro jec t
menu, try lo o king under the Mo re Ac tiveX Designers menu (o r Pro jec t ➪ Mo re Ac tiveX
Designers ➪ Data Enviro nment fro m the main menu). This will display the main windo w fo r the Data Enviro nment Designer.
If the Data Enviro nment Designer do esn’t appear in either lo c atio n, yo u’ll need to
add it to Visual Basic . Cho o se Pro jec t ➪ Co mpo nents fro m the main menu to display
the Co mpo nents dialo g bo x, then selec t the Designer tab to see the windo w as
sho wn in Figure 9-1. Plac e a c hec k mark in the bo x next to Data Enviro nment and
press OK. This will add the Data Enviro nment Designer to the Pro jec t menu. If yo u
do n’t see Data Enviro nment listed o n the Designers tab, yo u need to install the Data
Enviro nment feature fro m yo ur Visual Basic CD-ROM.
Figure 9-1: Adding the Data Environm ent Designer
to the Visual Basic IDE
Exploring the Data Environment Designer
The main Data Enviro nment Designer windo w (see Figure 9-2) inc ludes a series o f
ic o ns that are used to perfo rm c o mmo n o peratio ns, plus an ic o n tree view o f the
o bjec ts used in the Data Enviro nment.
Chapter 9 ✦ Programming with Data Environments
Add
Command
Refresh
Add Child
Command
Options
Properties
Delete
Design
Insert Stored
Procedure
Arrange by Objects
Arrange by
Connections
View
Code
Icon tree
Add
Connection
Figure 9-2: Exploring the Data Environm ent Designer w indow
✦ Add Connection – adds a new Connection o bjec t to the data enviro nment,
whic h will be used to ac c ess a database.
✦ Add Command – adds a new Command o bjec t to the data enviro nment, whic h
will be used to exec ute an SQL c o mmand.
✦ Insert Stored Procedure – adds a Command o bjec t with the info rmatio n to c all
a sto red pro c edure o n the database server.
143
144
Part II ✦ Beginning Database Programming
✦ Add Child Command – adds a Command o bjec t to ano ther Command o bjec t to
c reate a hierarc hic al struc ture o f data.
✦ Delete – remo ves an o bjec t fro m the data enviro nment.
✦ Refresh – refreshes the selec ted o bjec t. Connection o bjec ts are c lo sed and
reo pened, while all o f the metadata asso c iated with a Command o bjec t will be
rebuilt.
✦ Design – ac c esses the SQL query designer when yo u spec ify an SQL statement
as the data so urc e fo r a Command o bjec t.
✦ Properties – displays the pro perties asso c iated with the selec ted o bjec t.
✦ View Code – displays the c o de asso c iated with a partic ular o bjec t.
✦ Options – displays the Optio ns dialo g bo x that c o ntro ls ho w the Data
Enviro nment Designer wo rks.
✦ Arrange by Connections – arranges the o bjec ts in the ic o n tree by the
Connection o bjec t they ac c ess.
✦ Arrange by Objects – arranges the o bjec ts in the ic o n tree by o bjec t type.
✦ Icon Tree – the list o f o bjec ts asso c iated with the data enviro nment.
Tip
Many of these functions are also available via a pop-up m enu that you can display
by right clicking on an object in the icon tree.
Data Environment building blocks
The Data Enviro nment Designer helps yo u c reate three main types o f o bjec ts:
Connections, Commands, and Recordsets. These o bjec ts are used at bo th design
time and runtime to ac c ess yo ur database. At design time, info rmatio n abo ut yo ur
database is extrac ted and made available to help yo u c reate yo ur pro gram. At runtime, these o bjec ts are used to perfo rm typic al database o peratio ns.
Tip
It’s not what it seems: While these objects appear to be part of the Data Environm ent Designer, they are really norm al ADO objects that the Data Environm ent
Designer helps you create. For m ore inform ation about all of the capabilities of
these objects, please refer to Chapter 11.
Connection objects
A Connection o bjec t c o ntains the pro perties and metho ds needed to ac c ess a
database. Sinc e the Connection o bjec t is used at bo th runtime and design time, a
related o bjec t c alled the DECconnection is used by the Data Enviro nment Designer
to trac k info rmatio n abo ut eac h mo de. This info rmatio n c o ntains the user name,
passwo rd, ho w to pro mpt fo r passwo rd info rmatio n, and whether to save passwo rd
info rmatio n at the end o f the sessio n fo r bo th runtime and design-time use.
Chapter 9 ✦ Programming with Data Environments
Command objects
A Command o bjec t c o ntains the info rmatio n nec essary to exec ute a c o mmand
against yo ur database. A c o mmand may be an SQL statement, a c all to a sto red pro c edure, o r the name o f a table. So me c o mmands will require yo u to inc lude a list o f
parameters when they are run. So me c o mmands will return a set o f ro ws, while o thers will return no thing but a status c o nditio n.
Recordset objects
Ro ws are returned fro m yo ur database in a Recordset o bjec t. The Rec o rdset o bjec t
presents a single ro w o f data, kno wn as the curre nt re co rd. A curso r is used to po int
to the c urrent rec o rd in the Recordset. Yo u c an manipulate the c urso r by using
vario us metho ds in the Recordset o bjec t.
If the ro ws in the Recordset o bjec t c an be updated, there are o ther metho ds that
allo w yo u to add a new ro w, delete a ro w, and update a ro w. If yo u need to update
multiple ro ws, yo u c an easily c reate a Command o bjec t, whic h will c all the appro priate SQL statement, o r yo u c an use the c urso r to mo ve thro ugh the ro ws in the
Recordset o bjec t o ne at a time and use the appro priate metho ds to perfo rm yo ur
updates.
Like the ADO Data Control, a Recordset o bjec t c an be used as a data so urc e
with bo und c o ntro ls. This means that yo u c an easily replac e the ADO Data
Control with the appro priate Recordset o bjec t by c hanging the DataSource
pro perty o n eac h o f the bo und c o ntro ls.
Hierarchical Recordsets
A hierarc hic al rec o rdset is based o n a no rmal Recordset, exc ept that in plac e o f
o ne o f the values in a ro w o f data is ano ther Recordset, kno wn as a child rec o rdset.
The c hild rec o rdset is c reated by a c hild Command, who se values are determined by
a relatio nship with the parent rec o rdset. It is also reaso nable fo r a c hild rec o rdset
to have its o wn c hild rec o rdsets, thus c reating a multi-level hierarc hy.
Hierarc hic al rec o rdsets are useful when yo u want to retrieve data fro m multiple
tables, but do n’t want to merge the data into a single table. The c lassic c ase o f a
hierarc hic al rec o rdset is the c usto mers, o rders, and o rder items. A c o mpany has a
c o llec tio n o f c usto mers, eac h c usto mer may have plac ed multiple o rders, and eac h
o rder a c usto mer has plac ed may have multiple items.
Connecting to Your Database
The first step in wo rking with the Data Enviro nment Designer is to define a c o nnec tio n to the database. By default the Data Enviro nment Designer c reates a single
Connection o bjec t c alled Connection1. This o bjec t is used at bo th design time
and runtime to ac c ess info rmatio n fro m the database.
145
146
Part II ✦ Beginning Database Programming
Setting Connection properties
Selec ting the Connection1 o bjec t and pressing the Pro perties butto n displays
the Data Link Pro perties dialo g bo x, as sho wn in Figure 9-3. While there are fo ur
tabs o n the dialo g bo x, o nly the Pro vider and Co nnec tio n tab are typic ally used.
The Advanc ed tab c o ntains info rmatio n regarding netwo rk settings, c o nnec tio n
timeo ut, and ac c ess permissio ns who se default settings are almo st always o kay.
The All tab lists all o f the initializatio n parameters that will be used when establishing the database c o nnec tio n.
Figure 9-3: Setting Data Link properties
for a Connection object
Selecting an OLE DB provider
The first step in defining yo ur c o nnec tio n to the database is to c ho o se an OLE DB
pro vider o n the Pro vider tab o f the Data Link Pro perties dialo g bo x. All o f the pro viders available fo r yo ur system will be listed. Yo u sho uld c ho o se the native OLE
DB pro vider fo r yo ur database server, if o ne is available. Otherwise, yo u sho uld
c ho o se the Mic ro so ft OLE DB Pro vider fo r ODBC Drivers. Onc e yo u selec t the
pro per OLE DB pro vider, press Next to c o ntinue defining the c o nnec tio n pro perties.
Entering connection information
Sinc e I c ho se the Mic ro so ft OLE DB Pro vider fo r SQL Server in the previo us step,
pressing Next will request the info rmatio n sho wn in Figure 9-4 using the Co nnec tio n
tab. In this c ase, my database server is o n Athena. I’m go ing to use Windo ws NT
integrated sec urity and I want to use the VB6DB database as my default database.
Chapter 9 ✦ Programming with Data Environments
Onc e I enter this info rmatio n, I c an press the Test Co nnec tio n butto n to verify that
everything is c o rrec t. If there is a pro blem, a message bo x will be displayed with
a desc riptio n o f the erro r; o therwise, a message bo x saying Test c o nnec tio n suc c eeded will be displayed. After pressing OK o n the test’s message bo x, press OK
to save the c o nnec tio n info rmatio n.
Figure 9-4: Entering connection
inform ation for the Microsoft
OLE DB Provider for SQL Server
CrossReference
The inform ation entered in the Data Link dialog boxes is used to build a connection
string . This value is used anytim e you w ant to connect an ADO object to a database.
For m ore inform ation about connection strings, see the ConnectionString property and the Connection object in Chapter 11. For details about how to connect to
a specific database, see Connecting to SQL Server in Chapter 23, Connecting to
Oracle8 i in Chapter 26, or Connecting to Jet in Chapter 29.
Creating Commands with the Designer
After yo u have defined a Connection o bjec t, yo u c an begin to define so me
Command o bjec ts. The Data Enviro nment Designer treats Command o bjec ts in two
different ways — as c o mmands and as sto red pro c edures. The differenc e is primarily ho w the info rmatio n fo r the o bjec ts is o btained. If yo u c ho o se to add a sto red
pro c edure, the designer will get a list o f sto red pro c edures fro m the database, yo u
will need to enter a single, dynamic ally exec uted SQL statement as o ne o f the pro perties o f the Command o bjec t. Sto red pro c edures are disc ussed later in this c hapter
under “Selec ting a Database Objec t.”
147
148
Part II ✦ Beginning Database Programming
Adding a command
Adding a Command o b jec t b y pressing the Add Co mmand b utto n o n the Data
Enviro nment Designer to o lb ar simply adds a new c o mmand o b jec t b eneath the
c urrently selec ted Connection. All o f the pro perties asso c iated with the Command
o b jec t are left at their default values and must b e c hanged in o rder to use the
c o mmand.
Setting general command properties
Pressing the Pro perties butto n o r right c lic king o n the Command o bjec t will display
the Command1 Pro perties dialo g bo x as sho wn in Figure 9-5. On the General tab, yo u
c an spec ify the name o f the c o mmand, whic h c o nnec tio n will be used by the c o mmand, and the So urc e o f Data fo r the c o mmand.
Figure 9-5: View ing the general
properties of the Com m and1 object
The So urc e o f Data sec tio n is so mewhat misleading sinc e a Command o bjec t need
no t return data. It really depends o n whether the database o bjec t yo u selec t o r the
SQL statement yo u enter returns any data.
Selecting a database object
Yo u have a c ho ic e o f fo ur different database o bjec ts: a Sto red Pro c edure, a Table, a
View, o r a Syno nym. A sto re d pro ce dure is no thing but a series o f o ne o r mo re SQL
statements that are exec uted o n the database server. Any data returned depends
o n whether the sto red pro c edure inc ludes a Select statement. Selec ting Table o r
View will always return all o f the data visible in the selec ted table o r view. A syno nym is an alternate name fo r a database o bjec t, suc h as a table o r view.
Onc e yo u selec t whic h type o f database o bjec t yo u want, yo u must spec ify the
o bjec t name. The designer makes this easy bec ause after yo u spec ify the type o f
database o bjec t yo u want, it will auto matic ally c o nnec t to the database server using
Chapter 9 ✦ Programming with Data Environments
the spec ified Connection o bjec t and retrieve the list o f available o bjec ts. These
o bjec ts are then made available in the Objec t Name dro p-do wn list direc tly belo w
the Database Objec t dro p do wn bo x. All yo u need to do is selec t the o ne yo u want.
Entering an SQL Statement
If yo u want the c o mmand to exec ute an SQL statement, simply enter the statement
in the SQL Statement area in the dialo g bo x. No o ther statement, exc ept fo r the
Select statement, will return data. To make it easier to c reate an SQL Select statement, yo u c an press the SQL Builder butto n to display the Design windo w, whic h
will help yo u build SQL queries.
One o f the side effec ts o f using an SQL statement o r a sto red pro c edure is that the
designer do esn’t kno w what fields will be returned. The o nly way fo r the Command
o bjec t to kno w what fields are returned is to exec ute the c o mmand. Befo re exec uting the c o mmand, the designer will ask yo u fo r permissio n (see Figure 9-6), sinc e
the c o mmand c o uld po tentially update yo ur database.
Figure 9-6: Asking for perm ission
to execute an SQL statem ent
Tip
Test it first: You should take the tim e to verify that the SQL statem ent w ill w ork
before you enter it into the SQL Statem ent area. The easiest w ay to do this is to
use a tool like SQL Server’s Query Analyzer.
Setting parameters
If yo u are using a sto red pro c edure as yo ur c o mmand, yo u will pro bably have o ne
o r mo re parameters asso c iated with it. Co nsider the sto red pro c edure in Listing 9-1.
It will retrieve all o f the info rmatio n abo ut the c usto mer spec ified in CustId.
Listing 9-1: The GetCustomer stored procedure
Create Procedure GetCustomer (@CustId Int)
As
Select *
From Customers
Where CustomerId = @CustId
149
150
Part II ✦ Beginning Database Programming
Figure 9-7 sho ws yo u the Parameters tab o f the Pro perties dialo g bo x. Yo u c an view
the details abo ut a partic ular parameter by c lic king o n it in the Parameters frame.
The info rmatio n related to it will be displayed in the Parameter Pro perties frame.
Figure 9-7: Looking at the
param eters of a stored
procedure
Eac h parameter has a number o f different pro perties asso c iated with it:
✦ Name – c o ntains the fo rmal name o f the parameter.
✦ Direction – c lassifies the parameter as input, o utput, o r input/ o utput parameter.
✦ Data_Type – spec ifies the data type asso c iated with the parameter.
✦ Precision – spec ifies the prec isio n o f a numeric data type.
✦ Scale – spec ifies the sc ale o f a numeric data type. This field is disabled fo r
no n-numeric data types.
✦ Size – spec ifies the size asso c iated with the data type. This field is disabled
fo r no n-numeric data types.
✦ Host Data Type – spec ifies the data type that will be used by the ho st. This
value must be c o mpatible with the value spec ified in the Data_Type field.
✦ Required – is TRUE when yo u must spec ify a value fo r the parameter befo re
the c o mmand c an be exec uted.
✦ Value – c o ntains the default value fo r the parameter. It will be used at design
time to test the Command o bjec t. At runtime, yo u will typic ally o verride this
value with the real value yo u wish to use.
Chapter 9 ✦ Programming with Data Environments
Note
I can’t change anything: If the type of com m and you are creating doesn’t allow
param eters, all of the fields on this tab w ill be blank, and even if the type of com m and does support param eters, som e of the properties of the param eter m ay be
disabled, m eaning that you can’t change them .
Setting advanced properties
The Advanc ed Pro perties tab (see Figure 9-8) c o ntains a number o f different pro perties that affec t ho w the c o mmand will be exec uted and ho w the results will be
returned. Depending o n the type o f c o mmand yo u c ho o se, so me o r mo st o f these
pro perties may be disabled.
Figure 9-8: Review ing
advanced properties
Reviewing Recordset management properties
The fo ur pro perties in the Re co rdSe t Manage me nt sec tio n ( CursorType,
CursorLocation, LockType and CacheSize) c o ntro l ho w the Recordset
o bjec t will be c reated and ho w it c an be ac c essed fro m yo ur pro gram.
CrossReference
See the Recordset object in Chapter 14 for a m ore com plete discussion of
cursors and locks.
The type o f c urso r used in a Recordset determines many o f its c harac teristic s.
Client-side c urso rs are restric ted to using o nly static c urso rs, while server-side
c urso rs c an use any o f these fo ur different types o f c urso rs:
✦ Forward Only c urso rs po int to a c o llec tio n o f ro ws that c an o nly be ac c essed
in a fo rward direc tio n. Mo ving bac kwards isn’t permitted. Otherwise, this c urso r type is identic al to Static .
✦ Keyset c urso rs po int to a c o llec tio n o f ro ws that see all c hanges (inc luding
deletio ns) to the database, exc ept fo r rec o rds that have been added after the
Recordset was c reated.
151
152
Part II ✦ Beginning Database Programming
✦ Dynamic c urso rs po int to a c o llec tio n o f ro ws that see all c hanges (inc luding
additio ns and deletio ns) to the database after the Recordset was c reated.
✦ Static c urso rs po int to a c o llec tio n o f ro ws that will no t c hange until the
Recordset is c lo sed. Any ro ws that have been added, deleted, o r updated
by any o ther database user are no t seen.
The CursorLocation pro perty desc ribes where the c urso r is lo c ated. Cho o sing
Use server-side c urso rs means that the c urso r will be managed by the database
management system, while c ho o sing Use c lient-side c urso rs means that the c urso r
will be managed by a c urso r library lo c ated o n the same c o mputer as the applic atio n. Client-side c urso rs are mo re flexible than server-side c urso rs, while serverside c urso rs are easier to use than c lient-side c urso rs.
The LockType pro perty determines ho w yo u and o ther users c an ac c ess the data
in the database.
✦ Read-only lo c ks mean that yo u c an’t alter any o f the data in the Recordset.
✦ Pessimistic lo c ks mean that the ro w is lo c ked immediately when yo u begin to
c hange the values in a ro w. The lo c k will be released when yo u c o mplete yo ur
c hanges.
✦ Optimistic lo c ks mean that the ro w is no t lo c ked until yo u have finished making yo ur c hanges. Then the ro w is lo c ked and the c urrent values o f the ro w in
the database are c hec ked against the o riginal values befo re yo u c hanged
them. If they are the same, yo ur c hanges will be saved to the database, o therwise an erro r will be returned to yo ur pro gram.
✦ Batch Optimistic lo c ks wo rk just like o ptimistic lo c ks, exc ept that multiple
ro ws o f info rmatio n are updated lo c ally and are sent to the database server in
a single batc h. Any erro rs will be returned to yo ur pro gram. Yo ur pro gram
must then identify the ro ws that weren’t updated and take the appro priate
ac tio n fo r eac h ro w.
Tip
Lock least: You should lock the least am ount of data possible in order to m ake it
easy to share data. If you don’t need to update any of the data, you should use a
read-only lock. In the beginning, you should use a pessim istic lock w ith a serverside cursor to prevent others from updating the data you are editing. Once you are
com fortable w ith database program m ing, you should consider using client-side
cursors w ith either optim istic or batch optim istic locking.
The CacheSize pro perty determines ho w many ro ws are buffered in the c lient
mac hine. Inc reasing this size allo ws the database server to o perate mo re effic iently
when returning data to the c lient system. It will also impro ve the perfo rmanc e o f
the c lient system, sinc e mo st o f the time, it will retrieve data fro m the lo c al c ac he
rather than request data fro m the server. Ho wever, the data in the c ac he will no t be
updated if c hanges are made to the same ro ws o n the database server. The mo re
ro ws yo u keep in the c ac he, the greater the c hanc e that so meo ne else may have
Chapter 9 ✦ Programming with Data Environments
updated the data. If yo u c ho o se pessimistic lo c king, yo u sho uld set the CacheSize
pro perty to o ne to prevent invalid rec o rds fro m sitting in yo ur c ac he.
Reviewing other advanced properties
Like the pro perties in the Re co rdSe t Manage me nt sec tio n, tho se in the Co mmand
Co nfiguratio n sec tio n are taken fro m the Command o bjec t disc ussed in Chapter 11.
Ho wever, the Command Timeout is impo rtant eno ugh to disc uss twic e. This pro perty c o ntains the number o f sec o nds the c o mmand is allo wed to run befo re it is
c anc eled. When dealing with large vo lumes o f data o r very c o mplex sto red pro c edures, the default value o f 30 sec o nds may no t be eno ugh to allo w the c o mmand to
finish. If this happens, yo u will need to inc rease this value.
The Call Syntax sec tio n desc ribes ho w a sto red pro c edure will be c alled, inc luding
the list o f parameters and the return value. While yo u c an edit this value to c hange
the number o f parameters and presenc e o f a return value, in general yo u sho uld
leave this field alo ne.
Saving the Command
To save yo ur pro perty settings and c o ntinue wo rking with the pro perties, press
the Apply b utto n, o r to save yo ur c hanges and c lo se the Co mmand1 Pro perties
dialo g b o x, press the OK b utto n. If the Apply b utto n is grayed o ut, it indic ates
that the saved versio n o f the enviro nment is the same as the o ne yo u are viewing.
Onc e yo ur Command has b een defined, yo u c an see the list o f fields that the c o mmand will return in the Data Enviro nment b y expanding the plus sign in fro nt o f
the c o mmand’s ic o n ( see Figure 9-9) .
Figure 9-9: View ing the fields
returned by a com m and
153
154
Part II ✦ Beginning Database Programming
Adding a Child Command
One o f the nic er features o f the Data Enviro nment Designer is its ability to c reate
hierarc hic al rec o rdsets easily. Simply selec t the c o mmand yo u want to add the
c hild to and press the Add Child Co mmand butto n. This c reates a new c o mmand
that is nested at the same level as the fields o n the parent c o mmand. No te that the
c o mmand yo u c ho o se as the parent c o mmand must return a Recordset, o therwise yo u will no t be able to add the c hild c o mmand.
After selec ting the c hild c o mmand, yo u c an press the Pro perties butto n to define its
pro perties. The first thing yo u must do in the Pro perties dialo g bo x is to define the
So urc e o f Data. As with the parent c o mmand, yo u must c ho o se a So urc e o f Data
that returns a Recordset. If yo u do n’t define a so urc e o f data, yo u’ll rec eive a warning message if yo u try to ac c ess any o f the o ther tabs in the Pro perties dialo g bo x.
Onc e yo u’ve defined the So urc e o f Data, yo u sho uld define any pro perties o n the
Parameters and Advanc ed tabs that are needed to retrieve the data. No te that the
Recordset o bjec t returned by the c hild c o mmand is always read-o nly. In fac t, mo st
o f the pro perties o n the Advanc ed tab will be disabled, and the pro perties will be
set to be c o mpatible with the pro perties selec ted fo r the parent c o mmand.
Defining a relationship
On the Relatio n tab (see Figure 9-10), yo u must define ho w the parent and c hild
c o mmands are related. At the to p o f the page, yo u’ll see the Relate to a Parent
Co mmand Objec t c hec k bo x and the Parent Co mmand dro p-do wn bo x. By default,
the c hec k bo x will be c hec ked, meaning that this c o mmand is a c hild c o mmand,
and its parent c o mmand will be the o ne that was selec ted when yo u pressed the
Add Child Co mmand butto n. Unc hec king the c hec k bo x will make this a regular
c o mmand that is independent o f any o ther c o mmands in the Designer, while selec ting a different parent c o mmand will make this c o mmand a c hild o f the selec ted
c o mmand.
Figure 9-10: Defining a relationship
betw een a child com m and and its
parent
Chapter 9 ✦ Programming with Data Environments
Onc e the parent has been selec ted, yo u need to c ho o se the fields that establish the
parent c hild relatio nship in the Relatio n Definitio n frame. Spec ifying pairs o f fields,
o ne in the parent and o ne in the c hild, defines the relatio nship between the two
c o mmands. Fo r eac h ro w retrieved by the parent c o mmand, the c hild c o mmand will
be exec uted and the values fro m the parent fields will be used to selec t o nly tho se
ro ws with matc hing values in the c hild c o mmand. Sinc e this is a so mewhat c o mplex
c o nc ept, let’s use an example fro m the sample database. Assume that the parent
c o mmand retrieves all o f the ro ws fro m the Custo mers table. Then the c hild c o mmand is set up to retrieve all o f the ro ws fro m the Orders table. The relatio nship
info rmatio n spec ified o n the Relatio n tab asso c iates the Custo merId value in the
Orders table with the Custo merId value in eac h ro w retrieved fro m the Custo mers
table.
On the
CD-ROM
The inform ation needed to build the sam ple database can be found in the
\ Sam pleDB directory on the CD-ROM.
The retrieved rec o rds wo uld lo o k like the info rmatio n in Table 9-1. No tic e that fo r
eac h ro w retrieved fro m the Custo mers table (Custo merId and Name), o ne o r mo re
ro ws o f info rmatio n will be retrieved fro m the Orders table (OrderNumber and
DateOrdered).
Table 9-1
A View of a Hierarchical Recordset
CustomerId
Name
OrderNumber
DateOrdered
0
Dexter Valentine
-
-
0
-
1000
1 Jan 2000
1
Malik Hubert
-
-
1
-
1001
1 Jan 2000
1
-
1004
1 Feb 2000
2
Lee Holt
-
-
2
-
1002
2 Jan 2000
2
-
1005
2 Feb 2000
3
Scotty Waltrip
-
-
3
-
1003
3 Jan 2000
3
-
1006
3 Feb 2000
3
-
1007
3 Mar 2000
155
156
Part II ✦ Beginning Database Programming
Using groupings
An alternate way to c reate a hierarc hic al rec o rdset is to define a gro uping using the
Gro uping tab o f the Pro perties dialo g bo x (see Figure 9-11). A gro uping allo ws yo u to
take a single rec o rdset and break it into two levels. A new level is c reated eac h time
the values o f the Fie lds Use d fo r Gro uping c hange.
Figure 9-11: Selecting fields
for grouping
To define yo ur gro uping, simply selec t the field o r fields yo u want to mo ve in the
Fie lds in Co mmand sec tio n o f the fo rm and press the > butto n to mo ve them to the
Fie lds Use d fo r Gro uping. Yo u c an mo ve a field in the reverse direc tio n by using the
< butto n. The >> and butto n to add them to the Add list. Yo u c an use the >>
butto n to add all o f the sto red pro c edures to the Add list. Pressing the < o r