The Microsoft SQL Server Virtual Backup Device Specification · The SQL Server 2005 Virtual Backup...

MicrosoftSQLServerVirtualBackupDeviceSpecification

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.


ClientStateDiagramThisillustrationshowstheclientviewofthelifecycleofthevirtualdeviceset.


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—>


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—>


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

SignalAbort NOERROR—>AbortClose NOERROR—>DNE


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

_VIRTUAL_SERVER_NAME_astheinstancename.


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(


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

responsibleforinvokingIClientVirtualDevice2::CompleteCommandwhenthedatatransferiscomplete.


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(


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

occurred. VD_E_INVALID Aparameterwasinvalid.Remarks None


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_Rewind(x002)ThedevicemustsupporttheVDC_Rewindcommandtopositionatthestartofthedata.


VDF_Position(x010)ThedevicemustsupporttheVDC_GetPositionandVDC_SetPositioncommands.


VDF_SkipBlocks(x020)ThedevicemustsupporttheVDC_SkipBlockscommand.


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

subsequentGetCommandcall.


CommandDescriptionsThisisalistoftheVDIcommandsandadescriptionofeach.


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

VDC_Snapshot


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.


}


DisasterRecovery,MasterBackupNotAvailableTheentireserverisbeingrecoveredafteracatastrophicfailure.Acurrentconventionalbackupofmasterisnotavailable.Fulldatabasesnapshotsandconventionallogbackupsareavailableforsomeuserdatabases.

Steps

RestoreMicrosoft®SQLServer™service.(Thismayrequirerestorefromafilesystembackuporareinstall.)

Restartservernormally.

Recreateobjectsinmaster,butdonotcreateuserdatabasesforwhichtherearebackups(snapshotorconventional).

FixorrestoreMSDBandmodelasrequired.

Foreachdatabasetoberestored{

Restoredatabasewithnorecovery.


}


InitializeWarmStandbyThesnapshotisusedtoinitializethesecondarydatabaseonthestandbyserver.Onceinitialized,thestandbydatabasewillbemaintainedintheusualmannervialogshipping.

Steps

Restorethedatabasewithnorecoveryorstandby.

Maintaindatabasevialogshipping.


RestoreandRecoverDatabase,RelocatingFilesThedatabasemustberestored,buttheserverisfunctionalandotherdatabasesremainavailable.Therestorerequiresasnapshotrestorefollowedbyapplicationofoneormoretransactionlogbackups.Oneormorefilesmustberelocatedduetoadifferentmediareconfiguration.

Steps

Restorethedatabasewithnorecoveryandappropriatemoveoptions.



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.

}


Details


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_NOTOPEN(0x80770002)Thedeviceorvirtualdevicesetwasnotopen.


VD_E_TIMEOUT(0x80770003)Thespecifiedtime-outintervalelapsedbeforetheeventoccurred.


VD_E_ABORT(0x80770004)SignalAbortwasusedtoforceabnormaltermination.


VD_E_SECURITY(0x80770005)Aprobleminitializingthesecurityenvironmentoccurred.Formoreinformation,checktheapplicationeventlog.


VD_E_INVALID(0x80770006)Aninvalidparameterwassuppliedtotheinterfacereturningthiserror.


VD_E_INSTANCE_NAME(0x80770007)AninvalidinstancenamewaspassedtotheCreateExinterface.TheinstancenameisusedtoidentifytheSQLServerserviceaccountintheServiceControlManager.Verifythatavalidinstancenamewaspassedandthatnomachinenamewasincludedinthestring.


VD_E_NOTSUPPORTED(0x80770009)Theconfigurationisinvalidornotsupported.


VD_E_MEMORY(0x8077000A)Anout-of-memoryconditionhasoccurred.


VD_E_UNEXPECTED(0x8077000B)AninternalerrorinSQLVDI.DLLhasoccurred.Checktheapplicationeventlogformoreinformation.


VD_E_PROTOCOL(0x8077000C)Arequestwasmadethatisincompatiblewiththecurrentstateoftheobject.


VD_E_OPEN(0x8077000D)Alldeviceswerealreadyopen.


VD_E_CLOSE(0x8077000E)Theobjectwasclosed.


VD_E_BUSY(0x8077000F)Thedevicequeueisfull.


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.


TerminationCloseFile()isusedtoterminateusingpipes.

vds->Close()isusedtoterminateusingtheVDI.


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.


FindingMoreInformationFormoreinformationabouttheMicrosoft®SQLServer™BACKUPandRESTOREoperations,seethefollowingsources.

MicrosoftSQLServerBooksOnline

MicrosoftTapeFormat(MTF)specification

Sqlwriter.doc,VSSSDK.

Date post:	30-Jun-2019
Category:	Documents
Upload:	vuonglien
View:	256 times
Download:	1 times

The Microsoft SQL Server Virtual Backup Device Specification · The SQL Server 2005 Virtual Backup...

Documents