Share via

3.1.4.13 Backup (Opnum 28)

  • Article

The Backup method backs up the metabase.

 HRESULT Backup(
   [unique, in, string] LPCWSTR pszMDBackupName,
   [in] DWORD dwMDVersion,
   [in] DWORD dwMDFlags
 );

pszMDBackupName: A string of up to 100 Unicode characters that names the backup.

dwMDVersion: An integer value specifying the version number to be used for the backup.

Value

Meaning

MD_BACKUP_HIGHEST_VERSION

0xFFFFFFFE

Overwrite the highest existing backup version with the specified backup name.

MD_BACKUP_NEXT_VERSION

0xFFFFFFFF

Use the next backup version number available with the specified backup name.

dwMDFlags: An integer value containing the bit flags describing the type of backup operation to be performed. The flags can be one or more of the following values.

Value

Meaning

MD_BACKUP_FORCE_BACKUP

0x00000004

Force the backup even if the SaveData operation specified by MD_BACKUP_SAVE_FIRST fails.

MD_BACKUP_OVERWRITE

0x00000001

Back up even if a backup of the same name and version exists, overwriting it if necessary.

MD_BACKUP_SAVE_FIRST

0x00000002

Perform a SaveData operation before the backup.

Return Values: A signed 32-bit value that indicates return status. If the method returns a negative value, it failed. If the 12-bit facility code (bits 16–27) is set to 0x007, the value contains a Win32 error code in the lower 16 bits. Zero or positive values indicate success, with the lower 16 bits in positive nonzero values containing warnings or flags defined in the method implementation. For more information about Win32 error codes and HRESULT values, see [MS-ERREF].

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

0x000CC809

MD_WARNING_SAVE FAILED

The metadata save prior to backup failed. The previous version of the data was backed up.

0x80070008

ERROR_NOT_ENOUGH_MEMORY

There is not enough memory to complete the operation.

The opnum field value for this method is 28.

The location string can be up to 100 Unicode characters in length. Multiple metabase backups can be stored with the same name.

When processing this call, the server MUST do the following:

  • Check the pszMDBackupName parameter. If the length of the string is 100 characters or more, or if it contains any characters in the following set ('/', '\', '*', '.', '?', '"', '&', '!', '@', '#', '$', '%', '^', '(', ')', '=', '+', '|', '`', '~') return E_INVALIDARG.

  • Check the version parameter. If it is greater than the maximum allowed version number and is not either MD_BACKUP_HIGHEST_VERSION or MD_BACKUP_NEXT_VERSION, return E_INVALIDARG.

  • If the parameter flags have the bit MD_BACKUP_SAVE_FIRST set, flush the in-memory configuration data first. If this operation fails, check the MD_BACKUP_FORCE_BACKUP bit. If this bit is not set, return an error. Otherwise, continue the operation. If no subsequent error occurs, return MD_WARNING_SAVE_FAILED.

  • Check the MD_BACKUP_OVERWRITE bit. If it is not set, check if a backup with the target version exists. If it is TRUE, return an error, otherwise overwrite the existing backup.

  • If the value of the pszMDBackupName parameter is an empty string, the server uses a default name for the backup.

  • The server saves the persisted data using the backup name and the version number as a key so that the data can be restored later.