what's new in dao? · with dao, you can set the partialreplica property on a relation which...

What'sNewinDAO?

DAO3.5introducesanewclient/serverconnectionmode,called"ODBCDirect."ODBCDirectestablishesaconnectiondirectlytoanODBCdatasource,withoutloadingtheMicrosoftJetdatabaseengineintomemory,andisusefulinsituationswherespecificfeaturesofODBCarerequired.

ForMicrosoftJetdatabases,therearealsonewinterfacestoexposeMicrosoftJet'snewpartialreplicationfeature.

NoteYoucansendDAOqueriestoavarietyofdifferentdatabaseserverswithODBCDirect,anddifferentserverswillrecognizeslightlydifferentdialectsofSQL.Therefore,context-sensitiveHelpisnolongerprovidedforMicrosoftJetSQL,althoughonlineHelpforMicrosoftJetSQLisstillincludedthroughtheHelpmenu.BesuretochecktheappropriatereferencedocumentationfortheSQLdialectofyourdatabaseserverwhenusingeitherODBCDirectconnectionsorpass-throughqueriesinMicrosoftJet-connectedclient/serverapplications.

NewDAO3.5InterfacesforODBCDirect

Connectionobject—AconnectiontoanODBCdatabase.

Cancelmethod(onConnection,QueryDef,andRecordsetobjects)—Cancelsexecutionofanasynchronousoperation.

NextRecordsetmethod(onRecordsetobjects)—Retrievesthenextsetofrecords,ifany,returnedbyaquerythatreturnedmultiplesetsofrecordsinanOpenRecordsetcall,andindicateswhetheritsuccessfullyretrievedanothersetofrecords.

OpenConnectionmethod(onWorkspaceobjects)—OpensaConnectionobjectonanODBCdatasource.

BatchCollisionCountproperty(onRecordsetobjects)—Returnsthenumberofrecordsthatdidnotcompleteduringthelastbatchupdate.

BatchCollisionsproperty(onRecordsetobjects)—Returnsanarrayofbookmarksindicatingtherowsthatgeneratedcollisionsinthelastbatchupdate.

BatchSizeproperty(onRecordsetobjects)—Setsorreturnsthenumberofstatementssentbacktotheserverineachbatch.

Connectionproperty(onDatabaseandRecordsetobjects)—ReturnstheConnectionobjectthatcorrespondstotheDatabase,

orthatownstheRecordset.

Databaseproperty(onConnectionobjects)—ReturnsthenameoftheDatabaseobjectthatcorrespondstotheConnection.

DefaultCursorDriverproperty(onWorkspaceobjects)—SetsorreturnsthetypeofcursordriverusedforODBCDirectRecordsetobjects.

DefaultTypeproperty(onDBEngineobject)—Indicateswhattypeofworkspace(MicrosoftJetorODBCDirect)willbecreatedbythenextCreateWorkspacemethodcall.

Directionproperty(onParameterobjects)—IndicateswhetheraParameterobjectrepresentsaninputparameter,anoutputparameter,orboth,oriftheparameteristhereturnvaluefromastoredprocedure.

MaxRecordsproperty(onQueryDefobjects)—Setsorreturnsthemaximumnumberofrecordstoreturnfromaquery.

OriginalValueproperty(onFieldobjects)—ReturnsthevalueofaFieldinthedatabasethatexistedwhenthelastbatchupdatebegan.

Prepareproperty(onQueryDefobjects)—ReturnsavaluethatindicateswhetherthequeryshouldbepreparedontheserverasatemporarystoredprocedurewiththeODBCSQLPrepare

functionpriortoexecution,orjustexecutedusingtheODBCSQLExecDirectfunction.

RecordStatusproperty(onRecordsetobjects)—Returnsavaluethatindicatestheupdatestatusofthecurrentrecordifitispartofabatchupdate.

StillExecutingproperty(onConnection,QueryDef,andRecordsetobjects)—Returnsavalueindicatingwhetherornotanasynchronousoperationhasfinishedexecuting.

UpdateOptionsproperty(onRecordsetobjects)—ReturnsavaluethatindicateshowtheWHEREclauseisconstructedforeachrecordduringabatchupdate,andhowtheupdateshouldbeexecuted.

VisibleValueproperty(onRecordsetobjects)—ReturnsavaluecurrentlyinthedatabasethatisnewerthantheOriginalValuepropertyasdeterminedbyabatchupdateconflict.

NewCapabilitieswithODBCDirectServerConnections

AvailableonlyintheODBCDirectobjectmodel,thenewConnectionobjectcontainsinformationaboutaconnectiontoanODBCdatasource,suchastheservername,thedatasourcename,andsoon.ItissimilartoaDatabaseobject,andwilllookveryfamiliarifyou'veeveropenedaDatabaseobjectonanODBCdatasource.Infact,aConnectionobjectandaDatabaseobjectrepresentdifferentreferencestothesameobject,andnewpropertiesoneachofthesetwoobjecttypesallowyoutoobtainareferencetotheothercorrespondingobject,whichsimplifiesthetaskofconvertingexistingODBCclientapplicationsthatuseMicrosoftJettouseODBCDirectinstead.

BatchUpdates

Anewbatchupdatecursorisavailableforclientapplicationsthatneedtoworkwithacursorwithoutholdinglocksontheserverorissueupdaterequestsonerecordatatime.Instead,theclientstoresupdateinformationonmanyrecordsinalocalbuffer(or"batch"),andthenissuesabatchupdate.

BecauseofthetimelagbetweenopeningaRecordsetandsendingabatchofupdatesfromthatRecordsetbacktotheserver,otherusershaveanopportunitytochangetheoriginaldatabeforeyourchangesaresenttotheserver,soyourchanges"collide"withanotheruser'schanges.Severalnewfeaturesareavailabletohelpyoudeterminewheresuchcollisionshaveoccurred,followingabatchupdate,andgiveyousomeoptionsforresolvingthem.

AsynchronousMethodExecution

TheExecute,MoveLast,OpenConnection,andOpenRecordsetmethodsfeaturethedbRunAsyncoption.Thisallowstheclientapplicationtodoothertasks(suchasloadingforms,andsoon)whilethemethodisexecuting.Youcanalsopolltoseewhetherthetaskis

complete,andterminateanasynchronoustask.

ClientSupportforODBCCursors

FourdifferentRecordsettypessupportthefollowingODBCcursortypes:

ODBCCursor RecordsettypeDynamic dbOpenDynamic(NewinDAO3.5)Dynaset dbOpenDynaset

Forward-Only dbOpenForwardOnly(NewinDAO3.5)

Static dbOpenSnapshot

NewDAO3.5InterfacesfortheMicrosoftJetDatabaseEngine

PopulatePartialmethod(onDatabaseobjects)—Synchronizesanychangesinapartialreplicawiththefullreplica,clearsallrecordsinthepartialreplica,andthenrepopulatesthepartialreplicabasedonthecurrentreplicafilters.

SetOptionmethod(onDBEngineobject)—OverridestheregistryvaluesfortheMicrosoftJetdatabaseengineforthedurationofthecurrentinstanceofDAO.

FieldSizeproperty(onFieldobjects)—ReplacestheFieldSizemethod.Syntactically,theirusageisthesame,sothiswillnotrequirechangestoyourexistingcode.

MaxRecordsproperty(onQueryDefobjects)—Setsorreturnsthemaximumnumberofrecordstoreturnfromaquery.

ReplicaFilterproperty(onTableDefobjects)—Returnsavaluethatindicateswhichsubsetofrecordsisreplicatedtothattablefromafullreplica.

PartialReplicaproperty(onRelationobjects)—IndicateswhichRelationobjectshouldbeconsideredwhenpopulatingapartialreplicafromafullreplica.

NewCapabilitieswiththeMicrosoftJetDatabaseEnginePartialReplication

Version3.5oftheMicrosoftJetdatabaseengineallowsuserstoreplicateportionsofatableinsteadofthewholetable(onlyrowrestrictionsarepermitted,notcolumns).Therearetwotypesoffiltersusedinapartialreplica—Booleanandrelationship.Booleanfiltersselectonlyrowsthatmeetacertaincriteriatolimittherowsinatablethatarereplicated.DAOrepresentsthisfilterwiththeReplicaFilterpropertyonaTableDef.Relationshipfiltersenforcearelationshipbetweenpartiallyreplicatedtablestolimittherowsinatablethatarereplicated.WithDAO,youcansetthePartialReplicapropertyonaRelationwhichallowsthatRelationtobeusedinpartialreplication.

NewRecordsetType

InDAO3.5,dbOpenForwardOnlyisanewtypeargumentfortheOpenRecordsetmethod.ThisnewRecordsettypebehavesinthesamewayasaDAO3.0snapshot-typeRecordsetopenedwiththedbForwardOnlyoption.

Run-timeRegistryOverride

ThenewSetOptionmethodallowsyoutooverrideMicrosoftJetRegistrysettingsatruntime.ThisletsyoufinetuneMicrosoftJetqueryperformance,timeoutdelays,andsoon.

DAOOverview

DAOenablesyoutouseaprogramminglanguagetoaccessandmanipulatedatainlocalorremotedatabases,andtomanagedatabases,theirobjects,andtheirstructure.

ObjectModelsDAOsupportstwodifferentdatabaseenvironments,or"workspaces."

MicrosoftJetworkspacesallowyoutoaccessdatainMicrosoftJetdatabases,MicrosoftJet-connectedODBCdatabases,andinstallableISAMdatasourcesinotherformats,suchasParadoxorLotus1-2-3.

ODBCDirectworkspacesallowyoutoaccessdatabaseserversthroughODBC,withoutloadingtheMicrosoftJetdatabaseengine.

UsetheMicrosoftJetworkspacewhenyouopenaMicrosoftJetdatabase(.mdbfile)orotherdesktopISAMdatabase,orwhenyouneedtotakeadvantageofMicrosoftJet'suniquefeatures,suchastheabilitytojoindatafromdifferentdatabaseformats.

TheODBCDirectworkspaceprovidesanalternativewhenyouonlyneedtoexecutequeriesorstoredproceduresagainstaback-endserver,suchasMicrosoftSQLServer,orwhenyourclientapplicationneedsthespecificcapabilitiesofODBC,suchasbatchupdatesorasynchronousqueryexecution.

DAOObjects

Thereare17differentDAOobjecttypes.YoucandeclarenewDAOobjectvariablesforanyoftheobjecttypes.

Forexample,thefollowingVisualBasicforApplications(VBA)codecreatesobjectvariablesforaDatabaseobject,adynaset-typeRecordsetobject,andaFieldobject:

DimdbsExampleAsDatabaseDimrstExampleAsRecordset

DimfldExampleAsField

SetdbsExample=OpenDatabase("Biblio.mdb")SetrstExample=dbsExample.OpenRecordset("Authors",_dbOpenDynaset)SetfldExample=rstExample.Fields("Au_ID")

DAOCollections

EachDAOobjecttypeotherthanDBEnginealsohasacorrespondingcollection.Acollectionincludesalltheexistingobjectsofthattype.Forexample,theRecordsetscollectioncontainsallopenRecordsetobjects.Eachcollectionis"owned"byanotherobjectatthenexthigherlevelinthehierarchy.ADatabaseobject"owns"aRecordsetscollection.ExceptfortheConnectionandErrorobjects,everyDAOobjecthasaPropertiescollection.

MostDAOobjectshavedefaultcollectionsanddefaultproperties.Forexample,thedefaultcollectionofaRecordsetobjectistheFieldscollectionandthedefaultpropertyofaFieldobjectistheValueproperty.Youcansimplifyyourcodebytakingadvantageofthesedefaults.Forexample,thefollowingcodesetsthevalueofthePubIDfieldinthecurrentrecord:

rstExample!PubID=99

DBENGINEANDWORKSPACEOBJECTS

AllDAOobjectsarederivedfromtheDBEngineobject.YoucansettheDefaultTypepropertyontheDBEngineobjecttodeterminetheworkspacetype(MicrosoftJetorODBCDirect)tocreateonsubsequentCreateWorkspacemethodcalls,oryoucanoverridethispropertywiththetypeargumentintheCreateWorkspacemethoditself.Whenyourapplicationcreatesaworkspace,theappropriatelibrary—theMicrosoftJetdatabaseengineorODBC—isloadedintomemoryatthattime.

YoucanopenadditionalWorkspaceobjectsasneeded.EachWorkspaceobjecthasauserIDandpasswordassociatedwithit.

UsingtheMicrosoftJetWorkspaceOpeningaDatabase

Toopenadatabase,yousimplyopenanexistingDatabaseobject,orcreateanewone.ThisobjectcanrepresentaMicrosoftJetdatabase(.mdbfile),anISAMdatabase(forexample,Paradox),oranODBCdatabaseconnectedthroughtheMicrosoftJetdatabaseengine(alsoknownasa"MicrosoftJet-connectedODBCdatabase").

Data-DefinitionLanguage

YoucanuseobjectvariablesandotherDDLfeaturestomodifyyourdatabasestructure.Forexample,youcanaddanewFieldobjecttoanexistingtablewiththefollowingcode:

DimdbsAsDatabase,tdfAsTableDef,fldAsField'Openadatabase.Setdbs=OpenDatabase("Biblio.mdb")'OpenaTableDef.Settdf=dbs.TableDefs("Authors")'Createanewfield.Setfld=tdf.CreateField("Address",dbText,20)'AppendfieldtotheTableDefFieldscollection.tdf.Fields.Appendfld

ThiscodecreatesanewobjectvariableforaFieldobjectandaddsittoaTableDefobjectwiththeAppendmethod.BecauseaTableDefobjectcontainsthedefinitionofatable,thetablenowhasafieldnamedAddressforenteringdata.Inmuchthesameway,youcancreatenewtablesandnewindexes.

DataManipulation

DAOprovidesanexcellentsetofdatamanipulationtools.YoucancreateaRecordsetobjecttoconvenientlyqueryadatabaseandmanipulatethe

resultingsetofrecords.TheOpenRecordsetmethodacceptsanSQLstring,oraQueryDef(storedquery)nameasadatasourceargument,oritcanbeopenedfromaQueryDefobjectoraTableDefobject,usingthatobjectasitsdatasource.TheresultingRecordsetobjectfeaturesanextremelyrichsetofpropertiesandmethodswithwhichtobrowseandmodifydata.

TheRecordsetobjectisavailableinfourdifferenttypes—Table,Dynaset,Forward-Only,andSnapshot.

Transactions

AllDatabaseobjectsopenedagainstaWorkspaceobjectshareacommontransactionscope.Thatis,whenyouusetheBeginTransmethodonaWorkspaceobject,itappliestoallopendatabaseswithinthatWorkspaceobject.Inthesameway,whenyouusetheCommitTransmethodagainsttheWorkspace,itappliestoallopendatabasesintheWorkspaceobject.

Replication

YoucanusedatabasereplicationtocreateandmaintainreplicasofamasterMicrosoftJetdatabase,usingtheSynchronizemethodtoperiodicallyupdateallorpartofthereplicas,ortocopynewdatafromonereplicatoanother.Youcanalsorestricttheupdatetoonlyselectedrecords,usingtheReplicaFilterproperty,andthensynchronizethoserecordswiththePopulatePartialmethod.

Security

Youcanrestrictaccesstooneormore.mdbdatabasesortheirtablesusingsecuritysettingsestablishedandmanagedbytheMicrosoftJetdatabaseengine.Inyourcode,youcanestablishGroupandUserobjectstodefinethescopeandlevelofpermissionsavailabletoindividualusersonanobject-by-objectbasis.Forexample,youcanestablishpermissionsforaspecificusertoprovideread-onlyaccesstoonetableandfullaccesstoanother.

UsingtheODBCDirectObjectModelConnectingtoaDatabase

AConnectionobjectissimilartoaDatabaseobject.Infact,aConnectionobjectandaDatabaseobjectrepresentdifferentreferencestothesameobject,andpropertiesoneachofthesetwoobjecttypesallowyoutoobtainareferencetotheothercorrespondingobject,whichsimplifiesthetaskofconvertingODBCclientapplicationsthatuseMicrosoftJettouseODBCDirectinstead.UsetheOpenConnectionmethodtoconnecttoanODBCdatasource.TheresultingConnectionobjectcontainsinformationabouttheconnection,suchastheservername,thedatasourcename,andsoon.

Queries

AlthoughDAOdoesnotsupportstoredqueresinanODBCDirectworkspace,acompiledquerycanbecreatedasaQueryDefobjectandusedtoexecuteactionqueries,andcanalsobeusedtoexecutestoredproceduresontheserver.ThePreparepropertyletsyoudecidewhethertocreateaprivate,temporarystoredprocedureontheserverfromaQueryDefbeforeactuallyexecutingthequery.

Parameterqueriescanalsobepassedtotheserver,usingParameterobjectsontheQueryDef.TheDirectionpropertyletsyouspecifyaParameterasinput,output,orboth,ortoacceptareturnvaluefromastoredprocedure.

DataManipulation

CreatingaRecordsetobjectisaconvenientwaytoqueryadatabaseandmanipulatetheresultingsetofrecords.TheOpenRecordsetmethodacceptsanSQLstring,oraQueryDefobject(storedquery)asadatasourceargument.TheresultingRecordsetobjectfeaturesanextremelyrichsetofpropertiesandmethodswithwhichtobrowseandmodifydata.

TheRecordsetobjectisavailableinfourdifferenttypes—Dynamic,

Dynaset,Forward-Only,andSnapshot—correspondingtoODBCcursortypes—Dynamic,Keyset,Forward-only,andStatic.

Abatchupdatecursorlibraryisavailableforclientapplicationsthatneedtoworkwithacursorwithoutholdinglocksontheserverorwithoutissuingupdaterequestsonerecordatatime.Instead,theclientstoresupdateinformationonmanyrecordsinalocalbuffer(or"batch"),andthenissuesabatchupdate.

AsynchronousMethodExecution

TheExecute,MoveLast,OpenConnection,andOpenRecordsetmethodsfeaturethedbRunAsyncoption.Thisallowsyourclientapplicationtodoothertasks(suchasloadingforms,forexample)whilethemethodisexecuting.YoucanchecktheStillExecutingpropertytoseewhetherthetaskiscomplete,andterminateanasynchronoustaskwiththeCancelmethod.

DAOConstants

DAOprovidesbuilt-inconstantsthatyoucanusewithmethodsorproperties.Theseconstantsallbeginwiththelettersdbandaredocumentedwiththemethodorpropertytowhichtheyapply.

Legend:

Read-only

Read/write

AllPermissionsPropertyConstants(AllAre )

ForanyContainerorDocumentobject:

Constant Description

dbSecReadDef Allowsusertoreadthetabledefinition,includingcolumnandindexinformation.

dbSecWriteDefAllowsusertomodifyordeletethetabledefinition,includingcolumnandindexinformation.

dbSecRetrieveData AllowsusertoretrievedatafromtheDocumentobject.

dbSecInsertData Allowsusertoaddrecords.dbSecReplaceData Allowsusertomodifyrecords.dbSecDeleteData Allowsusertodeleterecords.

TheDatabasescontaineroranyDocumentobjectinaDocumentscollectionmayincludethefollowing:

Constant DescriptiondbSecDeleteData Allowsusertodeleterecords.

dbSecDBAdmin Allowsusertoreplicatethedatabaseandchangethedatabasepassword.

dbSecDBCreate

Allowsusertocreatenewdatabases.ThissettingisvalidonlyontheDatabasescontainerintheworkgroupinformationfile(System.mdw).

dbSecDBExclusive Allowsuserexclusiveaccesstothedatabase.dbSecDBOpen Allowsusertoopenthedatabase.

AttributesPropertyConstants

ForanyFieldobject,theAttributespropertymayincludethefollowing:


dbFixedField Fixedfieldsize(defaultforNumericfields)

dbVariableField Variablefieldsize(Textfieldsonly)

dbAutoIncrField

NewrecordfieldvalueincrementedtouniqueLonginteger(inaMicrosoftJetworkspace,availableonlyonTableDefobjectsopenedfrom.mdbfiles)

dbUpdatableField Fieldisupdatable

dbDescending Fieldsortedindescendingorder(MicrosoftJetworkspacesonly)

dbHyperlinkFieldThefieldcontainshyperlinkinformation

(MemofieldsinMicrosoftJetworkspacesonly)

dbSystemField

Thefieldisareplicationfield(onaTableDefobjectinMicrosoftJetdatabases

only)

ForanyRelationobject,theAttributespropertymayincludethefollowing:

Constant DescriptiondbRelationUnique One-to-onerelationship

dbRelationDontEnforce Relationshipnotenforced(noreferentialintegrity)

dbRelationInherited Relationshipexistsinthedatabasecontainingthetwolinkedtables

dbRelationUpdateCascade UpdatescascadedbRelationDeleteCascade Deletionscascade

dbRelationLeftMicrosoftAccessonly.InDesignview,displayaLEFTJOINasthedefaultjointype.

dbRelationRightMicrosoftAccessonly.InDesignview,displayaRIGHTJOINasthedefaultjointype.

ForanyTableDefobject,theAttributespropertymayincludethefollowing:


dbAttachExclusive OpensalinkedMicrosoftJetdatabaseenginetableforexclusiveuse.

dbAttachSavePWD SavesuserIDandpasswordforlinkedremotetable.

dbSystemObject SystemtabledbHiddenObject Hiddentable(fortemporaryuse)dbAttachedTable Linkednon-ODBCdatabasetabledbAttachedODBC LinkedODBCdatabasetable

CollatingOrderPropertyConstants(AllAre )


dbSortArabic ArabiccollatingorderdbSortChineseSimplified SimplifiedChinesecollatingorderdbSortChineseTraditional TraditionalChinesecollatingorderdbSortCyrillic RussiancollatingorderdbSortCzech CzechcollatingorderdbSortDutch Dutchcollatingorder

dbSortGeneral English,German,French,andPortuguesecollatingorder

dbSortGreek GreekcollatingorderdbSortHebrew HebrewcollatingorderdbSortHungarian HungariancollatingorderdbSortIcelandic IcelandiccollatingorderdbSortJapanese JapanesecollatingorderdbSortKorean KoreancollatingorderdbSortNeutral NeutralcollatingorderdbSortNorw NorwegianandDanishcollatingorderdbSortPDXIntl Paradoxinternationalcollatingorder

dbSortPDXNor ParadoxNorwegianandDanishcollatingorder

dbSortPDXSwe ParadoxSwedishandFinnishcollatingorder

dbSortPolish PolishcollatingorderdbSortSlovenian SloveniancollatingorderdbSortSpanish SpanishcollatingorderdbSortSwedFin SwedishandFinnishcollatingorderdbSortThai ThaicollatingorderdbSortTurkish TurkishcollatingorderdbSortUndefined Collatingorderundefinedorunknown

DefaultCursorDriverProperty(Allare )


dbUseDefaultCursor(Default)Usesserver-sidecursorsiftheserversupportsthem;otherwiseusestheODBCCursorLibrary.AlwaysusestheODBCCursorLibrary.Thisoptionprovidesbetterperformancefor

dbUseODBCCursor smallresultsets,butdegradesquicklyforlargerresultsets.

dbUseServerCursor

Alwaysusesserver-sidecursors.Formostlargeoperationsthisoptionprovidesbetterperformance,butmightcausemorenetworktraffic.

dbUseClientBatchCursorAlwaysusestheFoxProCursorLibrary.Thisoptionisrequiredforperformingbatchupdates.

dbUseNoCursor

Opensallcursors(thatis,Recordsetobjects)asforward-onlytype,read-only,witharowsetsizeof1.Alsoknownas"cursorlessqueries."

DirectionPropertyConstants(AllAre )


dbParamInput (Default)Passesinformationtotheprocedure.

dbParamInputOutput Passesinformationbothtoandfromtheprocedure.

dbParamOutput ReturnsinformationfromtheprocedureasinanoutputparameterinSQL.

dbParamReturnValue Passesthereturnvaluefromaprocedure.

EditModePropertyConstants(AllAre )

Constant DescriptiondbEditNone Noeditingoperationineffect.dbEditInProgress Editmethodinvoked.dbEditAdd AddNewmethodinvoked.

PermissionsPropertyConstants(Allare )

ForanyContainerobject,thePermissionspropertymayincludethe

following:

Constant DescriptiondbSecNoAccess Deniesuseraccesstotheobject.dbSecFullAccess Allowsuserfullaccesstotheobject.dbSecDelete Allowsusertodeletetheobject.

dbSecReadSec Allowsusertoreadtheobject'ssecurity-relatedinformation.

dbSecWriteSec Allowsusertoalteraccesspermissions.

dbSecWriteOwner AllowsusertochangetheOwnerpropertysetting.

ForanydatabaseContainer,thePermissionspropertymayincludeanyofthefollowing(Allare ):


dbSecDBAdminGivesuserpermissiontomakeadatabasereplicableandchangethedatabasepassword.

dbSecDBCreateAllowsusertocreatenewdatabases(validonlyonthedatabasesContainerobjectinthesystemdatabase).

dbSecDBOpen Allowsusertoopenthedatabase.dbSecDBExclusive Allowsuserexclusiveaccess.

ForanytablesContainer,thePermissionspropertymayincludeanyofthefollowing(Allare ):


dbSecCreate

Allowsusertocreatenewtables(validonlywithaContainerobjectthatrepresentsatableorwiththedatabasesContainerobjectinthesystemdatabase).


dbSecWriteDefAllowsusertomodifyordeletethetabledefinition,includingcolumnandindex

information.

dbSecRetrieveData Allowsusertoretrievedatafromthedocument.

dbSecInsertData Allowsusertoaddrecords.dbSecReplaceData Allowsusertomodifyrecords.dbSecDeleteData Allowsusertodeleterecords.

ForanyDocumentobject,thePermissionspropertymayincludeanyofthefollowing(Allare ):


dbSecCreateAllowsusertocreatenewtables(validonlywithaContainerobjectthatrepresentsatable).

dbSecDBCreateAllowsusertocreatenewdatabases(validonlyonthedatabasesContainerobjectinthesystemdatabase).

dbSecDBOpen Allowsusertoopenthedatabase.dbSecDBExclusive Allowsuserexclusiveaccess.dbSecDelete Allowsusertodeletetheobject.dbSecDeleteData Allowsusertodeleterecords.dbSecFullAccess Allowsuserfullaccesstotheobject.dbSecInsertData Allowsusertoaddrecords.


dbSecReadSec Allowsusertoreadtheobject'ssecurity-relatedinformation.

dbSecReplaceData Allowsusertomodifyrecords.

dbSecRetrieveData Allowsusertoretrievedatafromthedocument.

dbSecWriteDefAllowsusertomodifyordeletethetabledefinition,includingcolumnandindexinformation.

dbSecWriteSec Allowsusertoalteraccesspermissions.

dbSecWriteOwner AllowsusertochangetheOwnerpropertysetting.

PreparePropertyConstants(AllAre )


dbQPrepare (Default)Thestatementisprepared(thatis,theODBCSQLPrepareAPIiscalled).

dbQUnprepare Thestatementisnotprepared(thatis,theODBCSQLExecDirectAPIiscalled).

RecordStatusPropertyConstants(AllAre )


dbDBDeleted Therecordhasbeendeletedlocallyandinthedatabase.

dbDeleted Therecordhasbeendeleted,butnotyetdeletedinthedatabase.

dbRecordModified Therecordhasbeenmodifiedandnotupdatedinthedatabase.

dbRecordNewTherecordhasbeeninsertedwiththeAddNewmethod,butnotyetinsertedintothedatabase.

dbRecordUnmodified (Default)Therecordhasnotbeenmodifiedorhasbeenupdatedsuccessfully.

TypePropertyConstants

ForanyField,Parameter,orPropertyobject,theTypepropertymayincludeanyofthefollwing(Allare ):

Constant DescriptiondbBigInt BigIntegerdata(ODBCDirectonly)dbBinary BinarydatadbBoolean Boolean(True/False)datadbByte Byte(8-bit)datadbChar Characterdata(ODBCDirectonly)dbCurrency CurrencydatadbDate DatevaluedatadbDecimal Decimaldata(ODBCDirectonly)

dbDouble Double-precisionfloating-pointdatadbFloat Floating-pointdata(ODBCDirectonly)dbGUID GUIDdatadbInteger IntegerdatadbLong LongIntegerdatadbLongBinary Binarydata(bitmap)dbMemo Memodata(extendedtext)dbNumeric Numericdata(ODBCDirectonly)dbSingle Single-precisionfloating-pointdatadbText Textdata(variablewidth)dbTime Dataintimeformat(ODBCDirectonly)

dbTimeStamp Dataintimeanddateformat(ODBCDirectonly)

dbVarBinary VariableBinarydata(ODBCDirectonly)

ForanyQueryDefobject,theTypepropertymayincludeanyofthefollowing(Allare ):

Constant DescriptiondbQAction ActionquerydbQAppend Appendquery

dbQCompound Compoundquery(ODBCDirectworkspacesonly)

dbQCrosstab CrosstabquerydbQDDL Data-definitionlanguage(DDL)querydbQDelete DeletequerydbQMakeTable Make-tablequery

dbQProcedure SQLprocedurethatexecutesastoredprocedure(ODBCDirectworkspacesonly)

dbQSelect SelectquerydbQSetOperation SetoperationquerydbQSPTBulk BulkoperationquerydbQSQLPassThrough SQLpass-throughquerydbQUpdate Updatequery

ForanyRecordsetobject,theTypepropertymayincludeanyofthe

following(Allare ):

Constants Description

dbOpenDynamic Opensadynaset-typeRecordset(ODBCDirectworkspacesonly)

dbOpenDynaset Opensadynaset-typeRecordsetdbOpenForwardOnly Opensaforward-onlytypeRecordsetdbOpenSnapshot Opensasnapshot-typeRecordset

dbOpenTable Opensatable-typeRecordset(MicrosoftJetworkspacesonly)

UpdateOptionsPropertyConstants(AllAre )


dbCriteriaKey (Default)Usesjustthekeycolumn(s)inthewhereclause.

dbCriteriaModValues Usesthekeycolumn(s)andallupdatedcolumnsinthewhereclause.

dbCriteriaAllCols Usesthekeycolumn(s)andallthecolumnsinthewhereclause.

dbCriteriaTimeStampUsesjustthetimestampcolumnifavailable(willgeneratearun-timeerrorifnotimestampcolumnisintheresultset).

dbCriteriaDeleteInsert UsesapairofDELETEandINSERTstatementsforeachmodifiedrow.

dbCriteriaUpdate (Default)UsesanUPDATEstatementforeachmodifiedrow.

CompactDatabase,CreateDatabaseMethodsLocaleArgumentConstants(AllAre )


dbLangGeneral English,German,French,Portuguese,Italian,andModernSpanish

dbLangArabic ArabicdbLangChineseSimplified SimplifiedChinesedbLangChineseTraditional TraditionalChinese

dbLangCyrillic RussiandbLangCzech CzechdbLangDutch DutchdbLangGreek GreekdbLangHebrew HebrewdbLangHungarian HungariandbLangIcelandic IcelandicdbLangJapanese JapanesedbLangKorean KoreandbLangNordic NordicdbLangNorwDan NorwegianandDanishdbLangPolish PolishdbLangSlovenian SloveniandbLangSpanish SpanishdbLangSwedFin SwedishandFinnishdbLangThai ThaidbLangTurkish Turkish

CompactDatabaseMethodOptionsArgumentConstants(AllAre )

Constant DescriptiondbDecrypt DecryptsdatabasewhilecompactingdbEncrypt EncryptsdatabasedbVersion10 MicrosoftJetdatabaseengineversion1.0dbVersion11 MicrosoftJetdatabaseengineversion1.1dbVersion20 MicrosoftJetdatabaseengineversion2.0dbVersion30 MicrosoftJetdatabaseengineversion3.0

CreateDatabaseMethodOptionsArgumentConstants(AllAre )

Constant DescriptiondbEncrypt EncryptsdatabasedbVersion10 MicrosoftJetdatabaseengineversion1.0dbVersion11 MicrosoftJetdatabaseengineversion1.1dbVersion20 MicrosoftJetdatabaseengineversion2.0dbVersion30 MicrosoftJetdatabaseengineversion3.0

CreateWorkspaceMethodTypeArgumentConstants

ForanyWorkspaceobjectTypepropertyandDBEngineobjectDefaultTypeproperty,useanyofthefollowing:(AllAre )


dbUseODBC ThenextworkspacecreatedwilluseODBCDirect.

dbUseJet ThenextworkspacecreatedwillusetheMicrosoftJetdatabaseengine.

ExecuteMethodOptionsArgumentConstants(AllAre )


dbDenyWrite Denieswritepermissiontootherusers(MicrosoftJetworkspacesonly).

dbInconsistent Allowsinconsistentupdates(MicrosoftJetworkspacesonly).

dbConsistent Allowsconsistentupdates(MicrosoftJetworkspacesonly).

dbSQLPassThrough

AnSQLpass-through.CausestheSQLstatementtobepassedtoanODBCdatabaseforprocessing(MicrosoftJetworkspacesonly).

dbFailOnError Rollsbackupdatesifanerroroccurs(MicrosoftJetworkspacesonly).

dbSeeChangesGeneratesarun-timeerrorifanotheruserischangingdatayouareediting(MicrosoftJetworkspacesonly).

dbRunAsync Executesthequeryasynchronously(ODBCDirectworkspacesonly).

dbExecDirectExecutesthequerywithoutfirstcallingtheSQLPrepareODBCfunction(ODBCDirectworkspacesonly).

IdleMethodOptionalArgumentConstant(ThisIs )


dbRefreshCache Forcesanypendingwritestodisk,andrefreshesmemoryfromcurrentdiskfiles.

MakeReplicaMethodOptionalArgumentConstants(Allare )

Constant DescriptiondbRepMakePartial Createsapartialreplica.

dbRepMakeReadOnly Makesreplicableelementsofnewdatabaseread-only.

OpenConnectionandOpenDatabaseMethodsOptionArgumentConstants(AllAre )


dbDriverNoPrompt

Thedrivermanagerusestheconnectionstringprovidedinconnect.Ifsufficientinformationisnotprovided,atrappableerrorisreturned.

dbDriverPrompt

ThedrivermanagerdisplaystheODBCDataSourcesdialogbox.Theconnectionstringusedtoestablishtheconnectionisconstructedfromthedatasourcename(DSN)selectedandcompletedbytheuserviathedialogboxes.

dbDriverComplete

IftheconnectionstringprovidedincludestheDSNkeyword,thedrivermanagerusesthestringasprovidedinconnect,otherwiseitbehavesasitdoeswhendbDriverPromptisspecified.

dbDriverCompleteRequired

(Default)BehaveslikedbDriverCompleteexceptthedriverdisablesthecontrolsforanyinformationnotrequiredtocompletetheconnection.

OpenRecordsetMethodTypeArgumentConstants(AllAre )


dbOpenDynamic Opensadynamic-typeRecordset(ODBCDirectworkspacesonly)

dbOpenDynaset Opensadynaset-typeRecordsetdbOpenForwardOnly Opensaforward-onlytypeRecordsetdbOpenSnapshot Opensasnapshot-typeRecordset

dbOpenTable Opensatable-typeRecordset(MicrosoftJetworkspacesonly)

OpenRecordsetMethodLockEditsArgumentConstants(AllAre )


dbPessimisticPessimisticconcurrency.Cursorusesthelowestleveloflockingsufficienttoensuretherecordcanbeupdated.

dbReadOnly Cursorisread-only.Noupdatesareallowed.

dbOptimistic

OptimisticconcurrencybasedonrecordID.CursorcomparesrecordIDinoldandnewrecordstodetermineifchangeshavebeenmadesincetherecordwaslastaccessed.

dbOptimisticValue

Optimisticconcurrencybasedonrecordvalues.Cursorcomparesdatavaluesinoldandnewrecordstodetermineifchangeshavebeenmadesincetherecordwaslastaccessed(ODBCDirectworkspacesonly).

dbOptimisticBatch Enablesbatchoptimisticupdates(ODBCDirectworkspacesonly).

OpenRecordsetMethodOptionsArgumentConstants(AllAre )


dbDenyWritePreventsotherusersfromchangingRecordsetrecords(MicrosoftJetworkspacesonly).

dbDenyReadPreventsotherusersfromreadingRecordsetrecords(table-typeinMicrosoft

Jetworkspacesonly).

dbReadOnly OpenstheRecordsetasread-only(MicrosoftJetworkspacesonly).

dbAppendOnly

Allowsusertoaddnewrecordstothedynaset,butpreventsuserfromreadingexistingrecords(dynaset-typeinMicrosoftJetworkspacesonly).

dbInconsistent

Appliesupdatestoalldynasetfields,evenifotherrecordsareaffected(dynaset-andsnapshot-typeinMicrosoftJetworkspacesonly).

dbConsistent

Appliesupdatesonlytothosefieldsthatwillnotaffectotherrecordsinthedynaset(dynaset-andsnapshot-typeinMicrosoftJetworkspacesonly).

dbSQLPassThroughSendsanSQLstatementtoanODBCdatabase(snapshot-typeinMicrosoftJetworkspacesonly).

dbForwardOnlyCreatesaforward-onlyscrollingsnapshot-typeRecordset(snapshot-typeinMicrosoftJetworkspacesonly).

dbSeeChangesGeneratesarun-timeerrorifanotheruserischangingdatayouareediting(dynaset-typeinMicrosoftJetworkspacesonly).

dbRunAsync Executesthequeryasynchronously(ODBCDirectworkspacesonly).

dbExecDirectExecutesthequerywithoutfirstcallingtheSQLPrepareODBCfunction(ODBCDirectworkspacesonly).

SetOptionMethodParameterConstants(AllAre )

Constant DescriptiondbPageTimeout ThePageTimeoutkeydbSharedAsyncDelay TheSharedAsyncDelaykeydbExclusiveAsyncDelay TheExclusiveAsyncDelaykeydbLockRetry TheLockRetrykeydbUserCommitSync TheUserCommitSynckeydbImplicitCommitSync TheImplicitCommitSynckey

dbMaxBufferSize TheMaxBufferSizekeydbMaxLocksPerFile TheMaxLocksPerFilekeydbLockDelay TheLockDelaykeydbRecycleLVs TheRecycleLVskeydbFlushTransactionTimeout TheFlushTransactionTimeoutkey

SynchronizeMethodExchangeArgumentConstants(AllAre )


dbRepExportChanges Sendschangesfromcurrentdatabasetotargetdatabase.

dbRepImportChanges Receiveschangesfromtargetdatabase.

dbRepImpExpChanges Sendsandreceivesdatainabidirectionalexchange.

dbRepSyncInternet ExchangesdatabetweenfilesconnectedviaanInternetpathway.

UpdateMethodTypeArgumentConstants(AllAre )


dbUpdateRegular (Default)Pendingchangesaren'tcachedandarewrittentodiskimmediately.

dbUpdateBatch Allpendingchangesintheupdatecachearewrittentodisk.

dbUpdateCurrentRecord Onlythecurrentrecord'spendingchangesarewrittentodisk.

CancelUpdateMethodTypeArgumentConstants(AllAre )


dbUpdateRegular (Default)Pendingchangesaren'tcachedandarewrittentodiskimmediately.


DAOObjectsandCollectionsReference

DAOobjectsandcollectionsprovideaframeworkforusingcodetocreateandmanipulatecomponentsofyourdatabasesystem.Objectsandcollectionshavepropertiesthatdescribethecharacteristicsofdatabasecomponentsandmethodsthatyouusetomanipulatethem.Togethertheseobjectsandcollectionsformahierarchicalmodelofyourdatabasestructure,whichyoucancontrolprogrammatically.

Objectsandcollectionsprovidedifferenttypesofcontainmentrelations:Objectscontainzeroormorecollections,allofdifferenttypes;andcollectionscontainzeroormoreobjects,allofthesametype.Althoughobjectsandcollectionsaresimilarentities,thedistinctiondifferentiatesthetwotypesofrelations.

Inthefollowingtable,thetypeofcollectioninthefirstcolumncontainsthetypeofobjectinthesecondcolumn.Thethirdcolumndescribeswhateachtypeofobjectrepresents.

Collection Object Description

Connections Connection

InformationaboutaconnectiontoanODBCdatasource(ODBCDirectworkspacesonly)

Containers Container

Storageforinformationaboutapredefinedobjecttype(MicrosoftJetworkspacesonly)

Databases Database AnopendatabaseTheMicrosoftJetdatabase

None DBEngine engine

Documents DocumentInformationaboutasaved,predefinedobject(MicrosoftJetworkspacesonly)

Errors Error Informationaboutanyerrorsassociatedwiththisobject

Fields FieldAcolumnthatispartofatable,query,index,relation,orrecordset

Groups GroupAgroupofuseraccounts(MicrosoftJetworkspacesonly)

Indexes Index

Predefinedorderinganduniquenessofvaluesinatable(MicrosoftJetworkspacesonly)

Parameters Parameter Aparameterforaparameterquery

Properties Property Abuilt-inoruser-definedproperty

QueryDefs QueryDef Asavedquerydefinition

Recordsets Recordset Therecordsinabasetableorquery

Relations Relation

Arelationshipbetweenfieldsintablesandqueries(MicrosoftJetworkspacesonly)

TableDefs TableDefAsavedtabledefinition(MicrosoftJetworkspacesonly)

Users User Auseraccount(MicrosoftJetworkspacesonly)

Workspaces Workspace AsessionoftheMicrosoftJetdatabaseengine

DAOObjectModelforMicrosoftJetWorkspaces

DAOObjectModelforODBCDirectWorkspaces

ConnectionObject

AConnectionobjectrepresentsaconnectiontoanODBCdatabase(ODBCDirectworkspacesonly).

Remarks

AConnectionisanon-persistentobjectthatrepresentsaconnectiontoaremotedatabase.TheConnectionobjectisonlyavailableinODBCDirectworkspaces(thatis,aWorkspaceobjectcreatedwiththetypeoptionsettodbUseODBC).

NoteCodewrittenforearlierversionsofDAOcancontinuetousetheDatabaseobjectforbackwardcompatibility,butifthenewfeaturesofaConnectionaredesired,youshouldrevisecodetousetheConnectionobject.Tohelpwithcodeconversion,youcanobtainaConnectionobjectreferencefromaDatabasebyreadingtheConnectionpropertyoftheDatabaseobject.Conversely,youcanobtainaDatabaseobjectreferencefromtheConnectionobject’sDatabaseproperty.

ConnectionsCollection

AConnectionscollectioncontainsthecurrentConnectionobjectsofaWorkspaceobject.(ODBCDirectworkspacesonly).

Remarks

WhenyouopenaConnectionobject,itisautomaticallyappendedtotheConnectionscollectionoftheWorkspace.WhenyoucloseaConnectionobjectwiththeClosemethod,itisremovedfromtheConnectionscollection.YoushouldcloseallopenRecordsetobjects

withintheConnectionbeforeclosingit.

AtthesametimeyouopenaConnectionobject,acorrespondingDatabaseobjectiscreatedandappendedtotheDatabasescollectioninthesameWorkspace,andviceversa.Similarly,whenyouclosetheConnection,thecorrespondingDatabaseisdeletedfromtheDatabasescollection,andsoon.

TheNamepropertysettingofaConnectionisastringthatspecifiesthepathofthedatabasefile.TorefertoaConnectionobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Connections(0)

Connections("name")

Connections![name]

NoteYoucanopenthesamedatasourcemorethanonce,creatingduplicatenamesintheConnectionscollection.YoushouldassignConnectionobjectstoobjectvariablesandrefertothembyvariablename.

ConnectionObject,ConnectionsCollectionSummary

ConnectionObject

TheConnectionobjectcontainsthesecollections,methods,andproperties.

Collections

QueryDefs(default)Recordsets

Methods

CancelCloseCreateQueryDefExecuteOpenRecordset

Properties

ConnectDatabaseNameQueryTimeoutRecordsAffected

StillExecutingTransactionsUpdatable

ConnectionsCollection

AConnectionscollectioniscontainedineachODBCDirectWorkspaceobject,andcontainsthismethodandthisproperty:

Method

Refresh

Property

Count

ContainersCollection

AContainerscollectioncontainsalloftheContainerobjectsthataredefinedinadatabase(MicrosoftJetdatabasesonly).

Remarks

EachDatabaseobjecthasaContainerscollectionconsistingofbuilt-inContainerobjects.SomeoftheseContainerobjectsaredefinedbytheMicrosoftJetdatabaseenginewhileothersmaybedefinedbyotherapplications.

ContainerObject

AContainerobjectgroupssimilartypesofDocumentobjectstogether.

Remarks

EachDatabaseobjecthasaContainerscollectionconsistingofbuilt-inContainerobjects.Applicationscandefinetheirowndocumenttypesandcorrespondingcontainers(MicrosoftJetdatabasesonly);however,theseobjectsmaynotalwaysbesupportedthroughDAO.

SomeoftheseContainerobjectsaredefinedbytheMicrosoftJet

databaseenginewhileothersmaybedefinedbyotherapplications.ThefollowingtableliststhenameofeachContainerobjectdefinedbytheMicrosoftJetdatabaseengineandwhattypeofinformationitcontains.

Containername ContainsinformationaboutDatabases SaveddatabasesTables SavedtablesandqueriesRelations Savedrelationships

NoteDon'tconfusetheContainerobjectslistedintheprecedingtablewiththecollectionsofthesamename.TheDatabasesContainerobjectreferstoallsaveddatabaseobjects,buttheDatabasescollectionrefersonlytodatabaseobjectsthatareopeninaparticularworkspace.

EachContainerobjecthasaDocumentscollectioncontainingDocumentobjectsthatdescribeinstancesofbuilt-inobjectsofthetypespecifiedbytheContainer.YoutypicallyuseaContainerobjectasanintermediatelinktotheinformationintheDocumentobject.YoucanalsousetheContainerscollectiontosetsecurityforallDocumentobjectsofagiventype.

WithanexistingContainerobject,youcan:

UsetheNamepropertytoreturnthepredefinednameoftheContainerobject.

UsetheOwnerpropertytosetorreturntheowneroftheContainerobject.TosettheOwnerproperty,youmusthavewritepermissionfortheContainerobject,andyoumustsetthepropertytothenameofanexistingUserorGroupobject.

UsethePermissionsandUserNamepropertiestosetaccesspermissionsfortheContainerobject;anyDocumentobject

createdintheDocumentscollectionofaContainerobjectinheritstheseaccesspermissionsettings.

BecauseContainerobjectsarebuilt-in,youcan'tcreatenewContainerobjectsordeleteexistingones.

TorefertoaContainerobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Containers(0)

Containers("name")

Containers![name]

ContainerObject,ContainersCollectionSummary

ContainerObject

AContainerobjectcontainsnomethods;itcontainsthesecollectionsandproperties.

Collections

Documents(Default)Properties

Properties

AllPermissionsInheritNameOwnerPermissionsUserName

ContainersCollection

AContainerscollectionappearsineachDatabaseobjectofaMicrosoftJetdatabase,andcontainsthismethodandthisproperty.

Method

Refresh

Property

Count

DatabasesCollection

ADatabasescollectioncontainsallopenDatabaseobjectsopenedorcreatedinaWorkspaceobject.

Remarks

WhenyouopenanexistingDatabaseobjectorcreateanewonefroma

Workspace,itisautomaticallyappendedtotheDatabasescollection.WhenyoucloseaDatabaseobjectwiththeClosemethod,itisremovedfromtheDatabasescollectionbutnotdeletedfromdisk.YoushouldcloseallopenRecordsetobjectsbeforeclosingaDatabaseobject.

InaMicrosoftJetworkspace,theNamepropertysettingofadatabaseisastringthatspecifiesthepathofthedatabasefile.InanODBCDirectworkspace,theNamepropertyisthenameofthecorrespondingConnectionobject.

TorefertoaDatabaseobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Databases(0)

Databases("name")

Databases![name]

NoteYoucanopenthesamedatasourceordatabasemorethanonce,creatingduplicatenamesintheDatabasescollection.YoushouldassignDatabaseobjectstoobjectvariablesandrefertothembyvariablename.

DatabaseObject

ADatabaseobjectrepresentsanopendatabase.

Remarks

YouusetheDatabaseobjectanditsmethodsandpropertiestomanipulateanopendatabase.Inanytypeofdatabase,youcan:

UsetheExecutemethodtorunanactionquery.

SettheConnectpropertytoestablishaconnectiontoanODBCdatasource.

SettheQueryTimeoutpropertytolimitthelengthoftimetowaitforaquerytoexecuteagainstanODBCdatasource.

UsetheRecordsAffectedpropertytodeterminehowmanyrecordswerechangedbyanactionquery.

UsetheOpenRecordsetmethodtoexecuteaselectqueryandcreateaRecordsetobject.

UsetheVersionpropertytodeterminewhichversionofadatabaseenginecreatedthedatabase.

WithaMicrosoftJetdatabase(.mdbfile),youcanalsouseothermethods,properties,andcollectionstomanipulateaDatabaseobject,aswellascreate,modify,orgetinformationaboutitstables,queries,andrelationships.Forexample,youcan:

UsetheCreateTableDefandCreateRelationmethodstocreatetablesandrelations,respectively.

UsetheCreatePropertymethodtodefinenewDatabaseproperties.

UsetheCreateQueryDefmethodtocreateapersistentor

temporaryquerydefinition.

UseMakeReplica,Synchronize,andPopulatePartialmethodstocreateandsynchronizefullorpartialreplicasofyourdatabase.

SettheCollatingOrderpropertytoestablishthealphabeticsortingorderforcharacter-basedfieldsindifferentlanguages.

InanODBCDirectworkspace,youcan:

UsetheConnectionpropertytoobtainareferencetotheConnectionobjectthatcorrespondstotheDatabaseobject.

NoteForacompletelistofallmethods,properties,andcollectionsavailableonaDatabaseobjectineitheraMicrosoftJetworkspaceorODBCDirectworkspace,seetheSummarytopic.

YouusetheCreateDatabasemethodtocreateapersistentDatabaseobjectthatisautomaticallyappendedtotheDatabasescollection,therebysavingittodisk.

Youdon'tneedtospecifytheDBEngineobjectwhenyouusetheOpenDatabasemethod.

Openingadatabasewithlinkedtablesdoesn'tautomaticallyestablishlinkstothespecifiedexternalfilesorMicrosoftJet-connectedODBCdatasources.Youmusteitherreferencethetable'sTableDeforFieldobjectsoropenaRecordsetobject.Ifyoucan'testablishlinkstothesetables,atrappableerroroccurs.Youmayalsoneedpermissiontoaccessthedatabase,oranotherusermighthavethedatabaseopenedexclusively.Inthesecases,trappableerrorsoccur.

YoucanalsousetheOpenDatabasemethodtoopenanexternaldatabase(suchasFoxPro,dBASE,andParadox)directlyinsteadofopeningaMicrosoftJetdatabasethathaslinkstoitstables.

NoteOpeningaDatabaseobjectdirectlyonaMicrosoftJet-connectedODBCdatasource,suchasMicrosoftSQLServer,isnotrecommendedbecausequeryperformanceismuchslowerthanwhenusinglinkedtables.However,performanceisnotaproblemwithopeningaDatabaseobjectdirectlyonanexternalISAMdatabasefile,suchasFoxPro,Paradox,andsoforth.

WhenaprocedurethatdeclaresaDatabaseobjecthasexecuted,localDatabaseobjectsareclosedalongwithanyopenRecordsetobjects.Anypendingupdatesarelostandanypendingtransactionsarerolledback,butnotrappableerroroccurs.YoushouldexplicitlycompleteanypendingtransactionsoreditsandcloseRecordsetobjectsandDatabaseobjectsbeforeexitingproceduresthatdeclaretheseobjectvariableslocally.

Whenyouuseoneofthetransactionmethods(BeginTrans,CommitTrans,orRollback)ontheWorkspaceobject,thesetransactionsapplytoalldatabasesopenedontheWorkspacefromwhichtheDatabaseobjectwasopened.Ifyouwanttouseindependenttransactions,youmustfirstopenanadditionalWorkspaceobject,andthenopenanotherDatabaseobjectinthatWorkspaceobject.

NoteYoucanopenthesamedatasourceordatabasemorethanonce,creatingduplicatenamesintheDatabasescollection.YoushouldassignDatabaseobjectstoobjectvariablesandrefertothembyvariablename.

DatabaseObject,DatabasesCollectionSummary

DatabaseObject

ADatabaseobjectcontainsthesecollections,methods,andproperties.

Legend:

FeatureavailableinMicrosoftJetworkspacesonly.

FeatureavailableinODBCDirectworkspacesonly.

Collections

ContainersPropertiesQueryDefsRecordsets(Defaultfor )RelationsTableDefs(Defaultfor )

Methods

CloseCreatePropertyCreateQueryDefCreateRelationCreateTableDefExecute

MakeReplicaNewPasswordOpenRecordsetPopulatePartialSynchronize

Properties

CollatingOrderConnectConnectionDesignMasterIDNameQueryTimeoutRecordsAffectedReplicable(user-defined)ReplicaIDUpdatableV1xNullBehaviorVersion

DatabasesCollection

ADatabasescollectionappearsineachWorkspaceobject,andcontainsthismethodandthisproperty.

Method

Refresh

Property

Count

DBEngineObject

TheDBEngineobjectisthetoplevelobjectintheDAOobjectmodel.

Remarks

TheDBEngineobjectcontainsandcontrolsallotherobjectsinthehierarchyofDAOobjects.Youcan'tcreateadditionalDBEngineobjects,andtheDBEngineobjectisn'tanelementofanycollection.

NoteWhenyoureferenceanODBCdatasourcedirectlythroughDAO,itiscalledan"ODBCDirectworkspace."ThisistodistinguishitfromanODBCdatasourcethatyoureferenceindirectlythroughthe

MicrosoftJetdatabaseengine,usinga"MicrosoftJetworkspace."EachmethodofaccessingODBCdatarequiresoneoftwotypesofWorkspaceobject;youcansettheDefaultTypepropertytochoosethedefaulttypeofWorkspaceobjectthatyouwillcreatefromtheDBEngineobject.TheWorkspacetypeandassociateddatasourcedetermineswhichDAOobjects,methods,andpropertiesyoucanuse.

Withanytypeofdatabaseorconnection,youcan:

UsetheVersionpropertytoobtaintheDAOversionnumber.

UsetheLoginTimeoutpropertytoobtainorsettheODBClogintimeout,andtheRegisterDatabasemethodtoprovideODBCinformationtotheMicrosoftJetdatabaseengine.Youcanusethesefeaturesthesameway,regardlessofwhetheryouconnecttotheODBCdatasourcethroughMicrosoftJetorthroughanODBCDirectworkspace.

UsetheDefaultTypepropertytosetthedefaulttypeofdatabaseconnectionthatsubsequentlycreatedWorkspaceobjectswilluse—eitherMicrosoftJetorODBCDirect.

UsetheDefaultPasswordandDefaultUserpropertiestosettheuseridentificationandpasswordforthedefaultWorkspaceobject.

UsetheCreateWorkspacemethodtocreateanewWorkspaceobject.YoucanuseoptionalargumentstooverridethesettingsoftheDefaultType,DefaultPassword,andDefaultUserproperties.

UsetheOpenDatabasemethodtoopenadatabaseinthedefault

Workspace,andusetheBeginTrans,Commit,andRollbackmethodstocontroltransactionsonthedefaultWorkspace.

UsetheWorkspacescollectiontoreferencespecificWorkspaceobjects.

UsetheErrorscollectiontoexaminedataaccesserrordetails.

OtherpropertiesandmethodsareonlyavailablewhenyouuseDAOwiththeMicrosoftJetdatabaseengine.YoucanusethemtocontroltheMicrosoftJetdatabaseengine,manipulateitsproperties,andperformtasksontemporaryobjectsthataren'telementsofcollections.Forexample,youcan:

UsetheCreateDatabasemethodtocreateanewMicrosoftJetDatabaseobject.

UsetheIdlemethodtoenabletheMicrosoftJetdatabaseenginetocompleteanypendingtasks.

UsetheCompactDatabaseandRepairDatabasemethodstomaintaindatabasefiles.

UsetheIniPathandSystemDBpropertiestospecifythelocationofMicrosoftJetWindowsRegistryinformationandtheMicrosoftJetworkgroupinformationfile,respectively.TheSetOptionmethodallowsyouoverridewindowsregistrysettingsfortheMicrosoftJetdatabaseengine.

AfteryouchangetheDefaultTypeandIniPathpropertysettings,onlysubsequentWorkspaceobjectswillreflectthesechanges.

NoteForacompletelistofallmethods,properties,andcollectionsavailableontheDBEngineobject,seetheSummarytopic.

TorefertoacollectionthatbelongstotheDBEngineobject,ortorefertoamethodorpropertythatappliestothisobject,usethissyntax:

[DBEngine.][collection|method|property]

DBEngineObjectSummary

TheDBEngineobjectcontainsthesecollections,methods,andproperties.

Legend:



Collections

ErrorsPropertiesWorkspaces(Default)

Methods

BeginTransCommitTransCompactDatabaseCreateDatabaseCreateWorkspaceIdleOpenConnectionOpenDatabaseRegisterDatabaseRepairDatabaseRollback

SetOption

Properties

DefaultPasswordDefaultTypeDefaultUserIniPathLoginTimeoutSystemDBVersion

DocumentsCollection

ADocumentscollectioncontainsalloftheDocumentobjectsforaspecifictypeofobject(MicrosoftJetdatabasesonly).

Remarks

EachContainerobjecthasaDocumentscollectioncontainingDocumentobjectsthatdescribeinstancesofbuilt-inobjectsofthetypespecifiedbytheContainer.

TorefertoaDocumentobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Documents(0)

Documents("name")

Documents![name]

DocumentObject

ADocumentobjectincludesinformationaboutoneinstanceofanobject.Theobjectcanbeadatabase,savedtable,query,orrelationship(MicrosoftJetdatabasesonly).

Remarks

EachContainerobjecthasaDocumentscollectioncontainingDocumentobjectsthatdescribeinstancesofbuilt-inobjectsofthetypespecifiedbytheContainer.ThefollowingtableliststhetypeofobjecteachDocumentdescribes,thenameofitsContainerobject,andwhattypeofinformationDocumentcontains.

Document Container ContainsinformationaboutDatabase Databases SaveddatabaseTableorquery Tables SavedtableorqueryRelationship Relations Savedrelationship

NoteDon'tconfusetheContainerobjectslistedintheprecedingtablewiththecollectionsofthesamename.TheDatabasesContainerobjectreferstoallsaveddatabaseobjects,buttheDatabasescollectionrefersonlytodatabaseobjectsthatareopeninaparticularworkspace.

WithaDocumentobject,youcan:

UsetheNamepropertytoreturnthenamethatauserortheMicrosoftJetdatabaseenginegavetotheobjectwhenitwascreated.

UsetheContainerpropertytoreturnthenameoftheContainerobjectthatcontainstheDocumentobject.

UsetheOwnerpropertytosetorreturntheowneroftheobject.TosettheOwnerproperty,youmusthavewritepermissionfortheDocumentobject,andyoumustsetthepropertytothenameofanexistingUserorGroupobject.

UsetheUserNameorPermissionspropertiestosetorreturntheaccesspermissionsofauserorgroupfortheobject.Tosettheseproperties,youmusthavewritepermissionfortheDocumentobject,andyoumustsettheUserNamepropertytothenameofanexistingUserorGroupobject.

UsetheDateCreatedandLastUpdatedpropertiestoreturnthedateandtimewhentheDocumentobjectwascreatedandlastmodified.

BecauseaDocumentobjectcorrespondstoanexistingobject,youcan'tcreatenewDocumentobjectsordeleteexistingones.TorefertoaDocumentobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Documents(0)

Documents("name")

Documents![name]

DocumentObject,DocumentsCollectionSummary

DocumentObject

ADocumentobjectcontainsthiscollection,thismethod,andtheseproperties.

Collection

Properties

Method

CreateProperty

Properties

AllPermissionsContainerDateCreatedKeepLocal(user-defined)LastUpdatedNameOwnerPermissionsReplicable(user-defined)UserName

DocumentsCollection

ADocumentscollectionappearsineachContainerobject,andcontainsthismethodandthisproperty.

Method

Refresh

Property

Count

Dynamic-TypeRecordsetObject

ThisRecordsettyperepresentsaqueryresultsetfromoneormorebasetablesinwhichyoucanadd,change,ordeleterecordsfromarow-returningquery.Further,recordsthatotherusersadd,delete,oreditinthebasetablesalsoappearinyourRecordset.

ThistypeisonlyavailableinODBCDirectworkspaces,andcorrespondstoanODBCdynamiccursor.

Dynaset-TypeRecordsetObjectSummary

Thedynaset-typeRecordsetobjectcontainsthesecollections,methods,andproperties.

Legend:



Collections

Fields(default)PropertiesMethods RestrictionsAddNewCancelCancelUpdateCloneCloseCopyQueryDefDeleteEditFillCacheFindFirstFindLastFindNextFindPreviousGetRows

MoveMoveFirstMoveLastMoveNextMovePreviousNextRecordsetOpenRecordsetRequeryUpdate

Properties

Thefollowingtableindicateswhetherthepropertysettingisread/write,read-only,oronlyavailableineitherMicrosoftJetorODBCDirectworkspaces.

Read-only

Read/write

Properties RestrictionsAbsolutePositionBatchCollisionCountBatchCollisionsBatchSizeBOFBookmarkBookmarkable

CacheSizeMicrosoftJet

ODBCDirect

CacheStartConnectionEditModeEOFFilter

LastModified

LockEdits

NameNoMatchPercentPositionRecordCountRecordStatusRestartableSortStillExecutingTransactionsTypeUpdatableUpdateOptionsValidationRuleValidationText

ErrorsCollection

AnErrorscollectioncontainsallstoredErrorobjects,eachofwhichpertainstoasingleoperationinvolvingDAO.

Remarks

AnyoperationinvolvingDAOobjectscangenerateoneormoreerrors.Aseacherroroccurs,oneormoreErrorobjectsareplacedintheErrorscollectionoftheDBEngineobject.WhenanotherDAOoperationgeneratesanerror,theErrorscollectioniscleared,andthenewsetofErrorobjectsisplacedintheErrorscollection.Thehighest-numberedobjectintheErrorscollection(DBEngine.Errors.Count-1)

correspondstotheerrorreportedbytheMicrosoftVisualBasicforApplications(VBA)Errobject.

DAOoperationsthatdon'tgenerateanerrorhavenoeffectontheErrorscollection.

ElementsoftheErrorscollectionaren'tappendedastheytypicallyarewithothercollections,sotheErrorscollectiondoesn'tsupporttheAppendandDeletemethods.

ThesetofErrorobjectsintheErrorscollectiondescribesoneerror.ThefirstErrorobjectisthelowestlevelerror,thesecondthenexthigherlevel,andsoforth.Forexample,ifanODBCerroroccurswhiletryingtoopenaRecordsetobject,thefirsterrorobjectcontainsthelowestlevelODBCerror;subsequenterrorscontaintheODBCerrorsreturnedbythevariouslayersofODBC.Inthiscase,theODBCdrivermanager,andpossiblythedriveritself,returnseparateErrorobjects.ThelastErrorobjectcontainstheDAOerrorindicatingthattheobjectcouldn'tbeopened.

EnumeratingthespecificerrorsintheErrorscollectionenablesyourerror-handlingroutinestomorepreciselydeterminethecauseandoriginofanerror,andtakeappropriatestepstorecover.

NoteIfyouusetheNewkeywordtocreateanobjectthatcausesanerroreitherbeforeorwhilebeingplacedintotheErrorscollection,thecollectiondoesn'tcontainerrorinformationaboutthatobject,becausethenewobjectisnotassociatedwiththeDBEngineobject.However,theerrorinformationisavailableintheVBAErrobject.

ErrorObject

AnErrorobjectcontainsdetailsaboutdataaccesserrors,eachofwhichpertainstoasingleoperationinvolvingDAO.

Remarks

AnyoperationinvolvingDAOcangenerateoneormoreerrors.Forexample,acalltoanODBCservermightresultinanerrorfromthedatabaseserver,anerrorfromODBC,andaDAOerror.Aseachsucherroroccurs,anErrorobjectisplacedintheErrorscollectionoftheDBEngineobject.AsingleeventcanthereforeresultinseveralErrorobjectsappearingintheErrorscollection.

WhenasubsequentDAOoperationgeneratesanerror,theErrorscollectioniscleared,andoneormorenewErrorobjectsareplacedintheErrorscollection.DAOoperationsthatdon'tgenerateanerrorhavenoeffectontheErrorscollection.

ThesetofErrorobjectsintheErrorscollectiondescribesoneerror.ThefirstErrorobjectisthelowestlevelerror(theoriginatingerror),thesecondthenexthigherlevelerror,andsoforth.Forexample,ifanODBCerroroccurswhiletryingtoopenaRecordsetobject,thefirstErrorobject—Errors(0)—containsthelowestlevelODBCerror;subsequenterrorscontaintheODBCerrorsreturnedbythevariouslayersofODBC.Inthiscase,theODBCdrivermanager,andpossiblythedriveritself,returnseparateErrorobjects.ThelastErrorobject—Errors.Count-1—containstheDAOerrorindicatingthattheobjectcouldn'tbeopened.

EnumeratingthespecificerrorsintheErrorscollectionenablesyourerror-handlingroutinestomorepreciselydeterminethecauseandoriginofanerror,andtakeappropriatestepstorecover.OnbothMicrosoftJetandODBCDirectworkspaces,youcanreadtheErrorobject’spropertiestoobtainspecificdetailsabouteacherror,including:

TheDescriptionproperty,whichcontainsthetextoftheerroralertthatwillbedisplayedonthescreeniftheerrorisnottrapped.

TheNumberproperty,whichcontainstheLongintegervalueoftheerrorconstant.

TheSourceproperty,whichidentifiestheobjectthatraisedtheerror.ThisisparticularlyusefulwhenyouhaveseveralErrorobjectsintheErrorscollectionfollowingarequesttoanODBCdatasource.

TheHelpFileandHelpContextproperties,whichindicatethe

appropriateMicrosoftWindowsHelpfileandHelptopic,respectively,(ifanyexist)fortheerror.

NoteWhenprogramminginMicrosoftVisualBasicforApplications(VBA),ifyouusetheNewkeywordtocreateanobjectthatsubsequentlycausesanerrorbeforethatobjecthasbeenappendedtoacollection,theDBEngineobject'sErrorscollectionwon'tcontainanentryforthatobject'serror,becausethenewobjectisnotassociatedwiththeDBEngineobject.However,theerrorinformationisavailableintheVBAErrobject.

YourVBAerror-handlingcodeshouldexaminetheErrorscollectionwheneveryouanticipateadataaccesserror.Ifyouarewritingacentralizederrorhandler,testtheVBAErrobjecttodetermineiftheerrorinformationintheErrorscollectionisvalid.IftheNumberpropertyofthelastelementoftheErrorscollection(DBEngine.Errors.Count-1)andthevalueoftheErrobjectmatch,youcanthenuseaseriesofSelectCasestatementstoidentifytheparticularDAOerrororerrorsthatoccurred.Iftheydonotmatch,usetheRefreshmethodontheErrorscollection.

ErrorObject,ErrorsCollectionSummary

ErrorObject

AnErrorobjectcontainsnomethods;nocollections,andtheseproperties:

Properties

DescriptionHelpContextHelpFileNumberSource

ErrorsCollection

AnErrorscollectionappearsintheDBEngineobject,andcontainsthismethodandthisproperty:

Method

Refresh

Property

Count

FieldsCollection

AFieldscollectioncontainsallstoredFieldobjectsofanIndex,QueryDef(MicrosoftJetworkspacesonly),Recordset,Relation,orTableDefobject.

Remarks

TheFieldscollectionsoftheIndex,QueryDef,Relation,andTableDef

objectscontainthespecificationsforthefieldsthoseobjectsrepresent.TheFieldscollectionofaRecordsetobjectrepresentstheFieldobjectsinarowofdata,orinarecord.YouusetheFieldobjectsinaRecordsetobjecttoreadandtosetvaluesforthefieldsinthecurrentrecordoftheRecordsetobject.

TorefertoaFieldobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Fields(0)

Fields("name")

Fields![name]

Withthesamesyntaxforms,youcanalsorefertotheValuepropertyofaFieldobjectthatyoucreateandappendtoaFieldscollection.ThecontextofthefieldreferencewilldeterminewhetheryouarereferringtotheFieldobjectortheValuepropertyoftheFieldobject.

FieldObject

AFieldobjectrepresentsacolumnofdatawithacommondatatypeandacommonsetofproperties.

Remarks

TheFieldscollectionsofIndex,QueryDef,Relation,andTableDefobjectscontainthespecificationsforthefieldsthoseobjectsrepresent.

TheFieldscollectionofaRecordsetobjectrepresentstheFieldobjectsinarowofdata,orinarecord.YouusetheFieldobjectsinaRecordsetobjecttoreadandsetvaluesforthefieldsinthecurrentrecordoftheRecordsetobject.

InbothMicrosoftJetandODBCDirectworkspaces,youmanipulateafieldusingaFieldobjectanditsmethodsandproperties.Forexample,youcan:

UsetheOrdinalPositionpropertytosetorreturnthepresentationorderoftheFieldobjectinaFieldscollection.(Thispropertyisread-onlyforODBCDirectdatabases.)

UsetheValuepropertyofafieldinaRecordsetobjecttosetorreturnstoreddata.

UsetheAppendChunkandGetChunkmethodsandtheFieldSizepropertytogetorsetavalueinanOLEObjectorMemofieldofaRecordsetobject.

UsetheType,Size,andAttributespropertiestodeterminethetypeofdatathatcanbestoredinthefield.

UsetheSourceFieldandSourceTablepropertiestodeterminetheoriginalsourceofthedata.

InMicrosoftJetworkspaces,youcan:

UsetheForeignNamepropertytosetorreturninformationaboutaforeignfieldinaRelationobject.

UsetheAllowZeroLength,DefaultValue,Required,ValidateOnSet,ValidationRule,orValidationTextpropertiestosetorreturnvalidationconditions.

UsetheDefaultValuepropertyofafieldonaTableDefobjecttosetthedefaultvalueforthisfieldwhennewrecordsareadded.

InODBCDirectworkspaces,youcan:

UsetheValue,VisibleValue,andOriginalValuepropertiestoverifysuccessfulcompletionofabatchupdate.

NoteForacompletelistofallmethods,properties,andcollectionsavailableonaFieldobjectinanydatabaseorconnection,seetheSummarytopic.

TocreateanewFieldobjectinanIndex,TableDef,orRelationobject,usetheCreateFieldmethod.

WhenyouaccessaFieldobjectaspartofaRecordsetobject,datafromthecurrentrecordisvisibleintheFieldobject'sValueproperty.TomanipulatedataintheRecordsetobject,youdon'tusuallyreferencetheFieldscollectiondirectly;instead,youindirectlyreferencetheValuepropertyoftheFieldobjectintheFieldscollectionoftheRecordsetobject.

TorefertoaFieldobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Fields(0)

Fields("name")

Fields![name]

Withthesamesyntaxforms,youcanalsorefertotheValuepropertyofaFieldobjectthatyoucreateandappendtoaFieldscollection.The

contextofthefieldreferencewilldeterminewhetheryouarereferringtotheFieldobjectortheValuepropertyoftheFieldobject.

FieldObject,FieldsCollectionSummary

FieldObject

AFieldobjectcontainsthiscollection,thesemethods,andtheseproperties.

Legend:



Collection

Properties

Methods

ThefollowingtablelistsalloftheFieldobjectmethods.ThetypeofobjectwhoseFieldscollectioncontainstheFieldobjectdetermineswhichmethodsareavailable.

Method Index QueryDef Recordset Relation TableDefAppendChunkCreatePropertyGetChunk

Properties

ThefollowingtablelistsalloftheFieldobjectproperties.ThetypeofobjectwhoseFieldscollectioncontainstheFieldobjectdetermineswhichpropertiesareavailable.Allpropertiesareread-onlyforFieldobjectsappendedtoFieldscollectionsofIndex,Relation,andTableDefobjects.

Read-only

Read/write

Property Index QueryDef Recordset Relation TableDefAllowZeroLength AttributesCollatingOrderDataUpdatableDefaultValueFieldSizeForeignNameNameOrdinalPositionOriginalValue *RequiredSizeSourceFieldSourceTableTypeValidateOnSetValidationRuleValidationTextValueVisibleValue *

*ThesepropertiesareonlyavailableinanODBCDirectworkspacewhoseDefaultCursorDriverpropertyissettodbUseClientBatchCursor.

FieldsCollection

AFieldscollectionappearsineachoftheTableDef,QueryDef,Recordset,Relation,andIndexobjects,andcontainsthesemethodsandthisproperty.

Method Index QueryDefRecordset Relation TableDefAppendDeleteRefresh

Property Index QueryDefRecordset Relation TableDefCount

Forward-Only–TypeRecordsetObject

ThisRecordsettypeisidenticaltoasnapshotexceptthatyoucanonlyscrollforwardthroughitsrecords.Thisimprovesperformanceinsituationswhereyouonlyneedtomakeasinglepassthrougharesultset.

InanODBCDirectworkspace,thistypecorrespondstoanODBCforward-onlycursor.

Forward-Only–TypeRecordsetObjectSummary

Theforward-onlytypeRecordsetobjectcontainsthesecollections,methods,andproperties.

Legend:



Collections

Fields(default)PropertiesMethods RestrictionsAddNewCancelCancelUpdateCloseCopyQueryDefDeleteEditGetRows

Move Onlywithforwardmovesthatdon'tuseabookmarkoffset.

MoveNextNextRecordsetRequeryUpdate

Properties

Thefollowingtableindicateswhethereachpropertysettingisread/write,read-only,oralwaysFalseineitherMicrosoftJetorODBCDirectworkspaces.

Read-only

Read/write

Properties RestrictionsBatchCollisionCountBatchCollisionsBatchSizeBOFConnectionEOFFilterNameRecordCountRecordStatusRestartableStillExecutingTransactions AlwaysFalseTypeUpdatable FalseUpdateOptionsValidationRuleValidationText

GroupsCollection

AGroupscollectioncontainsallstoredGroupobjectsofaWorkspaceoruseraccount(MicrosoftJetworkspacesonly).

Remarks

YoucanappendanexistingGroupobjecttotheGroupscollectioninaUserobjecttoestablishmembershipofauseraccountinthatGroupobject.Alternatively,youcanappendaUserobjecttotheUserscollectioninaGroupobjecttogiveauseraccounttheglobal

permissionsofthatgroup.Ineithercase,theexistingGroupobjectmustalreadybeamemberoftheGroupscollectionofthecurrentWorkspaceobject.IfyouuseaGroupsorUserscollectionotherthantheonetowhichyoujustappendedanobject,youmayneedtousetheRefreshmethodtorefreshthecollectionwithcurrentinformationfromthedatabase.

TorefertoaGroupobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Groups(0)

Groups("name")

Groups![name]

GroupObject

AGroupobjectrepresentsagroupofuseraccountsthathavecommonaccesspermissionswhenaWorkspaceobjectoperatesasasecureworkgroup.(MicrosoftJetworkspacesonly).

Remarks

YoucreateGroupobjectsandthenusetheirnamestoestablishandenforceaccesspermissionsforyourdatabases,tables,andqueriesusingtheDocumentobjectsthatrepresenttheDatabase,TableDef,and

QueryDefobjectswithwhichyou'reworking.

WiththepropertiesofaGroupobject,youcan:

UsetheNamepropertyofanexistingGroupobjecttoreturnitsname.Youcan'treturnthePIDpropertysettingofanexistingGroupobject.

UsetheNameandPIDpropertiesofanewlycreated,unappendedGroupobjecttosettheidentityofthatGroupobject.

YoucanappendanexistingGroupobjecttotheGroupscollectioninaUserobjecttoestablishmembershipofauseraccountinthatGroupobject.Alternatively,youcanappendaUserobjecttotheUserscollectioninaGroupobjecttogiveauseraccounttheglobalpermissionsofthatgroup.IfyouuseaGroupsorUserscollectionotherthantheonetowhichyoujustappendedanobject,youmayneedtousetheRefreshmethodtorefreshthecollectionwithcurrentinformationfromthedatabase.

TheMicrosoftJetdatabaseenginepredefinesthreeGroupobjectsnamedAdmins,Users,andGuests.TocreateanewGroupobject,usetheCreateGroupmethodonaUserorWorkspaceobject.

TorefertoaGroupobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Groups(0)

Groups("name")

Groups![name]

GroupObject,GroupsCollectionSummary

GroupObject

AGroupobjectcontainsthesecollections,thismethod,andtheseproperties.

Collections

PropertiesUsers(default)

Method

CreateUser

Properties

NamePID

GroupsCollection

AGroupscollectionappearsineachUserandMicrosoftJetWorkspaceobject,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

IndexesCollection

AnIndexescollectioncontainsallthestoredIndexobjectsofaTableDefobject(MicrosoftJetworkspacesonly).

Remarks

Whenyouaccessatable-typeRecordsetobject,usetheobject'sIndexpropertytospecifytheorderofrecords.SetthispropertytotheNamepropertysettingofanexistingIndexobjectintheIndexescollectionofthetheTableDefobjectunderlyingtheRecordsetobject.

NoteYoucanusetheAppendorDeletemethodonanIndexescollectiononlyiftheUpdatablepropertysettingofthecontainingTableDefobjectisTrue.

AfteryoucreateanewIndexobject,youshouldusetheAppendmethodtoaddittotheTableDefobject'sIndexescollection.

ImportantMakesureyourdatacomplieswiththeattributesofyournewindex.Ifyourindexrequiresuniquevalues,makesurethattherearenoduplicatesinexistingdatarecords.Ifduplicatesexist,theMicrosoftJetdatabaseenginecan'tcreatetheindex;atrappableerrorresultswhenyouattempttousetheAppendmethodonthenewindex.

IndexObject

Indexobjectsspecifytheorderofrecordsaccessedfromdatabasetablesandwhetherornotduplicaterecordsareaccepted,providingefficientaccesstodata.Forexternaldatabases,Indexobjectsdescribetheindexesestablishedforexternaltables(MicrosoftJetworkspacesonly).

Remarks

TheMicrosoftJetdatabaseengineusesindexeswhenitjoinstablesandcreatesRecordsetobjects.Indexesdeterminetheorderinwhichtable-

typeRecordsetobjectsreturnrecords,buttheydon'tdeterminetheorderinwhichtheMicrosoftJetdatabaseenginestoresrecordsinthebasetableortheorderinwhichanyothertypeofRecordsetobjectreturnsrecords.

WithanIndexobject,youcan:

UsetheRequiredpropertytodeterminewhethertheFieldobjectsintheindexrequirevaluesthatarenotNull,andthenusetheIgnoreNullspropertytodeterminewhethertheNullvalueshaveindexentries.

UsethePrimaryandUniquepropertiestodeterminetheorderinganduniquenessoftheIndexobject.

TheMicrosoftJetdatabaseenginemaintainsallbasetableindexesautomatically.Itupdatesindexeswheneveryouadd,change,ordeleterecordsfromthebasetable.Onceyoucreatethedatabase,usetheCompactDatabasemethodperiodicallytobringindexstatisticsup-to-date.

Whenaccessingatable-typeRecordsetobject,youspecifytheorderofrecordsusingtheobject'sIndexproperty.SetthispropertytotheNamepropertysettingofanexistingIndexobjectintheIndexescollection.ThiscollectioniscontainedbytheTableDefobjectunderlyingtheRecordsetobjectthatyou'repopulating.

NoteYoudon'thavetocreateindexesforatable,butforlarge,unindexedtables,accessingaspecificrecordorprocessingjoinscantakealongtime.Conversely,havingtoomanyindexescanslowdownupdatestothedatabaseaseachofthetableindexesisamended.

TheAttributespropertyofeachFieldobjectintheindexdeterminestheorderofrecordsreturnedandconsequentlydetermineswhichaccesstechniquestouseforthatindex.

EachFieldobjectintheFieldscollectionofanIndexobjectisacomponentoftheindex.TodefineanewIndexobject,setitspropertiesbeforeyouappendittoacollection,makingtheIndexobjectavailableforsubsequentuse.

NoteYoucanmodifytheNamepropertysettingofanexistingIndexobjectonlyiftheUpdatablepropertysettingofthecontainingTableDefobjectisTrue.

Whenyousetaprimarykeyforatable,theMicrosoftJetdatabaseengineautomaticallydefinesitastheprimaryindex.Aprimaryindexconsistsofoneormorefieldsthatuniquelyidentifyallrecordsinatableinapredefinedorder.Becausetheprimaryindexfieldmustbeunique,theMicrosoftJetdatabaseengineautomaticallysetstheUniquepropertyoftheprimaryIndexobjecttoTrue.Iftheprimaryindexconsistsofmorethanonefield,eachfieldcancontainduplicatevalues,butthecombinationofvaluesfromalltheindexedfieldsmustbeunique.Aprimaryindexconsistsofakeyforthetableandisalwaysmadeupofthesamefieldsastheprimarykey.

ImportantMakesureyourdatacomplieswiththeattributesofyournewindex.Ifyourindexrequiresuniquevalues,makesurethattherearenoduplicatesinexistingdatarecords.Ifduplicatesexist,theMicrosoftJetdatabaseenginecan'tcreatetheindex;atrappableerrorresultswhenyouattempttousetheAppendmethodonthenewindex.

Whenyoucreatearelationshipthatenforcesreferentialintegrity,theMicrosoftJetdatabaseengineautomaticallycreatesanindexwiththeForeignproperty,setastheforeignkeyinthereferencingtable.Afteryou'veestablishedatablerelationship,theMicrosoftJetdatabaseenginepreventsadditionsorchangestothedatabasethatviolatethatrelationship.IfyousettheAttributespropertyoftheRelationobjecttoallowcascadingupdatesandcascadingdeletes,theMicrosoftJetdatabaseengineupdatesordeletesrecordsinrelatedtablesautomatically.

TocreateanewIndexobject

1. UsetheCreateIndexmethodonaTableDefobject.

2. UsetheCreateFieldmethodontheIndexobjecttocreateaFieldobjectforeachfield(column)tobeincludedintheIndexobject.

3. SetIndexpropertiesasneeded.

4. AppendtheFieldobjecttotheFieldscollection.

5. AppendtheIndexobjecttotheIndexescollection.

NoteTheClusteredpropertyisignoredfordatabasesthatusetheMicrosoftJetdatabaseengine,whichdoesn'tsupportclusteredindexes.

IndexObject,IndexesCollectionSummary

IndexObject

AnIndexobjectcontainsthesecollections,methods,andproperties.

Collections

Fields(default)Properties

Methods

CreateFieldCreateProperty

Properties

ClusteredDistinctCountForeignIgnoreNullsNamePrimaryRequiredUnique

IndexesCollection

AnIndexescollectionappearsineachTableDefobject,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

ParametersCollection

AParameterscollectioncontainsalltheParameterobjectsofaQueryDefobject.

Remarks

TheParameterscollectionprovidesinformationonlyaboutexistingparameters.Youcan'tappendobjectstoordeleteobjectsfromtheParameterscollection.

ParameterObject

AParameterobjectrepresentsavaluesuppliedtoaquery.TheparameterisassociatedwithaQueryDefobjectcreatedfromaparameterquery.

Remarks

ParameterobjectsallowyoutochangetheargumentsinafrequentlyrunQueryDefobjectwithouthavingtorecompilethequery.

UsingthepropertiesofaParameterobject,youcansetaqueryparameterthatcanbechangedbeforethequeryisrun.Youcan:

UsetheNamepropertytoreturnthenameofaparameter.

UsetheValuepropertytosetorreturntheparametervaluestobeusedinthequery.

UsetheTypepropertytoreturnthedatatypeoftheParameterobject.

UsetheDirectionpropertytosetorreturnwhethertheparameterisaninputparameter,anoutputparameter,orboth.

InanODBCDirectworkspace,youcanalso:

ChangethesettingoftheTypeproperty.DoingsowillalsocleartheValueproperty.

UsetheDirectionpropertytosetorreturnwhethertheparameterisaninputparameter,anoutputparameter,orboth.

ParameterObject,ParametersCollectionSummary

ParameterObject

AParameterobjectcontainsnomethods;itcontainsthiscollectionandtheseproperties.

Legend:


Collection

Properties

Properties

DirectionNameTypeValue(Default)

ParametersCollection

AParameterscollectionappearsineachQueryDefobjectandcontainsthismethodandthisproperty.

Method

Refresh

Property

Count

PropertiesCollection

APropertiescollectioncontainsallthePropertyobjectsforaspecificinstanceofanobject.

Remarks

EveryDAOobjectexcepttheConnectionandErrorobjectscontainsaPropertiescollection,whichhascertainbuilt-inPropertyobjects.ThesePropertyobjects(whichareoftenjustcalledproperties)uniquelycharacterizethatinstanceoftheobject.

Inadditiontothebuilt-inproperties,youcanalsocreateandaddyour

ownuser-definedproperties.Toaddauser-definedpropertytoanexistinginstanceofanobject,firstdefineitscharacteristicswiththeCreatePropertymethod,thenaddittothecollectionwiththeAppendmethod.Referencingauser-definedPropertyobjectthathasnotyetbeenappendedtoaPropertiescollectionwillcauseanerror,aswillappendingauser-definedPropertyobjecttoaPropertiescollectioncontainingaPropertyobjectofthesamename.

YoucanusetheDeletemethodtoremoveuser-definedpropertiesfromthePropertiescollection,butyoucan'tremovebuilt-inproperties.

NoteAuser-definedPropertyobjectisassociatedonlywiththespecificinstanceofanobject.Thepropertyisn'tdefinedforallinstancesofobjectsoftheselectedtype.

YoucanusethePropertiescollectionofanobjecttoenumeratetheobject'sbuilt-inanduser-definedproperties.Youdon'tneedtoknowbeforehandexactlywhichpropertiesexistorwhattheircharacteristics(NameandTypeproperties)aretomanipulatethem.However,ifyoutrytoreadawrite-onlyproperty,suchasthePasswordpropertyofaWorkspaceobject,ortrytoreadorwriteapropertyinaninappropriatecontext,suchastheValuepropertysettingofaFieldobjectintheFieldscollectionofaTableDefobject,anerroroccurs.

Torefertoabuilt-inPropertyobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

object.Properties(0)

object.Properties("name")

object.Properties![name]

Forabuilt-inproperty,youcanalsousethissyntax:

object.name

NoteForauser-definedproperty,youmustusethefullobject.Properties("name")syntax.

Withthesamesyntaxforms,youcanalsorefertotheValuepropertyofaPropertyobject.ThecontextofthereferencewilldeterminewhetheryouarereferringtothePropertyobjectitselfortheValuepropertyofthePropertyobject.

PropertyObject

APropertyobjectrepresentsabuilt-inoruser-definedcharacteristicofaDAOobject.

Remarks

EveryDAOobjectexcepttheConnectionandErrorobjectscontainsaPropertiescollectionwhichhasPropertyobjectscorrespondingtobuilt-inpropertiesofthatDAOobject.TheusercanalsodefinePropertyobjectsandappendthemtothePropertiescollectionofsomeDAOobjects.ThesePropertyobjects(whichareoftenjustcalledproperties)uniquelycharacterizethatinstanceoftheobject.

Youcancreateuser-definedpropertiesforthefollowingobjects:

Database,Index,QueryDef,andTableDefobjects

FieldobjectsinFieldscollectionsofQueryDefandTableDefobjects

Toaddauser-definedproperty,usetheCreatePropertymethodtocreateaPropertyobjectwithauniqueNamepropertysetting.SettheTypeandValuepropertiesofthenewPropertyobject,andthenappendittothePropertiescollectionoftheappropriateobject.Theobjecttowhichyouareaddingtheuser-definedpropertymustalreadybeappendedtoacollection.Referencingauser-definedPropertyobjectthathasnotyetbeenappendedtoaPropertiescollectionwillcauseanerror,aswillappendingauser-definedPropertyobjecttoaPropertiescollectioncontainingaPropertyobjectofthesamename.

Youcandeleteuser-definedpropertiesfromthePropertiescollection,butyoucan'tdeletebuilt-inproperties.

NoteAuser-definedPropertyobjectisassociatedonlywiththespecificinstanceofanobject.Thepropertyisn'tdefinedforallinstancesofobjectsoftheselectedtype.

YoucanusethePropertiescollectionofanobjecttoenumeratetheobject'sbuilt-inanduser-definedproperties.Youdon'tneedtoknowbeforehandexactlywhichpropertiesexistorwhattheircharacteristics(NameandTypeproperties)aretomanipulatethem.However,ifyoutrytoreadawrite-onlyproperty,suchasthePasswordpropertyofaWorkspaceobject,ortrytoreadorwriteapropertyinaninappropriatecontext,suchastheValuepropertysettingofaFieldobjectintheFieldscollectionofaTableDefobject,anerroroccurs.

ThePropertyobjectalsohasfourbuilt-inproperties:

TheNameproperty,aStringthatuniquelyidentifiestheproperty.

TheTypeproperty,anIntegerthatspecifiesthepropertydatatype.

TheValueproperty,aVariantthatcontainsthepropertysetting.

TheInheritedproperty,aBooleanthatindicateswhetherthepropertyisinheritedfromanotherobject.Forexample,aFieldobjectinaFieldscollectionofaRecordsetobjectcaninheritpropertiesfromtheunderlyingTableDeforQueryDefobject.

Torefertoabuilt-inPropertyobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

object.Properties(0)

object.Properties("name")

object.Properties![name]

Forabuilt-inproperty,youcanalsousethissyntax:

object.name

NoteForauser-definedproperty,youmustusethefullobject.Properties("name")syntax.

Withthesamesyntaxforms,youcanalsorefertotheValuepropertyofaPropertyobject.ThecontextofthereferencewilldeterminewhetheryouarereferringtothePropertyobjectitselfortheValuepropertyofthePropertyobject.

PropertyObject,PropertiesCollectionSummary

PropertyObject

APropertyobjectcontainsnomethods;itcontainsthiscollectionandtheseproperties.

Collection

Properties

Properties

Inherited(AlwaysFalseinODBCDirectdatabases)NameTypeValue

PropertiesCollection

APropertiescollectionappearsineachoftheotherDAOobjectsexcepttheConnectionandErrorobjects,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

QueryDefsCollection

AQueryDefscollectioncontainsallQueryDefobjectsofaDatabaseobjectinaMicrosoftJetdatabase,andallQueryDefobjectsofaConnectionobjectinanODBCDirectworkspace.

Remarks

TocreateanewQueryDefobject,usetheCreateQueryDefmethod.InaMicrosoftJetworkspace,ifyousupplyastringforthenameargumentor

ifyouexplicitlysettheNamepropertyofthenewQueryDefobjecttoanon–zero-lengthstring,youwillcreateapermanentQueryDefthatwillautomaticallybeappendedtotheQueryDefscollectionandsavedtodisk.Supplyingazero-lengthstringasthenameargumentorexplicitlysettingtheNamepropertytoazero-lengthstringwillresultinatemporaryQueryDefobject.

InanODBCDirectworkspace,aQueryDefisalwaystemporary.TheQueryDefscollectioncontainsallopenQueryDefobjects.WhenaQueryDefisclosed,itisautomaticallyremovedfromtheQueryDefscollection.

TorefertoaQueryDefobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

QueryDefs(0)

QueryDefs("name")

QueryDefs![name]

YoucanrefertotemporaryQueryDefobjectsonlybytheobjectvariablesthatyouhaveassignedtothem.

QueryDefObject

AQueryDefobjectisastoreddefinitionofaqueryinaMicrosoftJetdatabase,oratemporarydefinitionofaqueryinanODBCDirectworkspace.

Remarks

YoucanusetheQueryDefobjecttodefineaquery.Forexample,youcan:

UsetheSQLpropertytosetorreturnthequerydefinition.

UsetheQueryDefobject'sParameterscollectiontosetorreturnqueryparameters.

UsetheTypepropertytoreturnavalueindicatingwhetherthequeryselectsrecordsfromanexistingtable,makesanewtable,insertsrecordsfromonetableintoanothertable,deletesrecords,orupdatesrecords.

UsetheMaxRecordspropertytolimitthenumberofrecordsreturnedfromaquery.

UsetheODBCTimeoutpropertytoindicatehowlongtowaitbeforethequeryreturnsrecords.TheODBCTimeoutpropertyappliestoanyquerythataccessesODBCdata.

InaMicrosoftJetworkspace,youcanalso:

UsetheReturnsRecordspropertytoindicatethatthequeryreturnsrecords.TheReturnsRecordspropertyisonlyvalidonSQLpass-throughqueries.

UsetheConnectpropertytomakeanSQLpass-throughquerytoanODCdatabase.

InanODBCDirectworkspace,youcanalso:

UsethePreparepropertytodeterminewhethertoinvoketheODBCSQLPrepareAPIwhenthequeryisexecuted.

UsetheCacheSizepropertytocacherecordsreturnedfromaquery.

YoucanalsocreatetemporaryQueryDefobjects.UnlikepermanentQueryDefobjects,temporaryQueryDefobjectsarenotsavedtodiskorappendedtotheQueryDefscollection.TemporaryQueryDefobjectsareusefulforqueriesthatyoumustrunrepeatedlyduringruntimebutdonotnotneedtosavetodisk,particularlyifyoucreatetheirSQLstatementsduringruntime.

YoucanthinkofapermanentQueryDefobjectinaMicrosoftJetworkspacesasacompiledSQLstatement.IfyouexecuteaqueryfromapermanentQueryDefobject,thequerywillrunfasterthanifyouruntheequivalentSQLstatementfromtheOpenRecordsetmethod.ThisisbecausetheMicrosoftJetdatabaseenginedoesn'tneedtocompilethequerybeforeexecutingit.

ThepreferredwaytousethenativeSQLdialectofanexternaldatabaseengineaccessedthroughtheMicrosoftJetdatabaseengineisthroughQueryDefobjects.Forexample,youcancreateaMicrosoftSQLServerqueryandstoreitinaQueryDefobject.Whenyouneedtouseanon-MicrosoftJetdatabaseengineSQLquery,youmustprovideaConnectpropertystringthatpointstotheexternaldatasource.QuerieswithvalidConnectpropertiesbypasstheMicrosoftJetdatabaseengineandpassthequerydirectlytotheexternaldatabaseserverforprocessing.

TocreateanewQueryDefobject,usetheCreateQueryDefmethod.InaMicrosoftJetworkspace,ifyousupplyastringforthenameargumentorifyouexplicitlysettheNamepropertyofthenewQueryDefobjecttoanon–zero-lengthstring,youwillcreateapermanentQueryDefthatwillautomaticallybeappendedtotheQueryDefscollectionandsavedtodisk.Supplyingazero-lengthstringasthenameargumentorexplicitlysettingtheNamepropertytoazero-lengthstringwillresultinatemporaryQueryDefobject.

InanODBCDirectworkspace,aQueryDefisalwaystemporary.TheQueryDefscollectioncontainsallopenQueryDefobjects.Whena

QueryDefisclosed,itisautomaticallyremovedfromtheQueryDefscollection.

TorefertoaQueryDefobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

QueryDefs(0)

QueryDefs("name")

QueryDefs![name]

YoucanrefertotemporaryQueryDefobjectsonlybytheobjectvariablesthatyouhaveassignedtothem.

QueryDefObject,QueryDefsCollectionSummary

QueryDefObject

AQueryDefobjectcontainsthesecollections,methods,andproperties.

Legend:

AvailableonlyinaMicrosoftJetworkspace.

AvailableonlyinanODBCDirectworkspace.

Collections

FieldsParameters(default)Properties

Methods

CancelCloseCreatePropertyExecuteOpenRecordset

Properties

CacheSizeConnectDateCreatedKeepLocalLastUpdatedLogMessagesMaxRecordsNameODBCTimeoutPrepareRecordsAffectedReplicableReturnsRecordsSQLStillExecutingTypeUpdatable

QueryDefsCollection

AQueryDefscollectionappearsineachConnectionobjectinanODBCDirectworkspace,andeachDatabaseobject,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

RecordsetsCollection

ARecordsetscollectioncontainsallopenRecordsetobjectsinaConnectionorDatabaseobject.

Remarks

WhenyouuseDAOobjects,youmanipulatedataalmostentirelyusingRecordsetobjects.

AnewRecordsetobjectisautomaticallyaddedtotheRecordsets

collectionwhenyouopentheRecordsetobject,andisautomaticallyremovedwhenyoucloseit.

YoucancreateasmanyRecordsetobjectvariablesasneeded.DifferentRecordsetobjectscanaccessthesametables,queries,andfieldswithoutconflicting.

TorefertoaRecordsetobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Recordsets(0)

Recordsets("name")

Recordsets![name]

NoteYoucanopenaRecordsetobjectfromthesamedatasourceordatabasemorethanonce,creatingduplicatenamesintheRecordsetscollection.YoushouldassignRecordsetobjectstoobjectvariablesandrefertothembyvariablename.

RecordsetObject

ARecordsetobjectrepresentstherecordsinabasetableortherecordsthatresultfromrunningaquery.

Remarks

YouuseRecordsetobjectstomanipulatedatainadatabaseattherecordlevel.WhenyouuseDAOobjects,youmanipulatedataalmostentirelyusingRecordsetobjects.AllRecordsetobjectsareconstructedusingrecords(rows)andfields(columns).Therearefivetypesof

Recordsetobjects:

Table-typeRecordset—representationincodeofabasetablethatyoucanusetoadd,change,ordeleterecordsfromasingledatabasetable(MicrosoftJetworkspacesonly).

Dynaset-typeRecordset—theresultofaquerythatcanhaveupdatablerecords.Adynaset-typeRecordsetobjectisadynamicsetofrecordsthatyoucanusetoadd,change,ordeleterecordsfromanunderlyingdatabasetableortables.Adynaset-typeRecordsetobjectcancontainfieldsfromoneormoretablesinadatabase.ThistypecorrespondstoanODBCkeysetcursor.

Snapshot-typeRecordset—astaticcopyofasetofrecordsthatyoucanusetofinddataorgeneratereports.Asnapshot-typeRecordsetobjectcancontainfieldsfromoneormoretablesinadatabasebutcan'tbeupdated.ThistypecorrespondstoanODBCstaticcursor.

Forward-only-typeRecordset—identicaltoasnapshotexceptthatnocursorisprovided.Youcanonlyscrollforwardthroughrecords.Thisimprovesperformanceinsituationswhereyouonlyneedtomakeasinglepassthrougharesultset.ThistypecorrespondstoanODBCforward-onlycursor.

Dynamic-typeRecordset—aqueryresultsetfromoneormorebasetablesinwhichyoucanadd,change,ordeleterecordsfromarow-returningquery.Further,recordsotherusersadd,delete,oreditinthebasetablesalsoappearinyourRecordset.ThistypecorrespondstoanODBCdynamiccursor(ODBCDirectworkspacesonly).

YoucanchoosethetypeofRecordsetobjectyouwanttocreateusingthetypeargumentoftheOpenRecordsetmethod.

InaMicrosoftJetworkspace,ifyoudon'tspecifyatype,DAOattemptstocreatethetypeofRecordsetwiththemostfunctionalityavailable,startingwithtable.Ifthistypeisn’tavailable,DAOattemptsadynaset,thenasnapshot,andfinallyaforward-onlytypeRecordsetobject.

InanODBCDirectworkspace,ifyoudon'tspecifyatype,DAOattemptstocreatethetypeofRecordsetwiththefastestqueryresponse,startingwithforward-only.Ifthistypeisn'tavailable,DAOattemptsasnapshot,thenadynaset,andfinallyadynamic-typeRecordsetobject.

WhencreatingaRecordsetobjectusinganon-linkedTableDefobjectinaMicrosoftJetworkspace,table-typeRecordsetobjectsarecreated.Onlydynaset-typeorsnapshot-typeRecordsetobjectscanbecreatedwithlinkedtablesortablesinMicrosoftJet-connectedODBCdatabases.

AnewRecordsetobjectisautomaticallyaddedtotheRecordsetscollectionwhenyouopentheobject,andisautomaticallyremovedwhenyoucloseit.

NoteIfyouusevariablestorepresentaRecordsetobjectandtheDatabaseobjectthatcontainstheRecordset,makesurethevariableshavethesamescope,orlifetime.Forexample,ifyoudeclareapublicvariablethatrepresentsaRecordsetobject,makesurethevariablethatrepresentstheDatabasecontainingtheRecordsetisalsopublic,orisdeclaredinaSuborFunctionprocedureusingtheStatickeyword.

YoucancreateasmanyRecordsetobjectvariablesasneeded.DifferentRecordsetobjectscanaccessthesametables,queries,andfieldswithoutconflicting.

Dynaset-,snapshot-,andforward-only–typeRecordsetobjectsarestoredinlocalmemory.Ifthereisn'tenoughspaceinlocalmemorytostorethedata,theMicrosoftJetdatabaseenginesavestheadditionaldatatoTEMPdiskspace.Ifthisspaceisexhausted,atrappableerror

occurs.

ThedefaultcollectionofaRecordsetobjectistheFieldscollection,andthedefaultpropertyofaFieldobjectistheValueproperty.Usethesedefaultstosimplifyyourcode.

WhenyoucreateaRecordsetobject,thecurrentrecordispositionedtothefirstrecordifthereareanyrecords.Iftherearenorecords,theRecordCountpropertysettingis0,andtheBOFandEOFpropertysettingsareTrue.

YoucanusetheMoveNext,MovePrevious,MoveFirst,andMoveLastmethodstorepositionthecurrentrecord.Forward-only–typeRecordsetobjectssupportonlytheMoveNextmethod.WhenusingtheMovemethodstovisiteachrecord(or"walk"throughtheRecordset),youcanusetheBOFandEOFpropertiestocheckforthebeginningorendoftheRecordsetobject.

Withdynaset-andsnapshot-typeRecordsetobjectsinaMicrosoftJetworkspace,youcanalsousetheFindmethods,suchasFindFirst,tolocateaspecificrecordbasedoncriteria.Iftherecordisn'tfound,theNoMatchpropertyissettoTrue.Fortable-typeRecordsetobjects,youcanscanrecordsusingtheSeekmethod.

TheTypepropertyindicatesthetypeofRecordsetobjectcreated,andtheUpdatablepropertyindicateswhetheryoucanchangetheobject'srecords.

Informationaboutthestructureofabasetable,suchasthenamesanddatatypesofeachFieldobjectandanyIndexobjects,isstoredinaTableDefobject.

TorefertoaRecordsetobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Recordsets(0)

Recordsets("name")

Recordsets![name]

NoteYoucanopenaRecordsetobjectfromthesamedatasourceordatabasemorethanonce,creatingduplicatenamesintheRecordsetscollection.YoushouldassignRecordsetobjectstoobjectvariablesandrefertothembyvariablename.

RecordsetObject,RecordsetsCollectionSummary

RecordsetObject

ARecordsetobjectcontainsthesecollections,methods,andproperties.

Legend:

FeatureavailableinbothMicrosoftJetandODBCDirectworkspaces.



Collections


RecordsetMethods

ThefollowingtablelistsalloftheRecordsetmethods,andshowswhichRecordsettypesupportseachmethod,andwhetherthemethodisavailableineitheraMicrosoftJetorODBCDirectworkspace,orboth.

Method Table Dynaset Snapshot Forward-OnlyDynamicAddNew *CancelCancelUpdate *

CloneCloseCopyQueryDefDelete *Edit *FillCacheFindFirstFindLastFindNextFindPreviousGetRows

Move

Onlywithforwardmovesthatdon'tuseabookmarkoffset

MoveFirstMoveLastMoveNextMovePreviousNextRecordsetOpenRecordsetRequerySeekUpdate *

*InanODBCDirectworkspace,asnapshot-typeRecordsetmaybeupdatable,dependingontheODBCdriver.TheAddNew,Edit,Delete,Update,andCancelUpdatemethodsareonlyavailableonODBCDirectsnapshot-typeRecordsetobjectsiftheODBCdriversupportsupdatablesnapshots.

RecordsetProperties

ThefollowingtableindicateswhichpropertiesapplytoeachtypeofRecordsetobjectandwhetherthepropertysettingisread/write,read-only,oralwaysFalseineitherMicrosoftJetorODBCDirectdatabases.

Read-only

Read/write

Property Table Dynaset Snapshot Forward-Only Dynamic

AbsolutePositionBatchCollisionCountBatchCollisionsBatchSizeBOFBookmarkBookmarkable

CacheSizefor

MicrosoftJetworkspacesfor

ODBCDirectworkspaces

CacheStartConnectionDateCreatedEditModeEOFFilterIndexLastModified *LastUpdated

LockEditsfor

MicrosoftJetworkspaces

forMicrosoftJetworkspaces

forODBCDirectworkspaces

forODBCDirectworkspaces

NameNoMatchPercentPositionRecordCountRecordStatusRestartable False

Sort

StillExecuting

Transactions AlwaysFalse

AlwaysFalse

Type

Updatable

AlwaysFalseinMicrosoftJetworkspaces

AlwaysFalseinMicrosoftJetworkspaces

inODBCDirectworkspaces*

inODBCDirectworkspaces*

UpdateOptionsValidationRuleValidationText

*InanODBCDirectworkspace,asnapshot-typeRecordsetmaybeupdatable,dependingontheODBCdriver.TheLastModifiedpropertyisavailable,andtheUpdatablepropertyisTrueonlyonODBCDirectsnapshot-typeRecordsetobjectsiftheODBCdriversupportsupdatablesnapshots.

RecordsetsCollection

ARecordsetscollectionappearsineachConnectionandDatabaseobject,andcontainsthismethodandthisproperty.

Method

Refresh

Property

Count

RelationsCollection

ARelationscollectioncontainsstoredRelationobjectsofaDatabaseobject(MicrosoftJetdatabasesonly).

Remarks

YoucanusetheRelationobjecttocreatenewrelationshipsandexamineexistingrelationshipsinyourdatabase.ToaddaRelationobjecttotheRelationscollection,firstcreateitwiththeCreateRelationmethod,andthenappendittotheRelationscollectionwiththeAppendmethod.ThiswillsavetheRelationobjectwhenyouclosetheDatabaseobject.To

removeaRelationobjectfromthecollection,usetheDeletemethod.

TorefertoaRelationobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Relations(0)

Relations("name")

Relations![name]

RelationObject

ARelationobjectrepresentsarelationshipbetweenfieldsintablesorqueries(MicrosoftJetdatabasesonly).

Remarks

YoucanusetheRelationobjecttocreatenewrelationshipsandexamineexistingrelationshipsinyourdatabase.

UsingaRelationobjectanditsproperties,youcan:

Specifyanenforcedrelationshipbetweenfieldsinbasetables(butnotarelationshipthatinvolvesaqueryoralinkedtable).

Establishunenforcedrelationshipsbetweenanytypeoftableorquery—nativeorlinked.

UsetheNamepropertytorefertotherelationshipbetweenthefieldsinthereferencedprimarytableandthereferencingforeigntable.

UsetheAttributespropertytodeterminewhethertherelationshipbetweenfieldsinthetableisone-to-oneorone-to-manyandhowtoenforcereferentialintegrity.

UsetheAttributespropertytodeterminewhethertheMicrosoftJetdatabaseenginecanperformcascadingupdateandcascadingdeleteoperationsonprimaryandforeigntables.

UsetheAttributespropertytodeterminewhethertherelationshipbetweenfieldsinthetableisleftjoinorrightjoin.

UsetheNamepropertyofallFieldobjectsintheFieldscollectionofaRelationobjecttosetorreturnthenamesofthefieldsintheprimarykeyofthereferencedtable,ortheForeignNamepropertysettingsoftheFieldobjectstosetorreturnthenamesofthefieldsintheforeignkeyofthereferencingtable.

Ifyoumakechangesthatviolatetherelationshipsestablishedforthe

database,atrappableerroroccurs.Ifyourequestcascadingupdateorcascadingdeleteoperations,theMicrosoftJetdatabaseenginealsomodifiestheprimaryorforeignkeytablestoenforcetherelationshipsyouestablish.

Forexample,theNorthwinddatabasecontainsarelationshipbetweenanOrderstableandaCustomerstable.TheCustomerIDfieldoftheCustomerstableistheprimarykey,andtheCustomerIDfieldoftheOrderstableistheforeignkey.ForMicrosoftJettoacceptanewrecordintheOrderstable,itsearchestheCustomerstableforamatchontheCustomerIDfieldoftheOrderstable.IfMicrosoftJetdoesn'tfindamatch,itdoesn'tacceptthenewrecord,andatrappableerroroccurs.

Whenyouenforcereferentialintegrity,auniqueindexmustalreadyexistforthekeyfieldofthereferencedtable.TheMicrosoftJetdatabaseengineautomaticallycreatesanindexwiththeForeignpropertysettoactastheforeignkeyinthereferencingtable.

TocreateanewRelationobject,usetheCreateRelationmethod.TorefertoaRelationobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

Relations(0)

Relations("name")

Relations![name]

RelationObject,RelationsCollectionSummary

RelationObject

ARelationobjectcontainsthesecollections,thismethod,andtheseproperties.

Collections

Fields(Default)Properties

Method

CreateField

Properties

AttributesForeignTableNamePartialReplicaTable

RelationsCollection

ARelationscollectioniscontainedineachDatabaseobjectofaMicrosoftJetdatabase,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

Snapshot-TypeRecordsetObject

Asnapshot-typeRecordsetobjectisastaticsetofrecordsthatyoucanusetoexaminedatainanunderlyingtableortables.InanODBCDirectdatabase,asnapshot-typeRecordsetobjectcorrespondstoastaticcursor.

Remarks

Tocreateasnapshot-typeRecordsetobject,usetheOpenRecordsetmethodonanopendatabase,onanotherdynaset-orsnapshot-typeRecordsetobject,oronaQueryDefobject.

Asnapshot-typeRecordsetobjectcancontainfieldsfromoneormoretablesinadatabase.InaMicrosoftJetworkspace,asnapshotcan'tbeupdated.InanODBCDirectworkspace,asnapshotmaybeupdatable,

dependingontheODBCdriver.

Whenyoucreateasnapshot-typeRecordsetobject,datavaluesforallfields(exceptMemoandOLEObject(LongBinary)fielddatatypesin.mdbfiles)arebroughtintomemory.Onceloaded,changesmadetobasetabledataaren'treflectedinthesnapshot-typeRecordsetobjectdata.Toreloadthesnapshot-typeRecordsetobjectwithcurrentdata,usetheRequerymethod,orre-executetheOpenRecordsetmethod.

Theorderofsnapshot-typeRecordsetobjectdatadoesn'tnecessarilyfollowanyspecificsequence.Toorderyourdata,useanSQLstatementwithanORDERBYclausetocreatetheRecordsetobject.YoucanalsousethistechniquetofiltertherecordssothatonlycertainrecordsareaddedtotheRecordsetobject.UsingthistechniqueinsteadofusingtheFilterorSortpropertiesortestingeachrecordindividuallygenerallyresultsinfasteraccesstoyourdata.

Snapshot-typeRecordsetobjectsaregenerallyfastertocreateandaccessthandynaset-typeRecordsetobjectsbecausetheirrecordsareeitherinmemoryorstoredinTEMPdiskspace,andtheMicrosoftJetdatabaseenginedoesn'tneedtolockpagesorhandlemultiuserissues.However,snapshot-typeRecordsetobjectsusemoreresourcesthandynaset-typeRecordsetobjectsbecausetheentirerecordisdownloadedtolocalmemory.

Snapshot-TypeRecordsetObjectSummary

Thesnapshot-typeRecordsetobjectcontainsthesecollections,methods,andproperties.

Legend:



Collections

Fields(default)PropertiesMethods RestrictionsAddNew *CancelCancelUpdate *CloneCloseCopyQueryDefDelete *Edit *FindFirstFindLastFindNextFindPreviousGetRowsMove

MoveFirstMoveLastMoveNextMovePreviousNextRecordsetOpenRecordsetRequeryUpdate *

*InanODBCDirectworkspace,asnapshot-typeRecordsetmaybeupdatable,dependingontheODBCdriver.TheAddNew,Edit,Delete,Update,andCancelUpdatemethodsareonlyavailableonODBCDirectsnapshot-typeRecordsetobjectsiftheODBCdriversupportsupdatablesnapshots.

Properties

Thefollowingtableindicateswhetherthepropertysettingisread/write,read-only,oralwaysFalseineitherMicrosoftJetorODBCDirectworkspaces.

Read-only

Read/write

Properties RestrictionsAbsolutePositionBatchCollisionCountBatchCollisionsBatchSizeBOFBookmarkBookmarkableCacheSizeConnectionEditModeEOFFilterLastModified *

LockEdits

NameNoMatchPercentPositionRecordCountRecordStatusRestartableSortStillExecutingTransactions AlwaysFalseType

UpdatableAlwaysFalseinMicrosoftJetworkspaces;inODBCDirectworkspaces*

UpdateOptionsValidationRuleValidationText

*InanODBCDirectworkspace,asnapshot-typeRecordsetmaybeupdatable,dependingontheODBCdriver.TheLastModifiedpropertyisavailable,andtheUpdatablepropertyisTrueonlyonODBCDirectsnapshot-typeRecordsetobjectsiftheODBCdriversupportsupdatablesnapshots.

TableDefsCollection

ATableDefscollectioncontainsallstoredTableDefobjectsinadatabase(MicrosoftJetworkspacesonly).

Remarks

YoumanipulateatabledefinitionusingaTableDefobjectanditsmethodsandproperties.

ThedefaultcollectionofaDatabaseobjectistheTableDefscollection.

TorefertoaTableDefobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

TableDefs(0)

TableDefs("name")

TableDefs![name]

TableDefObject

ATableDefobjectrepresentsthestoreddefinitionofabasetableoralinkedtable(MicrosoftJetworkspacesonly).

Remarks

YoumanipulateatabledefinitionusingaTableDefobjectanditsmethodsandproperties.Forexample,youcan:

Examinethefieldandindexstructureofanylocal,linked,or

externaltableinadatabase.

UsetheConnectandSourceTableNamepropertiestosetorreturninformationaboutlinkedtables,andusetheRefreshLinkmethodtoupdateconnectionstolinkedtables.

UsetheValidationRuleandValidationTextpropertiestosetorreturnvalidationconditions.

UsetheOpenRecordsetmethodtocreateatable-,dynaset-,dynamic-,snapshot-,orforward-only–typeRecordsetobject,basedonthetabledefinition.

Forbasetables,theRecordCountpropertycontainsthenumberofrecordsinthespecifieddatabasetable.Forlinkedtables,theRecordCountpropertysettingisalways-1.

TocreateanewTableDefobject,usetheCreateTableDefmethod.

Toaddafieldtoatable

1. MakesureanyRecordsetobjectsbasedonthetableareallclosed.

2. UsetheCreateFieldmethodtocreateaFieldobjectvariableandsetitsproperties.

3. UsetheAppendmethodtoaddtheFieldobjecttotheFieldscollectionoftheTableDefobject.

YoucandeleteaFieldobjectfromaTableDefscollectionifitdoesn'thaveanyindexesassignedtoit,butyouwilllosethefield'sdata.

Tocreateatablethatisreadyfornewrecordsinadatabase

4. UsetheCreateTableDefmethodtocreateaTableDefobject.

5. Setitsproperties.

6. Foreachfieldinthetable,usetheCreateFieldmethodtocreateaFieldobjectvariableandsetitsproperties.

7. UsetheAppendmethodtoaddthefieldstotheFieldscollectionoftheTableDefobject.

8. UsetheAppendmethodtoaddthenewTableDefobjecttotheTableDefscollectionoftheDatabaseobject.

AlinkedtableisconnectedtothedatabasebytheSourceTableNameandConnectpropertiesoftheTableDefobject.

Tolinkatabletoadatabase

9. UsetheCreateTableDefmethodtocreateaTableDefobject.

10. SetitsConnectandSourceTableNameproperties(andoptionally,itsAttributesproperty).

11. UsetheAppendmethodtoaddittotheTableDefscollectionofaDatabase.

TorefertoaTableDefobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

TableDefs(0)

TableDefs("name")

TableDefs![name]

TableDefObject,TableDefsCollectionSummary

TableDefObject

ATableDefobjectcontainsthesecollections,methods,andproperties.

Collections

Fields(Default)IndexesProperties

Methods

CreateFieldCreateIndexCreatePropertyOpenRecordsetRefreshLink

Properties

AttributesConflictTableConnectDateCreatedKeepLocal(user-defined)LastUpdatedName

RecordCountReplicable(user-defined)ReplicaFilterSourceTableNameUpdatableValidationRuleValidationText

ATableDefobjectmayalsocontainapplication-definedproperties.Fordetailsonreadingandsettingtheseproperties,refertotheapplication'sonlineHelp.

TableDefsCollection

ATableDefscollectioniscontainedineachDatabaseobjectinaMicrosoftJetdatabase,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

Table-TypeRecordsetObject

Atable-typeRecordsetobjectrepresentsabasetableyoucanusetoadd,change,ordeleterecordsfromatable.Onlythecurrentrecordisloadedintomemory.ApredefinedindexdeterminestheorderoftherecordsintheRecordsetobject(MicrosoftJetworkspacesonly).

Remarks

Tocreateatable-typeRecordsetobject,usetheOpenRecordsetmethodonanopenDatabaseobject.

Youcancreateatable-typeRecordsetobjectfromabasetableofaMicrosoftJetdatabase,butnotfromanODBCorlinkedtable.Youcanusethetable-typeRecordsetobjectwithISAMdatabases(likeFoxPro,dBASE,orParadox)whenyouopenthemdirectly.

Unlikedynaset-orsnapshot-typeRecordsetobjects,thetable-typeRecordsetobjectcan'trefertomorethanonebasetable,andyoucan'tcreateitwithanSQLstatementthatfiltersorsortsthedata.Generally,whenyouaccessatable-typeRecordsetobject,youspecifyoneofthepredefinedindexesforthetable,whichordersthedatareturnedtoyourapplication.Ifthetabledoesn'thaveanindex,thedatawon'tnecessarilybeinaparticularorder.Ifnecessary,yourapplicationcancreateanindexthatreturnsrecordsinaspecificorder.Tochooseaspecificorderforyourtable-typeRecordsetobject,settheIndexpropertytoavalidindex.

Alsounlikedynaset-orsnapshot-typeRecordsetobjects,youdon'tneedtoexplicitlypopulatetable-typeRecordsetobjectstoobtainanaccuratevaluefortheRecordCountproperty.

Tomaintaindataintegrity,table-typeRecordsetobjectsarelockedduringtheEditandUpdatemethodsoperationssothatonlyoneusercanupdateaparticularrecordatatime.WhentheMicrosoftJetdatabaseenginelocksarecord,itlockstheentire2Kpagecontainingtherecord.

Twokindsoflockingareusedwithnon-ODBCtables—pessimisticandoptimistic.ODBC-accessedtablesalwaysuseoptimisticlocking.TheLockEditspropertydeterminesthelockingconditionsineffectduringediting.

Table-TypeRecordsetObjectSummary

Atable-typeRecordsetobjectcontainsthesecollections,methods,andproperties.ThistypeofRecordsetanditsmethodsandpropertiesareavailableonlyinaMicrosoftJetworkspace.

Collections


Methods

AddNewCancelUpdateCloneCloseDeleteEditGetRowsMoveMoveFirstMoveLastMoveNextMovePreviousOpenRecordsetSeekUpdate

Properties

Thefollowingtableindicateswhethereachpropertysettingisread/write,read-only,oralwaysFalse.

Read-only

Read/write

Properties RestrictionsBOFBookmarkBookmarkableDateCreatedEditModeEOFIndexLastModifiedLastUpdatedLockEditsNameNoMatchPercentPositionRecordCountRestartable AlwaysFalseTransactionsTypeUpdatableValidationRuleValidationText

UsersCollection

AUserscollectioncontainsallstoredUserobjectsofaWorkspaceorGroupobject(MicrosoftJetworkspacesonly).

Remarks

YoucanappendanexistingUserobjecttotheUserscollectionofaGroupobjecttogiveauseraccounttheaccesspermissionsforthatGroupobject.Alternatively,youcanappendtheGroupobjecttotheGroupscollectioninaUserobjecttoestablishmembershipoftheuser

accountinthatgroup.IfyouuseaUsersorGroupscollectionotherthantheonetowhichyoujustappendedanobject,youmayneedtousetheRefreshmethod.

TheMicrosoftJetdatabaseenginepredefinestwoUserobjectsnamedAdminandGuest.TheuserAdminisamemberofbothoftheGroupobjectsnamedAdminsandUsers;theuserGuestisamemberonlyoftheGroupobjectnamedGuests.

TorefertoaUserobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

[workspace|group].Users(0)

[workspace|group].Users("name")

[workspace|group].Users![name]

UserObject

AUserobjectrepresentsauseraccountthathasaccesspermissionswhenaWorkspaceobjectoperatesasasecureworkgroup(MicrosoftJetworkspacesonly).

Remarks

YouuseUserobjectstoestablishandenforceaccesspermissionsfortheDocumentobjectsthatrepresentdatabases,tables,andqueries.Also,ifyouknowthepropertiesofaspecificUserobject,youcancreate

anewWorkspaceobjectthathasthesameaccesspermissionsastheUserobject.

YoucanappendanexistingUserobjecttotheUserscollectionofaGroupobjecttogiveauseraccounttheaccesspermissionsforthatGroupobject.Alternatively,youcanappendtheGroupobjecttotheGroupscollectioninaUserobjecttoestablishmembershipoftheuseraccountinthatgroup.IfyouuseaUsersorGroupscollectionotherthantheonetowhichyoujustappendedanobject,youmayneedtousetheRefreshmethod.

WiththepropertiesofaUserobject,youcan:

UsetheNamepropertytoreturnthenameofanexistinguser.Youcan'treturnthePIDandPasswordpropertiesofanexistingUserobject.

UsetheName,PID,andPasswordpropertiesofanewlycreated,unappendedUserobjecttoestablishtheidentityofthatUserobject.Ifyoudon'tsetthePasswordproperty,it'ssettoazero-lengthstring("").

TheMicrosoftJetdatabaseenginepredefinestwoUserobjectsnamedAdminandGuest.TheuserAdminisamemberofbothoftheGroupobjectsnamedAdminsandUsers;theuserGuestisamemberonlyoftheGroupobjectnamedGuests.

TocreateanewUserobject,usetheCreateUsermethod.

TorefertoaUserobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

[workspace|group].Users(0)

[workspace|group].Users("name")

[workspace|group].Users![name]

UserObject,UsersCollectionSummary

UserObject

AUserobjectcontainsthesecollections,methods,andproperties.

Collections

Groups(Default)Properties

Methods

CreateGroupNewPassword

Properties

NamePasswordPID

UsersCollection

AUserscollectioniscontainedineachGroupandMicrosoftJetWorkspaceobject,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

WorkspacesCollection

AWorkspacescollectioncontainsallactive,unhiddenWorkspaceobjectsoftheDBEngineobject.(HiddenWorkspaceobjectsarenotappendedtothecollectionandreferencedbythevariabletowhichtheyareassigned.)

Remarks

UsetheWorkspaceobjecttomanagethecurrentsessionortostartanadditionalsession.

WhenyoufirstrefertooruseaWorkspaceobject,youautomaticallycreatethedefaultworkspace,DBEngine.Workspaces(0).ThesettingsoftheNameandUserNamepropertiesofthedefaultworkspaceare"#DefaultWorkspace#"and"Admin,"respectively.Ifsecurityisenabled,theUserNamepropertysettingisthenameoftheuserwhologgedon.

YoucancreatenewWorkspaceobjectswiththeCreateWorkspacemethod.AfteryoucreateanewWorkspaceobject,youmustappendittotheWorkspacescollectionifyouneedtorefertoitfromtheWorkspacescollection.Youcan,however,useanewlycreatedWorkspaceobjectwithoutappendingittotheWorkspacescollection.

TorefertoaWorkspaceobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

DBEngine.Workspaces(0)

DBEngine.Workspaces("name")

DBEngine.Workspaces![name]

WorkspaceObject

AWorkspaceobjectdefinesanamedsessionforauser.Itcontainsopendatabasesandprovidesmechanismsforsimultaneoustransactionsand,inMicrosoftJetworkspaces,secureworkgroupsupport.ItalsocontrolswhetheryouaregoingthroughtheMicrosoftJetdatabaseengineorODBCDirecttoaccessexternaldata.

Remarks

AWorkspaceisanon-persistentobjectthatdefineshowyourapplicationinteractswithdata—eitherbyusingtheMicrosoftJetdatabaseengine,orODBCDirect.UsetheWorkspaceobjecttomanagethecurrentsessionortostartanadditionalsession.Inasession,youcanopenmultipledatabasesorconnections,andmanagetransactions.Forexample,youcan:

UsetheName,UserName,andTypepropertiestoestablishanamedsession.Thesessioncreatesascopeinwhichyoucanopenmultipledatabasesandconductoneinstanceofnestedtransactions.

UsetheClosemethodtoterminateasession.

UsetheOpenDatabasemethodtoopenoneormoreexistingdatabasesonaWorkspace.

UsetheBeginTrans,CommitTrans,andRollbackmethodstomanagenestedtransactionprocessingwithinaWorkspaceanduseseveralWorkspaceobjectstoconductmultiple,simultaneous,andoverlappingtransactions.

Further,usingaMicrosoftJetdatabase,youcanestablishsecuritybasedonusernamesandpasswords:

UsetheGroupsandUserscollectionstoestablishgroupanduseraccesspermissionstoobjectsintheWorkspace.

UsetheIsolateODBCTranspropertytoisolatemultipletransactionsthatinvolvethesameMicrosoftJet-connectedODBC

database.

NoteForacompletelistofallmethods,properties,andcollectionsavailableonaWorkspaceobjectineitheraMicrosoftJetdatabaseoranODBCDirectdatabase,seetheSummarytopic.

WhenyoufirstrefertooruseaWorkspaceobject,youautomaticallycreatethedefaultworkspace,DBEngine.Workspaces(0).ThesettingsoftheNameandUserNamepropertiesofthedefaultworkspaceare"#DefaultWorkspace#"and"Admin,"respectively.Ifsecurityisenabled,theUserNamepropertysettingisthenameoftheuserwhologgedon.

ToestablishanODBCDirectWorkspaceobject,andtherebyavoidloadingtheMicrosoftJetdatabaseengineintomemory,settheDBEngineobject'sDefaultTypepropertytodbUseODBC,orsetthetypeargumentoftheCreateWorkspacemethodtodbUseODBC.

Whenyouusetransactions,alldatabasesinthespecifiedWorkspaceareaffected—evenifmultipleDatabaseobjectsareopenedintheWorkspace.Forexample,youuseaBeginTransmethod,updateseveralrecordsinadatabase,andthendeleterecordsinanotherdatabase.IfyouthenusetheRollbackmethod,boththeupdateanddeleteoperationsarecanceledandrolledback.YoucancreateadditionalWorkspaceobjectstomanagetransactionsindependentlyacrossDatabaseobjects.

YoucancreateWorkspaceobjectswiththeCreateWorkspacemethod.AfteryoucreateanewWorkspaceobject,youmustappendittotheWorkspacescollectionifyouneedtorefertoitfromtheWorkspacescollection.

YoucanuseanewlycreatedWorkspaceobjectwithoutappendingittotheWorkspacescollection.However,youmustrefertoitbytheobjectvariabletowhichyouhaveassignedit.

TorefertoaWorkspaceobjectinacollectionbyitsordinalnumberorbyitsNamepropertysetting,useanyofthefollowingsyntaxforms:

DBEngine.Workspaces(0)

DBEngine.Workspaces("name")

DBEngine.Workspaces![name]

WorkspaceObject,WorkspacesCollectionSummary

WorkspaceObject

AWorkspaceobjectcontainsthesecollections,methods,andproperties.

Legend:



Collections

ConnectionsDatabases(default)GroupsPropertiesUsers

Methods

BeginTransCloseCommitTransCreateDatabaseCreateGroupCreateUserOpenConnection

OpenDatabaseRollback

Properties

DefaultCursorDriverIsolateODBCTransLoginTimeoutNameTypeUserName

WorkspacesCollection

AWorkspacescollectioniscontainedintheDBEngineobject,andcontainsthesemethodsandthisproperty.

Methods

AppendDeleteRefresh

Property

Count

DAOMethodsbyObject

ThisreferencegroupsallDAOmethodsbyobject.ToseewhetheraparticularmethodisavailableforMicrosoftJetorODBCworkspaces,checktheHelptopicforthatmethod.

Connection

Container—nomethods

Database

Parameter—nomethods

Property—nomethods

QueryDef

DBEngine

Document

Error—nomethods

Field

Group

Recordset

Relation

TableDef

User

Index Workspace

DAOMethodsforMicrosoftJetWorkspaces

ThisreferencelistsalphabeticallyallDAOmethodsavailableforMicrosoftJetworkspaces(ISAMdatabasefiles).

A-CAddNew

Append

AppendChunk

BeginTrans

CancelUpdate

Clone

Close

CommitTrans

CompactDatabase

CopyQueryDef

CreateDatabase

CreateField

CreateGroup

CreateIndex

CreateProperty

CreateQueryDef

CreateRelation

CreateTableDef

CreateUser

CreateWorkspace

D-MDelete

Edit

Execute

FillCache

FindFirst

FindLast

FindNext

FindPrevious

GetChunk

GetRows

Idle

MakeReplica

Move

MoveFirst

MoveLast

MoveNext

MovePrevious

N-ZNewPassword

OpenDatabase

OpenRecordset

PopulatePartialdamthPopulatePartial>langref

Refresh

RefreshLink

RegisterDatabase

RepairDatabase

Requery

Rollback

Seek

SetOption

Synchronize

Update

DAOMethodsforODBCDirectWorkspaces

ThisreferencealphabeticallylistsallDAOmethodsavailableforODBCDirectworkspaces.

A-CAddNew

Append

AppendChunk

BeginTrans

Cancel

CancelUpdate

Clone

Close

CommitTrans

CreateQueryDef

CreateWorkspace

D-MDelete

Edit

Execute

GetChunk

GetRows

Move

MoveFirst

MoveLast

MoveNext

MovePrevious

N-ZNextRecordset

OpenConnection

OpenDatabase

OpenRecordset

Refresh

RegisterDatabase

Requery

Rollback

Update

AddNewMethod

CreatesanewrecordforanupdatableRecordsetobject.

Syntax

recordset.AddNew

TherecordsetplaceholderisanobjectvariablethatrepresentsanupdatableRecordsetobjecttowhichyouwanttoaddanewrecord.

Remarks

UsetheAddNewmethodtocreateandaddanewrecordintheRecordsetobjectnamedbyrecordset.Thismethodsetsthefieldstodefaultvalues,andifnodefaultvaluesarespecified,itsetsthefieldstoNull(thedefaultvaluesspecifiedforatable-typeRecordset).

Afteryoumodifythenewrecord,usetheUpdatemethodtosavethechangesandaddtherecordtotheRecordset.NochangesoccurinthedatabaseuntilyouusetheUpdatemethod.

CautionIfyouissueanAddNewandthenperformanyoperationthat

movestoanotherrecord,butwithoutusingUpdate,yourchangesarelostwithoutwarning.Inaddition,ifyouclosetheRecordsetorendtheprocedurethatdeclarestheRecordsetoritsDatabaseobject,thenewrecordisdiscardedwithoutwarning.

NoteWhenyouuseAddNewinaMicrosoftJetworkspaceandthedatabaseenginehastocreateanewpagetoholdthecurrentrecord,pagelockingispessimistic.Ifthenewrecordfitsinanexistingpage,pagelockingisoptimistic.

Ifyouhaven'tmovedtothelastrecordofyourRecordset,recordsaddedtobasetablesbyotherprocessesmaybeincludediftheyarepositionedbeyondthecurrentrecord.IfyouaddarecordtoyourownRecordset,however,therecordisvisibleintheRecordsetandincludedintheunderlyingtablewhereitbecomesvisibletoanynewRecordsetobjects.

ThepositionofthenewrecorddependsonthetypeofRecordset:

Inadynaset-typeRecordsetobject,recordsareinsertedattheendoftheRecordset,regardlessofanysortingororderingrulesthatwereineffectwhentheRecordsetwasopened.

Inatable-typeRecordsetobjectwhoseIndexpropertyhasbeenset,recordsarereturnedintheirproperplaceinthesortorder.Ifyouhaven'tsettheIndexproperty,newrecordsarereturnedattheendoftheRecordset.

TherecordthatwascurrentbeforeyouusedAddNewremainscurrent.Ifyouwanttomakethenewrecordcurrent,youcansettheBookmarkpropertytothebookmarkidentifiedbytheLastModifiedpropertysetting.

NoteToadd,edit,ordeletearecord,theremustbeauniqueindexontherecordintheunderlyingdatasource.Ifnot,a"Permissiondenied"errorwilloccurontheAddNew,Delete,orEditmethodcallinaMicrosoftJetworkspace,oran"Invalidargument"errorwilloccurontheUpdatecallinanODBCDirectworkspace.

AppendMethod

AddsanewDAOobjecttoacollection.

Syntax

collection.Appendobject

TheAppendmethodsyntaxhastheseparts.

Part Description

collection Anobjectvariablethatrepresentsanycollectionthatcanacceptnewobjects(forlimitations,seethetableattheendofthistopic).

object Anobjectvariablethatrepresentstheobjectbeingappended,whichmustbeofthesametypeastheelementsofcollection.

Remarks

YoucanusetheAppendmethodtoaddanewtabletoadatabase,addafieldtoatable,andaddafieldtoanindex.

Theappendedobjectbecomesapersistentobject,storedondisk,untilyoudeleteitbyusingtheDeletemethod.IfcollectionisaWorkspacescollection(whichisstoredonlyinmemory),theobjectisactiveuntilyou

removeitbyusingtheClosemethod.

Theadditionofanewobjectoccursimmediately,butyoushouldusetheRefreshmethodonanyothercollectionsthatmaybeaffectedbychangestothedatabasestructure.

Iftheobjectyou'reappendingisn’tcomplete(suchaswhenyouhaven’tappendedanyFieldobjectstoaFieldscollectionofanIndexobjectbeforeit’sappendedtoanIndexescollection)orifthepropertiessetinoneormoresubordinateobjectsareincorrect,usingtheAppendmethodcausesanerror.Forexample,ifyouhaven’tspecifiedafieldtypeandthentrytoappendtheFieldobjecttotheFieldscollectioninaTableDefobject,usingtheAppendmethodtriggersarun-timeerror.

ThefollowingtablelistssomelimitationsoftheAppendmethod.Theobjectinthefirstcolumnisanobjectcontainingthecollectioninthesecondcolumn.Thethirdcolumnindicateswhetheryoucanappendanobjecttothatcollection(forexample,youcanneverappendaContainerobjecttotheContainerscollectionofaDatabaseobject).

Object CollectionCanyouappendnewobjects?

DBEngine Workspaces Yes

DBEngine Errors No.NewErrorobjectsareautomaticallyappendedwhentheyoccur.

Workspace Connections No.UsingtheOpenConnectionmethodautomaticallyappendsnewobjects.

Workspace Databases No.UsingtheOpenDatabasemethodautomaticallyappendsnewobjects.

Workspace Groups YesWorkspace Users Yes

Connection QueryDefs No.UsingtheCreateQueryDefmethodautomaticallyappendsnewobjects.

Connection Recordsets No.UsingtheOpenRecordsetmethodautomaticallyappendsnewobjects.

Database Containers No

Database QueryDefsOnlywhentheQueryDefobjectisanew,unappendedobjectcreatedwithnoname.SeetheCreateQueryDefmethodfordetails.

Database Recordsets No.UsingtheOpenRecordsetmethodautomaticallyappendsnewobjects.

Database Relations YesDatabase TableDefs YesGroup Users YesUser Groups YesContainer Documents NoQueryDef Fields NoQueryDef Parameters NoRecordset Fields NoRelation Fields Yes

TableDef FieldsOnlywhentheUpdatablepropertyoftheTableDefobjectissettoTrue,orwhentheTableDefobjectisunappended.

TableDef IndexesOnlywhentheUpdatablepropertyoftheTableDefissettoTrue,orwhentheTableDefobjectisunappended.

Index Fields OnlywhentheIndexobjectisanew,unappendedobject.

Database,Field,Index,QueryDef,TableDef

PropertiesOnlywhentheDatabase,Field,Index,QueryDef,orTableDefobjectisinaMicrosoftJetworkspace.

DBEngine,Parameter,Recordset,Workspace

Properties No

AppendChunkMethod

AppendsdatafromastringexpressiontoaMemoorLongBinaryFieldobjectinaRecordset.

Syntax

recordset!field.AppendChunksource

TheAppendChunkmethodsyntaxhastheseparts.

Part Description

recordset AnobjectvariablethatrepresentstheRecordsetobjectcontainingtheFieldscollection.

fieldAnobjectvariablethatrepresentsthenameofaFieldobjectwhoseTypepropertyissettodbMemo(Memo),dbLongBinary(LongBinary),ortheequivalent.

source AVariant(Stringsubtype)expressionorvariablecontainingthedatayouwanttoappendtotheFieldobjectspecifiedbyfield.

Remarks

YoucanusetheAppendChunkandGetChunkmethodstoaccesssubsetsofdatainaMemoorLongBinaryfield.

YoucanalsousethesemethodstoconservestringspacewhenyouworkwithMemoandLongBinaryfields.Certainoperations(copying,forexample)involvetemporarystrings.Ifstringspaceislimited,youmayneedtoworkwithchunksofafieldinsteadoftheentirefield.

IfthereisnocurrentrecordwhenyouuseAppendChunk,anerroroccurs.

Notes

TheinitialAppendChunkoperation(afteranEditorAddNewcall)willsimplyplacethedatainthefield,overwritinganyexistingdata.SubsequentAppendChunkcallswithinthesameEditorAddNewsessionwillthenaddtotheexistingdata.

InanODBCDirectworkspace,unlessyoufirsteditanotherfieldinthecurrentrecord,usingAppendChunkwillfail(thoughnoerroroccurs)whileyouareinEditmode.

InanODBCDirectworkspace,afteryouuseAppendChunkonafield,youcannotreadorwritethatfieldinanassignmentstatementuntilyoumoveoffthecurrentrecordandthenreturntoit.YoucandothisbyusingtheMoveNextandMovePreviousmethods.

BeginTrans,CommitTrans,RollbackMethods

ThetransactionmethodsmanagetransactionprocessingduringasessiondefinedbyaWorkspaceobjectasfollows:

BeginTransbeginsanewtransaction.

CommitTransendsthecurrenttransactionandsavesthechanges.

RollbackendsthecurrenttransactionandrestoresthedatabasesintheWorkspaceobjecttothestatetheywereinwhenthecurrenttransactionbegan.

Syntax

workspace.BeginTrans|CommitTrans[dbForceOSFlush]|Rollback

TheworkspaceplaceholderisanobjectvariablethatrepresentstheWorkspacecontainingthedatabasesthatwillusetransactions.

Remarks

YouusethesemethodswithaWorkspaceobjectwhenyouwanttotreataseriesofchangesmadetothedatabasesinasessionasoneunit.

Typically,youusetransactionstomaintaintheintegrityofyourdatawhenyoumustbothupdaterecordsintwoormoretablesandensurechangesarecompleted(committed)inalltablesornoneatall(rolledback).Forexample,ifyoutransfermoneyfromoneaccounttoanother,youmightsubtractanamountfromoneandaddtheamounttoanother.Ifeitherupdatefails,theaccountsnolongerbalance.UsetheBeginTransmethodbeforeupdatingthefirstrecord,andthen,ifanysubsequentupdatefails,youcanusetheRollbackmethodtoundoalloftheupdates.UsetheCommitTransmethodafteryousuccessfullyupdatethelastrecord.

InaMicrosoftJetworkspace,youcanincludethedbFlushOSCacheWritesconstantwithCommitTrans,Thisforcesthedatabaseenginetoimmediatelyflushallupdatestodisk,insteadofcachingthemtemporarily.Withoutusingthisoption,ausercouldgetcontrolbackimmediatelyaftertheapplicationprogramcallsCommitTrans,turnthecomputeroff,andnothavethedatawrittentodisk.Whileusingthisoptionmayaffectyourapplication’sperformance,itisusefulinsituationswherethecomputercouldbeshutoffbeforecachedupdatesaresavedtodisk.

CautionWithinoneWorkspaceobject,transactionsarealwaysglobaltotheWorkspaceandaren'tlimitedtoonlyoneConnectionorDatabaseobject.IfyouperformoperationsonmorethanoneconnectionordatabasewithinaWorkspacetransaction,resolvingthetransaction(thatis,usingtheCommitTransorRollbackmethod)affectsalloperationsonallconnectionsanddatabaseswithinthatworkspace.

AfteryouuseCommitTrans,youcan'tundochangesmadeduringthattransactionunlessthetransactionisnestedwithinanothertransactionthatisitselfrolledback.Ifyounesttransactions,youmustresolvethecurrenttransactionbeforeyoucanresolveatransactionatahigherlevel

ofnesting.

Ifyouwanttohavesimultaneoustransactionswithoverlapping,non-nestedscopes,youcancreateadditionalWorkspaceobjectstocontaintheconcurrenttransactions.

IfyoucloseaWorkspaceobjectwithoutresolvinganypendingtransactions,thetransactionsareautomaticallyrolledback.

IfyouusetheCommitTransorRollbackmethodwithoutfirstusingtheBeginTransmethod,anerroroccurs.

SomeISAMdatabasesusedinaMicrosoftJetworkspacemaynotsupporttransactions,inwhichcasetheTransactionspropertyoftheDatabaseobjectorRecordsetobjectisFalse.Tomakesurethedatabasesupportstransactions,checkthevalueoftheTransactionspropertyoftheDatabaseobjectbeforeusingtheBeginTransmethod.IfyouareusingaRecordsetobjectbasedonmorethanonedatabase,checktheTransactionspropertyoftheRecordsetobject.IfaRecordsetisbasedentirelyonMicrosoftJettables,youcanalwaysusetransactions.Recordsetobjectsbasedontablescreatedbyotherdatabaseproducts,however,maynotsupporttransactions.Forexample,youcan'tusetransactionsinaRecordsetbasedonaParadoxtable.Inthiscase,theTransactionspropertyisFalse.IftheDatabaseorRecordsetdoesn'tsupporttransactions,themethodsareignoredandnoerroroccurs.

Youcan'tnesttransactionsifyouareaccessingODBCdatasourcesthroughtheMicrosoftJetdatabaseengine.

Notes

Youcanoftenimprovetheperformanceofyourapplicationbybreakingoperationsthatrequirediskaccessintotransactionblocks.Thisbuffersyouroperationsandmaysignificantlyreducethenumberoftimesadiskisaccessed.

InaMicrosoftJetworkspace,transactionsareloggedinafilekeptinthedirectoryspecifiedbytheTEMPenvironmentvariableontheworkstation.IfthetransactionlogfileexhauststheavailablestorageonyourTEMPdrive,thedatabaseenginetriggersarun-timeerror.Atthispoint,ifyouuseCommitTrans,anindeterminatenumberofoperationsarecommitted,buttheremaininguncompletedoperationsarelost,andtheoperationhastoberestarted.UsingaRollbackmethodreleasesthetransactionlogandrollsbackalloperationsinthetransaction.

ClosingacloneRecordsetwithinapendingtransactionwillcauseanimplicitRollbackoperation.

CancelMethod

Cancelsexecutionofapendingasynchronousmethodcall(ODBCDirectworkspacesonly).

Syntax

object.Cancel

TheCancelmethodsyntaxhastheseparts.

Part Description

object Astringexpressionthatevaluatestooneoftheobjectsinthe"AppliesTo"list.

Remarks

UsetheCancelmethodtoterminateexecutionofanasynchronousExecute,MoveLast,OpenConnection,orOpenRecordsetmethodcall(thatis,themethodwasinvokedwiththedbRunAsyncoption).Cancelwillreturnarun-timeerrorifdbRunAsyncwasnotusedinthemethodyou'retryingtoterminate.

Thefollowingtableshowswhattaskisterminatedwhenyouusethe

Cancelmethodonaparticulartypeofobject.

Ifobjectisa ThisasynchronousmethodisterminatedConnection ExecuteorOpenConnectionQueryDef ExecuteRecordset MoveLastorOpenRecordset

Anerrorwilloccurif,followingaCancelmethodcall,youtrytoreferencetheobjectthatwouldhavebeencreatedbyanasynchronousOpenConnectionorOpenRecordsetcall(thatis,theConnectionorRecordsetobjectfromwhichyoucalledtheCancelmethod).

CancelUpdateMethod

CancelsanypendingupdatesforaRecordsetobject.

Syntax

recordset.CancelUpdatetype

TheCancelUpdatemethodsyntaxhastheseparts.

Part Description

recordset AnobjectvariablethatrepresentstheRecordsetobjectforwhichyouarecancelingpendingupdates.

type Optional.Aconstantindicatingthetypeofupdate,asspecifiedinSettings.

Settings

Youcanusethefollowingvaluesforthetypeargumentonlyifbatchupdatingisenabled.


dbUpdateRegular Default.Cancelspendingchangesthataren’tcached.

dbUpdateBatch Cancelspendingchangesintheupdatecache.

Remarks

YoucanusetheCancelUpdatemethodtocancelanypendingupdatesresultingfromanEditorAddNewoperation.Forexample,ifauserinvokestheEditorAddNewmethodandhasn'tyetinvokedtheUpdatemethod,CancelUpdatecancelsanychangesmadeafterEditorAddNewwasinvoked.

ChecktheEditModepropertyoftheRecordsettodetermineifthereisapendingoperationthatcanbecanceled.

NoteUsingtheCancelUpdatemethodhasthesameeffectasmovingtoanotherrecordwithoutusingtheUpdatemethod,exceptthatthecurrentrecorddoesn'tchange,andvariousproperties,suchasBOFandEOF,aren'tupdated.

CloneMethod

CreatesaduplicateRecordsetobjectthatreferstotheoriginalRecordsetobject.

Syntax

Setduplicate=original.Clone

TheClonemethodsyntaxhastheseparts.

Part Description

duplicate AnobjectvariableidentifyingtheduplicateRecordsetobjectyou'recreating.

original AnobjectvariableidentifyingtheRecordsetobjectyouwanttoduplicate.

Remarks

UsetheClonemethodtocreatemultiple,duplicateRecordsetobjects.EachRecordsetcanhaveitsowncurrentrecord.UsingClonebyitselfdoesn'tchangethedataintheobjectsorintheirunderlyingstructures.WhenyouusetheClonemethod,youcansharebookmarksbetweentwoormoreRecordsetobjectsbecausetheirbookmarksare

interchangeable.

YoucanusetheClonemethodwhenyouwanttoperformanoperationonaRecordsetthatrequiresmultiplecurrentrecords.ThisisfasterandmoreefficientthanopeningasecondRecordset.WhenyoucreateaRecordsetwiththeClonemethod,itinitiallylacksacurrentrecord.TomakearecordcurrentbeforeyouusetheRecordsetclone,youmustsettheBookmarkpropertyoruseoneoftheMovemethods,oneoftheFindmethods,ortheSeekmethod.

UsingtheClosemethodoneithertheoriginalorduplicateobjectdoesn'taffecttheotherobject.Forexample,usingCloseontheoriginalRecordsetdoesn'tclosetheclone.

Notes

ClosingacloneRecordsetwithinapendingtransactionwillcauseanimplicitRollbackoperation.

Whenyoucloneatable-typeRecordsetobjectinaMicrosoftJetworkspace,theIndexpropertysettingisnotclonedonthenewcopyoftheRecordset.YoumustcopytheIndexpropertysettingmanually.

YoucanusetheClonemethodwithforward-only–typeRecordsetobjectsonlyinanODBCDirectworkspace.

CloseMethod

ClosesanopenDAOobject.

Syntax

object.Close

TheobjectplaceholderisanobjectvariablethatrepresentsanopenConnection,Database,Recordset,orWorkspaceobject.

Remarks

Closinganopenobjectremovesitfromthecollectiontowhichit'sappended.Anyattempttoclosethedefaultworkspaceisignored.

IftheConnection,Database,Recordset,orWorkspaceobjectnamedbyobjectisalreadyclosedwhenyouuseClose,arun-timeerroroccurs.

CautionIfyouexitaprocedurethatdeclaresConnection,Database,orRecordsetobjects,thoseobjectsareclosed,allpendingtransactionsarerolledback,andanypendingeditstoyourdataarelost.

IfyoutrytocloseaConnectionorDatabaseobjectwhileithasanyopenRecordsetobjects,theRecordsetobjectswillbeclosedandanypendingupdatesoreditswillbecanceled.Similarly,ifyoutrytocloseaWorkspaceobjectwhileithasanyopenConnectionorDatabaseobjects,thoseConnectionandDatabaseobjectswillbeclosed,whichwillclosetheirRecordsetobjects.

UsingtheClosemethodoneitheranoriginalorclonedRecordsetobjectdoesn'taffecttheotherRecordsetobject.

ToremoveobjectsfromupdatablecollectionsotherthantheConnections,Databases,Recordsets,andWorkspacescollections,usetheDeletemethodonthosecollections.Youcan'taddanewmembertotheContainers,Documents,andErrorscollections.

AnalternativetotheClosemethodistosetthevalueofanobjectvariabletoNothing(SetdbsTemp=Nothing).

CompactDatabaseMethod

Copiesandcompactsacloseddatabase,andgivesyoutheoptionofchangingitsversion,collatingorder,andencryption.(MicrosoftJetworkspacesonly).

Syntax

DBEngine.CompactDatabaseolddb,newdb,locale,options,password

TheCompactDatabasemethodsyntaxhastheseparts.

Part Description

olddb

AStringthatidentifiesanexisting,closeddatabase.Itcanbeafullpathandfilename,suchas"C:\db1.mdb".Ifthefilenamehasanextension,youmustspecifyit.Ifyournetworksupportsit,youcanalsospecifyanetworkpath,suchas"\\server1\share1\dir1\db1.mdb".

newdbAStringthatisthefilename(andpath)ofthecompacteddatabasethatyou'recreating.Youcanalsospecifyanetworkpath.Youcan'tusethenewdbargumenttospecifythesamedatabasefileasolddb.

localeOptional.AVariantthatisastringexpressionthatspecifiesacollatingorderforcreatingnewdb,asspecifiedinSettings.Ifyouomitthisargument,thelocaleofnewdbisthesameasolddb.

Youcanalsocreateapasswordfornewdbbyconcatenatingthepasswordstring(startingwith";pwd=")withaconstantinthelocaleargument,likethis:dbLangSpanish&";pwd=NewPassword"Ifyouwanttousethesamelocaleasolddb(thedefaultvalue),butspecifyanewpassword,simplyenterapasswordstringforlocale:";pwd=NewPassword"

optionsOptional.Aconstantorcombinationofconstantsthatindicatesoneormoreoptions,asspecifiedinSettings.Youcancombineoptionsbysummingthecorrespondingconstants.

password

Optional.AVariantthatisastringexpressioncontainingapassword,ifthedatabaseispasswordprotected.Thestring";pwd="mustprecedetheactualpassword.Ifyouincludeapasswordsettinginlocale,thissettingisignored.

NoteUsestrongpasswordsthatcombineupper-andlowercaseletters,numbers,andsymbols.Weakpasswordsdon'tmixtheseelements.Strongpassword:Y6dh!et5.Weakpassword:House27.Useastrongpasswordthatyoucanremembersothatyoudon'thavetowriteitdown.

Settings

YoucanuseoneofthefollowingconstantsforthelocaleargumenttospecifytheCollatingOrderpropertyforstringcomparisonsoftext.

Constant Collatingorder


dbLangArabic ArabicdbLangChineseSimplified SimplifiedChinesedbLangChineseTraditional TraditionalChinesedbLangCyrillic RussiandbLangCzech CzechdbLangDutch DutchdbLangGreek GreekdbLangHebrew HebrewdbLangHungarian HungariandbLangIcelandic Icelandic

dbLangJapanese JapanesedbLangKorean Korean

dbLangNordic Nordiclanguages(MicrosoftJetdatabaseengineversion1.0only)

dbLangNorwDan NorwegianandDanishdbLangPolish PolishdbLangSlovenian SloveniandbLangSpanish TraditionalSpanishdbLangSwedFin SwedishandFinnishdbLangThai ThaidbLangTurkish Turkish

Youcanuseoneofthefollowingconstantsintheoptionsargumenttospecifywhethertoencryptortodecryptthedatabasewhileit'scompacted.

Constant DescriptiondbEncrypt Encryptthedatabasewhilecompacting.dbDecrypt Decryptthedatabasewhilecompacting.

IfyouomitanencryptionconstantorifyouincludebothdbDecryptanddbEncrypt,newdbwillhavethesameencryptionasolddb.

Youcanuseoneofthefollowingconstantsintheoptionsargumenttospecifytheversionofthedataformatforthecompacteddatabase.Thisconstantaffectsonlytheversionofthedataformatofnewdbanddoesn'taffecttheversionofanyMicrosoftAccess-definedobjects,suchasformsandreports.


dbVersion10 CreatesadatabasethatusestheMicrosoftJetdatabaseengineversion1.0fileformatwhilecompacting.



dbVersion30CreatesadatabasethatusestheMicrosoftJetdatabaseengineversion3.0fileformat(compatiblewithversion3.5)whilecompacting.

Youcanspecifyonlyoneversionconstant.Ifyouomitaversionconstant,newdbwillhavethesameversionasolddb.Youcancompactnewdbonlytoaversionthatisthesameorlaterthanthatofolddb.

Remarks

Asyouchangedatainadatabase,thedatabasefilecanbecomefragmentedandusemorediskspacethanisnecessary.Periodically,youcanusetheCompactDatabasemethodtocompactyourdatabasetodefragmentthedatabasefile.Thecompacteddatabaseisusuallysmallerandoftenrunsfaster.Youcanalsochangethecollatingorder,theencryption,ortheversionofthedataformatwhileyoucopyandcompactthedatabase.

Youmustcloseolddbbeforeyoucompactit.Inamultiuserenvironment,otheruserscan'thaveolddbopenwhileyou'recompactingit.Ifolddbisn'tclosedorisn'tavailableforexclusiveuse,anerroroccurs.

BecauseCompactDatabasecreatesacopyofthedatabase,youmusthaveenoughdiskspaceforboththeoriginalandtheduplicatedatabases.Thecompactoperationfailsifthereisn'tenoughdiskspaceavailable.Thenewdbduplicatedatabasedoesn'thavetobeonthesamediskasolddb.Aftersuccessfullycompactingadatabase,youcandeletetheolddbfileandrenamethecompactednewdbfiletotheoriginalfilename.

TheCompactDatabasemethodcopiesallthedataandthesecuritypermissionsettingsfromthedatabasespecifiedbyolddbtothedatabasespecifiedbynewdb.

IfyouuseCompactDatabasetoconvertaversion1.xdatabasetoversion2.5or3.x,onlyapplicationsusingversionMicrosoftJet2.5or3.xcanopentheconverteddatabase.

NoteInanODBCDirectworkspace,usingtheCompactDatabasemethoddoesn'treturnanerror,butinsteadloadstheMicrosoftJetdatabaseengineintomemory.

CautionBecausetheCompactDatabasemethoddoesn'tconvertMicrosoftAccessobjects,youshouldn'tuseCompactDatabasetoconvertadatabasecontainingsuchobjects.ToconvertadatabasecontainingMicrosoftAccessobjects,ontheToolsmenu,pointtoDatabaseUtilities,andthenclickConvertDatabase.

CopyQueryDefMethod

ReturnsaQueryDefobjectthatisacopyoftheQueryDefusedtocreatetheRecordsetobjectrepresentedbytherecordsetplaceholder(MicrosoftJetworkspacesonly).

Syntax

Setquerydef=recordset.CopyQueryDef

TheCopyQueryDefmethodsyntaxhastheseparts.

Part Description

querydef AnobjectvariablethatrepresentsthecopyofaQueryDefobjectyouwanttocreate.

recordset AnobjectvariablethatrepresentstheRecordsetobjectcreatedwiththeoriginalQueryDefobject.

Remarks

YoucanusetheCopyQueryDefmethodtocreateanewQueryDefthatisaduplicateoftheQueryDefusedtocreatetheRecordset.

IfaQueryDefwasn'tusedtocreatethisRecordset,anerroroccurs.You

mustfirstopenaRecordsetwiththeOpenRecordsetmethodbeforeusingtheCopyQueryDefmethod.

ThismethodisusefulwhenyoucreateaRecordsetobjectfromaQueryDef,andpasstheRecordsettoafunction,andthefunctionmustre-createtheSQLequivalentofthequery,forexample,tomodifyitinsomeway.

CreateDatabaseMethod

CreatesanewDatabaseobject,savesthedatabasetodisk,andreturnsanopenedDatabaseobject(MicrosoftJetworkspacesonly).

Syntax

Setdatabase=workspace.CreateDatabase(name,locale,options)

TheCreateDatabasemethodsyntaxhastheseparts.

Part Description

database AnobjectvariablethatrepresentstheDatabaseobjectyouwanttocreate.

workspaceAnobjectvariablethatrepresentstheexistingWorkspaceobjectthatwillcontainthedatabase.Ifyouomitworkspace,CreateDatabaseusesthedefaultWorkspace.

name

AStringupto255characterslongthatisthenameofthedatabasefilethatyou'recreating.Itcanbethefullpathandfilename,suchas"C:\db1.mdb".Ifyoudon'tsupplyafilenameextension,.mdbisappended.Ifyournetworksupportsit,youcanalsospecifyanetworkpath,suchas"\\server1\share1\dir1\db1".Youcanonlycreate.mdbdatabasefileswiththismethod.Astringexpressionthatspecifiesacollatingorderforcreatingthe

locale database,asspecifiedinSettings.Youmustsupplythisargumentoranerroroccurs.

YoucanalsocreateapasswordforthenewDatabaseobjectbyconcatenatingthepasswordstring(startingwith";pwd=")withaconstantinthelocaleargument,likethis:dbLangSpanish&";pwd=NewPassword"


Ifyouwanttousethedefaultlocale,butspecifyapassword,simplyenterapasswordstringforthelocaleargument:";pwd=NewPassword"


optionsOptional.Aconstantorcombinationofconstantsthatindicatesoneormoreoptions,asspecifiedinSettings.Youcancombineoptionsbysummingthecorrespondingconstants.

Settings

YoucanuseoneofthefollowingconstantsforthelocaleargumenttospecifytheCollatingOrderpropertyoftextforstringcomparisons.

Constant Collatingorder


dbLangArabic ArabicdbLangChineseSimplified SimplifiedChinesedbLangChineseTraditional TraditionalChinesedbLangCyrillic RussiandbLangCzech Czech

dbLangDutch DutchdbLangGreek GreekdbLangHebrew HebrewdbLangHungarian HungariandbLangIcelandic IcelandicdbLangJapanese JapanesedbLangKorean Korean

dbLangNordic Nordiclanguages(MicrosoftJetdatabaseengineversion1.0only)

dbLangNorwDan NorwegianandDanishdbLangPolish PolishdbLangSlovenian SloveniandbLangSpanish TraditionalSpanishdbLangSwedFin SwedishandFinnishdbLangThai ThaidbLangTurkish Turkish

Youcanuseoneormoreofthefollowingconstantsintheoptionsargumenttospecifywhichversionthedataformatshouldhaveandwhetherornottoencryptthedatabase.

Constant DescriptiondbEncrypt Createsanencrypteddatabase.

dbVersion10 CreatesadatabasethatusestheMicrosoftJetdatabaseengineversion1.0fileformat.



dbVersion30 (Default)CreatesadatabasethatusestheMicrosoftJetdatabaseengineversion3.0fileformat(compatiblewithversion3.5).

Ifyouomittheencryptionconstant,CreateDatabasecreatesanun-encrypteddatabase.Youcanspecifyonlyoneversionconstant.Ifyouomitaversionconstant,CreateDatabasecreatesadatabasethatusestheMicrosoftJetdatabaseengineversion3.0fileformat.

Remarks

UsetheCreateDatabasemethodtocreateandopenanew,emptydatabase,andreturntheDatabaseobject.YoumustcompleteitsstructureandcontentbyusingadditionalDAOobjects.Ifyouwanttomakeapartialorcompletecopyofanexistingdatabase,youcanusetheCompactDatabasemethodtomakeacopythatyoucancustomize.

CreateFieldMethod

CreatesanewFieldobject(MicrosoftJetworkspacesonly).

Syntax

Setfield=object.CreateField(name,type,size)

TheCreateFieldmethodsyntaxhastheseparts.

Part Description

field AnobjectvariablethatrepresentstheFieldobjectyouwanttocreate.

object AnobjectvariablethatrepresentstheIndex,Relation,orTableDefobjectforwhichyouwanttocreatethenewFieldobject.

nameOptional.AVariant(Stringsubtype)thatuniquelynamesthenewFieldobject.SeetheNamepropertyfordetailsonvalidFieldnames.

type Optional.AconstantthatdeterminesthedatatypeofthenewFieldobject.SeetheTypepropertyforvaliddatatypes.

size

Optional.AVariant(Integersubtype)thatindicatesthemaximumsize,inbytes,ofaFieldobjectthatcontainstext.SeetheSizepropertyforvalidsizevalues.Thisargumentisignoredfornumericandfixed-widthfields.

Remarks

YoucanusetheCreateFieldmethodtocreateanewfield,aswellasspecifythename,datatype,andsizeofthefield.IfyouomitoneormoreoftheoptionalpartswhenyouuseCreateField,youcanuseanappropriateassignmentstatementtosetorresetthecorrespondingpropertybeforeyouappendthenewobjecttoacollection.Afteryouappendthenewobject,youcanaltersomebutnotallofitspropertysettings.Seetheindividualpropertytopicsformoredetails.

ThetypeandsizeargumentsapplyonlytoFieldobjectsinaTableDefobject.TheseargumentsareignoredwhenaFieldobjectisassociatedwithanIndexorRelationobject.

Ifnamereferstoanobjectthatisalreadyamemberofthecollection,arun-timeerroroccurswhenyouusetheAppendmethod.

ToremoveaFieldobjectfromaFieldscollection,usetheDeletemethodonthecollection.Youcan'tdeleteaFieldobjectfromaTableDefobject'sFieldscollectionafteryoucreateanindexthatreferencesthefield.

CreateGroupMethod

CreatesanewGroupobject(MicrosoftJetworkspacesonly).

Syntax

Setgroup=object.CreateGroup(name,pid)

TheCreateGroupmethodsyntaxhastheseparts.

Part Descriptiongroup AnobjectvariablethatrepresentstheGroupyouwanttocreate.

object AnobjectvariablethatrepresentstheUserorWorkspaceobjectforwhichyouwanttocreatethenewGroupobject.

nameOptional.AVariant(Stringsubtype)thatuniquelynamesthenewGroupobject.SeetheNamepropertyfordetailsonvalidGroupnames.

pid

Optional.AVariant(Stringsubtype)containingthePIDofagroupaccount.Theidentifiermustcontainfrom4to20alphanumericcharacters.SeethePIDpropertyformoreinformationonvalidpersonalidentifiers.

Remarks

YoucanusetheCreateGroupmethodtocreateanewGroupobjectforaUserorWorkspace.IfyouomitoneorbothoftheoptionalpartswhenyouuseCreateGroup,youcanuseanappropriateassignmentstatementtosetorresetthecorrespondingpropertybeforeyouappendthenewobjecttoacollection.Afteryouappendtheobject,youcanaltersomebutnotallofitspropertysettings.Seetheindividualpropertytopicsformoredetails.


ToremoveaGroupobjectfromacollection,usetheDeletemethodontheGroupscollection.

CreateIndexMethod

CreatesanewIndexobject(MicrosoftJetworkspacesonly).

Syntax

Setindex=tabledef.CreateIndex(name)

TheCreateIndexmethodsyntaxhastheseparts.

Part Descriptionindex Anobjectvariablethatrepresentstheindexyouwanttocreate.

tabledef AnobjectvariablethatrepresentstheTableDefobjectyouwanttousetocreatethenewIndexobject.

nameOptional.AVariant(Stringsubtype)thatuniquelynamesthenewIndexobject.SeetheNamepropertyfordetailsonvalidIndexnames.

Remarks

YoucanusetheCreateIndexmethodtocreateanewIndexobjectforaTableDefobject.IfyouomittheoptionalnamepartwhenyouuseCreateIndex,youcanuseanappropriateassignmentstatementtosetorresettheNamepropertybeforeyouappendthenewobjecttoa

collection.Afteryouappendtheobject,youmayormaynotbeabletosetitsNameproperty,dependingonthetypeofobjectthatcontainstheIndexescollection.SeetheNamepropertytopicformoredetails.


ToremoveanIndexobjectfromacollection,usetheDeletemethodonthecollection.

CreatePropertyMethod

Createsanewuser-definedPropertyobject(MicrosoftJetworkspacesonly).

Syntax

Setproperty=object.CreateProperty(name,type,value,DDL)

TheCreatePropertymethodsyntaxhastheseparts.

Part Description

property AnobjectvariablethatrepresentsthePropertyobjectyouwanttocreate.

objectAnobjectvariablethatrepresentstheDatabase,Field,Index,QueryDef,Document,orTableDefobjectyouwanttousetocreatethenewPropertyobject.

nameOptional.AVariant(Stringsubtype)thatuniquelynamesthenewPropertyobject.SeetheNamepropertyfordetailsonvalidPropertynames.

type Optional.AconstantthatdefinesthedatatypeofthenewPropertyobject.SeetheTypepropertyforvaliddatatypes.

value Optional.AVariantcontainingtheinitialpropertyvalue.SeetheValuepropertyfordetails.

DDLOptional.AVariant(Booleansubtype)thatindicateswhetherornotthePropertyisaDDLobject.ThedefaultisFalse.IfDDLisTrue,userscan'tchangeordeletethisPropertyobjectunlesstheyhavedbSecWriteDefpermission.

Remarks

Youcancreateauser-definedPropertyobjectonlyinthePropertiescollectionofanobjectthatispersistent.

IfyouomitoneormoreoftheoptionalpartswhenyouuseCreateProperty,youcanuseanappropriateassignmentstatementtosetorresetthecorrespondingpropertybeforeyouappendthenewobjecttoacollection.Afteryouappendtheobject,youcanaltersomebutnotallofitspropertysettings.SeetheName,Type,andValuepropertytopicsformoredetails.


Toremoveauser-definedPropertyobjectfromthecollection,usetheDeletemethodonthePropertiescollection.Youcan'tdeletebuilt-inproperties.

NoteIfyouomittheDDLargument,itdefaultstoFalse(non-DDL).BecausenocorrespondingDDLpropertyisexposed,youmustdeleteandre-createaPropertyobjectyouwanttochangefromDDLtonon-DDL.

CreateQueryDefMethod

CreatesanewQueryDefobjectinaspecifiedConnectionorDatabaseobject.

Syntax

Setquerydef=object.CreateQueryDef(name,sqltext)

TheCreateQueryDefmethodsyntaxhastheseparts.

Part Description

querydef AnobjectvariablethatrepresentstheQueryDefobjectyouwanttocreate.

object AnobjectvariablethatrepresentsanopenConnectionorDatabaseobjectthatwillcontainthenewQueryDef.

name Optional.AVariant(Stringsubtype)thatuniquelynamesthenewQueryDef.

sqltext

Optional.AVariant(Stringsubtype)thatisanSQLstatementdefiningtheQueryDef.Ifyouomitthisargument,youcandefinetheQueryDefbysettingitsSQLpropertybeforeorafteryouappendittoacollection.

Remarks

InaMicrosoftJetworkspace,ifyouprovideanythingotherthanazero-lengthstringforthenamewhenyoucreateaQueryDef,theresultingQueryDefobjectisautomaticallyappendedtotheQueryDefscollection.InanODBCDirectworkspace,QueryDefobjectsarealwaystemporary.

InanODBCDirectworkspace,thesqltextargumentcanspecifyanSQLstatementoraMicrosoftSQLServerstoredprocedureanditsparameters.

IftheobjectspecifiedbynameisalreadyamemberoftheQueryDefscollection,arun-timeerroroccurs.YoucancreateatemporaryQueryDefbyusingazero-lengthstringforthenameargumentwhenyouexecutetheCreateQueryDefmethod.YoucanalsoaccomplishthisbysettingtheNamepropertyofanewlycreatedQueryDeftoazero-lengthstring("").TemporaryQueryDefobjectsareusefulifyouwanttorepeatedlyusedynamicSQLstatementswithouthavingtocreateanynewpermanentobjectsintheQueryDefscollection.Youcan'tappendatemporaryQueryDeftoanycollectionbecauseazero-lengthstringisn'tavalidnameforapermanentQueryDefobject.YoucanalwayssettheNameandSQLpropertiesofthenewlycreatedQueryDefobjectandsubsequentlyappendtheQueryDeftotheQueryDefscollection.

ToruntheSQLstatementinaQueryDefobject,usetheExecuteorOpenRecordsetmethod.

UsingaQueryDefobjectisthepreferredwaytoperformSQLpass-throughquerieswithODBCdatabases.

ToremoveaQueryDefobjectfromaQueryDefscollectioninaMicrosoftJetdatabase,usetheDeletemethodonthecollection.ForanODBCDirectdatabase,usetheClosemethodontheQueryDefobject.

CreateRelationMethod

CreatesanewRelationobject(MicrosoftJetworkspacesonly).

Syntax

Setrelation=database.CreateRelation(name,table,foreigntable,attributes)

TheCreateRelationmethodsyntaxusestheseparts.

Part Description

relation AnobjectvariablethatrepresentstheRelationobjectyouwanttocreate.

database AnobjectvariablethatrepresentstheDatabaseobjectforwhichyouwanttocreatethenewRelationobject.

nameOptional.AVariant(Stringsubtype)thatuniquelynamesthenewRelationobject.SeetheNamepropertyfordetailsonvalidRelationnames.

tableOptional.AVariant(Stringsubtype)thatnamestheprimarytableintherelation.Ifthetabledoesn'texistbeforeyouappendtheRelationobject,arun-timeerroroccurs.

foreigntableOptional.AVariant(Stringsubtype)thatnamestheforeigntableintherelation.Ifthetabledoesn'texistbeforeyouappendtheRelation

object,arun-timeerroroccurs.

attributesOptional.Aconstantorcombinationofconstantsthatcontainsinformationabouttherelationshiptype.SeetheAttributespropertyfordetails.

Remarks

TheRelationobjectprovidesinformationtotheMicrosoftJetdatabaseengineabouttherelationshipbetweenfieldsintwoTableDeforQueryDefobjects.YoucanimplementreferentialintegritybyusingtheAttributesproperty.

IfyouomitoneormoreoftheoptionalpartswhenyouusetheCreateRelationmethod,youcanuseanappropriateassignmentstatementtosetorresetthecorrespondingpropertybeforeyouappendthenewobjecttoacollection.Afteryouappendtheobject,youcan'talteranyofitspropertysettings.Seetheindividualpropertytopicsformoredetails.

BeforeyoucanusetheAppendmethodonaRelationobject,youmustappendtheappropriateFieldobjectstodefinetheprimaryandforeignkeyrelationshiptables.

IfnamereferstoanobjectthatisalreadyamemberofthecollectionoriftheFieldobjectnamesprovidedinthesubordinateFieldscollectionareinvalid,arun-timeerroroccurswhenyouusetheAppendmethod.

Youcan'testablishormaintainarelationshipbetweenareplicatedtableandalocaltable.

ToremoveaRelationobjectfromtheRelationscollection,usetheDeletemethodonthecollection.

CreateTableDefMethod

CreatesanewTableDefobject(MicrosoftJetworkspacesonly).

Syntax

Settabledef=database.CreateTableDef(name,attributes,source,connect)

TheCreateTableDefmethodsyntaxhastheseparts.

Part Description

tabledef AnobjectvariablethatrepresentstheTableDefobjectyouwanttocreate.

database AnobjectvariablethatrepresentstheDatabaseobjectyouwanttousetocreatethenewTableDefobject.

nameOptional.AVariant(Stringsubtype)thatuniquelynamesthenewTableDefobject.SeetheNamepropertyfordetailsonvalidTableDefnames.

attributesOptional.AconstantorcombinationofconstantsthatindicatesoneormorecharacteristicsofthenewTableDefobject.SeetheAttributespropertyformoreinformation.

sourceOptional.AVariant(Stringsubtype)containingthenameofatableinanexternaldatabasethatistheoriginalsourceofthedata.

ThesourcestringbecomestheSourceTableNamepropertysettingofthenewTableDefobject.

connect

Optional.AVariant(Stringsubtype)containinginformationaboutthesourceofanopendatabase,adatabaseusedinapass-throughquery,oralinkedtable.SeetheConnectpropertyformoreinformationaboutvalidconnectionstrings.

Remarks

IfyouomitoneormoreoftheoptionalpartswhenyouusetheCreateTableDefmethod,youcanuseanappropriateassignmentstatementtosetorresetthecorrespondingpropertybeforeyouappendthenewobjecttoacollection.Afteryouappendtheobject,youcanaltersomebutnotallofitsproperties.Seetheindividualpropertytopicsformoredetails.

Ifnamereferstoanobjectthatisalreadyamemberofthecollection,oryouspecifyaninvalidpropertyintheTableDeforFieldobjectyou'reappending,arun-timeerroroccurswhenyouusetheAppendmethod.Also,youcan'tappendaTableDefobjecttotheTableDefscollectionuntilyoudefineatleastoneFieldfortheTableDefobject.

ToremoveaTableDefobjectfromtheTableDefscollection,usetheDeletemethodonthecollection.

CreateUserMethod

CreatesanewUserobject(MicrosoftJetworkspacesonly).

Syntax

Setuser=object.CreateUser(name,pid,password)

TheCreateUsermethodsyntaxhastheseparts.

Part Descriptionuser AnobjectvariablethatrepresentstheUserobjectyouwanttocreate.

object AnobjectvariablethatrepresentstheGrouporWorkspaceobjectforwhichyouwanttocreatethenewUserobject.

name Optional.AVariant(Stringsubtype)thatuniquelynamesthenewUserobject.SeetheNamepropertyfordetailsonvalidUsernames.

pid

Optional.AVariant(Stringsubtype)containingthePIDofauseraccount.Theidentifiermustcontainfrom4to20alphanumericcharacters.SeethePIDpropertyformoreinformationonvalidpersonalidentifiers.Optional.AVariant(Stringsubtype)containingthepasswordforthenewUserobject.Thepasswordcanbeupto14characterslongandcanincludeanycharactersexcepttheASCIIcharacter0(null).SeethePasswordpropertyformoreinformationonvalidpasswords.

password NoteUsestrongpasswordsthatcombineupper-andlowercaseletters,numbers,andsymbols.Weakpasswordsdon'tmixtheseelements.Strongpassword:Y6dh!et5.Weakpassword:House27.Useastrongpasswordthatyoucanremembersothatyoudon'thavetowriteitdown.

Remarks

IfyouomitoneormoreoftheoptionalpartswhenyouusetheCreateUsermethod,youcanuseanappropriateassignmentstatementtosetorresetthecorrespondingpropertybeforeyouappendthenewobjecttoacollection.Afteryouappendtheobject,youcanaltersomebutnotallofitspropertysettings.SeethePID,Name,andPasswordpropertytopicsformoredetails.


ToremoveaUserobjectfromtheUserscollection,usetheDeletemethodonthecollection.

CreateWorkspaceMethod

CreatesanewWorkspaceobject.

Syntax

Setworkspace=CreateWorkspace(name,user,password,type)

TheCreateWorkspacemethodsyntaxhastheseparts.

Part Description

workspace AnobjectvariablethatrepresentstheWorkspaceobjectyouwanttocreate.

name AStringthatuniquelynamesthenewWorkspaceobject.SeetheNamepropertyfordetailsonvalidWorkspacenames.

user AStringthatidentifiestheownerofthenewWorkspaceobject.SeetheUserNamepropertyformoreinformation.

password

AStringcontainingthepasswordforthenewWorkspaceobject.Thepasswordcanbeupto14characterslongandcanincludeanycharactersexceptASCIIcharacter0(null).SeethePasswordpropertyformoreinformationonvalidpasswords.

NoteUsestrongpasswordsthatcombineupper-and

lowercaseletters,numbers,andsymbols.Weakpasswordsdon'tmixtheseelements.Strongpassword:Y6dh!et5.Weakpassword:House27.Useastrongpasswordthatyoucanremembersothatyoudon'thavetowriteitdown.

type Optional.Aconstantthatindicatesthetypeofworkspace,asdescribedinSettings.

Settings

Youcanusethefollowingconstantsfortype.

Constant DescriptiondbUseJet CreatesaMicrosoftJetworkspace.

dbUseODBC CreatesanODBCDirectworkspace.

Remarks

OnceyouusetheCreateWorkspacemethodtocreateanewWorkspaceobject,aWorkspacesessionisstarted,andyoucanrefertotheWorkspaceobjectinyourapplication.

Workspaceobjectsaren'tpermanent,andyoucan'tsavethemtodisk.OnceyoucreateaWorkspaceobject,youcan'talteranyofitspropertysettings,exceptfortheNameproperty,whichyoucanmodifybeforeappendingtheWorkspaceobjecttotheWorkspacescollection.

Youdon'thavetoappendthenewWorkspaceobjecttoacollectionbeforeyoucanuseit.YouappendanewlycreatedWorkspaceobjectonlyifyouneedtorefertoitthroughtheWorkspacescollection.

ThetypeoptiondetermineswhetherthenewWorkspaceisaMicrosoftJetorODBCDirectworkspace.IfyousettypetodbUseODBCandyouhaven'talreadycreatedanyMicrosoftJetworkspaces,thentheMicrosoftJetdatabaseenginewillnotbeloadedintomemory,andallactivitywilloccurwiththeODBCdatasourcesubsequentlyidentifiedinaConnection

object.Ifyouomittype,theDefaultTypepropertyofDBEnginewilldeterminewhichtypeofdatasourcetheWorkspaceisconnectedto.YoucanhavebothMicrosoftJetandODBCDirectworkspacesopenatthesametime.

ToremoveaWorkspaceobjectfromtheWorkspacescollection,closeallopendatabasesandconnectionsandthenusetheClosemethodontheWorkspaceobject.

DeleteMethod

Recordsetobjects—deletesthecurrentrecordinanupdatableRecordsetobject.ForODBCDirectworkspaces,thetypeofdriverdetermineswhetherRecordsetobjectsareupdatableandthereforesupporttheDeletemethod.

Collections—deletesapersistentobjectfromacollection.

Syntax

recordset.Delete

collection.Deleteobjectname

TheDeletemethodsyntaxhastheseparts.

Part Description

recordset AnobjectvariablethatrepresentsanupdatableRecordsetobjectcontainingtherecordyouwanttodelete.

collection Anobjectvariablethatrepresentsacollectionfromwhichyouaredeletingobjectname.

objectname AStringthatistheNamepropertysettingofanobjectincollection.

Remarks

YoucanusetheDeletemethodtodeleteacurrentrecordfromaRecordsetoramemberfromacollection,suchasastoredtablefromadatabase,astoredfieldfromatable,orastoredindexfromatable.

Recordsets

ARecordsetmustcontainacurrentrecordbeforeyouuseDelete;otherwise,arun-timeerroroccurs.

InanupdatableRecordsetobject,Deleteremovesthecurrentrecordandmakesitinaccessible.Althoughyoucan'teditorusethedeletedrecord,itremainscurrent.Onceyoumovetoanotherrecord,however,youcan'tmakethedeletedrecordcurrentagain.SubsequentreferencestoadeletedrecordinaRecordsetareinvalidandproduceanerror.

YoucanundoarecorddeletionifyouusetransactionsandtheRollbackmethod.

Ifthebasetableistheprimarytableinacascadingdeleterelationship,deletingthecurrentrecordmayalsodeleteoneormorerecordsinaforeigntable.

NoteToadd,edit,ordeletearecord,theremustbeauniqueindexontherecordintheunderlyingdatasource.Ifnot,a"Permissiondenied"errorwilloccurontheAddNew,Delete,orEditmethodcallinaMicrosoftJetworkspace,oran"Invalidargument"errorwilloccurontheUpdatemethodcallinanODBCDirectworkspace.

Collections

YoucanusetheDeletemethodtodeleteapersistentobject.However,ifthecollectionisaDatabases,Recordsets,orWorkspacescollection(eachofwhichisstoredonlyinmemory),youcanremoveanopenor

activeobjectonlybyclosingthatobjectwiththeClosemethod.

Thedeletionofastoredobjectoccursimmediately,butyoushouldusetheRefreshmethodonanyothercollectionsthatmaybeaffectedbychangestothedatabasestructure.

WhenyoudeleteaTableDefobjectfromtheTableDefscollection,youdeletethetabledefinitionandthedatainthetable.

ThefollowingtablelistssomelimitationsoftheDeletemethod.Theobjectinthefirstcolumncontainsthecollectioninthesecondcolumn.Thethirdcolumnindicatesifyoucandeleteanobjectfromthatcollection(forexample,youcanneverdeleteaContainerobjectfromtheContainerscollectionofaDatabaseobject).

Object Collection CanyouusetheDeletemethod?

DBEngine Workspaces No.Closingtheobjectsdeletesthem.

DBEngine Errors No

Workspace Connections No.Closingtheobjectsdeletesthem.

Workspace Databases No.Closingtheobjectsdeletesthem.

Workspace Groups YesWorkspace Users YesConnection QueryDefs No

Connection Recordsets No.Closingtheobjectsdeletesthem.

Database Containers NoDatabase QueryDefs Yes

Database Recordsets No.Closingtheobjectsdeletesthem.

Database Relations YesDatabase TableDefs YesGroup Users YesUser Groups YesContainer Documents NoQueryDef Fields No

QueryDef Parameters NoRecordset Fields No

Relation Fields OnlywhentheRelationobjectisanew,unappendedobject.

TableDef Fields

OnlywhentheTableDefobjectisnewandhasn’tbeenappendedtothedatabase,orwhentheUpdatablepropertyoftheTableDefissettoTrue.

TableDef Indexes

OnlywhentheTableDefobjectisnewandhasn’tbeenappendedtothedatabase,orwhentheUpdatablepropertyoftheTableDefissettoTrue.

Index FieldsOnlywhentheIndexobjectisnewandhasn’tbeenappendedtothedatabase.

Database,Field,Index,QueryDef,TableDef Properties Onlywhenthepropertyisuser-

defined.DBEngine,Parameter,Recordset,Workspace Properties No

EditMethod

CopiesthecurrentrecordfromanupdatableRecordsetobjecttothecopybufferforsubsequentediting.

Syntax

recordset.Edit

Therecordsetplaceholderrepresentsanopen,updatableRecordsetobjectthatcontainstherecordyouwanttoedit.

Remarks

OnceyouusetheEditmethod,changesmadetothecurrentrecord'sfieldsarecopiedtothecopybuffer.Afteryoumakethedesiredchangestotherecord,usetheUpdatemethodtosaveyourchanges.

ThecurrentrecordremainscurrentafteryouuseEdit.

CautionIfyoueditarecordandthenperformanyoperationthatmovestoanotherrecord,butwithoutfirstusingUpdate,yourchangesarelostwithoutwarning.Inaddition,ifyoucloserecordsetorendthe

procedurewhichdeclarestheRecordsetortheparentDatabaseorConnectionobject,youreditedrecordisdiscardedwithoutwarning.

UsingEditproducesanerrorif:

Thereisnocurrentrecord.

TheConnection,Database,orRecordsetobjectwasopenedasread-only.

Nofieldsintherecordareupdatable.

TheDatabaseorRecordsetwasopenedforexclusiveusebyanotheruser(MicrosoftJetworkspace).

Anotheruserhaslockedthepagecontainingyourrecord(MicrosoftJetworkspace).

InaMicrosoftJetworkspace,whentheRecordsetobject'sLockEditspropertysettingisTrue(pessimisticallylocked)inamultiuserenvironment,therecordremainslockedfromthetimeEditisuseduntiltheupdateiscomplete.IftheLockEditspropertysettingisFalse(optimisticallylocked),therecordislockedandcomparedwiththepre-editedrecordjustbeforeit'supdatedinthedatabase.IftherecordhaschangedsinceyouusedtheEditmethod,theUpdateoperationfailswitharun-timeerrorifyouuseOpenRecordsetwithoutspecifyingdbSeeChanges.Bydefault,MicrosoftJet-connectedODBCandinstallableISAMdatabasesalwaysuseoptimisticlocking.

InanODBCDirectworkspace,onceyouedit(anduseUpdatetoupdate)arecord’sprimarykeyfield,youcannolongereditfieldsinthatrecorduntilyouclosetheRecordset,andthenretrievetherecordagaininasubsequentquery.

NoteToadd,edit,ordeletearecord,theremustbeauniqueindexontherecordintheunderlyingdatasource.Ifnot,a"Permissiondenied"errorwilloccurontheAddNew,Delete,orEditmethodcallinaMicrosoftJetworkspace,oran"Invalidargument"errorwilloccurontheUpdatecallinanODBCDirectworkspace.

ExecuteMethod

RunsanactionqueryorexecutesanSQLstatementonaspecifiedConnectionorDatabaseobject.

Syntax

object.Executesource,options

querydef.Executeoptions

TheExecutemethodsyntaxhastheseparts.

Part Description

object AConnectionorDatabaseobjectvariableonwhichthequerywillrun.

querydef AnobjectvariablethatrepresentstheQueryDefobjectwhoseSQLpropertysettingspecifiestheSQLstatementtoexecute.

source AStringthatisanSQLstatementortheNamepropertyvalueofaQueryDefobject.

optionsOptional.Aconstantorcombinationofconstantsthatdeterminesthedataintegritycharacteristicsofthequery,asspecifiedinSettings.

Settings

Youcanusethefollowingconstantsforoptions.


dbDenyWrite Denieswritepermissiontootherusers(MicrosoftJetworkspacesonly).

dbInconsistent (Default)Executesinconsistentupdates(MicrosoftJetworkspacesonly).

dbConsistent Executesconsistentupdates(MicrosoftJetworkspacesonly).

dbSQLPassThroughExecutesanSQLpass-throughquery.SettingthisoptionpassestheSQLstatementtoanODBCdatabaseforprocessing(MicrosoftJetworkspacesonly).

dbFailOnError Rollsbackupdatesifanerroroccurs(MicrosoftJetworkspacesonly).

dbSeeChanges Generatesarun-timeerrorifanotheruserischangingdatayouareediting(MicrosoftJetworkspacesonly).

dbRunAsync Executesthequeryasynchronously(ODBCDirectConnectionandQueryDefobjectsonly).

dbExecDirectExecutesthestatementwithoutfirstcallingSQLPrepareODBCAPIfunction(ODBCDirectConnectionandQueryDefobjectsonly).

NoteTheconstantsdbConsistentanddbInconsistentaremutuallyexclusive.Youcanuseoneortheother,butnotbothinagiveninstanceofOpenRecordset.UsingbothdbConsistentanddbInconsistentcausesanerror.

Remarks

TheExecutemethodisvalidonlyforactionqueries.IfyouuseExecutewithanothertypeofquery,anerroroccurs.Becauseanactionquerydoesn'treturnanyrecords,Executedoesn'treturnaRecordset.(ExecutinganSQLpass-throughqueryinanODBCDirectworkspacewillnotreturnanerrorifaRecordsetisn'treturned.)

UsetheRecordsAffectedpropertyoftheConnection,Database,or

QueryDefobjecttodeterminethenumberofrecordsaffectedbythemostrecentExecutemethod.Forexample,RecordsAffectedcontainsthenumberofrecordsdeleted,updated,orinsertedwhenexecutinganactionquery.WhenyouusetheExecutemethodtorunaquery,theRecordsAffectedpropertyoftheQueryDefobjectissettothenumberofrecordsaffected.

InaMicrosoftJetworkspace,ifyouprovideasyntacticallycorrectSQLstatementandhavetheappropriatepermissions,theExecutemethodwon'tfail—evenifnotasinglerowcanbemodifiedordeleted.Therefore,alwaysusethedbFailOnErroroptionwhenusingtheExecutemethodtorunanupdateordeletequery.Thisoptiongeneratesarun-timeerrorandrollsbackallsuccessfulchangesifanyoftherecordsaffectedarelockedandcan'tbeupdatedordeleted.

InearlierversionsoftheMicrosoftJetDatabaseEngine,SQLstatementswereautomaticallyembeddedinimplicittransactions.IfpartofastatementexecutedwithdbFailOnErrorfailed,theentirestatementwouldberolledback.Toimproveperformance,theseimplicittransactionswereremovedstartingwithversion3.5.IfyouareupdatingolderDAOcode,besuretoconsiderusingexplicittransactionsaroundExecutestatements.

ForbestperformanceinaMicrosoftJetworkspace,especiallyinamultiuserenvironment,nesttheExecutemethodinsideatransaction.UsetheBeginTransmethodonthecurrentWorkspaceobject,thenusetheExecutemethod,andcompletethetransactionbyusingtheCommitTransmethodontheWorkspace.Thissaveschangesondiskandfreesanylocksplacedwhilethequeryisrunning.

InanODBCDirectworkspace,ifyouincludetheoptionaldbRunAsyncconstant,thequeryrunsasynchronously.Todeterminewhetheranasynchronousqueryisstillexecuting,checkthevalueoftheStillExecutingpropertyontheobjectfromwhichtheExecutemethodwascalled.ToterminateexecutionofanasynchronousExecutemethodcall,usetheCancelmethod.

ForODBCDirect,usesinglequotestosignifystringsoranerrorwillbe

returned.

FillCacheMethod

FillsallorapartofalocalcacheforaRecordsetobjectthatcontainsdatafromaMicrosoftJet-connectedODBCdatasource(MicrosoftJet-connectedODBCdatabasesonly).

Syntax

recordset.FillCacherows,startbookmark

TheFillCachemethodsyntaxhastheseparts.

Part Description

recordsetAnobjectvariablethatrepresentsaRecordsetobjectcreatedfromanODBCdatasource,suchasaTableDefrepresentingalinkedtableoraQueryDefobjectderivedfromsuchaTableDef.

rowsOptional.AVariant(Integersubtype)thatspecifiesthenumberofrowstostoreinthecache.Ifyouomitthisargument,thevalueisdeterminedbytheCacheSizepropertysetting.

startbookmark

Optional.AVariant(Stringsubtype)thatspecifiesabookmark.Thecacheisfilledstartingfromtherecordindicatedbythisbookmark.Ifyouomitthisargument,thecacheisfilledstartingfromtherecordindicatedbytheCacheStartproperty.

Remarks

Cachingimprovestheperformanceofanapplicationthatretrievesdatafromaremoteserver.Acacheisspaceinlocalmemorythatholdsthedatamostrecentlyretrievedfromtheserver;thisassumesthatthedatawillprobablyberequestedagainwhiletheapplicationisrunning.Whenauserrequestsdata,theMicrosoftJetdatabaseenginechecksthecacheforthedatafirstratherthanretrievingitfromtheserver,whichtakesmoretime.Thecachedoesn'tsavedatathatdoesn'tcomefromanODBCdatasource.

Ratherthanwaitingforthecachetobefilledwithrecordsastheyareretrieved,youcanusetheFillCachemethodtoexplicitlyfillthecacheatanytime.ThisisafasterwaytofillthecachebecauseFillCacheretrievesseveralrecordsatonceinsteadofoneatatime.Forexample,whileyouvieweachscreenfulofrecords,yourapplicationusesFillCachetoretrievethenextscreenfulofrecordsforviewing.

AnyMicrosoftJet-connectedODBCdatasourcethatyouaccesswithRecordsetobjectscanhavealocalcache.Tocreatethecache,openaRecordsetobjectfromtheremotedatasource,andthensettheCacheSizeandCacheStartpropertiesoftheRecordset.

IfrowsandstartbookmarkcreatearangeofrecordsthatispartiallyorentirelyoutsidetherangeofrecordsspecifiedbytheCacheSizeandCacheStartproperties,theportionoftherecordsetoutsidethisrangeisignoredandwillnotbeloadedintothecache.

IfFillCacherequestsmorerecordsthanthenumberremainingintheremotedatasource,MicrosoftJetretrievesonlytheremainingrecords,andnoerroroccurs.

Notes

Recordsretrievedfromthecachedon'treflectconcurrentchangesthatotherusersmadetothesourcedata.

FillCacheonlyretrievesrecordsnotalreadycached.Toforceanupdateofallthecacheddata,settheCacheSizepropertyoftheRecordsetto0,resetittothesizeofthecacheyouoriginallyrequested,andthenuseFillCache.

FindFirst,FindLast,FindNext,FindPreviousMethods

Locatesthefirst,last,next,orpreviousrecordinadynaset-orsnapshot-typeRecordsetobjectthatsatisfiesthespecifiedcriteriaandmakesthatrecordthecurrentrecord(MicrosoftJetworkspacesonly).

Syntax

recordset.{FindFirst|FindLast|FindNext|FindPrevious}criteria

TheFindmethodshavetheseparts.

Part Description

recordset Anobjectvariablethatrepresentsanexistingdynaset-orsnapshot-typeRecordsetobject.

criteria AStringusedtolocatetherecord.ItisliketheWHEREclauseinanSQLstatement,butwithoutthewordWHERE.

Remarks

Ifyouwanttoincludealltherecordsinyoursearch—notjustthosethatmeetaspecificcondition—usetheMovemethodstomovefromrecord

mk:@MSITStore:daosdk.chm::/dajsql02_91t1.htm

torecord.Tolocatearecordinatable-typeRecordset,usetheSeekmethod.

Ifarecordmatchingthecriteriaisn'tlocated,thecurrentrecordpointerisunknown,andtheNoMatchpropertyissettoTrue.Ifrecordsetcontainsmorethanonerecordthatsatisfiesthecriteria,FindFirstlocatesthefirstoccurrence,FindNextlocatesthenextoccurrence,andsoon.

EachoftheFindmethodsbeginsitssearchfromthelocationandinthedirectionspecifiedinthefollowingtable.

Findmethod Beginssearchingat SearchdirectionFindFirst BeginningofrecordsetEndofrecordset

FindLast Endofrecordset Beginningofrecordset

FindNext Currentrecord Endofrecordset

FindPrevious Currentrecord Beginningofrecordset

WhenyouusetheFindLastmethod,theMicrosoftJetdatabaseenginefullypopulatesyourRecordsetbeforebeginningthesearch,ifthishasn'talreadyhappened.

UsingoneoftheFindmethodsisn'tthesameasusingaMovemethod,however,whichsimplymakesthefirst,last,next,orpreviousrecordcurrentwithoutspecifyingacondition.YoucanfollowaFindoperationwithaMoveoperation.

AlwayscheckthevalueoftheNoMatchpropertytodeterminewhethertheFindoperationhassucceeded.Ifthesearchsucceeds,NoMatchisFalse.Ifitfails,NoMatchisTrueandthecurrentrecordisn'tdefined.Inthiscase,youmustpositionthecurrentrecordpointerbacktoavalidrecord.

UsingtheFindmethodswithMicrosoftJet-connectedODBC-accessedrecordsetscanbeinefficient.Youmayfindthatrephrasingyourcriteriatolocateaspecificrecordisfaster,especiallywhenworkingwithlarge

recordsets.

InanODBCDirectworkspace,theFindandSeekmethodsarenotavailableonanytypeofRecordsetobject,becauseexecutingaFindorSeekthroughanODBCconnectionisnotveryefficientoverthenetwork.Instead,youshoulddesignthequery(thatis,usingthesourceargumenttotheOpenRecordsetmethod)withanappropriateWHEREclausethatrestrictsthereturnedrecordstoonlythosethatmeetthecriteriayouwouldotherwiseuseinaFindorSeekmethod.

WhenworkingwithMicrosoftJet-connectedODBCdatabasesandlargedynaset-typeRecordsetobjects,youmightdiscoverthatusingtheFindmethodsorusingtheSortorFilterpropertyisslow.Toimproveperformance,useSQLquerieswithcustomizedORDERBYorWHEREclauses,parameterqueries,orQueryDefobjectsthatretrievespecificindexedrecords.

YoushouldusetheU.S.dateformat(month-day-year)whenyousearchforfieldscontainingdates,evenifyou'renotusingtheU.S.versionoftheMicrosoftJetdatabaseengine;otherwise,thedatamaynotbefound.UsetheVisualBasicFormatfunctiontoconvertthedate.Forexample:

rstEmployees.FindFirst"HireDate>#"_&Format(mydate,'m-d-yy')&"#"

Ifcriteriaiscomposedofastringconcatenatedwithanon-integervalue,andthesystemparametersspecifyanon-U.S.decimalcharactersuchasacomma(forexample,strSQL="PRICE>"&lngPrice,andlngPrice=125,50),anerroroccurswhenyoutrytocallthemethod.Thisisbecauseduringconcatenation,thenumberwillbeconvertedtoastringusingyoursystem'sdefaultdecimalcharacter,andMicrosoftJetSQLonlyacceptsU.S.decimalcharacters.

Notes

Forbestperformance,thecriteriashouldbeineithertheform"field=value"wherefieldisanindexedfieldintheunderlying

basetable,or"fieldLIKEprefix"wherefieldisanindexedfieldintheunderlyingbasetableandprefixisaprefixsearchstring(forexample,"ART*").

Ingeneral,forequivalenttypesofsearches,theSeekmethodprovidesbetterperformancethantheFindmethods.Thisassumesthattable-typeRecordsetobjectsalonecansatisfyyourneeds.

GetChunkMethod

ReturnsalloraportionofthecontentsofaMemoorLongBinaryFieldobjectintheFieldscollectionofaRecordsetobject.

Syntax

Setvariable=recordset!field.GetChunk(offset,numbytes)

TheGetChunkmethodsyntaxhastheseparts.

Part Description

variable AVariant(Stringsubtype)thatreceivesthedatafromtheFieldobjectnamedbyfield.

recordset AnobjectvariablethatrepresentstheRecordsetobjectcontainingtheFieldscollection.

fieldAnobjectvariablethatrepresentsaFieldobjectwhoseTypepropertyissettodbMemo(Memo)ordbLongBinary(LongBinary).

offset ALongvalueequaltothenumberofbytestoskipbeforecopyingbegins.

numbytes ALongvalueequaltothenumberofbytesyouwanttoreturn.

Remarks

ThebytesreturnedbyGetChunkareassignedtovariable.UseGetChunktoreturnaportionofthetotaldatavalueatatime.YoucanusetheAppendChunkmethodtoreassemblethepieces.

Ifoffsetis0,GetChunkbeginscopyingfromthefirstbyteofthefield.

Ifnumbytesisgreaterthanthenumberofbytesinthefield,GetChunkreturnstheactualnumberofremainingbytesinthefield.

CautionUseaMemofieldfortext,andputbinarydataonlyinLongBinaryfields.Doingotherwisewillcauseundesirableresults.

GetRowsMethod

RetrievesmultiplerowsfromaRecordsetobject.

Syntax

SetvarArray=recordset.GetRows(numrows)

TheGetRowsmethodsyntaxhasthefollowingparts.

Part DescriptionvarArray AVariantthatstoresthereturneddata.recordset AnobjectvariablethatrepresentsaRecordsetobject.

numrows AVariantthatisequaltothenumberofrowstoretrieve.

Remarks

UsetheGetRowsmethodtocopyrecordsfromaRecordset.GetRowsreturnsatwo-dimensionalarray.Thefirstsubscriptidentifiesthefieldandthesecondidentifiestherownumber.Forexample,intFieldrepresentsthefield,andintRecordidentifiestherownumber:

avarRecords(intField,intRecord)

Togetthefirstfieldvalueinthesecondrowreturned,usecodelikethefollowing:

field1=avarRecords(0,1)

Togetthesecondfieldvalueinthefirstrow,usecodelikethefollowing:

field2=avarRecords(1,0)

TheavarRecordsvariableautomaticallybecomesatwo-dimensionalarraywhenGetRowsreturnsdata.

Ifyourequestmorerowsthanareavailable,thenGetRowsreturnsonlythenumberofavailablerows.YoucanusetheVisualBasicforApplicationsUBoundfunctiontodeterminehowmanyrowsGetRowsactuallyretrieved,becausethearrayissizedtofitthenumberofreturnedrows.Forexample,ifyoureturnedtheresultsintoaVariantcalledvarA,youcouldusethefollowingcodetodeterminehowmanyrowswereactuallyreturned:

numReturned=UBound(varA,2)+1

Youneedtouse"+1"becausethefirstrowreturnedisinthe0elementofthearray.Thenumberofrowsthatyoucanretrieveisconstrainedbytheamountofavailablememory.Youshouldn'tuseGetRowstoretrieveanentiretableintoanarrayifitislarge.

BecauseGetRowsreturnsallfieldsoftheRecordsetintothearray,includingMemoandLongBinaryfields,youmightwanttouseaquerythatrestrictsthefieldsreturned.

AfteryoucallGetRows,thecurrentrecordispositionedatthenextunreadrow.Thatis,GetRowshasthesameeffectonthecurrentrecordasMovenumrows.

IfyouaretryingtoretrievealltherowsbyusingmultipleGetRowscalls,

usetheEOFpropertytobesurethatyou'reattheendoftheRecordset.GetRowsreturnslessthanthenumberrequestedifit'sattheendoftheRecordset,orifitcan'tretrievearowintherangerequested.Forexample,ifyou'retryingtoretrieve10records,butyoucan'tretrievethefifthrecord,GetRowsreturnsfourrecordsandmakesthefifthrecordthecurrentrecord.Thiswillnotgeneratearun-timeerror.Thismightoccurifanotheruserdeletesarecordinadynaset-typeRecordset.Seetheexampleforademonstrationofhowtohandlethis.

IdleMethod

Suspendsdataprocessing,enablingtheMicrosoftJetdatabaseenginetocompleteanypendingtasks,suchasmemoryoptimizationorpagetimeouts(MicrosoftJetworkspacesonly).

Syntax

DBEngine.Idle[dbRefreshCache]

Remarks

TheIdlemethodallowstheMicrosoftJetdatabaseenginetoperformbackgroundtasksthatmaynotbeup-to-datebecauseofintensedataprocessing.Thisisoftentrueinmultiuser,multitaskingenvironmentsthatdon'thaveenoughbackgroundprocessingtimetokeepallrecordsinaRecordsetcurrent.

Usually,readlocksareremovedanddatainlocaldynaset-typeRecordsetobjectsareupdatedonlywhennootheractions(includingmousemovements)occur.IfyouperiodicallyusetheIdlemethod,MicrosoftJetcancatchuponbackgroundprocessingtasksbyreleasingunneededreadlocks.

SpecifyingtheoptionaldbRefreshCacheargumentrefreshesmemorywithonlythemostcurrentdatafromthe.mdbfile.ThedbForceOSFlushargumentforcespendingwritesto.mdbfilesaspartoftheCommitTransmethod.

Youdon'tneedtousethismethodinsingle-userenvironmentsunlessmultipleinstancesofanapplicationarerunning.TheIdlemethodmayincreaseperformanceinamultiuserenvironmentbecauseitforcesthedatabaseenginetowritedatatodisk,releasinglocksonmemory.

NoteYoucanalsoreleasereadlocksbymakingoperationspartofatransaction.

MakeReplicaMethod

Makesanewreplicafromanotherdatabasereplica(MicrosoftJetworkspacesonly).

Syntax

database.MakeReplicareplica,description,options

TheMakeReplicamethodsyntaxhasthefollowingparts.

Part Description

database AnobjectvariablethatrepresentsanexistingDatabasethatisareplica.

replica AStringthatisthepathandfilenameofthenewreplica.Ifreplicaisanexistingfilename,thenanerroroccurs.

description AStringthatdescribesthereplicathatyouarecreating.

optionsOptional.Aconstantorcombinationofconstantsthatspecifiescharacteristicsofthereplicayouarecreating,asspecifiedinSettings.

Settings

Youcanuseoneormoreofthefollowingconstantsintheoptions

argument.

Constant DescriptiondbRepMakePartial Createsapartialreplica.

dbRepMakeReadOnly

Preventsusersfrommodifyingthereplicableobjectsofthenewreplica;however,whenyousynchronizethenewreplicawithanothermemberofthereplicaset,designanddatachangeswillbepropagatedtothenewreplica.

Remarks

AnewlycreatedpartialreplicawillhaveallReplicaFilterpropertiessettoFalse,meaningthatnodatawillbeinthetables.

MoveMethod

MovesthepositionofthecurrentrecordinaRecordsetobject.

Syntax

recordset.Moverows,start

TheMovemethodsyntaxhastheseparts.

Part Description

recordset AnobjectvariablethatrepresentstheRecordsetobjectwhosecurrentrecordpositionisbeingmoved.

rows

AsignedLongvaluespecifyingthenumberofrowsthepositionwillmove.Ifrowsisgreaterthan0,thepositionismovedforward(towardtheendofthefile).Ifrowsislessthan0,thepositionismovedbackward(towardthebeginningofthefile).

startbookmarkOptional.AVariant(Stringsubtype)valueidentifyingabookmark.Ifyouspecifystartbookmark,themovebeginsrelativetothisbookmark.Otherwise,Movebeginsfromthecurrentrecord.

Remarks

IfyouuseMovetopositionthecurrentrecordpointerbeforethefirst

record,thecurrentrecordpointermovestothebeginningofthefile.IftheRecordsetcontainsnorecordsanditsBOFpropertyisTrue,usingthismethodtomovebackwardcausesanerror.

IfyouuseMovetopositionthecurrentrecordpointerafterthelastrecord,thecurrentrecordpointerpositionmovestotheendofthefile.IftheRecordsetcontainsnorecordsanditsEOFpropertyisTrue,thenusingthismethodtomoveforwardcausesanerror.

IfeithertheBOForEOFpropertyisTrueandyouattempttousetheMovemethodwithoutavalidbookmark,arun-timeerroroccurs.

Notes

WhenyouuseMoveonaforward-only-typeRecordsetobject,therowsargumentmustbeapositiveintegerandbookmarksaren'tallowed.Thismeansyoucanonlymoveforward.

Tomakethefirst,last,next,orpreviousrecordinaRecordsetthecurrentrecord,useeithertheMoveFirst,MoveLast,MoveNext,orMovePreviousmethod.

UsingMovewithrowsequalto0isaneasywaytoretrievetheunderlyingdataforthecurrentrecord.Thisisusefulifyouwanttomakesurethatthecurrentrecordhasthemostrecentdatafromthebasetables.ItwillalsocancelanypendingEditorAddNewcalls.

MoveFirst,MoveLast,MoveNext,MovePreviousMethods

Movetothefirst,last,next,orpreviousrecordinaspecifiedRecordsetobjectandmakethatrecordthecurrentrecord.

Syntax

recordset.{MoveFirst|MoveLast[dbRunAsync]|MoveNext|MovePrevious}

TherecordsetplaceholderisanobjectvariablethatrepresentsanopenRecordsetobject.

Remarks

UsetheMovemethodstomovefromrecordtorecordwithoutapplyingacondition.

CautionIfyoueditthecurrentrecord,besureyouusetheUpdatemethodtosavethechangesbeforeyoumovetoanotherrecord.Ifyoumovetoanotherrecordwithoutupdating,yourchangesarelostwithoutwarning.

WhenyouopenaRecordset,thefirstrecordiscurrentandtheBOFpropertyisFalse.IftheRecordsetcontainsnorecords,theBOFpropertyisTrue,andthereisnocurrentrecord.

IfthefirstorlastrecordisalreadycurrentwhenyouuseMoveFirstorMoveLast,thecurrentrecorddoesn'tchange.

IfyouuseMovePreviouswhenthefirstrecordiscurrent,theBOFpropertyisTrue,andthereisnocurrentrecord.IfyouuseMovePreviousagain,anerroroccurs,andBOFremainsTrue.

IfyouuseMoveNextwhenthelastrecordiscurrent,theEOFpropertyisTrue,andthereisnocurrentrecord.IfyouuseMoveNextagain,anerroroccurs,andEOFremainsTrue.

Ifrecordsetreferstoatable-typeRecordset(MicrosoftJetworkspacesonly),movementfollowsthecurrentindex.YoucansetthecurrentindexbyusingtheIndexproperty.Ifyoudon'tsetthecurrentindex,theorderofreturnedrecordsisundefined.

ImportantYoucanusetheMoveLastmethodtofullypopulateadynaset-orsnapshot-typeRecordsettoprovidethecurrentnumberofrecordsintheRecordset.However,ifyouuseMoveLastinthisway,youcanslowdownyourapplication'sperformance.YoushouldonlyuseMoveLasttogetarecordcountifitisabsolutelynecessarytoobtainanaccuraterecordcountonanewlyopenedRecordset.IfyouusethedbRunAsyncconstantwithMoveLast,themethodcallisasynchronous.YoucanusetheStillExecutingpropertytodeterminewhentheRecordsetisfullypopulated,andyoucanusetheCancelmethodtoterminateexecutionoftheasynchronousMoveLastmethodcall.

Youcan'tusetheMoveFirst,MoveLast,andMovePreviousmethodsonaforward-only–typeRecordsetobject.

TomovethepositionofthecurrentrecordinaRecordsetobjectaspecificnumberofrecordsforwardorbackward,usetheMovemethod.

NewPasswordMethod

ChangesthepasswordofanexistinguseraccountorMicrosoftJetdatabase(MicrosoftJetworkspacesonly).


Syntax

object.NewPasswordoldpassword,newpassword

TheNewPasswordmethodsyntaxhastheseparts.

Part Description

objectAnobjectvariablethatrepresentstheUserobjectoraMicrosoftJet3.xDatabaseobjectwhosePasswordpropertyyouwanttochange.

oldpassword AStringthatisthecurrentsettingofthePasswordpropertyoftheUserorJet3.xDatabaseobject.AStringthatisthenewsettingofthePasswordpropertyoftheUserorJet3.xDatabaseobject.

newpasswordNoteUsestrongpasswordsthatcombineupper-andlowercaseletters,numbers,andsymbols.Weakpasswordsdon'tmixtheseelements.Strongpassword:Y6dh!et5.Weakpassword:House27.Useastrongpasswordthatyoucanremembersothatyoudon'thavetowriteitdown.

Remarks

Theoldpasswordandnewpasswordstringscanbeupto14characterslongandcanincludeanycharactersexcepttheASCIIcharacter0(null).Toclearthepassword,useazero-lengthstring("")fornewpassword.

Passwordsarecase-sensitive.

IfobjectreferstoaUserobjectthatisnotyetappendedtoaUserscollection,anerroroccurs.Tosetanewpassword,youmusteitherlogonastheuserwhoseaccountyou'rechanging,oryoumustbeamemberoftheAdminsgroup.ThePasswordpropertyofaUserobjectiswrite-only—userscan'treadthecurrentvalue.

IfobjectreferstoaMicrosoftJetversion3.0orlaterDatabaseobject,thismethodofferssomesecuritybymeansofpasswordprotection.WhenyoucreateoropenaMicrosoftJet3.x.mdbfile,partoftheConnectconnectionstringcandescribethepassword.

Ifadatabasehasnopassword,MicrosoftJetwillautomaticallycreateonebypassingazero-lengthstring("")fortheoldpassword.

CautionIfyouloseyourpassword,youcanneveropenthedatabaseagain.

NextRecordsetMethod

Getsthenextsetofrecords,ifany,returnedbyamulti-partselectqueryinanOpenRecordsetcall,andreturnsaBooleanvalueindicatingwhetheroneormoreadditionalrecordsarepending(ODBCDirectworkspacesonly).

Syntax

boolean=recordset.NextRecordset

TheNextRecordsetmethodsyntaxhastheseparts:

Part Description

boolean

ABooleanvariable.Trueindicatesthenextsetofrecordsisavailableinrecordset;Falseindicatesthatnomorerecordsarependingandrecordsetisnowempty.

recordset AnexistingRecordsetvariabletowhichyouwanttoreturnpendingrecords.

Remarks

InanODBCDirectworkspace,youcanopenaRecordsetcontaining

morethanoneselectqueryinthesourceargumentofOpenRecordset,ortheSQLpropertyofaselectqueryQueryDefobject,asinthefollowingexample.

SELECTLastName,FirstNameFROMAuthorsWHERELastName='Smith';SELECTTitle,ISBNFROMTitlesWHEREPub_ID=9999

ThereturnedRecordsetwillopenwiththeresultsofthefirstquery.Toobtaintheresultsetsofrecordsfromsubsequentqueries,usetheNextRecordsetmethod.

Ifmorerecordsareavailable(thatis,therewasanotherselectqueryintheOpenRecordsetcallorintheSQLproperty),therecordsreturnedfromthenextquerywillbeloadedintotheRecordset,andNextRecordsetwillreturnTrue,indicatingthattherecordsareavailable.Whennomorerecordsareavailable(thatis,resultsofthelastselectqueryhavebeenloadedintotheRecordset),thenNextRecordsetwillreturnFalse,andtheRecordsetwillbeempty.

YoucanalsousetheCancelmethodtoflushthecontentsofaRecordset.However,Cancelalsoflushesanyadditionalrecordsnotyetloaded.

OpenConnectionMethod

OpensaConnectionobjectonanODBCdatasource(ODBCDirectworkspacesonly).

Syntax

Setconnection=workspace.OpenConnection(name,options,readonly,connect)

TheOpenConnectionmethodsyntaxhastheseparts.

Part Description

connection AConnectionobjectvariabletowhichthenewconnectionwillbeassigned.

workspace

Optional.AvariableofaWorkspaceobjectdatatypethatreferencestheexistingWorkspaceobjectthatwillcontainthenewconnection.

name Astringexpression.SeethediscussionunderRemarks.

options

Optional.AVariantthatsetsvariousoptionsfortheconnection,asspecifiedinSettings.Basedonthisvalue,theODBCdriver

managerpromptstheuserforconnectioninformationsuchasdatasourcename(DSN),username,andpassword.

readonly

Optional.ABooleanvaluethatisTrueiftheconnectionistobeopenedforread-onlyaccessandFalseiftheconnectionistobeopenedforread/writeaccess(default).

connect

Optional.AnODBCconnectstring.SeetheConnectpropertyforthespecificelementsandsyntaxofthisstring.Aprepended"ODBC;"isrequired.Ifconnectisomitted,theUIDand/orPWDwillbetakenfromtheUserNameandPasswordpropertiesoftheWorkspace.

Settings

Theoptionsargumentdeterminesifandwhentoprompttheusertoestablishtheconnection,andwhetherornottoopentheconnectionasynchronously.Youcanuseoneofthefollowingconstants.


dbDriverNoPrompt

TheODBCDriverManagerusestheconnectionstringprovidedindbnameandconnect.Ifyoudon'tprovidesufficientinformation,arun-timeerroroccurs.

dbDriverPrompt

TheODBCDriverManagerdisplaystheODBCDataSourcesdialogbox,whichdisplaysanyrelevantinformationsuppliedindbnameorconnect.TheconnectionstringismadeupoftheDSNthattheuserselectsviathedialogboxes,or,iftheuserdoesn'tspecifyaDSN,thedefaultDSNisused.

dbDriverComplete

Default.Iftheconnectargumentincludesallthenecessaryinformationtocompleteaconnection,theODBCDriverManagerusesthestringinconnect.OtherwiseitbehavesasitdoeswhenyouspecifydbDriverPrompt.

dbDriverCompleteRequired

ThisoptionbehaveslikedbDriverCompleteexcepttheODBCdriverdisablesthepromptsforanyinformationnotrequiredtocompletethe

connection.

dbRunAsyncExecutethemethodasynchronously.Thisconstantmaybeusedwithanyoftheotheroptionsconstants.

Remarks

UsetheOpenConnectionmethodtoestablishaconnectiontoanODBCdatasourcefromanODBCDirectworkspace.TheOpenConnectionmethodissimilarbutnotequivalenttoOpenDatabase.ThemaindifferenceisthatOpenConnectionisavailableonlyinanODBCDirectworkspace.

IfyouspecifyaregisteredODBCdatasourcename(DSN)intheconnectargument,thenthenameargumentcanbeanyvalidstring,andwillalsoprovidetheNamepropertyfortheConnectionobject.IfavalidDSNisnotincludedintheconnectargument,thennamemustrefertoavalidODBCDSN,whichwillalsobetheNameproperty.IfneithernamenorconnectcontainsavalidDSN,theODBCdrivermanagercanbeset(viatheoptionsargument)toprompttheuserfortherequiredconnectioninformation.TheDSNsuppliedthroughthepromptthenprovidestheNameproperty.

OpenConnectionreturnsaConnectionobjectwhichcontainsinformationabouttheconnection.TheConnectionobjectissimilartoaDatabaseobject.TheprincipaldifferenceisthataDatabaseobjectusuallyrepresentsadatabase,althoughitcanbeusedtorepresentaconnectiontoanODBCdatasourcefromaMicrosoftJetworkspace.

OpenDatabaseMethod

OpensaspecifieddatabaseinaWorkspaceobjectandreturnsareferencetotheDatabaseobjectthatrepresentsit.

Syntax

Setdatabase=workspace.OpenDatabase(dbname,options,read-only,connect)

TheOpenDatabasemethodsyntaxhastheseparts.

Part Description

database AnobjectvariablethatrepresentstheDatabaseobjectthatyouwanttoopen.

workspace

Optional.AnobjectvariablethatrepresentstheexistingWorkspaceobjectthatwillcontainthedatabase.Ifyoudon'tincludeavalueforworkspace,OpenDatabaseusesthedefaultworkspace.

dbnameAStringthatisthenameofanexistingMicrosoftJetdatabasefile,orthedatasourcename(DSN)ofanODBCdatasource.SeetheNamepropertyformoreinformationaboutsettingthisvalue.

options Optional.AVariantthatsetsvariousoptionsforthedatabase,asspecifiedinSettings.

read-onlyOptional.AVariant(Booleansubtype)valuethatisTrueifyouwanttoopenthedatabasewithread-onlyaccess,orFalse(default)ifyouwanttoopenthedatabasewithread/writeaccess.

connect Optional.AVariant(Stringsubtype)thatspecifiesvariousconnectioninformation,includingpasswords.

Settings

ForMicrosoftJetworkspaces,youcanusethefollowingvaluesfortheoptionsargument.

Setting DescriptionTrue Opensthedatabaseinexclusivemode.

False (Default)Opensthedatabaseinsharedmode.

ForODBCDirectworkspaces,theoptionsargumentdeterminesifandwhentoprompttheusertoestablishtheconnection.Youcanuseoneofthefollowingconstants.


dbDriverNoPrompt

TheODBCDriverManagerusestheconnectionstringprovidedindbnameandconnect.Ifyoudon'tprovidesufficientinformation,arun-timeerroroccurs.

dbDriverPrompt

TheODBCDriverManagerdisplaystheODBCDataSourcesdialogbox,whichdisplaysanyrelevantinformationsuppliedindbnameorconnect.TheconnectionstringismadeupoftheDSNthattheuserselectsviathedialogboxes,or,iftheuserdoesn'tspecifyaDSN,thedefaultDSNisused.

dbDriverComplete

(Default)Iftheconnectanddbnameargumentsincludeallthenecessaryinformationtocompleteaconnection,theODBCDriverManagerusesthestringinconnect.OtherwiseitbehavesasitdoeswhenyouspecifydbDriverPrompt.ThisoptionbehaveslikedbDriverComplete

dbDriverCompleteRequired excepttheODBCdriverdisablesthepromptsforanyinformationnotrequiredtocompletetheconnection.

Remarks

Whenyouopenadatabase,itisautomaticallyaddedtotheDatabasescollection.Further,inanODBCDirectworkspace,theConnectionobjectcorrespondingtothenewDatabaseobjectisalsocreatedandappendedtotheConnectionscollectionofthesameWorkspaceobject.

Someconsiderationsapplywhenyouusedbname:

Ifitreferstoadatabasethatisalreadyopenforexclusiveaccessbyanotheruser,anerroroccurs.

Ifitdoesn'trefertoanexistingdatabaseorvalidODBCdatasourcename,anerroroccurs.

Ifit'sazero-lengthstring("")andconnectis"ODBC;",adialogboxlistingallregisteredODBCdatasourcenamesisdisplayedsotheusercanselectadatabase.

Ifyou'reopeningadatabasethroughanODBCDirectworkspaceandyouprovidetheDSNinconnect,youcansetdbnametoastringofyourchoicethatyoucanusetoreferencethisdatabaseinsubsequentcode.

Theconnectargumentisexpressedintwoparts:thedatabasetype,followedbyasemicolon(;)andtheoptionalarguments.Youmustfirstprovidethedatabasetype,suchas"ODBC;"or"FoxPro2.5;".Theoptionalargumentsfollowinnoparticularorder,separatedbysemicolons.Oneoftheparametersmaybethepassword(ifoneis

assigned).Forexample:

"FoxPro2.5;pwd=mypassword"

UsingtheNewPasswordmethodonaDatabaseobjectotherthananODBCDirectdatabasechangesthepasswordparameterthatappearsinthe";pwd=..."partofthisargument.Youmustsupplytheoptionsandread-onlyargumentstosupplyasourcestring.SeetheConnectpropertyforsyntax.

Tocloseadatabase,andthusremovetheDatabaseobjectfromtheDatabasescollection,usetheClosemethodontheobject.

NoteWhenyouaccessaMicrosoftJet-connectedODBCdatasource,youcanimproveyourapplication'sperformancebyopeningaDatabaseobjectconnectedtotheODBCdatasource,ratherthanbylinkingindividualTableDefobjectstospecifictablesintheODBCdatasource.

OpenRecordsetMethod

CreatesanewRecordsetobjectandappendsittotheRecordsetscollection.

Syntax

ForConnectionandDatabaseobjects:

Setrecordset=object.OpenRecordset(source,type,options,lockedits)

ForQueryDef,Recordset,andTableDefobjects:

Setrecordset=object.OpenRecordset(type,options,lockedits)

TheOpenRecordsetmethodsyntaxhastheseparts.

Part Description

recordset AnobjectvariablethatrepresentstheRecordsetobjectyouwanttoopen.

object AnobjectvariablethatrepresentsanexistingobjectfromwhichyouwanttocreatethenewRecordset.AStringspecifyingthesourceoftherecordsforthenewRecordset.Thesourcecanbeatablename,aqueryname,oran

source SQLstatementthatreturnsrecords.Fortable-typeRecordsetobjectsinMicrosoftJetdatabases,thesourcecanonlybeatablename.

type Optional.AconstantthatindicatesthetypeofRecordsettoopen,asspecifiedinSettings.

options Optional.AcombinationofconstantsthatspecifycharacteristicsofthenewRecordset,aslistedinSettings.

lockedits Optional.AconstantthatdeterminesthelockingfortheRecordset,asspecifiedinSettings.

Settings

Youcanuseoneofthefollowingconstantsforthetypeargument.


dbOpenTable Opensatable-typeRecordsetobject(MicrosoftJetworkspacesonly).

dbOpenDynamicOpensadynamic-typeRecordsetobject,whichissimilartoanODBCdynamiccursor.(ODBCDirectworkspacesonly)

dbOpenDynaset Opensadynaset-typeRecordsetobject,whichissimilartoanODBCkeysetcursor.

dbOpenSnapshot Opensasnapshot-typeRecordsetobject,whichissimilartoanODBCstaticcursor.

dbOpenForwardOnly Opensaforward-only-typeRecordsetobject.

NoteIfyouopenaRecordsetinaMicrosoftJetworkspaceandyoudon'tspecifyatype,OpenRecordsetcreatesatable-typeRecordset,ifpossible.Ifyouspecifyalinkedtableorquery,OpenRecordsetcreatesadynaset-typeRecordset.InanODBCDirectworkspace,thedefaultsettingisdbOpenForwardOnly.

Youcanuseacombinationofthefollowingconstantsfortheoptionsargument.


dbAppendOnly

AllowsuserstoappendnewrecordstotheRecordset,butpreventsthemfromeditingordeletingexistingrecords(MicrosoftJetdynaset-type

Recordsetonly).

dbSQLPassThroughPassesanSQLstatementtoaMicrosoftJet-connectedODBCdatasourceforprocessing(MicrosoftJetsnapshot-typeRecordsetonly).

dbSeeChanges

Generatesarun-timeerrorifoneuserischangingdatathatanotheruserisediting(MicrosoftJetdynaset-typeRecordsetonly).Thisisusefulinapplicationswheremultipleusershavesimultaneousread/writeaccesstothesamedata.

dbDenyWrite Preventsotherusersfrommodifyingoraddingrecords(MicrosoftJetRecordsetobjectsonly).

dbDenyRead Preventsotherusersfromreadingdatainatable(MicrosoftJettable-typeRecordsetonly).

dbForwardOnly

Createsaforward-onlyRecordset(MicrosoftJetsnapshot-typeRecordsetonly).Itisprovidedonlyforbackwardcompatibility,andyoushouldusethedbOpenForwardOnlyconstantinthetypeargumentinsteadofusingthisoption.

dbReadOnly

PreventsusersfrommakingchangestotheRecordset(MicrosoftJetonly).ThedbReadOnlyconstantinthelockeditsargumentreplacesthisoption,whichisprovidedonlyforbackwardcompatibility.

dbRunAsync Runsanasynchronousquery(ODBCDirectworkspacesonly).

dbExecDirect

RunsaquerybyskippingSQLPrepareanddirectlycallingSQLExecDirect(ODBCDirectworkspacesonly).Usethisoptiononlywhenyou’renotopeningaRecordsetbasedonaparameterquery.Formoreinformation,seethe"MicrosoftODBC3.0Programmer’sReference."

dbInconsistent Allowsinconsistentupdates(MicrosoftJetdynaset-typeandsnapshot-typeRecordsetobjectsonly).

dbConsistentAllowsonlyconsistentupdates(MicrosoftJetdynaset-typeandsnapshot-typeRecordsetobjectsonly).

NoteTheconstantsdbConsistentanddbInconsistentaremutuallyexclusive,andusingbothcausesanerror.Supplyingalockedits

argumentwhenoptionsusesthedbReadOnlyconstantalsocausesanerror.

Youcanusethefollowingconstantsforthelockeditsargument.


dbReadOnly

PreventsusersfrommakingchangestotheRecordset(defaultforODBCDirectworkspaces).YoucanusedbReadOnlyineithertheoptionsargumentorthelockeditsargument,butnotboth.Ifyouuseitforbotharguments,arun-timeerroroccurs.

dbPessimistic

UsespessimisticlockingtodeterminehowchangesaremadetotheRecordsetinamultiuserenvironment.Thepagecontainingtherecordyou'reeditingislockedassoonasyouusetheEditmethod(defaultforMicrosoftJetworkspaces).

dbOptimistic

UsesoptimisticlockingtodeterminehowchangesaremadetotheRecordsetinamultiuserenvironment.ThepagecontainingtherecordisnotlockeduntiltheUpdatemethodisexecuted.

dbOptimisticValue Usesoptimisticconcurrencybasedonrowvalues(ODBCDirectworkspacesonly).

dbOptimisticBatch Enablesbatchoptimisticupdating(ODBCDirectworkspacesonly).

Remarks

InaMicrosoftJetworkspace,ifobjectreferstoaQueryDefobject,oradynaset-orsnapshot-typeRecordset,orifsourcereferstoanSQLstatementoraTableDefthatrepresentsalinkedtable,youcan'tusedbOpenTableforthetypeargument;ifyoudo,arun-timeerroroccurs.IfyouwanttouseanSQLpass-throughqueryonalinkedtableinaMicrosoftJet-connectedODBCdatasource,youmustfirstsettheConnectpropertyofthelinkedtable'sdatabasetoavalidODBCconnectionstring.IfyouonlyneedtomakeasinglepassthroughaRecordsetopenedfromaMicrosoftJet-connectedODBCdatasource,youcanimproveperformancebyusingdbOpenForwardOnlyforthe

typeargument.

Ifobjectreferstoadynaset-orsnapshot-typeRecordset,thenewRecordsetisofthesametypeobject.Ifobjectreferstoatable-typeRecordsetobject,thetypeofthenewobjectisadynaset-typeRecordset.Youcan'topennewRecordsetobjectsfromforward-only–typeorODBCDirectRecordsetobjects.

InanODBCDirectworkspace,youcanopenaRecordsetcontainingmorethanoneselectqueryinthesourceargument,suchas

"SELECTLastName,FirstNameFROMAuthorsWHERELastName='Smith';SELECTTitle,ISBNFROMTitlesWHEREISBNLike'1-55615-*'"

ThereturnedRecordsetwillopenwiththeresultsofthefirstquery.Toobtaintheresultsetsofrecordsfromsubsequentqueries,usetheNextRecordsetmethod.


UsethedbSeeChangesconstantinaMicrosoftJetworkspaceifyouwanttotrapchangeswhiletwoormoreusersareeditingordeletingthesamerecord.Forexample,iftwousersstarteditingthesamerecord,thefirstusertoexecutetheUpdatemethodsucceeds.WhentheseconduserinvokestheUpdatemethod,arun-timeerroroccurs.Similarly,ifthesecondusertriestousetheDeletemethodtodeletetherecord,andthefirstuserhasalreadychangedit,arun-timeerroroccurs.

Typically,iftheusergetsthiserrorwhileupdatingarecord,yourcodeshouldrefreshthecontentsofthefieldsandretrievethenewlymodifiedvalues.Iftheerroroccurswhiledeletingarecord,yourcodecoulddisplaythenewrecorddatatotheuserandamessageindicatingthatthedatahasrecentlychanged.Atthispoint,yourcodecanrequestaconfirmationthattheuserstillwantstodeletetherecord.

YoushouldalsousethedbSeeChangesconstantifyouopenaRecordsetinaMicrosoftJet-connectedODBCworkspaceagainstaMicrosoftSQLServer6.0(orlater)tablethathasanIDENTITYcolumn,otherwiseanerrormayresult.

InanODBCDirectworkspace,youcanexecuteasynchronousqueriesbysettingthedbRunAsyncconstantintheoptionsargument.Thisallowsyourapplicationtocontinueprocessingotherstatementswhilethequeryrunsinthebackground.But,youcannotaccesstheRecordsetdatauntilthequeryhascompleted.Todeterminewhetherthequeryhasfinishedexecuting,checktheStillExecutingpropertyofthenewRecordset.Ifthequerytakeslongertocompletethanyouanticipated,youcanterminateexecutionofthequerywiththeCancelmethod.

OpeningmorethanoneRecordsetonanODBCdatasourcemayfailbecausetheconnectionisbusywithapriorOpenRecordsetcall.Onewayaroundthisistouseaserver-sidecursorandODBCDirect,iftheserversupportsthis.AnothersolutionistofullypopulatetheRecordsetbyusingtheMoveLastmethodassoonastheRecordsetisopened.

IfyouopenaConnectionobjectwithDefaultCursorDriversettodbUseClientBatchCursor,youcanopenaRecordsettocachechangestothedata(knownasbatchupdating)inanODBCDirectworkspace.IncludedbOptimisticBatchinthelockeditsargumenttoenableupdatecaching.SeetheUpdatemethodtopicfordetailsabouthowtowritechangestodiskimmediately,ortocachechangesandwritethemtodiskasabatch.

ClosingaRecordsetwiththeClosemethodautomaticallydeletesitfromtheRecordsetscollection.

NoteIfsourcereferstoanSQLstatementcomposedofastringconcatenatedwithanon-integervalue,andthesystemparametersspecifyanon-U.S.decimalcharactersuchasacomma(forexample,strSQL="PRICE>"&lngPrice,andlngPrice=125,50),anerroroccurswhenyoutrytoopentheRecordset.Thisisbecauseduringconcatenation,thenumberwillbeconvertedtoastringusingyoursystem'sdefaultdecimalcharacter,andSQLonlyacceptsU.S.decimalcharacters.

PopulatePartialMethod

Synchronizesanychangesinapartialreplicawiththefullreplica,clearsallrecordsinthepartialreplica,andthenrepopulatesthepartialreplicabasedonthecurrentreplicafilters.(MicrosoftJetdatabasesonly.)

Syntax

database.PopulatePartialdbname

ThePopulatePartialmethodsyntaxhasthefollowingparts.

Part Description

databaseAnobjectvariablethatreferencesthepartialreplicaDatabaseobjectthatyouwanttopopulate.

dbname Astringspecifyingthepathandnameofthefullreplicafromwhichtopopulaterecords.

Remarks

Whenyousynchronizeapartialreplicawithafullreplica,itispossibletocreate"orphaned"recordsinthepartialreplica.Forexample,supposeyouhaveaCustomerstablewithitsReplicaFiltersetto"Region=

'CA'".Ifauserchangesacustomer'sregionfromCAtoNYinthepartialreplica,andthenasynchronizationoccursviatheSynchronizemethod,thechangeispropagatedtothefullreplicabuttherecordcontainingNYinthepartialreplicaisorphanedbecauseitnowdoesn'tmeetthereplicafiltercriteria.

Tosolvetheproblemoforphanedrecords,youcanusethePopulatePartialmethod.ThePopulatePartialmethodissimilartotheSynchronizemethod,butitsynchronizesanychangeswiththefullreplica,removesallrecordsinthepartialreplica,andthenrepopulatesthepartialreplicabasedonthecurrentreplicafilters.Evenifyourreplicafiltershavenotchanged,PopulatePartialwillalwaysclearallrecordsinthepartialreplicaandrepopulateitbasedonthecurrentfilters.

Generally,youshouldusethePopulatePartialmethodwhenyoucreateapartialreplicaandwheneveryouchangeyourreplicafilters.Ifyourapplicationchangesreplicafilters,youshouldfollowthesesteps:

1. Synchronizeyourfullreplicawiththepartialreplicainwhichthefiltersarebeingchanged.

2. UsetheReplicaFilterandPartialReplicapropertiestomakethedesiredchangestothereplicafilter.

3. CallthePopulatePartialmethodtoremoveallrecordsfromthepartialreplicaandtransferallrecordsfromthefullreplicathatmeetthenewreplicafiltercriteria.

Ifareplicafilterhaschanged,andtheSynchronizemethodisinvokedwithoutfirstinvokingPopulatePartial,atrappableerroroccurs.

ThePopulatePartialmethodcanonlybeinvokedonapartialreplicathathasbeenopenedforexclusiveaccess.Furthermore,youcan'tcallthePopulatePartialmethodfromcoderunningwithinthepartialreplicaitself.Instead,openthepartialreplicaexclusivelyfromthefullreplicaor

anotherdatabase,thencallPopulatePartial.

NoteAlthoughPopulatePartialperformsaone-waysynchronizationbeforeclearingandrepopulatingthepartialreplica,itisstillagoodideatocallSynchronizebeforecallingPopulatePartial.ThisisbecauseifthecalltoSynchronizefails,atrappableerroroccurs.YoucanusethiserrortodecidewhetherornottoproceedwiththePopulatePartialmethod(whichremovesallrecordsinthepartialreplica).IfPopulatePartialiscalledbyitselfandanerroroccurswhilerecordsarebeingsynchronized,recordsinthepartialreplicawillstillbecleared,whichmaynotbethedesiredresult.

RefreshMethod

Updatestheobjectsinacollectiontoreflectthecurrentdatabase'sschema.

Syntax

collection.Refresh

Thecollectionplaceholderisanobjectvariablethatrepresentsapersistentcollection.

Remarks

Youcan'tusetheRefreshmethodwithcollectionsthataren'tpersistent,suchasConnections,Databases,Recordsets,Workspaces,ortheQueryDefscollectionofaConnectionobject.

TodeterminethepositionthattheMicrosoftJetdatabaseengineusesforFieldobjectsintheFieldscollectionofaQueryDef,Recordset,orTableDefobject,usetheOrdinalPositionpropertyofeachFieldobject.ChangingtheOrdinalPositionpropertyofaFieldobjectmaynotchangetheorderoftheFieldobjectsinthecollectionuntilyouusetheRefresh

method.

UsetheRefreshmethodinmultiuserenvironmentsinwhichotherusersmaychangethedatabase.Youmayalsoneedtouseitonanycollectionsthatareindirectlyaffectedbychangestothedatabase.Forexample,ifyouchangeaUserscollection,youmayneedtorefreshaGroupscollectionbeforeusingtheGroupscollection.

Acollectionisfilledwithobjectsthefirsttimeit'sreferredtoandwon'tautomaticallyreflectsubsequentchangesotherusersmake.Ifit'slikelythatanotheruserhaschangedacollection,usetheRefreshmethodonthecollectionimmediatelybeforecarryingoutanytaskinyourapplicationthatassumesthepresenceorabsenceofaparticularobjectinthecollection.Thiswillensurethatthecollectionisasup-to-dateaspossible.Ontheotherhand,usingRefreshcanunnecessarilyslowperformance.

RefreshLinkMethod

Updatestheconnectioninformationforalinkedtable(MicrosoftJetworkspacesonly).

Syntax

tabledef.RefreshLink

ThetabledefplaceholderspecifiestheTableDefobjectrepresentingthelinkedtablewhoseconnectioninformationyouwanttoupdate.

Remarks

Tochangetheconnectioninformationforalinkedtable,resettheConnectpropertyofthecorrespondingTableDefobjectandthenusetheRefreshLinkmethodtoupdatetheinformation.UsingRefreshLinkmethoddoesn'tchangethelinkedtable'spropertiesandRelationobjects.

ForthisconnectioninformationtoexistinallcollectionsassociatedwiththeTableDefobjectthatrepresentsthelinkedtable,youmustusetheRefreshmethodoneachcollection.

RegisterDatabaseMethod

EntersconnectioninformationforanODBCdatasourceintheWindowsRegistry.TheODBCdriverneedsconnectioninformationwhentheODBCdatasourceisopenedduringasession.

Syntax

DBEngine.RegisterDatabasedbname,driver,silent,attributes

TheRegisterDatabasemethodsyntaxhastheseparts.

Part Description

dbname

AStringthatisthenameusedintheOpenDatabasemethod.Itreferstoablockofdescriptiveinformationaboutthedatasource.Forexample,ifthedatasourceisanODBCremotedatabase,itcouldbethenameoftheserver.

driver

AStringthatisthenameoftheODBCdriver.Thisisn'tthenameoftheODBCdriverDLLfile.Forexample,SQLServerisadrivername,butSQLSRVR.dllisthenameofaDLLfile.YoumusthaveODBCandtheappropriatedriveralreadyinstalled.

silent

ABooleanthatisTrueifyoudon'twanttodisplaytheODBCdriverdialogboxesthatpromptfordriver-specificinformation;orFalseifyouwanttodisplaytheODBCdriverdialogboxes.If

silentisTrue,attributesmustcontainallthenecessarydriver-specificinformationorthedialogboxesaredisplayedanyway.

attributes AStringthatisalistofkeywordstobeaddedtotheWindowsRegistry.Thekeywordsareinacarriage-return–delimitedstring.

Remarks

Ifthedatabaseisalreadyregistered(connectioninformationisalreadyentered)intheWindowsRegistrywhenyouusetheRegisterDatabasemethod,theconnectioninformationisupdated.

IftheRegisterDatabasemethodfailsforanyreason,nochangesaremadetotheWindowsRegistry,andanerroroccurs.

FormoreinformationaboutODBCdriverssuchasSQLServer,seetheHelpfileprovidedwiththedriver.

YoushouldusetheODBCDataSourcesdialogboxintheControlPaneltoaddnewdatasources,ortomakechangestoexistingentries.However,ifyouusetheRegisterDatabasemethod,youshouldsetthesilentoptiontoTrue.

RepairDatabaseMethod

NoteTheRepairDatabasefunctionisnolongeravailable.UsetheCompactDatabasemethodinstead.

AttemptstorepairacorruptedMicrosoftJetdatabase(MicrosoftJetdatabasesonly).

Syntax

DBEngine.RepairDatabasedbname

ThedbnameargumentisaStringthatisthepathandfilenameforanexistingMicrosoftJetdatabasefile.Ifyouomitthepath,onlythecurrentdirectoryissearched.Ifyoursystemsupportstheuniformnamingconvention(UNC),youcanalsospecifyanetworkpath,suchas"\\server1\share1\dir1\db1.mdb".

Remarks

Youmustclosethedatabasespecifiedbydbnamebeforeyourepairit.Inamultiuserenvironment,otheruserscan'thavedbnameopenwhileyou'rerepairingit.Ifdbnameisn'tclosedorisn'tavailableforexclusive

use,anerroroccurs.

Thismethodattemptstorepairadatabasethatwasmarkedaspossiblycorruptbyanincompletewriteoperation.ThiscanoccurifanapplicationusingtheMicrosoftJetdatabaseengineisclosedunexpectedlybecauseofapoweroutageorcomputerhardwareproblem.Thedatabasewon'tbemarkedaspossiblycorruptifyouusetheClosemethodorifyouquityourapplicationinausualway.

TheRepairDatabasemethodalsoattemptstovalidateallsystemtablesandallindexes.Anydatathatcan'tberepairedisdiscarded.Ifthedatabasecan'tberepaired,arun-timeerroroccurs.

Whenyouattempttoopenorcompactacorrupteddatabase,arun-timeerrorusuallyoccurs.Insomesituations,however,acorrupteddatabasemaynotbedetected,andnoerroroccurs.It'sagoodideatoprovideyouruserswithawaytousetheRepairDatabasemethodinyourapplicationiftheirdatabasebehavesunpredictably.

SometypesofdatabasescanbecomecorruptedifauserendsanapplicationwithoutclosingDatabaseorRecordsetobjectsandtheMicrosoftJetdatabaseengine;MicrosoftWindowsdoesn'thaveachancetowritedatacachestodisk.Toavoidcorruptdatabases,establishproceduresforclosingapplicationsandshuttingdownsystemsthatensurethatallcachedpagesaresavedtothedatabase.Insomecases,powersuppliesthatcan'tbeinterruptedmaybenecessarytopreventaccidentaldatalossduringpowerfluctuations.

NoteAfterrepairingadatabase,it'salsoagoodideatocompactitusingtheCompactDatabasemethodtodefragmentthefileandtorecoverdiskspace.

RequeryMethod

UpdatesthedatainaRecordsetobjectbyre-executingthequeryonwhichtheobjectisbased.

Syntax

recordset.Requerynewquerydef

TheRequerymethodsyntaxhasthefollowingparts.

Part Description

recordsetAnobjectvariablethatrepresentsanexistingMicrosoftJetdynaset-,snapshot-,orforward-only–typeRecordsetobject,oranODBCDirectRecordsetobject.

newquerydef Optional.AVariantthatrepresentstheNamepropertyvalueofaQueryDefobject(MicrosoftJetworkspacesonly).

Remarks

UsethismethodtomakesurethataRecordsetcontainsthemostrecentdata.Thismethodre-populatesthecurrentRecordsetbyusingeitherthecurrentqueryparametersor(inaMicrosoftJetworkspace)thenewonessuppliedbythenewquerydefargument.

InanODBCDirectworkspace,iftheoriginalquerywasasynchronous,thenRequerywillalsoexecuteanasynchronousquery.

Ifyoudon'tspecifyanewquerydefargument,theRecordsetisre-populatedbasedonthesamequerydefinitionandparametersusedtooriginallypopulatetheRecordset.Anychangestotheunderlyingdatawillbereflectedduringthisre-population.Ifyoudidn'tuseaQueryDeftocreatetheRecordset,theRecordsetisre-createdfromscratch.

IfyouspecifytheoriginalQueryDefinthenewquerydefargument,thentheRecordsetisrequeriedusingtheparametersspecifiedbytheQueryDef.Anychangestotheunderlyingdatawillbereflectedduringthisre-population.ToreflectanychangestothequeryparametervaluesintheRecordset,youmustsupplythenewquerydefargument.

IfyouspecifyadifferentQueryDefthanwhatwasoriginallyusedtocreatetheRecordset,theRecordsetisre-createdfromscratch.

WhenyouuseRequery,thefirstrecordintheRecordsetbecomesthecurrentrecord.

Youcan'tusetheRequerymethodondynaset-orsnapshot-typeRecordsetobjectswhoseRestartablepropertyissettoFalse.However,ifyousupplytheoptionalnewquerydefargument,theRestartablepropertyisignored.

IfboththeBOFandEOFpropertysettingsoftheRecordsetobjectareTrueafteryouusetheRequerymethod,thequerydidn'treturnanyrecordsandtheRecordsetcontainsnodata.

SeekMethod

Locatestherecordinanindexedtable-typeRecordsetobjectthatsatisfiesthespecifiedcriteriaforthecurrentindexandmakesthatrecordthecurrentrecord(MicrosoftJetworkspacesonly).

Syntax

recordset.Seekcomparison,key1,key2...key13

TheSeekmethodsyntaxhasthefollowingparts.

Part Description

recordsetAnobjectvariablethatrepresentsanexistingtable-typeRecordsetobjectthathasadefinedindexasspecifiedbytheRecordsetobject'sIndexproperty.

comparison Oneofthefollowingstringexpressions:<,<=,=,>=,or>.

key1,key2...key13OneormorevaluescorrespondingtofieldsintheRecordsetobject'scurrentindex,asspecifiedbyitsIndexpropertysetting.Youcanuseupto13keyarguments.

Remarks

YoumustsetthecurrentindexwiththeIndexpropertybeforeyouuse

Seek.Iftheindexidentifiesanonuniquekeyfield,Seeklocatesthefirstrecordthatsatisfiesthecriteria.

TheSeekmethodsearchesthroughthespecifiedkeyfieldsandlocatesthefirstrecordthatsatisfiesthecriteriaspecifiedbycomparisonandkey1.Oncefound,itmakesthatrecordcurrentandsetstheNoMatchpropertytoFalse.IftheSeekmethodfailstolocateamatch,theNoMatchpropertyissettoTrue,andthecurrentrecordisundefined.

Ifcomparisonisequal(=),greaterthanorequal(>=),orgreaterthan(>),Seekstartsatthebeginningoftheindexandsearchesforward.

Ifcomparisonislessthan(<)orlessthanorequal(<=),Seekstartsattheendoftheindexandsearchesbackward.However,ifthereareduplicateindexentriesattheendoftheindex,Seekstartsatanarbitraryentryamongtheduplicatesandthensearchesbackward.

Youmustspecifyvaluesforallfieldsdefinedintheindex.IfyouuseSeekwithamultiple-columnindex,andyoudon'tspecifyacomparisonvalueforeveryfieldintheindex,thenyoucannotusetheequal(=)operatorinthecomparison.That'sbecausesomeofthecriteriafields(key2,key3,andsoon)willdefaulttoNull,whichwillprobablynotmatch.Therefore,theequaloperatorwillworkcorrectlyonlyifyouhavearecordwhichisallNullexceptthekeyyou'relookingfor.It'srecommendedthatyouusethegreaterthanorequal(>=)operatorinstead.

Thekey1argumentmustbeofthesamefielddatatypeasthecorrespondingfieldinthecurrentindex.Forexample,ifthecurrentindexreferstoanumberfield(suchasEmployeeID),key1mustbenumeric.Similarly,ifthecurrentindexreferstoaTextfield(suchasLastName),key1mustbeastring.

Theredoesn'thavetobeacurrentrecordwhenyouuseSeek.

YoucanusetheIndexescollectiontoenumeratetheexistingindexes.

Tolocatearecordinadynaset-orsnapshot-typeRecordsetthatsatisfiesaspecificconditionthatisnotcoveredbyexistingindexes,use

theFindmethods.Toincludeallrecords,notjustthosethatsatisfyaspecificcondition,usetheMovemethodstomovefromrecordtorecord.

Youcan'tusetheSeekmethodonalinkedtablebecauseyoucan'topenlinkedtablesastable-typeRecordsetobjects.However,ifyouusetheOpenDatabasemethodtodirectlyopenaninstallableISAM(non-ODBC)database,youcanuseSeekontablesinthatdatabase.

InanODBCDirectworkspace,theFindandSeekmethodsarenotavailableonanytypeofRecordsetobject,becauseexecutingaFindorSeekthroughanODBCconnectionisnotveryefficientoverthenetwork.Instead,youshoulddesignthequery(thatis,usingthesourceargumenttotheOpenRecordsetmethod)withanappropriateWHEREclausethatrestrictsthereturnedrecordstoonlythosethatmeetthecriteriayouwouldotherwiseuseinaFindorSeek.

SetOptionMethod

TemporarilyoverridesvaluesfortheMicrosoftJetdatabaseenginekeysintheWindowsRegistry(MicrosoftJetworkspacesonly).

Syntax

DBEngine.SetOptionparameter,newvalue

TheSetOptionmethodsyntaxhastheseparts.

Part Descriptionparameter ALongconstantasdescribedinSettings.

newvalue AVariantvaluethatyouwanttosetparameterto.

Settings

EachconstantreferstothecorrespondingregistrykeyinthepathJet\3.5\Engines\Jet3.5\(thatis,dbSharedAsyncDelaycorrespondstothekeyJet\3.5\Engines\Jet3.5\SharedAsyncDelay,andsoon.).

Constant DescriptiondbPageTimeout ThePageTimeoutkey

dbSharedAsyncDelay TheSharedAsyncDelaykeydbExclusiveAsyncDelay TheExclusiveAsyncDelaykeydbLockRetry TheLockRetrykeydbUserCommitSync TheUserCommitSynckeydbImplicitCommitSync TheImplicitCommitSynckeydbMaxBufferSize TheMaxBufferSizekeydbMaxLocksPerFile TheMaxLocksPerFilekeydbLockDelay TheLockDelaykeydbRecycleLVs TheRecycleLVskeydbFlushTransactionTimeoutTheFlushTransactionTimeoutkey

Remarks

UsetheSetOptionmethodtooverrideregistryvaluesatrun-time.NewvaluesestablishedwiththeSetOptionmethodremainineffectuntilchangedagainbyanotherSetOptioncall,oruntiltheDBEngineobjectisclosed.

Forfurtherdetailsonwhattheregistrykeysdo,andappropriatevaluestosetthemto,seeInitializingtheMicrosoftJet3.5DatabaseEngine.

mk:@MSITStore:daosdk.chm::/dawreg01_51bk.htm

SynchronizeMethod

Synchronizestworeplicas.(MicrosoftJetdatabasesonly).

Syntax

database.Synchronizepathname,exchange

TheSynchronizemethodsyntaxhasthefollowingparts.

Part Description

database AnobjectvariablethatrepresentsaDatabaseobjectthatisareplica.

pathnameAStringthatcontainsthepathtothetargetreplicawithwhichdatabasewillbesynchronized.The.mdbfilenameextensionisoptional.

exchange Optional.Aconstantindicatingwhichdirectiontosynchronizechangesbetweenthetwodatabases,asspecifiedinSettings.

Settings

Youcanusethefollowingconstantsintheexchangeargument.Youcanuseoneofthefirstthreeconstantswithorwithoutthefourthconstant.

Constant DescriptiondbRepExportChanges Sendschangesfromdatabasetopathname.dbRepImportChanges Sendschangesfrompathnametodatabase.

dbRepImpExpChanges (Default)Sendschangesfromdatabasetopathname,andvice-versa,alsoknownasbidirectionalexchange.

dbRepSyncInternet ExchangesdatabetweenfilesconnectedbyanInternetpathway.

Remarks

YouuseSynchronizetoexchangedataanddesignchangesbetweentwodatabases.Designchangesalwayshappenfirst.Bothdatabasesmustbeatthesamedesignlevelbeforetheycanexchangedata.Forexample,anexchangeoftypedbRepExportChangesmightcausedesignchangesatareplicaeventhoughdatachangesflowonlyfromthedatabasetopathname.

Thereplicaidentifiedinpathnamemustbepartofthesamereplicaset.IfbothreplicashavethesameReplicaIDpropertysettingorareDesignMastersfortwodifferentreplicasets,thesynchronizationfails.

WhenyousynchronizetworeplicasovertheInternet,youmustusethedbRepSyncInternetconstant.Inthiscase,youspecifyaUniformResourceLocator(URL)addressforthepathnameargumentinsteadofspecifyingalocalareanetworkpath.

NoteYoucan'tsynchronizepartialreplicaswithotherpartialreplicas.SeethePopulatePartialmethodformoreinformation.

SynchronizationovertheInternetrequirestheReplicationManager,whichisonlyavailableintheMicrosoftOffice97,DeveloperEdition.

UpdateMethod

SavesthecontentsofthecopybuffertoanupdatableRecordsetobject.

Syntax

recordset.Update(type,force)

TheUpdatemethodsyntaxhasthefollowingparts.

Part Description

recordset Anobjectvariablethatrepresentsanopen,updatableRecordsetobject.

type Optional.Aconstantindicatingthetypeofupdate,asspecifiedinSettings(ODBCDirectworkspacesonly).

force

Optional.ABooleanvalueindicatingwhetherornottoforcethechangesintothedatabase,regardlessofwhethertheunderlyingdatahasbeenchangedbyanotherusersincetheAddNew,Delete,orEditcall.IfTrue,thechangesareforcedandchangesmadebyotherusersaresimplyoverwritten.IfFalse(default),changesmadebyanotheruserwhiletheupdateispendingwillcausetheupdatetofailforthosechangesthatareinconflict.Noerroroccurs,buttheBatchCollisionCountandBatchCollisionspropertieswillindicatethenumberofconflictsandtherows

affectedbyconflicts,respectively(ODBCDirectworkspacesonly).

Settings

Youcanusethefollowingvaluesforthetypeargument.Youcanusethenon-defaultvaluesonlyifbatchupdatingisenabled.


dbUpdateRegular Default.Pendingchangesaren’tcachedandarewrittentodiskimmediately.


dbUpdateCurrentRecord Onlythecurrentrecord’spendingchangesarewrittentodisk.

Remarks

UseUpdatetosavethecurrentrecordandanychangesyou'vemadetoit.

CautionChangestothecurrentrecordarelostif:

YouusetheEditorAddNewmethod,andthenmovetoanotherrecordwithoutfirstusingUpdate.

YouuseEditorAddNew,andthenuseEditorAddNewagainwithoutfirstusingUpdate.

YousettheBookmarkpropertytoanotherrecord.

YoucloserecordsetwithoutfirstusingUpdate.

YoucanceltheEditoperationbyusingCancelUpdate.

Toeditarecord,usetheEditmethodtocopythecontentsofthecurrentrecordtothecopybuffer.Ifyoudon'tuseEditfirst,anerroroccurswhenyouuseUpdateorattempttochangeafield'svalue.

InanODBCDirectworkspace,youcandobatchupdates,providedthecursorlibrarysupportsbatchupdates,andtheRecordsetwasopenedwiththeoptimisticbatchlockingoption.

InaMicrosoftJetworkspace,whentheRecordsetobject'sLockEditspropertysettingisTrue(pessimisticallylocked)inamultiuserenvironment,therecordremainslockedfromthetimeEditisuseduntiltheUpdatemethodisexecutedortheeditiscanceled.IftheLockEditspropertysettingisFalse(optimisticallylocked),therecordislockedandcomparedwiththepre-editedrecordjustbeforeitisupdatedinthedatabase.IftherecordhaschangedsinceyouusedtheEditmethod,theUpdateoperationfails.MicrosoftJet-connectedODBCandinstallableISAMdatabasesalwaysuseoptimisticlocking.TocontinuetheUpdateoperationwithyourchanges,usetheUpdatemethodagain.Toreverttotherecordastheotheruserchangedit,refreshthecurrentrecordbyusingMove0.

NoteToadd,edit,ordeletearecord,theremustbeauniqueindexontherecordintheunderlyingdatasource.Ifnot,a“Permissiondenied”errorwilloccurontheAddNew,Delete,orEditmethodcallinaMicrosoftJetworkspace,oran“Invalidargument”errorwilloccurontheUpdatecallinanODBCDirectworkspace.

DAOPropertiesbyObject

ThisreferencegroupsallDAOpropertiesbyobjectorcollection.TodeterminewhetheraparticularpropertyisavailabletoMicrosoftJetorODBCdatabases,checktheHelptopicforthatproperty.

Connection

Container

Database

Parameter

Property

DBEngine

Document

Error

Field

QueryDef

Recordset

Relation

TableDef

Group

Index

User

Workspace

DAOPropertiesforMicrosoftJetWorkspaces

ThisreferencelistsalphabeticallyallDAOpropertiesavailabletoMicrosoftJetworkspaces.

A-CAbsolutePosition

AllowZeroLength

AllPermissions

Attributes

BOF

Bookmark

Bookmarkable

CacheSize

CacheStart

Clustered

CollatingOrder

ConflictTable

Connect

Container

Count

D-HDataUpdatable

DateCreated

DefaultUser

DefaultPassword

DefaultValue

Description

DesignMasterID

DistinctCount

EditMode

EOF

FieldSize

Filter

Foreign

ForeignName

ForeignTable

HelpContext

HelpFile

I-OIgnoreNulls

Index

Inherit

Inherited

IniPath

IsolateODBCTrans

KeepLocal

LastModified

LastUpdated

LockEdits

LoginTimeout

LogMessages

MaxRecords

Name

NoMatch

Number

ODBCTimeout

OrdinalPosition

Owner

P-RPartialReplicadaproPartialReplica>langref

Password

PercentPosition

Permissions

PID

Primary

QueryTimeout

RecordCount

RecordsAffected

Replicable

ReplicableBool

ReplicaFilter

ReplicaID

Required

Restartable

ReturnsRecords

S-ZSize

Sort

Source

SourceField

SourceTable

SourceTableName

SQL

SystemDB

Table

Transactions

Type

Unique

Updatable

UserName

V1xNullBehavior

ValidateOnSet

ValidationRule

ValidationText

Value

Version

DAOPropertiesforODBCDirectWorkspaces

ThisreferencelistsalphabeticallyallDAOpropertiesavailabletoODBCDirectworkspaces.

A-DAbsolutePosition

Attributes

BatchCollisionCount

BatchCollisions

BatchSize

BOF

Bookmark

Bookmarkable

CacheSize

Connect

Connection

Count

Database

DataUpdatable

DefaultCursorDriver

DefaultType

Description

Direction

E-QEditMode

EOF

FieldSize

HelpContext

HelpFile

LastModified

LockEdits

LoginTimeout

LogMessages

MaxRecordsdaproMaxRecords>langref

Name

Number

ODBCTimeout

OrdinalPosition

OriginalValue

PercentPosition

Prepare

QueryTimeout

R-ZRecordCount

RecordsAffected

RecordStatus

Restartable

Size

Source

SourceField

SourceTable

SQL

StillExecuting

Transactions

Type

Updatable

UpdateOptions

UserName

Value

Version

VisibleValue

AbsolutePositionProperty

SetsorreturnstherelativerecordnumberofaRecordsetobject'scurrentrecord.

SettingsandReturnValues

ThesettingorreturnvalueisaLongintegerfrom0toonelessthanthenumberofrecordsintheRecordsetobject.ItcorrespondstotheordinalpositionofthecurrentrecordintheRecordsetobjectspecifiedbytheobject.

Remarks

YoucanusetheAbsolutePositionpropertytopositionthecurrentrecordpointertoaspecificrecordbasedonitsordinalpositioninadynaset-orsnapshot-typeRecordsetobject.YoucanalsodeterminethecurrentrecordnumberbycheckingtheAbsolutePositionpropertysetting.

BecausetheAbsolutePositionpropertyvalueiszero-based(thatis,asettingof0referstothefirstrecordintheRecordsetobject),youcannotsetittoavaluegreaterthanorequaltothenumberofpopulatedrecords;

doingsocausesatrappableerror.YoucandeterminethenumberofpopulatedrecordsintheRecordsetobjectbycheckingtheRecordCountpropertysetting.ThemaximumallowablesettingfortheAbsolutePositionpropertyisthevalueoftheRecordCountpropertyminus1.

Ifthereisnocurrentrecord,aswhentherearenorecordsintheRecordsetobject,AbsolutePositionreturns–1.Ifthecurrentrecordisdeleted,theAbsolutePositionpropertyvalueisn'tdefined,andatrappableerroroccursifit'sreferenced.Newrecordsareaddedtotheendofthesequence.

Youshouldn'tusethispropertyasasurrogaterecordnumber.BookmarksarestilltherecommendedwayofretainingandreturningtoagivenpositionandaretheonlywaytopositionthecurrentrecordacrossalltypesofRecordsetobjects.Inparticular,thepositionofarecordchangeswhenoneormorerecordsprecedingitaredeleted.ThereisalsonoassurancethatarecordwillhavethesameabsolutepositioniftheRecordsetobjectisre-createdagainbecausetheorderofindividualrecordswithinaRecordsetobjectisn'tguaranteedunlessit'screatedwithanSQLstatementbyusinganORDERBYclause.

Notes

SettingtheAbsolutePositionpropertytoavaluegreaterthanzeroonanewlyopenedbutunpopulatedRecordsetobjectcausesatrappableerror.PopulatetheRecordsetobjectfirstwiththeMoveLastmethod.

TheAbsolutePositionpropertyisn'tavailableonforward-only–typeRecordsetobjects,oronRecordsetobjectsopenedfrompass-throughqueriesagainstMicrosoftJet-connectedODBCdatabases.

AllowZeroLengthProperty

Setsorreturnsavaluethatindicateswhetherazero-lengthstring("")isavalidsettingfortheValuepropertyoftheFieldobjectwithaTextorMemodatatype(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleandatatypethatindicatesifavalueisvalid.ThevalueisTrueiftheFieldobjectacceptsazero-lengthstringasitsValueproperty;thedefaultvalueisFalse.

Remarks

ForanobjectnotyetappendedtotheFieldscollection,thispropertyisread/write.

OnceappendedtoaFieldscollection,theavailabilityoftheAllowZeroLengthpropertydependsontheobjectthatcontainstheFieldscollection,asshowninthefollowingtable.

IftheFieldscollectionbelongstoan ThenAllowZeroLengthis

Indexobject NotsupportedQueryDefobject Read-onlyRecordsetobject Read-onlyRelationobject NotsupportedTableDefobject Read/write

YoucanusethispropertyalongwiththeRequired,ValidateOnSet,orValidationRulepropertytovalidateavalueinafield.

AllPermissionsProperty

ReturnsallthepermissionsthatapplytothecurrentUserNamepropertyoftheContainerorDocumentobject,includingpermissionsthatarespecifictotheuseraswellasthepermissionsauserinheritsfrommembershipsingroups(MicrosoftJetworkspacesonly).

ReturnValues

ForanyContainerorDocumentobject,thereturnvalueisaLongvalueorconstant(s)thatmayincludethefollowing.


dbSecReadDef Theusercanreadthetabledefinition,includingcolumnandindexinformation.

dbSecWriteDef Theusercanmodifyordeletethetabledefinition,includingcolumnandindexinformation.

dbSecRetrieveData TheusercanretrievedatafromtheDocumentobject.

dbSecInsertData Theusercanaddrecords.dbSecReplaceData Theusercanmodifyrecords.dbSecDeleteData Theusercandeleterecords.

Inaddition,theDatabasescontaineroranyDocumentobjectinaDocumentscollectionmayincludethefollowing.

Constant DescriptiondbSecDeleteData Theusercandeleterecords.

dbSecDBAdmin Theusercanreplicatethedatabaseandchangethedatabasepassword.

dbSecDBCreateTheusercancreatenewdatabases.ThissettingisvalidonlyontheDatabasescontainerintheworkgroupinformationfile(System.mdw).

dbSecDBExclusive Theuserhasexclusiveaccesstothedatabase.dbSecDBOpen Theusercanopenthedatabase.

Remarks

ThispropertycontrastswiththePermissionsproperty,whichreturnsonlythepermissionsthatarespecifictotheuseranddoesn'tincludeanypermissionsthattheusermayalsohaveasamemberofgroups.IfthecurrentvalueoftheUserNamepropertyisagroup,thentheAllPermissionspropertyreturnsthesamevaluesasthePermissionsproperty.

AttributesProperty

SetsorreturnsavaluethatindicatesoneormorecharacteristicsofaField,Relation,orTableDefobject.


ThesettingorreturnvalueisLongdatatype,andthedefaultvalueis0.

ForaFieldobject,thevaluespecifiescharacteristicsofthefieldrepresentedbytheFieldobjectandcanbeacombinationoftheseconstants.


dbAutoIncrField

ThefieldvaluefornewrecordsisautomaticallyincrementedtoauniqueLongintegerthatcan'tbechanged(inaMicrosoftJetworkspace,supportedonlyforMicrosoftJetdatabase(.mdb)tables).

dbDescending

Thefieldissortedindescending(ZtoAor100to0)order;thisoptionappliesonlytoaFieldobjectinaFieldscollectionofanIndexobject.Ifyouomitthisconstant,thefieldissortedinascending(AtoZor0to

100)order.ThisisthedefaultvalueforIndexandTableDeffields(MicrosoftJetworkspacesonly).

dbFixedField Thefieldsizeisfixed(defaultforNumericfields).

dbHyperlinkField Thefieldcontainshyperlinkinformation(Memofieldsonly).

dbSystemFieldThefieldstoresreplicationinformationforreplicas;youcan'tdeletethistypeoffield(MicrosoftJetworkspacesonly).

dbUpdatableField Thefieldvaluecanbechanged.dbVariableField Thefieldsizeisvariable(Textfieldsonly).

ForaRelationobject,thevaluespecifiescharacteristicsoftherelationshiprepresentedbytheRelationobjectandcanbeacombinationoftheseconstants.

Constant DescriptiondbRelationUnique Therelationshipisone-to-one.

dbRelationDontEnforce Therelationshipisn'tenforced(noreferentialintegrity).

dbRelationInherited Therelationshipexistsinanon-currentdatabasethatcontainsthetwolinkedtables.

dbRelationUpdateCascade Updateswillcascade.dbRelationDeleteCascade Deletionswillcascade.

dbRelationLeftMicrosoftAccessonly.InDesignview,displayaLEFTJOINasthedefaultjointype.

dbRelationRightMicrosoftAccessonly.InDesignview,displayaRIGHTJOINasthedefaultjointype.

NoteIfyousettheRelationobject'sAttributespropertytoactivatecascadingoperations,theMicrosoftJetdatabaseengineautomaticallyupdatesordeletesrecordsinoneormoreothertableswhenchangesoccurinrelatedprimarytables.

Forexample,supposeyouestablishacascadingdeleterelationship

betweenaCustomerstableandanOrderstable.WhenyoudeleterecordsfromtheCustomerstable,recordsintheOrderstablerelatedtothatcustomerarealsodeleted.Inaddition,ifyouestablishcascadingdeleterelationshipsbetweentheOrderstableandothertables,recordsfromthosetablesareautomaticallydeletedwhenyoudeleterecordsfromtheCustomerstable.

ForaTableDefobject,thevaluespecifiescharacteristicsofthetablerepresentedbytheTableDefobjectandcanbeacombinationoftheseLongconstants.


dbAttachExclusive

FordatabasesthatusetheMicrosoftJetdatabaseengine,thetableisalinkedtableopenedforexclusiveuse.YoucansetthisconstantonanappendedTableDefobjectforalocaltable,butnotonaremotetable.

dbAttachSavePWD

FordatabasesthatusetheMicrosoftJetdatabaseengine,theuserIDandpasswordfortheremotelylinkedtablearesavedwiththeconnectioninformation.YoucansetthisconstantonanappendedTableDefobjectforaremotetable,butnotonalocaltable.

dbSystemObject

ThetableisasystemtableprovidedbytheMicrosoftJetdatabaseengine.YoucansetthisconstantonanappendedTableDefobject.

dbHiddenObject

ThetableisahiddentableprovidedbytheMicrosoftJetdatabaseengine.YoucansetthisconstantonanappendedTableDefobject.

dbAttachedTableThetableisalinkedtablefromanon-ODBCdatasourcesuchasaMicrosoftJetorParadoxdatabase(read-only).

dbAttachedODBCThetableisalinkedtablefromanODBCdatasource,suchasMicrosoftSQLServer(read-only).

Remarks

Foranobjectnotyetappendedtoacollection,thispropertyisread/write.

ForanappendedFieldobject,theavailabilityoftheAttributespropertydependsontheobjectthatcontainstheFieldscollection.

IftheFieldobjectbelongstoan ThenAttributesis

Indexobject

Read/writeuntiltheTableDefobjectthattheIndexobjectisappendedtoisappendedtoaDatabaseobject;thenthepropertyisread-only.

QueryDefobject Read-onlyRecordsetobject Read-onlyRelationobject NotsupportedTableDefobject Read/write

ForanappendedRelationobject,theAttributespropertysettingisread-only.

ForanappendedTableDefobject,thepropertyisread/write,althoughyoucan'tsetalloftheconstantsiftheobjectisappended,asnotedinSettingsandReturnValues.

Whenyousetmultipleattributes,youcancombinethembysummingtheappropriateconstants.Anyinvalidvaluesareignoredwithoutproducinganerror.

BatchCollisionCountProperty

Returnsthenumberofrecordsthatdidnotcompletethelastbatchupdate(ODBCDirectworkspacesonly).

ReturnValue

ThereturnvalueisaLongthatindicatesthenumberoffailingrecords,or0ifallrecordsweresuccessfullyupdated.

Remarks

Thispropertyindicateshowmanyrecordsencounteredcollisionsorotherwisefailedtoupdateduringthelastbatchupdateattempt.ThevalueofthispropertycorrespondstothenumberofbookmarksintheBatchCollisionsproperty.

IfyousettheworkingRecordsetobject'sBookmarkpropertytobookmarkvaluesintheBatchCollisionsarray,youcanmovetoeachrecordthatfailedtocompletethemostrecentbatchUpdateoperation.

Afterthecollisionrecordsarecorrected,abatch-modeUpdatemethodcanbecalledagain.AtthispointDAOattemptsanotherbatchupdate,

andtheBatchCollisionspropertyagainreflectsthesetofrecordsthatfailedthesecondattempt.Anyrecordsthatsucceededinthepreviousattemptarenotsentinthecurrentattempt,becausetheynowhaveaRecordStatuspropertyofdbRecordUnmodified.Thisprocesscancontinueaslongascollisionsoccur,oruntilyouabandontheupdatesandclosetheresultset.

BatchCollisionsProperty

Returnsanarrayofbookmarksindicatingtherowsthatgeneratedcollisionsinthelastbatchupdateoperation(ODBCDirectworkspacesonly).

ReturnValue

Thereturnvalueisavariantexpressioncontaininganarrayofbookmarks.

Remarks

ThispropertycontainsanarrayofbookmarkstorowsthatencounteredacollisionduringthelastattemptedbatchUpdatecall.TheBatchCollisionCountpropertyindicatesthenumberofelementsinthearray.

IfyousettheworkingRecordsetobject'sBookmarkpropertytobookmarkvaluesintheBatchCollisionsarray,youcanmovetoeachrecordthatfailedtocompletethemostrecentbatch-modeUpdateoperation.

Afterthecollisionrecordsarecorrected,youcancallthebatchmode

Updatemethodagain.AtthispointDAOattemptsanotherbatchupdate,andtheBatchCollisionspropertyagainreflectsthesetofrecordsthatfailedthesecondattempt.Anyrecordsthatsucceededinthepreviousattemptarenotsentinthecurrentattempt,astheynowhaveaRecordStatuspropertyofdbRecordUnmodified.Thisprocesscancontinueaslongascollisionsoccur,oruntilyouabandontheupdatesandclosetheresultset.

Thisarrayisre-createdeachtimeyouexecuteabatch-modeUpdatemethod.

BatchSizeProperty

Setsorreturnsthenumberofstatementssentbacktotheserverineachbatch(ODBCDirectworkspacesonly).

SettingsAndReturnValues

ThesettingorreturnvalueisaLongthatindicatesthenumberofbatchedstatementssenttheserverinasinglebatchupdate.Thedefaultvalueis15.

Remarks

TheBatchSizepropertydeterminesthebatchsizeusedwhensendingstatementstotheserverinabatchupdate.Thevalueofthepropertydeterminesthenumberofstatementssenttotheserverinonecommandbuffer.Bydefault,15statementsaresenttotheserverineachbatch.Thispropertycanbechangedatanytime.Ifadatabaseserverdoesn'tsupportstatementbatching,youcansetthispropertyto1,causingeachstatementtobesentseparately.

BOF,EOFProperties

BOF?returnsavaluethatindicateswhetherthecurrentrecordpositionisbeforethefirstrecordinaRecordsetobject.

EOF?returnsavaluethatindicateswhetherthecurrentrecordpositionisafterthelastrecordinaRecordsetobject.

ReturnValues

ThereturnvaluesfortheBOFandEOFpropertiesareBooleanvalues.

TheBOFpropertyreturnsTrueifthecurrentrecordpositionisbeforethefirstrecord,andFalseifthecurrentrecordpositionisonorafterthefirstrecord.

TheEOFpropertyreturnsTrueifthecurrentrecordpositionisafterthelastrecord,andFalseifthecurrentrecordpositionisonorbeforethelastrecord.

Remarks

YoucanusetheBOFandEOFpropertiestodeterminewhetheraRecordsetobjectcontainsrecordsorwhetheryou'vegonebeyondthelimitsofaRecordsetobjectwhenyoumovefromrecordtorecord.

ThelocationofthecurrentrecordpointerdeterminestheBOFandEOFreturnvalues.

IfeithertheBOForEOFpropertyisTrue,thereisnocurrentrecord.

IfyouopenaRecordsetobjectcontainingnorecords,theBOFandEOFpropertiesaresettoTrue,andtheRecordsetobject'sRecordCountpropertysettingis0.WhenyouopenaRecordsetobjectthatcontainsatleastonerecord,thefirstrecordisthecurrentrecordandtheBOFandEOFpropertiesareFalse;theyremainFalseuntilyoumovebeyondthebeginningorendoftheRecordsetobjectbyusingtheMovePreviousorMoveNextmethod,respectively.WhenyoumovebeyondthebeginningorendoftheRecordset,thereisnocurrentrecordornorecordexists.

IfyoudeletethelastremainingrecordintheRecordsetobject,theBOFandEOFpropertiesmayremainFalseuntilyouattempttorepositionthecurrentrecord.

IfyouusetheMoveLastmethodonaRecordsetobjectcontainingrecords,thelastrecordbecomesthecurrentrecord;ifyouthenusetheMoveNextmethod,thecurrentrecordbecomesinvalidandtheEOFpropertyissettoTrue.Conversely,ifyouusetheMoveFirstmethodonaRecordsetobjectcontainingrecords,thefirstrecordbecomesthecurrentrecord;ifyouthenusetheMovePreviousmethod,thereisnocurrentrecordandtheBOFpropertyissettoTrue.

Typically,whenyouworkwithalltherecordsinaRecordsetobject,yourcodewillloopthroughtherecordsbyusingtheMoveNextmethoduntiltheEOFpropertyissettoTrue.

IfyouusetheMoveNextmethodwhiletheEOFpropertyissettoTrueortheMovePreviousmethodwhiletheBOFpropertyissettoTrue,anerroroccurs.

ThistableshowswhichMovemethodsareallowedwithdifferentcombinationsoftheBOFandEOFproperties.

MoveFirst,MoveLast

MovePrevious,Move<0 Move0

MoveNext,Move>0

BOF=True,EOF=False Allowed Error Error Allowed

BOF=False,EOF=True Allowed Allowed Error Error

BothTrue Error Error Error ErrorBothFalse Allowed Allowed Allowed Allowed

AllowingaMovemethoddoesn'tmeanthatthemethodwillsuccessfullylocatearecord.ItmerelyindicatesthatanattempttoperformthespecifiedMovemethodisallowedandwon'tgenerateanerror.ThestateoftheBOFandEOFpropertiesmaychangeasaresultoftheattemptedMove.

AnOpenRecordsetmethodinternallyinvokesaMoveFirstmethod.Therefore,usinganOpenRecordsetmethodonanemptysetofrecordssetstheBOFandEOFpropertiestoTrue.(SeethefollowingtableforthebehaviorofafailedMoveFirstmethod.)

AllMovemethodsthatsuccessfullylocatearecordwillsetbothBOFandEOFtoFalse.

InaMicrosoftJetworkspace,ifyouaddarecordtoanemptyRecordset,BOFwillbecomeFalse,butEOFwillremainTrue,indicatingthatthecurrentpositionisattheendofRecordset.InanODBCDirectworkspace,bothBOFandEOFwillbecomeFalse,indicatingthatthecurrentpositionisonthenewrecord.

AnyDeletemethod,evenifitremovestheonlyremainingrecordfromaRecordset,won'tchangethesettingoftheBOForEOFproperty.

ThefollowingtableshowshowMovemethodsthatdon'tlocatearecordaffecttheBOFandEOFpropertysettings.

BOF EOFMoveFirst,MoveLast True TrueMove0 Nochange NochangeMovePrevious,Move<0True NochangeMoveNext,Move>0 Nochange True

BookmarkProperty

SetsorreturnsabookmarkthatuniquelyidentifiesthecurrentrecordinaRecordsetobject.


Thesettingorreturnvalueisastringexpressionorvariantexpressionthatevaluatestoavalidbookmark.ThedatatypeisaVariantarrayofBytedata.

Remarks

ForaRecordsetobjectbasedentirelyonMicrosoftJettables,thevalueoftheBookmarkablepropertyisTrue,andyoucanusetheBookmarkpropertywiththatRecordset.Otherdatabaseproductsmaynotsupportbookmarks,however.Forexample,youcan'tusebookmarksinanyRecordsetobjectbasedonalinkedParadoxtablethathasnoprimarykey.

WhenyoucreateoropenaRecordsetobject,eachofitsrecordsalreadyhasauniquebookmark.YoucansavethebookmarkforthecurrentrecordbyassigningthevalueoftheBookmarkpropertytoavariable.To

quicklyreturntothatrecordatanytimeaftermovingtoadifferentrecord,settheRecordsetobject'sBookmarkpropertytothevalueofthatvariable.

Thereisnolimittothenumberofbookmarksyoucanestablish.Tocreateabookmarkforarecordotherthanthecurrentrecord,movetothedesiredrecordandassignthevalueoftheBookmarkpropertytoaStringvariablethatidentifiestherecord.

TomakesuretheRecordsetobjectsupportsbookmarks,checkthevalueofitsBookmarkablepropertybeforeyouusetheBookmarkproperty.IftheBookmarkablepropertyisFalse,theRecordsetobjectdoesn'tsupportbookmarks,andusingtheBookmarkpropertyresultsinatrappableerror.

IfyouusetheClonemethodtocreateacopyofaRecordsetobject,theBookmarkpropertysettingsfortheoriginalandtheduplicateRecordsetobjectsareidenticalandcanbeusedinterchangeably.However,youcan'tusebookmarksfromdifferentRecordsetobjectsinterchangeably,eveniftheywerecreatedbyusingthesameobjectorthesameSQLstatement.

IfyousettheBookmarkpropertytoavaluethatrepresentsadeletedrecord,atrappableerroroccurs.

ThevalueoftheBookmarkpropertyisn'tthesameasarecordnumber.

BookmarkableProperty

ReturnsavaluethatindicateswhetheraRecordsetobjectsupportsbookmarks,whichyoucansetbyusingtheBookmarkproperty.

ReturnValues

ThereturnvalueisaBooleandatatypethatreturnsTrueiftheobjectsupportsbookmarks.

Remarks

ChecktheBookmarkablepropertysettingofaRecordsetobjectbeforeyouattempttosetorchecktheBookmarkproperty.

ForRecordsetobjectsbasedentirelyonMicrosoftJettables,thevalueoftheBookmarkablepropertyisTrue,andyoucanusebookmarks.Otherdatabaseproductsmaynotsupportbookmarks,however.Forexample,youcan'tusebookmarksinanyRecordsetobjectbasedonalinkedParadoxtablethathasnoprimarykey.

CacheSizeProperty

SetsorreturnsthenumberofrecordsretrievedfromanODBCdatasourcethatwillbecachedlocally.


ThesettingorreturnvalueisaLongvalueandmustbebetween5and1200,butnotgreaterthanavailablememorywillallow.Atypicalvalueis100.Asettingof0turnsoffcaching.

Remarks

DatacachingimprovesperformanceifyouuseRecordsetobjectstoretrievedatafromaremoteserver.Acacheisaspaceinlocalmemorythatholdsthedatamostrecentlyretrievedfromtheserver;thisisusefulifusersrequestthedataagainwhiletheapplicationisrunning.Whenusersrequestdata,theMicrosoftJetdatabaseenginechecksthecachefortherequesteddatafirstratherthanretrievingitfromtheserver,whichtakesmoretime.ThecacheonlysavesdatathatcomesfromanODBCdatasource.

AnyMicrosoftJet-connectedODBCdatasource,suchasalinkedtable,

canhavealocalcache.Tocreatethecache,openaRecordsetobjectfromtheremotedatasource,settheCacheSizeandCacheStartproperties,andthenusetheFillCachemethod,orstepthroughtherecordsbyusingtheMovemethods.

AnODBCDirectworkspacecanusealocalcache.Tocreatethecache,settheCacheSizepropertyonaQueryDefobject.OnaRelationobject,CacheSizeisread-onlyanddependsonthevalueoftheQueryDefobject'sCacheSizeproperty.Youcan'tusetheCacheStartpropertyonFillCachemethodinanODBCDirectworkspace.InaMicrosoftJetworkspace,theCacheSizepropertyisnotavailableonaQueryDefobject.

YoucanbasetheCacheSizepropertysettingonthenumberofrecordsyourapplicationcanhandleatonetime.Forexample,ifyou'reusingaRecordsetobjectasthesourceofthedatatobedisplayedonscreen,youcouldsetitsCacheSizepropertyto20todisplay20recordsatonetime.

TheMicrosoftJetdatabaseenginerequestsrecordswithinthecacherangefromthecache,anditrequestsrecordsoutsidethecacherangefromtheserver.

Recordsretrievedfromthecachedon'treflectconcurrentchangesthatotherusersmadetothesourcedata.

Toforceanupdateofallthecacheddata,settheCacheSizepropertyoftheRecordsetobjectto0,re-setittothesizeofthecacheyouoriginallyrequested,andthenusetheFillCachemethod.

CacheStartProperty

Setsorreturnsavaluethatspecifiesthebookmarkofthefirstrecordinadynaset-typeRecordsetobjectcontainingdatatobelocallycachedfromanODBCdatasource(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringthatspecifiesabookmark.

Remarks

Datacachingimprovestheperformanceofanapplicationthatretrievesdatafromaremoteserverthroughdynaset-typeRecordsetobjects.Acacheisaspaceinlocalmemorythatholdsthedatamostrecentlyretrievedfromtheserverintheeventthatthedatawillberequestedagainwhiletheapplicationisrunning.Whendataisrequested,theMicrosoftJetdatabaseenginechecksthecachefortherequesteddatafirstratherthanretrievingitfromtheserver,whichtakesmoretime.OnlydatafromanODBCdatasourcecanbesavedinthecache.

AnyMicrosoftJet-connectedODBCdatasource,suchasalinkedtable,canhavealocalcache.Tocreatethecache,openaRecordsetobject

fromtheremotedatasource,settheCacheSizeandCacheStartproperties,andthenusetheFillCachemethodorstepthroughtherecordsusingtheMovemethods.

TheCacheStartpropertysettingisthebookmarkofthefirstrecordintheRecordsetobjecttobecached.YoucanusethebookmarkofanyrecordtosettheCacheStartproperty.Maketherecordyouwanttostartthecachethecurrentrecord,andsettheCacheStartpropertyequaltotheBookmarkproperty.

TheMicrosoftJetdatabaseenginerequestsrecordswithinthecacherangefromthecache,anditrequestsrecordsoutsidethecacherangefromtheserver.

Recordsretrievedfromthecachedon'treflectchangesmadeconcurrentlytothesourcedatabyotherusers.

Toforceanupdateofallthecacheddata,settheCacheSizepropertyoftheRecordsetobjectto0,setittothesizeofthecacheyouoriginallyrequested,andthenusetheFillCachemethod.

ClusteredProperty

SetsorreturnsavaluethatindicateswhetheranIndexobjectrepresentsaclusteredindexforatable(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleandatatypethatisTrueiftheIndexobjectrepresentsaclusteredindex.

Remarks

SomeIISAMdesktopdatabaseformatsuseclusteredindexes.Aclusteredindexconsistsofoneormorenonkeyfieldsthat,takentogether,arrangeallrecordsinatableinapredefinedorder.Aclusteredindexprovidesefficientaccesstorecordsinatableinwhichtheindexvaluesmaynotbeunique.

TheClusteredpropertyisread/writeforanewIndexobjectnotyetappendedtoacollectionandread-onlyforanexistingIndexobjectinanIndexescollection.

Notes

MicrosoftJetdatabasesignoretheClusteredpropertybecausetheMicrosoftJetdatabaseenginedoesn'tsupportclusteredindexes.

ForODBCdatasourcestheClusteredpropertyalwaysreturnsFalse;itdoesnotdetectwhetherornottheODBCdatasourcehasaclusteredindex.

CollatingOrderProperty

Returnsavaluethatspecifiesthesequenceofthesortorderintextforstringcomparisonorsorting(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaLongvalueorconstantthatcanbeoneofthefollowingvalues.

Constant Sortorder

dbSortGeneral General(English,French,German,Portuguese,Italian,andModernSpanish)

dbSortArabic ArabicdbSortChineseSimplified SimplifiedChinesedbSortChineseTraditional TraditionalChinesedbSortCyrillic RussiandbSortCzech CzechdbSortDutch DutchdbSortGreek GreekdbSortHebrew HebrewdbSortHungarian HungariandbSortIcelandic Icelandic

dbSortJapanese JapanesedbSortKorean KoreandbSortNeutral NeutraldbSortNorwDan NorwegianorDanishdbSortPDXIntl ParadoxInternationaldbSortPDXNor ParadoxNorwegianorDanishdbSortPDXSwe ParadoxSwedishorFinnishdbSortPolish PolishdbSortSlovenian SloveniandbSortSpanish SpanishdbSortSwedFin SwedishorFinnishdbSortThai ThaidbSortTurkish TurkishdbSortUndefined Undefinedorunknown

Remarks

TheavailabilityoftheCollatingOrderpropertydependsontheobjectthatcontainstheFieldscollection,asshowninthefollowingtable.

IftheFieldscollectionbelongstoanThenCollatingOrderisIndexobject NotsupportedQueryDefobject Read-onlyRecordsetobject Read-onlyRelationobject NotsupportedTableDefobject Read-only

TheCollatingOrderpropertysettingcorrespondstothelocaleargumentoftheCreateDatabasemethodwhenthedatabasewascreatedortheCompactDatabasemethodwhenthedatabasewasmostrecentlycompacted.

ChecktheCollatingOrderpropertysettingofaDatabaseorFieldobjecttodeterminethestringcomparisonmethodforthedatabaseorfield.YoucansettheCollatingOrderpropertyofanew,unappendedFieldobjectifyouwantthesettingoftheFieldobjecttodifferfromthatoftheDatabaseobjectthatcontainsit.

TheCollatingOrderandAttributespropertysettingsofaFieldobjectinaFieldscollectionofanIndexobjecttogetherdeterminethesequenceanddirectionofthesortorderinanindex.However,youcan'tsetacollatingorderforanindividualindex—youcanonlysetitforanentiretable.

ConflictTableProperty

Returnsthenameofaconflicttablecontainingthedatabaserecordsthatconflictedduringthesynchronizationoftworeplicas(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaStringdatatypethatisazero-lengthstringifthereisnoconflicttableorthedatabaseisn'tareplica.

Remarks

Iftwousersattwoseparatereplicaseachmakeachangetothesamerecordinthedatabase,thechangesmadebyoneuserwillfailtobeappliedtotheotherreplica.Consequently,theuserwiththefailedchangemustresolvetheconflicts.

Conflictsoccurattherecordlevel,notbetweenfields.Forexample,ifoneuserchangestheAddressfieldandanotherupdatesthePhonefieldinthesamerecord,thenonechangeisrejected.Becauseconflictsoccurattherecordlevel,therejectionoccurseventhoughthesuccessfulchangeandtherejectedchangeareunlikelytoresultinatrueconflictof

information.

Thesynchronizationmechanismhandlestherecordconflictsbycreatingconflicttables,whichcontaintheinformationthatwouldhavebeenplacedinthetable,ifthechangehadbeensuccessful.Youcanexaminetheseconflicttablesandworkthroughthemrowbyrow,fixingwhateverisappropriate.

Allconflicttablesarenamedtable_conflict,wheretableistheoriginalnameofthetable,truncatedtothemaximumtablenamelength.

ConnectProperty

Setsorreturnsavaluethatprovidesinformationaboutthesourceofanopenconnection,anopendatabase,adatabaseusedinapass-throughquery,oralinkedtable.ForDatabaseobjects,newConnectionobjects,linkedtables,andTableDefobjectsnotyetappendedtoacollection,thispropertysettingisread/write.ForQueryDefobjectsandbasetables,thispropertyisread-only.

Syntax

object.Connect=databasetype;parameters;

TheConnectpropertysyntaxhastheseparts.

Part Description

object AnobjectexpressionthatevaluatestoanobjectintheAppliesTolist.

databasetypeOptional.AStringthatspecifiesadatabasetype.ForMicrosoftJetdatabases,excludethisargument;ifyouspecifyparameters,useasemicolon(;)asaplaceholder.

parametersOptional.AStringthatspecifiesadditionalparameterstopasstoODBCorinstallableISAMdrivers.Usesemicolonstoseparateparameters.

Settings

TheConnectpropertysettingisaStringcomposedofadatabasetypespecifierandzeroormoreparametersseparatedbysemicolons.TheConnectpropertypassesadditionalinformationtoODBCandcertainISAMdriversasneeded.

ToperformanSQLpass-throughqueryonatablelinkedtoyourMicrosoftJetdatabase(.mdb)file,youmustfirstsettheConnectpropertyofthelinkedtable'sdatabasetoavalidODBCconnectionstring.

ForaTableDefobjectthatrepresentsalinkedtable,theConnectpropertysettingconsistsofoneortwoparts(adatabasetypespecifierandapathtothedatabase),eachofwhichendswithasemicolon.

ThepathasshowninthefollowingtableisthefullpathforthedirectorycontainingthedatabasefilesandmustbeprecededbytheidentifierDATABASE=.Insomecases(aswithMicrosoftExcelandMicrosoftJetdatabases),youshouldincludeaspecificfilenameinthedatabasepathargument.

ThefollowingtableshowspossibledatabasetypesandtheircorrespondingdatabasespecifiersandpathsfortheConnectpropertysetting.InanODBCDirectworkspace,onlythe"ODBC"specifiercanbeused.

Databasetype Specifier ExampleMicrosoftJetDatabase [database]; drive:\path\filename.mdbdBASEIII dBASEIII; drive:\pathdBASEIV dBASEIV; drive:\pathdBASE5 dBASE5.0; drive:\pathParadox3.x Paradox3.x; drive:\pathParadox4.x Paradox4.x; drive:\pathParadox5.x Paradox5.x; drive:\pathMicrosoftFoxPro2.0 FoxPro2.0; drive:\pathMicrosoftFoxPro2.5 FoxPro2.5; drive:\pathMicrosoftFoxPro2.6 FoxPro2.6; drive:\pathMicrosoftVisual

FoxPro3.0 FoxPro3.0; drive:\path

MicrosoftExcel3.0 Excel3.0; drive:\path\filename.xlsMicrosoftExcel4.0 Excel4.0; drive:\path\filename.xlsMicrosoftExcel5.0orMicrosoftExcel95 Excel5.0; drive:\path\filename.xls

MicrosoftExcel97 Excel8.0; drive:\path\filename.xlsLotus1-2-3WKSandWK1 LotusWK1; drive:\path\filename.wk1

Lotus1-2-3WK3 LotusWK3; drive:\path\filename.wk3Lotus1-2-3WK4 LotusWK4; drive:\path\filename.wk4HTMLImport HTMLImport; drive:\path\filenameHTMLExport HTMLExport; drive:\pathText Text; drive:\path

ODBC

ODBC;DATABASE=database;UID=user;PWD=password;DSN=datasourcename;[LOGINTIMEOUT=seconds;]

None

MicrosoftExchange

Exchange4.0;MAPILEVEL=folderpath;[TABLETYPE={0|1}];[PROFILE=profile;][PWD=password;][DATABASE=database;]

drive:\path\filename.mdb

Remarks

Ifthespecifierisonly"ODBC;",theODBCdriverdisplaysadialogboxlistingallregisteredODBCdatasourcenamessothattheusercanselectadatabase.

IfapasswordisrequiredbutnotprovidedintheConnectpropertysetting,alogindialogboxisdisplayedthefirsttimeatableisaccessedbytheODBCdriverandagainiftheconnectionisclosedandreopened.

FordatainMicrosoftExchange,therequiredMAPILEVELkeyshouldbe

settoafully-resolvedfolderpath(forexample,"Mailbox-PatSmithIAlpha/Today").Thepathdoesnotincludethenameofthefolderthatwillbeopenedasatable;thatfolder’snameshouldinsteadbespecifiedasthenameargumenttotheCreateTablemethod.TheTABLETYPEkeyshouldbesetto"0"toopenafolder(default)or"1"toopenanaddressbook.ThePROFILEkeydefaultstotheprofilecurrentlyinuse.

ForbasetablesinaMicorosoftJetdatabase(.mdb),theConnectpropertysettingisazero-lengthstring("").

YoucansettheConnectpropertyforaDatabaseobjectbyprovidingasourceargumenttotheOpenDatabasemethod.Youcancheckthesettingtodeterminethetype,path,userID,password,orODBCdatasourceofthedatabase.

OnaQueryDefobjectinaMicrosoftJetworkspace,youcanusetheConnectpropertywiththeReturnsRecordspropertytocreateanODBCSQLpass-throughquery.Thedatabasetypeoftheconnectionstringis"ODBC;",andtheremainderofthestringcontainsinformationspecifictotheODBCdriverusedtoaccesstheremotedata.Formoreinformation,seethedocumentationforthespecificdriver.

Notes

YoumustsettheConnectpropertybeforeyousettheReturnsRecordsproperty.

Youmusthaveaccesspermissionstothecomputerthatcontainsthedatabaseserveryou'retryingtoaccess.

ConnectionProperty

OnaDatabaseobject,returnstheConnectionobjectthatcorrespondstothedatabase(ODBCDirectworkspacesonly).

OnaRecordsetobject,returnstheConnectionobjectthatownstheRecordset(ODBCDirectworkspacesonly).


ThereturnvalueisanobjectvariablethatrepresentstheConnection.OnaDatabaseobject,theConnectionpropertyisread-only,whileonaRecordsetobjectthepropertyisread-write.

Remarks

OnaDatabaseobject,usetheConnectionpropertytoobtainareferencetoaConnectionobjectthatcorrespondstotheDatabase.InDAO,aConnectionobjectanditscorrespondingDatabaseobjectaresimplytwodifferentobjectvariablereferencestothesameobject.TheDatabasepropertyofaConnectionobjectandtheConnectionpropertyofaDatabaseobjectmakeiteasiertochangeconnectionstoanODBCdatasourcethroughtheMicrosoftJetdatabaseenginetouse

ODBCDirect.

ContainerProperty

ReturnsthenameoftheContainerobjecttowhichaDocumentobjectbelongs(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaStringdatatype.

CountProperty

Returnsthenumberofobjectsinacollection.

ReturnValue

ThereturnvalueisanIntegerdatatype.

Remarks

Becausemembersofacollectionbeginwith0,youshouldalwayscodeloopsstartingwiththe0memberandendingwiththevalueoftheCountpropertyminus1.IfyouwanttoloopthroughthemembersofacollectionwithoutcheckingtheCountproperty,youcanuseaForEach...Nextcommand.

TheCountpropertysettingisneverNull.Ifitsvalueis0,therearenoobjectsinthecollection.

DatabaseProperty

ReturnstheDatabaseobjectthatcorrespondstothisconnection(ODBCDirectworkspacesonly).

ReturnValues

ThereturnvalueisanobjectvariablethatrepresentsaDatabaseobject.

Remarks

OnaConnectionobject,usetheDatabasepropertytoobtainareferencetoaDatabaseobjectthatcorrespondstotheConnection.InDAO,aConnectionobjectanditscorrespondingDatabaseobjectaresimplytwodifferentobjectvariablereferencestothesameobject.TheDatabasepropertyofaConnectionobjectandtheConnectionpropertyofaDatabaseobjectmakeiteasiertochangeconnectionstoanODBCdatasourcethroughtheMicrosoftJetdatabaseenginetouseODBCDirect.

DataUpdatableProperty

ReturnsavaluethatindicateswhetherthedatainthefieldrepresentedbyaFieldobjectisupdatable.

ReturnValues

ThereturnvalueisaBooleandatatypethatreturnsTrueifthedatainthefieldisupdatable.

Remarks

UsethispropertytodeterminewhetheryoucanchangetheValuepropertysettingofaFieldobject.ThispropertyisalwaysFalseonaFieldobjectwhoseAttributespropertyisdbAutoIncrField.

YoucanusetheDataUpdatablepropertyonFieldobjectsthatareappendedtotheFieldscollectionofQueryDef,Recordset,andRelationobjects,butnottheFieldscollectionofIndexorTableDefobjects.

DateCreated,LastUpdatedProperties

DateCreated?returnsthedateandtimethatanobjectwascreated,orthedateandtimeabasetablewascreatediftheobjectisatable-typeRecordsetobject(MicrosoftJetworkspacesonly).

LastUpdated?returnsthedateandtimeofthemostrecentchangemadetoanobject,ortoabasetableiftheobjectisatable-typeRecordsetobject(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaVariant(Date/Timesubtype).

Remarks

Fortable-typeRecordsetobjects,thedateandtimesettingsarederivedfromthecomputeronwhichthebasetablewascreatedorlastupdated.Forotherobjects,DateCreatedandLastUpdatedreturnthedateandtimethattheobjectwascreatedorlastupdated.Inamultiuserenvironment,usersshouldgetthesesettingsdirectlyfromthefileserver

toavoiddiscrepanciesintheDateCreatedandLastUpdatedpropertysettings.

DefaultCursorDriverProperty

SetsorreturnsthetypeofcursordriverusedontheconnectioncreatedbytheOpenConnectionorOpenDatabasemethods(ODBCDirectworkspacesonly).


ThesettingorreturnvalueisaLongthatcanbesettooneofthefollowingconstants:


dbUseDefaultCursor(Default)Usesserver-sidecursorsiftheserversupportsthem;otherwiseusetheODBCCursorLibrary.

dbUseODBCCursor

AlwaysusestheODBCCursorLibrary.Thisoptionprovidesbetterperformanceforsmallresultsets,butdegradesquicklyforlargerresultsets.

dbUseServerCursor

Alwaysusesserver-sidecursors.Formostlargeoperationsthisoptionprovidesbetterperformance,butmightcausemorenetworktraffic.

dbUseClientBatchCursor Alwaysusestheclientbatchcursorlibrary.

Thisoptionisrequiredforbatchupdates.

dbUseNoCursor

Opensallcursors(thatis,Recordsetobjects)asforward-onlytype,read-only,witharowsetsizeof1.Alsoknownas"cursorlessqueries."

Remarks

Thispropertysettingonlyaffectsconnectionsestablishedafterthepropertyhasbeenset.ChangingtheDefaultCursorDriverpropertyhasnoeffectonexistingconnections.

DefaultTypeProperty

Setsorreturnsavaluethatindicateswhattypeofworkspace(MicrosoftJetorODBCDirect)willbeusedbythenextWorkspaceobjectcreated.


ThesettingorreturnvalueisaLongthatcanbesettoeitherofthefollowingconstants:


dbUseJet CreatesWorkspaceobjectsconnectedtotheMicrosoftJetdatabaseengine

dbUseODBC CreatesWorkspaceobjectsconnectedtoanODBCdatasource

Remarks

ThesettingcanbeoverriddenforasingleWorkspacebysettingthetypeargumenttotheCreateWorkspacemethod.

DefaultUser,DefaultPasswordProperties

DefaultUser?setstheusernameusedtocreatethedefaultWorkspacewhenitisinitialized.

DefaultPassword?setsthepasswordusedtocreatethedefaultWorkspacewhenitisinitialized.

Settings

ThesettingforDefaultUserisaStringdatatype.Itcanbe1–20characterslonginMicrosoftJetworkspacesandanylengthinODBCDirectworkspaces,anditcanincludealphabeticcharacters,accentedcharacters,numbers,spaces,andsymbolsexceptfor:"(quotationmarks),/(forwardslash),\(backslash),[](brackets),:(colon),|(pipe),<(less-thansign),>(greater-thansign),+(plussign),=(equalsign),;(semicolon),,(comma),?(questionmark),*(asterisk),leadingspaces,andcontrolcharacters(ASCII00toASCII31).

ThesettingforDefaultPasswordisaStringdatatypethatcanbeupto14characterslonginMicrosoftJetdatabasesandanylengthin

ODBCDirectconnections.ItcancontainanycharacterexceptASCII0.


Bydefault,theDefaultUserpropertyissetto"admin"andtheDefaultPasswordpropertyissettoazero-lengthstring("").

Remarks

Usernamesaren'tusuallycase-sensitive;however,ifyou'rere-creatingauseraccountthatwasdeletedorcreatedinadifferentworkgroup,theusernamemustbeanexactcase-sensitivematchoftheoriginalname.Passwordsarecase-sensitive.

Typically,youusetheCreateWorkspacemethodtocreateaWorkspaceobjectwithagivenusernameandpassword.However,forbackwardcompatibilitywithearlierversionsandforconveniencewhenyoudon'timplementasecureddatabase,theMicrosoftJetdatabaseengineautomaticallycreatesadefaultWorkspaceobjectwhenneededifoneisn'talreadyopen.Inthiscase,theDefaultUserandDefaultPasswordpropertyvaluesdefinetheuserandpasswordforthedefaultWorkspaceobject.

Forthispropertytotakeeffect,youshouldsetitbeforecallinganyDAOmethods.

DefaultValueProperty

SetsorreturnsthedefaultvalueofaFieldobject.ForaFieldobjectnotyetappendedtotheFieldscollection,thispropertyisread/write(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringdatatypethatcancontainamaximumof255characters.Itcanbeeithertextoranexpression.Ifthepropertysettingisanexpression,itcan'tcontainuser-definedfunctions,MicrosoftJetdatabaseengineSQLaggregatefunctions,orreferencestoqueries,forms,orotherFieldobjects.

NoteYoucanalsosettheDefaultValuepropertyofaFieldobjectonaTableDefobjecttoaspecialvaluecalled"GenUniqueID()".Thiscausesarandomnumbertobeassignedtothisfieldwheneveranewrecordisaddedorcreated,therebygivingeachrecordauniqueidentifier.Thefield'sTypepropertymustbeLong.

Remarks

TheavailabilityoftheDefaultValuepropertydependsontheobjectthat

containstheFieldscollection,asshowninthefollowingtable.

IftheFieldscollectionbelongstoanThenDefaultValueisIndexobject NotsupportedQueryDefobject Read-onlyRecordsetobject Read-onlyRelationobject NotsupportedTableDefobject Read/write

Whenanewrecordiscreated,theDefaultValuepropertysettingisautomaticallyenteredasthevalueforthefield.YoucanchangethefieldvaluebysettingitsValueproperty.

TheDefaultValuepropertydoesn'tapplytoAutoNumberandLongBinaryfields.

DescriptionProperty

Returnsadescriptivestringassociatedwithanerror.ThisisthedefaultpropertyfortheErrorobject.

ReturnValues

ThereturnvalueisaStringdatatypethatdescribestheerror.

Remarks

TheDescriptionpropertycomprisesashortdescriptionoftheerror.Usethispropertytoalerttheuseraboutanerrorthatyoucannotordonotwanttohandle.

DesignMasterIDProperty

Setsorreturnsa16-bytevaluethatuniquelyidentifiestheDesignMasterinareplicaset(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaGUIDthatuniquelyidentifiestheDesignMaster.

Remarks

YoushouldsettheDesignMasterIDpropertyonlyifyouneedtomovethecurrentDesignMaster.SettingthispropertymakesaspecificreplicainthereplicasettheDesignMaster.

CautionNevercreateasecondDesignMasterinareplicaset.TheexistenceofasecondDesignMastercanresultinthelossofdata.

Underextremecircumstances—forexample,iftheDesignMasteriserasedorcorrupted—youcansetthispropertyatthecurrentreplica.However,settingthispropertyatareplicawhenthereisalreadyanotherDesignMasterinthesetmightpartitionyourreplicasetintotwo

irreconcilablesetsandpreventanyfurthersynchronizationofdata.

IfyoudecidetomakeareplicathenewDesignMasterfortheset,synchronizeitwithallthereplicasinthereplicasetbeforesettingtheDesignMasterIDpropertyinthereplica.ThereplicamustbeopeninexclusivemodeinordertomakeittheDesignMaster.

Ifyoumakeareplicathatisdesignatedread-onlyintotheDesignMaster,thetargetreplicaismaderead/write;theoldDesignMasteralsoremainsread/write.

TheDesignMasterIDpropertysettingisstoredintheMSysRepInfosystemtable.

DirectionProperty

SetsorreturnsavaluethatindicateswhetheraParameterobjectrepresentsaninputparameter,anoutputparameter,both,orthereturnvaluefromtheprocedure(ODBCDirectworkspacesonly).


ThesettingorreturnvalueisaLongthatcanbesettooneofthefollowingconstants:


dbParamInput (Default)Passesinformationtotheprocedure.

dbParamInputOutput Passesinformationbothtoandfromtheprocedure.

dbParamOutput ReturnsinformationfromtheprocedureasinanoutputparameterinSQL.

dbParamReturnValue Passesthereturnvaluefromaprocedure.

Remarks

UsetheDirectionpropertytodeterminewhethertheparameterisan

inputparameter,outputparameter,both,orthereturnvaluefromtheprocedure.SomeODBCdriversdonotprovideinformationonthedirectionofparameterstoaSELECTstatementorprocedurecall.Inthesecases,itisnecessarytosetthedirectionpriortoexecutingthequery.

Forexample,thefollowingprocedurereturnsavaluefromastoredprocedurenamed"get_employees":

{?=callget_employees}

Thiscallproducesoneparameter—thereturnvalue.YouneedtosetthedirectionofthisparametertodbParamOutputordbParamReturnValuebeforeexecutingtheQueryDef.

YouneedtosetallparameterdirectionsexceptdbParamInputbeforeaccessingorsettingthevaluesoftheparametersandbeforeexecutingtheQueryDef.

YoushouldusedbParamReturnValueforreturnvalues,butincaseswherethatoptionisnotsupportedbythedriverortheserver,youcanusedbParamOutputinstead.

NoteTheMicrosoftSQLServer6.0driverautomaticallysetstheDirectionpropertyforallprocedureparameters.NotallODBCdriverscandeterminethedirectionofaqueryparameter.Inthesecases,itisnecessarytosetthedirectionpriortoexecutingthequery.

DistinctCountProperty

ReturnsavaluethatindicatesthenumberofuniquevaluesfortheIndexobjectthatareincludedintheassociatedtable(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaLongdatatype.

Remarks

ChecktheDistinctCountpropertytodeterminethenumberofuniquevalues,orkeys,inanindex.Anykeyiscountedonlyonce,eventhoughtheremaybemultipleoccurrencesofthatvalueiftheindexpermitsduplicatevalues.Thisinformationisusefulinapplicationsthatattempttooptimizedataaccessbyevaluatingindexinformation.ThenumberofuniquevaluesisalsoknownasthecardinalityofanIndexobject.

TheDistinctCountpropertywon'talwaysreflecttheactualnumberofkeysataparticulartime.Forexample,achangecausedbyarolledbacktransactionwon'tbereflectedimmediatelyintheDistinctCountproperty.TheDistinctCountpropertyvaluealsomaynotreflectthedeletionof

recordswithuniquekeys.ThenumberwillbeaccurateimmediatelyafteryouusetheCreateIndexmethod.

EditModeProperty

Returnsavaluethatindicatesthestateofeditingforthecurrentrecord.

ReturnValues

ThereturnvalueisaLongthatindicatesthestateofediting,aslistedinthefollowingtable.

Constant DescriptiondbEditNone Noeditingoperationisinprogress.

DbEditInProgress TheEditmethodhasbeeninvoked,andthecurrentrecordisinthecopybuffer.

dbEditAddTheAddNewmethodhasbeeninvoked,andthecurrentrecordinthecopybufferisanewrecordthathasn'tbeensavedinthedatabase.

Remarks

TheEditModepropertyisusefulwhenaneditingprocessisinterrupted,forexample,byanerrorduringvalidation.YoucanusethevalueoftheEditModepropertytodeterminewhetheryoushouldusetheUpdateorCancelUpdatemethod.

YoucanalsochecktoseeiftheLockEditspropertysettingisTrueandtheEditModepropertysettingisdbEditInProgresstodeterminewhetherthecurrentpageislocked.

FieldSizeProperty

Returnsthenumberofbytesusedinthedatabase(ratherthaninmemory)ofaMemoorLongBinaryFieldobjectintheFieldscollectionofaRecordsetobject.

ReturnValues

ThereturnvalueisaLongthatindicatesthenumberofcharacters(foraMemofield)orthenumberofbytes(foraLongBinaryfield).

Remarks

YoucanuseFieldSizewiththeAppendChunkandGetChunkmethodstomanipulatelargefields.

BecausethesizeofaLongBinaryorMemofieldcanexceed64K,youshouldassignthevaluereturnedbyFieldSizetoavariablelargeenoughtostoreaLongvariable.

TodeterminethesizeofaFieldobjectotherthanMemoandLongBinarytypes,usetheSizeproperty.

NoteInanODBCDirectworkspace,theFieldSizepropertyisnotavailableinthefollowingsituations:

IfthedatabaseserverorODBCdriverdoesnotsupportserver-sidecursors.

IfyouareusingtheODBCcursorlibrary(thatis,theDefaultCursorDriverpropertyissettodbUseODBC,ortodbUseDefaultwhentheserverdoesnotsupportserver-sidecursors).

Ifyouareusingacursorlessquery(thatis,theDefaultCursorDriverpropertyissettodbUseNoCursor).

Forexample,MicrosoftSQLServerversion4.21doesnotsupportserver-sidecursors,sotheFieldSizepropertyisnotavailable.

TheFieldSizepropertyandtheVBALen()orLenB()functionsmayreturndifferentvaluesasthelengthofthesamestring.StringsarestoredinaMicrosoftJetdatabaseinmulti-bytecharacterset(MBCS)form,butexposedthroughVBAinUnicodeformat.Asaresult,theLen()functionwillalwaysreturnthenumberofcharacters,LenBwillalwaysreturnthenumberofcharactersX2(Unicodeusestwobytesforeachcharacter),butFieldSizewillreturnsomevalueinbetweenifthestringhasanyMBCScharacters.Forexample,givenastringconsistingofthreenormalcharactersandtwoMBCScharacters,Len()willreturn5,LenB()willreturn10,andFieldSizewillreturn7,thesumof1foreachnormalcharacterand2foreachMBCScharacter.

FilterProperty

SetsorreturnsavaluethatdeterminestherecordsincludedinasubsequentlyopenedRecordsetobject(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringdatatypethatcontainstheWHEREclauseofanSQLstatementwithoutthereservedwordWHERE.

Remarks

UsetheFilterpropertytoapplyafiltertoadynaset-,snapshot-,orforward-only–typeRecordsetobject.

YoucanusetheFilterpropertytorestricttherecordsreturnedfromanexistingobjectwhenanewRecordsetobjectisopenedbasedonanexistingRecordsetobject.

Inmanycases,it'sfastertoopenanewRecordsetobjectbyusinganSQLstatementthatincludesaWHEREclause.

UsetheU.S.dateformat(month-day-year)whenyoufilterfields

containingdates,evenifyou'renotusingtheU.S.versionoftheMicrosoftJetdatabaseengine(inwhichcaseyoumustassembleanydatesbyconcatenatingstrings,forexample,strMonth&"-"&strDay&"-"&strYear).Otherwise,thedatamaynotbefilteredasyouexpect.

Ifyousetthepropertytoastringconcatenatedwithanon-integervalue,andthesystemparametersspecifyanon-U.S.decimalcharactersuchasacomma(forexample,strFilter="PRICE>"&lngPrice,andlngPrice=125,50),anerroroccurswhenyoutrytoopenthenextRecordset.Thisisbecauseduringconcatenation,thenumberwillbeconvertedtoastringusingyoursystem'sdefaultdecimalcharacter,andMicrosoftJetSQLonlyacceptsU.S.decimalcharacters.

ForeignProperty

ReturnsavaluethatindicateswhetheranIndexobjectrepresentsaforeignkeyinatable(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaBooleandatatypethatreturnsTrueiftheIndexobjectrepresentsaforeignkey.

Remarks

Aforeignkeyconsistsofoneormorefieldsinaforeigntablethatuniquelyidentifyallrowsinaprimarytable.

TheMicrosoftJetdatabaseenginecreatesanIndexobjectfortheforeigntableandsetstheForeignpropertywhenyoucreatearelationshipthatenforcesreferentialintegrity.

ForeignNameProperty

SetsorreturnsavaluethatspecifiesthenameoftheFieldobjectinaforeigntablethatcorrespondstoafieldinaprimarytableforarelationship(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringdatatypethatevaluatestothenameofaFieldintheassociatedTableDefobject'sFieldscollection.

IftheRelationobjectisn'tappendedtotheDatabase,buttheFieldisappendedtotheRelationobject,theForeignNamepropertyisread/write.OncetheRelationobjectisappendedtothedatabase,theForeignNamepropertyisread-only.

Remarks

OnlyaFieldobjectthatbelongstotheFieldscollectionofaRelationobjectcansupporttheForeignNameproperty.

TheNameandForeignNamepropertysettingsforaFieldobjectspecifythenamesofthecorrespondingfieldsintheprimaryandforeigntablesof

arelationship.TheTableandForeignTablepropertysettingsforaRelationobjectdeterminetheprimaryandforeigntablesofarelationship.

Forexample,ifyouhadalistofvalidpartcodes(inafieldnamedPartNo)storedinaValidPartstable,youcouldestablisharelationshipwithanOrderItemtablesuchthatifapartcodewereenteredintotheOrderItemtable,itwouldhavetoalreadyexistintheValidPartstable.Ifthepartcodedidn'texistintheValidPartstableandyouhadnotsettheAttributespropertyoftheRelationobjecttodbRelationDontEnforce,atrappableerrorwouldoccur.

Inthiscase,theValidPartstableistheforeigntable,sotheForeignTablepropertyoftheRelationobjectwouldbesettoValidPartsandtheTablepropertyoftheRelationobjectwouldbesettoOrderItem.TheNameandForeignNamepropertiesoftheFieldobjectintheRelationobject'sFieldscollectionwouldbesettoPartNo.

Thefollowingillustrationdepictstherelationdescribedabove.

ForeignTableProperty

Setsorreturnsthenameoftheforeigntableinarelationship(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringdatatypethatevaluatestothenameofatableintheDatabaseobject'sTableDefscollection.Thispropertyisread/writeforanewRelationobjectnotyetappendedtoacollectionandread-onlyforanexistingRelationobjectintheRelationscollection.

Remarks

TheForeignTablepropertysettingofaRelationobjectistheNamepropertysettingoftheTableDeforQueryDefobjectthatrepresentstheforeigntableorquery;theTablepropertysettingistheNamepropertysettingoftheTableDeforQueryDefobjectthatrepresentstheprimarytableorquery.

Forexample,ifyouhadalistofvalidpartcodes(inafieldnamedPartNo)storedinaValidPartstable,youcouldestablisharelationship

withanOrderItemtablesuchthatifapartcodewereenteredintotheOrderItemtable,itwouldhavetoalreadybeintheValidPartstable.Ifthepartcodedidn'texistintheValidPartstableandyouhadnotsettheAttributespropertyoftheRelationobjecttodbRelationDontEnforce,atrappableerrorwouldoccur.

Inthiscase,theValidPartstableistheprimarytable,sotheTablepropertyoftheRelationobjectwouldbesettoValidPartsandtheForeignTablepropertyoftheRelationobjectwouldbesettoOrderItem.TheNameandForeignNamepropertiesoftheFieldobjectintheRelationobject'sFieldscollectionwouldbesettoPartNo.

Thefollowingillustrationdepictstherelationdescribedabove.

IgnoreNullsProperty

SetsorreturnsavaluethatindicateswhetherrecordsthathaveNullvaluesintheirindexfieldshaveindexentries(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleanthatisTrueifthefieldswithNullvaluesdon'thaveanindexentry.Thispropertyisread/writeforanewIndexobjectnotyetappendedtoacollectionandread-onlyforanexistingIndexobjectinanIndexescollection.

Remarks

Tospeeduptheprocessofsearchingforrecords,youcandefineanindexforafield.IfyouallowNullentriesinanindexedfieldandexpectmanyoftheentriestobeNull,youcansettheIgnoreNullspropertyfortheIndexobjecttoTruetoreducetheamountofstoragespacethattheindexuses.

TheIgnoreNullspropertysettingandtheRequiredpropertysettingtogetherdeterminewhetherarecordwithaNullindexvaluehasanindex

entry.

IfIgnoreNullsis AndRequiredis Then

True FalseANullvalueisallowedintheindexfield;noindexentryadded.

False FalseANullvalueisallowedintheindexfield;indexentryadded.

TrueorFalse TrueANullvalueisn'tallowedintheindexfield;noindexentryadded.

IndexProperty

SetsorreturnsavaluethatindicatesthenameofthecurrentIndexobjectinatable-typeRecordsetobject(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringdatatypethatevaluatestothenameofanIndexobjectintheIndexescollectionoftheTabledefortable-typeRecordsetobject'sTableDefobject.

Remarks

Recordsinbasetablesaren'tstoredinanyparticularorder.SettingtheIndexpropertychangestheorderofrecordsreturnedfromthedatabase;itdoesn'taffecttheorderinwhichtherecordsarestored.

ThespecifiedIndexobjectmustalreadybedefined.IfyousettheIndexpropertytoanIndexobjectthatdoesn'texistoriftheIndexpropertyisn'tsetwhenyouusetheSeekmethod,atrappableerroroccurs.

ExaminetheIndexescollectionofaTableDefobjecttodeterminewhatIndexobjectsareavailabletotable-typeRecordsetobjectscreatedfrom

thatTableDefobject.

YoucancreateanewindexforthetablebycreatinganewIndexobject,settingitsproperties,appendingittotheIndexescollectionoftheunderlyingTableDefobject,andthenreopeningtheRecordsetobject.

Recordsreturnedfromatable-typeRecordsetobjectcanbeorderedonlybytheindexesdefinedfortheunderlyingTableDefobject.Tosortrecordsinsomeotherorder,youcanopenadynaset-,snapshot-,orforward-only–typeRecordsetobjectbyusinganSQLstatementwithanORDERBYclause.

Notes

Youdon'thavetocreateindexesfortables.Withlarge,unindexedtables,accessingaspecificrecordorcreatingaRecordsetobjectcantakealongtime.Ontheotherhand,creatingtoomanyindexesslowsdownupdate,append,anddeleteoperationsbecauseallindexesareautomaticallyupdated.

Recordsreadfromtableswithoutindexesarereturnedinnoparticularsequence.

TheAttributespropertyofeachFieldobjectintheIndexobjectdeterminestheorderofrecordsandconsequentlydeterminestheaccesstechniquestouseforthatindex.

Auniqueindexhelpsoptimizefindingrecords.

Indexesdon'taffectthephysicalorderofabasetable?indexesaffectonlyhowtherecordsareaccessedbythetable-typeRecordsetobjectwhenaparticularindexischosenorwhen

Recordsetisopened.

InheritProperty

SetsorreturnsavaluethatindicateswhethernewDocumentobjectswillinheritadefaultPermissionspropertysetting(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleandatatype.IfyousetthepropertytoTrue,DocumentobjectsinheritadefaultPermissionspropertysetting.

Remarks

UsetheInheritpropertyinconjunctionwiththePermissionspropertytodefinewhatpermissionsnewdocumentswillautomaticallyhavewhenthey'recreated.IfyousettheInheritpropertytoTrue,andthensetapermissiononacontainer,thenwheneveranewdocumentiscreatedinthatcontainer,thatpermissionwillbesetonthenewdocument.Thisisaveryconvenientwayofpresettingpermissionsonanobject.

SettingtheInheritpropertywillnotaffectexistingdocumentsinthecontainer?youcan'tmodifyallthepermissionsonallexistingdocuments

inacontainerbysettingtheInheritpropertyandanewpermission.ItwillaffectonlynewdocumentsthatarecreatedaftertheInheritpropertyisset.

InheritedProperty

ReturnsavaluethatindicateswhetheraPropertyobjectisinheritedfromanunderlyingobject.

ReturnValues

ThereturnvalueisaBooleandatatypethatisTrueifthePropertyobjectisinherited.Forbuilt-inPropertyobjectsthatrepresentpredefinedproperties,theonlypossiblereturnvalueisFalse.ThispropertyisalwaysFalseinanODBCDirectworkspace.

Remarks

YoucanusetheInheritedpropertytodeterminewhetherauser-definedPropertywascreatedfortheobjectitappliesto,orwhetherthePropertywasinheritedfromanotherobject.Forexample,supposeyoucreateanewPropertyforaQueryDefobjectandthenopenaRecordsetobjectfromtheQueryDefobject.ThisnewPropertywillbepartoftheRecordsetobject'sPropertiescollection,anditsInheritedpropertywillbesettoTruebecausethepropertywascreatedfortheQueryDefobject,nottheRecordsetobject.

IniPathProperty

SetsorreturnsinformationabouttheWindowsRegistrykeythatcontainsvaluesfortheMicrosoftJetdatabaseengine(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringdatatypethatpointstoauser-suppliedportionoftheWindowsRegistrykeycontainingMicrosoftJetdatabaseenginesettingsorparametersneededforinstallableISAMdatabases.

Remarks

YoucanconfiguretheMicrosoftJetenginewiththeWindowsRegistry.YoucanusetheRegistrytosetoptions,suchasinstallableISAMDLLs.

Forthisoptiontohaveanyeffect,youmustsettheIniPathpropertybeforeyourapplicationinvokesanyotherDAOcode.Thescopeofthissettingislimitedtoyourapplicationandcan'tbechangedwithoutrestartingyourapplication.

YoualsousetheRegistrytoprovideinitializationparametersforsomeinstallableISAMdatabasedrivers.Forexample,touseParadoxversion4.0,settheIniPathpropertytoapartoftheRegistrycontainingtheappropriateparameters.

ThispropertyrecognizeseitherHKEY_LOCAL_MACHINEorHKEY_LOCAL_USER.Ifnorootkeyissupplied,thedefaultisHKEY_LOCAL_MACHINE.

MicrosoftJetversions2.5orearlierkeptinitializationinformationin.inifiles.

IsolateODBCTransProperty

SetsorreturnsavaluethatindicateswhethermultipletransactionsthatinvolvethesameMicrosoftJet-connectedODBCdatasourceareisolated(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleandatatypethatisTrueifyouwanttoisolatetransactionsinvolvingthesameODBC(OpenDatabaseConnectivity)connection.False(thedefault)willallowmultipletransactionsinvolvingthesameODBCconnection.

Remarks

Insomesituations,youneedtohavemultiplesimultaneoustransactionspendingonthesameODBCconnection.Todothis,youneedtoopenaseparateWorkspaceforeachtransaction.AlthougheachWorkspacecanhaveitsownODBCconnectiontothedatabase,thisslowssystemperformance.Becausetransactionisolationisn'tusuallyrequired,ODBCconnectionsfrommultipleWorkspaceobjectsopenedbythesameuseraresharedbydefault.

SomeODBCservers,suchasMicrosoftSQLServer,don'tallowsimultaneoustransactionsonasingleconnection.Ifyouneedtohavemorethanonetransactionatatimependingagainstsuchadatabase,settheIsolateODBCTranspropertytoTrueoneachWorkspaceassoonasyouopenit.ThisforcesaseparateODBCconnectionforeachWorkspace.

KeepLocalProperty

Setsorreturnsavalueonatable,query,form,report,macro,ormodulethatyoudonotwanttoreplicatewhenthedatabaseisreplicated(MicrosoftJetworkspacesonly).

NoteBeforegettingorsettingtheKeepLocalpropertyonaTableDef,orQueryDefobject,youmustcreateitbyusingtheCreatePropertymethodandappendittothePropertiescollectionfortheobject.


ThesettingorreturnvalueisaTextdatatype.Ifyousetthispropertyto"T",theobjectwillremainlocalwhenthedatabaseisreplicated.Youcan'tusetheKeepLocalpropertyonobjectsaftertheyhavebeenreplicated.

Remarks

OnceyousettheKeepLocalproperty,itwillappearinthePropertiescollectionfortheDocumentobjectrepresentingthehostobject.

BeforesettingtheKeepLocalproperty,youshouldcheckthevalueofthe

Replicableproperty.

Afteryoumakeadatabasereplicable,allnewobjectscreatedwithintheDesignMaster,orinanyotherreplicasintheset,arelocalobjects.Localobjectsremaininthereplicainwhichthey'recreatedandaren'tcopiedthroughoutthereplicaset.Eachtimeyoumakeanewreplicaintheset,thenewreplicacontainsallthereplicableobjectsfromthesourcereplica,butnoneofthelocalobjectsfromthesourcereplica.

Ifyoucreateanewobjectinareplicaandwanttochangeitfromlocaltoreplicablesothatalluserscanuseit,youcaneithercreatetheobjectinorimportitintotheDesignMaster.Besuretodeletethelocalobjectfromanyreplicas;otherwise,youwillencounteradesignerror.AftertheobjectispartoftheDesignMaster,settheobject'sReplicablepropertytoTrue.

TheobjectonwhichyouaresettingtheKeepLocalpropertymighthavealreadyinheritedthatpropertyfromanotherobject.However,thevaluesetbytheotherobjecthasnoeffectonthebehavioroftheobjectyouwanttokeeplocal.Youmustexplicitlysetthepropertyforeachobject.

LastModifiedProperty

Returnsabookmarkindicatingthemostrecentlyaddedorchangedrecord.

ReturnValues

ThereturnvalueisaVariantarrayofBytedata.

Remarks

YoucanusetheLastModifiedpropertytomovetothemostrecentlyaddedorupdatedrecord.UsetheLastModifiedpropertywithtable-anddynaset-typeRecordsetobjects.ArecordmustbeaddedormodifiedintheRecordsetobjectitselfinorderfortheLastModifiedpropertytohaveavalue.

LockEditsProperty

Setsorreturnsavalueindicatingthetypeoflockingthatisineffectwhileediting.


ThesettingorreturnvalueisaBooleanthatindicatesthetypeoflocking,asspecifiedinthefollowingtable.

Value Description

True

Default.Pessimisticlockingisineffect.The2Kpagecontainingtherecordyou'reeditingislockedassoonasyoucalltheEditmethod.

FalseOptimisticlockingisineffectforediting.The2KpagecontainingtherecordisnotlockeduntiltheUpdatemethodisexecuted.

Remarks

YoucanusetheLockEditspropertywithupdatableRecordsetobjects.

Ifapageislocked,nootherusercaneditrecordsonthesamepage.If

yousetLockEditstoTrueandanotheruseralreadyhasthepagelocked,anerroroccurswhenyouusetheEditmethod.Otheruserscanreaddatafromlockedpages.

IfyousettheLockEditspropertytoFalseandlaterusetheUpdatemethodwhileanotheruserhasthepagelocked,anerroroccurs.Toseethechangesmadetoyourrecordbyanotheruser,usetheMovemethodwith0astheargument;however,ifyoudothis,youwillloseyourchanges.

WhenworkingwithMicrosoftJet-connectedODBCdatasources,theLockEditspropertyisalwayssettoFalse,oroptimisticlocking.TheMicrosoftJetdatabaseenginehasnocontroloverthelockingmechanismsusedinexternaldatabaseservers.

NoteYoucanpresetthevalueofLockEditswhenyoufirstopentheRecordsetbysettingthelockeditsargumentoftheOpenRecordsetmethod.SettingthelockeditsargumenttodbPessimisticwillsettheLockEditspropertytoTrue,andsettinglockeditstoanyothervaluewillsettheLockEditspropertytoFalse.

LoginTimeoutProperty

SetsorreturnsthenumberofsecondsbeforeanerroroccurswhenyouattempttologontoanODBCdatabase.


ThesettingorreturnvalueisanIntegerrepresentingthenumberofsecondsbeforealogintimeouterroroccurs.ThedefaultLoginTimeoutpropertysettingis20seconds.WhentheLoginTimeoutpropertyissetto0,notimeoutoccurs.

Remarks

Whenyou'reattemptingtologontoanODBCdatabase,suchasMicrosoftSQLServer,theconnectioncanfailasaresultofnetworkerrorsorbecausetheserverisn'trunning.Ratherthanwaitingforthedefault20secondstoconnect,youcanspecifyhowlongtowaitbeforeraisinganerror.Loggingontotheserverhappensimplicitlyaspartofanumberofdifferentevents,suchasrunningaqueryonanexternalserverdatabase.

YoucanuseLoginTimeoutontheDBEngineobjectinbothMicrosoftJet

andODBCDirectworkspaces.YoucanuseLoginTimeoutontheWorkspaceobjectonlyinODBCDirectworkspaces.Settingthepropertyto-1onaWorkspacewilldefaulttothecurrentsettingofDBEngine.LoginTimeout.YoucanchangethispropertyinaWorkspaceatanytime,andthenewsettingwilltakeeffectwiththenextConnectionorDatabaseobjectopened.

ThedefaultvalueisdeterminedbytheODBCdriver.InaMicrosoftJetworkspace,youcanoverridethedriver’sdefaultvaluebycreatinganew“ODBC”keyintheRegistrypath\HKEY_LOCAL_MACHINE\SOFTWARE\Jet\3.5\,creatingaLoginTimeoutparameterinthiskey,andsettingthevalueasdesired.

LogMessagesProperty

SetsorreturnsavaluethatspecifiesifthemessagesreturnedfromaMicrosoftJet-connectedODBCdatasourcearerecorded(MicrosoftJetworkspacesonly).

NoteBeforeyoucansetorgetthevalueoftheLogMessagesproperty,youmustcreatetheLogMessagespropertywiththeCreatePropertymethod,andappendittothePropertiescollectionofaQueryDefobject.


ThesettingorreturnvalueisaBooleanthatisTrueifODBC-generatedmessagesarerecorded.

Remarks

Somepass-throughqueriescanreturnmessagesinadditiontodata.IfyousettheLogMessagespropertytoTrue,theMicrosoftJetdatabaseenginecreatesatablethatcontainsreturnedmessages.Thetablenameistheusernameconcatenatedwithahyphen(-)andasequentialnumberstartingat00.Forexample,becausethedefaultusernameis

Admin,thetablesreturnedwouldbenamedAdmin-00,Admin-01,andsoon.

Ifyouexpectthequerytoreturnmessages,createandappendauser-definedLogMessagespropertyfortheQueryDefobject,andsetitstypetoBooleananditsvaluetoTrue.

Onceyou'veprocessedtheresultsfromthesetables,youmaywanttodeletethemfromthedatabasealongwiththetemporaryqueryusedtocreatethem.

MaxRecordsProperty

SetsorreturnsthemaximumnumberofrecordstoreturnfromaqueryagainstanODBCdatasource.


ThesettingorreturnvalueisaLongthatrepresentsthenumberofrecordstobereturned.Thedefaultvalueis0,indicatingnolimitonthenumberofrecordsreturned.

Remarks

OncethenumberofrowsspecifiedbyMaxRecordsisreturnedtoyourapplicationinaRecordset,thequeryprocessorwillstopreturningadditionalrecordsevenifmorerecordswouldqualifyforinclusionintheRecordset.Thispropertyisusefulinsituationswherelimitedclientresourcesprohibitmanagementoflargenumbersofrecords.

NoteTheMaxRecordspropertycanonlybeusedwithanODBCdatasource,connectedthrougheitheraMicrosoftJetorODBCDirectworkspace.

NameProperty

Setsorreturnsauser-definednameforaDAOobject.Foranobjectnotappendedtoacollection,thispropertyisread/write.


ThesettingorreturnvalueisaStringthatspecifiesaname.Thenamemuststartwithaletter.ThemaximumnumberofcharactersdependsonthetypeofobjectNameappliesto,asshowninRemarks.Itcanincludenumbersandunderscorecharacters(_)butcan'tincludepunctuationorspaces.

Remarks

TableDef,QueryDef,Field,Index,User,andGroupobjectscan'tsharethesamenamewithanyobjectinthesamecollection.

TheNamepropertyofaRecordsetobjectopenedbyusinganSQLstatementisthefirst256charactersoftheSQLstatement.

Youcanuseanobject'sNamepropertywiththeVisualBasicforApplicationsDimstatementincodetocreateotherinstancesofthe

object.

NoteFormanyoftheDAOobjects,theNamepropertyreflectsthenameasknowntotheDatabaseobject,asinthenameofaTableDef,Field,orQueryDefobject.ThereisnodirectlinkbetweenthenameoftheDAOobjectandtheobjectvariableusedtoreferenceit.

Theread/writeusageoftheNamepropertydependsonthetypeofobjectitappliesto,andwhetherornottheobjecthasbeenappendedtoacollection.InanODBCDirectworkspace,theNamepropertyofanappendedobjectisalwaysread-only.ThefollowingtableindicateswhethertheNamepropertyinaMicrosoftJetworkspaceisread/writeorread-onlyforanobjectthatisappendedtoacollection(unlessotherwisenoted),andalsoindicatesitsmaximumlengthincaseswhereitisread/write.

Object Usage MaximumlengthContainer Read-onlyConnection Read-onlyDatabase Read-onlyDocument Read-onlyFieldUnappended Read/write 64AppendedtoIndex Read-onlyAppendedtoQueryDef Read-onlyAppendedtoRecordset Read-onlyAppendedtoTableDef(native) Read/write 64AppendedtoTableDef(linked)Read-onlyAppendedtoRelation Read-onlyGroupUnappended Read/write 20Appended Read-onlyIndexUnappended Read/write 64Appended Read-onlyParameter Read-onlyProperty

Unappended Read/write 64Appended Read-onlyBuilt-in Read-onlyQueryDefUnappended Read/write 64Temporary Read-onlyAppended Read/write 64Recordset Read-onlyRelationUnappended Read/write 64Appended Read-onlyTableDef Read/write 64UserUnappended Read/write 20Appended Read-onlyWorkspaceUnappended Read/write 20Appended Read-only

NoMatchProperty

IndicateswhetheraparticularrecordwasfoundbyusingtheSeekmethodoroneoftheFindmethods(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaBooleanthatisTrueifthedesiredrecordwasnotfound.WhenyouopenorcreateaRecordsetobject,itsNoMatchpropertyissettoFalse.

Remarks

Tolocatearecord,usetheSeekmethodonatable-typeRecordsetobjectoroneoftheFindmethodsonadynaset-orsnapshot-typeRecordsetobject.ChecktheNoMatchpropertysettingtoseewhethertherecordwasfound.

IftheSeekorFindmethodisunsuccessfulandtheNoMatchpropertyisTrue,thecurrentrecordwillnolongerbevalid.Besuretoobtainthecurrentrecord'sbookmarkbeforeusingtheSeekmethodoraFindmethodifyou'llneedtoreturntothatrecord.

NoteUsinganyoftheMovemethodsonaRecordsetobjectwon'taffectitsNoMatchpropertysetting.

NumberProperty

Returnsanumericvaluespecifyinganerror.

ReturnValues

ThereturnvalueisaLongdatatypethatrepresentsanerrornumber.

Remarks

UsetheNumberpropertytodeterminetheerrorthatoccurred.Thevalueofthepropertycorrespondstoauniquetrapnumberthatcorrespondstoanerrorcondition.Foracompletelistofalltrapnumbersanderrorconditions,seeTrappableMicrosoftJetandDAOErrors.

mk:@MSITStore:daosdk.chm::/idxmsgdb_0x9v.htm

ODBCTimeoutProperty

IndicatesthenumberofsecondstowaitbeforeatimeouterroroccurswhenaQueryDefisexecutedonanODBCdatabase.


ThesettingorreturnvalueisanIntegerrepresentingthenumberofsecondstowaitbeforeatimeouterroroccurs.

WhentheODBCTimeoutpropertyissetto-1,thetimeoutdefaultstothecurrentsettingoftheQueryTimeoutpropertyoftheConnectionorDatabaseobjectthatcontainstheQueryDef.WhentheODBCTimeoutpropertyissetto0,notimeouterroroccurs.

Remarks

Whenyou'reusinganODBCdatabase,suchasMicrosoftSQLServer,delayscanoccurbecauseofnetworktrafficorheavyuseoftheODBCserver.Ratherthanwaitingindefinitely,youcanspecifyhowlongtowaitbeforereturninganerror.

SettingtheODBCTimeoutpropertyofaQueryDefobjectoverridesthe

valuespecifiedbytheQueryTimeoutpropertyoftheConnectionorDatabaseobjectcontainingtheQueryDef,butonlyforthatQueryDefobject.

NoteInanODBCDirectworkspace,aftersettingODBCTimeouttoanexplicitvalueyoucanresetitbacktothedefault(i.e.,-1)onlyonceduringthelifeoftheQueryDefobject.Otherwise,anerrorwilloccur.

OrdinalPositionProperty

SetsorreturnstherelativepositionofaFieldobjectwithinaFieldscollection.ForanobjectnotyetappendedtotheFieldscollection,thispropertyisread/write.


ThesettingorreturnvalueisanIntegerthatspecifiesthenumericorderoffields.Thedefaultis0.

Remarks

TheavailabilityoftheOrdinalPositionpropertydependsontheobjectthatcontainstheFieldscollection,asshowninthefollowingtable.

IftheFieldscollectionbelongstoaThenOrdinalPositionisIndexobject NotsupportedQueryDefobject Read-onlyRecordsetobject Read-onlyRelationobject NotsupportedTableDefobject Read/write

Generally,theordinalpositionofanobjectthatyouappendtoacollectiondependsontheorderinwhichyouappendtheobject.Thefirstappendedobjectisinthefirstposition(0),thesecondappendedobjectisinthesecondposition(1),andsoon.Thelastappendedobjectisinordinalpositioncount–1,wherecountisthenumberofobjectsinthecollectionasspecifiedbytheCountpropertysetting.

YoucanusetheOrdinalPositionpropertytospecifyanordinalpositionfornewFieldobjectsthatdiffersfromtheorderinwhichyouappendthoseobjectstoacollection.Thisenablesyoutospecifyafieldorderforyourtables,queries,andrecordsetswhenyouusetheminanapplication.Forexample,theorderinwhichfieldsarereturnedinaSELECT*queryisdeterminedbythecurrentOrdinalPositionpropertyvalues.

YoucanpermanentlyresettheorderinwhichfieldsarereturnedinrecordsetsbysettingtheOrdinalPositionpropertytoanypositiveinteger.

TwoormoreFieldobjectsinthesamecollectioncanhavethesameOrdinalPositionpropertyvalue,inwhichcasetheywillbeorderedalphabetically.Forexample,ifyouhaveafieldnamedAgesetto4andyousetasecondfieldnamedWeightto4,WeightisreturnedafterAge.

Youcanspecifyanumberthatisgreaterthanthenumberoffieldsminus1.Thefieldwillbereturnedinanorderrelativetothelargestnumber.Forexample,ifyousetafield'sOrdinalPositionpropertyto20(andthereareonly5fields)andyou'vesettheOrdinalPositionpropertyfortwootherfieldsto10and30,respectively,thefieldsetto20isreturnedbetweenthefieldssetto10and30.

NoteEveniftheFieldscollectionofaTableDefhasnotbeenrefreshed,thefieldorderinaRecordsetopenedfromtheTableDefwillreflecttheOrdinalPositiondataoftheTableDefobject.Atable-typeRecordsetwillhavethesameOrdinalPositiondataastheunderlyingtable,butanyothertypeofRecordsetwillhavenewOrdinalPositiondata(startingwith0)thatfollowtheorderdeterminedbytheOrdinalPositiondataoftheTableDef.

OriginalValueProperty

ReturnsthevalueofaFieldinthedatabasethatexistedwhenthelastbatchupdatebegan(ODBCDirectworkspacesonly).

ReturnValues

Thereturnvalueisavariantexpression.

Remarks

Duringanoptimisticbatchupdate,acollisionmayoccurwhereasecondclientmodifiesthesamefieldandrecordinbetweenthetimethefirstclientretrievesthedataandthefirstclient'supdateattempt.TheOriginalValuepropertycontainsthevalueofthefieldatthetimethelastbatchUpdatebegan.IfthisvaluedoesnotmatchthevalueactuallyinthedatabasewhenthebatchUpdateattemptstowritetothedatabase,acollisionoccurs.Whenthishappens,thenewvalueinthedatabasewillbeaccessiblethroughtheVisibleValueproperty.

OwnerProperty

Setsorreturnsavaluethatspecifiestheowneroftheobject(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringthatevaluatestoeitherthenameofaUserobjectintheUserscollectionorthenameofaGroupobjectintheGroupscollection.

Remarks

Theownerofanobjecthascertainaccessprivilegesdeniedtootherusers.Anyindividualuseraccount(representedbyaUserobject)orgroupofuseraccounts(representedbyaGroupobject)canchangetheOwnerpropertysettingatanytimeifithastheappropriatepermissions.

PartialReplicaProperty

SetsorreturnsavalueonaRelationobjectindicatingwhetherthatrelationshouldbeconsideredwhenpopulatingapartialreplicafromafullreplica.(MicrosoftJetdatabasesonly.)


ThesettingorreturnvalueisaBooleandatatypethatisTruewhentherelationshouldbeenforcedduringsynchronization.

Remarks

Thispropertyenablesyoutoreplicatedatafromthefullreplicatothepartialreplicabasedonrelationshipsbetweentables.YoucanusethePartialReplicapropertywhensettingtheReplicaFilterpropertyalonecan'tadequatelyspecifywhatdatashouldbereplicatedtothepartial.Forexample,supposeyouhaveadatabaseinwhichtheCustomerstablehasaone-to-manyrelationshipwiththeOrderstable,andyouwanttoconfigureapartialreplicathatonlyreplicatesordersfromcustomersintheCaliforniaregion(insteadofallorders).ItisnotpossibletosettheReplicaFilterpropertyontheOrderstabletoRegion='CA'becausetheRegionfieldisintheCustomerstable,nottheOrderstable.

ToreplicateallordersfromtheCaliforniaregion,youmustindicatethattherelationbetweentheOrdersandCustomerstableswillbeactiveduringreplication.Onceyou'vecreatedapartialreplica,thefollowingstepswillpopulateitwithallordersfromtheCaliforniaregion:

1. SettheReplicaFilterpropertyontheCustomersTableDefobjectto"Region='CA'".

2. SetthevalueofthePartialReplicapropertytoTrueontheRelationobjectcorrespondingtotherelationshipbetweenOrdersandCustomers.

3. InvokethePopulatePartialmethod.

CautionWhenyousetareplicafilterorreplicarelation,beawarethatrecordsinthepartialreplicathatdon'tsatisfytherestrictioncriteriawillberemovedfromthepartialreplica,butnotfromthefullreplica.Forexample,supposeyousettheReplicaFilterpropertyontheCustomersTableDefinthepartialreplicato"Region='CA'"andyouthenrepopulatethedatabase.ThiswillinsertorupdateallrecordsforCalifornia-basedcustomers.IfyouthenresettheReplicaFilterpropertyto"Region='FL'"andrepopulatethedatabase,allCaliforniaregionrecordsinthepartialreplicawillberemoved,andallrecordsfromFlorida-basedcustomerswillbeinsertedfromthefullreplica.Norecordsinthefullreplicawillbedeleted.

BeforesettingeithertheReplicaFilterorPartialReplicaproperty,it'sagoodideatosynchronizethepartialreplicainwhichyouaresettingthesepropertieswiththefullreplica.Thiswillensurethatpendingchangesinthepartialreplicawillbemergedintothefullreplicabeforeanyrecordsareremovedinthepartialreplica.

PasswordProperty

Setsthepasswordforauseraccount(MicrosoftJetworkspacesonly).


Settings

ThesettingisaStringthatcanbeupto14characterslongandcanincludeanycharactersexcepttheASCIIcharacter0(null).Thispropertysettingiswrite-onlyfornewobjectsnotyetappendedtoacollection,andisnotavailableforexistingobjects.

Remarks

SetthePasswordpropertyalongwiththePIDpropertywhenyoucreateanewUserobject.

UsetheNewPasswordmethodtochangethePasswordpropertysettingforanexistingUserobject.Toclearapassword,setthenewpassword

argumentoftheNewPasswordmethodtoazero-lengthstring("").

Passwordsarecase-sensitive.

NoteIfyoudon'thaveaccesspermission,youcan'tchangethepasswordofanyotheruser.

PercentPositionProperty

SetsorreturnsavalueindicatingtheapproximatelocationofthecurrentrecordintheRecordsetobjectbasedonapercentageoftherecordsintheRecordset.


ThesettingorreturnvalueisaSinglethatisanumberbetween0.0and100.00.

Remarks

ToindicateorchangetheapproximatepositionofthecurrentrecordinaRecordsetobject,youcancheckorsetthePercentPositionproperty.Whenworkingwithadynaset-orsnapshot-typeRecordsetobjectopeneddirectlyfromabasetable,firstpopulatetheRecordsetobjectbymovingtothelastrecordbeforeyousetorcheckthePercentPositionproperty.IfyouusethePercentPositionpropertybeforefullypopulatingtheRecordsetobject,theamountofmovementisrelativetothenumberofrecordsaccessedasindicatedbytheRecordCountpropertysetting.YoucanmovetothelastrecordbyusingtheMoveLastmethod.

NoteUsingthePercentPositionpropertytomovethecurrentrecordtoaspecificrecordinaRecordsetobjectisn'trecommended?theBookmarkpropertyisbettersuitedforthistask.

OnceyousetthePercentPositionpropertytoavalue,therecordattheapproximatepositioncorrespondingtothatvaluebecomescurrent,andthePercentPositionpropertyisresettoavaluethatreflectstheapproximatepositionofthecurrentrecord.Forexample,ifyourRecordsetobjectcontainsonlyfiverecords,andyousetitsPercentPositionpropertyvalueto77,thevaluereturnedfromthePercentPositionpropertymaybe80,not77.

ThePercentPositionpropertyappliestoalltypesofRecordsetobjectsexceptforforward-only–typeRecordsetobjectsorRecordsetobjectsopenedfrompass-throughqueriesagainstremotedatabases.

YoucanusethePercentPositionpropertywithascrollbaronaformortextboxtoindicatethelocationofthecurrentrecordinaRecordsetobject.

PermissionsProperty

SetsorreturnsavaluethatestablishesthepermissionsfortheuserorgroupidentifiedbytheUserNamepropertyofaContainerorDocumentobject(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaLongconstantthatestablishespermissions.ThefollowingtableslistthevalidconstantsforthePermissionspropertyofvariousDAOobjects.Unlessotherwisenoted,allconstantsshowninalltablesarevalidforDocumentobjects.

ThefollowingtablelistspossiblevaluesforContainerobjectsotherthanTablesandDatabasescontainers.


dbSecNoAccess Theuserdoesn'thaveaccesstotheobject(notvalidforDocumentobjects).

dbSecFullAccess Theuserhasfullaccesstotheobject.dbSecDelete Theusercandeletetheobject.

dbSecReadSec Theusercanreadtheobject'ssecurity-relatedinformation.

dbSecWriteSec Theusercanalteraccesspermissions.

dbSecWriteOwner TheusercanchangetheOwnerpropertysetting.

ThefollowingtablesliststhepossiblesettingsandreturnvaluesfortheTablescontainer.


dbSecCreate Theusercancreatenewdocuments(notvalidforDocumentobjects).

dbSecReadDef Theusercanreadthetabledefinition,includingcolumnandindexinformation.

dbSecWriteDefTheusercanmodifyordeletethetabledefinition,includingcolumnandindexinformation.

dbSecRetrieveData TheusercanretrievedatafromtheDocumentobject.

dbSecInsertData Theusercanaddrecords.dbSecReplaceData Theusercanmodifyrecords.dbSecDeleteData Theusercandeleterecords.

ThefollowingtablesliststhepossiblesettingsandreturnvaluesfortheDatabasescontainer.


dbSecDBAdminTheusercanreplicateadatabaseandchangethedatabasepassword(notvalidforDocumentobjects).

dbSecDBCreate

Theusercancreatenewdatabases.ThisoptionisvalidonlyontheDatabasescontainerintheworkgroupinformationfile(Systen.mdw).Thisconstantisn'tvalidforDocumentobjects.

dbSecDBExclusive Theuserhasexclusiveaccesstothedatabase.

dbSecDBOpen Theusercanopenthedatabase.

Remarks

Usethispropertytoestablishordeterminethetypeofread/writepermissionstheuserhasforaContainerorDocumentobject.

ADocumentobjectinheritsthepermissionsforusersfromitsContainerobject,providedtheInheritpropertyoftheContainerobjectissetforthoseusersorforagrouptowhichtheusersbelong.BysettingaDocumentobject'sPermissionsandUserNamepropertieslater,youcanfurtherrefinetheaccesscontrolbehaviorofyourobject.

Ifyouwanttosetorreturnpermissionsforauserthatincludespermissionsinheritedfromanygroupstowhichtheuserbelongs,usetheAllPermissionsproperty.

PIDProperty

Setsthepersonalidentifier(PID)foreitheragrouporauseraccount(MicrosoftJetworkspacesonly).

Settings

ThesettingisaStringcontaining4-20alphanumericcharacters.Thispropertysettingiswrite-onlyfornewobjectsnotyetappendedtoacollection,andisnotavailableforexistingobjects.

Remarks

SetthePIDpropertyalongwiththeNamepropertywhenyoucreateanewGroupobject.SetthePIDpropertyalongwiththeNameandPasswordpropertieswhenyoucreateanewUserobject.

PrepareProperty

Setsorreturnsavaluethatindicateswhetherthequeryshouldbepreparedontheserverasatemporarystoredprocedure,usingtheODBCSQLPrepareAPIfunction,priortoexecution,orjustexecutedusingtheODBCSQLExecDirectAPIfunction(ODBCDirectworkspacesonly).


ThesettingorreturnvalueisaLongvaluethatcanbeoneofthefollowingconstants:


dbQPrepare (Default)Thestatementisprepared(thatis,theODBCSQLPrepareAPIiscalled).

dbQUnprepare Thestatementisnotprepared(thatis,theODBCSQLExecDirectAPIiscalled).

Remarks

YoucanusethePreparepropertytoeitherhavetheservercreateatemporarystoredprocedurefromyourqueryandthenexecuteit,orjust

havethequeryexecuteddirectly.BydefaultthePreparepropertyissettodbQPrepare.However,youcansetthispropertytodbQUnpreparetoprohibitpreparingofthequery.Inthiscase,thequeryisexecutedusingtheSQLExecDirectAPI.

Creatingastoredprocedurecanslowdowntheinitialoperation,butincreasesperformanceofallsubsequentreferencestothequery.However,somequeriescannotbeexecutedintheformofstoredprocedures.Inthesecases,youmustsetthePreparepropertytodbQUnprepare.

IfPrepareissettodbQPrepare,thiscanbeoverriddenwhenthequeryisexecutedbysettingtheExecutemethod'soptionsargumenttodbExecDirect.

NoteTheODBCSQLPrepareAPIiscalledassoonastheDAOSQLpropertyisset.Therefore,ifyouwanttoimproveperformanceusingthedbQUnprepareoption,youmustsetthePreparepropertybeforesettingtheSQLproperty.

PrimaryProperty

SetsorreturnsavaluethatindicateswhetheranIndexobjectrepresentsaprimarykeyindexforatable(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleanthatisTrueiftheIndexobjectrepresentsaprimarykeyindex.

ThePrimarypropertysettingisread/writeforanewIndexobjectnotyetappendedtoacollectionandread-onlyforanexistingIndexobjectinanIndexescollection.IftheIndexobjectisappendedtotheTableDefobjectbuttheTableDefobjectisn'tappendedtotheTableDefscollection,theIndexpropertyisread/write.

Remarks

Aprimarykeyindexconsistsofoneormorefieldsthatuniquelyidentifyallrecordsinatableinapredefinedorder.Becausetheindexfieldmustbeunique,theUniquepropertyoftheIndexobjectissettoTrue.Iftheprimarykeyindexconsistsofmorethanonefield,eachfieldcancontainduplicatevalues,buteachcombinationofvaluesfromalltheindexed

fieldsmustbeunique.Aprimarykeyindexconsistsofakeyforthetableandusuallycontainsthesamefieldsastheprimarykey.

NoteYoudon'thavetocreateindexesfortables,butinlarge,unindexedtables,accessingaspecificrecordcantakealongtime.TheAttributespropertyofeachFieldobjectintheIndexobjectdeterminestheorderofrecordsandconsequentlydeterminestheaccesstechniquestouseforthatindex.Whenyoucreateanewtableinyourdatabase,it'sagoodideatocreateanindexononeormorefieldsthatuniquelyidentifyeachrecord,andthensetthePrimarypropertyoftheIndexobjecttoTrue.

Whenyousetaprimarykeyforatable,theprimarykeyisautomaticallydefinedastheprimarykeyindexforthetable.

QueryTimeoutProperty

SetsorreturnsavaluethatspecifiesthenumberofsecondstowaitbeforeatimeouterroroccurswhenaqueryisexecutedonanODBCdatasource.


ThesettingorreturnvalueisanIntegerrepresentingthenumberofsecondstowait.Thedefaultvalueis60.

Remarks

Whenyou'reusinganODBCdatabase,suchasMicrosoftSQLServer,theremaybedelaysduetonetworktrafficorheavyuseoftheODBCserver.Ratherthanwaitingindefinitely,youcanspecifyhowlongtowait.

WhenyouuseQueryTimeoutwithaConnectionorDatabaseobject,itspecifiesaglobalvalueforallqueriesassociatedwiththedatabase.YoucanoverridethisvalueforaspecificquerybysettingtheODBCTimeoutpropertyoftheparticularQueryDefobject.

InaMicrosoftJetworkspace,youcanoverridethedefaultvalueby

creatinganew“ODBC”keyintheRegistrypath\HKEY_LOCAL_MACHINE\SOFTWARE\Jet\3.5\,creatingaQueryTimeoutparameterinthiskey,andsettingthevalueasdesired.

RecordCountProperty

ReturnsthenumberofrecordsaccessedinaRecordsetobject,orthetotalnumberofrecordsinatable-typeRecordsetorTableDefobject.

ReturnValues

ThereturnvalueisaLongdatatype.

Remarks

UsetheRecordCountpropertytofindouthowmanyrecordsinaRecordsetorTableDefobjecthavebeenaccessed.TheRecordCountpropertydoesn'tindicatehowmanyrecordsarecontainedinadynaset-,snapshot-,orforward-only–typeRecordsetobjectuntilallrecordshavebeenaccessed.Oncethelastrecordhasbeenaccessed,theRecordCountpropertyindicatesthetotalnumberofundeletedrecordsintheRecordsetorTableDefobject.Toforcethelastrecordtobeaccessed,usetheMoveLastmethodontheRecordsetobject.YoucanalsouseanSQLCountfunctiontodeterminetheapproximatenumberofrecordsyourquerywillreturn.

NoteUsingtheMoveLastmethodtopopulateanewlyopened

Recordsetnegativelyimpactsperformance.UnlessitisnecessarytohaveanaccurateRecordCountassoonasyouopenaRecordset,it'sbettertowaituntilyoupopulatetheRecordsetwithotherportionsofcodebeforecheckingtheRecordCountproperty.

Asyourapplicationdeletesrecordsinadynaset-typeRecordsetobject,thevalueoftheRecordCountpropertydecreases.However,recordsdeletedbyotherusersaren'treflectedbytheRecordCountpropertyuntilthecurrentrecordispositionedtoadeletedrecord.IfyouexecuteatransactionthataffectstheRecordCountpropertysettingandyousubsequentlyrollbackthetransaction,theRecordCountpropertywon'treflecttheactualnumberofremainingrecords.

TheRecordCountpropertyofasnapshot-orforward-only–typeRecordsetobjectisn'taffectedbychangesintheunderlyingtables.

ARecordsetorTableDefobjectwithnorecordshasaRecordCountpropertysettingof0.

WhenyouworkwithlinkedTableDefobjects,theRecordCountpropertysettingisalways–1.

UsingtheRequerymethodonaRecordsetobjectresetstheRecordCountpropertyjustasifthequerywerere-executed.

RecordsAffectedProperty

ReturnsthenumberofrecordsaffectedbythemostrecentlyinvokedExecutemethod.

ReturnValues

ThereturnvalueisaLongfrom0tothenumberofrecordsaffectedbythemostrecentlyinvokedExecutemethodoneitheraDatabaseorQueryDefobject.

Remarks

WhenyouusetheExecutemethodtorunanactionqueryfromaQueryDefobject,theRecordsAffectedpropertywillcontainthenumberofrecordsdeleted,updated,orinserted.

WhenyouuseRecordsAffectedinanODBCDirectworkspace,itwillnotreturnausefulvaluefromanSQLDROPTABLEactionquery.

RecordStatusProperty

Returnsavalueindicatingtheupdatestatusofthecurrentrecordifitispartofabatchupdate(ODBCDirectworkspacesonly).

ReturnValues

ThereturnvalueisaLongthatcanbeanyofthefollowingconstants:


dbRecordUnmodified (Default)Therecordhasnotbeenmodifiedorhasbeenupdatedsuccessfully.

dbRecordModified Therecordhasbeenmodifiedandnotupdatedinthedatabase.

dbRecordNewTherecordhasbeeninsertedwiththeAddNewmethod,butnotyetinsertedintothedatabase.

dbRecordDeleted Therecordhasbeendeleted,butnotyetdeletedinthedatabase.

dbRecordDBDeleted Therecordhasbeendeletedlocallyandinthedatabase.

Remarks

ThevalueoftheRecordStatuspropertyindicateswhetherandhowthecurrentrecordwillbeinvolvedinthenextoptimisticbatchupdate.

Whenauserchangesarecord,theRecordStatusforthatrecordautomaticallychangestodbRecordModified.Similarly,ifarecordisaddedordeleted,RecordStatusreflectstheappropriateconstant.Whenyouthenuseabatch-modeUpdatemethod,DAOwillsubmitanappropriateoperationtotheremoteserverforeachrecord,basedontherecord'sRecordStatusproperty.

ReplicableProperty

Setsorreturnsavaluethatdetermineswhetheradatabaseorobjectinadatabasecanbereplicated(MicrosoftJetworkspacesonly).

NoteBeforegettingorsettingtheReplicablepropertyonaDatabase,TableDef,orQueryDefobject,youmustcreateitbyusingtheCreatePropertymethodandappendittothePropertiescollectionfortheobject.

SettingandReturnValues

ThesettingorreturnvalueisaTextdatatype.

OnaDatabaseobject,settingthispropertyto"T"makesthedatabasereplicable.Onceyousetthepropertyto"T",youcan'tchangeit;settingthepropertyto"F"(oranyvalueotherthan"T")causesanerror.

Onanobjectinadatabase,settingthispropertyto"T"replicatestheobject(andsubsequentchangestotheobject)atallreplicasinthereplicaset.Youcanalsosetthispropertyintheobject'spropertysheetinMicrosoftAccess.

NoteMicrosoftJet3.5alsosupportstheBooleanReplicableBoolproperty.ItsfunctionalityisidenticaltotheReplicableproperty,exceptthatittakesaBooleanvalue.SettingReplicableBooltoTruemakestheobjectreplicable.

Remarks

BeforesettingtheReplicablepropertyonadatabase,makeabackupcopyofthedatabase.IfsettingtheReplicablepropertyfails,youshoulddeletethepartiallyreplicateddatabase,makeanewcopyfromthebackup,andtryagain.

WhenyousetthispropertyonaDatabaseobject,MicrosoftJetaddsfields,tables,andpropertiestoobjectswithinthedatabase.MicrosoftJetusesthesefields,tables,andpropertiestosynchronizedatabaseobjects.Forexample,allexistingtableshavethreenewfieldsaddedtothemthathelpidentifywhichrecordshavechanged.Theadditionofthesefieldsandotherobjectsincreasethesizeofyourdatabase.

Onforms,reports,macros,andmodulesdefinedbyahostapplication(suchasMicrosoftAccess),yousetthispropertyonthehost-definedobjectthroughthehostuserinterface.Onceset,theReplicablepropertywillappearinthePropertiescollectionfortheDocumentobjectrepresentingthehostobject.

IftheReplicablepropertyhasalreadybeensetonanobjectusingtheReplicatedcheckboxinthepropertysheetfortheobject,youcannotsettheReplicablepropertyincode.

Whenyoucreateanewtable,query,form,report,macro,ormoduleatareplica,theobjectisconsideredlocalandisstoredonlyatthatreplica.Ifyouwantusersatotherreplicastobeabletousetheobject,youmustchangeitfromlocaltoreplicable.EithercreatetheobjectatorimportitintotheDesignMasterandthensettheReplicablepropertyto"T".

TheobjectonwhichyouaresettingtheReplicablepropertymighthavealreadyinheritedthatpropertyfromanotherobject.However,thevaluesetbytheotherobjecthasnoeffectonthebehavioroftheobjectyou

wanttomakereplicable.Youmustexplicitlysetthepropertyforeachobject.

ReplicaFilterProperty

SetsorreturnsavalueonaTableDefobjectwithinapartialreplicathatindicateswhichsubsetofrecordsisreplicatedtothattablefromafullreplica.(MicrosoftJetdatabasesonly.)


ThesettingorreturnvalueisaStringorBooleanthatindicateswhichsubsetofrecordsisreplicated,asspecifiedinthefollowingtable:

Value Description

Astring Acriteriathatarecordinthepartialreplicatablemustsatisfyinordertobereplicatedfromthefullreplica.

True Replicatesallrecords.False (Default)Doesn'treplicateanyrecords.

Remarks

ThispropertyissimilartoanSQLWHEREclause(withoutthewordWHERE),butyoucannotspecifysubqueries,aggregatefunctions(suchasCount),oruser-definedfunctionswithinthecriteria.

Youcanonlysynchronizedatabetweenafullreplicaandapartialreplica.Youcan'tsynchronizedatabetweentwopartialreplicas.Also,withpartialreplicationyoucansetrestrictionsonwhichrecordsarereplicated,butyoucan'tindicatewhichfieldsarereplicated.

Usually,youresetareplicafilterwhenyouwanttoreplicateadifferentsetofrecords.Forexample,whenasalesrepresentativetemporarilytakesoveranothersalesrepresentative'sregion,thedatabaseapplicationcantemporarilyreplicatedataforbothregionsandthenreturntothepreviousfilter.Inthisscenario,theapplicationresetstheReplicaFilterpropertyandthenrepopulatesthepartialreplica.

Ifyourapplicationchangesreplicafilters,youshouldfollowthesesteps:

1. UsetheSynchronizemethodtosynchronizeyourfullreplicawiththepartialreplicainwhichthefiltersarebeingchanged.

2. UsetheReplicaFilterpropertytomakethedesiredchangestothereplicafilter.

3. UsethePopulatePartialmethodtoremoveallrecordsfromthepartialreplicaandtransferallrecordsfromthefullreplicathatmeetthenewreplicafiltercriteria.

Toremoveafilter,settheReplicaFilterpropertytoFalse.IfyouremoveallfiltersandinvokethePopulatePartialmethod,norecordswillappearinanyreplicatedtablesinthepartialreplica.

NoteIfareplicafilterhaschanged,andtheSynchronizemethodisinvokedwithoutfirstinvokingPopulatePartial,atrappableerroroccurs.

ReplicaIDProperty

Returnsa16-bytevaluethatuniquelyidentifiesadatabasereplica(MicrosoftJetworkspacesonly).

ReturnValues

ThereturnvalueisaGUIDvaluethatuniquelyidentifiesthereplicaorDesignMaster.

Remarks

TheMicrosoftJetdatabaseengineautomaticallygeneratesthisvaluewhenyoucreateanewreplica.

TheReplicaIDpropertyofeachreplica(andtheDesignMaster)isstoredintheMSysReplicassystemtable.

RequiredProperty

SetsorreturnsavaluethatindicateswhetheraFieldobjectrequiresanon-NullvalueorwhetherallthefieldsinanIndexobjectmusthaveavalue.


ThesettingorreturnvalueisaBooleanthatisTrueifafieldcan'tcontainaNullvalue.

Foranobjectnotyetappendedtoacollection,thispropertyisread/write.ForanIndexobject,thispropertysettingisread-onlyforobjectsappendedtoIndexescollectionsinRecordsetandTableDefobjects.

Remarks

TheavailabilityoftheRequiredpropertydependsontheobjectthatcontainstheFieldscollection,asshowninthefollowingtable.

IftheFieldscollectionbelongstoa ThenRequiredis

Indexobject Notsupported

QueryDefobject Read-onlyRecordsetobject Read-onlyRelationobject NotsupportedTableDefobject Read/write

ForaFieldobject,youcanusetheRequiredpropertyalongwiththeAllowZeroLength,ValidateOnSet,orValidationRulepropertytodeterminethevalidityoftheValuepropertysettingforthatFieldobject.IftheRequiredpropertyissettoFalse,thefieldcancontainNullvaluesaswellasvaluesthatmeettheconditionsspecifiedbytheAllowZeroLengthandValidationRulepropertysettings.

NoteWhenyoucansetthispropertyforeitheranIndexobjectoraFieldobject,setitfortheFieldobject.ThevalidityofthepropertysettingforaFieldobjectischeckedbeforethatofanIndexobject.

RestartableProperty

ReturnsavaluethatindicateswhetheraRecordsetobjectsupportstheRequerymethod,whichre-executesthequeryonwhichtheRecordsetobjectisbased.

ReturnValues

ThereturnvalueisaBooleandatatypethatisTrueiftheRecordsetobjectsupportstheRequerymethod.Table-typeRecordsetobjectsalwaysreturnFalse.

Remarks

ChecktheRestartablepropertybeforeusingtheRequerymethodonaRecordsetobject.Iftheobject'sRestartablepropertyissettoFalse,usetheOpenRecordsetmethodontheunderlyingQueryDefobjecttore-executethequery.

ReturnsRecordsProperty

SetsorreturnsavaluethatindicateswhetheranSQLpass-throughquerytoanexternaldatabasereturnsrecords(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleanthatisTrue(default)ifapass-throughqueryreturnsrecords.

Remarks

NotallSQLpass-throughqueriestoexternaldatabasesreturnrecords.Forexample,anSQLUPDATEstatementupdatesrecordswithoutreturningrecords,whileanSQLSELECTstatementdoesreturnrecords.Ifthequeryreturnsrecords,settheReturnsRecordspropertytoTrue;ifthequerydoesn'treturnrecords,settheReturnsRecordspropertytoFalse.

NoteYoumustsettheConnectpropertybeforeyousettheReturnsRecordsproperty.

SizeProperty

Setsorreturnsavaluethatindicatesthemaximumsize,inbytes,ofaFieldobject.


ThesettingorreturnvalueisaconstantthatindicatesthemaximumsizeofaFieldobject.ForanobjectnotyetappendedtotheFieldscollection,thispropertyisread/write.ThesettingdependsontheTypepropertysettingoftheFieldobject,asdiscussedunderRemarks.

Remarks

Forfields(otherthanMemotypefields)thatcontaincharacterdata,theSizepropertyindicatesthemaximumnumberofcharactersthatthefieldcanhold.Fornumericfields,theSizepropertyindicateshowmanybytesofstoragearerequired.

UseoftheSizepropertydependsontheobjectthatcontainstheFieldscollectiontowhichtheFieldobjectisappended,asshowninthefollowingtable.

ObjectappendedtoUsageIndex NotsupportedQueryDef Read-onlyRecordset Read-onlyRelation NotsupportedTableDef Read-only

WhenyoucreateaFieldobjectwithadatatypeotherthanText,theTypepropertysettingautomaticallydeterminestheSizepropertysetting;youdon'tneedtosetit.ForaFieldobjectwiththeTextdatatype,however,youcansetSizetoanyintegeruptothemaximumtextsize(255forMicrosoftJetdatabases).Ifyoudonotsetthesize,thefieldwillbeaslargeasthedatabaseallows.

ForLongBinaryandMemoFieldobjects,Sizeisalwayssetto0.UsetheFieldSizepropertyoftheFieldobjecttodeterminethesizeofthedatainaspecificrecord.ThemaximumsizeofaLongBinaryorMemofieldislimitedonlybyyoursystemresourcesorthemaximumsizethatthedatabaseallows.

SortProperty

SetsorreturnsthesortorderforrecordsinaRecordsetobject(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringthatcontainstheORDERBYclauseofanSQLstatementwithoutthereservedwordsORDERBY.

Remarks

YoucanusetheSortpropertywithdynaset-andsnapshot-typeRecordsetobjects.

Whenyousetthispropertyforanobject,sortingoccurswhenasubsequentRecordsetobjectiscreatedfromthatobject.TheSortpropertysettingoverridesanysortorderspecifiedforaQueryDefobject.

Thedefaultsortorderisascending(AtoZor0to100).

TheSortpropertydoesn'tapplytotable-orforward-only–typeRecordsetobjects.Tosortatable-typeRecordsetobject,usetheIndex

property.

NoteInmanycases,it'sfastertoopenanewRecordsetobjectbyusinganSQLstatementthatincludesthesortingcriteria.

SourceProperty

Returnsthenameoftheobjectorapplicationthatoriginallygeneratedtheerror.

ReturnValues

ThereturnvalueisaStringrepresentingtheobjectorapplicationthatgeneratedtheerror.

Remarks

TheSourcepropertyvalueisusuallytheobject'sclassnameorprogrammaticID.UsetheSourcepropertytoprovideyouruserswithinformationwhenyourcodeisunabletohandleanerrorgeneratedinanobjectinanotherapplication.

Forexample,ifyouaccessMicrosoftExcelanditgeneratesa"Divisionbyzero"error,MicrosoftExcelsetsError.NumbertotheMicrosoftExcelcodeforthaterrorandsetstheSourcepropertytoExcel.Application.NotethatiftheerrorisgeneratedinanotherobjectcalledbyMicrosoftExcel,MicrosoftExcelinterceptstheerrorandstillsetsError.NumbertotheMicrosoftExcelcode.However,theother

Errorobjectproperties(includingSource)willretainthevaluesassetbytheobjectthatgeneratedtheerror.TheSourcepropertyalwayscontainsthenameoftheobjectthatoriginallygeneratedtheerror.

Basedonalloftheerrordocumentation,youcanwritecodethatwillhandletheerrorappropriately.Ifyourerrorhandlerfails,youcanusetheErrorobjectinformationtodescribetheerrortoyouruser,usingtheSourcepropertyandtheotherErrorpropertiestogivetheuserinformationaboutwhichobjectoriginallycausedtheerror,thedescriptionoftheerror,andsoforth.

NoteTheOnErrorResumeNextconstructmaybepreferabletoOnErrorGoTowhendealingwitherrorsgeneratedduringaccesstootherobjects.CheckingtheErrorobjectpropertyaftereachinteractionwithanobjectremovesambiguityaboutwhichobjectyourcodewasaccessingwhentheerroroccurred.Thus,youcanbesurewhichobjectplacedtheerrorcodeinError.Number,aswellaswhichobjectoriginallygeneratedtheerror(Error.Source).

SourceField,SourceTableProperties

SourceField—returnsavaluethatindicatesthenameofthefieldthatistheoriginalsourceofthedataforaFieldobject.

SourceTable—returnsavaluethatindicatesthenameofthetablethatistheoriginalsourceofthedataforaFieldobject.

ReturnValues

ThereturnvalueisaStringspecifyingthenameofthefieldortablethatisthesourceofdata.

Remarks

ForaFieldobject,useoftheSourceFieldandSourceTablepropertiesdependsontheobjectthatcontainstheFieldscollectionthattheFieldobjectisappendedto,asshowninthefollowingtable.

ObjectappendedtoUsageIndex NotsupportedQueryDef Read-only

Recordset Read-onlyRelation NotsupportedTableDef Read-only

ThesepropertiesindicatetheoriginalfieldandtablenamesassociatedwithaFieldobject.Forexample,youcouldusethesepropertiestodeterminetheoriginalsourceofthedatainaqueryfieldwhosenameisunrelatedtothenameofthefieldintheunderlyingtable.

NoteTheSourceTablepropertywillnotreturnameaningfultablenameifusedonaFieldobjectintheFieldscollectionofatable-typeRecordsetobject.

SourceTableNameProperty

Setsorreturnsavaluethatspecifiesthenameofalinkedtableorthenameofabasetable(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringthatspecifiesatablename.Forabasetable,thesettingisazero-lengthstring("").Thispropertysettingisread-onlyforabasetableandread/writeforalinkedtableoranobjectnotappendedtoacollection.

SQLProperty

SetsorreturnstheSQLstatementthatdefinesthequeryexecutedbyaQueryDefobject.


ThesettingorreturnvalueisaStringthatcontainsanSQLstatement.

Remarks

TheSQLpropertycontainstheSQLstatementthatdetermineshowrecordsareselected,grouped,andorderedwhenyouexecutethequery.YoucanusethequerytoselectrecordstoincludeinaRecordsetobject.Youcanalsodefineactionqueriestomodifydatawithoutreturningrecords.

TheSQLsyntaxusedinaquerymustconformtotheSQLdialectofthequeryengine,whichisdeterminedbythetypeofworkspace.InaMicrosoftJetworkspace,usetheMicrosoftJetSQLdialect,unlessyoucreateanSQLpass-throughquery,inwhichcaseyoushouldusethedialectoftheserver.InanODBCDirectworkspace,usetheSQLdialectoftheserver.


IftheSQLstatementincludesparametersforthequery,youmustsetthesebeforeexecution.Untilyouresettheparameters,thesameparametervaluesareappliedeachtimeyouexecutethequery.

InanODBCDirectworkspace,youcanalsousetheSQLpropertytoexecuteapreparedstatementontheserver.Forexample,settingtheSQLpropertytothefollowingstringwillexecuteapreparedstatementnamed“GetData”withoneparameteronaMicrosoftSQLServerback-end.

"{callGetData(?)}"

InaMicrosoftJetworkspace,usingaQueryDefobjectisthepreferredwaytoperformSQLpass-throughoperationsonMicrosoftJet-connectedODBCdatasources.BysettingtheQueryDefobject'sConnectpropertytoanODBCdatasource,youcanusenon–Microsoft-Jet-databaseSQLinthequerytobepassedtotheexternalserver.Forexample,youcanuseTRANSACTSQLstatements(withMicrosoftSQLServerorSybaseSQLServerdatabases),whichtheMicrosoftJetdatabaseenginewouldotherwisenotprocess.

NoteIfyousetthepropertytoastringconcatenatedwithanon-integervalue,andthesystemparametersspecifyanon-U.S.decimalcharactersuchasacomma(forexample,strSQL="PRICE>"&lngPrice,andlngPrice=125,50),anerrorwillresultwhenyoutrytoexecutetheQueryDefobjectinaMicrosoftJetdatabase.Thisisbecauseduringconcatenation,thenumberwillbeconvertedtoastringusingyoursystem'sdefaultdecimalcharacter,andMicrosoft

JetSQLonlyacceptsU.S.decimalcharacters.

StillExecutingProperty

Indicateswhetherornotanasynchronousoperation(thatis,amethodcalledwiththedbRunAsyncoption)hasfinishedexecuting(ODBCDirectworkspacesonly).


ThereturnvalueisaBooleanthatisTrueifthequeryisstillexecuting,andFalseifthequeryhascompleted.

Remarks

UsetheStillExecutingpropertytodetermineifthemostrecentlycalledasynchronousExecute,MoveLast,OpenConnection,orOpenRecordsetmethod(thatis,amethodexecutedwiththedbRunAsyncoption)iscomplete.WhiletheStillExecutingpropertyisTrue,anyreturnedobjectcannotbeaccessed.

ThefollowingtableshowswhatmethodisevaluatedwhenyouuseStillExecutingonaparticulartypeofobject.

IfStillExecutingisusedon Thisasynchronousmethodisevaluated

Connection ExecuteorOpenConnectionQueryDef ExecuteRecordset MoveLastorOpenRecordset

OncetheStillExecutingpropertyonaConnectionorRecordsetobjectreturnsFalse,follwingtheOpenConnectionorOpenRecordsetcallthatreturnstheassociatedRecordsetorConnectionobject,theobjectcanbereferenced.SolongasStillExecutingremainsTrue,theobjectmaynotbereferenced,otherthantoreadtheStillExecutingproperty.WhenyouusetheNextRecordsetmethodtocompleteprocessingofaRecordset,theStillExecutingpropertyisresettoTruewhilesubsequentresultsetsareretrieved.

UsetheCancelmethodtoterminateexecutionofataskinprogress.

SystemDBProperty

Setsorreturnsthepathforthecurrentlocationoftheworkgroupinformationfile(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringdescribingthefullyresolvedpathtotheworkgroupinformationfile.

Remarks

TheMicrosoftJetdatabaseengineallowsyoutodefineaworkgroupandsetdifferentaccesspermissionstoeachobjectinthedatabaseforeachuserintheworkgroup.Theworkgroupisdefinedbytheworkgroupinformationfile,typicallycalled"system.mdw".Foruserstogainaccesstothesecuredobjectsinyourdatabase,DAOmusthavethelocationofthisworkgroupinformationfile.ThelocationcanbeidentifiedtoDAOeitherbyspecifyingitintheWindowsRegistryorbysettingtheSystemDBproperty.Onsetup,thedefaultsettingissimply"system.mdw"withnopath.

Forthisoptiontohaveanyeffect,youmustsettheSystemDBproperty

beforeyourapplicationinitializestheDBEngineobject(thatis,beforecreatinganinstanceofanyotherDAOobject).Thescopeofthissettingislimitedtoyourapplicationandcan'tbechangedwithoutrestartingyourapplication.

TableProperty

IndicatesthenameofaRelationobject'sprimarytable.ThisshouldbeequaltotheNamepropertysettingofaTableDeforQueryDefobject(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringthatevaluatestothenameofatableintheTableDefscollectionorqueryintheQueryDefscollection.TheTablepropertysettingisread/writeforanewRelationobjectnotyetappendedtoacollectionandread-onlyforanexistingRelationobjectinaRelationscollection.

Remarks

UsetheTablepropertywiththeForeignTablepropertytodefineaRelationobject,whichrepresentstherelationshipbetweenfieldsintwotablesorqueries.SettheTablepropertytotheNamepropertysettingoftheprimaryTableDeforQueryDefobject,andsettheForeignTablepropertytotheNamepropertysettingoftheforeign(referencing)TableDeforQueryDefobject.TheAttributespropertydeterminesthetypeofrelationshipbetweenthetwoobjects.

Forexample,ifyouhadalistofvalidpartcodes(inafieldnamedPartNo)storedinaValidPartstable,youcouldestablishaone-to-manyrelationshipwithanOrderItemtablesuchthatifapartcodewereenteredintotheOrderItemtable,itwouldhavetoalreadybeintheValidPartstable.Ifthepartcodedidn'texistintheValidPartstableandyouhadnotsettheAttributespropertyoftheRelationobjecttodbRelationDontEnforce,atrappableerrorwouldoccur.

Inthiscase,theValidPartstableistheprimarytable,sotheTablepropertyoftheRelationobjectwouldbesettoValidPartsandtheForeignTablepropertyoftheRelationobjectwouldbesettoOrderItem.TheNameandForeignNamepropertiesoftheFieldobjectintheRelationobject'sFieldscollectionwouldbesettoPartNo.

Thefollowingillustrationdepictsthisrelation.

TransactionsProperty

Returnsavaluethatindicateswhetheranobjectsupportstransactions.

ReturnValues

ThereturnvalueisaBooleandatatypethatisTrueiftheobjectsupportstransactions.

Remarks

InanODBCDirectworkspace,theTransactionspropertyisavailableonConnectionandDatabaseobjects,andindicateswhetherornottheODBCdriveryouareusingsupportstransactions.

InaMicrosoftJetworkspace,youcanalsousetheTransactionspropertywithdynaset-ortable-typeRecordsetobjects.Snapshot-andforward-only–typeRecordsetobjectsalwaysreturnFalse.

Ifadynaset-ortable-typeRecordsetisbasedonaMicrosoftJetdatabaseenginetable,theTransactionspropertyisTrueandyoucanusetransactions.Otherdatabaseenginesmaynotsupporttransactions.Forexample,youcan'tusetransactionsinadynaset-typeRecordset

objectbasedonaParadoxtable.

ChecktheTransactionspropertybeforeusingtheBeginTransmethodontheRecordsetobject'sWorkspaceobjecttomakesurethattransactionsaresupported.UsingtheBeginTrans,CommitTrans,orRollbackmethodsonanunsupportedobjecthasnoeffect.

TypeProperty

Setsorreturnsavaluethatindicatestheoperationaltypeordatatypeofanobject.


Thesettingorreturnvalueisaconstantthatindicatesanoperationalordatatype.ForaFieldorPropertyobject,thispropertyisread/writeuntiltheobjectisappendedtoacollectionortoanotherobject,afterwhichit'sread-only.ForaQueryDef,Recordset,orWorkspaceobject,thepropertysettingisread-only.ForaParameterobjectinaMicrosoftJetworkspacethepropertyisread-only,whileinanODBCDirectworkspacethepropertyisalwaysread-write.

ForaField,Parameter,orPropertyobject,thepossiblesettingsandreturnvaluesaredescribedinthefollowingtable.

Constant DescriptiondbBigInt BigIntegerdbBinary BinarydbBoolean BooleandbByte Byte

dbChar ChardbCurrency CurrencydbDate Date/TimedbDecimal DecimaldbDouble DoubledbFloat FloatdbGUID GUIDdbInteger IntegerdbLong LongdbLongBinary LongBinary(OLEObject)dbMemo MemodbNumeric NumericdbSingle SingledbText TextdbTime TimedbTimeStamp TimeStampdbVarBinary VarBinary

ForaQueryDefobject,thepossiblesettingsandreturnvaluesareshowninthefollowingtable.

Constant QuerytypedbQAction ActiondbQAppend AppenddbQCompound [email protected] CrosstabdbQDDL Data-definitiondbQDelete DeletedbQMakeTable Make-tabledbQProcedure Procedure(ODBCDirectworkspacesonly)dbQSelect SelectdbQSetOperation Union

dbQSPTBulk UsedwithdbQSQLPassThroughtospecifyaquerythatdoesn'treturnrecords(MicrosoftJetworkspacesonly).

dbQSQLPassThrough Pass-through(MicrosoftJetworkspacesonly)dbQUpdate Update

NoteTocreateanSQLpass-throughqueryinaMicrosoftJetworkspace,youdon'tneedtoexplicitlysettheTypepropertytodbQSQLPassThrough.TheMicrosoftJetdatabaseengineautomaticallysetsthiswhenyoucreateaQueryDefobjectandsettheConnectproperty.

ForaRecordsetobject,thepossiblesettingsandreturnvaluesareasfollows.

Constant RecordsettypedbOpenTable Table(MicrosoftJetworkspacesonly)dbOpenDynamic Dynamic(ODBCDirectworkspacesonly)dbOpenDynaset DynasetdbOpenSnapshot SnapshotdbOpenForwardOnlyForward-only

ForaWorkspaceobject,thepossiblesettingsandreturnvaluesareasfollows.

Constant Workspacetype

dbUseJet TheWorkspaceisconnectedtotheMicrosoftJetdatabaseengine.

dbUseODBC TheWorkspaceisconnectedtoanODBCdatasource.

Remarks

WhenyouappendanewField,Parameter,orPropertyobjecttothecollectionofanIndex,QueryDef,Recordset,orTableDefobject,anerroroccursiftheunderlyingdatabasedoesn'tsupportthedatatypespecifiedforthenewobject.

UniqueProperty

SetsorreturnsavaluethatindicateswhetheranIndexobjectrepresentsaunique(key)indexforatable(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleanthatisTrueiftheIndexobjectrepresentsauniqueindex.ForanIndexobject,thispropertysettingisread/writeuntiltheobjectisappendedtoacollection,afterwhichit'sread-only.

Remarks

Auniqueindexconsistsofoneormorefieldsthatlogicallyarrangeallrecordsinatableinaunique,predefinedorder.Iftheindexconsistsofonefield,valuesinthatfieldmustbeuniquefortheentiretable.Iftheindexconsistsofmorethanonefield,eachfieldcancontainduplicatevalues,buteachcombinationofvaluesfromalltheindexedfieldsmustbeunique.

IfboththeUniqueandPrimarypropertiesofanIndexobjectaresettoTrue,theindexisuniqueandprimary:Ituniquelyidentifiesallrecordsin

thetableinapredefined,logicalorder.IfthePrimarypropertyissettoFalse,theindexisasecondaryindex.Secondaryindexes(bothkeyandnonkey)logicallyarrangerecordsinapredefinedorderwithoutservingasanidentifierforrecordsinthetable.

Notes

Youdon'thavetocreateindexesfortables,butinlarge,unindexedtables,accessingaspecificrecordcantakealongtime.

Recordsretrievedfromtableswithoutindexesarereturnedinnoparticularsequence.

TheAttributespropertyofeachFieldobjectintheIndexobjectdeterminestheorderofrecordsandconsequentlydeterminestheaccesstechniquestouseforthatIndexobject.

Auniqueindexhelpsoptimizefindingrecords.

Indexesdon'taffectthephysicalorderofabasetable?indexesaffectonlyhowtherecordsareaccessedbythetable-typeRecordsetobjectwhenaparticularindexischosenorwhentheMicrosoftJetdatabaseenginecreatesRecordsetobjects.

UpdatableProperty

ReturnsavaluethatindicateswhetheryoucanchangeaDAOobject.

ReturnValues

ThereturnvalueisaBooleandatatypethatisTrueiftheobjectcanbechangedorupdated.(Snapshot-andforward-only–typeRecordsetobjectsalwaysreturnFalse.)

Remarks

Dependingontheobject,iftheUpdatablepropertysettingisTrue,theassociatedstatementinthefollowingtableistrue.

Object TypeindicatesConnection Dataintheconnecteddatabasecanbechanged.Database TheobjectcanbechangedQueryDef ThequerydefinitioncanbechangedRecordset TherecordscanbeupdatedTableDef Thetabledefinitioncanbechanged

TheUpdatablepropertysettingisalwaysTrueforanewlycreated

TableDefobjectandFalseforalinkedTableDefobject.AnewTableDefobjectcanbeappendedonlytoadatabaseforwhichthecurrentuserhaswritepermission.

Manytypesofobjectscancontainfieldsthatcan'tbeupdated.Forexample,youcancreateadynaset-typeRecordsetobjectinwhichonlysomefieldscanbechanged.Thesefieldscanbefixedorcontaindatathatincrementsautomatically,orthedynasetcanresultfromaquerythatcombinesupdatableandnonupdatabletables.

Iftheobjectcontainsonlyread-onlyfields,thevalueoftheUpdatablepropertyisFalse.Whenoneormorefieldsareupdatable,theproperty'svalueisTrue.Youcaneditonlytheupdatablefields.Atrappableerroroccursifyoutrytoassignanewvaluetoaread-onlyfield.

TheUpdatablepropertyofaQueryDefobjectissettoTrueifthequerydefinitioncanbeupdated,eveniftheresultingRecordsetobjectisn'tupdatable.

Becauseanupdatableobjectcancontainread-onlyfields,checktheDataUpdatablepropertyofeachfieldintheFieldscollectionofaRecordsetobjectbeforeyoueditarecord.

UpdateOptionsProperty

SetsorreturnsavaluethatindicateshowtheWHEREclauseisconstructedforeachrecordduringabatchupdate,andwhetherthebatchupdateshoulduseanUPDATEstatementoraDELETEfollowedbyanINSERT(ODBCDirectworkspacesonly).


ThesettingorreturnvalueisaLongthatcanbeanyofthefollowingconstants:


dbCriteriaKey (Default)Usesjustthekeycolumn(s)inthewhereclause.

dbCriteriaModValues Usesthekeycolumn(s)andallupdatedcolumnsinthewhereclause.

dbCriteriaAllCols Usesthekeycolumn(s)andallthecolumnsinthewhereclause.

dbCriteriaTimeStampUsesjustthetimestampcolumnifavailable(willgeneratearun-timeerrorifnotimestampcolumnisintheresultset).

dbCriteriaDeleteInsert UsesasetofDELETEandINSERTstatementsforeachmodifiedrow.

dbCriteriaUpdate (Default)UsesanUPDATEstatementforeachmodifiedrow.

Remarks

Whenabatch-modeUpdateisexecuted,DAOandtheclientbatchcursorlibrarycreateaseriesofSQLUPDATEstatementstomaketheneededchanges.AnSQLWHEREclauseiscreatedforeachupdatetoisolatetherecordsthataremarkedaschangedbytheRecordStatusproperty.Becausesomeremoteserversusetriggersorotherwaystoenforcereferentialintegrity,isitoftenimportanttolimitthefieldsbeingupdatedtojustthoseaffectedbythechange.Todothis,settheUpdateOptionspropertytooneoftheconstantsdbCriteriaKey,dbCriteriaModValues,dbCriteriaAllCols,ordbCriteriaTimeStamp.Thisway,onlytheabsoluteminimumamountoftriggercodeisexecuted.Asaresult,theupdateoperationisexecutedmorequickly,andwithfewerpotentialerrors.

YoucanalsoconcatenateeitheroftheconstantsdbCriteriaDeleteInsertordbCriteriaUpdatetodeterminewhethertouseasetofSQLDELETEandINSERTstatementsoranSQLUPDATEstatementforeachupdatewhensendingbatchedmodificationsbacktotheserver.Intheformercase,twoseparateoperationsarerequiredtoupdatetherecord.Insomecases,especiallywheretheremotesystemimplementsDELETE,INSERT,andUPDATEtriggers,choosingthecorrectUpdateOptionspropertysettingcansignificantlyimpactperformance.

Ifyoudon'tspecifyanyconstants,dbCriteriaUpdateanddbCriteriaKeywillbeused.

NewlyaddedrecordswillalwaysgenerateINSERTstatementsanddeletedrecordswillalwaysgenerateDELETEstatements,sothispropertyonlyappliestohowthecursorlibraryupdatesmodifiedrecords.

UserNameProperty

Setsorreturnsavaluethatrepresentsauser,agroupofusers,ortheownerofaWorkspaceobject.


ThesettingorreturnvalueisaStringthatevaluatestothenameofauser.InaMicrosoftJetworkspace,thisrepresentsaUserobjectintheUserscollectionoraGroupobjectintheGroupscollection.ForMicrosoftJetContainerandDocumentobjects,thispropertysettingisread/write.ForallWorkspaceobjects,thispropertysettingisread-only.

Remarks

Dependingonthetypeofobject,theUserNamepropertyrepresentsthefollowing.

TheownerofaWorkspaceobject.

AuserorgroupofuserswhenyoumanipulatetheaccesspermissionsofaContainerobjectoraDocumentobject

(MicrosoftJetworkspacesonly).

Tofindorsetthepermissionsforaparticularuserorgroupofusers,firstsettheUserNamepropertytotheuserorgroupnamethatyouwanttoexamine.ThencheckthePermissionspropertysettingtodeterminewhatpermissionsthatuserorgroupofusershas,orsetthePermissionspropertytochangethepermissions.

ForaWorkspaceobject,checktheUserNamepropertysettingtodeterminetheowneroftheWorkspaceobject.SettheUserNamepropertytoestablishtheowneroftheWorkspaceobjectbeforeyouappendtheobjecttotheWorkspacescollection.

V1xNullBehaviorProperty

Indicateswhetherzero-lengthstrings("")usedincodetofillTextorMemofieldsareconvertedtoNull.


ThesettingorreturnvalueisaBooleanthatisTrueifzero-lengthstringsareconvertedtoNull.

Remarks

ThispropertyappliestoMicrosoftJetdatabaseengineversion1.xdatabasesthathavebeenconvertedtoMicrosoftJetdatabaseengineversion2.0or3.0databases.

NoteTheMicrosoftJetdatabaseengineautomaticallycreatesthispropertywhenitconvertsaversion1.xdatabasetoaversion2.0or3.xdatabase.A2.0databasewillretainthispropertywhenitisconvertedtoa3.xdatabase.

Ifyouchangethispropertysetting,youmustcloseandthenreopenthedatabaseforyourchangetotakeeffect.

Forfastestperformance,modifycodethatsetsanyTextorMemofieldstozero-lengthstringssothatthefieldsaresettoNullinstead,andremovetheV1xNullBehaviorpropertyfromthePropertiescollection.

ValidateOnSetProperty

SetsorreturnsavaluethatspecifieswhetherornotthevalueofaFieldobjectisimmediatelyvalidatedwhentheobject'sValuepropertyisset(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaBooleanthatcanbeoneofthefollowingvalues.

Value Description

TrueThevalidationrulespecifiedbytheValidationRulepropertysettingoftheFieldobjectischeckedwhenyousettheobject'sValueproperty.

False (Default)Validatewhentherecordisupdated.

OnlyFieldobjectsinRecordsetobjectssupporttheValidateOnSetpropertyasread/write.

Remarks

SettingtheValidateOnSetpropertytoTruecanbeusefulinasituationwhenauserisenteringrecordsthatincludesubstantialMemodata.

WaitinguntiltheUpdatecalltovalidatethedatacanresultinunnecessarytimespentwritingthelengthyMemodatatothedatabaseifitturnsoutthatthedatawasinvalidanywaybecauseavalidationrulewasbrokeninanotherfield.

ValidationRuleProperty

Setsorreturnsavaluethatvalidatesthedatainafieldasit'schangedoraddedtoatable(MicrosoftJetworkspacesonly).


ThesettingsorreturnvaluesisaStringthatdescribesacomparisonintheformofanSQLWHEREclausewithouttheWHEREreservedword.ForanobjectnotyetappendedtotheFieldscollection,thispropertyisread/write.SeeRemarksforthemorespecificread/writecharacteristicsofthisproperty.

Remarks

TheValidationRulepropertydetermineswhetherornotafieldcontainsvaliddata.Ifthedataisnotvalid,atrappablerun-timeerroroccurs.ThereturnederrormessageisthetextoftheValidationTextproperty,ifspecified,orthetextoftheexpressionspecifiedbyValidationRule.

ForaFieldobject,useoftheValidationRulepropertydependsontheobjectthatcontainstheFieldscollectiontowhichtheFieldobjectisappended.

ObjectappendedtoUsageIndex NotsupportedQueryDef Read-onlyRecordset Read-onlyRelation NotsupportedTableDef Read/write

ForaRecordsetobject,useoftheValidationRulepropertyisread-only.ForaTableDefobject,useoftheValidationRulepropertydependsonthestatusoftheTableDefobject,asthefollowingtableshows.

TableDef UsageBasetable Read/writeLinkedtableRead-only

ValidationissupportedonlyfordatabasesthatusetheMicrosoftJetdatabaseengine.

ThestringexpressionspecifiedbytheValidationRulepropertyofaFieldobjectcanreferonlytothatField.Theexpressioncan'trefertouser-definedfunctions,SQLaggregatefunctions,orqueries.TosetaFieldobject'sValidationRulepropertywhenitsValidateOnSetpropertysettingisTrue,theexpressionmustsuccessfullyparse(withthefieldnameasanimpliedoperand)andevaluatetoTrue.IfitsValidateOnSetpropertysettingisFalse,theValidationRulepropertysettingisignored.

TheValidationRulepropertyofaRecordsetorTableDefobjectcanrefertomultiplefieldsinthatobject.TherestrictionsnotedearlierinthistopicfortheFieldobjectapply.

Foratable-typeRecordsetobject,theValidationRulepropertyinheritstheValidationRulepropertysettingoftheTableDefobjectthatyouusetocreatethetable-typeRecordsetobject.

ForaTableDefobjectbasedonanlinkedtable,theValidationRulepropertyinheritstheValidationRulepropertysettingoftheunderlyingbasetable.Iftheunderlyingbasetabledoesn'tsupportvalidation,the

valueofthispropertyisazero-lengthstring("").

NoteIfyousetthepropertytoastringconcatenatedwithanon-integervalue,andthesystemparametersspecifyanon-U.S.decimalcharactersuchasacomma(forexample,strRule="PRICE>"&lngPrice,andlngPrice=125,50),anerrorwillresultwhenyourcodeattemptstovalidateanydata.Thisisbecauseduringconcatenation,thenumberwillbeconvertedtoastringusingyoursystem'sdefaultdecimalcharacter,andMicrosoftJetSQLonlyacceptsU.S.decimalcharacters.

ValidationTextProperty

SetsorreturnsavaluethatspecifiesthetextofthemessagethatyourapplicationdisplaysifthevalueofaFieldobjectdoesn'tsatisfythevalidationrulespecifiedbytheValidationRulepropertysetting(MicrosoftJetworkspacesonly).


ThesettingorreturnvalueisaStringthatspecifiesthetextdisplayedifausertriestoenteraninvalidvalueforafield.Foranobjectnotyetappendedtoacollection,thispropertyisread/write.ForaRecordsetobject,thispropertysettingisread-only.ForaTableDefobject,thispropertysettingisread-onlyforalinkedtableandread/writeforabasetable.

Remarks

ForaFieldobject,useoftheValidationTextpropertydependsontheobjectthatcontainstheFieldscollectiontowhichtheFieldobjectisappended,asthefollowingtableshows.

ObjectappendedtoUsage

Index NotsupportedQueryDef Read-onlyRecordset Read-onlyRelation NotsupportedTableDef Read/write

ValueProperty

Setsorreturnsthevalueofanobject.


ThesettingorreturnvalueisaVariantdatatypethatevaluatestoavalueappropriateforthedatatype,asspecifiedbytheTypepropertyofanobject.

Remarks

Generally,theValuepropertyisusedtoretrieveandalterdatainRecordsetobjects.

TheValuepropertyisthedefaultpropertyoftheField,Parameter,andPropertyobjects.Therefore,youcansetorreturnthevalueofoneoftheseobjectsbyreferringtothemdirectlyinsteadofspecifyingtheValueproperty.

TryingtosetorreturntheValuepropertyinaninappropriatecontext(forexample,theValuepropertyofaFieldobjectintheFieldscollectionofaTableDefobject)willcauseatrappableerror.

Notes

InanODBCDirectworkspace,youcannotreadorsettheValuepropertyofaRecordsetfieldmorethanoncewithoutrefreshingthecurrentrecord.Forexample,toreadandthensettheValueproperty,firstreadtheproperty,thenusetheMove0methodtorefreshthecurrentrecord,thenwritethenewvalue.

WhenreadingdecimalvaluesfromaMicrosoftSQLServerdatabase,theywillbeformattedusingscientificnotationthroughaMicrosoftJetworkspace,butwillappearasnormaldecimalvaluesthroughanODBCDirectworkspace.

VersionProperty

MicrosoftJetworkspace?OntheDBEngineobject,returnstheversionofDAOcurrentlyinuse.OntheDatabaseobject,returnstheversionofJetthatcreatedthe.mdbfile.

ODBCDirectworkspace?OntheDBEngineobject,returnstheversionofDAOcurrentlyinuse.OntheDatabaseobject,returnstheversionoftheODBCdrivercurrentlyinuse.

ReturnValues

ThereturnvalueisaStringthatevaluatestoaversionnumber,formattedasfollows.

MicrosoftJetworkspace?representstheversionnumberintheform"major.minor".Forexample,"3.0".Theproductversionnumberconsistsoftheversionnumber(3),aperiod,andthereleasenumber(0).

ODBCDirectworkspace?representstheDAOversionnumberintheform"major.minor",orrepresentstheODBCdriverversionnumberintheform"major.minor.build".Forexample,theDBEngine.Versionvalueof“3.5”indicatedDAOversion3.5.ADatabaseobject'sVersionvalueof2.50.1032indicatesthatthecurrentinstanceofDAOisconnectedtoODBCversion2.5,build1032.

Remarks

InaMicrosoftJetworkspace,theVersionpropertyofaDatabaseobjectcorrespondstoaversionoftheMicrosoftJetdatabaseengine,anddoesn’tnecessarilymatchtheversionnumberoftheMicrosoftproductwithwhichthedatabaseenginewasincluded.Forexample,theVersionpropertyofaDatabaseobjectcreatedwithMicrosoftVisualBasic3.0willbe1.1,not3.0.

ThefollowingtableshowswhichversionofthedatabaseenginewasincludedwithvariousversionsofMicrosoftproducts.

MicrosoftJetVersion(yearreleased)

MicrosoftAccess

MicrosoftVisualBasic

MicrosoftExcel

MicrosoftVisualC++

1.0(1992) 1.0 N/A N/A N/A1.1(1993) 1.1 3.0 N/A N/A2.0(1994) 2.0 N/A N/A N/A2.5(1995) N/A 4.0(16-bit) N/A N/A3.0(1995) ‘95(7.0) 4.0(32-bit) ‘95(7.0) 4.x3.5(1996) ‘97(8.0) 5.0 ‘97(8.0) 5.0

VisibleValueProperty

ReturnsavaluecurrentlyinthedatabasethatisnewerthantheOriginalValuepropertyasdeterminedbyabatchupdateconflict(ODBCDirectworkspacesonly).

ReturnValues

Thereturnvalueisavariantexpression.

Remarks

Thispropertycontainsthevalueofthefieldthatiscurrentlyinthedatabaseontheserver.Duringanoptimisticbatchupdate,acollisionmayoccurwhereasecondclientmodifiedthesamefieldandrecordinbetweenthetimethefirstclientretrievedthedataandthefirstclient'supdateattempt.Whenthishappens,thevaluethatthesecondclientsetwillbeaccessiblethroughthisproperty.

ODBCDirect

AtechnologythatallowsyoutoaccessODBCdatasourcesdirectlybyusingDAOfeaturesthatbypasstheMicrosoftJetdatabaseengine.

ODBCdatasource

Atermusedtorefertoadatabaseordatabaseserverusedasasourceofdata.ODBCdatasourcesarereferredtobytheirDataSourceName(DSN).DatasourcescanbecreatedbyusingtheWindowsControlPanelortheRegisterDatabasemethod.

MicrosoftJetdatabaseengine

Adatabasemanagementsystemthatretrievesdatafromandstoresdatainuserandsystemdatabases.TheMicrosoftJetdatabaseenginecanbethoughtofasadatamanagercomponentwithwhichotherdataaccesssystems,suchasMicrosoftAccessandVisualBasic,arebuilt.

MicrosoftJetdatabase

AdatabasecreatedwiththeMicrosoftJetdatabaseengine.ThefilenameextensionforaMicrosoftJetdatabaseis.mdb.

batchupdate

Acursormodelforclientsthatworkwithcursorsbutdon'tholdlocksontheserverorissueupdatesbyrow.Instead,theclientupdatesmanyrowsthatarebufferedlocally,andthenitissuesabatchupdate.Thiscursormodelalsoallowstheclienttodroptheconnectiontotheserverandre-establishitwiththesameserverorevenadifferentserver.

TousebatchupdatinginDAO3.5,youmustuseanODBCDirectworkspace,theDefaultCursorDriverpropertymustbesettodbUseClientBatchCursoratthetimetheConnectionisopened,andtheRecordsetmustbeopenedwiththeOpenRecordsetmethod'slocktypeargumentsettodbOptimisticBatch.

collision

Aconflictthatoccursduringabatchupdate.

Acollisionoccurswhenaclientreadsdatafromtheserverandthenattemptstomodifythatdatainabatchupdate,butbeforetheupdateattemptisactuallyexecutedanotherclientchangestheoriginalserverdata.Inthissituation,thefirstclientisattemptingtomodifyserverdatawithoutknowingwhatdataactuallyexistsontheserver.

replica

Acopyofadatabase,includingitstables,queries,forms,reports,macros,andmodules.Areplicaisamemberofareplicasetandcanbesynchronizedwithotherreplicasintheset.Changestothedatainareplicatedtableinonereplicaaresentandappliedtotheothermembersinthereplicaset.

NoteTheDesignMasterisalsoareplica.

partialreplica

Adatabasethatcontainsonlyasubsetoftherecordsinafullreplica.Withapartialreplica,youcansetfiltersandidentifyrelationshipsthatdefinewhichsubsetoftherecordsinthefullreplicashouldbepresentinthedatabase.

MicrosoftJetworkspace

AworkspacethatusestheMicrosoftJetdatabaseenginetoaccessadatasource.ThedatasourcecanbeaMicrosoftJetdatabasefile(.mdb),anODBCdatabase,suchasaParadoxdatabase,oranISAMdatabase.

MicrosoftJet-connectedODBCdatasource

AnODBCdatasourcethatisaccessedbyusingDataAccessObjects(DAO)andtheMicrosoftJetdatabaseengine.

installableISAM

AdriveryoucanspecifythatallowsaccesstoexternaldatabaseformatssuchasdBASE,MicrosoftExcel,andParadox.ISAMisanacronymforIndexedSequentialAccessMethod.TheMicrosoftJetdatabaseengineinstalls(loads)theseISAMdriverswhenreferencedbyyourapplication.ThelocationofthesedriversismaintainedintheMicrosoftWindowsRegistry.

ODBCDirectworkspace

AworkspacethatusesODBCDirecttoaccessanODBCdatasourcedirectly,bypassingtheMicrosoftJetdatabaseengine.

ODBC(OpenDatabaseConnectivity)

Astandardprotocolthatpermitsapplicationstoconnecttoavarietyofexternaldatabaseserversorfiles.ODBCdriversusedbytheMicrosoftJetdatabaseenginepermitaccesstoMicrosoftSQLServerandseveralotherexternaldatabases.

TheODBCapplicationprogramminginterface(API)mayalsobeusedtoaccessODBCdriversandthedatabasestheyconnecttowithoutusingtheMicrosoftJetdatabaseengine.

asynchronousquery

AtypeofqueryinwhichSQLqueriesreturnimmediately,eventhoughtheresultsarestillpending.Thisenablesanapplicationtocontinuewithotherprocessingwhilethequeryispendingcompletion.

objectvariable

Avariablethatcontainsareferencetoanobject.

DDL(DataDefinitionLanguage)

Thelanguageusedtodescribeattributesofadatabase,especiallytables,fields,indexes,andstoragestrategy.

databasereplication

Theprocessofreproducingadatabasesothattwoormorecopies(replicas)ofthesamedatabasecanstaysynchronized.Changestothedatainareplicatedtableinonereplicaaresentandappliedtotheotherreplicasinthereplicaset.ChangesmadetothedesignofthedatabaseintheDesignMasteraresentandappliedtoallreplicasintheset.

permission

Oneormoreattributesthatspecifywhatkindofaccessauserhastodataorobjectsinadatabase.Forexample,ifauserhasreaddatapermissionforatableorquery,theusercanvieworretrievebutnoteditdatainthetableorquery.

method

Aproceduresimilartoafunctionthatoperatesonspecificobjects.

property

Anamedattributeofanobject.Propertiesdefineobjectcharacteristicssuchassize,color,andscreenlocation,orthestateofanobject,suchasenabledordisabled.

replicate

Produceareplica,orcopy,ofsomething?forexample,adatabase.

exclusive

Atypeofaccessthatprotectsdatainadatabasesharedoveranetwork.Whenyouopenadatabaseinexclusivemode,youpreventothersfromopeningthedatabase.

one-to-onerelationship

Anassociationbetweentwotablesinwhich:

Theprimarykeyvalueofeachrecordintheprimarytablecorrespondstothevalueinthematchingfieldorfieldsofoneandonlyonerecordintherelatedtable.

Theprimarykeyvalueofeachrecordintherelatedtablecorrespondstothevalueinthematchingfieldorfieldsofoneandonlyonerecordintheprimarytable.

relationship

Anassociationestablishedbetweencommonfields(columns)intwotables.Arelationshipcanbeone-to-one,many-to-many,orone-to-many.

referentialintegrity

Rulesthatyousettoestablishandpreserverelationshipsbetweentableswhenyouadd,change,ordeleterecords.Enforcingreferentialintegrityprohibitsusersfromaddingrecordstoajoinedtableforwhichthereisnoprimarykey,changingvaluesinaprimarytablethatwouldresultinorphanedrecordsinajoinedtable,anddeletingrecordsfromaprimarytablewhentherearematchingrelatedrecords.

IfyouselectthedbRelationDeleteCascadeordbRelationUpdateCascadeoptionforarelationship,theMicrosoftJetdatabaseengineallowschangesanddeletionsbutchangesordeletesrelatedrecordstomakesuretherulesarestillenforced.

linkedtable

AtableinanotherdatabaselinkedtoaMicrosoftJetdatabase.Dataforlinkedtablesremainsintheexternaldatabasewhereitcanbemanipulatedbyotherapplications.(Formerlyknownasattachedtables.)

server-sidecursor

Cursorsthatresideontheserver,asopposedtoresidingontheclientcomputer.Whileclient-sidecursorscopythecursortotheworkstation,server-sidecursorsusetheresourcesofthedatabaseservertomaintainthecursors.

replicateddatabase

Adatabasetowhichadditionaltables,fields,andpropertieshavebeenaddedtorecordinformationaboutchangestodataandthedesignofreplicatedobjectsinthedatabase.

actionquery

Aquerythatcopiesorchangesdata.Actionqueriesincludeappend,delete,make-table,andupdatequeries.Deleteandupdatequerieschangeexistingdata;appendandmake-tablequeriescopyexistingdata.Incontrast,selectqueriesreturndatarecords.AnSQLpass-throughquerymayalsobeanactionquery.

appendquery

Anactionquerythataddsnewrecordstotheendofanexistingtableorquery.Appendqueriesdon'treturnrecords(rows).

compoundquery

Aquerythatiscomposedofatleastoneactionquery(aquerythatcopiesorchangesdata)andatleastoneselectquery(aquerythatreturnsaRecordsetwithoutchangingdata).InDAO,acompoundqueryiscreatedbyputtingtwoormoreSQLstatements(separatedbysemicolons)intheSQLpropertyofaQueryDefobject.

crosstabquery

Aquerythatcalculatesasum,average,count,orothertypeoftotalonrecords,andthengroupstheresultbytwotypesofinformation?onedowntheleftsideofagrid(rowheadings)andtheotheracrossthetop(columnheadings).Forexample,theQuarterlyOrdersbyProductqueryintheNorthwindsampledatabaseisacrosstabquery.

data-definitionquery

AnSQL-specificquerythatcancreate,alter,ordeleteatable,orcreateordeleteanindexinadatabase.

deletequery

Anactionquerythatdeletesasetofrowsthatmatchthecriteriayouspecify.Adeletequerydoesn’treturnrows.

make-tablequery

AnactionquerythatcreatesanewtablefromtheRecordsetobjectofanexistingquery.

selectquery

AquerythatasksaquestionaboutthedatastoredinyourtablesandreturnsaRecordsetobjectwithoutchangingthedata.OncetheRecordsetdataisretrieved,youcanexamineandmakechangestothedataintheunderlyingtables.Incontrast,actionqueriescanmakechangestoyourdata,buttheydon'treturndatarecords.

pass-throughquery

AnSQL-specificqueryyouusetosendcommandsdirectlytoaSQLdatabaseserver(suchasMicrosoftSQLServer).Withpass-throughqueries,youworkwiththetablesontheserverinsteadoflinkingthem.Pass-throughqueriesareusedtoexecuteSQLqueriesandsystem-specificcommandswrittenbyusingSQLdialectsknownonlytotheserver.

Apass-throughquerymayormaynotreturnrecords.Ifitdoes,theyarealwaysreturnedinasnapshot.

updatequery

Anactionquerythatchangesasetofrecordsaccordingtocriteriayouspecify.Anupdatequerydoesn’treturnanyrecords.

inconsistent

Thestateofamultiple-tableRecordsetobjectthatenablesyoutoupdateallfields(columns).Forexample,inaRecordsetcreatedbyjoiningtwotablesinaone-to-manyjoin(asinaCustomersandOrderstable),youcanupdateOrders.CustomerIDsothatitdoesn’tmatchCustomers.CustomerID,unlessreferentialintegritydisablestheupdate.

consistent

Thestateofamultiple-tableRecordsetobjectthatallowsyoutoperformonlyupdatesthatresultinaconsistentviewofthedata.Forexample,inaRecordsetthatisajoinoftwoormoretables(aone-to-manyrelationship),aconsistentquerywouldnotallowyoutosetthemany-sidekeytoavaluethatisn’tintheone-sidetable.

ODBCDriverManager

AnapplicationthatmanagesconnectionsbetweenODBC-enableddatasourcesandthedriversusedtoaccessthem.

connectionstring

Astringusedtodefinethesourceofdataforanexternaldatabase.TheconnectionstringisusuallyassignedtotheConnectpropertyofaQueryDef,TableDef,Connection,orDatabaseobjectorasanargumenttotheOpenDatabasemethod.

dynaset

AtypeofRecordsetobjectthatreturnsadynamicsetofpointerstolivedatabasedata.Likeatable-orasnapshot-typeRecordset,adynasetreturnsdatainrecords(rows)andfields(columns).Unlikeatable-typeRecordset,adynaset-typeRecordsetcanbetheresultofaquerythatjoinstwoormoretables.Therecordsinadynaset-typeRecordsetobjectareupdatableiftheUpdatablepropertyoftheRecordsetisTrue,theFieldbeingchangedisupdatable,andthedatapagecontainingthecurrentrecordisn’tlocked.ThedatapageislockedwhentheUpdatemethodisused(whentheLockEditspropertyisFalse),ortheEditmethodisused(whentheLockEditspropertyisTrue).

SQLstatement/string

AnexpressionthatdefinesaStructuredQueryLanguage(SQL)command,suchasSELECT,UPDATE,orDELETE,andmayincludeclausessuchasWHEREandORDERBY.SQLstringsandstatementsaretypicallyusedinqueries,Recordsetobjects,andaggregatefunctionsbutcanalsobeusedtocreateormodifyadatabasestructure.

DAOobject

AnobjectthatisdefinedbytheDataAccessObjects(DAO)library.YoucanuseDAOobjects,suchastheDatabase,TableDef,Recordset,andQueryDefobjects,torepresentobjectsthatareusedtoorganizeandmanipulatedata,suchastablesandqueries,incode.

group

AcollectionofuseraccountsinaWorkgroupobject,identifiedbygroupnameandpersonalidentifier(PID).Permissionsassignedtoagroupapplytoallusersinthegroup.

parameterquery

Aquerythatrequiresyoutoprovideoneormorecriteriavalues,suchasRedmondforCity,beforethequeryisrun.Aparameterqueryisn’t,strictlyspeaking,aseparatekindofquery;rather,itextendstheflexibilityofotherqueries.

basetable

AtableinaMicrosoftJetdatabase.Atabledefinesthestructureofarelationaldatabase,andisanobjectthatstoresdatainrecordsandfields.YoucanmanipulatethestructureofabasetablebyusingtheDAOobjectsordatadefinitionSQLstatements,andyoucanmodifydatainabasetablebyusingRecordsetobjectsoractionqueries.

useraccount

Anaccountidentifiedbyausernameandpersonalidentifier(PID)thatiscreatedtomanageaccesstodatabaseobjectsinaMicrosoftJetdatabaseWorkgroupobject.

session

AsessiondelineatesasequenceofoperationsperformedbytheMicrosoftJetdatabaseengine.Asessionbeginswhenauserlogsonandendswhenauserlogsoff.Alloperationsperformedduringasessionformonetransactionscopeandaresubjecttopermissionsdeterminedbythelogonusernameandpassword.SessionsareimplementedasWorkspaceobjectsbyDAO.

persistentobject

Anobjectstoredinthedatabase;forexample,adatabasetableorQueryDefobject.Dynaset-typeorsnapshot-typeRecordsetobjectsarenotconsideredpersistentobjectsbecausetheyarecreatedinmemoryasneeded.

transaction

Aseriesofchangesmadetoadatabase'sdataandschema.MarkthebeginningofatransactionwiththeBeginTransstatement,committhetransactionbyusingtheCommitTransstatement,andundoallyourchangessinceBeginTransbyusingtheRollbackstatement.

Transactionsareoptionalandcanbenesteduptofivelevels.Transactionsincreasethespeedofoperationsthatchangedataandenableyoutoreversechangeseasily.

Transactionsareglobaltothereferenceddatabaseobject'sWorkspace.

DataAccessObjects(DAO)

Aprogramminginterfacetoaccessandmanipulatedatabaseobjects.

dynamiccursor

Adynamicsetofrowsthatyoucanusetoadd,change,ordeleterowsfromanunderlyingdatabasetableortables.Adynamiccursorcancontaincolumnsfromoneormoretablesinadatabase.Membershipisnotfixed.

Dynaset-TypeRecordsetObject

Adynaset-typeRecordsetobjectisadynamicsetofrecordsthatcancontainfieldsfromoneormoretablesorqueriesinadatabaseandmaybeupdatable.InanODBCDirectdatabase,adynaset-typeRecordsetobjectcorrespondstoanODBCkeysetcursor.

Remarks

Adynaset-typeRecordsetobjectisatypeofRecordsetobjectyoucanusetomanipulatedatainanunderlyingdatabasetableortables.

Itdiffersfromasnapshot-typeRecordsetobjectbecausethedynasetstoresonlytheprimarykeyforeachrecord,insteadofactualdata.Asaresult,adynasetisupdatedwithchangesmadetothesourcedata,whilethesnapshotisnot.Likethetable-typeRecordsetobject,adynaset

retrievesthefullrecordonlywhenit'sneededforeditingordisplaypurposes.

Tocreateadynaset-typeRecordsetobject,usetheOpenRecordsetmethodonanopendatabase,againstanotherdynaset-orsnapshot-typeRecordsetobject,onaQueryDefobject,oronaTableDefobject.(OpeningRecordsetobjectsonotherRecordsetobjectsorTableDefobjectsisavailableonlyinMicrosoftJetworkspaces.)

Ifyourequestadynaset-typeRecordsetobjectandtheMicrosoftJetdatabaseenginecan'tgainread/writeaccesstotherecords,theMicrosoftJetdatabaseenginemaycreatearead-only,dynaset-typeRecordsetobject.

Asusersupdatedata,thebasetablesreflectsthesechanges.Therefore,currentdataisavailabletoyourapplicationwhenyourepositionthecurrentrecord.Inamultiuserdatabase,morethanoneusercanopenadynaset-typeRecordsetobjectreferringtothesamerecords.Becauseadynaset-typeRecordsetobjectisdynamic,whenoneuserchangesarecord,otherusershaveimmediateaccesstothechangeddata.However,ifoneuseraddsarecord,otheruserswon’tseethenewrecorduntiltheyusetheRequerymethodontheRecordsetobject.Ifauserdeletesarecord,otherusersarenotifiedwhentheytrytoaccessit.

Recordsaddedtothedatabasedon'tbecomeapartofyourdynaset-typeRecordsetobjectunlessyouaddthembyusingtheAddNewandUpdatemethods.Forexample,ifyouuseanactionquerycontaininganINSERTINTOSQLstatementtoaddrecords,thenewrecordsaren'tincludedinyourdynaset-typeRecordsetobjectuntilyoueitherusetheRequerymethodoryourebuildyourRecordsetobjectusingtheOpenRecordsetmethod.

Tomaintaindataintegrity,theMicrosoftJetdatabaseenginecanlockdynaset-andtable-typeRecordsetobjectsduringEdit(pessimisticlocking)orUpdateoperations(optimisticlocking)sothatonlyoneusercanupdateaparticularrecordatatime.WhentheMicrosoftJetdatabaseenginelocksarecord,itlockstheentire2Kpagecontainingtherecord.

Youcanalsouseoptimisticandpessimisticlockingwithnon-ODBCtables.WhenyouaccessexternaltablesusingODBCthroughaMicrosoftJetworkspace,youshouldalwaysuseoptimisticlocking.TheLockEditspropertyandthelockeditsparameteroftheOpenRecordsetmethoddeterminethelockingconditionsduringediting.

Notallfieldscanbeupdatedinalldynaset-typeRecordsetobjects.Todeterminewhetheryoucanupdateaparticularfield,checktheDataUpdatablepropertysettingoftheFieldobject.

Adynaset-typeRecordsetobjectmaynotbeupdatableif:

Thereisn'tauniqueindexontheODBCorParadoxtableortables.

Thedatapageislockedbyanotheruser.

Therecordhaschangedsinceyoulastreadit.

Theuserdoesn'thavepermission.

Oneormoreofthetablesorfieldsareread-only.

Thedatabaseisopenedasread-only.

TheRecordsetobjectwaseithercreatedfrommultipletableswithoutaJOINstatementorthequerywastoocomplex.

Theorderofadynaset-typeRecordsetobjectorRecordsetdatadoesn'tnecessarilyfollowanyspecificsequence.Ifyouneedtoorderyourdata,useanSQLstatementwithanORDERBYclausetocreatethe

Recordsetobject.YoucanalsouseaWHEREclausetofiltertherecordssothatonlycertainrecordsareaddedtotheRecordsetobject.UsingSQLstatementsinthiswaytoselectasubsetofrecordsandorderthemusuallyresultsinfasteraccesstoyourdatathanusingtheFilterandSortproperties.

Longdatatype

Afundamentaldatatypethatholdslong-integernumbers.ALongvariableisstoredasa32-bit(4-byte)numberranginginvaluefrom-2,147,483,648to2,147,483,647.

HelpContext,HelpFileProperties

HelpContext—returnsacontextID,asaLongvariable,foratopicinaMicrosoftWindowsHelpfile.

HelpFile—returnsaStringthatisafullyqualifiedpathtotheHelpfile.

Remarks

IfyouspecifyaMicrosoftWindowsHelpfileinHelpFile,youcanusetheHelpContextpropertytoautomaticallydisplaytheHelptopicitidentifies.

NoteYoushouldwriteproceduresinyourapplicationtohandletypicalerrors.Whenprogrammingwithanobject,youcanusetheHelpsuppliedbytheobject'sHelpfiletoimprovethequalityofyourerrorhandling,ortodisplayameaningfulmessagetoyouruseriftheerrorisnotrecoverable.

currentrecord

TherecordinaRecordsetobjectthatyoucanusetomodifyorexaminedata.UsetheMovemethodstorepositionthecurrentrecordinarecordset.UsetheFindmethods(withadynaset-orsnapshot-typeRecordsetobject)ortheSeekmethod(withatable-typeRecordsetobject)tochangethecurrentrecordpositionaccordingtospecificcriteria.

OnlyonerecordinaRecordsetcanbethecurrentrecord;however,aRecordsetmayhavenocurrentrecord.Forexample,afteradynaset-typeRecordsetrecordhasbeendeleted,orwhenaRecordsethasnorecords,thecurrentrecordisundefined.Inthiscase,operationsthatrefertothecurrentrecordresultinatrappableerror.

datatype

Thecharacteristicsofavariablethatdeterminewhatkindofdatathevariablecanhold.DatatypesincludeBigInteger,Binary,Byte,Boolean,Char,Currency,Date,Decimal,Double,Float,GUID,Integer,Long,LongBinary(OLEObject),Memo,Numeric,Single,String,Text,Time,TimeStamp,VarBinary,Variant(default),user-definedtypes(createdwiththeTypestatement),andobjectdatatypes,whichincludehost-definedobjectdatatypesandDAOobjecttypes.

OLEObjectdatatype

AfielddatatypeyouuseforobjectscreatedinotherapplicationsthatcanbelinkedorembeddedinaMicrosoftJetdatabase.Forexample,youcoulduseanOLEObjectfieldtostoreacollectionofpictures.

Memodatatype

Afielddatatype.Suchfieldscancontainupto1.2GBoftextdata.

forward-onlycursor

Aresultsetwherethecurrentpositioncanonlymoveforwardbyaspecifiednumberofrecords,ortotheverylastrecord.Thecurrentpositioncannotbemovedbacktothebeginningoftheresultsetortopreviousrecords.Thecursormembership,order,andvaluesaregenerallyfixedwhenthecursorisopened.Ifotherusersupdate,delete,orinsertrows,thecursordoesn'treflectthesechangesuntilyoucloseandreopenit.

secureworkgroup

AMicrosoftJetdatabaseWorkgroupobjecttowhichuserslogonwithausernameandpasswordandinwhichaccesstodatabaseobjectsisrestrictedaccordingtopermissionsspecifiedforuseraccountsandgroups.

Null

Avaluethatindicatesmissingorunknowndata.Nullvaluescanbeenteredinfieldsforwhichinformationisunknownandinexpressionsandqueries.InVisualBasic,theNullkeywordindicatesaNullvalue.Somefields,suchasthosedefinedascontainingtheprimarykey,can’tcontainNullvalues.

join

Adatabaseoperationthatcombinessomeorallrecordsfromtwoormoretables,suchasanequi-join,outerjoin,orself-join.Generally,ajoinreferstoanassociationbetweenafieldinonetableandafieldofthesamedatatypeinanothertable.YoucreateajoinwithanSQLstatement.

Whenyoudefinearelationshipbetweentwotables,youcreateajoinbyspecifyingtheprimaryandforeigntablefields.Whenyouaddatabletoaquery,youneedtocreateajoinbetweenappropriatefieldsintheSQLstatementthatdefinesthequery.

primarykey

Oneormorefieldswhosevalueorvaluesuniquelyidentifyeachrecordinatable.Inarelationship,aprimarykeyisusedtorefertospecificrecordsinonetablefromanothertable.Aprimarykeyiscalledaforeignkeywhenitisreferredtofromanothertable.Youcanhaveonlyoneprimarykey.AnEmployeestable,forexample,couldusethesocialsecuritynumberfortheprimarykey.

foreignkey

Oneormoretablefieldsthatrefertotheprimarykeyfieldorfieldsinanothertable.Aforeignkeyindicateshowthetablesarerelated?thedataintheforeignkeyandprimarykeyfieldsmustmatch.Forexample,alistofvalidpartnumberswouldcontainaforeignkeytoaninventorytablecontainingreferencestovalidpartnumbers.Usedwhenestablishingreferentialintegrityforadatabase.

cascadingupdate

Forrelationshipsenforcingreferentialintegritybetweentables,anoptionthatcausesachangetotheprimarykeyinarecordintheprimarytabletoautomaticallyupdatetheforeignkeyinallrelatedrecordsintherelatedforeigntableortables.

Forexample,supposeyouestablisharelationshipbetweenaCustomers(primary)tableandanOrders(foreign)tablewiththecascadingupdateoptionenabled.WhentheprimarykeyinarecordintheCustomerstableischanged,allordersassociatedwiththatcustomerwouldalsobechangedintheforeignOrderstable.

cascadingdelete

Forrelationshipsthatenforcereferentialintegritybetweentables,anoptionthatcausesthedeletionofarecordfromtheprimarytabletoautomaticallydeleteallrelatedrecordsintherelatedforeigntableortables.

Forexample,supposeyouestablisharelationshipbetweenaCustomers(primary)tableandanOrders(foreign)tablewiththecascadingdeleteoptionenabled.WhenarecordintheCustomerstableisdeleted,allordersassociatedwiththatcustomerwouldalsobedeletedintheforeignOrderstable.

Stringdatatype

Afundamentaldatatypethatholdscharacterinformation.AStringvariableiseitherfixed-lengthorvariable-lengthandcontainsonecharacterperbyte.Fixed-lengthstringsaredeclaredtobeaspecificlengthandcancontain1toapproximately64K(2^16)characters.Variable-lengthstringscanbeanylengthupto2billion(2^31)characters(approximately64K[2^16]charactersforMicrosoftWindowsversion3.1andearlier),lessasmallamountofstorageoverhead.

Integerdatatype

Afundamentaldatatypethatholdsintegernumbers.AnIntegervariableisstoredasa16-bit(2-byte)numberranginginvaluefrom-32,768to32,767.

Variantdatatype

Aspecialdatatypethatcancontainnumeric,string,ordatedataaswellasthespecialvaluesEmptyandNull.TheVarTypefunctiondefineshowthedatainaVariantistreated.Allvariablesbecomevarianttypesifnotexplicitlydeclaredassomeothertype.

Booleandatatype

ATrue/Falseoryes/novalue.BooleanvaluesareusuallystoredinBitfieldsinaMicrosoftJetdatabase;however,somedatabasesdon'tsupportthisdatatypedirectly.

zero-lengthstring

Astringcontainingnocharacters("").TheLenfunctionofazero-lengthstringreturns0.

query

Aformalizedinstructiontoadatabasetoeitherreturnasetofrecordsorperformaspecifiedactiononasetofrecordsasspecifiedinthequery.Forexample,thefollowingSQLquerystatementreturnsrecords:

SELECTCompanyNameFROMPublishersWHERERegion='NY'

Youcancreateandrunselect,action,crosstab,parameter,andSQL-specificqueries.

record

Asetofrelateddataaboutaperson,place,event,orsomeotheritem.Tabledataisstoredinrecords(rows)inthedatabase.Eachrecordiscomposedofasetofrelatedfields(columns)?eachfielddefiningoneattributeofinformationfortherecord.Takentogether,arecorddefinesonespecificunitofretrievableinformationinadatabase.

field

Acategoryofinformationstoredinatableinadatabase?acolumnofdata.Anelementofadatabasetablethatcontainsaspecificitemofinformation,suchaslastname.

keysetcursor

Asetofrowsthatyoucanusetoadd,change,ordeleterowsfromanunderlyingdatabasetableortables.Movementwithinthekeysetisunrestricted.Akeysetcursorcancontaincolumnsfromoneormoretablesinadatabase.Membershipisfixed.

staticcursor

Aresultsetwherethemembership,order,andvaluesaregenerallyfixedwhenthecursorisopened.Ifotherusersupdate,delete,orinsertrows,thecursordoesn'treflectthesechangesuntilyoucloseandreopenit.

scope

Theattributeofavariableorprocedurethatdetermineswhichsectionsofwhichmodulesrecognizeit.Therearethreelevelsofscope:public,module,andprocedure.VariablesthatyoudeclarewithPubliccanbeaccessedbyanymodule,whilevariablesthatyoudeclareinaspecificmodulecanbeusedonlywithinthatmodule.Also,variablesthatyoudeclareinaSuborFunctionprocedurecanbeusedonlyinthatparticularprocedure.

TEMP

ATEMPenvironmentvariableissetbyyourautoexec.batfilewhenyoustartyoursystem.Generally,TEMPpointstoanareaonyourharddiskusedbyMicrosoftWindowsandotherprograms,liketheMicrosoftJetdatabaseengine,tostoreinformationthatdoesn'tneedtobesavedafteryoushutdownyoursystem.Forexample,thefollowinglineinyourautoexec.batfilepointstheTEMPenvironmentvariabletotheD:\TempAreafolder:

SETTEMP=D:\TempArea

primarytable

The"one"sideoftworelatedtablesinaone-to-manyrelationshipwithaforeigntable.Generally,aprimarykeytableisusedtoestablishorenforcereferentialintegrity.

foreigntable

Atablethatprovidesaforeignkeytoanothertableinthedatabase.Generally,youuseaforeigntabletoestablishorenforcereferentialintegrity.Theforeigntableisusuallyonthe"many"sideofaone-to-manyrelationship.Anexampleofaforeigntableisatableofcustomerorders.

one-to-manyrelationship

Anassociationbetweentwotablesinwhich:

Theprimarykeyvalueofeachrecordintheprimarytablecorrespondstothevalueinthematchingfieldorfieldsofmanyrecordsintherelatedtable.

Theprimarykeyvalueofeachrecordintherelatedtablecorrespondstothevalueinthematchingfieldorfieldsofoneandonlyonerecordintheprimarytable.

leftjoin

Aleftouterjoinincludesalloftherecordsfromthefirst(left)oftwotables,eveniftherearenomatchingvaluesforrecordsinthesecond(right)table.

rightjoin

Arightouterjoinincludesalloftherecordsfromthesecond(right)oftwotables,eveniftherearenomatchingvaluesforrecordsinthefirst(left)table.

Forexample,youcoulduseLEFTJOINwiththeDepartments(left)andEmployees(right)tablestoselectalldepartments,includingthosethathavenoemployeesassignedtothem.Toselectallemployees,includingthosewhoaren'tassignedtoadepartment,youwoulduseRIGHTJOIN.

index

Adynamiccross-referenceofoneormoretabledatafields(columns)thatpermitsfasterretrievalofspecificrecordsfromatable.Asrecordsareadded,changed,ordeleted,thedatabasemanagementsystemautomaticallyupdatestheindextoreflectthechanges.

Whenusedwithatable-typeRecordsetobject,thecurrentindexdeterminestheorderinwhichdatarecordsarereturnedtotheRecordset.Atablemayhaveseveralindexesdefinedforitsdata.

ADAOIndexobjectrepresentsanindexforaTableDefobject.

locked

Theconditionofadatapage,Recordsetobject,orDatabaseobjectthatmakesitread-onlytoallusersexcepttheonewhoiscurrentlyenteringdatainit.

page

Aportionofthedatabaseinwhichrecorddataisstored.Dependingonthesizeoftherecords,apagemaycontainmorethanonerecord.InMicrosoftJetdatabases(.mdb),apageis2048(2K)bytesinlength.

pessimistic

Atypeoflockinginwhichthepagecontainingoneormorerecords,includingtherecordbeingedited,isunavailabletootheruserswhenyouusetheEditmethod,andremainsunavailableuntilyouusetheUpdatemethod.PessimisticlockingisenabledwhentheLockEditspropertyoftheRecordsetobjectissettoTrue.

optimistic

Atypeoflockinginwhichthedatapagecontainingoneormorerecords,includingtherecordbeingedited,isunavailabletootherusersonlywhiletherecordisbeingupdatedbytheUpdatemethod,butisavailablebetweentheEditandUpdatemethods.OptimisticlockingisusedwhenaccessingODBCdatabasesorwhentheLockEditspropertyoftheRecordsetobjectissettoFalse.

defaultworkspace

TheWorkspaceobjectthatDAOautomaticallyestablisheswhenyourapplicationfirstreferencesanyDAOobject.ThisWorkspaceisreferencedbyDBEngine.Workspaces(0)orsimplyWorkspaces(0).

sortorder

Asequencingprincipleusedtoorderdata,alphabeticallyornumerically.Thesortordercanbeeitherascendingordescending.

bookmark

ApropertyoftheRecordsetobjectthatcontainsabinarystringidentifyingthecurrentrecord.IfyouassigntheBookmarkvaluetoavariableandthenmovetoanotherrecord,youcanmaketheearlierrecordcurrentagainbysettingtheBookmarkpropertytothatstringvariable.

collection

Anobjectthatcontainsasetofrelatedobjects.Anobject'spositioninthecollectioncanchangewheneverachangeoccursinthecollection;therefore,thepositionofanyspecificobjectinthecollectionmayvary.

stringexpression

Anyexpressionthatevaluatestoasequenceofcontiguouscharacters.Elementsoftheexpressioncanincludeafunctionthatreturnsastring,astringliteral,astringconstant,astringvariable,astringVariant,orafunctionthatreturnsastringVariant(VarType8).

LongBinarydatatype

Atypeoffieldthatcanhold1.2GBofdata.LongBinaryfieldscancontainanytypeofbinarydata.(AlsoknownasanOLEObjectdatatypeinMicrosoftAccess).

currenttransaction

AllchangesmadetoaRecordsetobjectafteryouusethelastBeginTransmethodandbeforeyouusetheRollbackorCommitTransmethod.

update

Theprocessthatsaveschangestodatainarecord.Untiltherecordissaved,changesarestoredinatemporaryrecordcalledthecopybuffer.TheUPDATEclauseinanSQLstatementchangesdatavaluesinoneormorerecords(rows)inadatabasetable.

forward-only–typeRecordset

ARecordsetobjectinwhichrecordscanbesearchedonlyfrombeginningtoend;thecurrentrecordpositioncan'tbemovedbacktothefirstrecord.Forward-only–typerecordsetsreduceprocessingoverheadonremotedatabases.Forexample,youcanuseaforward-only–typeRecordsetonalinkedremotetabletoquicklyprocessdatainonepass,suchaswhenyou’rebuildingacustomizedreport.

personalidentifier(PID)

Acase-sensitivealphanumericstring4-20characterslongthattheMicrosoftJetdatabaseengineusesincombinationwiththeaccountnametoidentifyauserorgroupinaWorkgroupobject.YouprovidethePIDandtheaccountnamewhenyoucreateanewuserorgroup.

replicatedobject

Atable,query,form,report,macro,ormodulethatisinallreplicasinthereplicaset.YoucanchangethereplicatedobjectonlyattheDesignMaster,andthesechangesaredispersedtootherreplicasinthereplicasetduringasynchronization.

localobject

Atable,query,form,report,macro,ormodulethatremainsinthereplicawhereitwascreated.Neithertheobjectnorchangestotheobjectaredispersedtoothermembersinthereplicaset.

ASCIICharacterSet

AmericanStandardCodeforInformationInterchange(ASCII)7-bitcharactersetwidelyusedtorepresentlettersandsymbolsfoundonastandardU.S.keyboard.TheASCIIcharactersetisthesameasthefirst128characters(0?127)intheANSIcharacterset.

copybuffer

AlocationcreatedbytheMicrosoftJetdatabaseengineforthecontentsofarecordthatisopenforediting.TheEditmethodcopiesthecurrentrecordtothecopybuffer;theAddNewmethodclearsthebufferforanewrecordandsetsthedefaultvalues;andtheUpdatemethodsavesthedatafromthecopybuffertothedatabase,replacingthecurrentrecordorinsertingthenewrecord.Anystatementthatresetsormovesthecurrentrecordpointerdiscardsthecopybuffer.Forexample,usingtheMoveNextmethodorchangingtheIndexpropertyofatablewoulddiscardthecontentsofthecopybuffer.

array

Avariablethatcontainsafinitenumberofelementsthathaveacommonnameanddatatype.Eachelementofanarrayisidentifiedbyauniqueindexnumber.Changesmadetooneelementofanarraydonotaffecttheotherelements.

run-timeerror

Anerrorthatoccurswhencodeisrunning.Arun-timeerrorresultswhenastatementattemptsaninvalidoperation.

replicaset

Replicasthatsharethesamedatabasedesignanduniquereplicasetidentifier.Synchronizationoccursbetweenreplicasetmembers.

currentindex

Foranindexedtable-typeRecordsetobject,theindexmostrecentlysetwiththeIndexproperty.Thisindexisthebasisfororderingrecordsinatable-typeRecordset,andisusedbytheSeekmethodtolocaterecords.ARecordsetobjectcanhavemorethanoneindexbutcanuseonlyoneindexatatime(althoughaTableDefobjectmayhaveseveralindexesdefinedonit).TheMicrosoftJetdatabaseenginemayusemorethanoneindextoevaluateaquery.

case-sensitive

Capableofdistinguishingbetweenuppercaseandlowercaseletters.Acase-sensitivesearchfindsonlytextthatisanexactmatchofuppercaseandlowercaseletters.Suchasearchwould,forinstance,treat“ZeroLengthStr”and“zerolengthstr”asdifferent.MicrosoftJetdatabaseoperationsarenotcase-sensitive.However,casesensitivityisafeatureofsomeotherdatabasemanagementsystems.

ODBCdriver

Adynamic-linklibrary(DLL)usedtoconnectaspecificOpenDatabaseConnectivitydatasourcewithanother(client)application.

DLL(dynamic-linklibrary)

Asetofroutinesthatcanbecalledfromproceduresandareloadedandlinkedintoyourapplicationatruntime.

fielddatatypes

ThefollowingtableliststheFielddatatypes.

DAOFielddatatype ConstantBigInteger dbBigIntBinary dbBinaryBoolean dbBooleanByte dbByteChar dbCharCurrency dbCurrencyDate/Time dbDateDecimal dbDecimalDouble dbDoubleFloat dbFloatGUID dbGUIDInteger dbIntegerLong dbLongLongBinary(OLEObject) dbLongBinaryMemo dbMemoNumeric dbNumericSingle dbSingleText dbTextTime dbTimeTimeStamp dbTimeStampVarBinary dbVarBinary

Internet

Aworldwidenetworkofthousandsofsmallercomputernetworksandmillionsofcommercial,educational,government,andpersonalcomputers.TheInternetislikeanelectroniccitywithvirtuallibraries,storefronts,businessoffices,artgalleries,andsoon.

DesignMaster

Adatabasetowhichsystemtables,systemfields,andreplicationpropertieshavebeenadded.ADesignMasteristhefirstreplicainareplicaset.YoucanmakechangestothedatabasestructureonlywiththeDesignMaster.ReplicasinthesamereplicasetcantaketurnsbeingtheDesignMaster,buttherecanbeonlyoneDesignMasteratatimeineachreplicaset.

synchronization

Theprocessofupdatingtworeplicasinwhichallupdatedrecordsandobjectsareexchanged.Theexchangeofdatabetweentworeplicascanbeone-wayortwo-wayandmaybehandledbyaSynchronizer.

Textdatatype

Afielddatatype.Textfieldscancontainupto255charactersorthenumberofcharactersspecifiedbytheSizepropertyoftheFieldobject,whicheverisless.IftheSizepropertyofthetextfieldissetto0,thetextfieldcanholdupto255charactersofdata.

currentdatabase

TheDatabaseobjectreturnedbytheCurrentDB()function.AreferenceofDBEngine.Workspaces(0).Databases(0)returnsthefirstdatabaseopened.ThisconceptappliesonlytoMicrosoftAccess.

variantexpression

Anyexpressionthatcanevaluatetonumeric,string,ordatedataaswellasthespecialvaluesEmptyandNull.

Bytedatatype

Afundamentaldatatypeusedtoholdsmallpositiveintegernumbersrangingfrom0to255.

ODBCDirectdatasource

AdatasourcethatisaccessedbyusingtheDAOODBCDirectfeatures,whichbypasstheMicrosoftJetdatabaseengine.

clusteredindex

Thephysicalorderofrowsisthesameastheindexedorderofrows.

stringcomparison

Theuseofanoperatortodeterminewhetheronestringisgreaterthanorequaltoanotherstring.IfyouuseOptionCompareTextintheDeclarationssectionofamodule,stringcomparisonsarenotcase-sensitive.IfyouuseOptionCompareBinary,comparisonsarecase-sensitive.IfyouuseOptionCompareDatabase,thecomparisonmethodissetbythecurrentdatabase.

conflicttable

Atablethatisgeneratedwhenasynchronizationconflictoccursbetweentworeplicas.Theconflicttableappearsonlyinthereplicawithrejectedchanges.

objectexpression

Anexpressionthatspecifiesaparticularobject.Thisexpressioncanincludeanyoftheobject'scontainers.Forexample,ifyourapplicationhasanApplicationobjectthatcontainsaDocumentobjectthatcontainsaTextobject,thefollowingarevalidobjectexpressions:

Application.Document.TextApplication.TextDocument.TextText

expression

Anycombinationofoperators,constants,literalvalues,functions,andnamesoffields,controls,andpropertiesthatevaluatestoasinglevalue.Youcanuseexpressionsassettingsformanypropertiesandactionarguments,tosetcriteria,ordefinecalculatedfieldsinqueries.

aggregatefunction

Afunction,suchasSum,Count,Avg,andVar,thatyoucanusetocalculatetotals.Inwritingexpressionsandinprogramming,youcanuseSQLaggregatefunctions(includingthefourlistedhere)anddomainaggregatefunctionstodeterminevariousstatistics.

AutoNumberfield

Afielddatatypethatautomaticallystoresauniquenumberforeachrecordasit'saddedtoatable.AnAutoNumberfieldalwaysusestheLongdatatype,andnumbersgeneratedbyanAutoNumberfieldcan'tbemodified.(AlsoknownasaCounterfield.)

GUIDdatatype

GloballyUniqueIdentifier/UniversallyUniqueIdentifier.Auniqueidentificationstringusedwithremoteprocedurecalls.EveryinterfaceandobjectclassusesaGUIDforidentification.AGUIDisa128-bitvalue.Forexample,12345678-1234-1234-1234-123456789ABCisasyntacticallycorrectGUID.TheGUIDsontheclientandservermustmatchfortheclientandservertobind.VendorsofobjectscanrequestthatMicrosoftallocateoneormoresetsof256GUIDsfortheirexclusiveuse.Alternatively,ifyouhaveanetworkcard,youcanrunatoolnamedUuidgen.exe,whichprovidesasetof256GUIDsbasedonthetimeofday,thedate,andauniquenumbercontainedinyournetworkcard.

filter

Asetofcriteriaappliedtorecordsinordertocreateasubsetoftherecords.

instance

Anyoneofasetofobjectssharingthesameclass.Forexample,multipleinstancesofaFormclasssharethesamecodeandareloadedwiththesamecontrolswithwhichtheFormclasswasdesigned.Duringruntime,theindividualpropertiesofcontrolsoneachinstancecanbesettodifferentvalues.

Singledatatype

Afundamentaldatatypethatholdssingle-precisionfloating-pointnumbersinIEEEformat.ASinglevariableisstoredasa32-bit(4-byte)numberranginginvaluefrom-3.402823E38to-1.401298E-45fornegativevalues,from1.401298E-45to3.402823E38forpositivevalues,and0.

class

Theformaldefinitionofanobject.Theclassactsasthetemplatefromwhichaninstanceofanobjectiscreatedatruntime.Theclassdefinesthepropertiesoftheobjectandthemethodsusedtocontroltheobject'sbehavior.

parameter

Anelementcontainingavaluethatyoucanchangetoaffecttheresultsofthequery.Forexample,aqueryreturningdataaboutanemployeemighthaveaparameterfortheemployee'sname.YoucanthenuseoneQueryDefobjecttofinddataaboutanyemployeebysettingtheparametertoaspecificnamebeforerunningthequery.

Booleanexpression

AnexpressionthatevaluatestoeitherTrueorFalse.

BigIntegerdatatype

Adatatypethatstoresasigned,exactnumericvaluewithprecision19(signed)or20(unsigned),scale0(signed:-263≤n≤263-1;unsigned:0≤n≤264-1).

Binarydatatype

Adatatypethatstoresfixed-lengthbinarydata.Themaximumlengthis255bytes.

Chardatatype

Adatatypethatstoresafixed-lengthcharacterstring.ThelengthissetbytheSizeproperty.

Currencydatatype

Adatatypethatisusefulforcalculationsinvolvingmoneyorforfixed-pointcalculationsinwhichaccuracyisextremelyimportant.Thisdatatypeisusedtostorenumberswithupto15digitstotheleftofthedecimalpointand4digitstotheright.BecausetheCurrencydatatypeusesdiscretevaluesforallamounts,binaryround-offisn’tafactorwhencalculatingtotals.

datesandtimes

Datesandtimesarestoredinternallyasdifferentpartsofarealnumber.

ThevaluetotheleftofthedecimalrepresentsadatebetweenDecember30,1899andDecember30,9999,inclusive.NegativevaluesrepresentdatespriortoDecember30,1899.

Thevaluetotherightofthedecimalrepresentsatimebetween0:00:00and23:59:59,inclusive.Middayisrepresentedby.5.

Decimaldatatype

Adatatypethatstoresasigned,exactnumericvaluewithprecisionpandscales(1≤p≤15;0≤s≤p).

Doubledatatype

Afundamentaldatatypethatholdsdouble-precisionfloating-pointnumbersinIEEEformat.ADoublevariableisstoredasa64-bit(8-byte)numberranginginvaluefrom-1.79769313486231E308to-4.94065645841247E-324fornegativevalues,from4.94065645841247E-324to1.79769313486231E308forpositivevalues,and0.

Floatdatatype

Adatatypethatstoresasigned,approximatenumericvaluewithmantissaprecision15(zeroorabsolutevalue10-308to10308).

Numericdatatype

Adatatypethatstoresasigned,exactnumericvaluewithprecisionpandscales(1≤p≤15;0≤s≤p).

Timedatatype

Adatatypethatstoresatimevalue.Thevalueisdependentontheclocksettingofthedatasource.

TimeStampdatatype

AdatatypethatstoresaTimeStamp.Thevalueisdependentontheclocksettingofthedatasource.

VarBinarydatatype

Adatatypethatstoresvariable-lengthbinarydata.Themaximumlengthis255bytes.

proceduralquery

AnSQLstatementthatexecutesastoredprocedure.

unionquery

AnSQL-specificselectquerythatcreatesasnapshot-typeRecordsetobjectcontainingdatafromallspecifiedrecordsintwoormoretableswithanyduplicaterecordsremoved.Toincludetheduplicates,addthekeywordALL.

Forinstance,aunionqueryoftheCustomerstableandtheSupplierstableresultsinasnapshot-typeRecordsetthatcontainsallsuppliersthatarealsocustomers.

clientbatchcursorlibrary

Alibrarythatprovidesclient-sidecursorsupportforODBCDirectdatabaseapplications.Thislibrarysupportsallfourtypesofcursors(keyset,static,dynamic,andforward-only)andprovidesanumberofotherfeaturesincludingtheabilitytodissociateconnectionsandperformoptimisticbatchupdates.

validation

Theprocessofcheckingwhetherentereddatameetscertainconditionsorlimitations.

validationrule

Arulethatsetslimitsorconditionsonwhatcanbeenteredinoneormorefields.ValidationrulescanbesetforaFieldorTableDefobject.Validationrulesarecheckedwhenyouupdatearecordcontainingfieldsrequiringvalidation.Iftheruleisviolated,atrappableerrorresults.

message

Apacketofinformationpassedfromoneapplicationtoanother.

multiuserdatabase

Adatabasethatpermitsmorethanoneusertoaccessandmodifythesamesetofdataatthesametime.Insomecases,theadditional"user"maybeanotherinstanceofyourapplicationoranotherapplicationrunningonyoursystemthataccessesthesamedataassomeotherapplication.