Objeto Recordset (ADO)

  • Artigo

Representa todo o conjunto de registros de uma tabela base ou os resultados de um comando executado. A qualquer momento, o objeto Recordset refere-se a apenas um único registro dentro do conjunto como o registro atual.

Comentários

Você usa objetos Recordset para manipular dados de um provedor. Ao usar o ADO, você manipula os dados quase inteiramente usando objetos Recordset. Todos os objetos Recordset consistem em registros (linhas) e campos (colunas). Dependendo da funcionalidade com suporte do provedor, alguns métodos ou propriedades Recordset podem não estar disponíveis.

ADODB.Recordset é o ProgID que deve ser usado para criar um objeto Recordset. Aplicativos existentes que fazem referência ao ProgID ADOR.Recordset desatualizado continuarão funcionando sem recompilar, mas o novo desenvolvimento deve fazer referência ao ADODB.Recordset.

Há quatro tipos de cursor diferentes definidos no ADO:

  • Cursor dinâmico Permite exibir adições, alterações e exclusões por outros usuários; permite todos os tipos de movimentação por meio do Recordset que não dependem de indicadores; e permite indicadores se o provedor dá suporte a eles.

  • Cursor de conjunto de chaves Comporta-se como um cursor dinâmico, exceto que ele impede que você veja registros que outros usuários adicionam e impede o acesso a registros que outros usuários excluem. As alterações de dados de outros usuários ainda ficarão visíveis. Ele sempre dá suporte a indicadores e, portanto, permite todos os tipos de movimentação por meio do Recordset.

  • Cursor estático Fornece uma cópia estática de um conjunto de registros para você usar a fim de localizar dados ou gerar relatórios; sempre permite indicadores e, portanto, permite todos os tipos de movimento por meio do Recordset. As adições, as alterações ou as exclusões por outros usuários não ficarão visíveis. Esse é o único tipo de cursor permitido quando você abre um objeto Recordset do lado do cliente.

  • Cursor de somente avanço Permite que você percorra o Recordset apenas avançando. As adições, as alterações ou as exclusões por outros usuários não ficarão visíveis. Isso melhora o desempenho em situações em que você precisa fazer apenas uma única passagem por meio de um Recordset.

Defina a propriedade CursorType antes de abrir o Recordset para escolher o tipo de cursor, ou transmita um argumento CursorType com o método Open. Alguns provedores não dão suporte a todos os tipos de cursor. Verifique a documentação do provedor. Se você não especificar um tipo de cursor, o ADO abrirá um cursor de somente avanço por padrão.

Se a propriedade CursorLocation estiver definida como adUseClient para abrir um Recordset, a propriedade UnderlyingValue em objetos Field não estará disponível no objeto Recordset retornado. Quando usado com alguns provedores (como o Provedor ODBC da Microsoft para OLE DB em conjunto com o Microsoft SQL Server), você pode criar objetos Recordset independentemente de um objeto Connection definido anteriormente com a transmissão de uma cadeia de conexão com o método Open. O ADO ainda cria um objeto Connection, mas não atribui esse objeto a uma variável de objeto. No entanto, se você estiver abrindo vários objetos Recordset na mesma conexão, deverá criar e abrir explicitamente um objeto Connection. Isso atribui o objeto Connection a uma variável de objeto. Se você não usar essa variável de objeto ao abrir seus objetos Recordset, o ADO criará outro objeto Connection para cada novo Recordset, mesmo que você transmita a mesma cadeia de conexão.

Você pode criar quantos objetos Recordset forem necessários.

Quando você abre um Recordset, o registro atual é posicionado no primeiro registro (se houver) e as propriedades BOF e EOF são definidas como False. Se não houver registros, as configurações de propriedade BOF e EOF serão True.

Você pode usar os métodos MoveFirst, MoveLast, MoveNext e MovePrevious; o método Move; e as propriedades AbsolutePosition, AbsolutePage e Filter para reposicionar o registro atual, supondo que o provedor dê suporte à funcionalidade pertinente. Os objetos Recordset de somente avanço dão suporte apenas ao método MoveNext. Ao usar os métodos Move para visitar cada registro (ou enumerar o Recordset), você poderá usar as propriedades BOF e EOF para determinar se foi além do início ou final do Recordset.

Antes de usar alguma funcionalidade de um objeto Recordset, você precisará chamar o método Supports no objeto para verificar se a funcionalidade tem suporte ou está disponível. Você não deve usar a funcionalidade quando o método Supports retorna false. Por exemplo, você poderá usar o método MovePrevious somente se Recordset.Supports(adMovePrevious) retornar True. Caso contrário, você receberá um erro, pois o objeto Recordset pode ter sido fechado e a funcionalidade considerada indisponível na instância. Se não houver suporte a um recurso no qual você esteja interessado, Supports também retornará false. Nesse caso, você deve evitar chamar a propriedade ou o método correspondente no objeto Recordset.

Os objetos Recordset podem dar suporte a dois tipos de atualização: imediato e em lote. Na atualização imediata, todas as alterações nos dados são gravadas imediatamente na fonte de dados subjacente depois que você chama o método Update. Você também pode transmitir matrizes de valores como parâmetros com os métodos AddNew e Update e atualizar simultaneamente vários campos em um registro.

Se um provedor der suporte à atualização em lote, você poderá fazer com que o provedor armazene alterações em cache em mais de um registro e as transmita em uma única chamada para o banco de dados com o método UpdateBatch. Isso se aplica a alterações feitas com os métodos AddNew, Update e Delete. Depois de chamar o método UpdateBatch, você pode usar a propriedade Status para verificar se há conflitos de dados a fim de resolvê-los.

Observação

Para executar uma consulta sem usar um objeto Command, transmita uma cadeia de consulta para o método Open de um objeto Recordset. No entanto, um objeto Command é necessário quando você deseja persistir o texto do comando e executá-lo novamente ou usar parâmetros de consulta.

A propriedade Mode rege as permissões de acesso.

A coleção Fields é o membro padrão do objeto Recordset. Como resultado, as duas instruções de código a seguir são equivalentes.

Debug.Print objRs.Fields.Item(0)  ' Both statements print   
Debug.Print objRs(0)              '  the Value of Item(0).

Quando um objeto Recordset é transmitido entre processos, apenas os valores de conjunto de linhas sofrem marshal; as propriedades do objeto Recordset são ignoradas. Durante o unmarshaling, o conjunto de linhas é descompactado em um objeto Recordset recém-criado, que também define suas propriedades como os valores padrão.

O objeto Recordset é seguro para scripts.

Esta seção contém o tópico a seguir.

Consulte Também

Objeto Connection (ADO)
Coleção Fields (ADO)
Coleção Properties (ADO)
Apêndice A: Provedores