Função RestoreClusterDatabase (clusapi.h)

[Essa função está disponível para uso nos sistemas operacionais especificados na seção Requisitos. O suporte para essa função foi removido no Windows Server 2008 e essa função não faz nada e retorna ERROR_CALL_NOT_IMPLEMENTED.]

Restaura o banco de dados de cluster e reinicia o serviço cluster no nó do qual a função é chamada. Esse nó é chamado de nó de restauração.

Sintaxe

DWORD RestoreClusterDatabase(
  [in]           LPCWSTR lpszPathName,
  [in]           BOOL    bForce,
  [in, optional] LPCWSTR lpszQuorumDriveLetter
);

Parâmetros

[in] lpszPathName

Cadeia de caracteres Unicode terminada em nulo especificando o caminho para o arquivo de backup. As informações de configuração do cluster estão contidas neste local; são dados confidenciais que devem ser protegidos. Por exemplo, esses dados podem ser protegidos usando uma lista de controle de acesso para restringir o acesso ao local onde os dados são armazenados.

[in] bForce

Se FALSE, a operação de restauração não será concluída se uma das seguintes circunstâncias se aplicar:

• Outros nós estão ativos no momento.
• O layout de partição do recurso de quorum atual não é idêntico ao layout de partição do recurso de quorum que estava em vigor quando o backup foi feito. (O termo "layout de partição" refere-se ao número de partições no disco e aos deslocamentos para cada partição. As atribuições de assinatura de disco e letra da unidade não precisam ser idênticas.)

Definir bForce como TRUE faz com que a operação prossiga independentemente dessas circunstâncias anteriores; no entanto, a operação ainda pode falhar por outros motivos.

[in, optional] lpszQuorumDriveLetter

Opcional. Identifica a letra da unidade do recurso de quorum no qual o banco de dados de cluster será restaurado. Use esse parâmetro somente se o recurso de quorum tiver sido substituído desde que o backup foi feito. A cadeia de caracteres deve ser formatada da seguinte maneira:

• O primeiro caractere deve ser alfabético, ou seja, no intervalo 'a'-'z' ou 'A'-'Z'.
• O segundo caractere deve ser dois-pontos (':').
• O terceiro caractere deve ser um nulo de terminação ('\0').

Retornar valor

Se a operação for bem-sucedida, a função retornará ERROR_SUCCESS.

Se a operação falhar, a função retornará um código de erro do sistema. Veja a seguir possíveis códigos de erro.

Código de retorno	Descrição
ERROR_CLUSTER_NODE_UP	A operação falhou porque outros nós de cluster estão ativos no momento. Se você chamar RestoreClusterDatabase novamente com o bForce definido como TRUE, o cluster tentará desligar o serviço cluster nos outros nós ativos.
ERROR_QUORUM_DISK_NOT_FOUND	A operação falhou porque o disco de quorum descrito no backup não corresponde ao disco de quorum atual. Se você chamar RestoreClusterDatabase novamente com bForce definido como TRUE, o cluster tentará alterar a assinatura e a letra da unidade do disco de quorum atual para os valores armazenados no backup.

Comentários

Se a operação de restauração for bem-sucedida, o nó de restauração forma um cluster de acordo com os dados de configuração no banco de dados de cluster restaurado. À medida que outros nós ingressam no cluster, eles atualizam seus bancos de dados de cluster do banco de dados no nó de restauração.

Observe que discos de cluster diferentes do recurso de quorum que foram adicionados ou alterados desde que o backup foi feito não serão reconhecidos pelo banco de dados de cluster restaurado e permanecerão offline mesmo se a operação de restauração for bem-sucedida. Novos recursos devem ser criados para esses discos (consulte Criando um recurso de disco físico).

O procedimento geral a seguir é recomendado para qualquer rotina de restauração de cluster:

1. Chame RestoreClusterDatabase com bForce definido como FALSE e nenhuma letra de unidade especificada. Essa é a melhor abordagem porque, se bem-sucedida, a operação não precisa forçar alterações de configuração.
2. Se a primeira chamada falhar, deixe que o usuário decida se deseja forçar o procedimento a continuar ou corrigir manualmente o problema. Certifique-se de comunicar as implicações de cada decisão.

   Retornar valor	Ação se for forçada	Correção manual
   ERROR_CLUSTER_NODE_UP	A operação de restauração interromperá o serviço de cluster em todos os outros nós.	O usuário desliga manualmente o serviço cluster em todos os outros nós de cluster. O comando Net Stop ClusSvc é suficiente; uma energia completa é desnecessária.
   ERROR_QUORUM_DISK_NOT_FOUND	O usuário deve fornecer a letra da unidade do recurso de quorum. A operação de restauração alterará a assinatura do disco e a letra da unidade para os valores armazenados no backup.	O usuário reparticionará o disco de quorum para que o layout seja idêntico ao layout armazenado no backup.

    

   Se o usuário concordar em forçar a continuação, chame RestoreClusterDatabase com bForce definido como TRUE e a letra da unidade especificada (se aplicável). Forçar não garante o sucesso. Se a operação de restauração falhar novamente, teste o valor retornado e responda adequadamente.

Exemplos

O exemplo a seguir ilustra o procedimento descrito acima. Para obter um exemplo mais completo que inclui BackupClusterDatabase, consulte Backup e restauração da configuração do cluster. Este exemplo usa o arquivo de cabeçalho ClusDocEx.h definido na documentação do Cluster de Failover.

int main( void )
{
    WCHAR szPath[] = L"c:\\ClusBack\\19991215";
    WCHAR szInput[3];
    BOOL bForce = FALSE;
    DWORD dwResult = ERROR_SUCCESS;

    // First try: no force
    dwResult = RestoreClusterDatabase( szPath, FALSE, NULL );
    
    // Allow user to force shutdown if necessary.
    if( dwResult == ERROR_CLUSTER_NODE_UP )
    {
        wprintf( L"The operation failed because other cluster nodes are currently active. " );
        wprintf( L"The Cluster service must be shut down on all other nodes in order for this operation to succeed." );
        wprintf( L"Enter 'f' to force automatic shutdown, or any other key to exit for manual shutdown:  " );
        fgetws( szInput, 2, stdin );
        if( towupper( szInput[0] ) == L'F' )
            dwResult = RestoreClusterDatabase( szPath, TRUE, NULL );
    }

    // Allow user to locate quorum resource if necessary.
    if( dwResult == ERROR_QUORUM_DISK_NOT_FOUND )
    {
        wprintf( L"\n\nERROR: QUORUM DISK NOT FOUND\n" );
        wprintf( L"The restore routine cannot find a quorum resource with the same partition layout as the quorum resource described in the backup. " );
        wprintf( L"The existing quorum resource must have a layout (number of partitions and offsets to each partition) identical to the layout stored in the backup.\n" );
        wprintf( L"Enter the drive letter of the quorum resource to force continuation, or any non-letter key to exit:  " );
        fgetws( szInput, 3, stdin );
        if( iswalpha( szInput[0] ) )
        {
            szInput[1] = L':';
            szInput[2] = L'\0';
            dwResult = RestoreClusterDatabase( szPath, TRUE, szInput );
        }
    }

    // Only one force attempt per error, then report success or failure. 
    if( dwResult == ERROR_SUCCESS )
    {
        wprintf( L"\n\nSUCCESS\n" );
        wprintf( L"The restore routine succeeded. Start the Cluster service on the other cluster nodes to complete the restore operation." );
        wprintf( L"As nodes join the cluster, they will update their cluster databases to match the restored configuration." ); 
        return 0;
    }
    else
    {
        wprintf( L"RestoreClusterDatabase failed (%d)\n", dwResult );
        return 1;
    }

}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Nenhum compatível
Servidor mínimo com suporte	Windows Server 2003 Enterprise, Windows Server 2003 Datacenter
Plataforma de Destino	Windows
Cabeçalho	clusapi.h
Biblioteca	ClusAPI.lib
DLL	ClusAPI.dll

Confira também

BackupClusterDatabase