Mastering VB6 Database

SYBEX Supplement
Mastering Database Programming with Visual Basic 6

by Evangelos Petroutsos
Appendix: ADO 2.5 Object Model
Screen reproductions produced with Collage Complete. Collage Complete is a trademark of Inner Media Inc. SYBEX, Network Press, and the Network Press logo are registered trademarks of SYBEX Inc. Mastering, Expert Guide, Developers Handbook, and No experience required. are trademarks of SYBEX Inc. TRADEMARKS: SYBEX has attempted throughout this book to distinguish proprietary trademarks from descriptive terms by following the capitalization style used by the manufacturer. Netscape Communications, the Netscape Communications logo, Netscape, and Netscape Navigator are trademarks of Netscape Communications Corporation. Microsoft Internet Explorer 1996 Microsoft Corporation. All rights reserved. Microsoft, the Microsoft Internet Explorer logo, Windows, Windows NT, and the Windows logo are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The author and publisher have made their best efforts to prepare this book, and the content is based upon final release software whenever possible. Portions of the manuscript may be based upon pre-release versions supplied by software manufacturer(s). The author and the publisher make no representation or warranties of any kind with regard to the completeness or accuracy of the contents herein and accept no liability of any kind including but not limited to performance, merchantability, fitness for any particular purpose, or any losses or damages of any kind caused or alleged to be caused directly or indirectly from this book. Photographs and illustrations used in this book have been downloaded from publicly accessible file archives and are used in this book for news reportage purposes only to demonstrate the variety of graphics resources available via electronic access. Text and images available over the Internet may be subject to copyright and other rights owned by third parties. Online availability of text and images does not imply that they may be reused without the permission of rights holders, although the Copyright Act does permit certain unauthorized reuse as fair use under 17 U.S.C. Section 107. Copyright 2000 SYBEX Inc., 1151 Marina Village Parkway, Alameda, CA 94501. World rights reserved. No part of this publication may be stored in a retrieval system, transmitted, or reproduced in any way, including but not limited to photocopy, photograph, magnetic or other record, without the prior agreement and written permission of the publisher.
A P P E N D I X
ADO 2.5 Object Model
Copyright 2000 SYBEX Inc., Alameda, CA
www.sybex.com
824
Appendix ADO 2.5 Object Model
ADO Objects
The ADO object model is the simplest data-access model yet, consisting of just a few objects and collections. Most objects expose several members, which are discussed in the following sections. These are the objects exposed by ADO 2.5. The Record and Stream objects are new to ADO 2.5 and are used in accessing semistructured data stores such as e-mail and file systems. Connection Object Errors Collection
Command Object Parameters Collection
Recordset Object Fields Collection
Record Object Fields Collection
Stream Object
Most objects support the Properties collection, which is made up of Property objects. This collection contains provider-specific information, through properties that are not part of ADO. We use this property to query the provider about specifics, such as the maximum number of columns it can return in a cursor, whether it supports OUTER joins and so on. Most developers never use the Properties collectionsyou may have to query a provider if youre writing applications that might contact several providers, or if you want to take advantage of a specific feature of a provider. For example, Access doesnt support the OUTER JOIN operation, while SQL Server does.
Connection Object
A Connection object represents an open connection to a data source. The Connection object is used to indicate the database against which a command will be executed, or the database from which the rows of a Recordset object will come from. In a client/server environment, the Connection object contains all the information needed to establish a connection to the database server and access the specified database. You usually set up a Connection object and then use it as argument to the methods of the Command and Recordset objects that access the database. However, you
www.sybex.com
ADO Objects
825
can use the Connection objects Execute method to execute a Command object directly against the database, as long as the command doesnt pass any parameters to the query or stored procedure. In addition, you must use the Connection object to execute multiple commands in a transaction. Finally, you must use the Connection objects OpenSchema method to retrieve schema information about your database. To execute a command through the Connection object, declare a Connection object and a Recordset object where the result of the query will be stored. Then, create a Command object, set its Name property, and execute it through the Connection object by calling its name:
Dim CN As New ADODB.Connection Dim CMD As New ADODB.Command Dim RS As New ADODB.Recordset CN.Open <connection string> CN.Name = GetBalances CMD.ActiveConnection = CN CN.GetBalances <parameters>, RS
To execute a stored procedure, use the stored procedures name as if it were a method of the Connection object:
Dim CN As New ADODB.Connection CN.sp_name <parameters>
The <parameters> expression is a string with the names and values of the parameters you want to pass to parameterized query or stored procedure.
Properties
Attributes This property indicates the transactional facilities of a Connection object and is an adXactAttributeEnum constant or a combination of these constants. CommandTimeout This property indicates how long to wait for a command to be executed on the Connection object. This value is expressed in seconds, and its default value is 30 seconds. If the command times out, a runtime error is generated. ConnectionString This property contains the information required to establish a connection to a data source. The information is stored in a string, and it consists of a series of argument = value statements, separated by semicolons, as in the following example:
CN.ConnectionString = Provider=Microsoft.Jet.OLEDB.4.0; & _ Data Source=C:\VB\NWind.mdb
www.sybex.com
826
You must pass the following five items to a Connection object to establish a connection to the database: Provider = <provider name> This is the name of a provider: OLEDBSQL for SQL Server, OLEDBJet for the OLE DB driver for Access databases, and so on. This item is used for Recordsets that have been persisted to a file; <file_name> is the name of the file where the Recordset has been persisted. This item specifies the name of a provider to be used with a client-side connection. Specifies the path name of the server to use when opening a client-side connection. (Remote Data Service only.) Specifies the connection string as an absolute URL identifying a resource, such as a file or directory.
File Name = <file name>
Remote Provider = <remote provider name>
Remote Server = <remote server name>
URL=<absolute URL>
After you set the ConnectionString property and open the Connection object, the provider may alter the contents of the property, for example, by mapping the ADO-defined argument names to their provider equivalents. The ConnectionString property automatically inherits the value used for the ConnectionString argument of the Open method, and you can override the current ConnectionString property during the Open method call. If you specify the File Name item in the ConnectionString, ADO will load the associated provider and will ignore the Provider setting. You cant pass both the Provider and File Name items in the string. ConnectionTimeout This property indicates how long to wait while establishing a connection before terminating the attempt and generating an error. Set the value of this property to the number of seconds you want to wait before the connection times out. The default value is 15 seconds.
www.sybex.com
ADO Objects
827
CursorLocation This property sets or returns the location of the cursor, and its value is a CursorLocationEnum constant. Any Recordsets created through a Connection object inherits the CursorLocation setting of the Connection object. DefaultDatabase This is the default database for a Connection object. If there is a default database, SQL strings may use an unqualified syntax to access objects in that database (i.e., you can omit the database name). If you have not defined a default database, you must prefix the database object names with the name of the database. Errors Collection Any errors that may occur during the execution of a command against a database are stored in the Error collection of the Connection object. IsolationLevel This property indicates the level of isolation for a Connection object. This property is set to an IsolationLevelEnum constant and its default type is adXactChaos. The isolation level determines how other transactions interact with yours, whether your application is allowed to see changes made by other transactions, and whether other transactions can see changes made by your transaction. Mode Mode indicates the available permissions for modifying data in a Connection, Record, or Stream object; its setting is one of the ConnectModeEnum constants. The default value for a Record object is adModeRead. The default value for a Stream associated with an underlying source (opened with a URL as the source or as the default Stream of a Record) is adReadOnly. The default value for a Stream not associated with an underlying source (instantiated in memory) is adReadWrite. Properties Collection This is a collection of Property objects that contain provider-specific information about the Connection object. Provider The Provider property returns the name of the provider used with the Connection object. The value of the provider is MSDASQL for ODBC Microsoft.Jet.OLEDB.4.0 for Access SQLOLEDB for SQL Server MSDAORA for Oracle MSDataShape for the Microsoft Data Shape driver, which returns hierarchical Recordsets State This property indicates whether a Connection object is open or not, and the propertys value is an ObjectStateEnum constant. If a Connection is open, you cant call its Open method again to establish a connection to a different database. You must first close it, and then open it with a new connection string.
www.sybex.com
828
Version This property sets or returns the name of the provider for a Connection object. When you set the ConnectionString property, or the connectionString argument of the Connection objects Open method, the Provider property is set automatically. The default provider is MSDASQL. This is the OLE DB provider for ODBC, and you use it to access all ODBC-compliant databases that dont have a native OLE DB provider.
Methods
level = BeginTrans CommitTrans RollbackTrans These methods manage transactions. To initiate a transaction, use the BeginTrans method. Then, code all the actions involved in the transaction. Finally, call the CommitTrans method to complete the transaction, or call the RollbackTrans to abandon the transaction and undo the changes made so far in the transaction. The BeginTrans method returns a value that indicates the nesting level of the transaction. The top transactions level is 1. If youre executing nested transactions by initiating a new transaction before another one has completed, then the BeginTrans method that initiates the nested transaction will return the value 2, and so on. Not all providers support transactions. Verify that the provider-defined property Transaction DDL appears in the Connection objects Properties collection, indicating that the provider supports transactions. If the provider does not support transactions, calling one of these methods will return an error. Cancel The Cancel method cancels the execution of a pending asynchronous Execute or Command method. Any of these methods can be executed asynchronously, and you can offer users a chance to cancel the operation (if they take too long) with a Cancel button. The Cancel method of the Connection object does not recognize any arguments, which means you cant initiate multiple asynchronous operations on the same Connection object. Close This method closes an open Recordset (or Connection, Record, and Stream) object. Closing an object does not remove it from memory, but it frees the resource allocated to it by the system. You can change the objects properties and open it again later. To completely eliminate an object from memory, set the object variable to Nothing. When you close a Connection object, any active Recordset objects associated with the connection will also be closed. When you close a Recordset, Record, or Stream object, the system releases the associated data. One of the most common runtime errors is that the requested operation cant be performed on a closed object. You may
www.sybex.com
ADO Objects
829
have forgotten to open a connection for a Recordset, or even to open the Recordset itself. See the discussion of the Open method for more information on opening and closing objects. Execute [commandText, recordsAffected, options] This method executes the specified SQL statement or stored procedure. If the command returns a Recordset, then use the following syntax
Set RS = CN.Execute (commandText, recordsAffected, options)
where CN is a Connection object. commandText is a string holding the name of the SQL statement, table name, or stored procedure; recordsAffected is a variable that returns the number of rows affected by the operation. The options argument indicates how the provider will interpret the commandText argument. Its value is CommandTypeEnum or ExecuteOptionEnum constant. The Recordset returned by the Execute method is a read-only, forward-only Recordset. If you need a different type pf Recordset, you must create a Recordset variable, set its properties, and then use the Recordset objects Open method to populate it. Open [connectionString, userID, password, options] This method opens a connection to a data source. The connectionString argument contains connection information. userID and password are two strings with the users ID and password that will be used to verify the user against the database. The userID and password arguments overwrite the equivalent settings in the connectionString argument. The last argument, options, is a ConnectOptionEnum constant that determines whether this method runs synchronously or asynchronously. When you no longer need the connection, call its Close method to free any associated system resources. Closing an object does not remove it from memory. To completely eliminate an object from memory, set the object variable to Nothing. Set Recordset = _ Connection.OpenSchema (queryType [, criteria, schemaID] ) The OpenSchema method returns database schema information from the provider information such as the tables in the database: their columns, data types, and so on. The information is returned in a Recordset object, and the exact contents of the Recordset depend on the queryType argument, which is a SchemaEnum constant. The criteria optional argument is an array of query constraints. The constraints for each queryType constant are listed in the same table with the SchemaEnum constants, at the end of this appendix. The schemaID argument is used with providers that support schema queries that are not defined in the OLE DB specification. This argument is ignored if the queryType is set to a value other than adSchemaProviderSpecific. Use the adSchemaProviderSpecific constant if the provider defines its own nonstandard schema queries.
www.sybex.com
830
The following code will display the names of all the tables in a database on a ListBox control. It assumes that you have set up a DataEnvironment object to connect to a database:
DataEnvironment1.Connection1.Open Set RSTables = _ DataEnvironment1.Connection1.OpenSchema(adSchemaTables) While Not RSTables.EOF If RSTables.Fields(TABLE_TYPE) <> SYSTEM TABLE Then List1.AddItem RSTables.Fields(TABLE_NAME) End If RSTables.MoveNext Wend
To retrieve the names of the columns of all tables, use the following statements:
Set RSCols = _ DataEnvironment1.Connection1.OpenSchema(adSchemaColumns) currCatalog = RSCols.Fields(TABLE_NAME) List1.AddItem TABLE & currCatalog List1.AddItem COLUMNS RSCols.MoveNext While RSCols.Fields(TABLE_NAME) = currCatalog List1.AddItem vbTab & RSCols.Fields(COLUMN_NAME) RSCols.MoveNext If RSCols.EOF Then GoTo BreakLoop If currCatalog <> RSCols.Fields(TABLE_NAME) Then currCatalog = RSCols.Fields(TABLE_NAME) List1.AddItem TABLE & currCatalog List1.AddItem COLUMNS End If Wend BreakLoop: Set RSTables = Nothing Set RSCols = Nothing
Events
The Connection object fires several events. To program a Connection objects events, you must declare it with the WithEvents keyword:
Dim WithEvents CN As ADODB.Connection
www.sybex.com
ADO Objects
831
The events fired by the Connection object are the following: Connection Object BeginTransComplete CommitTransComplete ConnectComplete Disconnect ExecuteComplete InfoMessage RollbackTransCommit WillConnect WillExecute Indication Completion of a BeginTrans method. Completion of a CommitTrans method. An asyncronous connection attempt has completed (successfully or otherwise). Temination of a connection to a database. The asynchronous execution of a command has completed (successfully or otherwise). A connection completed successfully; provides additional information returned by the provider. The completion of a CommitTrans method. The Connection object is about to establish a connection to a database. The Connection object is about to execute a command against the database.
Command Object
A Command object is a definition of a specific command that you intend to execute against a data source. You use this object to execute commands against the database. The commands can be SQL statements or stored procedures, which either retrieve rows from the database or update the database. To execute a command, you must set up a Connection object and a Command object. If the Command object invokes a stored procedure in the database, you may have to create a Parameters collection and add Parameter objects to this collection. Each Parameter object corresponds to a different parameter of the stored procedure.
Properties
ActiveConnection This property indicates the Connection to which the Command object belongs. You can assign to this property a Connection object or a string that contains the connections ConnectionString property. You should prefer the first method because this allows you to reuse an existing connection. When you specify
www.sybex.com
832
the connections properties with a connection string, ADO creates a new Connection object. CommandText This property contains a string with the text of a command that you want to issue against a database. The value of this property is a string that contains an SQL statement, a table name, a relative URL, or a stored procedure name. CommandTimeout This property indicates how long to wait while executing a command before terminating the attempt and generating an error. Its default value is 30 seconds. Notice that the Connection objects Timeout property has no effect on the CommandTimeout property of the Command objects on this connection. CommandType This property sets/returns the type of a Command object, and is a CommandEnumType constant. You can also use the adExecuteNoRecords constant (this is an ExecuteOptionEnum constant). Although ADO will figure out the commands type, you can optimize the execution of the command by specifying its type (it minimizes the internal processing). If you dont set this property or set it to adCmdUnknown (the default value), ADO will attempt to execute it first as an SQL statement, then as a stored procedure, and finally as a table name. In other words, ADO uses a trial-and-error technique to resolve the commands type. Name This is the name of the Command object. The Name property is rarely used in programming, but if you name a Command object, ADO adds a method and a Recordset object to the Command object, and names them according to the Command objects name. For example, when you add a new Command object to the DataEnvironment object and name it cmdCustomers, ADO will automatically create the cmdCustomers method (which you can call to execute the command and retrieve the desired rows). It will also create the rscmdCustomers Recordset (which will be automatically populated when you call the cmdCustomers method). Parameters Collection This collection is made up of Parameter objects. Each Parameter object contains information about a parameter of the query or stored procedure you will execute through the Command object. For a discussion of the members of a Parameter object, see the description of the Parameters collection. Prepared This property sets returns a Boolean value that determines whether to save a compiled version of a command before executing it. If you save the compiles version of the command before executing it (by setting its Prepared option to True), the command will take longer to execute the first time. Subsequent calls to the same command will return sooner, however, because the complied version is already available. If the property is False, the provider will execute the Command object directly without creating a compiled version. Properties Collection This is a collection of Property objects that contain provider-specific information about the Command object.
www.sybex.com
ADO Objects
833
State This property indicates whether a Command has completed its execution or is still executing. Its value is an ObjectStateEnum constant.
Methods
Cancel This method cancels the execution of a pending asynchronous Execute or Open method call. The Cancel method cancels the Execute method of a Command object, the Execute or Open method of the Connection object, the Open method (as well as the CopyRecord, DeleteRecord, and MoveRecord methods) of a Record object, the Open method of the Recordset object, and the Open method of the Stream object. Set parameter = _ Command.CreateParameter ([name, type, direction, size, value] ) Use this method to create a new Parameter object with the specified properties. The new Parameter object must be appended to a Command objects Parameters collection with the Append method. The name argument is the parameters name, type is the parameters data type, and size is the parameters size in bytes or characters. The direction argument is equivalent to the parameters Direction property, and it specifies whether its an input or output parameter. The last argument, value, is the parameters value. As you can see from the syntax of the method, all arguments are optional. You can create a Parameter object and then set all its properties as follows:
Set oParam = CMD.CreateParameter oParam.Name = parameter1 oParam.Type = adTypeInteger oParam.Direction = adParameterDirectionInput oParam.Value = 1001
Set RS = Command.Execute ([recordsAffected, parameters, options] ) The Execute method executes an SQL statement or stored procedure, as specified by the CommandText property. If the command retrieves a cursor, the Execute command will return a Recordset object. The recordsAffected optional argument is set by the provider, and its the number of rows affected by the command. This argument is set only for action queries or stored procedures. recordsAffected does not return the number of records returned by a result-returning query or stored procedure. The parameters argument is also optional, and its an array of parameter values passed to an SQL statement. You cant retrieve output parameters when passing parameters with this method. The last argument, options, is also optional, and it specifies how the provider should evaluate the CommandText property of the Command object. This property can be one or more CommandTypeEnum or ExecuteOptionEnum constants.
www.sybex.com
834
If the CommandText property specifies a cursor-returning query, the results of the query are stored in a new Recordset object. If the command is not a cursorreturning query, the provider returns a closed Recordset object.
Events
The Command object does not fire any events.
Recordset Object
A Recordset object represents a cursor retrieved from a database by executing a Command (usually a SELECT SQL statement). The Recordset has the structure of a grid. The columns map fields, and the rows map records. However, you cant access a row with an index; you must first move to the desired row, which is referred to as current row, and then access this rows fields.
Properties
AbsolutePage This property specifies the page on which the current row resides. The size of the page can be set with the PageSize property. AbsolutePosition This property specifies the position of the current row in a Recordset object; its an ordinal number between 1 and the number of rows in the Recordset (property RecordCount). ActiveCommand This property returns the Command object that created the Recordset object. If the Recordset is not based on a command, the ActiveCommand property returns an empty string. ActiveConnection This property sets or returns the Connection object used by a Recordset to connect to the database. The ActiveConnection property applies to Command and Recordset objects as well. This property does not return an object. Instead, it returns a string with the definition of the connection (the ConnectionString property). To set the ActiveConnection property, use a Connection object:
rs.ActiveConnection = CN
When you request the value of this property (with a statement such as Print rs .ActiveConnection), a string like the following one will be returned:
Provider=SQLOLEDB.1;Persist Security Info=False; User ID=sa;Initial Catalog=Northwind
BOF, EOF The BOF property returns True if the current row is ahead of the first row in the Recordset. The EOF property returns True if the current row is after the last row in the Recordset. If both BOF and EOF are True, then the Recordset is empty. The EOF property is also set to True by the Find and Seek operations to indicate that
www.sybex.com
ADO Objects
835
theres no matching row in the Recordset. Heres how you determine whether a row was located or not:
RS.Find CompanyName LIKE SYBEX% If RS.EOF Then MsgBox No rows were found Else {process record} End If
Bookmark This property returns a bookmark that uniquely identifies the current row in a Recordset. You can also set this property to move to another row. To bookmark a row, use the following statement:
thisRow = RS.BookMark {other statements}
You can return to a bookmarked row by assigning an existing bookmark to the Recordsets Bookmark property:
RS.Bookmark = thisRow
Do not compare bookmarks with the usual relational operators. Use the CompareBookmark method instead. You can also use the SelectedItem property of the dataaware controls (DataList and DataCombo controls) as a bookmark to move to the row selected on the control:
RS.Bookmark = DataList1.SelectedItem
CacheSize This property specifies how many rows are stored in the cache. If a row exists in the cache, ADO doesnt fetch it from the database. (As a result, a row in the cache may not be the same as the corresponding row in the database.) CursorLocation This property sets or returns the location of a cursor, and its value is one of the CursorLocationEnum constants. Client cursors are transmitted to the client. They are required if you want to automatically populate a data-bound control, such as the DataList control. Server-side cursors reside on the server, and their rows are moved to the client as needed. The CursorLocation, as well as the CursorType property, must be set before the Recordset is opened. Notice that you cant set the cursors location and type when you create a Recordset with the Recordset.Open method. RDS (Remote Data Services) Recordsets reside always on the client. CursorType This property sets or returns the type of a cursor, and its value is one of the CursorTypeEnum constants. The default value is adOpenForwardOnly. The CursorLocation, as well as the CursorType property, must be set before the Recordset is opened. Notice that you cant set the cursors location and type when
www.sybex.com
836
you create a Recordset with the Recordset.Open method. Use the Command objects Execute method instead. If the cursor resides on the client, its type is static, regardless of the value you set in the code. If a provider does not support the requested cursor type, the provider may return another cursor type. The various cursor types support different features, and you should use the Supports method to find out whether a Recordset supports a specific property. Here are the most important Recordset properties that are affected by the type of the Recordset: CursorType Forward-Only Keyset Dynamic Static Feature Supported none adBookmark, adHoldRecords, adMovePrevious, adResync adMovePrevious adBookmark, adHoldRecords, adMovePrevious, adResync
Notice that you cant set the cursors type and type when you create a Recordset with the Recordset.Open method. RDS (Remote Data Services) Recordsets are always static. DataMember Specifies the name of a Recordsets data member. This property applies to Recordsets whose DataSource property is a DataEnvironment object, which can have multiple members. If the DataSource is an ADO Data control, the DataMember property need not be set. The DataMember property requires a DataSource property; the opposite is not true. The DataMember property is a string with the name of the data member as it appears in the DataEnvironment object (the name of a table, SQL statement, or stored procedure). DataSource This property specifies the name of an object that will act as a data source for the Recordset, and its used to bind controls to database fields. It can be the name of an ADO Data control or the name of an Environment object. If the data source is an Environment object, you must set the DataMember property as well, even if the DataSource object contains a single member. EditMode This property returns the editing status of the current row, and its value is an EditModeEnum constant. Use this property in interactive applications that allow you to edit the fields of the current row to find out whether you are
www.sybex.com
ADO Objects
837
adding a new row or editing an existing one, and act accordingly. You cannot end an editing operation by setting this property. Call the Update or CancelUpdate method to end the operation. Fields Collection This collection is made up of Field objects, and each Field object contains information about a column of the Recordset. For a discussion of the members of a Field object, see the description of the Fields collection. Filter Property This property specifies a filter for a Recordset. The rows that do not match the filters specification are screened out. You can restore the original Recordset by setting its filter property to adFilterNone. This property can be set to FilterGroupEnum constant or a criterion that combines field names, values, and relational operators. In addition to the usual relational operators (<, <=, >, >=, = and <>), you can use the LIKE operator, as well as the logical operators AND and OR. To use literals in a Filter expression, use single quotes. Use the pound sign (#) to delimit dates. The filter constants allow you to identify the pending rows before a batch update or the conflicting rows after a batch update (see the list of FilterGroupEnum constants). Setting the Filter property to a zero-length string () has the same effect as using the adFilterNone constant. Whenever the Filter property is set, the first row the filtered Recordset becomes the current row. You can also create an array of bookmarks and use it to screen out undesired rows. This allows you to create groups that cant be declared with formal filter expressions. Index This property is used in conjunction with the Seek method; it returns the name of the index currently in effect or sets the current index. Its value is a string, with the name of the index. It indicates the name of the index currently in effect for a Recordset object. The Index property can always be set successfully if the Recordset is closed. When you set the index property, the current row may change, and any existing filter is released. LockType This property sets or returns the type of locks placed on the rows in a Recordset, and its value must be a LockTypeEnum constant. The default value is adLockReadOnly, which eliminates concurrency problems altogether by disabling the application to edit a row. This property must be set before you open the Recordset. The LockType property of a RDS Recordsets is adLockOptimisticBatch. MarshalOptions Indicates whether ADO should transmit all the rows back to the server during a batch update operation, or only the ones that were edited. The default value is adMarshalAll.
www.sybex.com
838
MaxRecords This property specifies the maximum number of records to be returned into a Recordset from a query. Use this property to limit the number of rows returned by the Recordset. This property is equivalent to including the TOP N clause in the SQL statement. PageCount This property indicates how many pages are contained in the Recordset object. The value of this property is set by the number of rows in the Recordset and the setting of the PageSize property. A page is a group of rows whose size equals the PageSize property setting. PageSize This property indicates how many records constitute one page in the Recordset. Use this property to determine how many records make up a logical page of data. Use the AbsolutePage, PageCount, and PageSize property to create pages output for display on a browser. RecordCount This property returns the number of rows in a Recordset. The property returns -1 when ADO cannot determine the number of records, or if the provider or cursor type does not support RecordCount. Only client-side Recordsets (which are static by definition) and keyset cursors return the correct number of rows. Sort This property allows you to sort the rows of a Recordset. Its value is one or more field names on which the Recordset is sorted. You can also specify whether the Recordset will be sorted in ascending or descending order. Multiple field names are separated by a comma. They are optionally followed by a space and the keyword ASC, which sorts the field in ascending order; or DESC, which sorts the field in descending order. By default, the field is sorted in ascending order. The sort operation is quite fast because the rows are not physically rearranged; theyre simply accessed in the specified order. If the Recordset resides on the client, a temporary index will be created for each field specified in the Sort property. To reset the rows to their original order and delete temporary indexes, set the Sort property to an empty string. Existing indexes will not be deleted. The field cannot be named ASC or DESC because those names conflict with the keywords ASC and DESC. Give a field with a conflicting name an alias by using the AS keyword in the query that returns the Recordset. Source Indicates the source for the data in a Recordset object (Command object, SQL statement, table name, or stored procedure). To set this property, assign a string value with the name of the Command object or the Command object itself. State This property indicates whether a Recordset object is open or not. If a Recordset is open, you cant call its Open method again to populate it with a different cursor. You must first close it and then open it with a new SQL statement or stored procedure.
www.sybex.com
ADO Objects
839
You can also use the same property with asynchronous operations to find out whether the Recordset is fetching rows or whether it has read the entire cursor. The State property applies to Connection objects (it indicates whether a connection has been established) and to Command objects (it indicates whether the command is still executing or whether it has completed its execution). The State property is read-only, and it returns an ObjectStateEnum constant. Because this property may return multiple constants, you must use the AND operator to find out a specific state. While a Recordset is being opened, the State property will return the constant adStateOpen + adStateExecuting. Status This property indicates the status of the current row after a batch update or other batch operation, and its value is a RecordStatusEnum constant. StayInSync This property applies to hierarchical Recordsets only, and indicates whether the reference to the underlying child records changes when the parent row position changes. The default value of the property is True.
Methods
AddNew [fieldList, values] This method creates a new row and appends it to the Recordset (provided that the Recordset is updateable). You can edit the fields and then commit the changes to the database with the Update method or by moving to another row. Alternatively, you can specify a list of field names and values to be inserted into the new row, similar to the INSERT SQL statement. If you use the second form of the method, be sure that the order of field names match the order of field values. Heres how to add a new row with the AddNew/Update methods:
RS.AddNew RS.Fields(0) = <value> RS.Fields(1) = <value> . . . RS.Update
Heres how to add a new row with a single statement:

RS.AddNew Array(field1, field2, ., fieldN), _ Array(value1, value2, , valueN)
When you use the second method of adding a new row to the Recordset, ADO submits the changes immediately to the database; theres no need to call the Update method. Cancel This method cancels the execution of a pending Open operation. If your application has called a query that takes long to execute, you may wish to
www.sybex.com
840
break its execution (or give users a chance to interrupt the execution of an Open method). CancelBatch [affectRecords] Call this method to cancel a pending batch update. The affectRecords optional argument determines which records will be affected, and it can be an AffectEnumType constant. If the attempt to cancel the pending updates fails because of a conflict with the underlying data (if, for example, a record has been deleted by another user), the provider returns warnings to the Errors collection but does not halt program execution. A runtime error occurs only if there are conflicts on all the requested records. Set the Filter property to adFilterConflictingRecords to isolate the rows that couldnt be updated due to a conflict. CancelUpdate This method cancels an AddNew operation, as well as any changes made to the current row. You call this method to restore the original field values of a row in data-editing applications. (Use a Cancel button on your VB Form to allow the user to cancel the current add or edit operation, and call the CancelUpdate method from within this buttons Click event handler.) If you call the CancelUpdate method after a call to the AddNew method, the record that was current before you called the AddNew call will become the current record again. Set RS2 = RS1.Clone (lockType) This method creates a copy of a Recordset object. The lockType argument specifies whether the clone is read-only or not, and it must be a LockTypeEnum constant. Clone Recordsets are used when you want to maintain two identical Recordsets (usually when you need two current rows at once). The Clone method is more efficient than creating and opening a new Recordset object with the same definition. Changes you make to one Recordset object are visible in all of its clones, regardless of cursor type. However, once you execute Requery on the original Recordset, the clones will no longer be synchronized to the original. You can only clone a Recordset object that supports bookmarks. Bookmarks are identical in the original and the cloned Recordset, so you can locate a row in any Recordset. Cloned Recordsets can be sorted differently, and this is a good reason to clone a Recordset. However, if you use a clone to populate a DataList control, VB will place the rows on the control in the same order as they are in the original Recordset, even if you have sorted the clone differently. Close This method closes an open Recordset (or Connection, Record, and Stream) object. Closing an object does not remove it from memory, but it frees the resource allocated to it by the system. You can change the objects properties and open it
www.sybex.com
ADO Objects
841
again later. To completely eliminate an object from memory, set the object variable to Nothing. When you close a Connection object, any active Recordset objects associated with the connection will also be closed. When you close a Recordset, Record, or Stream object, the system releases the associated data. One of the most common runtime errors is that the requested operation cant be performed on a closed object. You may have forgotten to open a connection for a Recordset or even the Recordset itself. See the discussion of the Open method for more information on opening and closing objects. CompareBookmarks (bookmark1, bookmark2) This method compares two bookmarks and returns an indication of their relative values. The value returned is a CompareEnum constant, which indicates the relative order of the two rows in the Recordset. Delete [affectRecords] This method deletes the current record or a group of records. The affectRecords optional argument determines which records will be affected, and it can be an AffectEnumType constant. After deleting the current record, the deleted record remains current until you move to a different record. At this point, the data-bound controls (if any) will display the deleted rows fields. If you attempt to access the value of these fields, however, an error will be generated. Once you move away from the deleted record, it is no longer accessible. If the attempt to delete records fails because of a conflict with the underlying data (for example, if a record has already been deleted by another user), ADO will set the Error object (the ADO Error object is different than the Err object of VB), but it will not set the Err object. As a consequence, it will not halt the execution of the application. You can set the Filter property to adFilterConflictingRecords to isolate the conflicting rows. Find criteria [, skipRows, searchDirection, start] The Find method searches a Recordset to locate the first row that matches the specified criteria. If no row matches the criteria, the Find method sets the EOF property to True (or the BOF property, if youre searching backward). The criteria argument is a string that contains a column name, a comparison operator, and a value to be used in the search. Notice that you cant combine multiple criteria with the logical operators (AND/OR). The second argument, skipRows, specifies an offset from the current row (or the start bookmark) where the search will begin. By default, the search starts on the current row. Most applications call the MoveFirst method before calling the Find method. The searchDirection argument specifies whether the search should begin on the current row or the next available row in the direction of the search, and its value can be a DirectionEnumType Constant. The last argument,
www.sybex.com
842
start, is the bookmark of the row that will be used as the starting position for the search. The criteria argument may contain relational operators (<, <=, >, >=, =, <>) as well as the LIKE operator. array = RS.GetRows ([rows, start, fields] ) The GetRows method retrieves multiple records of a Recordset object into an array. The method returns a Variant that evaluates to a two-dimensional array. The rows optional argument is a GetRowsOptionEnum constant that indicates the number of records to retrieve. The start optional argument is a string or variant value that evaluates to the bookmark of the record from which the GetRows operation should begin. You can also use a BookmarkEnum constant. The last argument, fields, is the name of a field (or an array of field names) that specify which columns will be retrieved. If you omit the fields argument, then all columns will be returned. To manipulate the array from within your code, keep in mind that the first subscript corresponds to the columns of the Recordset (fields), and the second index corresponds to the rows of the Recordset. The array is dimensioned automatically to fit the size of the Recordset. To specify which fields you want the GetRows method to return, you can pass either a single field name (or ordinal position) or an array of field names (or ordinal numbers) in the fields argument. Set Variant = RS.GetString ([stringFormat, numRows, columnDelimiter, rowDelimiter, nullExpr]) This method returns the Recordset as a string. The stringFormat argument specifies how the Recordset will be converted to a string, and its value is a StringFormat constant. The rowDelimiter, columnDelimiter, and nullExpr parameters are used only when the stringFormat is adClipString. The NumRows is also optional, and you can use it to specify the number of rows to be converted. If you omit this argument, all the rows in the Recordset are converted. The last argument is the delimiter that will be used between columns. The default delimiter is the TAB character. The nullExpr is a value to be used in the place of Null fields. Move numRecords [, start] The Move method moves numRecords rows ahead of the current row, or moves numRecords ahead of the row number specified by the start argument. If the numRecords argument is negative, the Move method moves toward the beginning of the Recordset. If your code attempts to move to a row before the first record, ADO sets the current record to the position before the first record in the Recordset and sets the BOF property to True. An attempt to move backward when the BOF property is already True generates an error. Likewise, with an attempt to move to a row after the last row, ADO sets the current record to the position after the last record in the Record-
www.sybex.com
ADO Objects
843
set and sets the EOF property to True. Calling the Move method from an empty Recordset object generates an error. This is the only navigational method supported by forward-only Recordsets. You can specify a negative value for the numRecords argument to move backward, provided that the destination row is in the cache. Use a large value for the CacheSize property to support full scrolling with a forward-only cursor. MoveFirst, MoveLast, MoveNext, and MovePrevious These are the Recordset object navigational methods: they move to the first, last, next, or previous row in a Recordset, respectively. Forward-only cursors support the MoveFirst and MoveNext methods only. Set RS2 = RS1.NextRecordset This method returns the next Recordset. Some SQL statements may return multiple Recordsets (a T-SQL batch with multiple SELECT statements, for example). After you have iterated through the rows of the first Recordset, you can call the NextRecordset method to move to the next Recordset. At any given time, you can see only one Recordset. Multiple Recordsets are generated by compound statements, which must be executed with the Execute method of the Command object or the Open method of the Recordset object. The NextRecordset method can be called many times. As long as there are Recordsets, the NextRecordset method will return a new Recordset. When it runs out of Recordsets, it will return an empty Recordset. To test empty Recordsets, examine the EOF and BOF properties. If theyre both True, then the Recordset is empty. If one of statements in the compound command does not return a Recordset, the NextRecordset method will be closed. You can examine its State property to test for this case. When you call the NextRecordset method, ADO executes only the next command in the statement. If you explicitly close the Recordset object before stepping through the entire command statement, ADO never executes the remaining commands. Open [source, activeConnection, cursorType, lockType, options] The Open method opens a Recordset by executing a cursor-returning command against the database or by opening a table. The source argument is a Command object, an SQL statement, a tables name, or a stored procedures name. It can also be a URL, the name of a file where a persisted Recordset has been stored (most likely with the Save method), or a Stream object. The ActiveConnection is a Connection object. The cursorType argument (a CursorTypeEnumType constant) specifies the type of the cursor, and the lockType argument (a LockTypeEnum constant) specifies the cursors locking mechanism. The default cursor is forward-only and read-only. The options argument indicates how the source argument should be interpreted (i.e., whether its something different from a Command object, or whether the
www.sybex.com
844
Recordset should be read from a file, where it was previously stored with the Save method). If the source argument is not a Command object, you can use the options argument to specify the type of the source argument. This will optimize performance because ADO will not have to figure on its own the type of command it must execute against the database. If the data source returns no records, the data store returns an empty Recordset by setting both its BOF and EOF properties to True. If you want to create a custom Recordset, you must first set its Fields (by populating the Fields collection with Field objects) and then call the Open with no arguments. Requery [options] This method updates the data in a Recordset object by executing the query on which the Recordset is based. The options argument is an ExecuteOptionEnum constant that affects how the operation is performed. The Requery method is equivalent to calling the Close and then the Open method of the Recordset. The number of rows in the Recordset may change after calling the Requery method. Resync [affectRecords, resyncValues] This method synchronizes the data in the Recordset with the underlying database. The affectRecords argument is an AffectEnumType constant that specifies which records will be updated. The resyncValues argument is a ResuncEnum type that specifies whether the underlying values will be overwritten or not. The Resync method does not execute the query on which the Recordset was based. As a result, the Resync method doesnt see any new rows inserted since the Recordset was created. If one or more of the underlying rows were deleted, ADO will return warnings in the Errors collection. You can set the Filter property to adFilterConflictingRecords to isolate the conflicting rows. Save destination [, persistFormat] This method saves (persists) the Recordset in a file or Stream object. The destination argument is the path name of the file where the Recordset will be saved or a reference to a Stream object. The persistFormat argument specifies the format in which the Recordset will be saved, and its value can be a PersistFormatEnum constant. If a filter is in effect, only the rows accessible under the filter are saved. If the Recordset is hierarchical, then the current child Recordset and its children are saved, including the parent Recordset. If the Save method of a child Recordset is called, the child and all its children are saved, but the parent is not. You must specify a destination Stream only the first time you call the Save method. If you call the Save method with a different destination, then both destinations will remain open.
www.sybex.com
ADO Objects
845
Seek keyvalues [, seekOption] The Seek method searches the index of a Recordset to quickly locate the row that matches the specified values, and changes the current row position to that row. The Seek method works with server-side cursors only. The keyValues argument is an array of values that represent an index consisting of one or more columns, and the array contains a value to compare against each corresponding column. The second argument specifies the comparison to be executed between the index columns and the corresponding keyValues. If the Seek method does not find the desired row, no error occurs, and the row is positioned at EOF. Supports(cursorOption) This method determines whether a specified Recordset object supports a particular cursor-related feature, and it returns True if the feature is supported; False otherwise. The cursorOption argument is a CursorOptionEnum constant. Usually, you know whether your Connection object supports a feature at design time. If you allow users to change the cursor type from within your applications code, you should make sure that the features you use in your code are supported by the cursor by calling the Supports method with the appropriate argument. Update [fields, values] This method commits any changes made to the current row of a Recordset in the underlying tables. To commit all the fields, call the Update method without arguments. If you want to change the values of selected fields, pass the names of the fields as an array and their new values also as an array. The order of the values must match the order of the fields. You use the Update method to save a new row after calling the AddNew method or after the user makes changes on data-bound controls on a Form. If you move to another row with one of the Move methods, or if you close the Recordset with the Close method, any changes in the current row are committed to the database automatically. To update selected fields, call the Update method, as follows:
RS.Update Array(Phone, FAX), Array(555-1234, 555-2233)
Or
RS.Fields(Phone) = 555-1234 RS.Fields(FAX) = 555-2233 RS.Update
UpdateBatch [affectRecords] This method writes all pending updates to disk in batch mode. The optional argument affectRecords determines which rows of the Recordset will be transmitted to the database server, and its value must be
www.sybex.com
846
an adAffectEnumType constant. Batch updates are possible with keyset or static cursors only. If the attempt to transmit changes fails for any or all records because of a conflict with the underlying data (for example, if a record has already been deleted by another user), the provider returns warnings to the Errors collection, and a runtime error occurs. Set the Filter property to adFilterAffectedRecords to screen the conflicting rows.
Events
The Recordset object fires several events. To program a Recordset objects events, you must declare it with the WithEvents keyword:
Dim WithEvents RS As ADODB.Recordset
The events fired by the Recordset object are the following: Events EndOfRecordset FetchComplete FetchProgress Indication Youve reached the end of the Recordset (youre past the last row in the Recordset). All the rows have been fetched. This event is fired periodically during an asynchronous operation and indicates the percentage of rows fetched so far. The value of one or more fields has been changed. The current row has changed. One or more fields in the current row in the local Recordset has changed. The Recordset has changed, as a result of a call to a Requery, Resync, Close, or Open method. This event is fired before an operation will change the value of one or more fields. This event is fired before an operation will update a row. This event is fired before an operation will update the Recordset. This event is fired when the current row in the Recordset will change.
www.sybex.com
FieldChangeComplete MoveComplete RecordChangeComplete RecordsetChangeComplete WillChangeField WillChangeRecord WillChangeRecordset WillMove
ADO Objects
847
Record Object
The Record object represents a row in a Recordset, or a file or folder in a file system. If the Record represents a row in a Recordset object, you can access the current rows fields through the Fields collection of the Record object. The Record object also represents an alternative way to navigate hierarchically organized data. A folder may be represented with a Record, which has subordinate Records that represent its files and folders. Folders that contain subfolders are mapped to Record objects that contain subordinate Record objects as well. A folder is uniquely identified by an absolute URL, so you can open a Record object by specifying an absolute URL. A Connection object is implicitly created and set to the Record object when the Record is opened with an absolute URL (see the description of the Open method for more details).
Properties
ActiveConnection This property identifies the Connection object to which the specified Record belongs. Fields Collection Each Record object has a Fields collection that contains information about the Records fields. See the discussion of the Fields Collection for more information. Mode This property indicates the permissions for modifying data in a Record object, and its value is a ConnectModeEnum constant. ParentURL The ParentURL property returns an absolute URL string that points to the parent Record of the current Record object. This property is Null if there is no parent for the current object (for example, if the Record object represents the root of a directory). It is also Null if the Record object represents an entity that cannot be specified with a URL (for example, a row of a Recordset derived from a database). RecordType This property indicates the type of a Record, and it returns a RecordTypeEnum constant. Source This property indicates the entity represented by a Record object. The Source property returns the Source argument of the Record objects Open method. It can be string with an absolute or relative URL, or a reference to an already open Recordset object. State This property indicates whether a Record object is opened or closed, and it returns an ObjectStateEnum constant.
www.sybex.com
848
Methods
Cancel This method cancels an asynchronous operation on a Record object. The asynchronous operation can be a call to the following methods: CopyRecord, DeleteRecord, MoveRecord, or Open. Close Use the Close method to close a Record object. All related data are released, and you must reopen the Record with Open method again, if you need it. CopyRecord source, destination [, userName, password, options, async ] The CopyRecord method copies a file or directory, and its contents, to another location. source is a URL that identifies the file or directory to be copied. If the source argument is omitted (or if its set to an empty string), the method will copy the file or directory represented by the Record object on which the method is applied. The destination argument is the URL of the destination (where the source will be copied), and it must be different from the source argument. The userName and password arguments contain the user ID and password, which may be needed to authorize the users access to the destination. The options argument is a CopyRecordOptionsEnum constant that specifies the behavior of this method. The last argument, async, determines whether the operation should take place asynchronously (if True) or synchronously (if False). All subdirectories in the source are copied recursively, unless the adCopyNonRecursive option is specified. In a recursive operation, destination must not be a subdirectory of source. DeleteRecord source [, async] The DeleteRecord method deletes a file or directory, and all its subdirectories. The source argument specifies a URL that identifies the object to be deleted (a file or directory). If the source argument is omitted, then the DeleteRecord method will remove the file or directory represented by the Record on which the method is applied. The async argument specifies whether the operation will take place synchronously (if False) or asynchronously (if True). Set Recordset = Record.GetChildren This method returns a Recordset with rows that represent the files and subfolders in the folder represented by the Record object on which the GetChildren method is called. MoveRecord (source, destination [, userName, password, options, async]) This method moves a file, or a directory and its contents, to another location. The source argument is a URL that identifies the Record object to be moved. This argument is usually omitted, and the operation is applied on the Record object on which the method is applied. The destination argument is the URL of the location where the Record will be moved. The source and destination arguments must be different, or else a runtime error is generated. The username and password arguments are used to verify the users rights.
www.sybex.com
ADO Objects
849
The options argument is a MoveRecordOptionsEnum constant, which specifies the methods behavior. If the destination exists already, you can overwrite it by setting the adMoveOverWrite option. You can specify multiple options by combining the individual options with the OR operator. The last argument, async, determines whether the operation will be executed asynchronously (if True) or synchronously (if False). Open [source, activeConnection, mode, createOptions, options, userName, password] The Open method opens a Record object. The source argument is the URL of the entity represented by the Record object. For the simplest type of Record, which represents a row, Record can be a row of an open Recordset object. For Recordset-related Records, the activeConnection argument is a connection string or a valid Connection object. If the Record is associated to a file system, then source can be a relative or an absolute URL. In the second case, it specifies the file or folder over which subsequent operations will apply. The mode argument is a ConnectMode Enum constant that specifies the access mode for the Record object that will be opened. The createOptions argument is a RecordCreateOptionsEnum constant that specifies whether an existing file or folder should be opened, or whether a new one should be created. The options argument is a RecordOpenOptionsEnum constant, and it specifies options for opening the Record. The last two arguments are used to validate the users rights to the files or folders that will be accessed through the Record object. The following statements open a Record from the URL of an existing folder.
Dim Record As New ADODB.Record Record.Open http://127.0.0.1/PublicDocs/
A relative URL is the URL of a document in the context of the Connection object:
Dim aConnection As New ADODB.Connection Dim Record As New ADODB.Record aConnection.Open http://127.0.0.1/PiblicDocs/ Record.Open Resume.doc, aConnection
Update This method commits the addition and deletion of fields to a Record objects Fields collection. Deleted fields are hidden immediately, but theyre actually removed from the Fields collection when the Update method is called. You can restore deleted fields by calling the Fields.Append method with the same field name or setting a value to the deleted field before calling the Update method.
www.sybex.com
850
Stream Object
A Stream object represents a stream of binary data or text. ADO can access semistructured data stores, such as a file system or an e-mail system. A Stream object consists of Records that correspond to contents of a file or the items in an e-mail system. A Stream object can be obtained in these ways: From a URL pointing to an object (typically a file) containing binary or text data. This object can be a simple document, in which case a Record object represents a document or a folder. Accessing files and folders through a Stream object is similar to using the FileSystemObject (this is an object of the Windows Scripting Host). From a Record object. After you have opened a Record object, you can obtain its default stream. By creating a Stream object with the appropriate declaration. This Stream can be used to store data, which you can manipulate from within your code.
You can use the Stream objects methods and properties to access its Records (the subfolder of a folder, the contents of a file, the messages stored in an e-mail system, and so on). You can also save information to a folder or file by using the Stream object. The Stream object allows you to access non-traditional data stores (non-relational databases) through the ADO object. This capacity of ADO doesnt apply to databases and their programming, and its not discussed in this book.
Properties
Charset This property specifies the character set into which the contents of a text Stream should be translated. The default value is Unicode. Other values are the character set strings use in the HTML <META> tag (Windows-1252, etc.). For a list of the character sets available on your system, see the following branch of the Registry:
HKEY_CLASSES_ROOT\MIME\Database\Charset in the Windows Registry.
EOS The EOS (End Of Stream) property is the equivalent of the EOF property for Stream objects. It returns True if the current position is the end of the Stream. Unlike the EOF property, the EOS property can be set. When you set the EOS property to True, you specify that the current position becomes the end of the Stream. Any additional characters or bytes in the Stream are discarded. LineSeparator This property specifies the character to be used as the line separator in a text stream, and its value must be a LineSeparatorEnum constant. The default value is adCRLF.
www.sybex.com
ADO Objects
851
The LineSeparator must be used with text streams only; its ignored if specified with a binary stream. Mode This property indicates the permissions for modifying data in a Stream object. The same property applies to Connection objects and Record objects as well. Position This property identifies the current position in a Stream object. It sets a long integer value, which is the offset (in characters or bytes) of the current position from the beginning of the Stream. The value zero corresponds to the first byte in the Stream. Size This property returns the size of a Stream object in number of bytes. If the size of the Stream object is not known, the Size property will return the value 1, similar to the RecordCount property. Type The Type property identifies the type of the data stored in a Stream object, and it can be a StreamTypeEnum constant. The default value is adTypeText. This property can be set only while youre on the first byte of the Stream. At any other position, the Type property is read-only.
Methods
Cancel Call this method to cancel an asynchronous Open operation. A runtime error will be generated if the operation youre attempting to cancel is not asynchronous. Close This method closes an open Stream object. Closing a Stream object does not remove it from memory. To remove the object from memory and release its resources, set it to Nothing. The Close method releases the data associated with the Stream object. CopyTo destStream [, numChars] The CopyTo method copies numChars characters or bytes from one Stream object to another. The destStream argument is a reference to an open Stream object, where the characters or bytes will be copied into. If you omit the numChars argument, the method will copy all the characters or bytes from the current location to the end of the Stream. Flush This method flushes the Stream to the object (a file, for example) to which the Stream object is associated. This method need not be called frequently because the Stream object flushes its buffer as frequently as possible in the background. When a Stream object is closed, its contents are automatically flushed. LoadFromFile filename This method loads the contents of an existing file into a Stream. The Stream object must be already open before its LoadFromFile method can be called. Any existing bytes in the Stream are overwritten by the contents of the file. Any existing bytes after the EOS created by LoadFromFile are truncated.
www.sybex.com
852
Open [source, mode, openOptions, userName, password] The Open method opens a Stream object. The source argument specifies the source of the Streams data. It may be an absolute URL or a string pointing to a structured data source, such as a file system of an e-mail storage. Alternately, source may contain a reference to an already open Record object, which opens the default stream associated with the Record. The mode argument specified the access mode for the Stream. The openOptions argument is a StreamOpenOptionsEnum constant, and specifies whether the Streams data will come from a URL or a file. The userName and password arguments contain information required to validate access to the Stream object. variant = Stream.Read (numBytes) Reads a numBytes bytes from a Stream object. The data read from the Stream are stored in a variant. The numBytes argument can be a StreamReadEnum constant and its default value is adReadAll. String = Stream.ReadText (numChars) This method reads numChars characters from a text Stream object. The text read from the Stream is stored in a string variable. The numChars argument can be a StreamReadEnum constant, and its default value is adReadAll. SaveToFile filename [, saveOptions] This method saves the binary contents of a Stream to a file. The filename argument is the name of the file to which the contents of the Stream will be saved. The saveOptions argument is a SaveOptionsEnum constant that specifies whether a new file should be created by SaveToFile if it does not already exist. The default value is adSaveCreateNotExists. SetEOS This method sets the position that is the end of the stream. It updates the value of the EOS property by making the current Position the end of the stream. Any bytes or characters following the current position are truncated. SkipLine This method skips one entire line when reading a text stream. The SkipLine method is used with text streams only. Write buffer This method writes binary data to a Stream object. The buffer argument contains an array of bytes that will be written to the Stream. The current Position is set to the byte following the written data. The Write method does not truncate the rest of the data in a stream. If you want to truncate these bytes, call SetEOS. WriteText data [, options] This method writes a specified text string to a Stream object. The data argument contains the text to be written to the Stream. The options argument is a StreamWriteOptionsEnum constant, and it specifies whether a line separator must be written to the end of the string. The WriteText method does not truncate the rest of the data in a stream. If you want to truncate these characters, call SetEOS. If you write past the current EOS position, the Size of the Stream will be increased to contain any new characters, and EOS will move to the new last byte in the Stream.
www.sybex.com
ADO Objects
853
Field Object
A Field object represents a column of a table in the database. Each table exposes the Fields collection, which contains a Field object for each column in the table. Use the items of the Fields collection to find out information about the tables columns. Most of the members of the Field object are the same as the properties of the Parameter object.
Properties
ActualSize This property returns the actual length of the data stored in a field. Use this property with variable length fields to find out the length of the data stored in the field. For fixed-length fields, the ActualSize property is the same as the DefinedSize property. Attributes This property indicates one or more characteristics of a Field object, and its value is a FieldAttributeEnum constant. To find out whether an attribute is set, AND the Attributes property value with the desired constant:
If (Field.Attribute And adFldLong) = adFldLong Then {can call the AppendChunk method on this field} End If
DataFormat This property identifies the format in which the data should be displayed. Use this property with Visual Basics DataFormat object, which allows you to identify the format using its properties. DefinedSize This property indicates the defined size of a Field object (the size that appears in the tables definition). You can set a size for only varchar and binary fields. Name This property returns or sets the fields name. You must set this property in a custom Recordet and read it in a Recordset, based on a query. NumericScale This property indicates the scale of numeric field (the number of digits to the right of the decimal point). OriginalValue Property This is the value of a Field the moment it was read from the database; it doesnt change when you edit the field. Precision This property specified the precision of a Field that holds a numeric value (the same property applies to the Parameter object as well). A numeric values precision is the maximum number of digits used to represent the fields value. Type This is the fields (columns) data type, and it can a DataTypeEnum constant. UnderlyingValue This is the value of a field in the database. If the user has edited the field, then the UnderlyingValue is different from the Value property. If
www.sybex.com
854
another user has edited the field in the database, then the Underlying value is different from the Value and OriginalValue properties. Reading a fields UnderlyingValue property is similar to calling the Resync method for a specific field. The UnderlyingValue and OriginalValue properties are used to resolve conflicts in batch updates. Value Property This is the current value of a Field object. This value is different from the UnderlyingValue property if the field has been edited since it was read on the client. The Value is the default property of the Field object and you can omit its name. The following expressions are equivalent:
RS.Fields(Name).Value RS.Fields(Name)
Because the Fields property is the default property of the Recordset object, the previous expressions are also equivalent to the following one:
RS(Name)
Methods
AppendChunk data The AppendChunk method appends data to a large text or binary field. The data argument is a variant holding the data to be appended to the Field object. The first time you call the AppendChunk method, it overwrites any existing data. Subsequent calls to this method append the data to the ones already written to the field. If you switch to another field, the AppendChunk method assumes that youre done appending data. The next time you call the AppendChunk method on the same field, it will overwrite its data. Variable = GetChunk(size) This method returns a large text of binary field, or part of it. The size argument is the number of characters or bytes you want to retrieve. In situations where system memory is limited, you can use the GetChunk method to manipulate long values in portions, rather than in their entirety. The first call to the GetChunk method retrieves data from the beginning of the field. Each successive call of the GetChunk method retrieves data. starting from where the previous call left off.
Fields Collection Methods

Append fieldname, type [, definedSize, Attributes] This method appends a Field object to the Fields collection. fieldname is the fields name and type is its data type (a DataTypeEnum constant). The optional argument definedSize is used with character and binary fields to denote the maximum length of data that can be stored in the field. attributes is another optional argument that specifies additional field attributes, and its a FieldAttributeEnum constant.
www.sybex.com
ADO Objects
855
Delete field This method deletes a Field object from the Fields collection. The field argument is the name of the field object to be deleted and it cant be the ordinal position of the object in the Fields collection. This method should be used with custom Recordsets. You cant manipulate the structure of a Table by adding or deleting fields in the Fields collection. Refresh The Refresh method reads the field definitions in a Field collection directly from the database.
Parameter Object
A Parameter object represents a parameter or argument associated with a Command object, based on a parameterized query or stored procedure. To call a stored procedure with input/output parameters, you must create a Parameter object for each of the stored procedures parameters, and then append it to the Command objects Parameters collection. After you have populated the Parameters collection, you can call the stored procedure with the Command objects Execute method. The members of the Parameter object described in the following section allow you to manipulate the parameters of the stored procedures, set the values of the input parameters, and read the values of the output parameters.
Properties
Attributes This property sets or returns one or more characteristics of a Parameter object. It is a ParameterAttributesEnum constant, or a combination of two or more constants. To assign a new attribute, you must OR the appropriate constant with the existing attributes:
param.Attributes = param.Attributes OR adParamNullable
To find out whether an attribute is set, use a statement like the following:
If (param.Attributes And adParamNullable) Then . . .
Direction The Direction property represents an input parameter, an output parameter, or both. Its value is a ParameterDirectionEnum constant. Name This is the name of the Parameter object and it is used to identify the Parameter object in the Parameters collection. The Parameter objects Name property need not be the same as the name of the parameter in the stored procedure. NumericScale This property determines the numeric scale (the number of digits to the right of the decimal point) of the numeric value stored in the Parameter object. Precision This property specifies the precision of a Parameter that holds a numeric value (the same property applies to the Field object as well). A numeric
www.sybex.com
856
values precision is the maximum number of digits used to represent the value values. Size This property indicates the maximum size, in bytes or characters, of a Parameter object (or a Field object). This property must be used with variable length data types (varchar and binary types). Fixed-length data types have a Size property, but setting it doesnt affect the parameters actual size. Type This property indicates the data type of a Parameter, Field, or Property object and its a DataEnumType constant. Value This property sets or returns the Parameter objects value. You set this value for input parameters before calling a stored procedure through the Command object, and read this value for output parameters to retrieve the values returned by the stored procedure.
Methods
Set parameter = _ Command.CreateParameter ([name, type, direction, size, value]) The CreateParameter method creates a new Parameter object with the specified properties. The new Parameter object must be appended to a Command objects Parameters collection with the Append method. The name argument is the parameters name, type is the parameters data type, and size is the parameters size in bytes or characters (the last argument applies to variable length fields only). The direction argument is equivalent to the parameters Direction property and specifies whether its an input or output parameter. The last argument, value, is the parameters value. As you can see from the syntax of the method, all arguments are optional. You can create a Parameter object and then set all its properties as follows:
Set oParam = CMD.CreateParameter oParam.Name = parameter1 oParam.Type = adTypeInteger oParam.Direction = adParameterDirectionInput oParam.Value = 1001
Parameters Collection
The Parameters collection supports three methods for adding and removing Parameter objects to the collection. AppendChunk data This method appends data to a large text, or appends binary data to a Parameter object. The syntax of the method is the same as with the AppendChunk method of the Field object.
www.sybex.com
ADO Objects
857
Delete param_name This method deletes an object from the Parameters collection. The param_name argument is the name of the object you want to remove from the Parameters collection. You can also specify the parameters order in the collection. Append object This method appends a Parameter object to a Parameter collection, or appends a Field object to a Fields collection. The object variable represents the object to be appended. To append the oParam Parameter object to the Parameters collection of the CMD Command object, use the following statement:
CMD.Parameters.Addpend oParam
Error Object
The Error object holds information about an error returned by the OLE DB provider. As such it contains only data-access errors and provides additional information about an error to your application. The same condition may result in multiple errors, so you must scan the Errors collection of the Connection object to read them all.
Properties
Description This property is a string with a short description of the error. This property is used to display additional information to the user when you cant handle the error from within your code. NativeError This is an integer value that indicates the provider-specific error code for the current Error object. Number This property is an error that uniquely identifies an error. You use this property to find out which error occurred and handle it from within your code. Source This property is the name of the object (or application) that generated the error. This property is used in applications that make use of many different objects. For an ADO-generated error, for example, this property will be ADODB .objName, where objName is the name of the object that caused the error (Recordset, Command, and so on). SQLState This property indicates the SQL state for an Error object. This is a five-character string returned by the provider, and identifies an error that occurred during the processing of an SQL statement. The error code S1109 means invalid cursor location, and the error code 07001 means wrong number of parameters. For a complete list of SQL Servers SQLState codes, consult SQL Servers Books Online.
Methods
The Error object does not support any methods.
www.sybex.com
858
ADO Enumerated Types

AffectEnum Constant adAffectCurrent adAffectGroup This type specifies which records are affected by an operation. Value 1 2 Description Affects only the current record Affects only records that satisfy the current Filter property setting. You must set the Filter property to one of the valid predefined constants to use this option. Affects all records in the Recordset Affects records in all chapters of the Recordset
adAffectAll adAffectAllChapters
3 4
BookmarkEnum tion should begin. Constant
This type specifies a bookmark indicating where the opera-
Value 0 1 2
Description Starts at the current record. Starts at the first record. Starts at the last record.
adBookmarkCurrent adBookmarkFirst adBookmarkLast
CEResyncEnum This type specifies whether the UpdateBatch method is followed by an implicit Resync method operation; if so, it specifies the scope of that operation. Constant adResyncNone Value 0 Description Does not invoke Resync Default; invokes Resync for all successfully inserted rows, including the values of columns that are automatically incremented or generated by the data source, such as Microsoft Jet AutoNumber fields Invokes Resync for all rows in which the update or delete operation failed because of a concurrency conflict Invokes Resync for all successfully updated rows
www.sybex.com
adResyncAutoIncrement 1
adResyncConflicts
adResyncUpdates
859
adResyncInserts
Invokes Resync for all successfully inserted rows. Values of their primary key columns will be resynchronized except for primary key columns that are automatically incremented by the data source, such as Microsoft SQL Server Identity columns. To resynchronize inserted rows with automatically incremented columns, use adResyncInserts + adResyncAutoIncrementing together. Invokes Resync for each row with pending changes
adResyncAll
15
CommandTypeEnum be interpreted. Constant
This type specifies how a command argument should
Value 1 8
Description Does not specify the command type argument Default; indicates that the type of command in the CommandText property is not known Evaluates CommandText as a textual definition of a command or stored procedure call Evaluates CommandText as a table name whose columns are all returned by an internally generated SQL query Evaluates CommandText as a stored procedure name Evaluates CommandText as the file name of a persisted Recordset Evaluates CommandText as a table name whose columns are all returned Evaluates CommandText as a URL (Connection objects only; do not use with Command objects.)
adCmdUnspecified adCmdUnknown
adCmdText
adCmdTable
adCmdStoredProc adCmdFile adCmdTableDirect adCmdURLBind
4 256 512 1024
www.sybex.com
860
CompareEnum This type specifies the relative position of two records represented by their bookmarks. Constant adCompareLessThan adCompareEqual adCompareGreaterThan adCompareNotEqual adCompareNotComparable Value 0 1 2 3 4 Indication The first bookmark is before the second. The bookmarks are equal. The first bookmark is after the second. The bookmarks are not equal and not ordered. The bookmarks cannot be compared.
ConnectModeEnum This type specifies the available permissions for modifying data in a Connection, opening a Record, or specifying values for the Mode property of the Record and Stream objects. Constant adModeUnknown Value 0 Description Default; indicates that the permissions have not yet been set or cannot be determined Indicates read-only permissions Indicates write-only permissions Indicates read/write permissions Prevents others from opening a connection with read permissions Prevents others from opening a connection with write permissions. Prevents others from opening a connection Allows others to open a connection with any permissions. Neither read nor write access can be denied to others.
adModeRead adModeWrite adModeReadWrite adModeShareDenyRead adModeShareDenyWrite adModeShareExclusive adModeShareDenyNone
1 2 3 4 8 12 16
www.sybex.com
861
adModeRecursive
32
Uses in conjunction with the other *ShareDeny* values (adModeShareDenyNone, adModeShareDenyWrite, or adModeShareDenyRead) to propagate sharing restrictions to all subrecords of the current Record. It has no affect if the Record does not have any children. A runtime error is generated if it is used with adModeShareDenyNone.
ConnectOptionEnum This type specifies whether the Open method of a Connection object should return after (synchronously) or before (asynchronously) the connection is established. Constant adConnectUnspecified adAsyncConnect Value 1 16 Description Default; opens the connection synchronously Opens the connection asynchronously. The ConnectComplete event may be used to determine when the connection is available.
ConnectPromptEnum This type specifies whether a dialog box should be displayed to prompt for missing parameters when opening a connection to an ODBC data source. Constant adPromptAlways adPromptComplete adPromptCompleteRequired Value 1 2 3 Description Always prompts Prompts if more information is required Prompts if more information is required but optional parameters are not allowed Never prompts
adPromptNever
www.sybex.com
862
CopyRecordOptionsEnum Record method. Constant adCopyOverWrite
This type specifies the behavior of the Copy-
Value 1
Description Overwrites the file or directory if the Destination points to an existing file or directory Copies the current directory, but none of its subdirectories, to the destination. The copy operation is not recursive. Indicates that the Source provider attempts to simulate the copy using download and upload operations if this method fails because Destination is on a different server or is serviced by a different provider than Source. Note that differing provider capabilities may hamper performance or lose data.
adCopyNonRecursive
adCopyAllowDataLoss
CursorLocationEnum Constant adUseNone
This type specifies the location of the cursor engine. Value 1 Description Does not use cursor services. (This constant is obsolete and appears solely for the sake of backward compatibility.) Uses client-side cursors supplied by a local cursor library. Local cursor services often will allow many features that driver-supplied cursors may not, so using this setting may provide an advantage with respect to features that will be enabled. For backward compatibility, the synonym adUseClientBatch is also supported. Default; uses data-provider or driver-supplied cursors. These cursors are sometimes very flexible and allow for additional sensitivity to changes others make to the data source. However, some features of the Microsoft Client Cursor Provider (such as disassociated Recordset objects) cannot be simulated with server-side cursors, and these features will be unavailable with this setting.
adUseClient
adUseServer
www.sybex.com
863
CursorOptionEnum This type specifies what functionality the Supports method should test for. Constant adAddNew adApproxPosition adBookmark adDelete adFind adHoldRecords Value 0x1000400 0x4000 0x2000 0x1000800 0x80000 0x100 Description Uses the AddNew method to add new records Reads and sets the AbsolutePosition and AbsolutePage properties Uses the Bookmark property to gain access to specific records Uses the Delete method to delete records Uses the Find method to locate a row in a Recordset Retrieves more records or changes the next retrieve position without committing all pending changes Uses the Index property to name an index Uses the MoveFirst and MovePrevious methods, and the Move or GetRows methods to move the current record position backward without requiring bookmarks Indicates that the underlying data provider supports notifications (which determine whether Recordset events are supported) Updates the cursor with the data that is visible in the underlying database, using the Resync method Uses the Seek method to locate a row in a Recordset Uses the Update method to modify existing data Uses batch updating (UpdateBatch and CancelBatch methods) to transmit groups of changes to the provider
www.sybex.com
adIndex adMovePrevious
0x100000 0x200
adNotify
0x40000
adResync
0x20000
adSeek adUpdate adUpdateBatch
0x200000 0x1008000 0x10000
864
CursorTypeEnum object. Constant
This type specifies the type of cursor used in a Recordset
Value 1 0
Description Does not specify the type of cursor Default; uses a forward-only cursor. Identical to a static cursor, except that you can only scroll forward through records. This improves performance in situations when you need to make only a single pass through a Recordset. Uses a keyset cursor. Similar to a dynamic cursor, except that you cant see records that other users add (although records that other users delete are inaccessible from your Recordset). Data changes by other users are still visible. Uses a dynamic cursor. Additions, changes, and deletions by other users are visible. All types of movement through the Recordset are allowed except for bookmarks, if the provider doesnt support them. Uses a static cursor. A static copy of a set of records that you can use to find data or generate reports. Additions, changes, or deletions by other users are not visible.
adOpenUnspecified adOpenForwardOnly
adOpenKeyset
adOpenDynamic
adOpenStatic
DataTypeEnum Property. Constant adBigInt adBinary adBoolean adBSTR
This type specifies the data type of a Field, Parameter, or
Value 20 128 11 8
Description Indicates an eight-byte signed integer Indicates a binary value Indicates a Boolean value Indicates a null-terminated character string (Unicode)
www.sybex.com
865
Constant adChapter adChar adCurrency
Value 136 129 6
Description Indicates a four-byte chapter value used to identify rows in a child rowset Indicates a String value Indicates a currency value. Currency is a fixed-point number with four digits to the right of the decimal point. It is stored in an eight-byte signed integer scaled by 10,000. Indicates a date value. A date is stored as a Double, the whole part of which is the number of days since December 30, 1899, and the fractional part of which is the fraction of a day. Indicates a date value (yyyymmdd) Indicates a file-time value Indicates a time value (hhmmss) Indicates a date-time stamp (yyyymmddhhmmss, plus a fraction in billionths) Indicates an exact numeric value with a fixed precision and scale Indicates a double-precision floatingpoint value Specifies no value Indicates a 32-bit error code Indicates a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 Indicates a globally unique identifier Indicates a pointer to an IDispatch interface on an OLE object. Note: This data type is currently not supported by ADO. Usage may cause unpredictable results.
adDate
adDBDate adDBFileTime adDBTime adDBTimeStamp
133 137 134 135
adDecimal adDouble adEmpty adError adFileTime
14 5 0 10 64
adGUID adIDispatch
72 9
www.sybex.com
866
Constant adInteger adIUnknown
Value 3 13
Description Indicates a four-byte signed integer Indicates a pointer to an IUnknown interface on an OLE object. Note: This data type is currently not supported by ADO. Usage may cause unpredictable results. Indicates a long binary value (Parameter object only) Indicates a long string value (Parameter object only) Indicates a long null-terminated string value (Parameter object only) Indicates an exact numeric value with a fixed precision and scale Indicates an Automation Indicates a single-precision floatingpoint value Indicates a two-byte signed integer Indicates a one-byte signed integer Indicates an eight-byte unsigned integer Indicates a four-byte unsigned integer Indicates a two-byte unsigned integer Indicates a one-byte unsigned integer Indicates a user-defined variable Indicates a binary value (Parameter object only) Indicates a string value (Parameter object only) Indicates an Automation Variant Indicates a numeric value (Parameter object only)
adLongVarBinary adLongVarChar adLongVarWChar adNumeric adPropVariant adSingle adSmallInt adTinyInt adUnsignedBigInt adUnsignedInt
205 201 203 131 138 4 2 16 21 19
adUnsignedSmallInt 18 adUnsignedTinyInt adUserDefined adVarBinary adVarChar adVariant adVarNumeric 17 132 204 200 12 139
www.sybex.com
867
Constant adVarWChar adWChar
Value 202 130
Description Indicates a null-terminated Unicode character string (Parameter object only) Indicates a null-terminated Unicode character string
EditModeEnum Constant adEditNone
This type specifies the editing status of a record. Value 0 1 2 Indication No editing operation is in progress. Data in the current record has been modified but not saved. The AddNew method has been called and the current record in the copy buffer is a new record that hasnt been saved in the database. The current record has been deleted.
adEditInProgress adEditAdd
adEditDelete ErrorValueEnum Constant adErrBoundToCommand
This type specifies the type of ADO runtime error. Value 3707 Indication The application cannot change the ActiveConnection property of a Recordset object with a Command object as its source. The application is using a value of the wrong type for the current operation. The operation requested by the application is not supported by the provider. The operation requested by the application is not allowed in this context. The application cannot explicitly close a Connection object while in the middle of a transaction.
adErrDataConversion
3421
adErrFeatureNotAvailable 3251
adErrIllegalOperation
3219
adErrInTransaction
3246
www.sybex.com
868
Constant adErrInvalidArgument
Value 3001
Indication The application is using arguments that are of the wrong type, are out of acceptable range, or are in conflict with one another. The application requested an operation on an object with a reference to a closed or invalid Connection object. The application has improperly defined a Parameter object. ADO could not find the object in the collection corresponding to the name or ordinal reference requested by the application. Either BOF or EOF is True or the current record has been deleted. The operation requested by the application requires a current record. An ADO operation that was not executed was requested to be cancelled. Code that would cause an event to reoccur cannot be executed within that event. The operation requested by the application is not allowed if the object is closed. The object is already in the collection and cannot be appended. The object referenced by the application no longer points to a valid object. The operation requested by the application is not allowed if the object is open.
adErrInvalidConnection
3709
adErrInvalidParamInfo adErrItemNotFound
3708 3265
adErrNoCurrentRecord
3021
adErrNotExecuting
3715
adErrNotReentrant
3710
adErrObjectClosed
3704
adErrObjectInCollection 3367 adErrObjectNotSet 3420
adErrObjectOpen
3705
www.sybex.com
869
Constant adErrOperationCancelled adErrProviderNotFound adErrStillConnecting
Value 3712 3706 3713
Indication An ADO operation has been cancelled. ADO could not find the specified provider. ADO was still connecting to the data source when another operation was requested. ADO was still executing a command when another operation was requested. The requested operation is not allowed under the security of the environment that ADO is running under (such as Microsoft Internet Explorer).
adErrStillExecuting
3711
adErrUnsafeOperation
3716
EventReasonEnum Constant adRsnAddNew adRsnDelete adRsnUpdate
This type specifies the reason that caused an event to occur. Value 1 2 3 4 5 6 7 8 9 10 11 Description Added a new record Deleted a record Updated an existing record Reversed an update to an existing record Reversed the adding of a new record Reversed the deletion of a record Re-queried the Recordset Resynchronized the Recordset with the database Closed the Recordset Moved the record pointer within the Recordset Made the first change to a record
adRsnUndoUpdate adRsnUndoAddNew adRsnUndoDelete adRsnRequery adRsnResynch adRsnClose adRsnMove adRsnFirstChange
www.sybex.com
870
Constant adRsnMoveFirst adRsnMoveNext adRsnMovePrevious adRsnMoveLast
Value 12 13 14 15
Description Moved the record pointer to the first record in the Recordset Moved the record pointer to the next record in the Recordset Moved the record pointer to the previous record in the Recordset Moved the record pointer to the last record in the Recordset
EventStatusEnum an event. Constant adStatusOK
This type specifies the current status of the execution of
Value 1 2
Description Indicates that the operation that caused the event was successful Indicates that the operation that caused the event failed due to an error or errors Indicates that the operation cannot request cancellation of the pending operation Requests cancellation of the operation that caused the event to occur Prevents subsequent notifications before the event method has finished executing
adStatusErrorsOccurred
adStatusCantDeny
adStatusCancel adStatusUnwantedEvent
4 5
ExecuteOptionEnum command. Constant
This type specifies how a provider should execute a
Value -1 0x10
Indication The command is unspecified The command should execute asynchronously
adOptionUnspecified adAsyncExecute
www.sybex.com
871
Constant adAsyncFetch
Value 0x20
Indication The remaining rows after the initial quantity specified in the CacheSize property should be fetched asynchronously The main thread never blocks while fetching. If the requested row has not been fetched, the current row automatically moves to the end of the file. The command text is a command or stored procedure that does not return rows (for example, a command that only inserts data). If any rows are retrieved, they are discarded and not returned. Always combined with CommandTypeEnum values adCmdText or adCmdStoredProc.
adAsyncFetchNonBlocking
0x40
adExecuteNoRecords
0x80
FieldEnum This type specifies the special fields referenced in a Record objects Fields collection. Constant adDefaultStream Value 1 Description References the field containing the default Stream object associated with a Record References the field containing the absolute URL string for the current Record
adRecordURL
FieldAttributeEnum istics, of a Field object. Constant
This type specifies one or more attributes, or character-
Value 1 0x2
Indication Does not specify the field attributes The field is deferredthat is, the field values are not retrieved from the data source with the whole record; only when you explicitly access them.
www.sybex.com
adFldUnspecified adFldMayDefer
872
Constant adFldUpdatable
Value 0x4
Indication You can write to the field. The provider cannot determine if you can write to the field. The field contains fixed-length data. The field accepts Null values. You can read Null values from the field. The field is a long binary field. Also indicates that you can use the AppendChunk and GetChunk methods. The field contains a persistent row identifier that cannot be written to and has no meaningful value except to identify the row (such as a record number, unique identifier, and so forth). The field contains some kind of time or date stamp used to track updates. The provider caches field values, and that subsequent reads are done from the cache. The field represents numeric value from a column that supports negative scale values. The scale is specified by the NumericScale property. The field is the primary key of the underlying rowset. Also can indicate that the field is part of a compound primary key.
adFldUnknownUpdatable 0x8 adFldFixed adFldIsNullable adFldMayBeNull adFldLong 0x10 0x20 0x40 0x80
adFldRowID
0x100
adFldRowVersion
0x200
adFldCacheDeferred
0x1000
adFldNegativeScale
0x4000
adFldKeyColumn
0x8000
www.sybex.com
873
FilterGroupEnum a Recordset. Constant adFilterNone
This type specifies the group of records to be filtered from
Value 0 1
Description Removes the current filter and restores all records to view Allows you to view only records that have changed but not yet sent to the server. Applicable only for batch update mode Allows you to view only records affected by the last Delete, Resync, UpdateBatch, or CancelBatch call Allows you to view records in the current cachethat is, the results of the last call to retrieve records from the database Allows you to view the records that failed the last batch update attempt
adFilterPendingRecords
adFilterAffectedRecords
adFilterFetchedRecords
adFilterConflictingRecords
GetRowsOptionEnum from a Recordset. Constant adGetRowsRest
This type specifies how many records to retrieve
Value 1
Description Retrieves the rest of the records in the Recordset, from either the current position or a bookmark specified by the Start parameter of the GetRows method
IsolationLevelEnum a Connection object. Constant
This type specifies the level of transaction isolation for
Value 1
Indication The provider is using a different isolation level than specified, but that the level cannot be determined.
adXactUnspecified
www.sybex.com
874
Constant adXactChaos
Value 16
Indication You cannot overwrite pending changes from more highly isolated transactions. From one transaction you can view uncommitted changes in other transactions. Same as adXactBrowse From one transaction you can view changes in other transactions only after theyve been committed. Same as adXactCursorStability From one transaction you cannot see changes made in other transactions, but requerying can bring new Recordsets. Transactions are conducted in isolation of other transactions. Same as adXactIsolated
adXactBrowse
256
adXactReadUncommitted adXactCursorStability
256 4096
adXactReadCommitted adXactRepeatableRead
4096 65536
adXactIsolated adXactSerializable
1048576 1048576
LineSeparatorsEnum This type specifies the character used as a line separator in text Stream objects. Constant adCRLF adLF adCR LockTypeEnum editing. Constant adLockUnspecified Value Chr(10) & Chr(13) Chr(10) Chr(13) Description Default; indicates carriage return line feed Indicates line feed Indicates carriage return
This type specifies the type of lock placed on records during
Value 1
Description Does not specify a type of lock. For clones, the clone is created with the same lock type as the original.
www.sybex.com
875
Constant adLockReadOnly adLockPessimistic
Value 1 2
Description Indicates read-onlyyou cannot alter the data. Indicates pessimistic locking, record by recordthe provider does what is necessary to ensure successful editing of the records, usually by locking records at the data source immediately upon editing. Indicates optimistic locking, record by recordthe provider uses optimistic locking, locking records only when you call the Update method. Indicates optimistic batch updates required for batch update mode as opposed to immediate update mode.
adLockOptimistic
adLockBatchOptimistic
MarshalOptionsEnum to the server. Constant adMarshalAll
This type specifies which records should be returned
Value 0 1
Description Default; returns all rows to the server Returns only modified rows to the server
adMarshalModifiedOnly
ModeEnum
This type specifies the access mode for a Stream object. Value 0 1 2 3 Description Indicates that access mode for the Stream object is not known Opens the Stream object in readonly mode Opens the Stream object in writeonly mode Opens the Stream object in readwrite mode
Constant adoModeUnknown adoModeRead adoModeWrite adoModeReadWrite
www.sybex.com
876
Constant adoModeShareDenyRead
Value 4
Description Opens the Stream object in Sharedeny read mode. While the object is opened in this mode, read access is denied to other processes. Opens the Stream object in Sharedeny write mode. While the object is opened in this mode, write access is denied to other processes. Opens the Stream object in Shareexclusive mode. While the object is opened in this mode, all access is denied to other processes. Opens the Stream object in Sharenone mode. While the object is opened in this mode, no access is denied to other processes.
adoModeShareDenyWrite
adoModeShareExclusive
12
adoModeShareDenyNone
16
MoveRecordOptionsEnum object MoveRecord method. Constant adMoveOverWrite
This type specifies the behavior of the Record
Value 1
Description Overwrites the Record with the MoveRecord method if the Destination points to an already existing Record Modifies the default behavior of MoveRecord method by not updating the hypertext links of the source Record. The default behavior depends on the capabilities of the provider. Move operation updates links if the provider is capable. If the provider cannot fix up links or if this value is not specified, then the move succeeds even when links have not been fixed.
adMoveDontUpdateLinks
www.sybex.com
877
Constant adMoveAllowEmulation
Value 4
Description Requests that the provider attempt to simulate the move (using download, upload, and delete operations) if the attempt to move the Record fails because the destination URL is on a different server or serviced by a different provider than the source. Note that this may cause increased latency and/or data loss, because of different provider capabilities when moving resources between providers.
ObjectStateEnum This type specifies whether an object is open or closed, connecting to a data source, executing a command, or fetching data. Constant adStateClosed adStateOpen adStateConnecting adStateExecuting adStateFetching Value 0 1 2 4 8 Indication The object is closed. The object is open. The object is connecting. The object is executing a command. The rows of the object are being fetched. This type specifies the attributes of a Parameter
ParameterAttributesEnum object. Constant adParamSigned adParamNullable adParamLong
Value 16 64 128
Indication The parameter accepts signed values. The parameter accepts Null values. The parameter accepts long binary data.
ParameterDirectionEnum This type specifies whether the Parameter represents an input parameter, an output parameter, or both, or if the parameter is the return value from a stored procedure. Constant adParamUnknown Value 0 Indication Parameter direction is unknown.
www.sybex.com
878
Constant adParamInput adParamOutput
Value 1 2
Indication Default: an input parameter An output parameter Both an input and output parameter A return value
adParamInputOutput 3 adParamReturnValue 4 PersistFormatEnum Recordset. Constant adPersistADTG adPersistXML
This type specifies the format in which to save a
Value 0 1
Description Recordset is saved in ADTG (Advanced Data TableGram) format. Indicates XML (Extended Markup Language) format
PositionEnum This type specifies the current position of the record pointer within a Recordset. Constant adPosUnknown Value 1 Indication The Recordset is empty, the current position is unknown, or the provider does not support the AbsolutePage or AbsolutePosition property. The current record pointer is at BOF (that is, the BOF property is True). The current record pointer is at EOF (that is, the EOF property is True). This type specifies the attributes of a Property
adPosBOF adPosEOF
2 3
PropertyAttributesEnum object. Constant
Value
Indication The property is not supported by the provider. The user must specify a value for this property before the data source is initialized.
adPropNotSupported 0 adPropRequired 1
www.sybex.com
879
Constant adPropOptional
Value 2
Indication The user does not need to specify a value for this property before the data source is initialized. The user can read the property. The user can set the property.
adPropRead adPropWrite
512 1024
RecordCreateOptionsEnum This type specifies whether an existing Record should be opened or a new Record created for the Record object Open method. Constant adCreateCollection Value 0x2000 Description Creates a new Record at the node specified by Source parameter instead of opening an existing Record. If the source points to an existing node, then a runtime error occurs. Only valid with sourcetype of adSourceBind and adSourceRelURLBind. Creates a new Record of type adRecordStructDoc, instead of opening an existing Record Creates a new Record of type adRecORdNotCollection Modifies the creation flags specified above. When OR is used with this value and one of the above values, if the source URL points to an existing node or Record object, the provider must open the existing Record instead of creating a new one. This cannot be used together with adCreate Overwrite.
adCreateStructDoc
0x80000000
adCreateNonCollection adOpenIfExists
0 0x2000000
www.sybex.com
880
Constant adCreateOverwrite
Value 0x4000000
Description Modifies the creation flags specified above. When OR is used with this value and one of the above values, if the source URL points to an existing node or Record, then the existing Record is overwritten and a new one is created in its place. This cannot be used together with adOpenIfExists. Default; results in a runtime error if Source points to a nonexistent node.
adFailIfNotExists
RecordOpenOptionsEnum This type specifies options for opening a Record. These values may be combined by using OR. Constant adOpenSource Value 0x800000 Description Indicates that if the source points to a node that contains an executable script (such as .ASP), then a Record containing the source is opened rather than the executed contents. Only valid with non-collection records. Indicates that the Record object is opened in asynchronous mode Hints to the provider that the fields associated with the Record need not be fetched initially, but can be fetched at the first attempt to access the field. The default behavior, indicated by the absence of this flag, is to fetch all the Record object fields.
adOpenAsync adDelayFetchFields
0x1000 0x8000
www.sybex.com
881
Constant adDelayFetchStream
Value 0x4000
Description Hints to the provider that the default stream associated with the Record need not be fetched initially. The default behavior, indicated by the absence of this flag, is to fetch the default stream associated with the Record object. Indicates that the connection string represents a URL. Either or both this constant and the URL= connection string keyword may be specified to indicate a URL.
adOpenURLBind
0x400
RecordStatusEnum This type specifies the status of a record with regard to batch updates and other bulk operations. Constant adRecOK adRecNew adRecModified adRecDeleted adRecUnmodified adRecInvalid Value 0 0x1 0x2 0x4 0x8 0x10 Indication The record was successfully updated. The record is new. The record was modified. The record was deleted. The record was not modified. The record was not saved because its bookmark is invalid. The record was not saved because it would have affected multiple records. The record was not saved because it refers to a pending insert. The record was not saved because the operation was canceled.
adRecMultipleChanges
0x40
adRecPendingChanges
0x80
adRecCanceled
0x100
www.sybex.com
882
Constant AdRecCantRelease
Value 0x400
Indication The new record was not saved because of existing record locks. The record was not saved because optimistic concurrency was in use. The record was not saved because the user violated integrity constraints. The record was not saved because there were too many pending changes. The record was not saved because of a conflict with an open storage object. The record was not saved because the computer has run out of memory. The record was not saved because the user has insufficient permissions. The record was not saved because it violates the structure of the underlying database. The record has already been deleted from the data source.
adRecConcurrencyViolation
0x800
adRecIntegrityViolation
0x1000
adRecMaxChangesExceeded
0x2000
adRecObjectOpen
0x4000
adRecOutOfMemORy
0x8000
adRecPermissionDenied
0x10000
adRecSchemaViolation
0x20000
adRecDBDeleted
0x40000
RecordTypeEnum Constant
This type specifies the type of Record object. Value 0 Indication A simple record (does not contain child nodes) A collection record (contains child nodes) A special kind of collection record that represents OLE-structured documents
adSimpleRecord
adCollectionRecord 1 adStructDoc 2
www.sybex.com
883
ResyncEnum This type specifies whether underlying values are overwritten by a call to Resync. Constant adResyncAllValues adResyncUnderlyingValues Value 2 1 Description Default; overwrites data, and pending updates are cancelled. Does not overwrite data, and pending updates are not cancelled.
SaveOptionsEnum This type specifies whether a file should be created or overwritten when saving from a Stream object. The values can be combined with an AND operator. Constant adSaveCreateNotExist Value 1 Description Default; creates a new file if the file specified by the FileName parameter is not already existing Overwrites the file with the data from the currently open Stream object, if the file specified by the Filename parameter already exists
adSaveCreateOverwrite
SchemaEnum This type specifies the type of schema Recordset to be retrieved by the OpenSchema method. Constant adSchemaProviderSpecific Value -1 Description Used if the provider defines its own nonstandard schema queries outside of those listed as follows Returns the assertions, defined in the catalog, which are owned by a given user Returns the physical attributes associated with catalogs accessible from the DBMS Returns the character sets, defined in the catalog, which are accessible to a given user
adSchemaAsserts
adSchemaCatalogs
adSchemaCharacterSets
www.sybex.com
884
Constant adSchemaCollations
Value 3
Description Returns the character collations, defined in the catalog, which are accessible to a given user Returns the columns of tables (including views), defined in the catalog, which are accessible to a given user Returns the check constraints, defined in the catalog, which are owned by a given user Returns the columns used by referential constraints, unique constraints, check constraints, and assertions; defined in the catalog and owned by a given user Returns the tables that are used by referential constraints, unique constraints, check constraints, and assertions; defined in the catalog and owned by a given user Returns the columns, defined in the catalog, which are constrained as keys by a given user Returns the referential constraints, defined in the catalog, which are owned by a given user Returns the table constraints, defined in the catalog , which are owned by a given user
adSchemaColumns
adSchemaCheckConstraints
adSchemaConstraintColumnUsage
adSchemaConstraintTableUsage
adSchemaKeyColumnUsage
adSchemaReferentialConstraints
adSchemaTableConstraints
10
www.sybex.com
885
Constant adSchemaColumnsDomainUsage
Value 11
Description Returns the columns, defined in the catalog, which are dependent on a domain defined in the catalog and owned by a given user Returns the indexes, defined in the catalog, which are owned by a given user Returns the privileges on columns of tables, defined in the catalog, which are available to or granted by a given user Returns the privileges on tables, defined in the catalog, which are available to or granted by a given user Returns the USAGE privileges on objects, defined in the catalog, which are available to or granted by a given user Returns the procedures, defined in the catalog, which are owned by a given user Returns the schemas (database objects) that are owned by a given user Returns the conformance levels, options, and dialects supported by the SQLimplementation processing data defined in the catalog Returns the statistics, defined in the catalog, which are owned by a given user Returns the tables (including views), defined in the catalog, which are accessible to a given user
adSchemaIndexes
12
adSchemaColumnPrivileges
13
adSchemaTablePrivileges
14
adSchemaUsagePrivileges
15
adSchemaProcedures
16
adSchemaSchemata
17
adSchemaSQLLanguages
18
adSchemaStatistics
19
adSchemaTables
20
www.sybex.com
886
Constant adSchemaTranslations
Value 21
Description Returns the character translations, defined in the catalog, which are accessible to a given user Returns the (base) data types supported by the data provider Returns the views, defined in the catalog, which are accessible to a given user Returns the columns on which viewed tables, defined in the catalog and owned by a given user, are dependent Returns the tables on which viewed tables, defined in the catalog and owned by a given user, are dependent Returns information about the parameters and return codes of procedures Returns the foreign key columns defined in the catalog by a given user Returns the primary key columns defined in the catalog by a given user Returns information about the columns of rowsets returned by procedures Returns a list of provider-specific keywords Returns a list of providerspecific literals used in text commands
adSchemaProviderTypes adSchemaViews
22 23
adSchemaViewColumnUsage
24
adSchemaViewTableUsage
25
adSchemaProcedureParameters 26
adSchemaForeignKeys
27
adSchemaPrimaryKeys
28
adSchemaProcedureColumns
29
adSchemaDBInfoKeywORds adSchemaDBInfoLiterals
30 31
www.sybex.com
887
Constant adSchemaCubes
Value 32
Description Returns information about the available cubes in a schema (or in the catalog, if the provider does not support schemas) Returns information about the dimensions in a given cube. It has one row for each dimension. Returns information about the hierarchies available in a dimension Returns information about the levels available in a dimension Returns information about the available measures Returns information about the available properties for each level of the dimension Returns information about the available members Returns information about trustees
adSchemaDimensions
33
adSchemaHierarchies
34
adSchemaLevels adSchemaMeasures adSchemaProperties
35 36 37
adSchemaMembers adSchemaTrustees
38 39
SearchDirectionEnum within a Recordset. Constant adSearchForward
This type specifies the direction of a record search
Value 1
Description Searches forward. Search stops at end of Recordset. If a match is not found, the record pointer is positioned at EOF. Searches backward. Search stops at beginning of Recordset. If a match is not found, the record pointer is positioned at BOF.
adSearchBackward
www.sybex.com
888
SeekEnum
This type specifies the type of Seek to execute. Value 1 2 4 Description Seeks the first key equal to KeyValues Seeks the last key equal to KeyValues Seeks a key equal to KeyValues or just after where that match would have occurred Seeks a key just after where a match with KeyValues would have occurred Seeks a key equal to KeyValues or just before where that match would have occurred Seeks a key just before where a match with KeyValues would have occurred
Constant adSeekFirstEQ adSeekLastEQ adSeekAfterEQ
adSeekAfter adSeekBeforeEQ
8 16
adSeekBefore
32
StatePropertyEnum This type specifies whether the current state of the Stream object is closed, open, or executing. Constant adStateClosed adStateOpen adStateExecuting Value 0 1 4 Indication Default; the Stream object is closed. The Stream object is open. The Stream object is in the process of being opened (the Open method has not yet completed).
StreamOpenOptionsEnum This type specifies options for opening a Stream object. The values can be combined with the AND operator. Constant adOpenStreamAsync adOpenStreamFromRecord Value 1 4 Description Opens the Stream object in asynchronous mode Identifies the contents of the Source parameter to be an already open Record object. The default behavior is to treat Source as a URL that points directly to a node in a tree structure. The default stream associated with that node is opened.
www.sybex.com
889
Constant adOpenStreamFromURL
Value 8
Description Default; identifies the contents of the Source parameter to be an absolute URL, pointing to a node in a tree structure. The default stream associated with that node is opened as the Stream object.
StreamReadEnum This type specifies whether the whole stream or the next line should be read from a Stream object. Constant adReadAll adReadLine Value 1 2 Description Default; reads all bytes from the stream, from the current position onwards to the EOS marker Reads the next line from the stream (designated by the LineSeparator property)
StreamTypeEnum Constant
This type specifies the type of data stored in a Stream object. Value 1 2 Indication Default; binary data ANSI text
adTypeBinary adTypeText
StreamWriteOptionsEnum This type specifies whether a line separator is appended to the string written to a Stream object. Constant adWriteChar adWriteLine Value 0 1 Description Default; writes the specified text string (specified by the Data parameter) to the Stream object Writes a text string and a line separator character to a Stream object. If the LineSeparator property is not defined, then this returns a runtime error.
StringFormatEnum set as a string. Constant adClipString
This type specifies the format when retrieving a Record-
Value 2
Description Delimits rows by RowDelimiter, columns by ColumnDelimiter, and NULL values by NullExpr
www.sybex.com
890
XactAttributeEnum Constant
Specifies the transaction attributes of a Connection object. Value 131072 Description Performs retaining commitsthat is, calling CommitTrans automatically starts a new transaction. Not all providers support this. Performs retaining abortsthat is, calling
adXactCommitRetaining
adXactAbortRetaining
262144
www.sybex.com

Mastering VB6 Database

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Mastering VB6 Database

Hochgeladen von

Copyright:

Verfügbare Formate

SYBEX Supplement

Mastering Database Programming with Visual Basic 6

Appendix: ADO 2.5 Object Model

ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Command Object Parameters Collection

Recordset Object Fields Collection

Record Object Fields Collection

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

File Name = <file name>

Remote Provider = <remote provider name>

Remote Server = <remote server name>

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Heres how to add a new row with a single statement:

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

FieldChangeComplete MoveComplete RecordChangeComplete RecordsetChangeComplete WillChangeField WillChangeRecord WillChangeRecordset WillMove

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Fields Collection Methods

Copyright 2000 SYBEX Inc., Alameda, CA

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

Copyright 2000 SYBEX Inc., Alameda, CA

Appendix ADO 2.5 Object Model

ADO Enumerated Types