The Microsoft SQL Server Virtual Backup Device Specification · The SQL Server 2005 Virtual Backup...
Transcript of The Microsoft SQL Server Virtual Backup Device Specification · The SQL Server 2005 Virtual Backup...
TheSQLServer2005VirtualBackupDeviceSpecificationInadditiontoitsbuilt-infunctionality,Microsoft®SQLServer™issupportedbyalargenumberofthird-partybackupsolutions.SQLServerprovidesapplicationprogramminginterfaces(APIs)thatenableindependentsoftwarevendorstointegrateSQLServerintotheirproducts.TheseAPIsareengineeredtoprovidemaximumreliabilityandperformance,andsupportthefullrangeofSQLServerbackupandrestorefunctionality,includingthefullrangeofhotandsnapshotbackupcapabilities.
ThisdocumentcontainsthespecificationsforSQLServerapplicationprogramminginterfacesintendedforusebythird-partybackupsoftwarevendors.
NoteIfyouarenotabackupsolutiondeveloper,youprobablydonotneedtorefertothematerialinthisdocument.Formoreinformationonhowyourthird-partybackupsolutionintegrateswithSQLServer,contactyourbackupsolutionvendor.
MethodsforThird-PartyBackupSoftwareDevelopers
Beforereadingthisdocumentation,usersmayfinditusefultorefertothe"SQLWriterinSQLServer2005:AGuideforSQLServerBackupApplicationVendors"articleontheSQLServerTechCenter.
Thevirtualdeviceinterface(VDI)providesthehighestonlinebackupthroughputwithminimaldegradationtothetransactionworkload,aswellasthefastestpossiblerestoretimes.ItenablesthirdpartyvendorstoachievethesameperformancecharacteristicsastheSQLServernativebackup/restore,andmakesthefullrangeofbackup/restorefunctionalityavailable.VDIwasintroducedinSQLServer7.0andissupportedandenhancedinlaterversions.
VDIsupportstwoprimarytypesofbackuptechnologies:
Conventionalonlinebackupswheretheentirecontentsofthebackupsetisreadandtransferredtothebackupmedia.
Snapshotbackupsusingunderlyingsplit-mirrororcopy-on-writetechnology.
ConventionalonlinebackupsdonethroughVDIcantakeadvantageofthefullrangeoffeaturesofbackupandrestoreinSQLServer.Snapshotbackupsarelimitedtofulldatabaseandfile/filegroupbackupsonly.However,snapshotbackupsmayberolledforwardwithconventionaldatabasedifferential,filedifferential,andtransactionlogbackups.
TheremainderofthisdocumentdescribesVDIindetail.
ChangesfromSQLServer2000VDIapplicationswrittenforSQLServer2000shouldworkwithSQLServer2005.Nochangesshouldbenecessary.
Forsnapshotbackupsupport,werecommendtheuseoftheVSSbackupframework.InSQLServer2005,the"sqlwriter"serviceisprovidedastheVSSwriterforSQLServer.
StreamingVDIbackupsautomaticallyincludefull-textcatalogs.Forsnapshotbackup,theapplicationisresponsibleforcopyingthetreeoffileswherethecatalogisstored.Thoselocationscanbefoundbyqueryingsys.database_filesorsys.master_files.
VDIerrormessagesnolongerarewrittentotheVDI.LOGfile.TheWindowsapplicationeventlogisnowused.
VDIsharedmemorysegmentsmaynowbemappedatmanydifferentaddresses.Thishasnoimpactonthefunctionalityofaclient,butshouldhelpinsituationswherevirtualaddresslimitationsrequiredtweakingthe"-g"parameterofsqlservr.exe.Largertotalbufferspaceshouldbeavailable.InpreviousversionsofVDI,asinglecontiguousallocationwasrequired,whichcouldprecludetheuseoflargebufferallocation.
Snapshotrestoreofmasterisnotsupported.Torestoremaster,justtaketheinstanceofflineandcopythefiles.
OnlinerestoreisthedefaultbehaviorinSQLServer2005EnterpriseEdition.However,snapshotrestorecontinuestobeanofflineoperation.
BACKUPTOPIPEhasbeenremoved.
Fileandfilegroupbackupsnowcontainlogdata.Thisistrueforallbackups,notjustVDIbackups.However,forsnapshotbackups,SQLServer2005assumesthatnologhasbeensavedinthesnapshot.
Pagerestoreisnotsupportedwithsnapshotbackups.
DifferencesfromtheOriginalVDISpecificationBeawareofthefollowingdifferencesfromtheoriginalVDIspecification:
Multi-instancesupport.IClientVirtualDevice2supercedesIClientVirtualDevice.Thenewinterfaceisidenticaltotheoriginalexceptfortheadditionofthe'CreateEx'and'OpenInSecondaryEx'methods.Theseextendtheoriginal'Create'and'OpenInSecondary'toallowforaninstancenametobespecified.
RemovablePipesupport.The'VDF_Removable'featureisnowsupportedwiththeVDF_LikePipemodeofoperation.ThisassistsapplicationswhichwishtosupportRESTOREoperationsusingfewerdevicesthanwereoriginallyusedtoBACKUP.
WITHSNAPSHOTsupport.ThisfeatureenablesanapplicationtomakeafastbackupofSQLServerdataandlogfilesinamannerthatallowsintegrationwithtraditionallogbackupsupport.Formoreinformation,seeSNAPSHOTSupport.
IServerVirtualDevice2.Thisdoesnotsubstantiallyaffectclientapplications.Improvementsweremadetotheserverinterface,whichpermitmoreflexiblebufferingdecisionsbytheserver.The'maxIoDepth'and'bufferAreaSize'fieldsintheVDConfigstructurearedeprecated.Theywillcontinuetobefilledinwith"reasonable"values,butapplicationsshouldavoidusingthesefields.
OverviewTheinterfacewillbeavailableonallMicrosoft®SQLServer™platforms,includingMicrosoftWindows®98.TheVDIwasintroducedwithSQLServerversion7.0.ItisnotsupportedbyearlierversionsofSQLServer.SQLServer2000willcontinuetosupportnamedpipes;however,VDIisthepreferredmechanism.SupportfornamedpipesmayberemovedfromSQLServerinafuturerelease.
Thisillustrationshowstherelationshipsamongthevirtualdevice,SQLServer,andthird-partybackupapplications.
ThevirtualdeviceprovidesaninterfacetoSQLServerthatallowsanapplicationtoactasastoragedevice.Theclientapplicationimplementsthevirtualdevice.SQLServerwritestothevirtualdeviceduringbackupandreadsfromthevirtualdeviceduringrestore.
Thevirtualdeviceprovidesaserverinterfacethatacceptsdevice-likecommands,andaclientapplicationinterfacethatexecutesthosecommandsandprovidesnotificationofcommandcompletions.Sharedmemoryisusedforefficientbuffering(thatis,noextradatacopies).AnapplicationshouldperformaswellasSQLServerwithdirectdevicecontrol.TheclientapplicationmustberunningonthesamecomputerasSQLServer.
NoteTheserversideinterfaceisdescribedforinformationpurposesonly.ThisinterfaceisusedexclusivelybytheSQLServerprocess.
Thisillustrationshowsthecommunicationbetweentheclientandtheserverduringtheactive,data-transferphaseofoperation.
Duringbackup,SQLServerwritesastreamofdatatoavirtualdevice.Insomecases,readingandpositioningofthedeviceisnecessary.Duringrestore,itreadsastreamofdatafromavirtualdevice.Thestreamreadmustbeidenticaltothestreamwritten.
SQLServerallocatesabuffer,andthenreadsorwritesdatatoavirtualdevicebyissuingacommand.Theclientperformstherequestedactionandindicatescompletionofthecommand.Duringthecommandprocessing,theclienthasexclusivecontrolofthebufferreferencedbythecommand.Althoughitiscriticalthattheclientpreservesthestreamintheorderitwaswritten,commandcompletionsonasinglevirtualdevicemayoccurinanyorder.Thisfacilitatestheclient'suseofasynchronousinput/output(I/O)operation.Forexample,theclientcanscheduleI/Oforonerequest,andtheninitiateasecondrequestwithoutwaitingforcompletionofthefirstrequest.
CompletioneventsarepostedtoSQLServerbymeansofacompletionagent.
Ifmultipledevicesarespecified,SQLServerreadsorwritesmultiplestreamsinparallel,oneperdevice.Streamsareindependentintermsofdatacontent,butatcertaintimesduringthebackuporrestoreoperation,SQLServermustsynchronizethestreams.ItispossibleforaGetCommandononevirtualdevicetoblockwhileSQLServerwaitsforactivitytocompleteonanothervirtualdevice.Whenthissynchronizationoccurscanvaryfromversiontoversion.
Multiplevirtualdevicesaretypicallyusedinsituationswhentheclientisbackinguptoorrestoringfrommorethanonerealdevice.Ifthenumberofvirtualdevicesmatchesthenumberofphysicalbackupdevices,theclientneednotperformanymultiplexingofthestreams.Theclienttypicallyhasonethreadorprocessforeachvirtualdevice.
ServerStateDiagramThisillustrationshowstheserverviewofthelifecycleofthevirtualdeviceset.
ForthefunctionsOpenDeviceandExecuteCompletionAgent,theactivestateisnotentereduntilalldevicesareopenedandthecompletionagentisrunning.IfCloseisinvokedfromanystateexceptTerminated,thefunctionimplicitlyperformsSignalAbortprocessingtomovetoanAbortstate.ItthenimmediatelytransitionstotheDoesNotExiststate.
ClientTransitionsThesetablesdisplaythefullsetofclienttransitions.TheyalsolistthefunctionsassociatedwiththeIClientVirtualDeviceandtheIClientVirtualDeviceSet2,thepossiblestateswhenthefunctionscanbeinvoked,andthestatuscodetobeexpectedwhenafunctionisinvoked.AlistofstatuscodesandtheirdescriptionsfollowstheClientTransitionstables.Iftheinvocationofthefunctionresultsinastatechange,thenthenextstateisgiven,identifiedbythesymbol—>.Whenallresourcesarereleased,theVDInolongerexistsandatransitiontotheDoesNotExist(DNE)stateoccurs.
FunctionsDoesNotExistState ConfigurableState InitializingState
Create,CreateEx NOERROR—>Configurable
VD_E_PROTOCOLVD_E_PROTOCOL
GetConfiguration VD_E_PROTOCOLNOERROR->Initializing
NOERROR
OpenDevice VD_E_PROTOCOLVD_E_PROTOCOLNOERROR®Active
GetCommand VD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLCompleteCommandVD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLSignalAbort VD_E_PROTOCOLNOERROR—>
AbortNOERROR—>Abort
Close VD_E_PROTOCOLNOERROR—>DNE
NOERROR—>DNE
Functions ActiveStateNormallyTerminatedState AbortState
Create VD_E_PROTOCOL VD_E_PROTOCOLVD_E_PROTOCOLGetConfiguration NOERROR NOERROR VD_E_ABORTOpenDevice VD_E_PROTOCOL VD_E_PROTOCOLVD_E_ABORTGetCommand NOERRORor
VD_E_CLOSE->NormallyTerminated
VD_E_PROTOCOLVD_E_ABORT
CompleteCommandNOERROR VD_E_PROTOCOLVD_E_ABORTSignalAbort NOERROR—>
AbortNOERROR—>Abort
NOERROR
Close NOERROR—>DNE
NOERROR—>DNE
NOERROR—>DNE
StatusCode DescriptionNOERROR Thefunctionsucceeded.VD_E_PROTOCOLAprotocolerrorhasoccurred.Thefunctioncannotbe
calledinthisstate.VD_E_ABORT TheVDIisintheAbortstate.OnlyCloseisuseful
whileintheAbortstate.VD_E_CLOSE WhentheserverissuesaCloseDevicecall,theclient
willreceiveaVD_E_CLOSEcodefromGetCommand.WhenthelastdeviceinthesetreturnsaVD_E_CLOSE,thevirtualdevicesetenterstheNormallyTerminatedstate.
ServerTransitionsThesetablesdisplaythefullsetofservertransitions.ThetablesincludethefunctionsassociatedwiththeIServerVirtualDeviceandtheIServerVirtualDeviceSet2,thepossiblestateswhenthefunctionscanbeinvoked,andthestatuscodetobeexpectedwhenafunctionisinvoked.Iftheinvocationofthefunctionresultsinastatechange,thenthenextstateisgiven,identifiedbythesymbol—>.Whenallresourcesarereleased,theVDInolongerexistsandatransitiontotheDoesNotExist(DNE)stateoccurs.
FunctionsDoesNotExistState ConfigurableState InitializingState
Open NOERROR->Connected
VD_E_PROTOCOLVD_E_PROTOCOL
GetConfiguration VD_E_PROTOCOLNOERROR NOERRORBeginConfiguration VD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLRequestBuffers VD_E_PROTOCOLNOERROR NOERRORQueryAvailableBuffers VD_E_PROTOCOLNOERROR NOERROREndConfiguration VD_E_PROTOCOLNOERROR-
>InitializeVD_E_PROTOCOL
OpenDevice VD_E_PROTOCOLVD_E_PROTOCOLNOERROR—>Active
ExecuteCompletionAgentVD_E_PROTOCOLVD_E_PROTOCOLNOERROR—>Active
AllocateBuffer VD_E_PROTOCOLVD_E_PROTOCOLNOERRORFreeBuffer VD_E_PROTOCOLVD_E_PROTOCOLNOERRORSendCommand VD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLCloseDevice VD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLSignalAbort VD_E_PROTOCOLNOERROR—>
AbortNOERROR—>Abort
Close VD_E_PROTOCOLNOERROR—>DNE
NOERROR—>DNE
Normally Abnormally
Functions ActiveState TerminatedState TerminatedStateOpen VD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLGetConfiguration NOERROR NOERROR VD_E_ABORTBeginConfiguration VD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLRequestBuffers NOERROR VD_E_PROTOCOLVD_E_PROTOCOLQueryAvailableBuffers NOERROR VD_E_PROTOCOLVD_E_PROTOCOLEndConfiguration VD_E_PROTOCOLVD_E_PROTOCOLVD_E_PROTOCOLOpenDevice VD_E_PROTOCOLVD_E_PROTOCOLVD_E_ABORTExecuteCompletionAgentVD_E_PROTOCOLVD_E_PROTOCOLVD_E_ABORTAllocateBuffer NOERROR NOERROR VD_E_ABORTFreeBuffer NOERROR NOERROR VD_E_ABORTSendCommand NOERROR VD_E_PROTOCOLVD_E_ABORTCloseDevice NOERROR—>
TerminatedNOERROR VD_E_ABORT
SignalAbort NOERROR—>Abort
NOERROR—>Abort
NOERROR
Close NOERROR—>DNE
NOERROR—>DNE
NOERROR—>DNE
Functions ConnectedStateOpen VD_E_PROTOCOLGetConfiguration NOERRORBeginConfiguration NOERROR->ConfigurableRequestBuffers VD_E_PROTOCOLQueryAvailableBuffers VD_E_PROTOCOLEndConfiguration VD_E_PROTOCOLOpenDevice VD_E_PROTOCOLExecuteCompletionAgent VD_E_PROTOCOLAllocateBuffer VD_E_PROTOCOLFreeBuffer NOERRORSendCommand NOERRORCloseDevice NOERROR—>Terminated
InitializationThevirtualdeviceinterfaceisimplementedasasetofComponentObjectModel(COM)interfaces.AnapplicationgainsaccesstotheinterfacebystandardCOMmethods.First,theapplicationmustinitializetheCOMenvironmentformultithreading:
CoInitializeEx(NULL,COINIT_MULTITHREADED);
OnceCOMisinitialized,thentheapplicationcreatesaninstanceofaninterface:
CoCreateInstance(CLSID_MSSQL_ClientVirtualDeviceSet,NULL,CLSCTX_INPROC_SERVER,IID_IClientVirtualDeviceSet2,&vds))
Samplecodeaccompaniesthisdocumentation.Browsingoverthiscodemayhelpyouunderstandthedetailscoveredinthisdocument.Ifyoudon'thavethesamplecode,youcandownloaditfromMicrosoft.com.
TheclientusesIClientVirtualDeviceSet2::CreateExtogiveauniquesystem-widenametothevirtualdevicesetandestablishsomebasicconfigurationinformation,suchasthenumberofdevices.TheclientthenissuesaBACKUPorRESTOREcommandthroughODBCoranalternative.However,ratherthanspecifyingdiskortapethekeywordVIRTUAL_DEVICEshouldbeused.Ifmorethanonedeviceistobeused,thenthecommandmusthaveoneVIRTUAL_DEVICEclauseforeachdevice.ThefirstVIRTUAL_DEVICEclausemustspecifytheexactnamegivenontheIClientVirtualDeviceSet2::CreateExinvocation.Subsequentclausesnameeachadditionalvirtualdevicewithintheset.Theonlyrestrictiononthesenamesisthattheybeuniquewithintheset.Forexample,ifthreedeviceswerespecified,aBACKUPcommandmightlooklike:
BACKUPDATABASEMYDBTOVIRTUAL_DEVICE='{0D0F5BA0-B21A-4519-A961-A6E2292A17CA}',VIRTUAL_DEVICE='dev2',VIRTUAL_DEVICE='dev3'
Toensureuniqueness,itisrecommendedthataGUIDbeusedasthenameofthevirtualdeviceset.Thesamplecodeusesthisapproach.However,clientsarefreetouseanyschemetheywish.
NoteUsuallythesamenumberofdevicesisusedduringbothRESTOREandBACKUP.However,forremovablemedia,itispossibletousefewerdevices.Inthatcase,aftereachdatastreamhasbeenread,SQLServerrequestsanew,unprocesseddatastreambyissuingamountrequest.Formoreinformationaboutmediasets,backupsets,andmediafamilies,seeMicrosoftSQLServerBooksOnline.
ConfigurationAtthispointMicrosoft®SQLServer™isexecutinginparallelwiththeclient.ThevirtualdevicesetisintheConfigurablestateuntiltheservercompletestheconfigurationofthevirtualdevice.TheclientinvokesIClientVirtualDeviceSet2::GetConfigurationtowaitforthisevent.Meanwhile,SQLServerbeginsexecutionoftheutilitycommandandinvokesIServerVirtualDeviceSet2::OpenusingthenameprovidedbythefirstVIRTUAL_DEVICEclause.SQLServerinspectsthevirtualdeviceconfigurationbyusingIServerVirtualDeviceSet2::GetConfiguration.Iftheconfigurationissatisfactory,theserverproceedstoinvokeIServerVirtualDeviceSet2::BeginConfiguration,RequestBuffersandCompleteConfigurationtocompletetheconfiguration.Theserverdecidesonthetotalbufferspacerequirement,deviceblocksize,andmaximumtransfersizebyusingdefaultsorinputfromtheBUFFERCOUNT,BLOCKSIZE,andMAXTRANSFERSIZEoptionsofthebackupcommand.TheseoptionsarespecifiedaspartoftheWITHclause.Forexample:
BACKUPDATABASEMYDBTOVIRTUAL_DEVICE='{0D0F5BA0-B21A-4519-A961-A6E2292A17CA}'WITHBLOCKSIZE=4096,BUFFERCOUNT=20,MAXTRANSFERSIZE=524288.
BLOCKSIZEisthesize,inbytes,thatisusedasthedeviceBLOCKSIZE.Alldatatransfersareinintegralmultiplesofthisvalue.Valuesmustbeapowerof2between512bytesand64kilobytes(KB)inclusive.Ifthisoptionisnotspecifiedwiththecommand,thenadefaultnumberof512bytesisused.
BUFFERCOUNTisthetotalnumberofbuffers(ofsizeMAXTRANSFERSIZE)thatisusedbytheBACKUPorRESTOREoperation.Whenmorethanonevirtualdeviceisused,thebuffersareusedasneededandarenotassociatedwithanygivendevice.NotethatsomesmallerbuffersmaybeusedbySQLServertohandlethesmallmetadatatransfers.ThesesmallbuffersarenotincludedintheBUFFERCOUNT.
MAXTRANSFERSIZEisthesize,inbytes,ofthemaximuminputoroutputrequestwhichisissuedbySQLServertothedevice.TheMAXTRANSFERSIZEmustbeamultipleof64KB.Therangeisfrom64KB
through4megabytes(MB).Ifthisoptionisnotspecifiedwiththecommand,thenadefaultof64KBisused.
Whentheconfigurationiscomplete,thevirtualdevicesetisintheInitializingstateuntilalldevicesareopenbetweentheclientandserver,andthecompletionagentisstarted.TheclientusesIClientVirtualDeviceSet2::OpenDevicetoobtaintheIClientVirtualDeviceinterfacetoeachofthevirtualdevices.Atthispoint,thevirtualdevicesetisintheActivestateandalldevicesarereadytobeginwork.
ActiveAsMicrosoft®SQLServer™executestheutilitycommand,itwillallocateorfreebuffersasnecessarybyaccessingthesinglesharedbufferpool.WheneverSQLServerneedstoperformI/Oagainstoneofitsdatastreams,itbuildsacommandandsendsittotheappropriatedevice.Thecommandspecifiestheactiontoperform.Whendatatransferisinvolved,asharedbufferaccessibleintheclientprocessisidentified.Theclientloops,invokingIClientVirtualDevice::GetCommandtoretrieveasequenceofcommands.Theclientexecutesthecommand,andwhenitiscomplete,invokesIClientVirtualDevice::CompleteCommandtonotifytheserver.ThispromptsthecompletionagentinSQLServertocallbacktoaSQLServerfunctionassociatedwiththatcommand.
ThevirtualdeviceisresponsibleforensuringthattheexactsequenceofdatawrittenduringBACKUPisretrievedduringRESTORE.DuringRESTORE,thesameBLOCKSIZEmustbeusedasthatusedduringtheBACKUP.Generally,thesameMAXTRANSFERSIZEshouldalsobeused.However,ifthebackupdoesnotcontainfull-textdata,thenanyMAXTRANSFERSIZEcanbespecifiedduringtheRESTORE.Regardlessofthesesettings,theRESTOREcommandmayrequestdatatobereadinanysizebetweenBLOCKSIZEandMAXTRANSFERSIZE(inmultiplesofBLOCKSIZE).ThereisnoguaranteethattheRESTOREcommandwillrequestdatainthesamesequenceofsizesaswereusedduringtheBACKUP.
IfaclientisusingasynchronousI/O,itmustensurethatamechanismexiststocompleteoutstandingrequestswhenitisblockedinaIClientVirtualDevice::GetCommandcall.BecauseGetCommandwaitsinanAlertablestate,thatuseofAlertableI/Oisonesuchtechnique.Inthiscase,theoperatingsystemcallsbacktoacompletionroutinesetupbytheclient.
NormalTerminationWhentheoperationiscomplete,Microsoft®SQLServer™invokesIServerVirtualDevice::CloseDeviceforeachdevice.ThisresultsintheIClientVirtualDevice::GetCommandreturningaVD_E_CLOSEstatuscode.TheclientrespondsbyterminatingitsGetCommandloop.
Afteralldevicesareclosed,thecompletionagentisterminatedandthevirtualdevicesetenterstheNormallyTerminatedstate.TheclientinvokesIClientVirtualDeviceSet2::CloseandtheserverinvokesIServerVirtualDeviceSet2::Closetoreleaseanyresourcesusedbythevirtualdeviceset.
Theclientdoesnotneedtowaitforthecompletionagenttoterminate.TheclientcanissueIClientVirtualDeviceSet2::CloseassoonasallofthedeviceshavereceivedaClosestatuscode.
TheserverispermittedtocallIServerVirtualDeviceSet2::Closewithoutfreeinganyallocatedbuffers.TheClosefunctionwillfreethem.ItispermissibletoinvokeFreeBufferaspartofthecleanupprocessingintheserver.
ThebackuphistorywrittenforVDIbackupsisthesameasfornon-VDIbackups.Theonlydistinctionisthatmsdb..backupmediafamily.device_typeissetto7.
Noteon"sp_addumpdevice":VDIdevicesshouldnotbeaddedasbackupdevices.ThisisnotpreventedinSQLServer2005,butisdeprecated.SinceVDIdevicesshoulduseuniquenames,itdoesnotmakesensetoaddpersistentnamestothecatalog.GUIDsarerecommendedfornames.
AbnormalTerminationWhenafatalerroroccurs,eachsideoftheVirtualDeviceInterfaceisprovidedwithafunctiontosignalthatabnormalterminationshouldoccur.TheclientfunctionisIClientVirtualDeviceSet2::SignalAbort.TheserverfunctionisIServerVirtualDeviceSet2::SignalAbort.WhenSQLServerusesSignalAborttoinitiatetermination,theBACKUPorRESTOREcommandcompleteswithoneormoremessagesexplainingthereasonfortheabnormaltermination.Itisrecommendedthattheclientlikewiselogerrors.WheneithertheclientorserverinvokestheSignalAbortinterface,thevirtualdevicesetenterstheAbortstate.Asaresult,thisdocumentdoesnotalwaysspecifywhatcausedtheSignalAbortinvocation.
TheuseofSignalAbortisnotalwaysnecessaryasameanstoterminateaBACKUPorRESTOREcommand.IftheserverreceivesanerrorcodefromIClientVirtualDevice::CompleteCommandorfromanoperationinternaltotheserver,itwillusuallyterminatethecommandbywaitingforoutstandingvirtualdevicecommandstocomplete,andthenclosingthevirtualdevice(s).
WhenSignalAbortmustbeused,itperformsafail-fastprotocol,effectivelydisconnectingtheclientandserver.In-progresscommandshaveabortedcompletionnotificationssenttoSQLServerandtheclientreceivesabortingerrorcodeswhenattemptingtogetorcompletecommands.
ActionstriggeredbySignalAbortvarywiththestateofthevirtualdevice.Actionsandeffectsinclude:
Anyin-progressfunctionsterminate,returningwithaVD_E_ABORTresult.ExamplesincludeGetCommandandGetConfiguration.
NonewSendCommandsareaccepted.
NonewcommandsaredeliveredbyGetCommand.
NonewbuffersarereturnedfromGetBuffer.
BuffersalreadyinthecontroloftheclientandserverremainintheircontroluntileachinvokesitsVirtualDeviceSet::Closefunction.
AnyoutstandingcommandsareautomaticallycompletedwithanERROR_OPERATION_ABORTEDcompletioncode.Thenotificationagentcallsthecallbackfunctionsasiftheclienthadperformedthecompletion.
Anycommandcompletionsattemptedbytheclientareignored.
Theserver'scompletionagentreturnsfromitsExecuteCompletionAgentcall.
AfterSignalAborthasbeenusedandafteruseofanyresourcesisended,theonlyrequirementontheserverandclientistoinvokeIServerVirtualDeviceSet2::CloseandIClientVirtualDeviceSet2::Close.Forexample,ifanI/Oisbeingperformedwithabufferwhentheabortingstatusisnoticed,theI/OmustbecancelledorcompletedbeforetheCloseinterfaceisinvoked.
IServerVirtualDeviceSet2::FreeBufferandIServerVirtualDevice::CloseDevicedonotneedtobeinvokedafterthevirtualdevicesetisinanAbortstate.Iftheyareinvoked,theonlyactionFreeBufferorCloseDeviceperformsistoreturnVD_E_ABORT.
IfeitherserverorclientexitswithoutinvokingtheClosemethod,theWIN32®synchronizationprimitiveswillalerttheinterface.SignalAbortprocessingisinternallytriggeredandVD_E_ABORTisreturnedbytheinterface.
ProcessModelTheprocessmodelusedbyMicrosoft®SQLServer™isasingleprocesswithmultiplethreads.WhenprocessingaBACKUPorRESTOREcommand,thereisonethreadforeachvirtualdevice.
Ontheclientside,severalprocessmodelsarepossible.Thisillustrationshowsthesimplestmodel,whichisoneprocess,withonethreadpervirtualdevice.
Noticethatthe<x>intheprecedingillustrationdenotesthatserverorclientisintended.Forexample,IServerVirtualDeviceSet2isusedbytheserverprocesswhileIClientVirtualDeviceSet2isusedbytheclientprocess.TheI<x>VirtualDeviceSetinterfacecanbeusedbyanythreadintheprocess.TheI<x>VirtualDeviceinterfaceisintendedtobeusedbyasinglethreadtocontroloneofthevirtualdevicesinthevirtualdeviceset.
Someusersmightrequireamultiple-processarchitecture.Forthatcase,aspecialmethodisprovidedtoopenthevirtualdevicesetinthesecondaryclient:IClientVirtualDeviceSet2::OpenInSecondary.Inthismodel,ratherthanthreadsintheclientprocesshandlingeachvirtualdevice,secondaryprocessesareemployed.Theprimaryprocessisresponsibleforcreatingthevirtualdeviceset,configuringit,andcommunicatingwiththesecondaryprocesses.ThesecondaryprocessesgainaccesstothevirtualdevicesetbyemployingtheOpenInSecondarymethod.ThesecondaryprocessescanthenuseOpenDevice
toaccessthevirtualdevicesasiftheywerethreadsintheprimaryprocess.Applicationschoosingthismodelareresponsiblefordetectingabnormalterminationofthesecondaryclients.TheVDIwillonlydetecttheabnormalterminationoftheSQLServerprocessortheprimaryclient.Thefollowingdrawingillustratesthemultipleprocessmodel,withonethreadforeachvirtualdevice.
SecurityThesystemobjectsusedtoimplementthevirtualdevicesetaresecuredwithanaccesscontrollist.Thislistpermitsaccesstoallprocessesrunningundertheaccountusedbytheprimaryclient.AccessisalsopermittedtoprocessesrunningundertheaccountusedbyMicrosoft®SQLServer™,asrecordedinthesystemservicesconfiguration.
TheserverconnectionforSQLServerthatisusedtoissuetheBACKUPorRESTOREcommandsmustbeloggedinwiththesysadminfixedserverrole.Formoreinformation,seeMicrosoftSQLServerBooksOnline.
TheCreateEx(andCreate)callsmodifythesecurityDACLontheprocesshandleintheclientprocess.BecauseofthisanyothermodificationoftheprocesshandlemustbeserializedwithinvocationofCreateEx.
ClientFunctionsThischaptercontainsdescriptionsofeachoftheclientfunctions.Thedescriptionsincludethefollowinginformation:
Functionpurpose
Functionsyntax
Parameterlist
Returnvalues
Remarks
IClientVirtualDeviceSet2::CreateEx
Purpose Thisfunctioncreatesthevirtualdeviceset.Syntax HRESULTIClientVirtualDeviceSet2::CreateEx(
LPCWSTRlpInstanceName,
LPCWSTRlpName,
VDConfig*pCfg
);
Parameters Argument Explanation lpInstanceName Thisstringidentifiesthe
SQLServerinstancetowhichtheSQLcommandwillbesent.
lpName Thisidentifiesthevirtualdeviceset.TherulesfornamesusedbyCreateFileMapping()mustbefollowed.Anycharacterexceptbackslash(\)maybeused.Thisisawide-characterUnicodestring.Prefixingthestringwiththeuser'sproductorcompanynameanddatabasenameisrecommended.
pCfg Thisistheconfigurationforthevirtualdeviceset.Formoreinformation,seeConfiguration.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_NOTSUPPORTEDOneormoreofthe
fieldsintheconfigurationwasinvalidorotherwiseunsupported.
VD_E_PROTOCOL Thevirtualdevicesethasbeencreated.
Remarks TheCreateExmethodshouldbecalledonlyonceperBACKUPorRESTOREoperation.AfterinvokingtheClosemethod,theclientcanreusetheinterfacetocreateanothervirtualdeviceset.
TheinstancenamemustidentifytheinstancetowhichtheTransact-SQLisissued.NULLidentifiesthedefaultinstance.No"machineName\"prefixisaccepted.
TheCreateEx(andCreate)callswillmodifythesecurityDACLontheprocesshandleintheclientprocess.Becauseofthis,anyothermodificationoftheprocesshandlemustbeserializedwithinvocationofCreateEx.CreateExwillserializewithothercallstoCreateEx,butisunabletoserializewithexternalprocessing.AccessisgrantedtotheaccountrunningtheSQLServerservice.
TheCreateExmethodsupersedestheCreatemethoddefinedintheoriginalIClientVirtualDeviceSet.TheoriginalCreatemethodisdeprecatedandshouldnotbeusedinfuturedevelopment.TheoriginalCreatemethodimplementsaformofinstancenamesupportwiththe_VIRTUAL_SERVER_NAME_environmentvariable.Ifthatvariableissetintheenvironment,thentheCreatemethodinternallycallsCreateEx,passingthevalueof
IClientVirtualDeviceSet2::GetConfiguration
Purpose Thisfunctionisusedtowaitfortheservertoconfigurethevirtualdeviceset.
Syntax HRESULTIClientVirtualDeviceSet2::GetConfiguration(
DWORDdwTimeOut,
VDConfig*pCfg
);
Parameters Argument Explanation DwTimeOut Thisisthetime-outin
milliseconds.UseINFINITEtopreventtime-out.
pCfg Uponsuccessfulexecution,thiscontainstheconfigurationselectedbytheserver.Formoreinformation,seeConfiguration.
ReturnValues Argument Explanation NOERROR Theconfigurationwas
returned. VD_E_ABORT SignalAbortwasinvoked. VD_E_TIMEOUT Thefunctiontimedout.
Remarks
ThisfunctionblocksinanAlertablestate.Aftersuccessfulinvocation,thedevicesinthevirtualdevicesetmaybeopened.
IClientVirtualDeviceSet2::OpenDevice
Purpose Thisfunctionopensoneofthedevicesinthevirtualdeviceset.
Syntax HRESULTIClientVirtualDeviceSet2::OpenDevice(
LPCWSTRlpName,
IClientVirtualDevice**ppVirtualDevice
);
Parameters Argument Explanation lpName Thisidentifiesthevirtualdevice. ppVirtualDevice Whenthefunctionsucceeds,an
interfacepointertothevirtualdeviceisreturned.ThisinterfaceisusedfortheGetCommandandCompleteCommand.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_ABORT Abortwasrequested. VD_E_OPEN Alldevicesareopen. VD_E_PROTOCOL Thesetisnotintheinitializing
stateorthisparticulardeviceisalreadyopen.
VD_E_INVALID Thedevicenameisinvalid.Itisnotoneofthenamesknowntocomprisetheset.
Remarks VD_E_OPENmaybereturnedwithoutproblem.TheclientmaycallOpenDevicebymeansofaloopuntilthiscodeisreturned.
Ifmorethanonedeviceisconfigured(forexample,ndevices),thevirtualdevicesetwillreturnnunique
deviceinterfaces.Thefirstdevicehasthesamenameasthevirtualdeviceset.OtherdevicesarenamedasspecifiedwiththeVIRTUAL_DEVICEclausesoftheBACKUP/RESTOREstatement.
TheGetConfigurationfunctioncanbeusedtowaituntilthedevicescanbeopened.
Ifthisfunctiondoesnotsucceed,thenanullvalueisreturnedthroughtheppVirtualDevice.
IClientVirtualDevice::GetCommand
Purpose Thisfunctionisusedtoobtainthenextcommandqueuedtoadevice.Whenrequested,thisfunctionwaitsforthenextcommand.
Syntax HRESULTIClientVirtualDevice::GetCommand(
DWORDdwTimeOut,
VDC_Command**constppCmd
);
Parameters Argument Explanation ppCmd Whenacommandissuccessfully
returned,theparameterreturnstheaddressofacommandtoexecute.Thememoryreturnedisread-only.Whenthecommandiscompleted,thispointerispassedtotheCompleteCommandroutine.Formoreinformationabouteachcommand,seeCommands.
dwTimeOut Thisisthetimetowait,inmilliseconds.UseINFINTEtowaitindefinitely.Use0topollforacommand.VD_E_TIMEOUTisreturnedifnocommandiscurrentlyavailable.Ifthetime-outoccurs,theclientdecidesthenextaction.
ReturnValues Argument Explanation NOERROR Acommandwasfetched. VD_E_CLOSE Thedevicehasbeenclosedbythe
server. VD_E_TIMEOUT Nocommandwasavailableandthe
time-outexpired. VD_E_ABORT Eithertheclientortheserverhasused
theSignalAborttoforceashutdown.Remarks WhenVD_E_CLOSEisreturned,
SQLServerhasclosedthedevice.Thisispartofthenormalshutdown.Afteralldeviceshavebeenclosed,theclientinvokesIClientVirtualDeviceSet2::Closetoclosethevirtualdeviceset.Whenthisroutinemustblocktowaitforacommand,thethreadisleftinanAlertablecondition.
IClientVirtualDevice::CompleteCommand
Purpose ThisfunctionisusedtonotifySQLServerthatacommandhasfinished.Completioninformationappropriateforthecommandshouldbereturned.Formoreinformation,seeCommands.
Syntax HRESULTIClientVirtualDevice::CompleteCommand(
VDC_Command*constpCmd,
UINT32dwCompletionCode,
UINT32dwBytesTransferred,
UINT64dwlPosition
);
Parameters Argument Explanation pCmd Thisistheaddressofacommand
previouslyreturnedfromIClientVirtualDevice::GetCommand.
dwCompletionCode ThisisaWIN32statuscodethatindicatesthecompletionstatus.Thisparametermustbereturnedforallcommands.Thecodereturnedshouldbeappropriatetothecommandbeingperformed.ERROR_SUCCESSisusedinallcasestodenoteasuccessfullyexecutedcommand.Forthecompletelistofpossiblecodes,seethefile,Winerror.h.AlistoftypicalstatuscodesforeachcommandappearsinCommands.
dwBytesTransferred Thisisthenumberofsuccessfullytransferredbytes.Thisisreturned
onlyfordatatransfercommandsReadandWrite.
dwlPosition ThisisaresponsetotheGetPositioncommandonly.
ReturnValues Argument Explanation NOERROR Thecompletionwascorrectlynoted. VD_E_INVALID pCmdwasnotanactivecommand. VD_E_ABORT Abortwassignaled. VD_E_PROTOCOL Thedeviceisnotopen.Remarks None
IClientVirtualDeviceSet2::SignalAbort
Purpose Thisfunctionisusedtosignalthatanabnormalterminationshouldoccur.
Syntax HRESULTIClientVirtualDeviceSet2::SignalAbort();
Parameters Argument Explanation None NotapplicableReturnValues Argument Explanation NOERROR TheAbortnotificationwas
successfullyposted.Remarks Atanytime,theclientmaychoosetoaborttheBACKUPor
RESTOREoperation.Thisroutinesignalsthatalloperationsshouldcease.ThestateoftheoverallvirtualdevicesetenterstheAbortstate.Nofurthercommandsarereturnedonanydevices.Alluncompletedcommandsareautomaticallycompleted,returningERROR_OPERATION_ABORTEDasacompletioncode.TheclientshouldcallIClientVirtualDeviceSet2::Closeafterithassafelyterminatedanyoutstandinguseofbuffersprovidedtotheclient.Formoreinformation,seeAbnormalTermination.
IClientVirtualDeviceSet2::Close
Purpose ThisfunctionclosesthevirtualdevicesetcreatedbyIClientVirtualDeviceSet2::Create.Itresultsinthereleaseofallresourcesassociatedwiththevirtualdeviceset.
Syntax HRESULTIClientVirtualDeviceSet2::Close();Parameters Argument Explanation None NotapplicableReturnValues Argument Explanation NOERROR Thisisreturnedwhenthevirtual
devicesetwassuccessfullyclosed. VD_E_PROTOCOL Noactionwastakenbecausethe
virtualdevicesetwasnotopen. VD_E_OPEN Deviceswerestillopen.Remarks TheinvocationofCloseisadeclarationbytheclientthatall
resourcesusedbythevirtualdevicesetshouldbereleased.TheclientmustensurethatallactivityinvolvingdatabuffersandvirtualdevicesisterminatedbeforeinvokingClose.AllvirtualdeviceinterfacesreturnedbyOpenDeviceareinvalidatedbyClose.
TheclientispermittedtoissueaCreatecallonthevirtualdevicesetinterfaceaftertheClosecallreturns.SuchacallwouldcreateanewvirtualdevicesetforasubsequentBACKUPorRESTOREoperation.
IfCloseiscalledwhenoneormorevirtualdevicesarestillopen,VD_E_OPENisreturned.Inthiscase,SignalAbortisinternallytriggered,toensureapropershutdownifpossible.VDIresourcesarereleased.TheclientshouldwaitforaVD_E_CLOSEindicationoneachdevicebeforeinvokingIClientVirtualDeviceSet2::Close.IftheclientknowsthatthevirtualdevicesetisalreadyinanAbnormallyTerminatedstate,thenitshouldnotexpectaVD_E_CLOSEindication
fromGetCommand,andmayinvokeIClientVirtualDeviceSet2::Closeassoonasactivityonthesharedbuffersisterminated.
Formoreinformation,seeAbnormalTermination.
IClientVirtualDeviceSet2::OpenInSecondaryEx
Purpose Thisfunctionopensthevirtualdevicesetinasecondaryclient.TheprimaryclientmusthavealreadyusedCreateExandGetConfigurationtosetupthevirtualdeviceset.
Syntax HRESULTIClientVirtualDeviceSet2::OpenInSecondaryEx(
LPCWSTRlpInstanceName,
LPCWSTRlpSetName
);
Parameters Argument Explanation lpInstanceName ThisstringidentifiestheSQLServer
instancetowhichtheSQLcommandwillbesent.
lpSetName Thisidentifiestheset.Thisnameiscase-sensitiveandmustmatchthenameusedbytheprimaryclientwhenitinvokedIClientVirtualDeviceSet2::Create.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_PROTOCOL Thevirtualdevicesethasbeen
openedorthevirtualdevicesetisnotreadytoacceptopenrequestsfromsecondaryclients.
VD_E_ABORT Theoperationisbeingaborted.Remarks Whenusingamultipleprocessmodel,theprimaryclientis
responsiblefordetectingnormalandabnormalterminationofsecondaryclients.TheinstancenamemustidentifytheinstancetowhichtheT-SQLisissued.NULLidentifiesthedefaultinstance.No
"machineName\"prefixisaccepted.
OpenInSecondaryExsupersedestheoriginalIClientVirtualDeviceSet::OpenInSecondarythatwasdefinedintheoriginalSQLServerversion7.0interface.NewdevelopmentshoulduseOpenInSecondaryEx.
IClientVirtualDeviceSet2::GetBufferHandle
Purpose SomeapplicationsmayrequiremorethanoneprocesstooperateonthebuffersreturnedbyIClientVirtualDevice2::GetCommand.Insuchcases,theprocessthatreceivesthecommandcanuseGetBufferHandletoobtainaprocessindependenthandlethatidentifiesthebuffer.ThishandlecanthenbecommunicatedtoanyotherprocessthatalsohasthesameVirtualDeviceSetopen.ThatprocesswouldthenuseIClientVirtualDeviceSet2::MapBufferHandletoobtaintheaddressofthebuffer.Theaddresswilllikelybeadifferentaddressthaninitspartnerbecauseeachprocessmaybemappingbuffersatdifferentaddresses.
Syntax HRESULTIClientVirtualDeviceSet2::GetBufferHandle(
BYTE*pBuffer,
DWORD*pBufferHandle
);
Parameters Argument Explanation pBuffer Thisistheaddressofabuffer
obtainedfromaReadorWritecommand.
pBufferHandle Auniqueidentifierforthebufferisreturned.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_PROTOCOL Thevirtualdevicesetisnotcurrently
open. VD_E_INVALID ThepBufferisnotavalidaddress.Remarks TheprocessthatinvokestheGetBufferHandlefunctionis
IClientVirtualDeviceSet2::MapBufferHandle
Purpose Thisfunctionisusedtoobtainavalidbufferaddressfromabufferhandleobtainedfromsomeotherprocess.
Syntax HRESULTIClientVirtualDeviceSet2::MapBufferHandle(
DWORDdwBuffer,
BYTE**ppBuffer
);
ParametersArgument Explanation dwBuffer Thisisthehandlereturnedby
IClientVirtualDeviceSet2::GetBufferHandle. ppBuffer Thisistheaddressofthebufferthatisvalid
inthecurrentprocess.ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_PROTOCOLThevirtualdevicesetisnotcurrentlyopen. VD_E_INVALID TheppBufferisaninvalidhandle.Remarks Caremustbetakentocommunicatethehandlescorrectly.
Handlesarelocaltoasinglevirtualdeviceset.Thepartnerprocessessharingahandlemustensurethatbufferhandlesareusedonlywithinthescopeofthevirtualdevicesetfromwhichthebufferwasoriginallyobtained.
ServerFunctionsThefollowingtopicscontaindescriptionsofeachoftheserverfunctions.Thedescriptionsincludethefollowinginformation:
Functionpurpose
Functionsyntax
Parameterlist
Returnvalues
Remarks
NoteTheserverfunctionsarefortheexclusiveuseofSQLServer.Theyaredescribedhereforinformationpurposesonly.
IServerVirtualDeviceSet2::Open
Purpose Thisfunctionopensthevirtualdevicesetontheserver,anditmustbethefirstcallmadeusingtheCOM-providedinterfacehandle.
Syntax HRESULTIServerVirtualDeviceSet2::Open(
LPCWSTRlpInstanceName,
LPCWSTRlpName
);
Parameters Argument Explanation lpInstanceName ThisstringidentifiestheSQLServer
instancetowhichtheSQLcommandwillbesent.NULLmaybepassedtoidentifythedefaultinstanceonthecurrentmachine.
lpName ThisisprovidedfromthefirstVIRTUAL_DEVICE=clauseoftheBACKUPorRESTOREcommand.Thisnameisusedasthekeytoobtainaccesstothevirtualdevicesetcreatedbytheclient.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_INVALID Thenameprovideddidnotidentifya
virtualdevicesetthatisaccessibletotheserver.
Remarks Afterthisfunctionissuccessfullyinvoked,theservermayproceedtoconfigurethevirtualdevicesetbyusingGetConfigurationandSetConfiguration.
IServerVirtualDeviceSet2::GetConfiguration
Purpose Thisfunctionobtainstheconfigurationrequestedbytheclient.
Syntax HRESULTIServerVirtualDeviceSet2::GetConfiguration(
VDConfig*pCfg
);
Parameters Argument Explanation pCfg Thisistheconfigurationspecifiedby
theclientusingIClientVirtualDeviceSet2::Create.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded.Remarks Theserverisexpectedtoinspectandrespondtothesettings
providedbytheclient.Formoreinformation,seeConfiguration.TheservercanuseSignalAbortifitdeterminesthatitcannotoperatecorrectlywiththeprovidedconfiguration.
IServerVirtualDeviceSet2::BeginConfiguration
Purpose Theserverinvokesthisfunctiontobeginconfigurationofthevirtualdeviceset.
Syntax HRESULTIServerVirtualDeviceSet2::BeginConfiguration(
DWORDdwFeatures,
DWORDdwAlignment,
DWORDdwBlockSize,
DWORDdwMaxTransferSize,
DWORDdwTimeout
);
Parameters Argument Explanation dwFeatures Themodifiedfeaturesmask.
VDF_WriteMediaand/orVDF_ReadMedia.
dwAlignment Thefinalalignment.If0,defaultstodwBlockSize.Mustbeapowerof2,>=dwBlockSizeand<=64KB.
dwBlockSize Theminimumunitoftransfer,inbytes.Mustbeapowerof2,>=512and<=64KB.
dwMaxTransferSize Thelargesttransferwhichwillbeattempted.Mustbeamultipleof64KB.
dwTimeout Millisecondstowaitfortheprimaryclienttofinishdeclaringbufferareasitwillprovide.
ReturnValues Argument Explanation
NOERROR ThevirtualdevicesetisintheConfigurablestate.
VD_E_ABORT TheSignalAbortwasinvoked. VD_E_PROTOCOL Thevirtualdevicesetisnotinthe
Connectedstate.Remarks Afterthisfunctionisinvoked,thevirtualdevicesetmovesto
theConfigurablestate,inwhichbufferlayoutisdecided.Oncethebasicconfigurationisset(aspertheparameters),thesevaluesremainfixedforthelifeofthevirtualdeviceset.Thealignmentpropertyforthevirtualdevicesetisusedtocontrolalignmentofdatabuffers.Thisvaluesetsaminimumalignmentvaluethatmaybeoverriddenonabuffer-by-bufferbasis.
IServerVirtualDeviceSet2::EndConfiguration
Purpose ThisfunctioninformstheVDIthattheserverisfinishedwithitsconfiguration.
Syntax HRESULTIServerVirtualDeviceSet2::EndConfiguration();
Parameters Argument Explanation None Notapplicable.ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_ABORT Abortwasrequested. VD_E_PROTOCOL ThesetisnotintheConfigurable
state. VD_E_MEMORY Thememoryrequiredviathe
'RequestBuffers'callscouldnotbeobtained.Thesetremainsintheconfigurablestatewithnobufferspaceavailable.Theservercaneitherreduceitsbufferrequirementsoraborttheoperation.
Remarks
IServerVirtualDeviceSet2::RequestBuffers
Purpose ThisfunctioninformstheVDIthattheserverwillneedacertainnumberofbufferswithagivensizeandalignmentrequirement.
Syntax HRESULTIServerVirtualDeviceSet2::RequestBuffers(
DWORDdwSize,
DWORDdwAlignment,
DWORDdwCount
);
Parameters Argument Explanation dwSize Identifiesthesizeofeachbuffer.This
sizeshouldonlyincludetheregionneededfordata.TheVDItakescareofanyalignmentandprefixrequirements.
dwAlignment Thealignmentrequiredforthesebuffers.Avaluemorerestrictivethanthebasicalignmentvaluespecifiedwith'BeginConfiguration'maybeused.Ifthevalueis0,itwilldefaulttothebasicalignmentvalue.
dwCount Thenumberofbufferswhichwillberequestedby'AllocateBuffer'withthegivensizeandalignment.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_ABORT Abortwasrequested. VD_E_PROTOCOL Thesetisnotinastateinwhich
bufferallocationsmaybedeclared(seethestatetransitionmatrix).
VD_E_MEMORY Therequestedmemorycouldnotbeobtained.
Remarks ThismethodshouldbeusedbeforebuffersareallocatedwithAllocateBuffer.SetsofbufferswithagivensizeandalignmentarerequestedwithRequestBuffersandthenindividualbuffersareallocatedwithAllocateBuffer.
Duringtheconfigurationphase,RequestBufferscallsare"summed"togethersothatattheEndConfigurationcallasinglebufferareacanbeused(itisallocatedatthattime).Afterconfigurationiscomplete,anyRequestBufferscallsresultinimmediateallocationofmorebufferspace.
IServerVirtualDeviceSet2::ExecuteCompletionAgent
Purpose Thisfunctionisusedtoimplementthemainloopofthecompletionagent.
Syntax HRESULTIServerVirtualDeviceSet2::ExecuteCompletionAgent();
ParametersArgument Explanation None NotapplicableReturnValues Argument Explanation NOERROR Thefunctionsucceeded.Remarks Thecompletionagentprovidesamechanismthroughwhich
SQLServercansynchronizeitselfwithvirtualdevicecommandcompletions.Itmustbeactivebeforeanycommandscanbeissuedanditshouldremainactiveuntilalldevicesareclosed.SinceSQLServermighthavetoperformspecialthreadinitialization,thisinterfacedoesnotstartanewthreadofcontrol.Instead,SQLServersetsupathread,andthenpassescontroltothisroutine.ThethreadmustbeblockableonWindowsNTInter-processCommunication(IPC)mechanismsandcapableofcallinganyofthecallbackfunctionsthatareprovidedwithcommandssentthroughIServerVirtualDevice::SendCommand.ThisfunctionwillnotreturnuntilIServerVirtualDeviceSet2::CloseorSignalAbortisinvoked.
IServerVirtualDeviceSet2::OpenDevice
Purpose Thisfunctionobtainsvirtualdeviceinterfacesfromthevirtualdeviceset.
Syntax HRESULTIServerVirtualDeviceSet2::OpenDevice(
LPCWSTRlpName,
IServerVirtualDevice**ppVirtualDevice
);
Parameters Argument Explanation lpName Thisisprovidedfromthefirst
VIRTUAL_DEVICE=clauseoftheBACKUPorRESTOREcommand.Thisnameisusedasthekeytoobtainaccesstothevirtualdevicesetcreatedbytheclient.
ppVirtualDevice Thisisusedtoreturnavirtualdeviceinterface.
ReturnValues Argument Explanation NOERROR Thefunctionsucceeded. VD_E_OPEN Alldeviceshavebeenopened.Remarks Eachcallreturnsthenextunopeneddevice.Thisfunctioncan
becalledonlythenumberoftimesequaltothenumberofdevicesspecifiedinthevirtualdevicesetconfiguration.
IServerVirtualDeviceSet2::AllocateBuffer
Purpose Thisfunctionobtainsasharedmemorybufferfromthevirtualdeviceset.
Syntax HRESULTIServerVirtualDeviceSet2::AllocateBuffer(
LPVOID*ppBuffer,
UINT32dwSize,
UINT32dwAlignment
);
Parameters Argument Explanation ppBuffer Thisreturnsapointertothestartof
thebuffer. dwSize Thisisthesizeofthebufferinbytes.
Thisdoesnotincludeanyprefixzonerequestedbytheclient.Anysuchzoneishiddenfromtheserverandtherewillbespaceavailablepriortowhenthebufferaddressisreturned.
dwAlignment Thisspecifiesthealignmentboundaryforthebuffer.Forexample,avalueof4096wouldensurethatthebufferisalignedona4096-byteboundary.Thismeansthattheaddressreturnedwouldhavetheloworder12bitssettozero.Thisparametermustbeapowerof2.
ReturnValues Argument Explanation NOERROR Thebufferisreturned. VD_E_MEMORY Anoutofmemoryconditionhas
IServerVirtualDeviceSet2::FreeBuffer
Purpose Thisfunctionobtainsasharedmemorybufferfromthevirtualdeviceset.
Syntax HRESULTIServerVirtualDeviceSet2::FreeBuffer(
LPVOIDpBuffer,
UINT32dwSize
);
Parameters Argument Explanation pBuffer Thisreturnsabufferreturnedby
IServerVirtualDeviceSet2::AllocateBuffer. dwSize Thisisthesizeofthebufferinbytes.This
doesnotincludeanyprefixzonerequestedbytheclient.Anysuchzoneishiddenfromtheserverandtherewillbespaceavailablepriortowhenthebufferaddressisreturned.
ReturnValues Argument Explanation NOERROR Thebufferisreturned. VD_E_INVALID Aparameterwasinvalid.Remarks None
IServerVirtualDeviceSet2::IsSharedBuffer
Purpose ThisfunctiondeterminesifthegivenbufferaddressreferstooneofthesharedbuffersmadeavailablebytheAllocateBuffermethod.
Syntax HRESULTIServerVirtualDeviceSet2::IsSharedBuffer(
LPVOIDlpBuffer
);
Parameters Argument Explanation lpBuffer Thisisanaddressofabuffer.ReturnValues Argument Explanation TRUE Thebufferisasharedbuffer. FALSE Thebufferisnotpartofthevirtual
deviceset.Remarks None
IServerVirtualDevice::SendCommand
Purpose ThisfunctionsendsacommandtotheclientbyusingavirtualdeviceobjectreturnedfromIServerVirtualDeviceSet2::OpenDevice.
Syntax HRESULTIServerVirtualDevice::SendCommand(
VDS_Command*pCmd
);
ParametersArgument Explanation pCmd Thisisapointertoacommandrequestblock.
Formoreinformation,seeCommands.ThecompletionFunctionfieldmustbesettopointtotheaddressofafunctionwiththefollowingsignature:
voidcallbackFunction(VDS_Command*pCmd);
Thiscallbackismadebythecompletionagentwhentheclientindicatesthatacommandhasbeencompleted.
SQLServersetsthecompletionContextfieldofthepCmd.Itspurposeistoprovidecontexttothecallbackfunction.
ReturnValues Argument Explanation NOERROR Thecommandissuccessfullyqueuedtothe
client. VD_E_QUEUE_FULL Thedevicequeueisfull. VD_E_IO_ERROR ThedeviceisinanIO-ERRORstate. VD_E_PROTOCOL Thedeviceisnotactive.Remarks Whenanerroroccurswhileattemptingtosendthecommand,thecallback
functionisinvoked,andthecompletionCodeinthecommandbufferisset
asfollows:
VD_E_QUEUE_FULLERROR_NO_SYSTEM_RESOURCES
VD_E_IO_ERRORERROR_IO_DEVICE
VD_E_PROTOCOLERROR_INVALID_HANDLE
VD_E_ABORTERROR_OPERATION_ABORTED
Formoreinformation,seeCommandErrorHandling.
IServerVirtualDevice::CloseDevice
Purpose ThisfunctionclosesavirtualdevicethathadbeenopenedwithIServerVirtualDeviceSet2::OpenDevice
Syntax HRESULTIServerVirtualDevice::CloseDevice();Parameters Argument Explanation None NotapplicableReturnValues Argument Explanation VD_E_CLOSE Thedeviceisalreadyclosed. VD_E_ABORT TheinterfaceisintheAbortstate.Remarks CloseDeviceisnotrequiredafterSignalAbortisusedto
forceabnormaltermination.IfCloseDeviceisinvokedafterSignalAbortisused,noactionistaken.
IServerVirtualDeviceSet2::SignalAbort
Purpose Thisfunctionsignalsthatanabnormalterminationshouldoccur.
Syntax HRESULTIServerVirtualDeviceSet2::SignalAbort();
Parameters Argument Explanation None NotapplicableReturnValues Argument Explanation NOERROR Theabortmessagewassuccessfully
posted.Remarks Atanytime,theservermaychoosetoaborttheBACKUPor
RESTOREoperation.Thisroutinesignalsthatalloperationsshouldcease.Theoverallinterfaceentersanabortstate.Nofurthercommandsareacceptedonanydevices.ThecompletionagentreturnsERROR_OPERATION_ABORTEDforeachoutstandingrequestandreturnstoitscaller.Anycompletionsrecordedattheclientareignored.Theserverensuresthatthereisnofurtherrequireduseofthebuffersordevicesreturnedfromthevirtualdeviceinterface.Theserverthenperformsabnormalterminationcleanup,whichshouldincludecallingtheIServerVirtualDeviceSet2::Closefunction.Formoreinformation,seeAbnormalTermination.
IServerVirtualDeviceSet2::Close
Purpose ThisfunctionclosesavirtualdevicesetopenedbyIServerVirtualDeviceSet2::Open.Itresultsinreleasingallresourcesassociatedwiththevirtualdevice.TheIServerVirtualDeviceSet2handleisnotusefulafterthisfunctionreturnsanditshouldbereturnedtoCOM.
Syntax HRESULTIServerVirtualDeviceSet2::Close();Parameters Argument Explanation None NotapplicableReturnValues Argument Explanation VD_E_PROTOCOL Thedeviceswerestillopen.Remarks Closingthevirtualdevicesetbeforeclosingthedevices
shouldnotbeperformed.Ifthissituationoccurs,VD_E_PROTOCOLisreturned.ThisactionresultsinCloseimmediatelyreleasingitsmappingofsharedmemory.Theserverissubjecttoaccessviolationsifitcontinuestoexpectownershipofresourcesreturnedfromthevirtualdeviceinterface.TheinterfaceperformsSignalAbortprocessing.
Thecompletionagent,ifrunning,completesanyoutstandingcommandsbeforereturningtoitscaller.AnyoutstandingcommandsarecompletedwithERROR_OPERATION_ABORTED.Thatis,thecallbackfunctionisinvokedforeachsuchcommand.
Inallcasesincludingwhenerrorsarereturned,Closereleasesallresourcesforthevirtualdeviceinterface.AnybuffersandotherinterfacepointersreturnedfromtheVDIbecomeinvalid.
ItisimportanttoensurethatthecompletionagenthasbeenterminatedbeforetheCOMlibraryisunloaded.Ifthelibraryisunloadedbeforethecompletionagentreturnstoitscaller,thentheprocesscouldcauseaninstructionviolation.
ConfigurationThefollowingtopicsdescribethevirtualdeviceconfiguration,listtheclientinputstotheVDConfigstructure,describethefeaturebitpositioningmethods,anddescribethefeaturebits.
DescriptionWhenaclientcreatesthevirtualdeviceset,itspecifiesinputstotheconfigurationtobeusedbyinitializingaVDConfigstructure.Whentheserveropensthevirtualdeviceset,itexaminestheseinputsandtheBACKUPorRESTOREcommandinputs,suchasBLOCKSIZE,MAXTRANSFERSIZE,andBUFFERCOUNT.Thisinformationhelpsdeterminetheactualconfigurationused.
Afterthevirtualdevicesethasbeenconfiguredbytheserver,theclientcanobtaintheconfigurationbyusingtheGetConfigurationfunction.
Ifeithertheserverortheclientisunabletoworkwiththeselectedconfiguration,SignalAbortcanbeusedtoterminatetheconnection.
TheVDIsupportsanoptionalbufferprefixzonefortheconvenienceoftheclient.
NoteThestartofthedatazoneisusedforalignmentpurposes.Theprefixzoneisplacedimmediatelypriortothestartofthedata.
TheconfigurationsupportsaserverTimeOut.Theclientmaychooseatime-outintervaltobeusedbytheserver.Iftheserver'scompletionagentwaitslongerthantwotime-outintervalswithrequestspendingandnorequestcompleting,theoperationisabortedautomatically.
Thisfeatureisintendedtobeadebuggingaid.Applicationsmayneedtoimplementtheirowntime-outlogictoreliablyhandleissuessuchasmountrequestsforremovablemedia.
VDConfigStructureThistableliststheclientinputstotheVDConfigstructure.
Field Type ValuedeviceCount UINT32Thisisthenumberofdevices,from1to
64,tobeused.features UINT32Thisisabitmaskoffeatures.Formore
information,seeFeatureBits.prefixZoneSize UINT32Thisisthesize,inbytes,oftheprefix
zone.Thevalue0indicatesthatnoprefixzonewillbeused.Thezoneappearsatanegativeoffsetfromthealigneddatabuffers.
alignment UINT32Thisistheminimumalignmentofbuffersrequiredbytheclient.Forexample,1024indicatesthatanybuffermusthavethedatazonestartingata1-KBboundary.
softFileMarkBlockSize UINT32ThisfieldisusedonlywhenVDF_FileMarksisset.Ifthefieldissettozero,thentheMicrosoftTapeFormat(MTF)controlblocksindicatethatsoftFileMarksarenotused.Foranyothervalue,thisfieldprovidesthesize,inbytes,ofthesoftFileMarksimplementedbytheclient.TheserverusesthisvaluetoformattheMTFcontrolblocksproperly.
SQLServerwritesthisvalueintotheMTFcontrolblockfieldsthatrequirethesoftFileMarkBlockSize.
EOMWarningSize UINT32Thisisthesize,inbytes,oftheendofthemediawarningzone.Ifthisfieldissetto0,SQLServerwillnotattempttoconstrainitselfforthisfactor.
Formoreinformation,seeEndOfMediaandUnexpectedFilemarks.
serverTimeOut UINT32Thisisthetime-out,inmilliseconds,usedbySQLServertolimittheclientresponsetime.
Thevalue0causesaninfinitetime-out.
ThistableliststheserverinputstotheVDConfigstructure.
Field Type ValueblockSize UINT32Thisisthesize,inbytes,thatisusedasthe
deviceBLOCKSIZE.maxIODepth UINT32Thisfieldisdeprecated.Itisnowalways
returnedas4.ThisusedtobethecountofthemaximumnumberofI/Orequestsoutstandingatanyonetime.
maxTransferSize UINT32Thisisthesize,inbytes,ofthemaximumI/OrequestthatisissuedbySQLServertothedevice.Thisisthesizeofthedataportionofthebuffer.
bufferAreaSize UINT32Thisfieldisdeprecated.ItisnowalwaysreturnedasmaxTransferSize*4*deviceCount.Thisusedtobethebytecountofthetotalamountofspacebeingusedforbuffermemory.
FeatureBitsTheselectionoffeaturesdetermineswhichcommandsMicrosoft®SQLServer™sendstothedevice.Formoreinformationaboutcommands,seeCommands.Onlycertaincombinationsoffeaturesaresupported:PIPE-like,TAPE-like,andDISK-like.Thefollowingdescribeswhichcommandsarerequiredforeachofthesupportedfeaturebitcombinations.Whenselectingthefeaturebits,thefirstconsiderationistoselectapositioningmethod:
PIPE-like.Inthismode,theclientactslikeapipe.Thisisapuresequentialmethod.Itrequirestheminimallevelofclientfunction.Featurebits:VDF_LikePipe,allbitsarezero(0).Optionalfeaturebits:VDF_Removable.
TAPE-like.Inthismode,theclientactslikeatapedevice.Thevirtualtapedeviceisafull-functiondevice,capableofhandlingfilemarks,removablemedia,reversepositioning,blockrelativepositioning,andskippingforwardoverblocks.Featurebits:VDF_LikeTape.Thisisequivalentto:VDF_FileMarks|VDF_Removable|VDF_ReversePosition|VDF_Rewind|VDF_Position|VDF_SkipBlocks.
DISK-like.Inthismode,theclientactslikeadiskdevice.AlldatatransferReadandWritecommandsprovidethepositionfieldinthecommand.Thisspecifiesabyteaddressrelativetothestartofthefile.Theclientmustensurethatdataisreadorwrittentothelocationspecifiedbytheposition.Datatransferissequential,withthefollowingexception:Duringthevalidationandpositioningphaseofmediahandling,aheaderisreadatposition0andsoftfilemarksarescanned.Featurebits:VDF_LikeDisk.ThisisequivalenttoVDF_RandomAccess.Optionalfeaturebits:VDF_Removable.
Thisoptioncanbeincludedwithanyofthecombinationsdescribedpreviously:
VDF_Discard.Thisfeaturebitissetbytheclienttoindicatethatit
supportstheDiscardcommand.
Onlycombinationsoffeaturebitsdescribedearlieraresupported.Behaviorresultingfromusingothercombinationsisundefined.
VDF_Removable(0x001)ThisfeaturebitspecifiesthedevicethatsupportstheVDC_Loadcommand.Supportforendofmediahandlingmustbeintheclient.Formoreinformation,seeEndofMediaandUnexpectedFilemarks.TheclientmustsupporttheVDC_Loadcommand.
VDF_FileMarks(0x100)Thedeviceusesfilemarks.Inthiscase,thesoftFileMarkBlockSizefieldoftheVDConfigstructuremustspecifythesizeofthesoftfilemarkblock.Asizeof0indicatesthathardfilemarkswillbeused.Otherwise,theclientimplementssoftfilemarksandMicrosoft®SQLServer™writesthissizeintocontrolfieldsrequiredbyMicrosoftTapeFormat(MTF).TheclientmustrespondtoVDC_WriteMarksandVDC_SkipMarkscommands.TheclientmustreturnERROR_FILEMARK_DETECTEDifSQLServerattemptstoreadthroughafilemark.
VDF_RandomAccess(x200)Whenthisbitisset,theclientsupportsthepositionfieldinallVDC_ReadorVDC_Writecommands.TheclientmustrespondtotheVDC_SetPositioncommand.Itspecifiesanorigin(current,beginning,orend),butmustreturnapositionrelativetothestartofthefile.
VDF_ReversePosition(x040)Reversepositioningisrequiredforremovabledevicesthatusefilemarks.TheVDC_SkipMarkscommandmayspecifyanegativedirectionforthemovement.
VDF_Discard(0x080)ThedevicemustsupporttheVDC_Discardcommand.ThisallowstheclienttogaincontrolofprocessingwhenthebackupsetisbeingabortedbySQLServer.
VDF_SnapshotPrepare(0x0400)UsedwithBACKUPWITHSNAPSHOToperations.Whenthisbitisset,SQLServerwillsendaVDC_PrepareToFreezecommandpriortofreezingthedatabasefiles.ThisallowstheVDIapplicationcontroloverthetimingofthefreeze.Itisparticularlyusefulwhencoordinatingsnapshotsofmultipledatabases.
ThisfeaturebitisonlydefinedinMicrosoft®SQLServer™2000ServicePack2andlater.InearlierversionsofSQLServer,thebitisignoredandnoVDC_PrepareToFreezecommandisissued.ThesnapshotproceedsimmediatelytothefrozenstateandaVDC_Snapshotcommandisissued.
Formoreinformation,seeSNAPSHOTSupport
VDF_WriteMedia(0x10000)ThisbitissetbyMicrosoft®SQLServer™.OnlythisandtheVDF_ReadMediafeaturebitaresetinthismanner.ItisvisibleafterIClientVirtualDeviceSet2::GetConfigurationreturnsthefinalconfiguration.Thisbitisfortheconvenienceoftheclient,informingitthataBACKUPisbeingperformedandthatitshouldbepreparedtoreceiveVDC_Writedatatransfercommands.
VDF_ReadMedia(0x20000)Fortheconvenienceoftheclient,thisbitissetbyMicrosoft®SQL™Server.TheclientshouldbepreparedtoreceiveVDC_Readdatatransfercommands.ThisbitisalwayssetonRESTOREoperationsandcanbesetonBACKUPoperationswhentheclientsupportspositioning,enablingdisk-likeortape-likebehavior.
CommandsThissectionprovidesadescriptionofeachcommandandliststheclientcommandinputs,servercommandinputsandoutputs,thecommandsthatmustbesupportedbytheclientbasedonselectedfeatures,andthecommandcompletioncodes.Thissectionalsodescribescommanderrorhandling,aswellasend-of-mediaandunexpectedfilemarkhandling.
CommandGeneralRulesAllcommandsmustreturnacompletioncode:
ERROR_OPERATION_ABORTEDisreturnedasthecompletioncodewhentheserverorclientusesitsSignalAbortinterface.
ERROR_SUCCESSisreturnedwheneveracommandsuccessfullycompletes.
ERROR_NOT_SUPPORTEDisreturnediftheclientisaskedtoperformanycommandforwhichnosupportexists.ThiscouldhappeniftheclientspecifiesincorrectfeaturesupportbitsduringIClientVirtualDeviceSet2::Create.
Inothercases,acodeappropriatetotheoperationmustbereturned.ForWIN32-definedcodes,seethefileWinerror.h.
CommandErrorHandlingWhenanerrorisreturnedforacommandthedeviceentersanIO-ERRORstate.ToclearthisstatetheservermustissueaClearErrorcommand.TheclientmustcompleteoutstandingcommandsusingtheCompleteCommandfunctionandthenacknowledgetheClearErrorcommand.
Attheserverinterface,whenavirtualdeviceisintheIO-ERRORstate,furthercommandsareimmediatelyrejectedwithacodeofERROR_IO_DEVICE.ThisisdonebycallingthecallbackfunctionimmediatelyfromthethreadissuingtheSendCommand.TheserverisnotabletosendanycommandotherthanaClearErrorcommand.ThiscommandisnotdeliveredfromtheGetCommandinterfaceuntiltheclienthasdeliveredcommandcompletionsforcommandsthatwereoutstandingatthetimethedeviceenteredtheIO-ERRORstate.WhentheclientreceivestheClearErrorcommand,itcantakeanynecessaryactions,andthencanrespondwithasuccessfulcompletioncode.CommandsqueuedbutnotyetdeliveredtotheclientareautomaticallycompletedwithERROR_IO_DEVICE.Theclientneverseesthesecommands.
AftertheserverreceivesthecompletionontheClearErrorcommand,thestateofthedevicebecomesActiveagainandanycommandcanbeissued.
Thisdiagramdescribesthedevicestates.
ThereasonforthiserrorhandlingprotocolistoensurethattheserverisabletoreliablyrecoverfromerrorswhileasynchronousI/Oispending.
InsteadofissuingaClearErrorcommand,theserverisfreetoCloseDeviceorSignalAbort.Ineithercase,theclientseesanappropriateresponsefroma
VDC_ReadThiscommandmustalwaysbesupported.Ittransfersthesizebytesfromthedeviceintothebuffer.Thenumberofbytessuccessfullytransferredmustbereturned.PositionisdefinedonlyifVDF_RandomAccessisset.
Thisisalistoferrorcodesandtheirdescriptions:
ERROR_HANDLE_EOF.Nomoredataisavailable.
ERROR_NO_DATA_DETECTED.Nomoredataisavailable.Microsoft®SQLServer™handlesthiserrorandERROR_HANDLE_EOFinasimilarfashion.
ERROR_FILEMARK_DETECTED.Thiserroroccurswhenattemptingtoreadpastafilemark.Formoreinformation,seeEndofMediaandUnexpectedFilemarks.
VDC_WriteThiscommandmustalwaysbesupported.Ittransferssizebytesfromthebuffertothedevice.Thenumberofbytessuccessfullytransferredmustbereturned.PositionisdefinedonlyifVDF_RandomAccessisset.
DuringBACKUPoperations,theclientmaycachetheoutputdatastream.Microsoft®SQLServer™issuestheFlushcommandwhenitneedstobesurethatdataisactuallystoredinadurablefashion.
Thefollowingisalistoferrorcodesandtheirdescriptions:
ERROR_DISK_FULL.Thisindicatesthatthedeviceisnotcapableofstoringmoreinformation.SQLServerrespondstothiscodebyabortingtheBACKUPoperation.
ERROR_EOM_OVERFLOW.Thisindicatesthatthedeviceisnotcapableofstoringmoreinformation.SQLServerrespondstothiscodebyabortingtheBACKUPoperation.
ERROR_END_OF_MEDIA.Thisindicatesthatthedevicehasreachedtheendofmediawarning.Formoreinformation,seeEndofMediaandUnexpectedFilemarks.
VDC_ClearErrorThiscommandmustalwaysbesupported.ItisusedtoclearthedeviceoutoftheI/O-errorstateafteranerrorhasbeenreturnedforapreviouscommand.Onlyasuccessfulcompletioncodeshouldbeused.Ifthedevicecannotrecoverfromapreviouslyreturnederrorcode,thenMicrosoft®SQLServer™abortstheoperation.
VDC_RewindThiscommandissupportedwhenVDF_Rewindissetintheconfiguration.Itrewindsthemediumtothebeginningofthedata.
VDC_WriteMarkThiscommandissupportedifVDF_FileMarksisset.Itputsafilemarkonthemedium.Atalatertimewhenreadingthemedium,anattempttoreadthefilemarkshouldreturnERROR_FILEMARK_DETECTED.
VDC_SkipMarksThiscommandissupportedifVDF_FileMarksisset.Itskipsforwardandbackwardsizefilemarks.Thesizeisinterpretedasasignedintegerforthiscommand.AnegativesizewillberequestedonlyiftheVDF_ReversePositionbitisset.
VDC_SkipBlocksThiscommandissupportedonlyiftheVDF_SkipBlocksbitissetintheconfiguration.Itskipsforwardandbackwardsizephysicalblocks.Thesizeisinterpretedasasignedinteger.AnegativesizewillberequestedonlyiftheVDF_ReversePositionbitisset.
VDC_LoadThiscommandissupportedifVDF_Removableissetintheconfiguration.Thisloadsmediaontothedevice.Oncompletion,themediumshouldbepositionedatthestartofdata.Sizeisinterpretedasanunload-firstflag.Ifsizeissettoone,theexistingmediumshouldbeejectedbeforerequestinganother.
NoteIfserverTimeOutissettoavalueotherthan0,theloadcommandcantimeoutwhilewaitingfortheusertomountatape.ThiscausesMicrosoft®SQLServer™toabnormallyterminatetheBACKUPorRESTOREoperation.ConsidersettingtheserverTimeOuttothe0(infinite)valueifVDF_Removableissetintheconfiguration.
VDC_GetPositionThiscommandissupportedifVDF_PositionorVDF_RandomAccessissetintheconfiguration.Thepositionfieldmustbeprovidedoncommandcompletion.
IfVDF_RandomAccessisspecified,thepositionreturnedtoMicrosoft®SQLServer™mustalwaysbeazero-originbyteoffsetfromthebeginningofdata.IfVDF_RandomAccessisnotspecified,thepositionistreatedasablockaddress.
MicrosoftTapeFormat(MTF)requiresaPhysicalBlockAddress(PBA)inseveralofitsfields.SQLServerdoesnotsupporttapesthatdonotreturnblockaddresses.SQLServerchooseslogicalblockaddressingbeforephysicalblockaddressingwhenbothareavailable.BecausepipesdonotprovidePBA,thevirtualdeviceinterfacepermitsclientconfigurationswithoutpositioningsupport.Inthiscase,SQLServercreatesaPBAbasedonthemedia'sapparentposition.
VDC_SetPositionThiscommandisrequiredifVDF_PositionorVDF_RandomAccessissetintheconfiguration.Thepositionfieldmustbeprovidedasinputtothiscommand.TheresultingpositionmustbereturnedoncommandcompletionsimilartowhenaGetPositioncommandisexecutedimmediatelyaftertheSetPosition.
IfVDF_RandomAccessisspecified,theinputpositionisinterpretedasabyteoffsetrelativetothebeginningofdata,currentposition,orendofdata.Thebeginningofdata,VDC_Beginning(0),currentposition,VDC_Current(1),orendofdata,VDC_End(2),informationisobtainedfromthesizefieldofthecommand.
IfSetPositionisusedwithoutVDF_RandomAccess,thenthepositionisdevicedefined.OnlypositionspreviouslyreturnedbyaGetPositioncommandarespecifiedbyaSetPositioncommand.
VDC_DiscardThiscommandissupportedifVDF_Discardissetintheconfiguration.IfthedevicesupportstheDiscardcommand,Microsoft®SQLServer™issuesaDiscardcommandbeforeclosingthedevice.ThisallowstheclienttogaincontroloverthediscardprocessingforabortedBACKUPsets.
VDC_FlushThiscommandisrequired.ItisusedbyMicrosoft®SQLServer™torequestthatallpreviouslyreceivedwriteoperationsaredurablystored.DuringBACKUPoperations,theclientmaycachetheoutputdatastream.SQLServerissuestheFlushcommandwhenitmustensurethatdataisstoredinadurablefashion.
IfVDF_LikeDiskisbeingused,theend-of-filemarkerisimplicitlysetwhentheFlushcommandisreceived.Clientsimplementingadisk-likedevicemustensurethatthefileendsatthelastpositionpreviouslywritten.TheSetEndOfFile()Windowsfunctioncanbeusedtoaccomplishthis.Thisisimportantforcaseswhereapre-existingdiskfileisbeingoverwritten.Forexample,whentheWITHINITstatementisusedtooverwriteanexistingbackupfileandthenewbackupfileisshorterthantheoriginal,thentheFlushcommandshouldbeusedtosettheend-of-filemarker.
VDC_SnapshotWhenBACKUPWITHSNAPSHOTisused,thiscommandindicatesthatMicrosoft®SQLServer™hassuspendedwritestoitsdatabasefiles.Theapplicationmustcopythefilesasquicklyaspossibleandthencompletethecommand.Toabortthecommand,theapplicationshouldreturnthe'ERROR_OPERATION_ABORTED'errorcode.Formoreinformation,seeSNAPSHOTSupport.
Atthetimethiscommandisreceived,themetadatathatisbeingwrittenovertheVDIchanneliscomplete.Theapplicationmaycloseitsoutputstreamandisfreetoincludethemetadatawiththeactualdataportionofthesnapshot.
VDC_PrepareToFreezeWhenBACKUPWITHSNAPSHOTisused,andtheVDF_SnapshotPrepareconfigurationbitisset,theVDC_PrepareToFreezecommandissentpriortothefreezeofthedatabasefiles.RefertoSNAPSHOTSupportformoreinformationontheuseofthiscommand.
ThiscommandwasaddedinServicePack2forMicrosoft®SQLServer™2000.InearlierversionstheVDF_SnapshotPrepareconfigurationbitisignoredandtheVDC_PrepareToFreezecommandisneverissued.
VDC_MountSnapshotWhenRESTOREWITHSNAPSHOTisused,thiscommandindicatesthattheapplicationshouldmakethedatafilesavailabletoMicrosoft®SQLServer™.Toabortthecommand,theapplicationshouldreturnthe'ERROR_OPERATION_ABORTED'errorcode.Formoreinformation,seeSNAPSHOTSupport.
VDC_CommandClientCommandInputsThistableprovidestheclientcommandinputsforVDC_Command.
Field Type ValueCommandCode UINT32Thisisanoperationcode.Buffer PTR Thisistheaddressofthedatatransferarea.Size UINT32Thisisthenumberofbytestotransfer.Thisfield
isoverloadedforsomecommands.Position UINT64Thisisthedevicepositiontolocate.
VDS_CommandServerCommandInputsThistableprovidestheservercommandinputsforVDS_Command.
Field Type ValueCommandCode UINT32Thisisanoperationcode.Buffer PTR Thisisadatatransferarea.Size UINT32Thisisthenumberofbytestotransfer.Thisfield
isoverloadedforsomecommands.Position UINT64Thisisthedevicepositiontolocate.CompletionRoutine
PTR Thisisacallbackfunctioninvokedbythecompletionagent.
CompletionContext
PTR Thisisthecontextforthecompletionroutine.ItsuseisdecidedbyMicrosoft®SQLServer™.
VDS_CommandServerCommandOutputsThistableprovidestheservercommandoutputsforVDS_Command.
Field Type ValueCompletionCode
UINT32ThisisanappropriateWindowscompletioncode.AnexampleisERROR_SUCCESS.
Bytestransferred
UINT32Thisisthenumberofbytessuccessfullytransferred.
Position UINT64ThisistheresultoftheGetPositioncommand.
CommandInputsThistableshowsthecommandinputsthatarerequired.
Command(VDC_x) Buffer Size Position
CompletionRoutine
VDC_Read X X XVDC_Write X X XVDC_ClearError XVDC_WriteMark XVDC_SkipMarks X XVDC_SkipBlocks X XVDC_Load X XVDC_Rewind XVDC_GetPosition XVDC_SetPosition X XVDC_Discard XVDC_Flush XVDC_Snapshot XVDC_MountSnapshot X
CommandOutputsThistableshowsthecommandoutputsthatarereturnedforeachcommand.
Command(VDC_x)
CompletionCode
BytesTransferred Position
VDC_Read X X VDC_Write X X VDC_ClearError X VDC_WriteMark X VDC_SkipMarks X VDC_SkipBlocks X VDC_Load X VDC_Rewind X VDC_GetPosition X XVDC_SetPosition X XVDC_Discard X VDC_Flush X VDC_Snapshot X VDC_MountSnapshot X
ClientSupportedCommandsThisisalistofcommandsthataresupportedbytheclient,dependingonfeaturesselectedintheconfiguration.AnXindicatesthatthecommandmustbesupportedbytheclient.AnOindicatesthatthecommandisoptional.VDC_Discardisoptionalinallconfigurations.
Command(VDC_x) Pipe-like Tape-like Disk-like
Disk-like(removable)
VDC_Read X X X XVDC_Write X X X XVDC_ClearError X X X XVDC_WriteMark X VDC_SkipMarks X VDC_SkipBlocks X VDC_Load O X XVDC_Rewind X VDC_GetPosition X VDC_SetPosition X X XVDC_Discard O O O OVDC_Flush X X X XVDC_Snapshot O O O OVDC_MountSnapshotO O O O
EndOfMediaandUnexpectedFilemarksFornonremovabledevices,thereisnoavailableresponsetoanend-of-fileordisk-fullcondition.Microsoft®SQLServer™abortstheoperationinthissituation.
Properhandlingofendofmedia,especiallywithoverlapped,asynchronousI/O,forremovabledevicescanbechallenging.
InthecaseofRESTOREoperations,SQLServerhasoneormorereadoperationsissuedtoadevicewhenoneofthefollowingerrorsisreturned:
ERROR_NO_DATA_DETECTED
ERROR_HANDLE_EOF
ERROR_FILEMARK_DETECTED
SQLServerwaitsforanyotheroutstandingI/Otocomplete.Afterdeterminingthatthebackupsetwasproperlyterminated,SQLServerissuesaVDC_Loadcommandtobeginprocessingthenextmedia.
DuringRESTOREoperations,SQLServereitherterminatesorcontinuesdependingontheoperationbeingperformedandthestateofthemedium.Forexample,RESTOREcanbeusedtorestoredatatothedatabase,toscantapes,toverifymedia,andsoon.
DuringBACKUPoperations,removabledevicesrespondwithERROR_END_OF_MEDIAwhenanend-of-mediumwarningzoneisreached.SQLServercurrentlyrequiresthatallI/Opendingatthetimethiswarningoccursmustbestored.IfthebytesWrittendoesnotequaltherequestednumberofbytes,SQLServerreissuesthewriterequests.Ifthedevicecannotstorethequeueddata,SQLServerabortstheBACKUP.SQLServerattemptstoavoidoverrunningthiswarningzonebyrespondingtothesizeofthezonereportedinthedeviceconfiguration.
Clientssupportingremovablemediamayhidetheend-of-mediaconditionsfromSQLServer.Whenend-of-mediaconditionsarehidden,thenativeSQLServer
supportofthebackupsetisprevented.SQLServerisnotabletoreadthebackupsetdirectlyfromthemediawithouttheassistanceoftheclientapplication.Insuchcases,theclientshouldindicate,byconfiguration,thatthemediaisnotaremovabledevice.
SNAPSHOTSupportWerecommendtheuseoftheVSSframeworkformanagingsnapshotbackupandrestore.ThefollowinginformationdescribeshowsnapshotbackupandrestoreisimplementedusingVDI.SomeoftheinformationisalsorelevanttosnapshotbackupandrestoreimplementedusingtheVSSsqlwritercomponent.Thesqlwritersupportsdatabasedifferentialsnapshotbackup.NosuchsupportisplannedfortheVDI/snapshotinterface.However,thesqlwriterdoesnotyetsupportfileandfilegroupgranularityrestore.Refertothearticle"SQLWriterinSQLServer2005:AGuideforSQLServerBackupApplicationVendors"formoreinformation.
AsnapshotofaMicrosoft®SQLServer™databaseisacopyofdataandlogfilesatasinglepointintime.Thedataisnottransactionallyconsistent,butcanbemadesobyapplyingthelogasisdonebyregularRESTOREoperations.Afullbackupwillmakeacopyofalldataandlogfiles.'File'backupsarealsosupported,inwhichcaseonlyasubsetofthedatafilesarecopied.
Snapshotsmaybehardware-assistedordonebysoftware.
Motivationsforsnapshots,particularlyhardwareassistedones,include:
Extremelyfastrestoresfromdiskbackups.
Fastcreationofdatabasecopiesforreporting,DBCC,ortesting.
ExtremelyfastbackupofhighlyavailableVLDBsystemswith"noimpact".
Fastinitializationofwarmstandbyserverspriortologshipping.
Bothfulldatabaseandfilesnapshotsaresupported.Differentialsnapshotsarenotsupported.
Afulldatabasesnapshotcapturesalldataandlogfiles,andisequivalenttoafulldatabasebackup.Inparticular,onecanperformafile,filegroup,orpartialdatabaserestorefromafulldatabasesnapshot.
Afilesnapshotcapturesasubsetofthedatafiles,butdoesnotcapturethelogfiles.ThelistoffilescapturedmustmatchthelistoffilesandfilegroupsprovidedtotheBACKUPDATABASEcommand.Filesnapshotsaresubjecttothesameoperationalmodelasconventionalfilebackups;acompletesetoffilebackupsandafullsetofconventionallogbackupsarerequiredforrecovery.
Conventionaldifferentialdatabasebackupswillbebasedonthemostrecentfulldatabasesnapshotorfulldatabasebackup.Thatis,onlythoseextentsmodifiedsincethemostrecentfulldatabasesnapshotorconventionalbackupwillbebackedup.
DevelopersofbackupapplicationswillwriteasnapshotproviderapplicationtoissuethebackupandrestorecommandsandinteractwiththeserverthroughVDI.Thisissimilarto,yetsimplerthan,theagentsdevelopedbybackupapplicationvendorsthatsupportVDI.Withsnapshots,onlyasingle"device"isallowedandvendorsareonlyrequiredtosavethebackupsetmetadata.
Avolumeistheminimumunitofwhichasnapshotcanbetaken.Thesnapshotmaybecreatedbyanytechniquethatmakesa"near-instant"copyofthefilesbeingcaptured.Typically,thiswillinvolvesplit-mirrororcopy-on-writetechnology.
ThedurationofthesnapshotisthelengthoftimebetweenSQLServer'sissuanceofthesnapshotcommandtothesnapshotprovider,andthereturnofasuccessfulcompletionindication.Writestothedatabasefilesbeingcapturedaresuspendedforthedurationofthesnapshotoperation.Hence,thesnapshotmustbecompletedasquicklyaspossibleinordertoavoidimpactonSQLServerusers.
NoteMicrosoftrecommendsthatthedurationofthesnapshotbelimitedto10secondsorless.
Holdingadatabasefrozenforlongperiodsoftimemayresultinserver-wideeffects.ThisisparticularlytrueforSQLServer2000.InSQLServer2005,backgroundoperationssuchasthelazywriterandcheckpointprocesseshavebeenimprovedtoavoidsomeofthis"freezespillover"effect.
Thesnapshotprovidershouldreturnindicationofcompletionassoonasitcanallowwritestothedatabasewhileprotectingthesnapshotfrommodification.ThesnapshotoperationmustappeartoSQLServerasifitcompletedbeforetheproviderreturnedsuccess.Forsplit-mirrorsnapshots,itmaybethatthecache
canbemarkedappropriatelywithoutwaitingfortheflushofthecachetodiskortheactualsplit.Forcopy-on-writetechnology,itisnormallynecessaryonlytosetupthecopy,andthenmaterializethesnapshotonseparatemedialater.
Weusethetermmounttorefertotherestorationofsnapshotvolume(s)totheoperatingsystem.Inthecaseofacopy-on-writesnapshot,thismayinvolvecopyingthevolumecontentintoplacefromothermedia.Forsplit-mirrorsnapshots,thisinvolvesareconciliationofthetwomirrors,wherethesnapshotisthecorrectcopy.Thisreconciliationistypicallydoneinthebackground,resultinginanapparent"near-instant"restore.
Avolumeisthesmallestunitthatcanbecapturedwithasnapshot.Typically,avolumecontainsfilesfromonlyonedatabasebecauseinSQLServer2000ServicePack1(SP1)andearlier,thereisnowaytofreezeandbackupmorethanasingledatabaseatonetime.Thefreezeisdoneinthecontextofabackupcommand,whichbacksupasingledatabaseatatime.Thereisnowaytospecifythatmorethanonedatabaseisbeingbackedup.
However,SQLServer2000ServicePack2(SP2)includesaPrepareToFreezecapabilitythatallowsmultipledatabasestobefrozenandcapturedinasinglesnapshot.
Formoreinformation,seeCreationofaSnapshot.
CreationofaSnapshotTheBACKUPcommandsupportsthe'WITHSNAPSHOT'optiontobeusedwithvirtualdevices.AnapplicationissuestheBACKUPDATABASEcommand,andtheninteractswiththeserverthroughtheVirtualDeviceInterface(VDI)tocapturethebackupsetmetadataandperformthesnapshot.Onlymetadataistransferredtotheapplication.Insteadofreceivingthedataandlogportionsofthebackupset,theapplicationreceivesacommandtoperformthesnapshot.Topreventtornpages,writestothedatabasefilesaresuspendedwithinMicrosoft®SQLServer™untilthiscommandcompletesoraborts.Uponsuccessfulcompletionofthesnapshot,SQLServerwillresumewritingtothefiles.Themetadatamustbesavedbytheapplication,asitisrequiredtorestorethesnapshot.
NoteWhenfulldatabasesnapshotbackupsarebeingperformed,alldatabaseandlogfilesmustresideonthevolumesbeingcaptured.
Thedevelopmentkitcontainsasampleapplication(snapshot.cpp)thatdemonstrateshowasnapshotiscreated.
Herearethebasicstepsforcreatingasnapshot:
1. CreatetheVirtualDeviceSet.
SettingtheVDF_SnapshotPrepareconfigurationbitisoptional.Ifomitted,SQLServerwillnotissuetheVDC_PrepareToFreezecommandduringtheprocess.
2. IssuetheBACKUPDATABASEcommand,includingtheWITHSNAPSHOTclause.
3. OpentheVirtualDevice.
TheremaybeonlyoneVirtualDeviceforeachSNAPSHOTBACKUPcommand.
4. ConsumetheMTFheaderdata(asequenceofVDC_Writecommands).
5. IftheVDF_SnapshotPreparebithasbeenset(optionalinSQLServer2000SP2),theVDC_PrepareToFreezecommandisissued.TheVDIapplicationcancoordinateactionspriortothedatabasefreezeatthispoint.Forexample,ifmultipledatabasesarehostedonasinglevolume,multipleBACKUPWITHSNAPSHOTcommandscanbeissued,andtheapplicationcanwaitfortheVDC_PrepareToFreezefromeachoftheactivebackupstatements.
6. WhenVDC_PrepareToFreezeiscompleted,thedatabasefilesarefrozen.MetadatadescribingthefrozenstateiscollectedandsentasasequenceofVDC_Writecommands.
7. TheVDC_Snapshotcommandisissued.
Thesnapshotismadestable(mirrorsplit,etc.).
8. WhentheVDC_Snapshotcommandiscompleted,thedatabasefilesareunfrozen.TheVirtualDeviceSetisclosedandtheBACKUPcommandreturnsasuccessfulstatuscode.
9. Whenfreezingthemasterdatabasealongwithmultipleotherdatabases,alwaysfreezethemasterdatabaselast.Whenfinishedwiththesnapshot,thereisnoneedtoserializethecompletionsoftheVDC_Snapshotcommands.AllthedatabasesshouldbeunfrozenasquicklyaspossiblebycallingCompleteCommandfortheVDC_Snapshotcommands.
10. Whenfreezingmultipledatabases,thereisaBACKUPstatementactiveagainsteachdatabase.ThisconsumesresourcesinsideSQLServer.Thustherearelimitstohowmanydatabasescanbefrozenatatime.Werecommendthatnomorethanafewdatabasesbeincludedinajointsnapshot.
Seealso
BACKUPstatement
MediaRecoveryUsingtheSnapshotTheRESTOREcommandsupportsuseofthe'WITHSNAPSHOT'optionwithvirtualdevices.AnapplicationissuestheRESTOREDATABASEcommand,theninteractswiththeserverthroughtheVDIinterfacetoprovidethebackupsetmetadata.Afterinspectingthemetadata,theapplicationreceivesacommandtomountthesnapshot.Itmakestheoriginalcontentofthedatafilesavailableonthesystemandrespondswhenthisiscomplete.Thedatafilesmountedmustbebyte-for-byteexactlythesameaswhenthesnapshotwastakenwiththeBACKUPcommand.
Ideally,thefilecontentisprovidedtotheoperatingsystem(mounted)inresponsetothemountcommand.Thisprovidesthemostfunctionality,highestavailability,andeasiestadministration.However,sometechnologiesorscenariosmaynotallowthis,insteadrequiringarebootoftheoperatingsystem.
IfthefilescannotbemountedduringtheRESTOREcommand,thedatabaseshouldbedetachedordroppedfromarunningSQLServerpriortoexecutionoftheRESTOREcommand.Thisapproachprecludesrestorationofindividualfiles.Snapshotrestoreofindividualfilesisonlysupportedifthedatabaseexists.
Seealso
RESTOREstatement
VDC_MountSnapshot
ScenariosThefollowingtopicsaddresscommonrecoveryscenarioswithsnapshotbackups.ThescenariosinvolvingrestoreassumethatthevolumesaremountedinresponsetotheVDC_MountSnapshotcommandissuedbyMicrosoft®SQLServer™duringexecutionoftheRESTORE.
RestoreDatabaseThedatabasemustberestored,buttheserverisfunctionalandotherdatabasesremainavailable.Therestorerequiresapplicationofafulldatabasebackupfollowedbyapplicationofoneormoretransactionlogbackups.Thefulldatabasebackupisahardware-assistedsnapshot.
Steps
Restorethesnapshotwithnorecovery.
Applylogbackupsandrecover.
DataandlogfilescanberelocatedbyusingtheMOVEoption.Thesnapshotfilesareplacedintheirnewlocationsbythesnapshotprovider;MOVEspecifiesthenewpathname.
Averysimilarscenariocanbedescribedinwhichonlythedamagedfilesarerestored.Theonlydifferenceisintherestorecommandissuedandthesnapshotfilesrestoredbytheprovider.Point-in-timerecoveryisnotanoption,sincealltherestoredfileswillneedtoberestoredtotheendoflog,consistentwiththefilesthatwerenotrestored.
Snapshotrestoreofthemasterdatabaseisnotsupported.Ifasnapshotbackupofthemasterdatabasewastaken,itcanberestoredbystoppingtheSQLServerservice,copyingthemasterfiles,andthenrestartingtheservice.
DisasterRecovery,MasterBackupAvailableTheentireserverisbeingrecoveredafteracatastrophicfailure.Currentconventionalbackupsofmaster,MSDBandmodelareavailable.Fulldatabasesnapshotsandconventionallogbackupsareavailableforsomeuserdatabases.Thesnapshotbackupsaremountedafterrecoveryofmaster.
Steps
RestoreMicrosoft®SQLServer™service.(Thismayrequirerestorefromafilesystembackuporareinstall.)
StartSQLServerinsingleusermode(-m).
Restoremasterdatabase.
Restartservernormally.
Foreachselecteddatabase{
Restoredatabasewithnorecovery.
Applylogbackupsandrecover.
}
DisasterRecovery,MasterBackupNotAvailableTheentireserverisbeingrecoveredafteracatastrophicfailure.Acurrentconventionalbackupofmasterisnotavailable.Fulldatabasesnapshotsandconventionallogbackupsareavailableforsomeuserdatabases.
Steps
RestoreMicrosoft®SQLServer™service.(Thismayrequirerestorefromafilesystembackuporareinstall.)
Restartservernormally.
Recreateobjectsinmaster,butdonotcreateuserdatabasesforwhichtherearebackups(snapshotorconventional).
FixorrestoreMSDBandmodelasrequired.
Foreachdatabasetoberestored{
Restoredatabasewithnorecovery.
Applylogbackupsandrecover.
}
InitializeWarmStandbyThesnapshotisusedtoinitializethesecondarydatabaseonthestandbyserver.Onceinitialized,thestandbydatabasewillbemaintainedintheusualmannervialogshipping.
Steps
Restorethedatabasewithnorecoveryorstandby.
Maintaindatabasevialogshipping.
RestoreandRecoverDatabase,RelocatingFilesThedatabasemustberestored,buttheserverisfunctionalandotherdatabasesremainavailable.Therestorerequiresasnapshotrestorefollowedbyapplicationofoneormoretransactionlogbackups.Oneormorefilesmustberelocatedduetoadifferentmediareconfiguration.
Steps
Restorethedatabasewithnorecoveryandappropriatemoveoptions.
Applylogbackupsandrecover.
RestoreDamagedFilesfromFileBackupsAfewdatabasevolumesaredamagedandmustberestored,buttheserverisfunctionalandotherdatabasesremainavailable.Availablebackupsconsistofafullsetoffile/filegroupsnapshotbackupsandasetofconventionaltransactionlogbackups.Databaserecoveryrequiresrestoreofthesnapshotsofthedamagedvolumesfollowedbyapplicationofthetransactionlogbackups.
NoteThisscenarioisnotpossibleifthesnapshottechnologydoesnotallowmountingofthevolumesduringtheexecutionoftheRESTOREstatement.
Steps
Foreachdamagedvolume{
Restorefile/filegroupsnapshotwithNORECOVERY.
}
Applyconventionallogbackupsandrecover.
DisasterRecovery,Backupof"SystemVolumes"AvailableTheentireserverisbeingrecoveredafteracatastrophicfailure.Animagesnapshotofthesystemvolumes(thosevolumescontainingWindowsandSQLServerinstallations)isavailable.Thesystemvolumesnapshotincludescurrentcontentsofmaster,model,andMSDB.Conventionallogordifferentialbackupsareavailableforsomeuserdatabases.
Thisscenarioassumesthatthesnapshotbackupsaremounted(orcopiedintoplace)atthebeginningofthesequenceaspartofthesystemvolume(s).Itisalsopossibletomountorcopythefilesintoplaceduringtheexecutionoftheindividualrestorecommands.
Recoveryofuserdatabasesneedingroll-forwardispreventedbybringinguptheserverinminimalmode(-f)topreventrecoveryofthedatabases,thentakingthesedatabasesoffline.Theservermustnotbeallowedtocomeupwithoutthisflag,orthecapabilitytoroll-forwardwillbelost.ItisusuallydesirableforSQLServertostartautomaticallywithoutthe–foption,sothesnapshotimagewillnothavethisoptionset.Therefore,MicrosoftrecommendsstartingWindowsinsafemodeandaddingthe–foptiontothestartupparametersoftheSQLServerservice.Ifthisisnotpossible,recoveryofadatabasemayalsobepreventedbytemporarilyrenamingoneofthedatabasefiles.
Ifthemodel,msdbandtempdbdatabasesarebeingrelocated,useofthe–T3608flagpreventsstartupofthesedatabases.Thensp_detach_dbandsp_attach_dbcanbeusedtopointatthenewlocations.InSQLServer2005,abettermethodisavailable:useALTERDATABASEMODIFYFILEtotellSQLServerwhenthefileswillbelocatedonthenextrestart.
Steps
Mountallvolumescontainingthesystemimagesnapshot
StartSQLServerinminimalconfiguration(-fstartupparameter)
Detachdatabasesforwhichlogordifferentialbackupsareavailable
usingsp_detach_db.
StartSQLServernormally(without–f)
Foreachuserdatabasedetached{
RestoredatabasesnapshotwithNORECOVERY,REPLACE.
Applyconventionallogand/ordifferentialbackupsandrecover.
}
BACKUPStatementSyntax
BACKUPDATABASE{database_name|@database_name_var}TO<backup_device>[,...n][WITH[BLOCKSIZE={blocksize|@blocksize_variable}][[,]DESCRIPTION={text|@text_variable}][[,]DIFFERENTIAL][[,]EXPIREDATE={date|@date_var}|RETAINDAYS={days|@days_var}][[,]FORMAT|NOFORMAT][[,]{INIT|NOINIT}][[,]MEDIADESCRIPTION={text|@text_variable}][[,]MEDIANAME={media_name|@media_name_variable}][[,][NAME={backup_set_name|@backup_set_name_var}][[,]{NOSKIP|SKIP}][[,]{NOUNLOAD|UNLOAD}][[,][RESTART]
[[,]SNAPSHOT][[,]STATS[=percentage]]]
ThefollowingrestrictionsapplyiftheSNAPSHOToptionisgiven:
Thebackupdevicemustbeavirtualdevice.
Onlyasinglevirtualdevicemaybespecified.
Thefollowingoptionsmaynotbespecified:
DIFFERENTIAL
ItisexpectedthattheapplicationwillspecifyPIPE-likebehaviorforthevirtualdevice.Thismodeiswrite-onlyandimpliesFORMAT.Inanycase,thebehaviorofthecommandoptionswillbeasitistodayforVDI.
NoteForcompletedocumentationontheBACKUPstatement,seeSQLServerBooksOnline.
RESTOREStatementSyntax
RESTOREDATABASE{database_name|@database_name_var}[FROM<backup_device>[,...n]][WITH[DBO_ONLY][[,]FILE=file_number][[,]MEDIANAME={media_name|@media_name_variable}][[,]MOVE'logical_file_name'TO'operating_system_file_name'][,...n][[,]{NORECOVERY|RECOVERY|STANDBY=undo_file_name}][[,]{NOUNLOAD|UNLOAD}][[,]REPLACE][[,]RESTART]
[[,]SNAPSHOT][[,]STATS[=percentage]]]
TheSNAPSHOToptioninstructsRESTOREtoskipthedataandloglaydownphasesoftherestore,asthesnapshotwillbepresentondisk.Instead,restorewillissueaVDC_MountSnapshotcommandtotheVDIapplication.Successfulcompletionofthecommandindicatestobackupthatthedataandlogfilesareinplace.
ThefollowingrestrictionsapplyiftheSNAPSHOToptionisgiven:
Thebackupdevicemustbeavirtualdevice.
Onlyasinglevirtualdevicemaybespecified.
ItisexpectedthattheapplicationwillspecifyPIPE-likebehaviorforthevirtualdevice.Whatevermodeischosen,thebehaviorofthecommandoptionswillbe
consistentwithVDIbehavior.Inparticular,MOVEcanbeusedtoindicatethatanindividualfileisinadifferentlocationthanindicatedinthebackupsetmetadata.
NoteForcompletedocumentationontheRESTOREstatement,seeSQLServerBooksOnline.
ErrorCodesandLogsTheI/Ocompletioncodesarereturnedaspartofcommandcompletion.TheseareappropriateWIN32codes.
ThevirtualdevicemethodsreturntheCOMstandardofHRESULTS.ThecallercanuseSUCCEEDEDorFAILEDmacrostodetermineifthefunctionfailed.
ErrorsfromWIN32functionswillbeencodedasHRESULT_FROM_WIN32().ThisisdefinedinthefileWinerror.h.Anotherusefulfunction:GetScode()isalsodefinedinWinerror.h.TheGetScode()functioncanextractaWIN32statuscodefromaWIN32-HRESULT.
VDIerrormessagesarenowstoredintheWindowsapplicationeventlog.Lookforeventswiththesource"SQLVDI".AregkeyisavailabletoturnoffVDIerrorlogging:
underHKLM\Software\Microsoft\SQLVirtualDeviceInterface
CreateaREG_SZvaluewithname"LogFile",butleavethestringnull.
InSQLServer2000ServicePack4(SP4),thiskeycouldbeusedtoredirectVDI.LOGtoanotherlocation.
InSQLServer2005,thiskeyjustcontrolswhetherornotVDIerrorloggingisenabled.
Refertovdierror.hforthelistoferrors.
VD_E_SECURITY(0x80770005)Aprobleminitializingthesecurityenvironmentoccurred.Formoreinformation,checktheapplicationeventlog.
VD_E_INSTANCE_NAME(0x80770007)AninvalidinstancenamewaspassedtotheCreateExinterface.TheinstancenameisusedtoidentifytheSQLServerserviceaccountintheServiceControlManager.Verifythatavalidinstancenamewaspassedandthatnomachinenamewasincludedinthestring.
VD_E_UNEXPECTED(0x8077000B)AninternalerrorinSQLVDI.DLLhasoccurred.Checktheapplicationeventlogformoreinformation.
ConvertingApplicationsWrittenforPipesCurrently,anapplicationwrittentousenamedpipesmustperformbasicOpen,Close,Read,andWriteprocessingonapipe.WiththeVDI,theseoperationsareperformedwiththefollowingfunctioncalls:
Read
Write
Flush
ClearError
Initialization
Forpipes,theWIN32interfacesattempttoopenandwaitforthepipeinterfacetobecomeavailable:
while(1){h=CreateFile(<pipename>,OPEN_EXISTING...)if(h!=INVALID_HANDLE_VALUE)break;//continuewithactivephaseWaitNamedPipe(<someintervaloftime>)}
WiththeVDI,theclientobtainsaCOMinterface,createsthevirtualdeviceset,andthenwaitsfortheservertofinishconfiguringit:
VDConfigconfig;IClientVirtualDeviceSet2*vds;memset(&config,0,sizeof(config));config.deviceCount=1;CoCreateInstance(CLSID_MSSQL_ClientVirtualDeviceSet,NULL,CLSCTX_INPROC_SERVER,
IID_IClientVirtualDeviceSet2,&vds);vds->Create(<VDNAME>,&config)vds->GetConfiguration(&newConfig,timeout)
TheinvocationoftheBACKUPorRESTOREcommandwasnotshown.TheonlydifferenceinthecommandsyntaxistospecifyVIRTUAL_DEVICEratherthanpipeandthenamesofthedevicesthemselves.
ReadingorWritingWithpipes,theapplicationwillloop:
while(1){if(readingPipe)ReadFile(h,buf,maxBytes,&bytesRead)elseWriteFile(h,buf,numBytes,&bytesWritten)
switch(error){caseERROR_BROKEN_PIPE://theservercloseditsend,sowe'redonegotoexit;//breakwhileloop
caseERROR_MORE_DATA//moredatatoread;anormalsituationbreak;
default://unexpectederror//breakoutofwhileloopgotoexit;}
//dealwithbuffer,eitherwritingitsomewhere,//orreadthenextchunkfromsomewhere}exit://proceedwithtermination
WiththeVDI:
while(1){
errCode=vds->GetCommand(&cmd)switch(errCode){caseNOERROR://wegotacommandbreak;
caseVD_E_CLOSE://timetoclose//breakoutofloopgotoexit;
default://unexpectedgotoexit;}
compCode=ERROR_SUCCESS;bytesTransferred=0;switch(cmd.commandCode){caseRead://readbytesintocmd.Bufferbreak;
caseWrite://writebytesfromcmd.Bufferbreak;
caseFlush://flushtherealoutputdevicebreak;
caseClearError://simplyacknowledgingthecommand//issufficient
break;
default://unexpected,soabortvds->SignalAbort();gotoexit;}
vds->CompleteCommand(cmd,compCode,bytesTransferred,0);}exit://continuewithtermination
ThemainphaseofprocessingisslightlymorecomplicatedwiththeVDIthanwithpipes.NocomplexasynchronousI/Oprocessingisrequired.Asimplefetch,execute,andcompleteloopissufficient.Higherperformanceispossiblebyexploitinganasynchronousmodel.
GlossaryBLOCKSIZE
Thisisthesize,inbytes,thatisusedasthedeviceBLOCKSIZE.Alldatatransfersareinintegralmultiplesofthisvalue.Valuesmustbeapowerof2between512bytesand64kilobytes(KB)inclusive.Ifthisoptionisnotspecifiedwiththecommand,thenadefaultof512bytesisused.
TheBLOCKSIZEparameterisspecifiedintheWITHclauseoftheBACKUPandRESTOREstatements.Forexample:
BACKUPDATABASEpubstoVIRTUAL_DEVICE='...'WITHBLOCKSIZE=65536
BUFFERCOUNT
Thisisthetotalnumberofbuffers(ofsizeMAXTRANSFERSIZE)usedbytheBACKUPorRESTOREoperation.
TheBUFFERCOUNTparameterisspecifiedintheWITHclauseoftheBACKUPandRESTOREstatements.Forexample:
BACKUPDATABASEpubstoVIRTUAL_DEVICE='...'WITHBUFFERCOUNT=20
buffers
SharedbuffersareprovidedfromthevirtualdevicesettoMicrosoft®SQLServer™ondemand.Thesebuffersarereferencedbycommandsissuedtothevirtualdevices.Whilethecommandsarebeingprocessedbythedevice,thebuffersareinclientcontrol.Theserverwillnotreadorwritetothebufferwhilethecommandisoutstandingtotheclient.Theclientmayonlyreadorwritetothebuffer,orrememberthebuffer'saddress,fromthetimeitreceivesacommanduntilthetimeitcompletesthecommand.Whentheclientindicatesthatthecommandiscompleted,thenthebufferisimplicitlyreturnedtoSQLServercontrol.
datastream
Adatastreamisanorderedsequenceofbytesandfilemarks.
MAXTRANSFERSIZE
Thisisthesize,inbytes,ofthemaximuminputoroutputrequestthatisissuedbySQLServertothedevice.Thisisthesizeofthedataportionofthebuffer.Itdoesnotincludetheprefixzone,ifany.TheMAXTRANSFERSIZEmustbeamultipleof64KB.Therangeisfrom64KBthrough4megabytes(MB).Ifthisoptionisnotspecifiedwiththecommand,thenadefaultof64KBisused.
TheMAXTRANSFERSIZEparameterisspecifiedintheWITHclauseoftheBACKUPandRESTOREstatements.Forexample:
BACKUPDATABASEpubstoVIRTUAL_DEVICE='...'WITHMAXTRANSFERSIZE=524288
virtualdevice
Thevirtualdeviceisimplementedbytheclient.ItisusedbySQLServerasastoragedevice,likeanyotherdevice.DuringBACKUP,adatastreamiswrittentothedevice.DuringRESTORE,thedatastreamisreadfromthedevice.
ThenumberofdevicesusedduringaRESTOREwilltypicallybethesameasthatusedfortheBACKUP.ItispossibletousefewerdevicesduringRESTOREoperationsifthemediaisremovable.However,forremovablemedia,itispossibletousefewerdevices.Inthatcase,onceeachdatastreamhasbeenread,SQLServerrequestsanew,unprocesseddatastreambyissuingamountrequest.Formoreinformationaboutmediasets,backupsets,andmediafamilies,seeMicrosoftSQLServerBooksOnline.
VirtualDeviceInterface(VDI)
TheVDIisasetofComponentObjectModel(COM)interfaces.BehindtheinterfacesareCOMobjectsthatimplementthebehaviorofvirtualdevices.
virtualdeviceset
Thevirtualdevicesetisthetop-levelobjecttobemanipulatedbytheclientandserversidesoftheinterface.Theclientisresponsibleforcreatingthevirtualdeviceset.Theserveropensandconfiguresthevirtualdeviceset.