Copyright: Copyright ©1999 Xceed Software Inc.


Welcome to the Xceed Backup Library

 The Xceed Backup Library is an ActiveX control that allows Windows applications to automatically perform their own backup and restore operations. Xceed Backup can be added to existing projects with little or no coding, providing instant protection against lost or corrupted data files, end-user mistakes and hard drive crashes.

The Xceed Backup Library was created to provide exactly the features and functionality even the most complex applications need for backing up and restoring files. While a full featured compression library such as Xceed Zip will allow developers to code their own backup and restore routines for their apps, Xceed Backup allows developers to immediately achieve advanced results without having to spend any time coding and testing backup-oriented functionality themselves.

Xceed Backup speaks and thinks in backup terms. By setting the Xceed Backup ActiveX control's properties, developers tell it which files need to be backed up, where to back them up, and when the files should be backed up. The library does the rest. It can backup files to floppy disks, hard drives, network drives and any removable media your users may have, like "ZIP" disks or CD-RW. Backed up data is compressed and includes CRC-32 checksums to ensure data integrity.

Xceed Backup also provides complete file restoring facilities. Applications can find out what files are available for restoring and inform the library which files to restore, and the library takes care of finding the backup files, requesting the required disks or removable media if necessary, and restoring the files. When a file exists in multiple backups, the library allows restoring any version of the file. To help make the developer's task as easy as possible, the library includes a Recovery Wizard application, with source code, that can be included with the developer's application, so no coding is required in order to allow end-users to restore files.

Xceed Backup is a multi-threaded, fully self-contained ActiveX control. It's got a built-in scheduler, supports asynchronous (background) operation, and it can backup your application's data transparently without any end-user intervention or screen noise if desired.

Xceed Backup comes with support for any 32-bit development language that supports ActiveX controls. Xceed invites you to download the fully functional free trial version of the library and start adding backup and restore into one of your existing programs right away. All you really have to do is add a few controls to your splash screen or main form, fill out a few fields in dialog boxes or set a few properties, and off you go! Get it at http://www.xceedsoft.com.

All Xceed products include comprehensive online documentation, free expert technical support, royalty-free distribution and a 60-day money-back guarantee. If you're not satisfied for any reason, return the product for a full refund of the purchase price.

Xceed is devoted to the development and support of its developer products and is determined to pursue their evolution. That's a promise kept since Xceed's first library (Xceed Zip Compression Library) was introduced in 1995. Visit our web site at www.xceedsoft.com for up-to-date information on upgrades, add-on modules and wizards for Xceed Backup and other new Xceed developer tools.


Features of the Xceed Backup Library

•	Backup files to floppy disks, SuperDisks, hard drives, network drives, ZIP™ drives, JAZ™, Syquest™, SparQ™, writable CD, and most other removable media.

•	Full, incremental, differential and copy backup types

•	Backup and restore registry keys, Unicode filenames, NT file attributes, file times and security

•	Creates and manages backup catalogs for powerful file finding capability when restoring

•	Automatic log file creation with adjustable detail level

•	Built-in data compression with controllable compression level

•	Backups are created in an improved, yet 100%-PKZip compatible file format, so if required, files can be recovered with any typical unzipping application.

•	Intelligent job scheduling that compensates for missed backups

•	Verify backed up data

•	Full wildcard support, flexible subfolder search, excluded file lists

•	Partial or full restore, to original or redirected locations

•	Comes with a "Recovery Wizard" app. that you can include with your program to help end-users restore files - so you don't have to write your own restore code.

•	25+ intelligently designed events are triggered for complete application feedback and control. Use only those you need.

•	Use the ActiveX control programmatically or by dialog box property sheets

•	Multi-threaded, runs in the background

•	Supports physical label descriptions

•	Backup retention management

•	Light encryption using passwords

•	Recreate lost backup catalogs


About the free trial version

The free trial version of the Xceed Backup Library includes everything the registered version does, except that it does not allow you to distribute applications that were created using the trial version of the library. That means you get the complete Windows help with examples, sample applications with fully commented source codes and free technical support by email or telephone.

The trial version allows you to design, code and test applications that use Xceed Backup – as long as you don't try to distribute them to other machines. Only registered users are permitted to distribute applications that use Xceed Backup.

When you have decided that you like the product and will use it, all you have to do after you have purchased a registered copy is to install the registered package and recompile your application(s).

Please see the How to order section for ordering information.


Installation instructions index

Select the installation instructions for your language:

•	Installation instructions for Visual Basic 4.0 (32-bit)

•	Installation instructions for Visual Basic 5.0

•	Installation instructions for Visual Basic 6.0

•	Installation instructions for Visual C++ 4.0 (MFC)

•	Installation instructions for Visual C++ 5.0 (MFC)

•	Installation instructions for Visual C++ 6.0 (MFC)

•	Installation instructions for Word 97 and Excel 97

•	Installation instructions for Access 97

•	Installation instructions for Visual FoxPro 5.0 and 6.0

•	Installation instructions for Delphi 3.0

•	Installation instructions for Delphi 4.0

•	Installation instructions for C++ Builder 3.0

•	Installation instructions for C++ Builder 4.0

•	Installation instructions for other 32-bit development environments


Installation instructions for Visual Basic 4.0 (32-bit)

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and "register" the control with the operating system. The only thing left to do is to make the control available to your VB 4.0 projects. To do this, perform the following steps:

•	Start the 32-bit Visual Basic 4.0.

•	Select Custom Controls... from the Tools menu.

•	In the Show box, select the Controls checkbox.

•	An entry named "Xceed Backup Library" entry should appear in the "available controls" list.

•	Make sure the checkbox next to the "Xceed Backup Library " entry is selected. Click on the OK button and the 5 Xceed Backup control icons should now appear in your toolbox.

If the Xceed Backup Library entry is not in the "available controls" list, perform the following steps:

•	Try reinstalling the Xceed Backup Library from its setup program. Continue only if that didn't help.

•	Select the Browse... button from the Custom Controls dialog.

•	Find and select the XCEEDBKP.DLL file (use the one in the Windows System folder that was copied there by the setup program) then click on the OK button.

•	The library's entry should now appear in the components list.


Installation instructions for Visual Basic 5.0

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available to your VB 5.0 projects. To do this, perform the following steps:

•	Start Visual Basic 5.0.

•	Create a new project or open an existing one.

•	Select Components… from the Project menu.

•	An entry named "Xceed Backup Library " entry should appear in the components list.

•	In the Components dialog, make sure the "Xceed Backup Library " entry is checked in the components list. This will make it available for use in your applications.

•	Click the OK button. The 5 Xceed Backup control icons should now appear in the components toolbox.

If the Xceed Backup Library entry is not in the components list, perform the following steps:

•	Try reinstalling the Xceed Backup Library from its setup program. Continue only if that didn't help.

•	Click the Browse… button.

•	Find and select the XCEEDBKP.DLL file (use the one in the Windows System folder that was copied there by the setup program) then click on the OK button.

•	The "Xceed Backup Library " entry should now appear in the components list.


Installation instructions for Visual Basic 6.0

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available to your VB 6.0 projects. To do this, perform the following steps:

•	Start Visual Basic 6.0.

•	Create a new project or open an existing one.

•	Select Components… from the Project menu.

•	An entry named "Xceed Backup Library " entry should appear in the components list.

•	In the Components dialog, make sure the "Xceed Backup Library " entry is checked in the components list. This will make it available for use in your applications.

•	Click the OK button. The 5 Xceed Backup control icons should now appear in the components toolbox.

If the Xceed Backup Library entry is not in the components list, perform the following steps:

•	Try reinstalling the Xceed Backup Library from its setup program. Continue only if that didn't help.

•	Click the Browse… button.

•	Click on All files in the Files of type tab

•	Find and select the XCEEDBKP.DLL file (use the one in the Windows System folder that was copied there by the setup program) then click on the OK button.

The "Xceed Backup Library" entry should now appear in the components list.


Installation instructions for Visual C++ 4.0 (MFC)

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to create a wrapper class for your MFC projects (assuming you're working with MFC) and make the control available to your VC++ 4.0 projects. To do this, perform the following steps:

•	Start Visual C++ 4.0 (developer studio)

•	Open your MFC AppWizard application project, or create a new one by selecting the New... menu item from the File menu, and choosing the Project Workspace option. Select MFC AppWizard and follow the Wizards instructions to create the project. Be sure that you select the OLE Controls option for the question What OLE support would you like to include?

•	Select the Component... menu item from the Insert menu.

•	Select the OLE Controls tab in the Component Gallery dialog.

•	The 5 Xceed Backup control icons should appear in the list of controls displayed in the OLE Controls tab in the Component Gallery dialog.

•	Select the XceedBackup control icon, then click the Insert button in the Component Gallery dialog to insert the control in your project. The Confirm Classes dialog should appear.

•	Click OK to close the Confirm Classes dialog.

•	Click the Close button to close the Component Gallery dialog.

•	The XCEEDBKP.CPP and XCEEDBKP.H files should now be part of your project. You will now be able to instantiate the Xceed Backup Library objects in your project, and see the Xceed Backup Library icons available in your Controls toolbar when designing dialog boxes.

If the Xceed Backup control icon does not appear in the list of controls displayed in the OLE Controls tab in the Component Gallery dialog:

•	Try reinstalling the Xceed Backup Library from its setup program. Continue only if that didn't help. Select the Customize... button.

•	Select the OLE Controls category in the Customize Component Gallery dialog.

•	Select the Import... button in the Customize Component Gallery dialog.

•	Find and select the XCEEDBKP.DLL file (preferably the one in the Windows System folder that was copied there by the Xceed Backup Library setup program), then click on the OK button.

•	Click the OK button in the Customize Component Gallery dialog.

•	The Xceed Backup Library control icons should now appear in the list of controls.


Installation instructions for Visual C++ 5.0 (MFC)

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to create a wrapper class for your MFC projects (assuming you're working with MFC) and make the control available to your VC++ 5.0 projects. To do this, perform the following steps:

•	Start Microsoft Visual C++ 5.0

•	Open your MFC AppWizard application project, or create a new one by selecting the New... menu item from the File menu, then selecting the Projects tab and choosing the MFC AppWizard item. Follow the Wizards instructions to create the project. Be sure that you select the ActiveX Controls option for the question "What other support would you like to include?"

•	Select the Project menu

•	Select the Add to project submenu, then select Components and Controls...

•	In the Components and Controls Gallery dialog, look in the Registered ActiveX Controls folder for the "Xceed Backup Library" entry, then select it and click on the Insert button.

•	Select the OK in response to the Insert this component? message box. The Confirm Classes dialog should appear.

•	Click OK to close the Confirm Classes dialog.

•	Click the Close button to close the Components and Controls Gallery dialog.

The XCEEDBKP.CPP and XCEEDBKP.H files should now be part of your project. You will now be able to instantiate the Xceed Backup Library objects in your project, and see the Xceed Backup Library control icons available in your Controls toolbar when designing dialog boxes.


Installation instructions for Visual C++ 6.0 (MFC)

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available to your VC++ 6.0 projects. To do this, perform the following steps:

•	Start Microsoft Visual C++ 6.0

•	Open your MFC AppWizard application project, or create a new one by selecting the New... menu item from the File menu, then selecting the Projects tab and choosing the MFC AppWizard item. Follow the Wizards instructions to create the project. Be sure that you select the ActiveX Controls option for the question "What other support would you like to include?"

•	Select the Project menu

•	Select the Add to project submenu, then select Components and Controls...

•	In the Components and Controls Gallery dialog, look in the Registered ActiveX Controls folder for the "Xceed Backup Library" entry, then select it and click on the Insert button.

•	Select the OK in response to the Insert this component? message box. The Confirm Classes dialog should appear.

•	Click OK to close the Confirm Classes dialog.

•	Click the Close button to close the Components and Controls Gallery dialog.

•	The XCEEDBKP.CPP and XCEEDBKP.H files should now be part of your project. You will now be able to instantiate the Xceed Backup Library objects in your project, and see the Xceed Backup Library icons available in your Controls toolbar when designing dialog boxes.


Installation instructions for Word 97 and Excel 97

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available to your Word 97 projects. To do this, perform the following steps:

•	Start Word 97 or Excel 97.

•	Select the Visual Basic Editor option from the Macro submenu in the Tools menu or use the Alt+F11 shortcut.

•	In the Microsoft Visual Basic window, select the References… option from the Tools Menu.

•	Make sure the "Xceed Backup Library " entry is checked and then click on the OK button.

•	In the Microsoft Visual Basic window, select the UserForm option from the Insert menu.

•	If the Toolbox window is not visible, select the ToolBox option from the View menu.

•	Select the Additional Controls… option from the Tools menu.

•	In the Additional Controls dialog, make sure "Xceed Backup Library " is checked in the Available Controls list.

•	Click the OK button.

If there is no entry for Xceed Backup in the references dialog's list of available references:

•	Try reinstalling the Xceed Backup Library from its setup program. Continue only if that didn't help.

•	In the References dialog, click the Browse... button.

•	Find and select the XCEEDBKP.DLL file (preferably the one in Windows System which was placed there by the Xceed Backup Library setup program), then click on the Open button.

The "Xceed Backup Library" entry should now appear in the Available References listing in the References dialog.


Installation instructions for Access 97

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available to your Access 97 projects. To do this, perform the following steps:

•	Start Access 97.

•	Select the ActiveX Controls… option from the Tools menu

•	The "Xceed Backup Library " entry should appear in the Available Controls list of the ActiveX Controls dialog.

•	Click the Close button.

If the Xceed Backup Library entry does not appear in the list:

•	Try reinstalling the Xceed Backup Library from its setup program. Continue only if that didn't help.

•	In the ActiveX Controls dialog, click the Register... button.

•	Find and select the XCEEDBKP.DLL file (use the one in the Windows System folder that was copied there by the setup program) then click on the Open button.

The Xceed Backup Library entry should now be available the "Available Controls" list.


Installation instructions for Visual FoxPro 5.0 and 6.0

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available to your VFP 5.0 and 6.0 projects. To do this, perform the following steps:

•	Start Visual FoxPro 5.0 or 6.0

•	Select Options... from the Tools menu.

•	Select the Controls tab from the Options dialog.

•	Select the ActiveX controls checkbox.

•	The Xceed Backup Library entry should appear in the "selected:" listbox (still in the Controls tab of the Options dialog)

•	Now, to make the Xceed Backup Library's 5 separate controls available to your Visual FoxPro 5.0 projects, make sure the checkbox next to the "Xceed Backup Library " entry is selected. Click on the OK button and the 5 Xceed Backup control icons should now appear in the list of controls you can insert - for example, when using the OLE Container Object on a form.

If the Xceed Backup Library entry does not appear in the list of controls:

•	Try reinstalling the Xceed Backup Library from its setup program. Continue only if that didn't help.

•	Select the Add... button from the Controls tab of the Options dialog.

•	Find and select the XCEEDBKP.DLL file (preferably the one in the Windows System folder that was placed there by the Xceed Backup Library setup program), then click on the OK button.

•	The control's entry should now appear in the list.

Special note for Visual FoxPro 5.0 and 6.0: Xceed Backup Library events will be triggered only if you set "Application.AutoYield = .F." Place this code in the section of your main program where you set up your environment. If you only have a single form in your application that uses Xceed Backup, place "Application.AutoYield = .F." in the forms load method, and set it back to the default in the forms destroy method.


Installation instructions for Delphi 3.0

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available in your Delphi 3.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Apply the latest patches from Inprise to your copy of Delphi 3.0

•	Start Delphi 3.0

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Backup Library " item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBKP.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".DPK" file, and you'll probably want to put it with your other package files in your Delphi installation folder.

•	Click OK in the Install dialog

•	Delphi will then ask you to confirm the rebuild – click Yes in the Confirm dialog.

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

You have now succesfully installed the Xceed Backup ActiveX control in Delphi 3. The components should appear in your component toolbar (ActiveX or Xceed tabs).


Installation instructions for Delphi 4.0

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available in your Delphi 4.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Apply the latest patches from Inprise to your copy of Delphi 4.0

•	Start Delphi 4.0

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Backup Library " item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBKP.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".DPK" file, and you'll probably want to put it with your other package files in your Delphi installation folder.

•	Click OK in the Install dialog

•	Delphi will then ask you to confirm the rebuild – click Yes in the Confirm dialog.

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

You have now succesfully installed the Xceed Backup ActiveX control in Delphi 4. The components should appear in your component toolbar (ActiveX or Xceed tabs).


Installation instructions for C++ Builder 3.0

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBK.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available in your C++ Builder 3.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Apply the latest patches from Inprise to your copy of C++ Builder 3.0

•	Start C++ Builder 3.0

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Backup Library " item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBKP.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".BPK" file, and you'll probably want to put it with your other package files in your C++ Builder installation folder

•	Click OK in the install dialog

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

The components should now appear in the ActiveX tab of your component toolbar.


Installation instructions for C++ Builder 4.0

The Xceed Backup Library setup utility will copy all the necessary files to your system and place the XCEEDBKP.DLL in the Windows System folder and register it with the operating system. The only thing left to do is to make the control available in your C++ Builder 4.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Apply the latest patches from Inprise to your copy of C++ Builder 4.0

•	Start C++ Builder 4.0

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Backup Library " item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBKP.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".BPK" file, and you'll probably want to put it with your other package files in your C++ Builder installation folder

•	Click OK in the install dialog

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

The components should now appear in the ActiveX tab of your component toolbar.


Installation instructions for other 32-bit development environments

The Xceed Backup ActiveX control should be available in your language's list of available ActiveX controls. Normally, the component (XCEEDBKP.DLL) is copied to the Windows System folder by the Xceed Backup Library setup program and then "registered" with the operating system. Your language should automatically "see" the component. If it does not, then you may need to manually register the control. Before doing this, though, we strongly suggest that you reinstall your Xceed Backup Library using the setup program. This will ensure that it is licensed as well as being registered with the operating system. If that doesn't solve the problem, here's how to manually register the control:

•	From the Run option in the Windows 95/98 or Windows NT start menu, or from a command prompt, run the following command to register an OCX:

regsvr32 "path and filename of the xceedbkp.dll"

You will then see a message box that either displays "LoadLibrary failed" or displays "LoadLibrary succeeded". If you get the success message, then your ActiveX control is now registered on the machine and is ready for use by applications or in your development environment.


What must be distributed

You only need to distribute the XCEEDBKP.DLL file with your applications in order for the Xceed Backup Library to work.

It is highly recommended to place the XCEEDBKP.DLL file in the Windows System folder, with an installation program that does version checking, so that an already existing version of the DLL is not overwritten by an older version. Xceed Software will ensure that as long as the file keeps the XCEEDBKP.DLL name, it will always be backwards compatible with older versions. So applications compiled to work with Xceed Backup Library v1.0 will work with future versions of the DLL as well.

The XCEEDBKP.DLL file is fully self-contained, which means that target machines do not need any other files (such as MFC40.DLL or MSVCRT40.DLL for example) in order for XCEEDBKP.DLL to register and work on the machine. The early releases of Windows 95 (up to OSR1) require that you install the DCOM update or Internet Explorer v4.0.

Only registered users can deploy applications that use the Xceed Backup Library.


About the ActiveX component

The XCEEDBKP.DLL is a fully self-contained COM ActiveX control written entirely with ATL v3.0 and Visual C++ 6.0. There are no external dependencies required for its operation such as other DLLs.

The control's DLL file can be found in the "C:\PROGRAM FILES\XCEED BACKUP\BIN" directory, if you installed your Xceed Backup Library package in the default location.

The ActiveX control supports both the single-threaded apartment and the multi-threaded apartment models, and therefore will not work with Windows NT 3.51 because the DCOM extensions are not available for that operating system.

The control is digitally signed with Microsoft Authenticode technology, with VeriSign as the certificate verification authority. This ensures that the component has not been tampered or modified by parties other than Xceed Software, and is also useful when the component is used on web pages so that browsers do not complain about security issues.

Typically, applications that use ActiveX controls are distributed with an install or setup program that will also take care of registering the controls on the machine. If you aren't using a setup program, then you will have to manually register the component on the machine.

How to manually register the ActiveX component

The registration process referred to here is not related to licensing, it refers to the process of making the control known to the operating system. If you don't use an install program with this capability built-in, you can register your controls manually. From the Run option in the Windows 95 or Windows NT start menu, or from a command prompt, run the following command to register an ActiveX control:

regsvr32 "path and filename of the ActiveX control's DLL file"

You will then see a message box that either displays "LoadLibrary failed" or displays "LoadLibrary succeeded". If you get the success message, then the control is now registered on the machine and is ready for use by applications or in your development environment. If you get the failure message, make sure you specified a correct path and filename, and placed it in quotes if it has spaces in it.

Registration problems

If you are unable to register a fully-self contained ActiveX control on a target machine, even after following the instructions above, Xceed is currently aware of only one possible problem that may prevent proper registration of ActiveX controls. The problem applies to systems running the original release of Windows 95 or OSR1. If these machines don't have Internet Explorer v4.0 or up, then you will need to install DCOM 95 (available from Microsoft's web site) which will update the COM support for these machines.


About the sample applications

Currently, there are three sample applications provided. One for Delphi 4, one for VB6 and one for Visual C++ 6.0. More samples are on their way and will be added to the package as they become available. If you need a sample for a language not listed here, let us know – we may already have one ready but not officially released.

The samples can be found in the SAMPLES folder where you installed the library. Registered users of the library are permitted to modify the samples and to distribute them royalty-free.

Click one of the topics below for information on the corresponding sample application:

About the VB 6 sample

About the Delphi 4 sample

About the VC++ 6 sample


License, copyright and disclaimer

The use of this package indicates your understanding and acceptance of the following terms and conditions. This license shall supersede any verbal, or prior verbal or written, statement or agreement to the contrary. If you do not understand or accept these terms, or your local regulations prohibit "after sale" license agreements or limited disclaimers, you must cease and desist using this product immediately.

Copyright: This product is Copyright ©1999 Xceed Software Inc., all rights reserved. This product is protected by Canadian and United States copyright laws, international treaties and all other applicable national or international laws. This software product and documentation may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine readable form, without prior consent in writing, from Xceed Software Inc. and according to all applicable laws. The sole owner of this product is Xceed Software Inc.

Liability disclaimer: This product and/or license is provided as is, without any representation or warranty of any kind, either express or implied, including without limitation any representations or endorsements regarding the use of, the results of, or performance of the product, its appropriateness, accuracy, reliability, or correctness. The entire risk as to the use of this product is assumed by the user and/or licensee. Xceed Software Inc. does not assume liability for the use of this program beyond the original purchase price of the software. In no event will Xceed Software Inc. be liable for additional direct or indirect damages including any lost profits, lost savings, or other incidental or consequential damages arising from any defects, or the use or inability to use these programs, even if Xceed Software Inc. has been advised of the possibility of such damages.

Restrictions: You may not use, copy, modify, translate, or transfer the programs, documentation, or any copy except as expressly defined in this agreement. You may not attempt to unlock or bypass any "copy-protection" or authentication algorithm utilized by the program. You may not remove or modify any copyright notice, nor the About dialog or the method by which it may be invoked.

Operating license: You have the non-exclusive right to use any enclosed program only by a single person, on a single computer at a time. You may physically transfer the program from one computer to another, provided that the program is used only by a single person, on a single computer at a time. In group projects where multiple persons will use the program, you must purchase an individual license for each member of the group. Use over a "local area network" (within the same locale) is permitted provided that the program is used only by a single person, on a single computer at a time. Use over a "wide area network" (outside the same locale) is strictly prohibited under any and all circumstances.

Linking and distribution license: In order to link and distribute compiled Xceed Backup Library code, including the XCEEDBKP.DLL, in accordance to this license, you must be registered with Xceed Software Inc. as an authorized licensee. You may not reproduce or distribute copies of the complete package, any of the source, interface, code units or any license (.LIC) files, the LICENSE.TXT file, your private license key, any of the documentation, nor may you supply any means by which your users could create, modify, or incorporate the Xceed Backup Library in their own products. Violations will be prosecuted to the maximum extent possible under the law.

Back-up and transfer: You may make one copy of the program solely for "back-up" purposes, as prescribed by Canadian, United States, and international copyright laws. You must reproduce and include the copyright notice on the back-up copy. You may transfer the product to another party only if the other party agrees to the terms and conditions of this agreement, and completes and returns registration information (name, address, etc.) to Xceed Software Inc. within 30 days of the transfer. If you transfer the program you must at the same time transfer the documentation and back-up copy, or transfer the documentation and destroy the back-up copy. You may not retain any portion of the program, in any form, under any circumstance.

Terms: This license is effective until terminated. You may terminate it by destroying the program, the documentation and copies thereof. This license will also terminate if you fail to comply with any terms or conditions of this agreement. You agree upon such termination to destroy all copies of the program and of the documentation, or return them to Xceed Software Inc. for disposal.

Other rights and restrictions: All other rights and restrictions not specifically granted in this license are reserved by Xceed Software Inc.


Acknowledgments

Numega

Xceed Backup Library was extensively checked and processed with the help of Numega's BoundsChecker, TrueCoverage, TrueTime software and of course, lots of beta testing! BoundsChecker finds memory and resource leaks, checks API calls for accuracy, and finds a host of other potential problems. TrueCoverage makes sure every single line of code was tested. TrueTime allows you to find out what the bottlenecks are in your code and helps you optimize and fine tune your code for maximum speed. These products may not come cheap, but they're worth every penny.

Zlib

The compression and decompression algorithms used by the Xceed Backup Library are based on the Zlib library, written by Jean-Loup Gailly and Mark Adler. Zlib is a publicly available library that includes source code for the "deflate" compression and decompression algorithm. You can download it from the Zlib web site (if you are interested in it, we suggest you do a search on yahoo.com in order to make sure you have the latest web site address).

We wish to thank the members of the Zlib group for the outstanding contribution that they have provided the software community.

There are no extra charges or costs due to the use of the Zlib code in the Xceed Backup Library.

Blue Sky

This help documentation was created with RoboHelp Office. It is a very complete package that includes lots of time-saving tools, is very robust, and fully integrates with Microsoft Word.

Absolute Packager

	The Xceed Backup Library is packaged with a self-extracting zip file created by Absolute Packager, one of our own products. Absolute Packager itself internally uses the Xceed Zip Compression Library v3.5 and Xceed Zip Self-Extractor Module, which are also Xceed Software products!


Xceed Software's address, phones and email

You can contact us through any of the following:

	Internet Web site	info@xceedsoft.com (general inquiries) support@xceedsoft.com (technical support) www.xceedsoft.com
	Telephone Orders Fax	(450) 442-2626 (800) 865-2626 (450) 442-4604
	Mail	Xceed Software Inc. 1555 Boul. Jean-Paul Vincent Suite 180 Longueuil, Québec Canada  J4N 1L6


How to order Xceed Backup Library

To place an order

Contact Xceed Software directly using the (800) 865-2626 order line, fax/mail an Order Form, or use the secure online ordering system at www.xceedsoft.com. See the order form for pricing information.

If you are an established distributor or reseller and you wish to carry Xceed products, please contact us directly.

When ordering, please follow these simple guidelines

•	Print or type clearly. Do not assume we will know what city, state/province, or country you are in. This is especially important for foreign orders, where it is more difficult for us to guess what a city or state might be. For telephone or fax numbers, please include your country code, and/or make sure that the country is spelled out completely. Do not use abbreviations such as UK, DN, FR, etc. It will avoid confusion and greatly accelerate processing your order.

•	We can only accept credit cards, US or Canadian checks, and international bank drafts or money orders. Please do not send EuroChecks or request bank transfers. All checks must be drawn on a US or Canadian bank.

•	If you are sending a check or a bank draft, and this help file is more than 6 months old (past February 1999), please make sure that the price has not changed before you order.

•	If you send a bank draft, please do not have the bank send it automatically. You must include an order form with the bank draft.

•	If you order by credit card, please make sure you include all the details, including the card number, the expiration date, and the complete name on the card. Do not send a fax/letter asking us to call you for the card number. Call us directly if you do not want to include the card number on your fax.

•	Although we will always do our utmost to process your order as quickly as possible, it can sometimes take up to 48 hours. Please consider this when you place a rush order.

•	Finally, please note the time before you call and check the time difference between your time zone and ours. We are located in the Eastern standard time zone.

These few guidelines will help assure that everyone will get their order processed quickly and correctly.


Upgrades

We periodically provide bug fixes and upgrades for our products. Always check our Web site at www.xceedsoft.com for the latest information on the Xceed Backup Library.

Upgrade policy

Minor changes and bug fixes are free; major revisions carry an upgrade fee. If we release a major revision within 60 days of your purchase, and it is identically priced, we will provide the upgrade free of charge. Shipping and handling are always extra. We do not automatically inform you of minor fixes, only major revisions.

Upgrade pricing and purchasing

Purchasing an upgrade entitles you to 1 year's worth of unlimited minor and major upgrades. A year's worth of upgrades for the Xceed Backup Library costs $99 US.

The upgrade price applies to upgrades from any previous version of the Xceed Backup Library.

All upgrades and discounts must be obtained directly from Xceed Software Inc. See the How to Order topic.

Upgrade prices are subject to change without any prior notice.


Technical support

Before you contact us

In order to save everyone some time, we'd like you to do a few things before you contact us. We know the urge to call is great, but we'd appreciate it if you double check this list:

•	Have you consulted the Windows Help manual?

•	Have you used the search feature of the manual?

•	Have you looked at the sample application sources?

If you got this far, it must be a tough one. Maybe it's time to tell us about your problem. Start by noting down the language you are using, the version of the Xceed Backup Library, the exact error message (if any) or error code values you are getting, the operating system you are running your project on and a brief description of what you are trying to do. It would be a good idea to also note down exactly when the problem occurs.

How to contact us

The preferred method of contacting us for technical support is on the Internet. You can send any questions or problems to our Internet address: support@xceedsoft.com. Do not leave questions in newsgroups or on CompuServe forums as they probably won't be answered.

We also offer free telephone support on an "as available" basis, Monday through Friday usually from 9 a.m. to 5 p.m. Eastern standard time. Please note the time before you call and check the time difference between your time zone and ours. Sorry, we cannot return international calls.

Although there is currently no expiration date on free support, we reserve the right to restrict it to the first 90 days from the time of purchase, without any prior notice.


Year 2000 compliance

All of Xceed Software's active products have been tested and conform to Year 2000 compliance criteria.  Xceed Software products have no inherent dependencies on date/time, and to the best of our knowledge, will not be adversely affected by the internal computer clock setting prior to, during and after January 1, 2000.

All future software upgrades of the products, listed below, shall be placed under the scrutiny of Year 2000 compliance. Software tested includes:

•	Xceed Absolute Packager v1.0 and up

•	Xceed Zip Compression Library v3.0 and up

•	Xceed Zip Self-Extractor Module v1.0 and up

•	Xceed Backup Library v1.0 and up

Xceed Software does not provide contractual warranties or guarantees specific to Year 2000 readiness. Xceed Software product guarantees are set forth in the License Agreement section included in each of our manuals. We recommend that you read these agreements in order to fully understand your rights. Any information provided by Xceed Software regarding Year 2000 issues does not constitute an extension of any Xceed Software guarantee.

Please note that the Xceed Backup Library is a software development tool. We have no control over the ultimate quality or accuracy of products developed using our tools. Therefore, Xceed Software provides no guarantee whatsoever in connection with Year 2000 compliance of any software, application, or operating system developed by third parties using our products.


Contents

Introduction • Welcome to the Xceed Backup Library  • Features  • About the free trial version  • Installation instructions  Getting started quickly • Backup concepts  • Backing up files  • Performing schedule backups  • Restoring files  Xceed Backup controls reference • Overview  • Using the controls via property pages  • Formless use of the controls  • Running simultaneous operations  • FileSelection properties / methods   • BackupJob properties  • RestoreJob properties  • ScheduledJob properties  • XceedBackup properties / methods / events  • Error codes / Skipping reasons  • Enumerations	Deploying • What must be distributed  • About the ActiveX component  Samples • About the sample applications  Recovery Wizard • License, copyright and disclaimer  Legal information • License, copyright and disclaimer  • Acknowledgments  Contact and product information • Xceed Software's contact info  • Order form with pricing info  • How to order  • Upgrades  • Technical support  • Year 2000 compliance  Help file revision


Overview of the Xceed Backup controls

The Xceed Backup Library consists of five controls designed to make adding backup and restore capabilities to applications as easy as possible.

The controls work together to quickly allow you to configure, schedule and perform backup and restore operations. Their relationships are shown in the figure below.

	XceedBackup control This is main control. It checks for and runs scheduled jobs, provides methods for running jobs manually and triggers all the events.  Properties    Methods    Events  ScheduledJob control Lets you schedule jobs to be run automatically. Properties  BackupJob control Lets you configure a backup job. Properties   RestoreJob control Lets you configure a restore job. Properties  FileSelection control Lets you define a set of files and registry keys to be backed up or restored. Properties    Methods
How the controls work

The XceedBackup control can run jobs manually (just invoke the appropriate method whenever you want to run a job) or it can run jobs that have been scheduled. When running jobs manually, the XceedBackup control requires a job definition, which is provided by either the BackupJob or the RestoreJob control. To run scheduled jobs, XceedBackup relies on the ScheduledJob control's settings. In turn, the ScheduledJob control relies on the BackupJob or the RestoreJob control for job definitions. Finally, the FileSelection control is used by the BackupJob and the RestoreJob control to determine which files to backup or restore.

Resources

•	Error codes

•	Skipping reasons

•	Enumeration types

Getting started quickly

•	Backup concepts

•	Backing up files

•	Performing scheduled backups

•	Restoring files

Other information

•	Formless use of the controls

•	Running multiple operations at the same time


Backup concepts

Xceed Backup offers an organized backup system. You should be aware of the following subjects in order to make good use of the library's functionality. Click on any of the underlined terms for an explanation on what they mean.

Files

Various types of files are created and managed by the library which you should know about.

•	Backup files

•	Catalog files

•	Log files

Concepts

Xceed Backup offers functionality that makes use of many widely accepted backup concepts.

•	Jobs

•	Backup Sets

•	Backup Types

•	Retention management

•	Job Scheduling


Formless use of the controls

The Xceed Backup controls can be instantiated without putting them on a form. To do this, make the controls available in your development environment (this should already have been done if you followed the installation instructions) and simply create an instance of the required object(s) like you would any other variable. The object types are "XceedBackup", "FileSelection", "BackupJob", "RestoreJob" and "ScheduledJob".

Example for VB users:

' Make sure you have added the Xceed Backup Library to your object references. To do this, go to the Project menu and select the "References..." menu item, then checkmark the “Xceed Backup Library” entry in the list of components.

' Here we define the type for our variable

Dim WithEvents MyBackupInstance1 As XceedBackup

 ' Now we instantiate the variable with an Xceed Backup control instance

Set MyBackupInstance1 = New XceedBackup

 ' And now we can work as usual...

XceedBackup1.CatalogFolder = "c:\catalogs\"

...


Running multiple operations at the same time

The Xceed Backup Library ActiveX control supports both the Single-Threaded Apartment model (STA) and the Multi-Threaded Apartment model (MTA). The entire library's code is threadsafe and can be instantiated multiple times in order to perform multiple backup operations at the same time. The library is also designed to use very little memory per instance, so your machine won't run out of memory when you're running dozens of instances at the same time.

Background Processing

The library also supports background processing. Background processing is a different concept than running multiple instances simultaneously. See the BackgroundProcessing property topic for details.

Any restrictions?

Yes, two small restrictions. First: two or more instances may not use the same backup file located in the same folder.  Second: each instance of the Xceed Backup control can only execute one process at a time. This makes sense, because if it was possible for a single instance to run more than one operation at a time, you would get the same event from two processes and wouldn't know for which process you are getting the event. Running multiple simultaneous operations involves having multiple instances, with each instance running its own operation.

How is it done?

If you're using forms in your application, you can place multiple Xceed Backup control objects on your form, call them XceedBackup1, XceedBackup2, XceedBackup3, etc. Each control on the form is a separate instance of the library. Therefore, each instance's methods can be called simultaneously and can each process at the same time.

For example, place 4 Xceed Backup controls on a form, with 4 buttons, and 4 progress bars. For the click event of Button1, add code to backup up a file that refers to the XceedBackup1 control. Set Button1's caption to the return value so you can know when it finished. In the XceedBackup1 control's GlobalStatus event, set ProgressBar1's value to the nBytesPercent parameter provided to you by the GlobalStatus event. Do this 4 times, changing Button1 for Button2, XceedBackup1 for XceedBackup2, and ProgressBar1 for ProgressBar2. Make sure each instance works on a different backup file! Now run your program, and click on each button one after the other. If you are backing up enough files, each progress bar should be moving along at its own pace at the same time as the others.


Order form with pricing information

	XCEED SOFTWARE INC. 1555 Boul. Jean-Paul Vincent Suite 180 Longueuil, Québec Canada  J4N 1L6 Tel: (800) 865-2626 (Orders) Tel: (450) 442-2626 (Tech) Fax: (450) 442-4604	Fax Back Order Form (450) 442-4604
Please fill in the form below and send back for immediate service. Please print clearly.

Please note that your order will be charged in Canadian dollars at the current US dollar exchange rate.

Document revision 1000


FilesToExclude property
FilesToExclude property        (FileSelection control)

Example

Description

The FilesToExclude property lets you exclude specific files from the list of files provided to the FilesToProcess property.

The FilesToExclude property is used the same way as the FilesToProcess property:

•	Wildcards can be used in both the filename portion and the path portion.

•	Files can be specified either as a full path + filename or as a full path+wildcards.

•	When specifying multiple files to exclude, each file must be separated with the CR character (ASCII 13), the LF character (ASCII 10) , the CR+LF characters or the "|" character.

•	There's an AddFilesToExclude method equivalent of the AddFilesToProcess method.

•	You can append “<S>” or "<R>" to an entry to exclude all subfolders as well.

Data type

String

Default value

Empty


FilesToProcess property
FilesToProcess property        (FileSelection control)

Example

Description

The FilesToProcess property is used to provide a list of files to be backed up, restored, or browsed.

Each item in the FilesToProcess property list must be specified as a full path + filename, or as a full path + wildcards. Items must be separated with the CR character (ASCII 13),  the LF character (ASCII 10), the CR+LF characters or the vertical bar "|" character – your choice.

For each item in the FilesToProcess property, you can append "<S>" to it if you want subfolders to be scanned for matching filenames. Subfolders that don't contain matching filenames will not be preserved in the backup as folder entries, nor recreated back to real folders when restoring. Use "<R>" instead of "<S>" if you want to preserve the subfolder tree or you want the backed-up subfolder tree to be restored even though the subfolders contain no matching filenames.

The FilesToProcess property supports folder macros.

Data type

String

Default value

Empty

Tips

•	You can use the AddFilesToProcess method when you need to specify multiple files in the FilesToProcess property – it automatically handles the task of separating items with the return character.

•	You can use the FilesToExclude property if you want to exclude specific filenames or paths from the list of files you have specified in the FilesToProcess property.

•	Filenames or wildcards that do not match existing files to backup (or backed up files to restore) will be reported by the SkippingFile event with the bsrNoFilesMatched skipping reason.

•	If none of the filenames or wildcards specified in the FilesToProcess property match any existing files, the Backup or Restore methods will return the berNothingToDo result code.

•	Wildcard matching in the Xceed Backup Library can be used in both the filename portion and the path portion.


MaxDate property
MaxDate property        (FileSelection control)

Description

The MaxDate property lets you limit the processing of files to only those files that have a date and time stamp smaller than or equal to a specified date and time. This property affects the list of files specified in the FilesToProcess property.

Files that are skipped because they are newer than the date specified in the MaxDate property will be reported as skipped by the SkippingFile event (skipping reason: bsrDateRange).

This property can be used in conjunction with the MinDate property in order to provide a range of date and time stamps that should be processed.

Data type

Date

Possible values

Dates can range from 01/01/1900 to 31/12/9999

Default value

31/12/9999


MinDate property
MinDate property        (FileSelection control)

Description

The MinDate property lets you limit the processing of files to only those files that have a date and time stamp larger than or equal to a specified date and time. This property affects the list of files specified in the FilesToProcess property.

Files that are skipped because they are newer than the date specified in the MinDate property will be reported as skipped by the SkippingFile event (skipping reason: bsrDateRange).

This property can be used in conjunction with the MaxDate property in order to provide a range of date and time stamps that should be processed.

Data type

Date

Possible values

Dates can range from 01/01/1900 to 31/12/9999

Default value

01/01/1900


RegKeysToInclude property
RegKeysToInclude property        (FileSelection control)

Description

The RegKeysToInclude property lets you specify a list of registry keys to be backed up or restored.

Each item in the RegKeysToInclude property list must be specified as a full path to a registry key. Items must be separated with the CR character (ASCII 13),  the LF character (ASCII 10), the CR+LF characters or the vertical bar "|" character – your choice.

A registry key is always backed up and restored with all its subkeys and values.

Data type

String

Default value

Empty

Remarks

•	Registry values themselves can’t be specified in this property

•	You can use the AddRegKeysToInclude method when you need to specify multiple keys in the RegKeysToInclude property – it automatically handles the task of separating items with the return character.

•	The full path to a registry key must always be supplied. A key’s full path always begin with a predefined root key name (“HKEY_CLASSES_ROOT”, “HKEY_CURRENT_USER”, “HKEY_LOCAL_MACHINE”, “HKEY_USERS”, “HKEY_PERFORMANCE_DATA”, “HKEY_CURRENT_CONFIG”, ‘HKEY_DYN_DATA”)


AddFilesToExclude method
AddFilesToExclude method        (FileSelection control)

Description

The AddFilesToExclude method adds an item to the FilesToExclude property's list of files to exclude.

Declaration

Method AddFilesToExclude(sFileMask As String, bRecurse As Boolean)

Parameters

Parameter	Description

sFileMask	The item to add to the FilesToExclude property's list of files.

bRecurse	If True, “<R>” will be appended to the entry provided in sFileMask.

Return values

None

Remarks

AddFilesToExclude automatically handles separating items with the CR+LF characters. In fact, it performs the same work as the following line of (VB) code:

FileSelection1.FilesToExclude = FileSelection1.FilesToExclude + sFileMask + Chr(13) + Chr(10)


AddFilesToProcess method
AddFilesToProcess method        (FileSelection control)

Description

The AddFilesToProcess method adds an item to the FilesToProcess property's list of files to process.

Declaration

Method AddFilesToProcess(sFileMask As String, bRecurse As Boolean)

Parameters

Parameter	Description

sFileMask	The item to add to the FilesToProcess property's list of files.

bRecurse	If True, “<R>” will be appended to the entry provided in sFileMask.

Return values

None

Remarks

AddFilesToProcess automatically handles separating items with the CR+LF characters. In fact, it performs the same work as the following line of (VB) code:

FileSelection1.FilesToProcess = FileSelection1.FilesToProcess + sFileMask + Chr(13) + Chr(10)


AddRegKeysToInclude method
AddRegKeysToInclude method        (FileSelection control)

Description

The AddRegKeysToInclude method adds an item to the RegKeysToInclude property's list of registry keys to include.

Declaration

Method AddRegKeysToInclude(sRegKey As String)

Parameters

Parameter	Description

sRegKey	The item to add to the FilesToExclude property's list of registry keys.

Return values

None

Remarks

AddRegKeysToInclude automatically handles separating items with the CR+LF characters. In fact, it performs the same work as the following line of VB code:

FileSelection1.RegKeysToInclude = FileSelection1. RegKeysToInclude + sFileMask + Chr(13) + Chr(10)


BackupFolder property
BackupFolder property        (BackupJob control)

Description

The BackupFolder property specifies where the backup files for a backup job will be stored.

A new backup file is created whenever a backup job is run. Backup files are named automatically by the Xceed Backup control with the BACKUPSETNAME_TYPE_YYYYMMDD_HHMM.ZIP filename format. BackupSetName is the name specified in the BackupSetName property. Type is either FULL, COPY, INCR or DIFF as set by the BackupType property. When using the Backup method, the date and time portion represents the date and time when the method was called. For scheduled jobs, the date and time portion represents the date and time when the job was scheduled to be performed (as opposed to the date and time the job was actually performed).

The BackupFolder property supports folder macros.

Data type

String

Default value

Empty

Remarks

The BackupFolder property must not be empty when the backup job is launched, or the berMissingBackupFolder error will occur.


BackupType property
BackupType property        (BackupJob control)

Description

The BackupType property determines the backup type for a backup job.

Data type

bkpBackupType

Possible values

Value	Description (see Backup Types for explanations)

bbtFull (0)	The backup job will perform a full backup.

bbtCopy (1)	The backup job will perform a copy backup.

bbtIncremental (2)	The backup job will perform an incremental backup.

bbtDifferential (3)	The backup job will perform a differential backup.

Default value

bbtCopy


CompressionLevel property
CompressionLevel property        (BackupJob control)

Description

The CompressionLevel property controls the amount of compression to be applied to files being backed up. The greater the amount of compression applied, the greater the time it takes to perform the compression phase of a backup job.

Data type

bkpCompressionLevel

Possible values

Value	Meaning

bclNone (0)	No compression. Files are stored in the backup file as raw data.

bclLow (1)	Minimum compression. This setting takes the least amount of time to compress files. When compared to the bclMedium setting, this setting usually gives noticeably faster compression times in exchange for about 1 to 15% larger compressed files.

bclMedium (6)	Normal compression. This is the best balance between the time it takes to compress a file and the compression ratio achieved.

bclHigh (9)	Maximum compression. This setting achieves the best compression ratios that the compression algorithm is capable of producing. When compared to the bclMedium setting, this setting significantly increases compression time in exchange for about 1-3% smaller compressed files.

Default value

bclMedium


RetentionPeriod property
RetentionPeriod property        (BackupJob control)

Description

The RetentionPeriod property allows you to determine how long backup files should be kept in the folder specified by the BackupFolder property before being deleted. The value specified in the RetentionPeriod property represents the number of hours that must pass after the creation of a backup file before it can be deleted by the Xceed Backup's retention management system.

Retention management can be turned off, so that backup files are never deleted. See the bkpRetentionForever value below.

Data type

Long

Default value

bkpRetentionForever (-1)

Possible values

Value	Meaning

bkpRetentionForever (-1)	Backup files should never be deleted.

bkpRetentionOneDay (24)	Backup files can be deleted only after a full day has passed since their creation.

bkpRetentionOneWeek (168)	Backup files can be deleted only after a full week has passed since their creation.

Any other Long value	Number of hours which must pass after a backup file has been created before it can be deleted..


VerifyAfterBackup property
VerifyAfterBackup property        (BackupJob control)

VB Example

Description

The VerifyAfterBackup property lets you determine whether or not a newly created backup file should be verified for errors before its backup job is considered successful.

After each file is verified, the VerifiedFile event is triggered to provide information on the file just verified, and to let you know whether the file passed verification. Files that fail verification have the VerifiedFile event's bCorrupted parameter set to True, and generate a SkippingFile event that provides details on what went wrong.

If errors are detected, the ProcessCompleted event or the Backup method will return the berVerificationFailed error code.

Data type

Boolean

Default value

False

Remarks

•	Verification is done by rereading and uncompressing the backup file in memory, and then performing a CRC-32 check on the data to ensure its integrity (Backed up files are not compared bit-for-bit with the original files). The backup file's structure is also verified for errors.

•	When this property is set to True, the GlobalStatus event's behavior is modified. See the "remarks" section of that event's topic for details.


BackupSetName property        (RestoreJob control)

Description

The BackupSetName property indicates the backup set from which files should be restored by the restore job.

You must set the BackupSetName property to the same name provided to the BackupJob's BackupSetName property when you backed up the files you want to restore.

If you don't know the backup set name for files you want to restore, use the RecreateCatalogs method to obtain it.

Data type

String

Default value

Empty

Remarks

The BackupSetName property must not be empty when the restore job is launched, or the berMissingBackupSetName error will occur. Since the default value is empty, it is your responsibility to set it to the value you want.


PreservePaths property
PreservePaths property        (RestoreJob control)

Description

The PreservePaths property determines whether or not to restore files using the path information stored in the backup file. The PreservePaths property works in conjunction with the RedirectToFolder property in order to allow flexibility in choosing where to restore files. The table below provides details on how the properties work together:

Restore files to:	Property settings required:

Original locations	PreservePaths = True, RedirectToFolder = Empty

New location plus original paths	PreservePaths = True, RedirectToFolder = New path

New location without original paths	PreservePaths = False, RedirectToFolder = New path

Data type

Boolean

Default value

True

Remarks

•	If you set the PreservePaths property to False, you must provide a path to the RedirectToFolder property.

•	If False, all files will be restored in the folder specified by the RedirectToFolder property.


RedirectToFolder property
RedirectToFolder property        (RestoreJob control)

Description

The RedirectToFolder property allows you to restore files in a different location than the ones they were backed up from. The RedirectToFolder property works in conjunction with the PreservePaths property in order to allow flexibility in choosing where to restore files. The table below provides details on how the properties work together:

Restore files to:	Property settings required:

Original locations	PreservePaths = True, RedirectToFolder = Empty

New location plus original paths	PreservePaths = True, RedirectToFolder = New path

New location without original paths	PreservePaths = False, RedirectToFolder = New path

Data type

String

Default value

Empty

Remarks

The FilesToProcess property supports folder macros.


RestoreCorruptedFiles property
RestoreCorruptedFiles property        (RestoreJob control)

Description

The RestoreCorruptedFiles property specifies whether or not corrupted files should be restored when possible.

If this property is set to True, files being restored that fail the CRC-32 check will not be skipped, and will be restored even though they may be corrupted. Whenever a corrupted file is restored, the AfterRestoringFiles event's bCorrupted parameter will be equal to True.

Data type

Boolean

Default value

False

Remarks

•	If RestoreCorruptedFiles property is False, and a file being restored appears to be corrupted, the destination file (if it exists) will not be altered. The SkippingFile event will be triggered, with the bsrDamagedBackupFile skipping reason.

•	If RestoreCorruptedFiles is True, and a file being restored appears to be corrupted, the destination file (if it exists) will be replaced by the corrupted file.


RestoreSecurity property
RestoreSecurity property        (RestoreJob control)

Description

The RestoreSecurity property specifies if Windows NT file security information (permissions) should be recreated whenever a file is restored.

Data type

Boolean

Default value

True

Remarks

•	Windows NT file security information, if available, is always backed up. You decide if you want to restore it or not.

•	Windows NT file security information is valid throughout the same Windows NT domain. If you are restoring files backed up from another domain, Windows NT file security information cannot be recreated.


Selection property        (RestoreJob control)

Description

The Selection property identifies the FileSelection control that should be consulted in order to determine which files and/or registry keys to restore.

If the MinDate and MaxDate properties are left to their default values, the most recently backed up version of each file will be restored. If you want file(s) from a specific date range, use these properties to ensure the correct file(s) are restored.

Data type

Object: FileSelection

Default value

None

Remarks

The Selection property must be set to a valid FileSelection object when the restore job is launched.


BackupSetName property        (BackupJob control)

Description

The BackupSetName property indicates the backup set to which this backup job belongs.

Data type

String

Default value

Empty

Remarks

The BackupSetName property must not be empty when the backup job is launched. Since the default value is empty, it is your responsibility to set it to the value you want, otherwise the berMissingBackupSetName error will occur.


EncryptionPassword property        (BackupJob control)

Description

The EncryptionPassword property contains the password to be used for encrypting files being backed up. If this property is left empty, files will not be encrypted when being backed up.

Data type

String

Default value

Empty

Remarks

•	Passwords can be up to 80 characters long.

•	Passwords are case-sensitive.

•	The encryption algorithm used by the Xceed Backup Library is the same one used by the PKZip 2.04g program. This type of encryption can resist attacks by amateurs if the password is well chosen and long enough (at least 16 characters) but it will probably not resist attacks by determined users or experts. Therefore, we suggest that you always use long passwords, and when possible, do not rely solely on this encryption system to protect sensitive data.


Selection property        (BackupJob control)

Description

The Selection property identifies the FileSelection control that should be consulted in order to determine which files and/or registry keys to backup.

Data type

Object: FileSelection

Default value

None

Remarks

The Selection property must be set to a valid FileSelection object when the backup job is launched, otherwise the berNoSelection error will occur.


DaysOfWeek property
DaysOfWeek property        (ScheduledJob control)

Description

The DaysOfWeek property lets you select specific days of the week when a weekly scheduled job should be performed.

This property is ignored if the RecurrenceType property is not set to xotDaysOfWeek.

Data type

bkpDaysOfWeek

Default value

Empty


Job property
Job property        (ScheduledJob control)

Description

The Job property identifies the BackupJob or RestoreJob control that is being scheduled by the current instance of the ScheduledJob control.

Data type

Object: BackupJob or RestoreJob

Default value

Empty


RecurrenceType property
RecurrenceType property        (ScheduledJob control)

Description

The RecurrenceType property allows you to specify the timeframe between occurrences of a scheduled job. It also allows you to specify that a job should be scheduled to be performed only once. The RecurrenceType property works together with the RecurrenceInterval property, because it determines the size of the time units referred to by the RecurrenceInterval property.

Data type

xcdRecurrenceType

Possible Values

Value	Meaning

brtOnce (0)	The job is scheduled for a one-time execution only.

brtEveryNMinutes (1)	The job is scheduled to be performed once every N minutes.

brtEveryNHours (2)	The job is scheduled to be performed once every N hours.

brtEveryNDays (3)	The job is scheduled to be performed once every N days.

brtEveryNMonths (4)	The job is scheduled to be performed once every N months.

brtDaysOfWeek (5)	The job is scheduled to be performed every week, certain days of the week only. The days of the week to perform the job on are specified in the DaysOfWeek property.

Default value

xotOnce

Remarks

•	The N value is specified by the RecurrenceInterval property.

•	Keep in mind that the Xceed Backup scheduler must be started before it will start running scheduled jobs.


RecurrenceInterval property
RecurrenceInterval property        (ScheduledJob control)

Description

The RecurrenceInterval property lets you specify the actual number of time units that must pass before a recurring scheduled job is performed. The size of the time units is specified by the RecurrenceType property.

Data type

Long

Default value

0

Remarks

•	This property is ignored if the RecurrenceType property is set to xotOnce or xotDaysOfWeek.

•	Keep in mind that the Xceed Backup scheduler must be started before it will start running scheduled jobs.


Required property
Required property        (ScheduledJob control)

Description

The Required property allows you to specify that a job is absolutely required to be performed and that it must not be skipped. Setting Required to True marks a job as absolutely required. Setting Required to False marks a job as skippable.

Data type

Boolean

Default value

True

Details

Because scheduled jobs can only be run when the Xceed Backup scheduler has been started, it is possible that a job cannot be run at the specified scheduled time or period. With many applications, this is a common occurrence because the programs are running only during working hours, and often don't run when other applications are being used, on holidays, special occasions, etc.

Whenever the scheduler is started, it checks whether any scheduled jobs have been missed since the last time the scheduler was running. Jobs that have been missed (but specified as Required = False), are skipped and will only execute on the next occurrence time if applicable (see the RecurrenceType and RecurrenceInterval properties). Jobs that have been missed (but specified as Required = True) will be performed. If a recurring job has been missed more than once, it will only be performed once. If jobs from different BackupJob or RestoreJob configurations have been missed, the jobs will be performed starting with the oldest jobs first.


StartDate property
StartDate property        (ScheduledJob control)

Description

The StartDate property lets you specify the date and time that a scheduled job should be performed for the first time. If the scheduled job is a one-time job (i.e. the RecurrenceType property is set to xotOnce) then the StartDate property simply specifies the date and time to perform the job.

Data type

Date

Default value

01/01/1900 00:00

Remarks

•	When a scheduled job with the RecurrenceType property set to xotOnce has been performed, changing the StartDate property to a new date and time will cause the job to be performed again at the new date and time.

•	Keep in mind that the Xceed Backup scheduler must be started before it will start running scheduled jobs.


Abort property
Abort property        (XceedBackup control)

Description

The Abort property allows you to stop the execution of any currently running XceedBackup control method.

Data type

Boolean

Default value

False

Remarks

•	At any time during the execution of a method, setting the Abort property to True will cause the currently executing method to abort and return the berUserAbort value, which indicates that the abort was successful.

•	The Abort property is automatically set back to False whenever a new method is called.

•	In order to properly terminate the current operation, the response to the Abort property is not always instantaneous.

•	This property does not appear in property browsers at design-time.

Related topics

The CurrentOperation property lets you determine which, if any, XceedBackup method is currently executing.


BackgroundProcessing property
BackgroundProcessing property        (XceedBackup control)

Description

The BackgroundProcessing property controls whether or not the XceedBackup control's methods are executed immediately or are run as background processes.

Data type

Boolean

Default value

False

Remarks

•	This property is useful when you need methods to be executed asynchronously.

•	Normally this property is set to False, so method calls are not executed as background processes, and the entire operation is processed immediately and returns the real result code for the operation.

•	When the BackgroundProcessing property is set to True, the operation starts immediately. However, the result code is also immediately set to berProcessStarted, and the code following the method call is executed. When the method finally completes, the ProcessCompleted event is triggered, and provides the real result code for the operation, as well as statistics on the operation.

•	A separate thread is started by the library in order to accomplish asynchronous method execution.


CatalogFolder property
CatalogFolder property        (XceedBackup control)

Description

The CatalogFolder property specifies the folder where catalog files should be written to when backing up files and read from when restoring files.

A new catalog file is created whenever a backup job is run. Catalog files are named automatically by the XceedBackup control using the same convention as backup files (see the BackupFolder property), but have the ".CAT" filename extension. (See the BackupFolder property for the filename format)

The CatalogFolder property supports folder macros.

Data type

String

Default value

Empty

Remarks

•	If CatalogFolder is empty, <APPPATH>\BACKUPS\CATALOGS will be used.

•	Catalog files sizes can be foreseen if necessary with the following formula: approximately  82 + ( 3 * FilenameLength ) bytes per file in the backup, plus approximately 150 bytes for the catalog header. That means about 75K of catalog file size per 500 files backed up. The multiplier 3 is because Unicode filenames are stored in the catalog file, and the 82 bytes are file attribute, file permissions, CRC-32 and other file information.


CurrentOperation property
CurrentOperation property        (XceedBackup control)

Description

The CurrentOperation property indicates what the XceedBackup control is currently doing.

Data type

bkpCurrentOperation

Possible values

Value	Meaning

bcoIdle (0)	No method currently executing

bcoManualBackup (1)	Performing a backup job launched manually by a call to the Backup method.

bcoScheduledBackup (2)	Performing a backup job launched automatically by a ScheduledJob object.

bcoManualRestore (3)	Performing a restore job launched manually by a call to the Restore method.

bcoScheduledRestore (4)	Performing a restore job launched automatically by a ScheduledJob object.

bcoBrowseCatalogs (5)	Browsing catalog files (executing the BrowseCatalogs method).

bcoRecreateCatalogs (6)	Recreating catalog files (executing the RecreateCatalogs method).

Default value

bcoIdle

Remarks

This property is read-only and does not appear in property browsers at design-time.


LogDetailLevel property
LogDetailLevel property        (XceedBackup control)

Description

The LogDetailLevel property specifies the detail level of the information written into log files by the library when running jobs.

Data type

bkpLogDetailLevel

Possible values

Value	Meaning

bldNone (0)	No logging will occur.

bldSummary (1)	Log will contain the operation start/end dates, and a list of any major warnings or errors that occur.

bldSummaryWithFolders (2)	Log will contain the operation start/end dates, a list of any major warnings or errors that occur, and a list of all the folders that are processed.

bldGeneral (3)	Log will contain the operation start/end dates, a list of minor and major warnings or errors that occur, and a list of all the files and folders that are processed.

bldComplete (4)	Same as bldGeneral, but also includes many added notes that can be helpful for debugging purposes or for obtaining maximum information about every single event that occurred during an operation. This produces a tremendous amount of text when dealing with lots of files.

Default value

bldSummaryWithFolders

Related topics

The LogFolder property allows you to determine where log files should be created.


LogFolder property
LogFolder property        (XceedBackup control)

Description

The LogFolder property specifies the folder where log files should be generated by the XceedBackup control.

The Xceed Backup Library automatically manages log filenames. A new log filename is chosen (and the log file is created) during the first execution of a job after the LogFolder property has been set. Log files have the YYYYMMDD_HHMMSS.LOG filename format. The date and time in the filename represents the moment the log file was created. You can find out what the exact log filename is that the library is currently using by reading the value of the LogFilename (read-only) property.

The LogFolder property supports folder macros.

Data type

String

Default value

Empty

Remarks

If the LogFolder property is empty, <APPPATH>\BACKUPS\LOGS will be used.


ScheduledJobs property
ScheduledJobs property        (XceedBackup control)

Description

The ScheduledJobs property specifies a list of ScheduledJob controls that the library should consult in order to determine what jobs must be run by job scheduling system.

The list of ScheduledJob controls is constantly consulted by the XceedBackup control when the scheduler is has been started by the StartScheduler method. You can add and remove jobs from the list at any time.

Data type

Collection of ScheduledJob objects

How to use this data type

Collection properties have an Add and Remove submethod, as well as a Count subproperty. Here's how you would add two ScheduledJob objects to the ScheduledJobs property (VB code):

XceedBackup1.ScheduledJobs.Add(ScheduledJob1)

XceedBackup1.ScheduledJobs.Add(ScheduledJob2)

Default value

Empty collection


Backup method
Backup method        (XceedBackup control)

VB Example    Delphi Example

Description

The Backup method immediately launches a backup job. The backup job to run is provided by the xBackupJob parameter (see below).

Declaration

Method Backup(xBackupJob As BackupJob) As bkpError

Parameters

Parameter	Description

xBackupJob	BackupJob object representing the backup job that must be launched.

Return values

A return value of type bkpError is returned. Only the return value of berSuccess indicates that the method has been completed successfully. See the error codes topic for a list of other possible return values.

Applicable properties

Abort, BackgroundProcessing, CatalogFolder, CurrentOperation, LogDetailLevel, LogFolder

Events triggered

AfterBackingUpFile, BackingUpRegKey, BackupFileNotFound, BackupFileExpired, BeforeBackingUpFile, FileStatus, GlobalStatus, InsertMedia, MediaNotEmpty, OpenedFile, ProcessCompleted, StartingBackup, StartingVerify, SkippingRegKey, SkippingFile, VerifiedFile


BrowseCatalogs method
BrowseCatalogs method        (XceedBackup control)

VB Example    Delphi Example

Description

The BrowseCatalogs method allows you to search the backup catalog files for specific files or to obtain a detailed listing of files contained in the backup catalogs. The CatalogFolder property must be set in order to let the library know where to look for the catalog files.

Information on the backed up files is provided by the BrowsingCatalogEntry event, which is triggered once for each file, and offers information such as the date and time the file was backed up, its size, which media it is backed up on, which backup set it is part of, and more. You can display this information to your application's users if you wish, so that they can select the exact version(s) of the file(s) they want to restore.

If the sBackupSetName parameter (see below) is left empty, multiple catalog files will be consulted. Right before each catalog file's contents are listed, the BrowsingCatalog event is triggered for information purposes.

Declaration

Method BrowseCatalogs(xFileSelection As FileSelection, sBackupSetName As String) As bkpError

Parameters

Parameter	Description

xFileSelection	FileSelection object representing the files and/or registry keys that must be listed from the catalog files.

sBackupSetName	Name of the backup set for which the catalog files must be listed. If sBackupSetName is empty, all catalog files in the catalog folder are listed, regardless of the backup set to which they belong.

Return values

A return value of type bkpError is returned. Only the return value of berSuccess indicates that the method has been completed successfully. See the error codes topic for a list of possible return values.

Remarks

The berNoCatalogFilesFound result code can be returned if there is a problem finding the catalog files.

Applicable properties

CatalogFolder

Events triggered

BrowsingCatalog, BrowsingCatalogEntry, GlobalStatus, ProcessCompleted


GetErrorDescription method
GetErrorDescription method        (XceedBackup control)

Description

The GetErrorDescription method returns a text description of a bkpError or a bkpSkippingReason enumeration member.

For example, to assign the description of the berMoveFile (value 1527) error to a string, do this:

DescribeError = XceedBackup1.GetErrorDescription(bvtError , berMoveFile);

or even

DescribeError = XceedBackup.GetErrorDescription(0, 1527);

Declaration

Method GetErrorDescription(xValueType As bkpValueType, lValue As Long) As String

Parameters

Parameter	Description

xValueType	Specifies the enumeration type for the error code passed in the lValue parameter.

lValue	Value of the enumeration member for which you want to get a text description.

Return values

Returns the string containing the text description. If a non-existent member value is passed in the lValue parameter, an empty string will be returned.

Remarks

This method is particularly useful in order to translate an error or skipping reason code into English text in order to display a more detailed error message than just the numeric code itself.


License method
License method        (XceedBackup control)

Description

The License method must be called to license the XceedBackup control for runtime use when you are instantiating it dynamically. This applies, for example, when using VB's CreateObject() call or the COM API call CoCreateInstance(). You do not have to call the License method when the control is placed on a form or if you are instantiating the control with the following VB code:

Dim WithEvents MyBackupInstance As XceedBackup

Set MyBackupInstance = New XceedBackup

Declaration

Method License(sLicense As String) As Boolean

Parameters

Parameter	Description

sLicense	Your license key. Only registered users have a license key, which can be found in the LICENSE.TXT file located in the folder where the registered Xceed Backup Library package was installed. Users of the free trial version do not need to call the License method, because it is only required for applications that are being distributed, and the free trial version is intended to be used only on the development machine for evaluation purposes.

Return values

Returns True if the license key was accepted, False if the license key was invalid.

Remarks

•	The License method should be the first method you call after manually instantiating the XceedBackup control.

•	If you do not call this method when dynamically instantiating the control with CreateObject(), CoCreateInstance(), or similar methods of instantiating an object, all XceedBackup methods will not work and will immediately return the berNotLicensed error code.

•	When the control is being used on an HTML document with the <OBJECT> tag, a License Package File (LPK) should be used to provide the license key. You can obtain more information and an LPK creation kit from http://www.microsoft.com/workshop/components/activex/licensing.asp#LPKFILES or from http://www.microsoft.com/gallery/tools/lpktool/lpktool.asp.

•	The License method is required because instantiation methods such as CreateObject() and CoCreateInstance() do not cooperate with the standard COM licensing scheme provided by IClassFactory2.


RecreateCatalogs method
RecreateCatalogs method        (XceedBackup control)

VB Example

Description

The RecreateCatalogs methods allows to recreate catalog files from backup files.

Details

Catalog files are necessary in order to perform a restore job. If your catalog files have been deleted, this method can recreate them.

Declaration

Method RecreateCatalogs(sBackupSetName As String, sBackupFolder As String) As bkpError

Parameters

Parameter	Description

sBackupSetName	Name of the backup set for which the catalog files must be recreated. If sBackupSetName is empty, catalogs for all backup files in sBackupFolder are recreated, regardless of the backup set to which they belong.

sBackupFolder	Backup folder that must be scanned for backup files for which catalogs must be recreated.

Return values

A return value of type bkpError is returned. Only the return value of berSuccess indicates that the method has been completed successfully. See the error codes topic for a list of possible return values.

Remarks

•	Right before each catalog file is recreated, the RecreatingCatalog event is triggered.

•	For each entry being added to a catalog file, the RecreatingCatalogEntry event is triggered.

•	The berNoBackupFilesFound result code can be returned if there is a problem finding the backup files.

Events triggered

GlobalStatus, InsertMedia, ProcessCompleted, RecreatingCatalog, RecreatingCatalogEntry, SkippingBackupFile, SkippingCatalogFile


Restore method
Restore method        (XceedBackup control)

VB Example    Delphi Example

Description

The Restore method immediately launches a restore job. The restore job to run is provided by the xRestoreJob parameter (see below).

Declaration

Method Restore(xRestoreJob As RestoreJob ) As bkpError

Parameters

Parameter	Description

xRestoreJob	RestoreJob object representing the restore job that must be launched.

Return values

A return value of type bkpError is returned. Only the return value of berSuccess indicates that the method has been completed successfully. See the error codes topic for a list of possible return values.

Events triggered

AfterRestoringFile, BeforeRestoringFile, FileStatus, GlobalStatus, InsertMedia, InvalidPassword, ProcessCompleted, ReplacingRegKey, ReplacingFile, RestoringRegKey, SkippingCatalogFile, SkippingFile, SkippingRegKey, StartingRestore


BackingUpRegKey event
BackingUpRegKey event        (XceedBackup control)

Description

The BackingUpRegKey event is triggered for each registry key added to the backup file.

Declaration

Event BackingUpRegKey(sRegKey As String)

Parameters

Parameter	Description

sRegKey	Registry key being backed up.


AfterBackingUpFile event
AfterBackingUpFile event        (XceedBackup control)

Description

The AfterBackingUpFile event is triggered once for each file being backed up, right after the file has been added to the backup file. The event provides information on the file just backed up, including which disk the file was written to if applicable.

Declaration

Event AfterBackingUpFile(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number where this file ends. (This parameter is 0 when writing to non-removable media)


AfterRestoringFile event
AfterRestoringFile event        (XceedBackup control)

Description

The AfterRestoringFile event is triggered after a file has been restored. The event provides information on the file just restored.

Declaration

Event AfterRestoringFile(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long, bCorrupted As Boolean)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number where this file ends.

bCorrupted	Indicates if the file has been restored in a corrupted state. This parameter can be True only when the RestoreCorruptedFiles property of the RestoreJob control was True.


BackupFileExpired event
BackupFileExpired event        (XceedBackup control)

Description

The BackupFileExpired event is triggered when an expired backup file has been found in the backup folder of a backup job that is about to be performed.

Declaration

(Parameters in bold are modifiable)

Event BackupFileExpired(sBackupFilename As String, sBackupSetName As String, xBackupType As bkpBackupType, dtBackupDate As Date, dtExpirationDate As Date, bLatestOfThisType As Boolean, bKeepBackup As Boolean)

Parameters

Parameter (Modifiable)	Description

sBackupFilename	Name of the expired backup file.

sBackupSetName	Backup set to which the expired file belongs.

xBackupType	Backup type of the expired backup file.

dtBackupDate	Date at which the expired backup was performed.

dtExpirationDate	Date at which the backup expired.

bLatestOfThisType	Indicates if the expired backup file is the latest of it’s type for the backup set to which it belongs.

bKeepBackup (YES)	If you want to keep the backup file anyway, set this parameter to True. If you want it to be deleted, set this parameter to False. By default, it is False.


BeforeBackingUpFile event
BeforeBackingUpFile event        (XceedBackup control)

Description

The BeforeBackingUpFile event is triggered before a file is added to the backup file. The event provides information on the file about to be backed up.

Declaration

Event BeforeBackingUpFile(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number where the file begins.


BeforeRestoringFile event
BeforeRestoringFile event        (XceedBackup control)

Description

The BeforeRestoringFIle event is triggered before a file is restored. The event provides information on a file about to be restored.

Declaration

Event BeforeRestoringFile(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number where the file begins.


BrowsingCatalog event
BrowsingCatalog event        (XceedBackup control)

VB Example    Delphi Example

Description

The BrowsingCatalog event is triggered when a catalog file is about to be listed. The event provides various types of information on the backup that was performed when this catalog was created.

Declaration

Event BrowsingCatalog(sBackupSetName As String, xBackupType As bkpBackupType, sBackupFilename As String, dtBackupDate As Date, dtExpirationDate As Date, sMediaLabelPattern As String, bEncrypted As Boolean)

Parameters

Parameter	Description

sBackupSetName	Backup set to which the catalog file belongs.

xBackupType	Type of the backup to which the catalog file relates.

sBackupFilename	Name of the file of the backup to which the catalog file relates.

dtBackupDate	Date of the backup to which the catalog file relates.

dtExpirationDate	Expiration date of the backup to which the catalog file relates.

sMediaLabelPattern	Media label pattern of the backup to which the catalog file relates.

bEncrypted	Indicates if the backup to which the catalog file relates is password-encrypted.


BrowsingCatalogEntry event
BrowsingCatalogEntry event        (XceedBackup control)

VB Example    Delphi Example

Description

The BrowsingCatalogEntry event is triggered when an entry from a catalog file is being listed. This event provides information on the backed up file or folder being listed, including which disk number the file is located on if applicable.

Declaration

Event BrowsingCatalogEntry(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long, sMediaLabel As String)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number where this file can be found.

sMediaLabel	Physical label of the media on which this file can be found.


FileStatus event
FileStatus event        (XceedBackup control)

Description

The FileStatus event provides a status report on the processing of a given file. It is triggered throughout the processing of each file as a result of calling the Backup or Restore methods. The event provides information on the file's size, as well as how many bytes have been processed and the percentage of completion.

The FileStatus event is triggered for every 32K of uncompressed data that has been processed for the current file. If the file size is less than 32K, this event will only be triggered once.

None of the parameters provided by the FileStatus event are modifiable.

Declaration

Event FileStatus(sFilename As String, lSize As Long, lBytesProcessed As Long, nPercentCompleted As Integer)

Parameters

Parameter	Description

sFilename	Name of the file being processed.

lSize	Size of the file, in bytes.

lBytesProcessed	Number of bytes processed for this file.

nPercentCompleted	The completion percentage of this file (from 0% to 100%).

Remarks

When a file has been completely processed, the lBytesProcessed parameter equals the lSize parameter.

To get statistics on the entire group of files being processed, use the GlobalStatus event.


GlobalStatus event
GlobalStatus event        (XceedBackup control)

Description

The GlobalStatus event provides a status report on the group of files currently being processed.

The GlobalStatus event is triggered for every 32K of uncompressed data that has been processed for the entire group of files being processed. This event provides various statistics related to the group of files being processed.

None of the parameters provided by the GlobalStatus event are modifiable.

Declaration

Event GlobalStatus(lFilesTotal As Long, lFilesProcessed As Long, lFilesSkipped As Long, nFilesPercent As Integer, lBytesTotal As Long, lBytesProcessed As Long, lBytesSkipped As Long, nBytesPercent As Integer)

Parameters

Parameter	Description

lFilesTotal	The total number of files to process.

lFilesProcessed	The number of files that have been processed so far.

lFilesSkipped	The number of files that have been skipped so far.

nFilesPercent	The completion percentage (0% to 100%) based on how many files have been processed so far.

lBytesTotal	The total number of bytes to process for the entire group of files.

lBytesProcessed	The total number of bytes that have been processed so far for the entire group of files.

lBytesSkipped	The total number of bytes that have not been processed due to files that have been skipped.

nBytesPercent	The completion percentage (0% to 100%) based on the amount of bytes processed so far.

Remarks

•	To get statistics on individual files, as opposed to the entire group of files being processed, use the FileStatus event.

•	The BackupJob object's VerifyAfterBackup property causes two processes to occur: one backup phase and one verification phase. GlobaStatus counters and percentages are reset after the backup phase, so they start over for the verification phase. During the verification phase, lFilesTotal signifies the total amount of files that are to be verified. The lFilesTotal parameter may therefore be smaller during the verification phase due to the fact that some files may have been skipped during the backup phase. The ProcessCompleted event's lFilesTotal parameter shows the total number of files verified.


InsertMedia event
InsertMedia event        (XceedBackup control)

Description

The InsertMedia event is triggered whenever a new or different removable media is required to be inserted in a drive so that the current operation can proceed.

Use this event to display a custom message or dialog box to end-users.

Declaration

(Parameters in bold are modifiable)

Event InsertMedia(sMediaLabel As String, lDiskNumber As Long, bMediaInserted As Boolean)

Parameters

Parameter (Modifiable)	Description

sMediaLabel	Physical label of the media that is being requested.

lDiskNumber	Disk number requested.

bMediaInserted (YES)	Set this parameter to True to confirm that the appropriate disk is in the drive. If you leave it to its default value of False, the current operation will terminate and return berInsertMediaAbort.


InvalidPassword event
InvalidPassword event        (XceedBackup control)

Description

The InvalidPassword event is triggered when restoring encrypted files that cannot be decrypted with the password found in the EncryptionPassword property of the RestoreJob control. The event lets you provide a new password to use in order to decrypt the files.

Declaration

(Parameters in bold are modifiable)

Event InvalidPassword(sBackupFilename As String, sPassword As String, bPasswordProvided As Boolean)

Parameters

Parameter (Modifiable)	Description

sBackupFilename	Name of the backup file for which the password is invalid.

sPassword (YES)	Set this parameter to the new password that should be tried.

bPasswordProvided (YES)	Set this parameter to True if you have provided a new password. Leaving this parameter to False (the default value it has when the event is triggered) will cause the file to be skipped.


MediaNotEmpty event
MediaNotEmpty event        (XceedBackup control)

Description

The MediaNotEmpty event is triggered when creating a backup file on a removable media that already contains data. The event allows you to tell the library what to do, such as to completely erase the media and proceed with the backup, to abort the job, to ignore the other data or to ask for another media.

Declaration

(Parameters in bold are modifiable)

Event MediaNotEmpty(bContainsBackup As Boolean, sMediaLabel As String, xAction As bkpNotEmptyAction)

Parameters

Parameter (Modifiable)	Description

bContainsBackup	Indicates if the media contains other backup files created by the Xceed Backup Library.

sMediaLabel	Physical label of the media that is currently in the drive, if one could be found.

xAction (YES)	The action to take.

Set to bnaErase to completely erase the media and proceed with the backup.

Set to bnaAppend to create the backup file on the media without affecting the existing files.

Set to bnaAskAnother to instruct the library to ask another media by triggering an InsertMedia event. This is the default action.

Set to bnaAbort to abort the backup job.


OpenedFile event
OpenedFile event        (XceedBackup control)

Description

The OpenedFile event is triggered when trying to backup a file that is opened by another process or application. The event provides information on the file and allows you to instruct the library on what action to take.

Declaration

(Parameters in bold are modifiable)

Event OpenedFile(sFilename As String, lSize As Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, xAction As bkpOpenedFileAction)

Parameters

Parameter (Modifiable)	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

xAction (YES)	The action to take.

Set to bnaSkip to skip the file. This is the default action.

Set to bnaRetry to try to open the file again.

Set to bnaRetryShareWrite to try to open the file with shared write access.*

Remarks

When backing up files, the library always opens the files for read access, with shared read access. This means that the file will be successfully opened only if is not opened for write access by another process. It will also deny other processes to open the file with write access while the file is being backed up. This ensures that the file is not tampered while it is being added to the backup.

When you set xAction to bnaRetry, the library will try to open the file again with the same access scheme. If it still does not work, another OpenedFile event will be triggered.

When you set xAction to bnaRetryShareWrite, the library will try to open the file with shared read and write access. This means that the file will be successfully opened even if it is opened for write access by another process. If it does not work, the file will be skipped.

* Setting xAction to bnaRetryShareWrite allows you to backup files that would not be backed up normally, but be aware that the integrity of the backed up file can’t be guaranteed.


ProcessCompleted event
ProcessCompleted event        (XceedBackup control)

Description

The ProcessCompleted event is triggered whenever a method has completed its processing. This event provides statistics about the completed operation similar to those provided by the GlobalStatus event.

Declaration

Event ProcessCompleted(lFilesTotal As Long, lFilesProcessed As Long, lFilesSkipped As Long, lBytesTotal As Long, lBytesProcessed As Long, lBytesSkipped As Long, xResult As bkpError)

Parameters

Parameter	Description

lFilesTotal	The total number of files that needed processing.

lFilesProcessed	The number of files that have been processed.

lFilesSkipped	The number of files that have been skipped.

lBytesTotal	The total number of bytes for the entire group of files that needed processing.

lBytesProcessed	The total number of bytes that have been processed for the entire group of files.

lBytesSkipped	The total number of bytes that have not been processed due to files that have been skipped.

xResult	The result code returned by the method.

Remarks

In your handler for the ProcessCompleted event, the CurrentOperation property allows you to find out which method just completed.


RecreatingCatalog event
RecreatingCatalog event        (XceedBackup control)

Description

The RecreatingCatalog event is triggered when a catalog file is about to be recreated from a backup file. The event provides information on the backup files whose catalog is about to be created.

Declaration

Event RecreatingCatalog(sBackupSetName As String, xBackupType As bkpBackupType, sBackupFilename As String, dtBackupDate As Date, dtExpirationDate As Date, sMediaLabelPattern As String, bEncrypted As Boolean)

Parameters

Parameter	Description

sBackupSetName	Backup set to which the catalog file belongs.

xBackupType	Type of the backup to which the catalog file relates.

sBackupFilename	Name of the file of the backup to which the catalog file relates.

dtBackupDate	Date of the backup to which the catalog file relates.

dtExpirationDate	Expiration date of the backup to which the catalog file relates.

sMediaLabelPattern	Media label pattern of the backup to which the catalog file relates.

bEncrypted	Indicates if the backup to which the catalog file relates is password-encrypted.


RecreatingCatalogEntry event
RecreatingCatalogEntry event        (XceedBackup control)

Description

The RecreatingCatalogEntry event is triggered right before an entry (file or folder) in the current catalog being recreated is added to the catalog. The event provides information on the catalog entry.

Declaration

Event RecreatingCatalogEntry(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long, sMediaLabel As String)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number where this file can be found.

sMediaLabel	Physical label of the media on which this file can be found.


ReplacingFile event
ReplacingFile event        (XceedBackup control)

Description

The ReplacingFile event is triggered when a file being restored is about to overwrite an already existing file with the same name. The event provides information on both the existing file, and the file about to be written. The event also allows you to tell the library to skip the file so that the existing file is not overwritten.

Declaration

(Parameters in bold are modifiable)

Event ReplacingFile(sFilename As String, lExistingSize As Long, xExistingAttributes As bkpFileAttributes, dtExistingLastModified As Date, dtExistingLastAccessed As Date, dtExistingCreated As Date, lSize As Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long, bSkipFile As Boolean)

Parameters

Parameter (Modifiable)	Description

sFilename (YES)	Fully-qualified name of the file. Changing this parameter allows you to rename the file being restored to another path and/or filename if you don't want to replace the already existing file.

lExistingSize	Size of the existing file, in bytes.

xExistingAttributes	Attributes of the existing file.

dtExistingLastModified	Last modification date of the existing file.

dtExistingLastAccessed	Last access date of the existing file.

dtExistingCreated	Creation date of the existing file.

lSize	Size of the file being restored, in bytes.

xAttributes	Attributes of the file being restored.

dtLastModified	Last modification date of the file being restored.

dtLastAccessed	Last access date of the file being restored.

dtCreated	Creation date of the file being restored.

lDiskNumber	Disk number from which the file is being restored.

bSkipFile (YES)	Set this parameter to True if you don't want the library to overwrite the already existing file. Leave it to False if you want the file replaced, or if you are renaming the path and file. By default, this parameter is False, so files are automatically overwritten.


ReplacingRegKey event
ReplacingRegKey event        (XceedBackup control)

Description

The ReplacingRegKey event is triggered when a registry key being restored is about to overwrite an existing registry key. The event allows you to tell the library what to do, such as to overwrite the existing key, to merge the keys or to skip the key.

Declaration

(Parameters in bold are modifiable)

Event ReplacingRegKey(sRegKey As String, xAction As bkpReplacingRegKeyAction)

Parameters

Parameter (Modifiable)	Description

sRegKey	Registry key being restored.

xAction (YES)	Action to take.

Set to braOverwrite to delete the existing registry key (with all it’s subkeys and values) before restoring the registry key.

Set to braMerge to restore the registry over the existing one, modifying existing values with the ones from the backup, and adding values that are in the backup but not in the registry. This is the default action.

Set to braSkip to skip this registry key.


RestoringRegKey event
RestoringRegKey event        (XceedBackup control)

Description

The RestoringRegKey event is triggered for each registry key being restored.

Declaration

Event RestoringRegKey(sRegKey As String)

Parameters

Parameter	Description

sRegKey	Registry key being restored.


SkippingFile event
SkippingFile event        (XceedBackup control)

Description

The SkippingFile event is triggered for each file being skipped from the current processing. The event provides the name of the file and the exact reason the file is being skipped. Various other information on the file being skipped is also provided.

The parameters provided by the SkippingFile event are not modifiable.

Declaration

Event SkippingFile(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, xSkippingReason As bkpSkippingReason)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number on which the file can be found.

xSkippingReason	Reason why the file is being skipped.

Remarks

The information provided by the SkippingFile event can be displayed on the screen, printed out, or completely ignored – it's your choice. If you do not write a handler for the SkippingFile event, your application will still be notified if any files are skipped because the method currently executing will return a result code of either berFilesSkipped or xerNothingToDo (if all files and wildcards are skipped with the bsrNoFilesMatched skipping reason).


SkippingRegKey event
SkippingRegKey event        (XceedBackup control)

Description

The SkippingRegKey event is triggered for each registry key being skipped from the current processing. The event provides the registry key's name as well as the reason why it is being skipped.

Declaration

Event SkippingRegKey(sRegKey As String, xSkippingReason As bkpSkippingReason)

Parameters

Parameter	Description

sRegKey	Registry key being skipped.

xSkippingReason	Reason why the registry key is being skipped.


StartingBackup event
StartingBackup event        (XceedBackup control)

Description

The StartingBackup event is triggered when a backup job is about to be launched, either automatically by the scheduler, or manually by a call to the Backup method. The event allows you to prevent the launch of the backup job as well as change the media label pattern written by the library to the destination media.

Declaration

(Parameters in bold are modifiable)

Event StartingBackup(xBackupJob As BackupJob, dtBackupDate As Date, sMediaLabelPattern As String, bPreventLaunch As Boolean)

Parameters

Parameter (Modifiable)	Description

xBackupJob	BackupJob control representing the backup job being launched.

dtBackupDate	Official date of the backup.

sMediaLabelPattern (YES)	Media label pattern to use for this backup. A default label pattern is provided, but you are free to modify it.

bPreventLaunch (YES)	Set this parameter to True to prevent the backup job from launching. By default, this parameter is False.


StartingRestore event
StartingRestore event        (XceedBackup control)

Description

The StartingRestore event is triggered when a restore job is about to be launched, either automatically by the scheduler, or manually by a call to the Restore method. The method allows you to prevent the restore job from being launched.

Declaration

(Parameters in bold are modifiable)

Event StartingRestore(xRestoreJob As RestoreJob, bPreventLaunch As Boolean)

Parameters

Parameter (Modifiable)	Description

xRestoreJob	RestoreJob control representing the restore job being launched.

bPreventLaunch (YES)	Set this parameter to True to prevent the restore job from launching. By default, this parameter is False.


StartingVerify event
StartingVerify event        (XceedBackup control)

Description

The StartingVerify event is triggered when the verify phase of a backup job is about to start. The event allows you to prevent the verification phase of the backup job from being launched.

Declaration

(Parameters in bold are modifiable)

Event StartingVerify(xBackupJob As BackupJob, bPreventLaunch As Boolean)

Parameters

Parameter (Modifiable)	Description

xBackupJob	BackupJob control representing the backup job for which the verify phase is commencing.

bPreventLaunch (YES)	Set this parameter to True to prevent the verify phase from occurring. By default, this parameter is False.

Remarks

This event will be triggered only if the VerifyAfterBackup property of the BackupJob control is True.


VerifiedFile event
VerifiedFile event        (XceedBackup control)

VB Example

Description

The VerifiedFile event is triggered for each file being verified. The event provides information on the file being verified.

The events parameters are not modifiable.

Declaration

Event VerifiedFile(sFilename As String, lSize as Long, xAttributes As bkpFileAttributes, dtLastModified As Date, dtLastAccessed As Date, dtCreated As Date, lDiskNumber As Long, bCorrupted As Boolean)

Parameters

Parameter	Description

sFilename	Fully-qualified name of the file.

lSize	Size of the file, in bytes.

xAttributes	Attributes of the file.

dtLastModified	Last modification date of the file.

dtLastAccessed	Last access date of the file.

dtCreated	Creation date of the file.

lDiskNumber	Disk number on which the file can be found.

bCorrupted	If False, the file has been properly backed up. If True, the file contained in the backup does not match the original file on disk.


bkpBackupType enumeration

bkpBackupType

{

bbtFull = 0,

bbtCopy = 1,

bbtIncremental = 2,

bbtDifferential = 3

}


bkpCompressionLevel enumeration

bkpCompressionLevel

{

bclNone = 0,

bclLow = 1,

bclMedium = 6,

bclHigh = 9

}


bkpCurrentOperation enumeration

bkpCurrentOperation

{

bcoIdle = 0,

bcoManualBackup = 1,

bcoScheduledBackup = 2,

bcoManualRestore = 3,

bcoScheduledRestore = 4,

bcoBrowseCatalogs = 5,

bcoRecreateCatalogs = 6

}


bkpDaysOfWeek enumeration

bkpDaysOfWeek

{

bdwNone = 0,

bdwSunday = 1,

bdwMonday = 2,

bdwTuesday = 4,

bdwWednesday = 8,

bdwThursday = 16,

bdwFriday = 32,

bdwSaturday = 64,

bdwWeekDays = 62,

bdwWeekEnds = 65,

bdwEveryDay = 127

}


bkpError enumeration

bkpError

{

berSuccess = 0,

berProcessStarted = 1,

berMissingBackupFolder = 1500,

berMissingBackupSetName = 1501,

berNoSelection = 1502,

berSelectionIsEmpty = 1503,

berBackupExists = 1504,

berUserAbort = 1505,

berMemory = 1506,

berCOMError = 1507,

berUserPreventLaunch = 1508,

berBusy = 1509,

berInvalidBackupFileHeader = 1510,

berCreateCatalogFile = 1511,

berOpenCatalogFile = 1512,

berReadCatalogFile = 1513,

berWriteCatalogFile = 1514,

berInvalidCatalogFile = 1515,

berCreateLabelFile = 1516,

berReadLabelFile = 1517,

berWriteLabelFile = 1518,

berInvalidLabelFile = 1519,

berNotLicensed = 1520,

berEmptyBackupFile = 1521,

berSeekInBackupFile = 1522,

berEndOfBackupFile = 1523,

berOpenBackupFile = 1524,

berReadBackupFile = 1525,

berWriteBackupFile = 1526,

berMoveFile = 1527,

berNothingToDo = 1528,

berInsertMediaAbort = 1529,

berNotABackupFile = 1530,

berFilesSkipped = 1532,

berMediaNotEmptyAbort = 1533,

berMissingRedirectToFolder = 1534,

berBackupFileNotFound = 1535,

berVerificationFailed = 1536,

berSecurityNotRestored = 1537,

berCatalogFilesSkipped = 1539,

berBackupFilesSkipped = 1540,

berNoCatalogFilesFound = 1541,

berNoBackupFilesFound = 1542,

berInternalError = 1999

}


bkpFileAttributes enumeration

bkpFileAttributes

{

bfaNone = 0,

bfaReadOnly = 1,

bfaHidden = 2,

bfaSystem = 4,

bfaVolume = 8,

bfaFolder = 16,

bfaArchive = 32,

bfaCompressed = 2048

}


About the FileSelection control properties

The FileSelection control's properties are used to define a set of files and registry keys to be backed up or restored.

These properties can be altered visually at design-time using the FileSelection control's custom property pages, or your language's property editor window. At run time, your code can change the values of the properties as desired.

List of the FileSelection control's properties:

•	FilesToExclude

•	FilesToProcess

•	MaxDate

•	MinDate

•	RegKeysToInclude


About the FileSelection control methods

The FileSelection control's methods are provided to simplify adding items to its properties.

List of the FileSelection control’s methods:

•	AddFilesToExclude

•	AddFilesToProcess

•	AddRegKeysToInclude


About the BackupJob control properties

The BackupJob control's properties are used to configure a backup job.

These properties can be altered visually at design-time using the BackupJob control's custom property pages, or your language's property editor window. At run time, your code can change the values of the properties as desired.

List of the BackupJob control’s properties:

• BackupFolder  • BackupSetName  • BackupType  • CompressionLevel	• EncryptionPassword  • RetentionPeriod  • Selection  • VerifyAfterBackup


About the RestoreJob control properties

The RestoreJob control's properties are used to configure a restore job.

These properties can be altered visually at design-time using the RestoreJob control's custom property pages, or your language's property editor window. At run time, your code can change the values of the properties as desired.

List of the RestoreJob control’s properties:

• BackupSetName  • EncryptionPassword  • PreservePaths  • RedirectToFolder	• RestoreCorruptedFiles  • RestoreSecurity  • Selection


About the ScheduledJob control properties

The ScheduledJob control's properties are used to set up the date and times when one-time or recurring scheduled jobs must be performed.

These properties can be altered visually at design-time using the ScheduledJob control's custom property pages, or your language's property editor window. At run time, your code can change the values of the properties as desired.

List of the ScheduledJob control’s properties:

•	DaysOfWeek

•	Job

•	RecurrenceType

•	RecurrenceInterval

•	Required

•	StartDate


About the XceedBackup control properties

The following XceedBackup control properties are used by the various XceedBackup control methods in order to determine their behavior.

Most of these properties contain default values that are appropriate for common backup and restore needs, and can be altered visually at design-time using the XceedBackup control's custom property pages, or your language's property editor window. At run time, your code can change the values of the properties as desired before calling an XceedBackup method.

List of the XceedBackup control’s properties:

• Abort  • BackgroundProcessing  • CatalogFolder  • CurrentOperation	• LogDetailLevel  • LogFolder  • ScheduledJobs


About the XceedBackup control methods

The XceedBackup control provides the following methods to accomplish the tasks of backing up files, restoring files, browsing catalogs and recreating catalogs. Each method's behavior is determined by the values of the various XceedBackup control properties. The "Applicable properties" section in the documentation for each method lists the properties that are used by that method. When executing a method, it is important to correctly set all properties that are used by that method. Unwanted side effects may occur if properties were altered for the execution of one method, but were not set to the desired values for the next execution of a method that uses those same properties.

Most methods provide a return value that indicates if the operation was successful or if a warning or error has occurred. A properly coded application always checks, at the very least, to make sure the operation was successful. See the Error codes topic for a list of possible return values for all methods that return an bkpError type result code.

List of the XceedBackup control’s methods:

•	Backup

•	BrowseCatalogs

•	GetErrorDescription

•	License

•	RecreateCatalogs

•	Restore

•	StartScheduler

•	StopScheduler


About the XceedBackup control events

Events are triggered by the XceedBackup control to provide as much information as possible to your application while it is busy running jobs. Some events have modifiable parameters to allow the application to provide certain information on an as-needed basis or for real-time control.

For example, the BeforeBackingUpFile event is triggered right before a file is backed up. So if you want to, you can write an event handler for the BeforeBackingUpFile event that displays "Currently backing up file:" on a status bar along with the filename and any other file information you want to display for the file being backed up.

With Visual FoxPro 5.0 and up, events will be triggered only if you set "Application.AutoYield = .F.". Place this code in the section of your main program where you set up your environment. If you only have a single form in your application that uses Xceed Backup, place "Application.AutoYield = .F." in the form's load method, and set it back to the default in the form's destroy method.

Code in event handlers for XceedBackup control events cannot recursively call XceedBackup methods.

List of the XceedBackup control’s events:

• AfterBackingUpFile  • AfterRestoringFile  • BackingUpRegKey  • BackupFileExpired  • BackupFileNotFound  • BeforeBackingUpFile  • BeforeRestoringFile  • BrowsingCatalog  • BrowsingCatalogEntry  • FileStatus  • GlobalStatus  • InsertMedia  • InvalidPassword  • MediaNotEmpty  • OpenedFile	• ProcessCompleted  • RecreatingCatalog  • RecreatingCatalogEntry  • ReplacingFile  • ReplacingRegKey  • RestoringRegKey  • SkippingFile  • SkippingBackupFile  • SkippingCatalogFile  • SkippingRegKey  • StartingBackup  • StartingRestore  • StartingVerify  • VerifiedFile


About the enumerations

The following enumerations are built into the Xceed Backup Library ActiveX interface and are used as return codes for methods, as parameter types for methods and events, and as types for some properties.

For the bkpError and xcdSkippingReason enumerations, it is possible to retrieve a string explaining a particular value. Take a look at the GetErrorDescription method to see how.

List of global constants:

•	bkpLastDisk = 0

•	bkpMinimumDate = 2

•	bkpMaximumDate = 2958465 (represents the date 31/12/9999*)

List of Xceed Backup Library enumerations:

• bkpBackupType  • bkpCompressionLevel  • bkpCurrentOperation  • bkpDaysOfWeek  • bkpError  • bkpFileAttributes  • bkpLogDetailLevel	• bkpNotEmptyAction  • bkpRecurrenceType  • bkpOpenedFileAction  • bkpReplacingRegKeyAction  • bkpSkippingReason  • bkpValueType
*Not a typo


EncryptionPassword property        (RestoreJob control)

Description

The EncryptionPassword property contains the password to be used for decrypting files being restored. If this property is left empty, the InvalidPassword event will be triggered whenever an attempt is made to restore an encrypted file.

Data type

String

Default value

Empty

Remarks

•	Passwords can be up to 80 characters long.

•	Passwords are case-sensitive.

•	The encryption algorithm used by the Xceed Backup Library is the same one used by the PKZip 2.04g program. This type of encryption can resist attacks by amateurs if the password is well chosen and long enough (at least 16 characters) but it will probably not resist attacks by determined users or experts. Therefore, we suggest that you always use long passwords, and when possible, do not rely solely on this encryption system to protect sensitive data.


Wildcards

The Xceed Backup Library supports the * and ? wildcard characters. The * character matches a sequence of 0 or more characters. The ? character matches exactly one character.

Do not use "*.*" to match all files. You must use "*" instead. In the 32-bit Windows world, using *.* will only match files that contain a "." in them!

Wildcard matching in the Xceed Backup Library can be used in both the filename portion and the path portion. Example: "C:\AB*\Hello.txt" will find all Hello.txt files that are located in folders on drive C: starting with the letters "AB".

Wildcard matching is not case sensitive.


Relative paths

A relative path is a path that must be combined with a root path in order to make a complete (absolute) path. For example, "GRAPHICS\256COLOR\SMALL" is a relative path because it does not start by indicating a device or drive. "C:\USERS\FRED\GRAPHICS\256COLOR\SMALL" is an absolute path.


Current Directory

The current directory is the folder from which an application was executed. An application's current directory can change depending on where it is installed or by which method is chosen to start it (it could be executed from a batch file, by double-clicking on its program icon, from a shortcut, etc.)


Absolute paths

An absolute path is a complete path. It can start by a drive letter and colon or it can be a UNC format path. Examples of absolute paths are "C:\DATA FILES", "D:\" or "\\COMPUTERNAME\SHARENAME\DATA FILES". A path such as "GRAPHICS\256COLOR\SMALL" is not an absolute path. It is a relative path because the root portion is missing.


"Object" type properties

Since this property's type is "object", it will not appear in property browsers of visual development environments. To change its value at design time, you must use the control's property page.


bkpLogDetailLevel enumeration

bkpLogDetailLevel

{

bldNone = 0,

bldSummary = 1,

bldSummaryWithFolders = 2,

bldGeneral = 3,

bldComplete = 4

}


bkpNotEmptyAction enumeration

bkpNotEmptyAction

{

bnaErase = 0,

bnaAppend = 1,

bnaAskAnother = 2,

bnaAbort = 3

}


bkpRecurrenceType enumeration

bkpRecurrenceType

{

brtOnce = 0,

brtEveryNMinutes = 1,

brtEveryNHours = 2,

brtEveryNDays = 3,

brtEveryNMonths = 4,

brtDaysOfWeek = 5

}


bkpOpenedFileAction enumeration

bkpOpenedFileAction

{

boaSkip = 0,

boaRetry = 1,

boaRetryShareWrite = 2

}


bkpSkippingReason enumeration

bkpSkippingReason

{

bsrBackupType = 1000,

bsrDateRange = 1001,

bsrFilesToExclude = 1002,

bsrInternalError = 1003,

bsrUserNotReplace = 1004,

bsrNoFilesMatched = 1005,

bsrDamagedBackupFile = 1100,

bsrWriteFile = 1101,

bsrOpenFile = 1102,

bsrReadFile = 1103,

bsrMoveFile = 1104,

bsrInvalidPassword = 1105,

bsrDamagedCatalogFile = 1106,

bsrCreateFolder = 1107,

bsrAccessDenied = 1108,

bsrCreateFile = 1109,

bsrRestoreDiskFull = 1110,

bsrCreateTempFile = 1111,

bsrWriteTempFile = 1112,

bsrReadTempFile = 1113,

bsrRestoreRegKey = 1114,

bsrInvalidCRC = 1115,

bsrInvalidSize = 1116

}


bkpValueType enumeration

bkpValueType

{

bvtError = 0,

bvtSkippingReason = 1

}


bkpReplacingRegKeyAction enumeration

bkpReplacingRegKeyAction

{

braSkip = 0,

braOverwrite = 1,

braMerge = 2

}


About the error codes

The following constants define the possible return values of all the Xceed Backup Library methods of type bkpError, as well as the xResult parameter of the ProcessCompleted event. The declarations for these error codes are built into the ActiveX control's interface and should automatically be accessible by your code.

You can get a text description for each of these error codes by calling the GetErrorDescription method.

Xceed Backup Library error codes:

• berSuccess (0) • berProcessStarted (1) • berMissingBackupFolder (1500) • berMissingBackupSetName (1501) • berNoSelection (1502) • berSelectionIsEmpty (1503) • berBackupExists (1504) • berUserAbort (1505) • berMemory (1506) • berCOMError (1507) • berUserPreventLaunch (1508) • berBusy (1509) • berInvalidBackupFileHeader (1510) • berCreateCatalogFile (1511) • berOpenCatalogFile (1512) • berReadCatalogFile (1513) • berWriteCatalogFile (1514) • berInvalidCatalogFile (1515) • berCreateLabelFile (1516) • berReadLabelFile (1517) • berWriteLabelFile (1518) • berInvalidLabelFile (1519)	• berNotLicensed (1520) • berEmptyBackupFile (1521) • berSeekInBackupFile (1522) • berEndOfBackupFile (1523) • berOpenBackupFile (1524) • berReadBackupFile (1525) • berWriteBackupFile (1526) • berMoveFile (1527) • berNothingToDo (1528) • berInsertMediaAbort (1529) • berNotABackupFile (1530) • berFilesSkipped (1532) • berMediaNotEmptyAbort (1533) • berMissingRedirectToFolder (1534) • berBackupFileNotFound (1535) • berVerificationFailed (1536) • berSecurityNotRestored (1537) • berCatalogFilesSkipped (1539) • berBackupFilesSkipped (1540) • berNoCatalogFilesFound (1541) • berNoBackupFilesFound (1542) • berInternalError (1999)


Media label pattern

A media label is a string that represents what is physically written on a removable media.

A media label pattern is the generic string used to generate media labels for a particular backup. The pattern string must contain one, and only one, "%d" token somewhere. This token will be replaced by the disk number.

Example:

"MyApplication Full backup disk number %d" will translate to "MyApplication Full backup disk number 1", "MyApplication Full backup disk number 2", and so on.


berSuccess

Value

0

Description

This value indicates that the method executed successfully, without errors or skipped files.


berProcessStarted

Value

1

Description

The method has successfully started the thread that will perform the operation in the background.

Tips

When the BackgroundProcessing property is set to True, all methods will return berProcessStarted to indicate that they are performing their work in the background. The real return value of the method will be provided by the ProcessCompleted event.


berMissingBackupFolder

Value

1500

Description

The BackupFolder property of the BackupJob control being processed is empty.

Tips

The BackupFolder property is a required value. Set this property to the folder where you want the backup file to be stored before using the BackupJob control.


berMissingBackupSetName

Value

1501

Description

The BackupSetName property of the BackupJob or RestoreJob control being processed is empty.

Tips

The BackupSetName property is a required value. Set this property to the name of the backup set for a BackupJob or RestoreJob control before using the control.


berNoSelection

Value

1502

Description

The Selection property of the BackupJob or RestoreJob control being processed is empty.

Tips

The Selection property is a required value. Assign a FileSelection control to this property for a BackupJob or RestoreJob control before using the control.


berSelectionIsEmpty

Value

1503

Description

The FileSelection control specified in the Selection property of a BackupJob or RestoreJob control being processed, or the FileSelection control passed as a parameter to the BrowseCatalogs method, does not specify any files or registry keys.

Tips

Before using a FileSelection control, make sure that it contains at least one entry in it’s FilesToProcess property and/or RegKeysToInclude property.


berBackupExists

Value

1504

Description

The backup file for the current backup job already exists. This can occur when two identical backup jobs are trying to perform at the exact same time.

Tips

If multiple instances of an application using Xceed Backup Library are running on the same machine at the same time, and are using the same schedule for automatic backups, only one of these instances will be allowed to perform the backup.

If an application using Xceed Backup Library is running on different machines at the same time, and performing the same backup jobs at the same time, only one of these applications will be allowed to perform the backup.


berUserAbort

Value

1505

Description

The abort property has been set to True, and the current operation was succesfully aborted.


berMemory

Value

1506

Description

The system ran out of memory.

Tips

A memory allocation requested by the library was refused by the operating system. The machine was low on available memory.


berCOMError

Value

1507

Description

An internal COM error occurred when a control was attempting to communicate with another control. This can occur when, for example, a BackupJob control retrieves information from the FileSelection control represented by it’s Selection property.

Tips

This is an unrecoverable error. If you get this error value, please contact Xceed Software immediately.


berUserPreventLaunch

Value

1508

Description

The bPreventLaunch parameter of the StartingBackup, StartingRestore, or StartingVerify event has been set to True.


berBusy

Value

1509

Description

The current instance of the library is already running another operation.

Tips

Although the library is fully multi-threaded, each instance of the XceedBackup control can only do one operation at a time. This makes event handling much clearer. The developer can create another instance of the control if it is necessary to do another, independent operation simultaneously.


berInvalidBackupFileHeader

Value

1510

Description

An invalid backup file header has been read. This can occur when the library checks for expired backup files (see Backup Retention), or when opening a backup file to recreate it’s corresponding catalog file by a call to the RecreateCatalogs method.

Tips

Make sure that the media containing the backup file is not damaged.

This can also occur if a zip file with a name that matches Xceed Backup Library’s file naming convention is found in the backup folder.


berCreateCatalogFile

Value

1511

Description

The catalog file could not be created. This can occur when performing a backup job or when recreating a catalog file by a call to the RecreateCatalogs method.

Tips

Make sure that the catalog folder specified in the CatalogFolder property points to a valid folder, and that write access is allowed in that folder.


berOpenCatalogFile

Value

1512

Description

The catalog file could not be opened for reading. This can occur when performing a restore job or when a catalog file by a call to the BrowseCatalogs method.

Tips

Make sure that the catalog folder specified in the CatalogFolder property points to a valid folder, and that read access is allowed in that folder.


berReadCatalogFile

Value

1513

Description

An error occurred while reading data from the catalog file. This can occur when performing a restore job or when a catalog file by a call to the BrowseCatalogs method.

Tips

This can occur if the network drive where the catalog file is located on suddenly becomes disconnected, or if the removable media on which the catalog file is located is removed from the drive while it is being read. It can also occur if there is a bad sector on the drive where the catalog file is located.


berWriteCatalogFile

Value

1514

Description

An error occurred while writing data to the catalog file. This can occur when performing a backup job or when recreating a catalog file by a call to the RecreateCatalogs method.

Tips

Make sure that the drive where your catalog file is being written to is not full and has not been disconnected or rendered inaccessible. This error can occur if the network drive on which the catalog file is located suddenly becomes disconnected, or if the removable media on which the catalog file is located is removed from the drive while it is being created or updated by the library.


berInvalidCatalogFile

Value

1515

Description

The catalog file is not valid. This can occur when performing a restore job or when a catalog file by a call to the BrowseCatalogs method.

Tips

Make sure that the media containing the catalog file is not damaged.

This can also occur if a file with a name that matches Xceed Backup Library’s file naming convention is found in the catalog folder.


berCreateLabelFile

Value

1516

Description

The media label file could not be opened for write or read access. This can occur when working on a removable media.

Tips

Make sure that the removable media is not write-protected.


berReadLabelFile

Value

1517

Description

An error occurred while reading data from the media label file. This can occur when working on a removable media.

Tips

This can occur if the network drive where the media label file is located on suddenly becomes disconnected, or if the removable media on which the media label file is located is removed from the drive while it is being read. It can also occur if there is a bad sector on the drive where the media label file is located.


berWriteLabelFile

Value

1518

Description

An error occurred while writing data to the media label file. This can occur when working on a removable media.

Tips

Make sure that the drive where your media label file is being written to is not full and has not been disconnected or rendered inaccessible. This error can occur if the network drive on which the media label file is located suddenly becomes disconnected, or if the removable media on which the media label file is located is removed from the drive while it is being created or updated by the library.


berInvalidLabelFile

Value

1519

Description

The media label file is not valid.

Tips

This error can occur when working on removable media, and if it occurs the problem is most likely that the media label file is corrupted.


berNotLicensed

Value

1520

Description

This error occurs when the XceedBackup control is dynamically instantiated without calling the License method.

Tips

You must call the License method in certain cases of dynamic instantiation. Please see the documentation's License method topic to find out how to proceed.


berEmptyBackupFile

Value

1521

Description

The backup file is empty.


berSeekInBackupFile

Value

1522

Description

Cannot seek in backup file.

Tips

This can occur when the library is looking for signatures that identify the backup file but is unable to perform a seek operation. Make sure you are using a random-access media.


berEndOfBackupFile

Value

1523

Description

Premature end-of-file encountered in the backup file.

Tips

This can occur when the library is reading data from the backup file, but an end-of-file condition occurs. The backup file is probably truncated, or is corrupted.


berOpenBackupFile

Value

1524

Description

The backup file could not be opened.


berReadBackupFile

Value

1525

Description

An error occurred while reading data from the backup file.

Tips

This can occur if the network drive on which the backup file is located suddenly becomes disconnected, or if the floppy disk on which the backup file is located is removed from the drive while it is being read by the library. It can also happen if there is a bad sector on the drive where the backup file is located.


berWriteBackupFile

Value

1526

Description

An error occurred while writing data to the backup file.

Tips

Make sure that the drive where your backup file is being written to is not full and has not been disconnected or rendered inaccessible. This error can occur if the network drive on which the backup file is located suddenly becomes disconnected, or if the floppy disk on which the backup file is located is removed from the drive while it is being created or updated by the library.


berMoveFile

Value

1527

Description

Cannot move a temporary file created by the library to it’s final destination/name.


berNothingToDo

Value

1528

Description

This occurs when none of the files specified in the FilesToProcess property match any real existing files to be backed up or restored. The error can also occur when running the BrowseCatalogs method and no files from the FilesToProcess property match any files in the catalogs.

Tips

The paths and filenames specified in the FilesToProcess property must be checked.


berInsertMediaAbort

Value

1529

Description

The library was instructed to abort the current operation during the occurrence of the InsertMedia event.

Tips

This can occur when the bMediaInserted parameter of the InsertMedia event is left to its default value of False. The library takes this as an indication that no handler was written for the InsertMedia event. Of course, this error will also occur if the bMediaInserted parameter is voluntarily set to False.


berNotABackupFile

Value

1530

Description

The backup file being processed does not appear to be a backup file created by the Xceed Backup Library.

Tips

The library has determined that the file is not a backup file because a required signature was not found anywhere in the file.


berFilesSkipped

Value

1532

Description

Some of the files or registry keys to process were skipped (not processed) during the operation because of errors.

Tips

The SkippingFile and SkippingRegKey events are triggered whenever a file or registry key is skipped for any reason during an operation. Sometimes files are skipped because of errors (such as a read or write problem), and other times they are skipped because your application instructed the library to skip them (using the xAction parameter of the OpenedFile event, for example).

You can write a handler for the SkippingFile or SkippingRegKey event if you want to know what the errors were and which files or registry keys they were associated with.


berMediaNotEmptyAbort

Value

1533

Description

The library was instructed to abort the current operation during the occurrence of the MediaNotEmpty event.

Tips

This error occurs when the xAction parameter of the MediaNotEmpty event is set to bnaAbort.


berInternalError

Value

1999

Description

An unexpected error occurred in the library.

Tips

There are some types of errors tested in the library's code that should not occur in practice. If you get this error value, please contact Xceed Software immediately.


About the skipping reasons

The following constants define the possible values of SkippingFile and SkippingRegKey events’ xSkippingReason parameter.

You can get a text description for each of these codes by calling the GetErrorDescription method.

Xceed Backup Library skipping reasons:

• bsrBackupType (1000) • bsrDateRange (1001) • bsrFilesToExclude (1002) • bsrInternalError (1003) • bsrUserNotReplace (1004) • bsrNoFilesMatched (1005) • bsrDamagedBackupFile (1100) • bsrWriteFile (1101) • bsrOpenFile (1102) • bsrReadFile (1103) • bsrMoveFile (1104) • bsrInvalidPassword (1105)	• bsrDamagedCatalogFile (1106) • bsrCreateFolder (1107) • bsrAccessDenied (1108) • bsrCreateFile (1109) • bsrRestoreDiskFull (1110) • bsrCreateTempFile (1111) • bsrWriteTempFile (1112) • bsrReadTempFile (1113) • bsrRestoreRegKey (1114) • bsrInvalidCRC (1115) • bsrInvalidSize (1116)


bsrBackupType

Value

1000

Description

The file is being skipped because the backup type of the backup job being processed discarded it.

Tips

This can occur, for example, when performing an incremental backup. All files that do not have the archive attribute set will be skipped with the bsrBackupType reason.


bsrDateRange

Value

1001

Description

The file is being skipped because it’s last modification date does not fit in the date range of the FileSelection control that included it.


bsrFilesToExclude

Value

1002

Description

The filename matched an entry in the FilesToExclude property of the FileSelection control.


bsrInternalError

Value

1003

Description

An unexpected error occurred in the library that caused the file to be skipped.

Tips

There are some types of errors tested in the library's code that should not occur in practice. If you get this skipping reason, please contact Xceed Software immediately.


bsrUserNotReplace

Value

1004

Description

The file has been skipped because the bReplace parameter of the ReplacingFile event was set to False in the event handler, or the xAction parameter of the ReplacingRegKey event was set to braSkip.


bsrDamagedBackupFile

Value

1100

Description

The file has been skipped because of an inconsistency in the backup file that prevented the file from being restored.

Tips

The backup file contains inconsistent data, but other files may still be restored even though this file is corrupted.


bsrWriteFile

Value

1101

Description

An error occurred while writing data to the file.

Tips

The library was able to open the file for writing, and was able to verify that there was enough disk space free. However, it still could not write data to the file. This can happen in exceptional situations, like when a user removes a floppy from the drive while the library is writing data to a file on it.


bsrOpenFile

Value

1102

Description

Could not open the file for reading.

Tips

The file may currently be opened for reading in exclusive mode or for writing by another application. Setting the xAction parameter of the OpenedFile event to boaRetryShareWrite may in some cases allow the library to open the file for reading even though it is currently opened for writing by another application.


bsrReadFile

Value

1103

Description

An error occurred while reading data from the file.

Tips

The library was able to open the file for reading, but was not able to complete a read operation on the file. This is a severe error, and could be caused by circumstances such the removal of a floppy disk from the drive being read from, or an untimely disconnection of a network drive being read from.


bsrMoveFile

Value

1104

Description

Cannot move a temporary file to the real file's destination.

Tips

When the library is instructed not to restore corrupted files (because the RestoreCorruptedFiles property is set to False), it restores each file with a temporary name in order to make sure it is restored without any errors. The bsrMoveFile skipping reason can occur when the file is indeed going to replace the existing file, but the library is unable to overwrite the existing file with the new one just restored. This may be a file security or permission problem.


bsrInvalidPassword

Value

1105

Description

The file was encrypted and the library was unable to decrypt the file with the password provided.

Tips

The password in the EncryptionPassword property was invalid for this file, as well as any passwords provided to the InvalidPassword event  if it was implemented.


bsrDamagedCatalogFile

Value

1106

Description

The file has been skipped because it’s required information could not be retrieved from the catalog file.

Tips

Damaged catalog files can always be recreated using the RecreateCatalogs method.


bsrCreateFolder

Value

1107

Description

Could not create the folder where this file is being restored to.

Tips

The library may not have write access on the media where the folder is to be created.


bsrAccessDenied

Value

1108

Description

The file being restored could not be written because the already existing file it was about to replace could not be deleted by the library.

Tips

This may be a file security or permission problem.


bsrCreateFile

Value

1109

Description

Could not open the file for writing.

Tips

The library may not have write access on the destination folder of the file. This may be a file security or permission problem.


bsrRestoreDiskFull

Value

1110

Description

The file could not be restored because the destination location's disk is full.

Tips

If the filesystem is not full, then you should check to make sure everything is working correctly with the drive, and check if there are any security or permission problems for accessing this drive.


bsrCreateTempFile

Value

1111

Description

A temporary file required for registry backup/restore operations could not be created.

Tips

Make sure there is enough free disk space on the drive where the system’s temp folder is located.


bsrWriteTempFile

Value

1112

Description

An error occurred while writing data to the temporary file used for registry backup.

Tips

The library was able to open the temporary file for writing, and was able to verify that there was enough disk space free. However, it still could not write data to the file. This can happen in exceptional situations, like when a user removes a floppy from the drive while the library is writing data to a file on it.


bsrReadTempFile

Value

1113

Description

An error occurred while reading data from the temporary file used for registry restore.

Tips

The library was able to open the temporary file for reading, but was not able to complete a read operation on the file. This is a severe error, and could be caused by circumstances such the removal of a floppy disk from the drive being read from, or an untimely disconnection of a network drive being read from.


bsrRestoreRegKey

Value

1114

Description

The registry key could not be restored.

Tips

This can occur if the library does not have the required access rights to the registry.


Help file revision

Xceed Backup Library v1.0

Windows Help File Last Revised on Aug 16th, 1999

Copyright © 1999 Xceed Software Inc. All rights reserved.

This document may not be reproduced in whole or in part without written authorization from Xceed software Inc.


Restoring Files

Manually launching a restore job

To allow your application to restore files, follow these 5 steps:

•	Specify which files you want to restore. To do this, place a FileSelection control on a form and set it's FilesToProcess property to the path and filenames of the files you want to restore. The FileSelection control's property page allows you to do this visually, or you can just set the property in your code.

•	Configure the restore job to perform. To do this, place a RestoreJob control on a form, and start by setting it's Selection property to indicate which FileSelection control contains the list of files you want to restore. Again, you can do this visually or in your code.

•	Specify the name of the backup set to restore from. To do this, set the RestoreJob control's BackupSetName property. You can do this visually, too.

•	Start the restore job. To do this, place an XceedBackup control on a form and call the Restore method from within your code. If you changed the default location of the catalog files when you backed up your data, then you must set the CatalogFolder property before running the Restore method.

•	Make sure it worked successfully. To do this, check the Restore method's return value.

View sample code for the above steps. See the recovery wizard application topic if you want to avoid coding a restore procedure yourself.

Things you should consider

The main questions you should ask yourself when you are backing up files are:

•	Do you want to restore files to their original folders? If so, see the RedirectToFolder property.

•	Are you restoring from a removable media device? If so, see the InsertMedia event.

•	Do you need detailed list of available files to restore? If so, see the BrowseCatalogs method.

•	Do you want to display the status of the restore operation? If so, see the GlobalStatus event.

Other questions you may want to consider are:

•	Are your backups password-protected? See the EncryptionPassword property.

•	Do you want to restore files even if corrupted? See the RestoreCorruptedFiles property.

•	Do you want to restore file security permissions? See the RestoreSecurity property.


Sample code for restoring files on-demand

Assuming you aren't setting the properties visually, here's sample code (in VB) to code the described steps:

' Put a FileSelection, RestoreJob and XceedBackup control

' on a form to use this code.

Dim ResultCode As bkpError

FileSelection1.FilesToProcess = "c:\myapp\data\*"

RestoreJob1.Selection = FileSelection1

RestoreJob1.BackupSetName = "Manually launched backups"

ResultCode = XceedBackup1.Restore(RestoreJob1)

If ResultCode = berSuccess then

    MsgBox "Files successfully restored."

Else

 	MsgBox "Problem restoring files. Error: "+

XceedBackup1.GetErrorDescription(bvtError, ResultCode)

EndIf


Performing scheduled backups

Having backups launched at specific times or intervals

Backups can automatically be started by Xceed Backup Library's job scheduling system. To setup scheduled backups for your application, follow these steps:

•	Set up which files you want to backup. To do this, place a FileSelection control on a form and set it's FilesToProcess property. The FileSelection control's property page allows you to do this visually, or you can just set the property in your code.

•	Configure the backup job(s) to perform. To do this, place a BackupJob control on a form, and set its Selection property to indicate which FileSelection control contains the list of files to backup. Again, you can do this visually or in your code. Multiple BackupJob controls can be placed on the form if required, and they can all use the same FileSelection control if they deal with the same files.

•	Configure where to place the backup files and give your backup set a name. To do this, set the BackupJob control's BackupFolder and the BackupSetName properties. Both of these properties are available visually, too. If you have multiple BackupJob controls on the form, don't forget to set each one's properties.

•	Schedule when your backup job should be performed. To do this, place a ScheduledJob control on a form and set it's Job property to indicate which BackupJob or RestoreJob control to use for this particular scheduled job. You will also need to set the RecurrenceType, StartDate and possibly the RecurrenceInterval property in order to specify when the job should take place.

•	Start and stop the scheduler. To do this, place an XceedBackup control on a form and call the StartScheduler method. Call the StopScheduler method before your application terminates.

•	Make sure your scheduled jobs are successful. To do this, check the ProcessCompleted event's xResult parameter.

View sample code for the above steps.

Things you should consider

The main questions you should ask yourself when you are coding scheduled backups are:

•	If a scheduled job is missed, should it be skipped? See the Required property.

•	What kind of backup type do you want to perform? See the BackupType property.

•	Are you backing up to a removable media device? If so, see the InsertMedia event.

•	Do you want to display a message when a scheduled backup is about to start? If so, see the StartingBackup event.

•	Do you want to display the status of the backup operation? If so, see the GlobalStatus event.

Other questions you may want to consider are:

•	Do you want the backup up data to be verified? See the VerifyAfterBackup property.

•	Should old backup files be deleted after a while? If so, see the RetentionPeriod property.

•	Where should my catalog files be placed? See the CatalogFolder property.

•	Do you want to password-protect your backup files? See the EncryptionPassword property.

•	Are you backing up some files that may already be in use? See the OpenedFiles event.


Sample code for performing scheduled backups

Assuming you aren't setting the properties visually, here's sample code (in VB) to code the described steps:

' Put a FileSelection, BackupJob, ScheduledJob and an

' XceedBackup control on a form to use this code.

FileSelection1.FilesToProcess = "c:\myapp\data\*"

BackupJob1.Selection = FileSelection1

BackupJob1.BackupFolder = "d:\backups"

BackupJob1.BackupSetName = "Daily Afternoon Backup"

ScheduledJob1.Job = BackupJob1

ScheduledJob1.RecurrenceType = brtEveryNDays

ScheduledJob1.RecurrenceInterval = 1 ' every day...

ScheduledJob1.StartDate = "28/05/2000 14:00" ' ...at 2pm

XceedBackup1.ScheduledJobs.Add(ScheduledJob1)

XceedBackup1.StartScheduler

' The following code can be put into the

' StartingBackup event if you want to inform

' your users that a backup is about to start

Dim Response As Integer

Response = MsgBox("The daily backup is about to start. Click OK to continue or Cancel to skip the backup.", vbOkCancel)

If Response = vbCancel Then

bPreventLaunch = True

Endif

' The following code should be put into the

' ProcessCompleted event handler, to check if a

' backup was completed succesfully or not.

If xResult = berSuccess then

    MsgBox "Backup successful."

Else

    MsgBox "Problem backing up files. Error: "+

XceedBackup1.GetErrorDescription(bvtError, xResult)

EndIf


Backing up files

Manually launching a backup

To allow your application to backup its files on-demand, follow these 5 steps:

•	Set up which files you want to backup. To do this, place a FileSelection control on a form and set it's FilesToProcess property. The FileSelection control's property page allows you to do this visually, or you can just set the property in your code.

•	Configure the backup job to perform. To do this, place a BackupJob control on a form, and start by setting it's Selection property to indicate which FileSelection control contains the list of files you want to backup. Again, you can do this visually or in your code.

•	Configure where to place the backup files and give your backup set a name. To do this, set the BackupJob control's BackupFolder and the BackupSetName properties. Both of these properties are available visually, too.

•	Start the backup job. To do this, place an XceedBackup control on a form and call the Backup method from within your code.

•	Make sure it worked successfully. To do this, check the Backup method's return value.

View sample code for the above steps.

Things you should consider

The main questions you should ask yourself when you are backing up files are:

•	What kind of backup type do you want to perform? See the BackupType property.

•	Are you backing up to a removable media device? If so, see the InsertMedia event.

•	Do you want to display the status of the backup operation? If so, see the GlobalStatus event.

Other questions you may want to consider are:

•	Do you want the backup up data to be verified? See the VerifyAfterBackup property.

•	Should old backup files be deleted after a while? If so, see the RetentionPeriod property.

•	Where should my catalog files be placed? See the CatalogFolder property.

•	Do you want to password-protect your backup files? See the EncryptionPassword property.

•	Are you backing up some files that may already be in use? See the OpenedFiles event.


Sample code for backing up files on-demand

Assuming you aren't setting the properties visually, here's sample code (in VB) to code the described steps:

' Put a FileSelection, BackupJob and XceedBackup control

' on a form to use this code.

Dim ResultCode As bkpError

FileSelection1.FilesToProcess = "c:\myapp\data\*"

BackupJob1.Selection = FileSelection1

BackupJob1.BackupFolder = "d:\backups"

BackupJob1.BackupSetName = "Manually launched backups"

ResultCode = XceedBackup1.Backup(BackupJob1)

If ResultCode = berSuccess then

    MsgBox "Backup successful."

Else

 	MsgBox "Problem backing up files. Error: "+

XceedBackup1.GetErrorDescription(bvtError, ResultCode)

EndIf


About the getting started quickly section

This section of the manual has but one goal: To show you, as fast as possible, how to start using the library's major features.

If you don't see what you need here, the next step is to read the Overview of the Xceed Backup controls topic. From there you will probably jump to one of the various method or property topics. If all else fails, use the "search" feature of the manual, or browse the sample applications. Feel free to contact Xceed Software at any time if you have questions.

Getting started quickly topics

•	Backup concepts

•	Backing up files

•	Performing scheduled backups

•	Restoring files


berMissingRedirectToFolder

Value

1534

Description

The PreservePaths property was set to False, but the RedirectToFolder property is empty.

Tips

If you chose to have Xceed Backup discard the path information stored in a backup file, you must tell Xceed Backup where to restore files to.


Backup sets

A backup set represents a group of backup jobs that relate to the same data to backup. A backup set can include as many backup jobs as required to adequately perform the backups for a group of files and registry keys. For example, if you want to backup all the files in C:\MYDATA\ each day, with a full backup on Fridays and an incremental backup on the other weekdays, you would have two different backup jobs that would relate to the same backup set.


Backup_types
Backup types

A backup type allows you to specify how files should be selected for backup during a backup job. It also determines which files will be left for future backup jobs. Backup types rely on the archive attribute of a file. All files have the archive attribute and this attribute is automatically updated by the operating system whenever a file is manipulated by any application. The Xceed Backup Library checks this attribute to determine if a file has been modified since the last backup, and uses this information along with the backup type you have specified in order to determine whether or not the file should be backed up during a given job. There are four backup types with the following meanings:

Backup type	Description

Full	Backup every file, regardless of the archive attribute.
Removes the archive attribute after a file is backed up.

Copy	Backup every file, regardless of the archive attribute.
Does not remove the archive attribute after a file is backed up.

Incremental	Backup only the files that have the archive attribute.
Removes the archive attribute after a file is backed up.

Differential	Backup only the files that have the archive attribute.
Does not remove the archive attribute after a file is backed up.


Retention management

Retention management is a feature that allows for automatic deletion of out-of-date backup files. Every backup file can be assigned an expiration date, calculated by adding a number of retention hours to the date/time at which the backup file is created.

Every time a backup job is launched, it first checks in the backup folder for backup files that belong to the same backup set. If any of the backup files are expired, a BackupFileExpired event is triggered, and the expired backup file will eventually be deleted.


Catalog files

Every backup file created with the library has a corresponding catalog file. This catalog file contains an index of the files and registry keys contained in its corresponding backup file. The catalog files are usually stored locally on hard disk for immediate reference when required.

The catalog files are required for any restore operation. When you need to restore a set of files that were backed up in a given backup set, the library will use the catalogs for this backup set to locate the backup files that contain the files to be restored.

If you ever lose or delete the catalog files, it is possible to recreate them from their originating backup files.


berBackupFileNotFound

Value

1535

Description

The backup file required in order to restore files was not found. Files could not be restored.

Tips

The Xceed Backup Library automatically knows where to find backups because the backup file locations are stored in the catalog files generated during the backup. When a backup file is not found in the location indicated by the catalogs, the BackupFileNotFound event occurs, giving you the chance to tell the Xceed Backup Library another location where it can find the backup file(s). If the library still cannot find the backup files, this error will then occur.


StartScheduler method
StartScheduler method        (XceedBackup control)

Description

The StartScheduler method starts the Xceed Backup Library's scheduler thread, which launches scheduled jobs when they are due to run. Only when the scheduler has been started does the library run scheduled jobs. You must call the StopScheduler method to stop the scheduler when you exit your application, otherwise you may cause a memory leak.

Sometimes a scheduled job can be missed because the application was not running (and therefore the scheduler was not started) at the time the job was due to be launched. When multiple scheduled jobs are due to be launched as soon as the scheduler is started, the scheduler will run jobs with the following rules:

•	Jobs with older due dates will be launched first.

•	If the same job was missed multiple times (recurring jobs), the job will be launched only once, as if only the latest missed job was considered missed.

•	Missed jobs that had the Required property set to False will be skipped.

Declaration

Method StartScheduler() As Boolean

Return values

A return value of True indicates that the scheduler has been successfully started. False indicates that the library could not start the scheduler.


StopScheduler method
StopScheduler method        (XceedBackup control)

Description

The StartScheduler method starts the Xceed Backup Library's scheduler thread. Only when the scheduler has been started does the library run scheduled jobs. You must call the StopScheduler method to stop the scheduler when you exit your application, otherwise you may cause a memory leak.

Declaration

Method StopScheduler(bWaitForRunningJob As Boolean) As Boolean

Parameters

Parameter	Description

bWaitForRunningJob	Set this to False if you want the scheduler to be stopped immediately even when a job is currently being run. When you do this, the scheduler stops the running job and shuts down. Set this to True if you want the scheduler to wait for the currently running job to be completed before shutting down.

Return values

A return value of True indicates that the scheduler has been successfully stopped. False indicates that the scheduler could not be stopped.


SkippingBackupFile event
SkippingBackupFile event        (XceedBackup control)

Description

The SkippingBackupFile event is triggered whenever a backup file cannot be read due to an error. The event provides the catalog file's name and the reason it is being skipped.

The SkippingBackupFile event's parameters are not modifiable.

Declaration

Event SkippingBackupFile(sBackupFilename as String, xReason as bkpError)

Parameters

Parameter (Modifiable)	Description

sBackupFilename	The path and filename of the backup file that is being skipped

xReason	The error code indicating why the backup file is being skipped

Remarks

This event can occur when calling the Restore or the RecreateCatalogs methods.


SkippingCatalogFile event
SkippingCatalogFile event        (XceedBackup control)

Description

The SkippingCatalogFile event is triggered whenever a catalog file cannot be read due to an error. The event provides the catalog file's name and the reason it is being skipped.

The SkippingCatalogFile event's parameters are not modifiable.

Declaration

Event SkippingCatalogFile(sCatalogFilename as String, xReason as bkpError)

Parameters

Parameter (Modifiable)	Description

sBackupFilename	The path and filename of the catalog file that is being skipped

xReason	The error code indicating why the catalog file is being skipped

Remarks

This event can occur when calling the BrowseCatalogs or the RecreateCatalogs methods.


BackupFileNotFound event
BackupFileNotFound event        (XceedBackup control)

Description

The BackupFileNotFound event is triggered whenever a backup file (referred to by a catalog file) is not found. The event allows you to specify a new location where the backup file may be searched for.

Declaration

(Parameters in bold are modifiable)

BackupFileNotFound(sBackupFilename As String, sNewFolder As String)

Parameters

Parameter (Modifiable)	Description

sBackupFilename	The path and filename of the backup file that was not found

sNewFolder (YES)	If you want to inform the backup library that it can try to find the backup file in another location, set this parameter to specify the path to the folder where the backup files can be found.

Remarks

If the backup file is still not found (after you have set the sNewFolder parameter and the event's handler completed), the berBackupFileNotFound result code will be returned.


Backup files

Backup files contain the backed up data. Backup files created by the Xceed Backup Library contain compressed files and registry keys that were backed up by the library. The data may also be encrypted. The backup file format is an improved, yet 100%-PKZip 2.04g compatible file format, so if required, files can be recovered with any typical unzipping application. The Recovery Wizard application provided with the library also allows users to recover backups, with an easy to use interface and supporting all the library's restore capabilities.


Log files

Log files are text files which contain a description of events that occur during backup, restore and other operations. They allow the developer or the end-user to troubleshoot these operations, determine if everything is working as it should, or help determine which files were backed up or restored.


Jobs

A job is an operation that the Xceed Backup Library can execute on-demand or at a specific scheduled time or recurring interval.


Job Scheduling

The Xceed Backup Library can run jobs on-demand (whenever you call the Backup or Restore method, for example) or can run jobs at specific scheduled times or recurring intervals. The later capability is called "job scheduling", and can be configured by setting up one or more ScheduledJob controls.


32-bit CRC

Cyclic Redundancy Check. The 32-bit CRC is a checksum system that is used to verify the integrity of data. Backup files contain the 32-bit CRC of each file's original uncompressed data. When a file is restored or verified, the CRC is calculated on the file's newly uncompressed data and compared with the CRC stored for the original file read off disk during the backup. If the CRCs are the same, then the restored or verified file is very probably identical to the original file, because the 32-bit CRC is able to detect single bit or multiple-bit variations even in the largest files.


bsrNoFilesMatched

Value

1005

Description

The particular filename or wildcard specified in the FilesToProcess did not match any files or folders.


berCatalogFilesSkipped

Value

1539

Description

At least one catalog file was skipped during the operation.


berBackupFilesSkipped

Value

1540

Description

At least one backup file was skipped during the operation.


berSecurityNotRestored

Value

1537

Description

The Windows NT security permissions for one or more files was not restored. The files themselves were restored, though.


bsrInvalidCRC

Value

1115

Description

The file failed the CRC-32 check after it was uncompressed from within the backup file.

Tips

The file is corrupted. It can still be restored (but corrupted) if the RestoreJob control's RestoreCorruptedFiles property is set to True.


bsrInvalidSize

Value

1116

Description

The file's size was incorrect after it was uncompressed from within the backup file.

Tips

The file is corrupted. It can still be restored (but corrupted) if the RestoreJob control's RestoreCorruptedFiles property is set to True.


Using the controls via property pages

All 5 controls that make up the Xceed Backup library can be configured visually by using their built-in property page dialog boxes.

All development languages that support ActiveX controls should be able to display these property pages. In most languages (example: VB, Delphi, Visual FoxPro) all you have to do is select one of the control icons you have placed on a form, right-click on the icon and select the "properties" item from the popup menu.

Each property page has a help button that opens this manual to the appropriate property page description topic. That includes:

•	FileSelection control property page (File selection tab)

•	FileSelection control property page (Registry selection tab)

•	BackupJob control property page

•	RestoreJob control property page

•	ScheduledJob control property page

•	XceedBackup control property page (Backup session tab)

•	XceedBackup control property page (Scheduled Job tab)

The FileSelection control's property page is shown here:


FileSelection control property page (File selection tab)
FileSelection control property page
File selection tab

"File selection" list

The file selection list lets you visually select the files you want to backup or restore, and automatically fills in the FilesToProcess and FilesToExclude properties. The file selection list lets you select:

•	Files relative to your application's current directory (when it is running)

•	Files in the Windows or System directories

•	Files in specific hard-coded locations (example: "C:\DATA\*")

Keep in mind that you are selecting files that will be backed up or restored when your application (and therefore the Xceed Backup Library) is running on end-user machine(s). Therefore, selecting files in specific hard-coded locations is dangerous if your application's data is sometimes placed on other drives (like "D:\DATA"). To remedy this, you can select files relative to your application's current directory. However, for some situations, this is not enough. In that case you must set the FilesToProcess / FilesToExclude properties via code – the property page will not be able to help.

"App. Folder" item in the "File selection" list

This item lets you select files to backup that are located inside your application's current directory. Files selected from this branch will are prepended with the "<AppFolder>" macro in the FilesToProcess property. "<AppFolder>" changes depending on where your application's .EXE is located at run-time. If you try to use the "App. Folder" item, you will be prompted to specify the folder which contains the same files and folders on your development machine that your application's current directory at run-time will contain.

"Legend" explanations

Because the "File selection" list maps to two different properties: FilesToProcess and FilesToExclude, it displays the selected items in such a way that you can tell how each included or excluded item was selected. For example, suppose you have folders A and B in the C:\TEMP folder, and you click the C:\TEMP folder's box. You will see a green checkmark appear in the box, which means that entire folder and its contents will be processed. The item "C:\TEMP\*<R>" will appear in the FilesToProcess list below. Notice that inside the C:\temp folder in the File selection list, the folders A and B have black checkmarks. That means that they (and their contents) will be processed as well, but that they have been selected indirectly because you clicked on a parent folder (C:\TEMP). Suppose you don't want folder B to be processed. Clicking on its box will put a red x in the box. That means the folder is specifically excluded, and will appear in the FilesToExclude list below, and the C:\TEMP folder's green checkmark will now be on a grey background, which means that some files or folders in the C:\TEMP folder are excluded or not selected.

"Also select subfolders when selecting a folder" checkbox

This option, which is selected by default, means that when you click a box next to a folder, all subfolders will also be selected. Turning off this item will allow you to select or deselect a folder itself, without affecting its subfolders. This is useful for example if you only want to select all files in the folder C:\TEMP, but not the subfolders C:\TEMP contains. This option does not correspond to any FileSelection control properties – but it does correspond to the <R> feature described in the FilesToProcess property topic.

"Files to process" and "Files to exclude" lists

These lists represent the current state of the FilesToProcess and FilesToExclude properties. You can edit them yourself to fine tune your visual selections (ex: change "C:\TEMP\*<R>" to "C:\TEMP\*.TXT<R>") or to add new selections. They are linked to the "File selection" list above, so your editing will be reflected visually in real-time.

"Minimum date" and "maximum date" lists

These fields let you visually set the MinDate and MaxDate properties.


FileSelection control property page (Registry selection tab)
FileSelection control property page
Registry selection tab

"Registry key selection" list

Selecting items in this list adds items to the RegKeysToInclude property. All subkeys and their values are selected when you check an item in this list.

"Registry keys to include" list

This editable list reflects the current contents of the RegKeysToInclude property.


RestoreJob control property page

"File selection" drop-down list

This drop-down list lets you select the FileSelection control to use in order to know which files to restore when the restore job is launched. All FileSelection controls available on the same form should be available for selection in this list.

"Backup set name" field

This field must contain the backup set name that will be used by the Xceed Backup Library to determine where files should be restored from. It corresponds to the RestoreJob control's BackupSetName property.

"Restore to original location" option

This option, which is selected by default, causes the Xceed Backup Library to restore the files back to the original locations they were backed up from. Existing files will automatically be overwritten (unless you handle the ReplacingFile event).

"Redirect to a specific folder" option

This option, when selected, allows you to have files restored to a specific location, as opposed to each file's original location. This option, when selected, enables the next field described in the next paragraph.

"Redirect to this folder:" field

When you have selected the "Redirect to a specific folder" option, this field lets you specify the full path to the location where files should be restored to. It corresponds to the RedirectToFolder property, and you must fill it in when you are redirecting files being restored.

"Preserve the tree structure" checkbox

When files are being redirected with the "Redirect to a specific folder" option, selecting this checkbox allows you to have the original folders files were backed up from recreated in the folder specified by the "Redirect to this folder" field. If this checkbox is not selected, all files will be dumped directly in the destination folder, without their original source folders being recreated. This option corresponds to the PreservePaths property.

"Restore security attributes" checkbox

This checkbox indicates whether or not Windows NT security and permission information be restored for each file. This checkbox corresponds to the RestoreSecurity property.

"Restore corrupted files anyway" checkbox

This checkbox indicates whether or not files that seem to be corrupted (due to a CRC-32 test or other problem) should be restored. This checkbox corresponds to the RestoreCorruptedFiles property.

"Decryption password" field and "Hide" checkbox

This field lets you enter the decryption password that is required if you are restoring files that were backed up with a password. The "Hide" checkbox lets you hide the password on-screen for protection against prying eyes. This field corresponds to the RestoreJob control's EncryptionPassword property.


BackupJob control property page

"File selection" drop-down list

This drop-down list lets you select the FileSelection control to use in order to know which files to backup when the backup job is launched. All FileSelection controls available on the same form should be available for selection in this list.

"Backup folder" field

This field allows you to determine where the Xceed Backup Library will create the backup files that are created whenever a backup job is launched. The field corresponds to the BackupFolder property.

"Backup set name" field

This field must contain the backup set name that will be used by the Xceed Backup Library to remember where files were backed up to. It corresponds to the BackupJob control's BackupSetName property.

"Backup type" drop-down list

Lets you chose the backup type to be used by the backup job. This drop-down list corresponds to the choices available for the BackupType property.

"Encryption password" field and "Hide" checkbox

This field lets you enter the encryption password that will be used to protect the files you are backing up. The "Hide" checkbox lets you hide the password on-screen for protection against prying eyes. This field corresponds to the BackupJob control's EncryptionPassword property.

"Compression level" drop-down list

Lets you select the amount of compression to be applied to files being backed up. This field corresponds to the CompressionLevel property.

"Apply a retention period of N hours" checkbox and field.

Checking this box allows you to enable the retention management system. The "hours" field allows you to determine how many hours backup files should be kept in the folder specified by the BackupFolder property before being deleted. This field corresponds to the RetentionPeriod property.

"Verify backup when completed" checkbox

This checkbox lets you determine whether backup files should be completely re-read after the backup is complete, and checked for errors. This checkbox corresponds to the VerifyAfterBackup property.


XceedBackup control property page (Backup session tab)
XceedBackup control property page
Backup session tab

"Catalogs folder" field

This field lets you decide where catalog files should be created (when backing up files) or read from (when restoring files). This field corresponds to the CatalogFolder property. Leaving this field empty will place the catalog files in <AppFolder>\Backups\Catalogs, where <AppFolder> is your application's current directory.

"Log files folder" field

This field lets you decide where log files should be written to whenever you run a job. This field corresponds to the LogFolder property. Leaving this field empty will place the log files in <AppFolder>\Backups\Logs, where <AppFolder> is your application's current directory.

"Log detail level" drop-down list

This drop-down list lets you select the level of detail that will be written to the log files. You can turn logging off completely with this option, or select one of the 4 other detail levels. This drop-down list corresponds to the possible values of the LogDetail Level property.

"Process in the background" checkbox

Select this option if you want jobs to be executed asynchronously (in the background). See the BackgroundProcessing property for details.


XceedBackup control property page (ScheduledJobs tab)
XceedBackup control property page
ScheduledJobs tab

"Available scheduled jobs" list

This is the list of the available ScheduledJob controls currently on the same form as the XceedBackup component. Select the jobs you want the XceedBackup control to monitor when the scheduler has been started, and click the right arrow button to move them to the "Assigned scheduled jobs" list.

"Assigned scheduled jobs" list

This list contains all the jobs that will be monitored by the XceedBackup component's scheduler when the scheduler has been started (with the StartScheduler method). This list corresponds to the ScheduledJobs property.


ScheduledJob control property page

"Backup or restore job" drop-down list

This drop-down list allows you to select which backup or restore job to configure scheduling for. For each backup or restore job you want to schedule, you must put a ScheduledJob control on the form, because only one backup or restore job can be configured per control. When you have finished scheduling all your jobs, they must be assigned in the ScheduledJobs property of the XceedBackup control, or by the XceedBackup control's property page window, in the "Scheduled Jobs" tab. This drop-down list corresponds to the Job property.

"Starting date" fields

These fields allow you to specify when the job must be run for the first time. The fields correspond to the StartDate property.

"Recurrence type" drop-down list

This drop-down list allows you to specify the time frame that must pass before the scheduled job is launched again after the date specified in the "Starting date" fields. This list works together with the "Recurrence interval" field below, or the "Days of the week" checkboxes to the right. This list corresponds to the possible values for the RecurrenceType property. Selecting the option named "Only once" allows you to shut off recurrence so that a job is only executed one, on the specified starting date.

"Recurrence interval" field

This field allows you to specify the number of minutes / hours / days / months for the "Recurrence type" drop-down list. This field corresponds to the RecurrenceInterval property.

"Next calculated job date and time" indicator

This indicator tells you when the next job (after the first one specified by the "Starting date" field) will be launched according to the "Recurrence type", the "Recurrence Interval" and the "Days of the week" checkboxes if applicable.

"Days of the week" checkboxes

These checkboxes let you select specific days of the week to launch a scheduled job. They apply only when the "Recurrence type" drop down list's "Specific days of the week" item is selected. These checkboxes correspond to the DaysOfWeek property.

"This scheduled job is required to run" checkbox

Lets you determine if a job can be skipped or not if it is missed for any reason. This checkbox corresponds to the Required property.


berNoCatalogFilesFound

Value

1541

Description

This error code is returned by the BrowseCatalogs or the Restore method if no catalogs for the backup set were found in the catalog folder.

Tips

The catalog filenames that are searched for are determined by the RestoreJob object's BackupSetName property (when using the Restore method) or by the sBackupSetName parameter when using the BrowseCatalogs method. Therefore, make sure you have specified the correct backup set name.


berNoBackupFilesFound

Value

1542

Description

This error code is returned by the RecreateCatalogs method if no backup files were found in the backup folder specified by the RecreateCatalog method's sBackupFolder parameter.


About the recovery wizard
About the recovery wizard application

The Recovery Wizard is an application that helps users restore backups created by applications that use the Xceed Backup Library. A compiled version is provided along with the VB6 source code. You can find it in the RECOVERY WIZARD folder where you installed the library.

The Recovery Wizard is designed to guide users so that they can enter all the information required in order to restore files from a backup. The information obtained from the user:

•	Selection of the backup set and the catalog folder location

•	Selection of files and/or registry keys to restore

•	Selection of the location where you want to restore your backups

•	Selection of a couple of other options and decryption password

The Recovery Wizard can also recreate the catalogs (which are essential in order to restore backups) if they were lost or misplaced. When necessary, the catalog recreation step is offered by the Recovery Wizard after the backup set name has been entered and the "Next" button has been clicked.

Improve it for your own needs

When you have registered your copy of the Xceed backup library, you are allowed to distribute the Recovery Wizard application as desired (royalty-free), and can also change its provided source code to improve it. You can modify the Recovery Wizard application in order to hard code some of the required information, such as eliminating the questions "What is the backup set name?" and "Where are the catalog files?". You can also remove or modify the Recovery Wizard's introduction page or remove it, change the icon – basically any modification you want.


VerifyAfterBackup and VerifiedFile exampe for VB
VerifyAfterBackup and VerifiedFile example for VB

This example demonstrates the use of the VerifyAfterBackup property and the resulting VerifiedFile event. To use it, place a Button, a Listbox, a FileSelection, a BackupJob and an XceedBackup control on a form and keep their default names. The code below is separated into two parts. One part is code for the button's click event that sets the VerifyAfterBackup property to True and starts a backup, and the second part is code for the VerifiedFile event handler,

Private Sub Command1_Click()

  Dim ResultCode As bkpError

  ' Lets backup all .TXT files on drive C:

  FileSelection1.FilesToProcess = "c:\*.txt<r>"

  ' Set some of the backup job's parameters

  BackupJob1.BackupSetName = "Example backup with verify"

  BackupJob1.BackupFolder = "c:\Example Backup"

  BackupJob1.BackupType = bbtFull

  BackupJob1.Selection = FileSelection1

  ' Specify we want our backup verified

  BackupJob1.VerifyAfterBackup = True

  ' Run the backup method and display the result code description text

  ResultCode = XceedBackup1.Backup(BackupJob1)

  MsgBox "Backup process ended. Result: " + XceedBackup1.GetErrorDescription(bvtError, ResultCode)

End Sub

'For this example, we add code to the VerifiedFile event handler that displays whether each file passes the test or not.

Private Sub XceedBackup1_VerifiedFile(ByVal sFilename As String, ByVal lSize As Long, ByVal xAttributes As XceedBackupLibCtl.bkpFileAttributes, ByVal dtLastModified As Date, ByVal dtLastAccessed As Date, ByVal dtCreated As Date, ByVal lDiskNumber As Long, ByVal bCorrupted As Boolean)

  List1.AddItem (sFilename & " (Size= " & lSize & " bytes) Passes verification: " & (Not bCorrupted))

End Sub


BrowseCatalogs and BrowsingCatalog example in VB

The following code uses the BrowseCatalogs method to obtain a list of files available in the specified backup set. This method causes the BrowsingCatalog and BrowsingCatalogEntry events to be triggered. Code for each one of these events is provided which adds some information on the backup set's catalog and its contents to a listbox.

Once it is finished it will return the Result of the operation. If it is xerSuccess, the operation was successful. Otherwise, the code below will return the error description with the help of the  GetErrorDescription method. The following code assumes you have placed a button, a list box, an XceedBackup and a FileSelection control on a form and kept their default names.

' The following Sub is for the button's click event:

Private Sub Command1_Click()

  Dim ResultCode As bkpError

  ' The first thing is to specify what we want to browse from the catalog files. We may be interested only in knowing which .MDB files can be restored from the backup set, so we set the FilesToProcess property accordingly:

  FileSelection1.FilesToProcess = "*.MDB<r>"

  ' We also specify the path where we keep the catalog files

  XceedBackup1.CatalogFolder = "c:\Backup\Catalogs"

  ' Now we can start browsing the catalog

  ResultCode = XceedBackup1.BrowseCatalogs(FileSelection1, "Weekly Backups")

  ' Check the return code…

  If ResultCode <> berSuccess Then

    MsgBox "The following error occurred: " & XceedBackup1.GetErrorDescription(bvtError, ResultCode)

  End If

End Sub

' Now here is the handler for the BrowsingCatalogEntry event. It will add each file's name and size to the listbox.

Private Sub XceedBackup1_BrowsingCatalogEntry(ByVal sFilename As String, ByVal lSize As Long, ByVal xAttributes As XceedBackupLibCtl.bkpFileAttributes, ByVal dtLastModified As Date, ByVal dtLastAccessed As Date, ByVal dtCreated As Date, ByVal lDiskNumber As Long, ByVal sMediaLabel As String)

  List1.AddItem "File: " & sFilename & "  (" & lSize & " bytes)"

End Sub

' Here is the handler for the BrowsingCatalog event. It will add the name of the backup set being browsed to the listbox.

Private Sub XceedBackup1_BrowsingCatalog(ByVal sBackupSetName As String, ByVal xBackupType As XceedBackupLibCtl.bkpBackupType, ByVal sBackupFilename As String, ByVal dtBackupDate As Date, ByVal dtExpirationDate As Date, ByVal sMediaLabelPattern As String, ByVal bEncrypted As Boolean)

  List1.AddItem "Browsing a new catalog file..."

  List1.AddItem "Backup set name: " & sBackupSetName

  List1.AddItem "Type of backup : " & xBackupType

  List1.AddItem "Date of backup : " & dtBackupDate

End Sub


BrowseCatalogs and BrowsingCatalog example in Delphi

The following code uses the BrowseCatalogs method to obtain a list of files available in the specified backup set. This method causes the BrowsingCatalog and BrowsingCatalogEntry events to be triggered. Code for each one of these events is provided which adds some information on the backup set's catalog and its contents to a listbox.

Once it is finished it will return the Result of the operation. If it is xerSuccess, the operation was successful. Otherwise, the code below will return the error description with the help of the  GetErrorDescription method. The following code assumes you have placed a button, a list box, an XceedBackup and a FileSelection control on a form and kept their default names.

procedure TForm1.Button1Click(Sender: TObject);

var ResultCode: bkperror ;

begin

  { The first thing is to specify what we want to browse from the catalog files. We may be interested only in knowing which .MDB files can be restored from the backup set, so we set the FilesToProcess property accordingly: }

  FileSelection1.FilesToProcess := '*.MDB<r>';

  {Now we must specify the path for the catalog folder}

  XceedBackup1.CatalogFolder := 'c:\Backup\Catalogs';

  {Start browsing the catalogs...}

  ResultCode := XceedBackup1.BrowseCatalogs(FileSelection1.ControlInterface, 'Weekly Backup');

  {Check the return code}

  If ResultCode <> 0 Then

    Showmessage (('The following error occurred: ') + XceedBackup1.GetErrorDescription(bvtError, ResultCode))

  end;

end;

{ Now here is the handler for the BrowsingCatalogEntry event. It will add each file's name and size to the listbox. }

procedure TForm1.XceedBackup1BrowsingCatalogEntry(Sender: TObject;

  const sFilename: WideString; lSize: Integer; xAttributes: TOleEnum;

  dtLastModified, dtLastAccessed, dtCreated: TDateTime;

  lDiskNumber: Integer; const sMediaLabel: WideString);

begin

    Listbox1.items.add ('File: ' + sFilename +  ' (' + inttostr(lSize) + ' bytes)');

end;

{ Here is the handler for the BrowsingCatalog event. It will add the name of the backup set being browsed to the listbox. }

procedure TForm1.XceedBackup1BrowsingCatalog(Sender: TObject;

  const sBackupSetName: WideString; xBackupType: TOleEnum;

  const sBackupFilename: WideString; dtBackupDate,

  dtExpirationDate: TDateTime; const sMediaLabelPattern: WideString;

  bEncrypted: WordBool);

begin

    Listbox1.Items.add ('Browsing a new catalog file...');

    Listbox1.Items.add ('Backup set name: ' + sBackupSetName);

    Listbox1.Items.add ('Type of backup : ' + inttostr(xBackupType));

    Listbox1.items.add ('Date of backup : ' + DateTimeTostr(dtBackupDate));

end;


Backup method example in VB

The following code uses the Backup method to backup all the .DOC files on the C:\ drive, as well as a big chunk of the registry. Once the backup method is finished it will return the result of the operation. The code below will display a description of the problem if an error occurs. The following code assumes you have placed a button, an XceedBackup, a FileSelection and a BackupJob control on a form and kept their default names.

' Here's the code for the button's click event:

Private Sub Command1_Click()

  Dim ResultCode As bkpError

  ' First we define the files we want to backup

  ' The FileSelection control will later be assigned to the BackupJob control's "Selection" property.

  FileSelection1.FilesToProcess = "C:\*.DOC<r>"

  ' Lets backup a big branch from the registry, too:

  FileSelection1.RegKeysToInclude = "HKEY_LOCAL_MACHINE\SOFTWARE"

  ' Now lets configure our backup job settings

  BackupJob1.BackupFolder = "C:\Backup" ' place backups here

  BackupJob1.BackupSetName = "Example backups"

  BackupJob1.BackupType = bbtFull

  BackupJob1.Selection = FileSelection1

  ' Now lets specify exactly where we want our catalog files created

  XceedBackup1.CatalogFolder = "C:\Backup\Catalogs"

  ' Lets start backing up the files now

  ResultCode = XceedBackup1.Backup(BackupJob1)

  'Check the return value

  If ResultCode = 0 Then

    MsgBox "Backup completed successfully."

  Else

    MsgBox "Error backing up files. Error description: " & XceedBackup1.GetErrorDescription(bvtError, ResultCode)

  End If

End Sub


Backup method example in Delphi

The following code uses the Backup method to backup all the .DOC files on the C:\ drive, as well as a big chunk of the registry. Once the backup method is finished it will return the result of the operation. The code below will display a description of the problem if an error occurs. The following code assumes you have placed a button, an XceedBackup, a FileSelection and a BackupJob control on a form and kept their default names.

{ Here's the code for the button's click event: }

procedure TForm1.Button1Click(Sender: TObject);

var ResultCode: bkperror ;

begin

  { First we define the files we want to backup

    The FileSelection control will later be assigned to the BackupJob control's "Selection" property. }

  FileSelection1.FilesToProcess := 'C:\*.DOC<r>';

  { Lets backup a big branch from the registry, too: }

  FileSelection1.RegKeysToInclude := 'HKEY_LOCAL_MACHINE\SOFTWARE';

  { Now lets configure our backup job settings }

  BackupJob1.BackupFolder := 'C:\Backup';

  BackupJob1.BackupSetName := 'Example backups';

  BackupJob1.BackupType := bbtFull;

  BackupJob1.Selection := FileSelection1.ControlInterface;

  { Lets also specify exactly where we want our catalog files created }

  XceedBackup1.CatalogFolder := 'C:\Backup\Catalogs';

  { Start backing up the files. }

  ResultCode := XceedBackup1.Backup(BackupJob1.ControlInterface);

  { Check the return code }

  If ResultCode = 0 Then

    showmessage ('Backups created successfully.' )

  Else

    Showmessage (('Error backing up files. Error description: ') + XceedBackup1.GetErrorDescription(bvtError, ResultCode))

  end;

end;


Restore method example in VB

The following code uses the Restore method to restore all the .DOC files starting with the letter "A" back to their original locations on the C:\ drive. The code also restores a specific branch of the registry. Once the restore method is finished it will return the result of the operation. The code below will display a description of the problem if an error occurs. This example's code assumes you backed up files using the code from the Backup method example in VB. The code also assumes you have placed a button, an XceedBackup, a FileSelection and a RestoreJob control on a form and kept their default names.

' Here's the code for the button's click event:

Private Sub Command1_Click()

  Dim ResultCode As bkpError

  ' First we define the files we want to restore (in this case, all DLL files starting with A)

  ' The FileSelection control will later be assigned to the RestoreJob control's "Selection" property.

  FileSelection1.FilesToProcess = "C:\A*.DOC<r>"

  ' Lets restore the backed up branch from the registry, too:

  FileSelection1.RegKeysToInclude = "HKEY_LOCAL_MACHINE\SOFTWARE"

  ' Now lets configure our restore job settings

  RestoreJob1.BackupFolder = "C:\Backup" ' place backups here

  RestoreJob1.BackupSetName = "Example backups"

  RestoreJob1.BackupType = bbtFull

  RestoreJob1.Selection = FileSelection1

  ' Now lets specify exactly where the catalog files are located (since we changed their default location)

  XceedBackup1.CatalogFolder = "C:\Backup\Catalogs"

  ' Lets start restoring the files now

  ResultCode = XceedBackup1.Restore(RestoreJob1)

  'Check the return value

  If ResultCode = 0 Then

    MsgBox "Files restored successfully."

  Else

    MsgBox "Error restoring files. Error description: " & XceedBackup1.GetErrorDescription(bvtError, ResultCode)

  End If

End Sub


Restore method example in Delphi

The following code uses the Restore method to restore all the .DOC files starting with the letter "A" back to their original locations on the C:\ drive. The code also restores a specific branch of the registry. Once the restore method is finished it will return the result of the operation. The code below will display a description of the problem if an error occurs. This example's code assumes you backed up files using the code from the Backup method example in Delphi. The code also assumes you have placed a button, an XceedBackup, a FileSelection and a ResotreJob control on a form and kept their default names.

{ Here's the code for the button's click event: }

procedure TForm1.Button1Click(Sender: TObject);

var ResultCode: bkperror ;

begin

  { First we define the files we want to restore (in this case, all DLL files starting with A)

    The FileSelection control will later be assigned to the RestoreJob control's "Selection" property. }

  FileSelection1.FilesToProcess := 'C:\A*.DOC<r>';

  { Lets restore the backed up branch from the registry, too: }

  FileSelection1.RegKeysToInclude := 'HKEY_LOCAL_MACHINE\SOFTWARE';

  { Now lets configure our restore job settings }

  RestoreJob1.BackupFolder := 'C:\Backup';

  RestoreJob1.BackupSetName := 'Example backups';

  RestoreJob1.BackupType := bbtFull;

  RestoreJob1.Selection := FileSelection1.ControlInterface;

  { Now lets specify exactly where the catalog files are located (since we changed their default location) }

  XceedBackup1.CatalogFolder := 'C:\Backup\Catalogs';

  { Start restoring the files. }

  ResultCode := XceedBackup1.Restore(RestoreJob1.ControlInterface);

  { Check the return code }

  If ResultCode = 0 Then

    showmessage ('Files restored successfully.' )

  Else

    Showmessage (('Error restoring files. Error description: ') + XceedBackup1.GetErrorDescription(bvtError, ResultCode))

  end;

end;


RecreateCatalog method example in VB

The following code uses the RecreateCatalogs method to recreate the catalog files for a specific backup set. Once the method completes it will return the result code for the operation. If the result code is xerSuccess, the operation was successful, otherwise the code below will display the error's description with the help of the GetErrorDescription method. The following code assumes you placed a button and an XceedBackup control on a form and kept their default names.

' Put this code in the button's click event handler...

Private Sub Command1_Click()

  Dim ResultCode As bkpError

  ' The first thing to do is to specify where you want your newly recreated catalogs to be placed.

  XceedBackup1.CatalogFolder = "c:\Backup\Catalogs"

  ' Now, to recreate the catalogs, all you need to do is to call the RecreateCatalogs method directly, and provide (by parameters) the backup set name and the folder where the backups are kept.

  ResultCode = XceedBackup1.RecreateCatalogs("Example backups", "C:\Backup")

  ' Now check the return code…

  If ResultCode = 0 Then

    MsgBox "Your catalogs were recreated successfully."

  Else

    MsgBox "Error recreating catalogs. Error description: " & XceedBackup1.GetErrorDescription(bvtError, ResultCode)

  End If

End Sub


FilesToProcess / FilesToExclude example

Suppose we have the following files on a given drive mapped to H:

H:\

----------DATA\

--------------------BACKUPS\

------------------------------DOCS\

----------------------------------------DOC1.DOC

----------------------------------------DOC2.DOC

----------------------------------------DOC3.PDF

----------------------------------------DOC4.TXT

------------------------------PICS\

----------------------------------------PIC1.BMP

----------------------------------------PIC2.BMP

----------------------------------------PIC3.GIF

----------------------------------------PIC4.JPEG

------------------------------JUNK\

----------------------------------------ERASE.ME

----------READDATA.TXT

ROOT.TXT

Examples (use <S> instead of <R> as desired)

To process all files on drive H:\, and all subfolders, set FilesToProcess to:

FileSelction1.FilesToProcess = "H:\*<r>"

To process all ".TXT" files on drive H:\, and all subfolders, set FilesToProcess to:

FileSelction1.FilesToProcess = "H:\*.TXT<r>"

To process all files in the H:\DATA folder, but not its subfolders or their contents, set FilesToProcess to:

FileSelection1.FilesToProcess = "H:\DATA\*"

(This will result in only the file H:\DATA\READDATA.TXT being processed)

To process all the files on drive H: except files ending with ".TXT", set the

FilesToProcess and FilesToExclude properties to the following values:

FileSelection1.FilesToProcess = "H:\*<r>"

FileSelection1.FilesToExclude = "*.TXT<r>"

To process all the .TXT files on drive H: except those starting with D,  set the

FilesToProcess and FilesToExclude properties to the following values:

FileSelection1.FilesToProcess = "H:\*.TXT<r>"

FileSelection1.FilesToExclude = "H:\D*<r>"

To process all the files and folders in the "H:\DATA\BACKUPS" folder but excluding

the contents of the "H:\DATA\BACKUPS\PICS" folder set the FilesToProcess and

FilesToExclude properties to the following values:

FileSelection1.FilesToProcess = "H:\DATA\BACKUPS\*<r>"

FileSelection1.FilesToExclude = "H:\DATA\BACUPS\PICS\*<r>


Folder macros

Some properties allow macros to be used when specifying paths and filenames.

A macro is a substring that starts with a '<' character and ends with a '>', and contains a macro name in between. The macro name can be selected among the available macros (see below). The complete macro, including the start and ending characters are replaced by a fully qualified path at runtime. Thus, the value of a macro usually depends on the particular settings of the Windows operating system the Xceed Backup Library is being run on at runtime.

To use a macro, simply replace dangerous code such as this:

XceedBackup1.LogFolder = "c:\windows\system\logs"

with code that uses a macro, like this:

XceedBackup1.LogFolder = "<SystemFolder>\logs"

Here is a list of the available macros:

Macro	Description

<AppFolder>	Your application's current directory. Usually where your .EXE is located.

<WindowsFolder>	The location of the Windows folder.

<SystemFolder>	The location of the Windows System folder.


About the VB 6 sample

About the VB 6 sample

The VB 6 sample application demonstrates the use of scheduled backups, catalog browsing, and recovery of a specific version of a backed-up file.

You can load the sample in VB 6 by selecting the SAMPLE.VBP project file .

The sample application's main form, called frmSample, contains the Form Load function, which initializes the backup library objects and starts the scheduler. The form has an editable text field whose contents are saved to a text file whenever a backup is about to start (the StartingBackup event is triggered to let us know). The form's "Rollback" button opens the frmRollback form, which lists the available backups (using the BrowseCatalogs method and BrowsingCatalogEntry event) and allows the user to select which version of the backed up text file to restore. The code restores the text file from the backups and then reloads it into the frmSample form's editable text field.


About the Delphi 4 sample

About the Delphi 4 sample

The Delphi 4 sample application demonstrates the use of scheduled backups, catalog browsing, and recovery of a specific version of a backed-up file.

To load the sample, use Delphi's "Open project…" item from the File menu to load the sample.dpr file.

The sample application's main form, called frmSample, contains the FormCreate function, which initializes the backup library objects and starts the scheduler. The form has an editable text field whose contents are saved to a text file whenever a backup is about to start (due to the StartingBackup event). The form's "Rollback" button opens the frmRollback form, which lists the available backups (using the BrowseCatalogs method and BrowsingCatalogEntry event) and allows the user to select which version of the backed up text file to restore. The code restores the text file from the backups and then reloads it into the frmSample form's editable text field.


About the VC++ 6.0 sample

About the Visual C++ 6.0 sample

The Visual C++ 6.0 sample demonstrates the library's use, and at the same time as it shows you how to do event sinking with ATL.  The sample is actually an "add-in" for Visual C++ 6.0, which schedules a backup of your current project's files every 10 minutes.

To install the add-in, follow these instructions:

•	Open the workspace file ADDIN.DSW, and compile the DLL.

•	Open the "Customize" dialog box (Tools -> Customize)

•	Go to the "Add-ins and Macro Files" tab

•	Click the "Browse" button

•	In the "Files of type" combo box, select "Add-ins (.DLL)"

•	Locate the "ADDIN.DLL" file. It should be in the "Debug" folder under the folder where the sample is located.

•	You will see "BackupAddIn Class" in the Add-ins list box. Check the box beside it.

•	Close the "Customize" dialog box.

The add-in will now be active. Every time you open a workspace, the addin will schedule a backup job every 10 minutes that will perform a copy backup of all the project files. A different backup job will be scheduled for every project contained in the workspace.

The add-in provides feedback through the output window of MSVC, in the "Macro" tab.


berVerificationFailed

Value

1536

Description

The verification phase of a backup job detected errors.


LogFilename (read-only) property

Description

The LogFilename (read-only) property specifies what the current path and filename is that the Xceed Backup Library is using as a log file.

Data type

String