Compartilhar via


Classe CDaoRecordset

Representa um conjunto de registros selecionados de uma fonte de dados.

Observação

O DAO (Objeto de Acesso a Dados) é suportado pelo Office 2013. DAO 3.6 é a versão final e está obsoleta.

Sintaxe

class CDaoRecordset : public CObject

Membros

Construtores públicos

Nome Descrição
CDaoRecordset::CDaoRecordset Constrói um objeto CDaoRecordset.

Métodos públicos

Nome Descrição
CDaoRecordset::AddNew Prepara-se para adicionar um novo registro. Chame Atualização para concluir a adição.
CDaoRecordset::CanAppend Retorna diferente de zero se novos registros puderem ser adicionados ao conjunto de registros por meio da função de membro AddNew.
CDaoRecordset::CanBookmark Retornará diferente de zero se o conjunto de registros der suporte a indicadores.
CDaoRecordset::CancelUpdate Cancela todas as atualizações pendentes devido a uma operação Edit ou AddNew .
CDaoRecordset::CanRestart Retorna diferente de zero se Requery puder ser chamado para executar a consulta do conjunto de registros novamente.
CDaoRecordset::CanScroll Retorna diferente de zero se você puder percorrer os registros.
CDaoRecordset::CanTransact Retornará diferente de zero se a fonte de dados der suporte a transações.
CDaoRecordset::CanUpdate Retornará diferente de zero se o conjunto de registros puder ser atualizado (você pode adicionar, atualizar ou excluir registros).
CDaoRecordset::Close Fecha o conjunto de registros.
CDaoRecordset::Delete Exclui o registro atual do conjunto de registros. Você deve avançar explicitamente para outro registro após a exclusão.
CDaoRecordset::DoFieldExchange Chamado para trocar dados (em ambas as direções) entre os membros de dados de campo do conjunto de registros e o registro correspondente na fonte de dados. Implementa o DFX (troca de campo de registro do DAO).
CDaoRecordset::Edit Prepara-se para alterações no registro atual. Chame Update para concluir a edição.
CDaoRecordset::FillCache Preenche todo ou uma parte de um cache local para um objeto de conjunto de registros que contém dados de uma fonte de dados ODBC.
CDaoRecordset::Find Localiza o primeiro, próximo, anterior ou último local de uma cadeia de caracteres específica em um conjunto de registros do tipo dynaset que atende aos critérios especificados e transforma esse registro no registro atual.
CDaoRecordset::FindFirst Localiza o primeiro registro em um conjunto de registros do tipo dynaset ou do tipo snapshot que atende aos critérios especificados e transforma esse registro no registro atual.
CDaoRecordset::FindLast Localiza o último registro em um conjunto de registros do tipo dynaset ou do tipo snapshot que atende aos critérios especificados e transforma esse registro no registro atual.
CDaoRecordset::FindNext Localiza o próximo registro em um conjunto de registros do tipo dynaset ou do tipo snapshot que atende aos critérios especificados e transforma esse registro no registro atual.
CDaoRecordset::FindPrev Localiza o registro anterior em um conjunto de registros do tipo dynaset ou do tipo snapshot que atende aos critérios especificados e transforma esse registro no registro atual.
CDaoRecordset::GetAbsolutePosition Retorna o número de registro do registro atual do objeto de um conjunto de registros.
CDaoRecordset::GetBookmark Retorna um valor que representa o indicador em um registro.
CDaoRecordset::GetCacheSize Retorna um valor que especifica o número de registros em um conjunto de registros do tipo dynaset que contém dados a serem armazenados em cache localmente de uma fonte de dados ODBC.
CDaoRecordset::GetCacheStart Retorna um valor que especifica o indicador do primeiro registro no conjunto de registros a ser armazenado em cache.
CDaoRecordset::GetCurrentIndex Retorna um CString que contém o nome do índice usado mais recentemente em um CDaoRecordset de tipo de tabela e indexado.
CDaoRecordset::GetDateCreated Retorna a data e a hora em que a tabela base subjacente a um objeto CDaoRecordset foi criada
CDaoRecordset::GetDateLastUpdated Retorna a data e a hora da alteração mais recente feita no design de uma tabela base subjacente a um objeto CDaoRecordset.
CDaoRecordset::GetDefaultDBName Retorna o nome da fonte de dados padrão.
CDaoRecordset::GetDefaultSQL Chamado para obter a cadeia de caracteres SQL padrão a ser executada.
CDaoRecordset::GetEditMode Retorna um valor que indica o estado da edição do registro atual.
CDaoRecordset::GetFieldCount Retorna um valor que representa o número de campos em um conjunto de registros.
CDaoRecordset::GetFieldInfo Retorna tipos específicos de informações sobre os campos no conjunto de registros.
CDaoRecordset::GetFieldValue Retorna o valor de um campo em um conjunto de registros.
CDaoRecordset::GetIndexCount Recupera o número de índices em uma tabela subjacente a um conjunto de registros.
CDaoRecordset::GetIndexInfo Retorna vários tipos de informações sobre um índice.
CDaoRecordset::GetLastModifiedBookmark Usado para determinar o registro adicionado ou atualizado mais recentemente.
CDaoRecordset::GetLockingMode Retorna um valor que indica o tipo de bloqueio que está vigente durante a edição.
CDaoRecordset::GetName Retorna um CString que contém o nome do conjunto de registros.
CDaoRecordset::GetParamValue Recupera o valor atual do parâmetro especificado armazenado no objeto DAOParameter subjacente.
CDaoRecordset::GetPercentPosition Retorna a posição do registro atual como uma porcentagem do número total de registros.
CDaoRecordset::GetRecordCount Retorna o número de registros acessados em um objeto de conjunto de registros.
CDaoRecordset::GetSQL Obtém a cadeia de caracteres SQL usada para selecionar registros para o conjunto de registros.
CDaoRecordset::GetType Chamado para determinar o tipo de conjunto de registros: tipo de tabela, tipo de dynaset ou tipo de snapshot.
CDaoRecordset::GetValidationRule Retorna um CString contendo o valor que valida os dados à medida que são inseridos em um campo.
CDaoRecordset::GetValidationText Recupera o texto exibido quando uma regra de validação não é atendida.
CDaoRecordset::IsBOF Retornará diferente de zero se o conjunto de registros tiver sido posicionado antes do primeiro registro. Não há registro atual.
CDaoRecordset::IsDeleted Retornará diferente de zero se o conjunto de registros estiver posicionado em um registro excluído.
CDaoRecordset::IsEOF Retornará diferente de zero se o conjunto de registros tiver sido posicionado depois do último registro. Não há registro atual.
CDaoRecordset::IsFieldDirty Retornará diferente de zero se o campo especificado no registro atual tiver sido alterado.
CDaoRecordset::IsFieldNull Retornará diferente de zero se o campo especificado no registro atual for nulo (sem ter valor).
CDaoRecordset::IsFieldNullable Retornará diferente de zero se o campo especificado no registro atual puder ser definido como nulo (sem valor).
CDaoRecordset::IsOpen Retornará diferente de zero se Open tiver sido chamado anteriormente.
CDaoRecordset::Move Posiciona o conjunto de registros para um número especificado de registros do registro atual em qualquer direção.
CDaoRecordset::MoveFirst Posiciona o registro atual no primeiro registro no conjunto de registros.
CDaoRecordset::MoveLast Posiciona o registro atual no último registro no conjunto de registros.
CDaoRecordset::MoveNext Posiciona o registro atual no próximo registro no conjunto de registros.
CDaoRecordset::MovePrev Posiciona o registro atual no registro anterior no conjunto de registros.
CDaoRecordset::Open Cria um novo conjunto de registros de uma tabela, dynaset ou snapshot.
CDaoRecordset::Requery Executa a consulta do conjunto de registros novamente para atualizar os registros selecionados.
CDaoRecordset::Seek Localiza o registro em um objeto de conjunto de registros do tipo tabela indexado que atende aos critérios especificados para o índice atual e transforma esse registro no registro atual.
CDaoRecordset::SetAbsolutePosition Define o número de registro do registro atual do objeto de um conjunto de registros.
CDaoRecordset::SetBookmark Posiciona o conjunto de registros em um registro que contém o indicador especificado.
CDaoRecordset::SetCacheSize Define um valor que especifica o número de registros em um conjunto de registros do tipo dynaset que contém dados a serem armazenados em cache localmente de uma fonte de dados ODBC.
CDaoRecordset::SetCacheStart Define um valor que especifica o indicador do primeiro registro no conjunto de registros a ser armazenado em cache.
CDaoRecordset::SetCurrentIndex Chamado para definir um índice em um conjunto de registros do tipo tabela.
CDaoRecordset::SetFieldDirty Marca o campo especificado no registro atual conforme alterado.
CDaoRecordset::SetFieldNull Define o valor do campo especificado no registro atual como Nulo (sem valor).
CDaoRecordset::SetFieldValue Define o valor de um campo em um conjunto registros.
CDaoRecordset::SetFieldValueNull Define o valor de um campo em um conjunto registros para Null. (sem valor)
CDaoRecordset::SetLockingMode Define um valor que indica o tipo de bloqueio que se tornará vigente durante a edição.
CDaoRecordset::SetParamValue Define o valor atual do parâmetro especificado armazenado no objeto DAOParameter subjacente.
CDaoRecordset::SetParamValueNull Define o valor atual do parâmetro especificado como Null (sem valor).
CDaoRecordset::SetPercentPosition Define a posição do registro atual como um local correspondente a uma porcentagem do número total de registros em um conjunto de registros.
CDaoRecordset::Update Conclui uma operação AddNew ou Edit salvando os dados novos ou editados na fonte de dados.

Membros de Dados Públicos

Nome Descrição
CDaoRecordset::m_bCheckCacheForDirtyFields Contém um sinalizador que indica se os campos são marcados automaticamente como alterados.
CDaoRecordset::m_nFields Contém o número de membros de dados de campo na classe de conjunto de registros e o número de colunas selecionadas pelo conjunto de registros da fonte de dados.
CDaoRecordset::m_nParams Contém o número de membros de dados de parâmetro na classe do conjunto de registros — o número de parâmetros passados com a consulta do conjunto de registros
CDaoRecordset::m_pDAORecordset Um ponteiro para a interface DAO subjacente ao objeto do conjunto de registros.
CDaoRecordset::m_pDatabase Banco de dados de origem deste conjunto de resultados. Contém um ponteiro para um objeto CDaoDatabase.
CDaoRecordset::m_strFilter Contém uma cadeia de caracteres usada para construir uma instrução SQL WHERE.
CDaoRecordset::m_strSort Contém uma cadeia de caracteres usada para construir uma instrução SQL ORDER BY.

Comentários

Conhecidos como "conjuntos de registros", os objetos CDaoRecordset estão disponíveis nas três formas a seguir:

  • Os conjuntos de registros de tipo de tabela representam uma tabela base que você pode usar para examinar, adicionar, alterar ou excluir registros de uma única tabela de banco de dados.

  • Conjuntos de registros do tipo dynaset são o resultado de uma consulta que pode ter registros atualizáveis. Esses conjuntos de registros podem ser usados para examinar, adicionar, alterar ou excluir registros de uma tabela ou tabela de banco de dados subjacente. Os conjuntos de registros do tipo dynaset podem conter campos de uma ou mais tabelas em um banco de dados.

  • Conjuntos de registros do tipo snapshot são uma cópia estática de um conjunto de registros que você pode usar para localizar dados ou gerar relatórios. Esses conjuntos de registros podem conter campos de uma ou mais tabelas em um banco de dados, mas não podem ser atualizados.

Cada forma de conjunto de registros representa um conjunto de registros corrigidos no momento em que o conjunto de registros é aberto. Quando você move até um registro em um conjunto de registros do tipo tabela ou em um conjunto de registros do tipo dynaset, ele reflete as alterações feitas no registro depois que o conjunto de registros é aberto, seja por outros usuários ou por outros conjuntos de registros em seu aplicativo. (Um conjunto de registros do tipo instantâneo não pode ser atualizado.) Você pode usar CDaoRecordset diretamente ou derivar uma classe de conjunto de registros específica do aplicativo de CDaoRecordset. Em seguida, você pode:

  • Percorra os registros.

  • Defina um índice e procure rapidamente registros usando Seek (somente conjuntos de registros do tipo tabela).

  • Localize registros baseados em uma comparação de cadeia de caracteres: "<", "<=", "=", ">=", or ">" (conjuntos de registros do tipo dynaset e snapshot).

  • Atualize os registros e especifique um modo de bloqueio (exceto conjuntos de registros do tipo snapshot).

  • Filtrar o conjunto de registros para restringir quais registros ele seleciona dentre os disponíveis na fonte de dados.

  • Organizar o conjunto de registros.

  • Parametrizar o conjunto de registros para personalizar sua seleção com informações não conhecidas até o tempo de execução.

A classe CDaoRecordset fornece uma interface semelhante à da classe CRecordset. A principal diferença é que a classe CDaoRecordset acessa dados por meio de um DAO (Objeto de acesso a dados) com base em OLE. A classe CRecordset acessa o DBMS por meio da ODBC (Open Database Connectivity) e um driver ODBC para esse DBMS.

Observação

As classes de banco de dados do DAO são diferentes das classes de banco de dados MFC com base no ODBC (Open Database Connectivity). Todos os nomes de classe de banco de dados do DAO têm o prefixo "CDao". Você ainda pode acessar fontes de dados ODBC com as classes DAO; as classes DAO geralmente oferecem recursos superiores porque são específicas do mecanismo de banco de dados do Microsoft Jet.

Você pode usar CDaoRecordset diretamente ou derivar uma classe de CDaoRecordset. Para usar uma classe de conjunto de registros em ambos os casos, abra um banco de dados e construa um objeto de conjunto de registros, passando o construtor um ponteiro para o objeto CDaoDatabase. Você também pode construir um objeto CDaoRecordset e permitir que o MFC crie um objeto CDaoDatabase temporário para você. Em seguida, chame a função de membro Open do conjunto de registros, especificando se o objeto é um conjunto de registros do tipo tabela, um conjunto de registros do tipo dynaset ou um conjunto de registros do tipo snapshot. Chamar Open seleciona dados do banco de dados e recupera o primeiro registro.

Use as funções membros do objeto e os membros de dados para percorrer os registros e operá-los. As operações disponíveis dependem se o objeto é um conjunto de registros do tipo tabela, um conjunto de registros do tipo dynaset ou um conjunto de registros do tipo instantâneo e se ele é atualizável ou somente leitura — isso depende da capacidade do banco de dados ou da fonte de dados ODBC (Open Database Connectivity). Para atualizar registros que podem ter sido alterados ou adicionados desde a chamada de Open, chame a função de membro Requery do objeto. Chame a função de membro Close do objeto e destrua o objeto quando terminar.

CDaoRecordset usa a DFX (troca de campo de registro) da DAO para dar suporte à leitura e à atualização de campos de registro por meio de membros C++ com segurança de tipo de sua classe derivada de CDaoRecordset ou CDaoRecordset. Você também pode implementar a associação dinâmica de colunas em um banco de dados sem usar o mecanismo DFX usando GetFieldValue e SetFieldValue.

Para obter informações relacionadas, consulte o tópico "Conjunto de registros" na ajuda do DAO.

Hierarquia de herança

CObject

CDaoRecordset

Requisitos

Cabeçalho: afxdao.h

CDaoRecordset::AddNew

Chame essa função de membro para adicionar um novo registro a um conjunto de registros do tipo tabela ou do tipo dynaset.

virtual void AddNew();

Comentários

Os campos do registro são inicialmente Null. (Na terminologia de banco de dados, Null significa "não ter valor" e não é o mesmo que NULL em C++.) Para concluir a operação, você deve chamar a função de membro Update . Update salva as alterações feitas na fonte de dados.

Cuidado

Se você editar um registro e avançar para outro registro sem chamar Update, suas alterações serão perdidas sem aviso.

Se você adicionar um registro a um conjunto de registros do tipo dynaset chamando AddNew, o registro ficará visível no conjunto de registros e será incluído na tabela subjacente em que ele se tornará visível para quaisquer novos objetos CDaoRecordset.

A posição do novo registro depende do tipo de conjunto de registros:

  • Em um conjunto de registros do tipo dynaset, onde o novo registro é inserido não é garantido. Esse comportamento mudou com o Microsoft Jet 3.0 por motivos de desempenho e simultaneidade. Se sua meta é tornar o registro recém-adicionado o registro atual, obtenha o indicador do último registro modificado e vá para esse indicador:
rs.SetBookmark(rs.GetLastModifiedBookmark());
  • Em um conjunto de registros do tipo tabela para o qual um índice foi especificado, os registros são retornados em seu local apropriado na ordem de classificação. Se nenhum índice tiver sido especificado, novos registros serão retornados no final do conjunto de registros.

O registro que era atual antes de você usar AddNew permanece atual. Se você quiser tornar o novo registro atual e o conjunto de registros oferecer suporte a indicadores, chame SetBookmark para o indicador identificado pela configuração da propriedade LastModified do objeto de conjunto de registros DAO subjacente. Fazer isso é útil para determinar o valor para campos de contador (incremento automático) em um registro adicionado. Para obter mais informações, confira GetLastModifiedBookmark.

Se o banco de dados der suporte a transações, você poderá tornar sua chamada AddNew parte de uma transação. Para obter mais informações sobre transações, confira a classe CDaoWorkspace. Você deve chamar CDaoWorkspace::BeginTrans antes de chamar AddNew.

É ilegal chamar AddNew para um conjunto de registros cuja função de membro Open não foi chamada. A CDaoException será lançado se você chamar AddNew um conjunto de registros que não pode ser acrescentado. Você pode determinar se o conjunto de registros pode ser atualizado chamando CanAppend.

A estrutura marca os membros de dados de campo alterados para garantir que eles sejam gravados no registro na fonte de dados pelo mecanismo de troca de campo de registro (DFX) do DAO. Alterar o valor de um campo geralmente define o campo sujo automaticamente, portanto, você raramente precisará chamar SetFieldDirty por conta própria, mas às vezes pode querer garantir que as colunas sejam explicitamente atualizadas ou inseridas, independentemente do valor que está no membro de dados do campo. O mecanismo DFX também emprega o uso de PSEUDO NULL. Para obter mais informações, confira CDaoFieldExchange::m_nOperation.

Se o mecanismo de buffer duplo não estiver sendo usado, alterar o valor do campo não definirá automaticamente o campo como sujo. Nesse caso, é necessário definir explicitamente o campo sujo. O sinalizador contido em m_bCheckCacheForDirtyFields controla essa verificação automática de campo.

Observação

Se os registros forem armazenados em buffer duplo (ou seja, a verificação automática de campo está habilitada), chamar CancelUpdate restaurará as variáveis de membro para os valores que eles tinham antes de AddNew ou Edit serem chamados.

Para obter informações relacionadas, consulte os tópicos "Método AddNew", "Método CancelUpdate", "Propriedade LastModified" e "Propriedade EditMode" na ajuda do DAO.

CDaoRecordset::CanAppend

Chame essa função de membro para determinar se o conjunto de registros aberto anteriormente permite que você adicione novos registros chamando a função de membro AddNew.

BOOL CanAppend() const;

Valor de retorno

Diferente de zero se o conjunto de registros permitir a adição de novos registros; caso contrário, 0. CanAppend Retorna 0 se você abriu o conjunto de registros como somente leitura.

Comentários

Para obter informações relacionadas, consulte o tópico "Método Append" na ajuda do DAO.

CDaoRecordset::CanBookmark

Chame essa função de membro para determinar se o conjunto de registros aberto anteriormente permite marcar registros individualmente usando indicadores.

BOOL CanBookmark();

Valor de retorno

Diferente de zero se o conjunto de registros der suporte a indicadores, caso contrário, será zero.

Comentários

Se você estiver usando conjuntos de registros baseados inteiramente em tabelas do mecanismo de banco de dados do Microsoft Jet, os indicadores poderão ser usados, exceto em conjuntos de registros do tipo instantâneo sinalizados como conjuntos de registros de rolagem somente para frente. Outros produtos de banco de dados (fontes de dados ODBC externas) podem não dar suporte a indicadores.

Para obter informações relacionadas, consulte o tópico "Propriedade Indicadora" na ajuda do DAO.

CDaoRecordset::CancelUpdate

A função de membro CancelUpdate cancela qualquer atualização pendente devido a uma operação Edit ou AddNew.

virtual void CancelUpdate();

Comentários

Por exemplo, se um aplicativo chamar a Edit função de membro ou AddNew e não tiver chamado Update, CancelUpdate cancelará todas as alterações feitas após Edit ou AddNew foi chamada.

Observação

Se os registros forem armazenados em buffer duplo (ou seja, a verificação automática de campo está habilitada), chamar CancelUpdate restaurará as variáveis de membro para os valores que eles tinham antes de AddNew ou Edit serem chamados.

Se não houver nenhuma Edit AddNew operação pendente, CancelUpdate fará com que o MFC gere uma exceção. Chame a função de membro GetEditMode para determinar se há uma operação pendente que pode ser cancelada.

Para obter informações relacionadas, consulte o tópico "Método CancelUpdate" na ajuda do DAO.

CDaoRecordset::CanRestart

Chame essa função de membro para determinar se o conjunto de registros permite reiniciar sua consulta (para atualizar seus registros) chamando a função de membro Requery.

BOOL CanRestart();

Valor de retorno

Diferente de zero se Requery puder ser chamado para executar a consulta do conjunto de registros novamente, caso contrário, será 0.

Comentários

Os conjuntos de registros do tipo tabela não oferecem suporte a Requery.

Se Requery não houver suporte, chame Fechar e Abrir para atualizar os dados. Você pode chamar Requery para atualizar a consulta de parâmetro subjacente de um objeto de conjunto de registros depois que os valores do parâmetro forem alterados.

Para obter informações relacionadas, consulte o tópico "Propriedade Restartable" na ajuda do DAO.

CDaoRecordset::CanScroll

Chame essa função de membro para determinar se o conjunto de registros permite a deslocamento.

BOOL CanScroll() const;

Valor de retorno

Diferente de zero se você puder se deslocar pelos registros, caso contrário, será 0.

Comentários

Se você chamar Open com dbForwardOnly, o conjunto de registros só poderá se deslocar para frente.

Para obter informações relacionadas, consulte o tópico "Posicionando o ponteiro de registro atual com DAO" na Ajuda do DAO.

CDaoRecordset::CanTransact

Chame essa função de membro para determinar se o conjunto de registros permite transações.

BOOL CanTransact();

Valor de retorno

Diferente de zero se a fonte de dados subjacente dá suporte a transações, caso contrário, será 0.

Comentários

Para obter informações relacionadas, confira o tópico "Propriedade Transactions" na ajuda do DAO.

CDaoRecordset::CanUpdate

Chame essa função de membro para determinar se o conjunto de registros pode ser atualizado.

BOOL CanUpdate() const;

Valor de retorno

Diferente de zero se o conjunto de registros puder ser atualizado (adicionar, atualizar e excluir registros), caso contrário, será 0.

Comentários

Um conjunto de registros poderá ser somente leitura se a fonte de dados subjacente for somente leitura ou se você especificou dbReadOnly para nOptions quando chamou Open para o conjunto de registros.

Para obter informações relacionadas, consulte os tópicos "Método AddNew", "Método Edit", "Método Delete", "Método Update" e "Propriedade Updatable" na Ajuda do DAO.

CDaoRecordset::CDaoRecordset

Constrói um objeto CDaoRecordset.

CDaoRecordset(CDaoDatabase* pDatabase = NULL);

Parâmetros

pDatabase
Contém um ponteiro para um objeto CDaoDatabase ou o valor NULL. Se não for NULL e a CDaoDatabase função membro do Open objeto não tiver sido chamada para conectá-la à fonte de dados, o conjunto de registros tentará abri-la para você durante sua própria chamada Open . Se você passar NULL, um objeto CDaoDatabase será construído e conectado para você usando as informações de fonte de dados especificadas se você deu origem à classe de conjunto de registros CDaoRecordset.

Comentários

Você pode usar CDaoRecordset diretamente ou derivar uma classe específica do aplicativo de CDaoRecordset. Você pode usar ClassWizard para derivar suas classes de conjunto de registros.

Observação

Se você derivar uma classe CDaoRecordset, sua classe derivada deverá fornecer seu próprio construtor. No construtor de sua classe derivada, chame o construtor CDaoRecordset::CDaoRecordset, passando os parâmetros apropriados para ele.

Passe NULL para o construtor do conjunto de registros para que um objeto CDaoDatabase seja construído e conectado automaticamente. Esse é um atalho útil que não exige que você construa e conecte um CDaoDatabase objeto antes de construir seu conjunto de registros. Se o CDaoDatabase objeto não estiver aberto, um objeto CDaoWorkspace também será criado para você que usa o workspace padrão. Para obter mais informações, consulte CDaoDatabase::CDaoDatabase.

CDaoRecordset::Close

Fechar um objeto CDaoRecordset o remove da coleção de conjuntos de registros abertos no banco de dados associado.

virtual void Close();

Comentários

Como Close não destrói o CDaoRecordset objeto, você pode reutilizá-lo chamando Open a mesma fonte de dados ou uma fonte de dados diferente.

Todas as instruções AddNew ou Edit pendentes são canceladas e todas as transações pendentes são revertidas. Se você quiser preservar adições ou edições pendentes, chame Update antes de chamar Close para cada conjunto de registros.

Você pode chamar Open novamente depois de chamar Close. Isso permite reutilizar o objeto do conjunto de registros. Uma alternativa melhor é chamar Requery, se possível.

Para obter informações relacionadas, consulte o tópico "Método Close" na ajuda do DAO.

CDaoRecordset::Delete

Chame essa função de membro para excluir o registro atual em um objeto de conjunto de registros aberto do tipo dynaset ou tipo de tabela.

virtual void Delete();

Comentários

Após uma exclusão bem-sucedida, os membros de dados de campo do conjunto de registros são definidos como um valor Null e você deve chamar explicitamente uma das funções de membro de navegação do conjunto de registros (Move, Seek, SetBookmark e assim por diante) para sair do registro excluído. Quando você exclui registros de um conjunto de registros, deve haver um registro atual no conjunto de registros antes de chamar Delete; caso contrário, o MFC gerará uma exceção.

Delete remove o registro atual e o torna inacessível. Embora você não possa editar ou usar o registro excluído, ele permanece atual. No entanto, depois de passar para outro registro, você não poderá tornar o registro excluído atual novamente.

Cuidado

O conjunto de registros deve ser atualizável e deve haver um registro válido atual no conjunto de registros quando você chamar Delete. Por exemplo, se você excluir um registro, mas não rolar para um novo registro antes de chamar Delete novamente, Delete o lançará um CDaoException.

Você pode reverter a exclusão de um registro se usar transações e chamar a função de membro CDaoWorkspace::Rollback. Se a tabela base for a tabela primária em uma relação de exclusão em cascata, excluir o registro atual também poderá excluir um ou mais registros em uma tabela estrangeira. Para obter mais informações, consulte a definição "exclusão em cascata" na ajuda do DAO.

Diferentemente de AddNew e Edit, uma chamada para Delete não é seguida por uma chamada para Update.

Para obter informações relacionadas, consulte os tópicos "Método AddNew", "Método Edit", "Método Delete", "Método Update" e "Propriedade Updatable" na Ajuda do DAO.

CDaoRecordset::DoFieldExchange

A estrutura chama essa função de membro para trocar dados automaticamente entre os membros de dados de campo do objeto do conjunto de registros e as colunas correspondentes do registro atual na fonte de dados.

virtual void DoFieldExchange(CDaoFieldExchange* pFX);

Parâmetros

pFX
Contém um ponteiro para um objeto CDaoFieldExchange. A estrutura já terá configurado esse objeto para especificar um contexto para a operação de troca de campo.

Comentários

Ele também associa seus membros de dados de parâmetro, se houver, a espaços reservados de parâmetro na cadeia de caracteres de instrução SQL para a seleção do conjunto de registros. A troca de dados de campo, chamada DFX (troca de campo de registro de DAO), funciona em ambas as direções: dos membros de dados de campo do objeto do conjunto de registros aos campos do registro na fonte de dados e do registro na fonte de dados para o objeto do conjunto de registros. Se você estiver vinculando colunas dinamicamente, não será necessário implementar DoFieldExchangeo .

A única ação que você normalmente deve tomar para implementar DoFieldExchange para sua classe de conjunto de registros derivada é criar a classe com ClassWizard e especificar os nomes e tipos de dados dos membros de dados do campo. Você também pode adicionar código ao que o ClassWizard grava para especificar membros de dados de parâmetro. Se todos os campos forem vinculados dinamicamente, essa função ficará inativa, a menos que você especifique membros de dados de parâmetro.

Quando você declara sua classe de conjunto de registros derivada com ClassWizard, o assistente grava uma substituição de DoFieldExchange para você, que se assemelha ao exemplo a seguir:

void CCustSet::DoFieldExchange(CDaoFieldExchange *pFX)
{
   pFX->SetFieldType(CDaoFieldExchange::param);
   DFX_Text(pFX, _T("Param"), m_strParam);
   pFX->SetFieldType(CDaoFieldExchange::outputColumn);
   DFX_Short(pFX, _T("EmployeeID"), m_EmployeeID);
   DFX_Text(pFX, _T("LastName"), m_LastName);
   DFX_Short(pFX, _T("Age"), m_Age);
   DFX_DateTime(pFX, _T("hire_date"), m_hire_date);
   DFX_DateTime(pFX, _T("termination_date"), m_termination_date);

   CDaoRecordset::DoFieldExchange(pFX);
}

CDaoRecordset::Edit

Chame essa função de membro para permitir alterações no registro atual.

virtual void Edit();

Comentários

Depois de chamar a função de membro Edit, as alterações feitas nos campos do registro atual são copiadas para o buffer de cópia. Depois de fazer as alterações desejadas no registro, chame Update para salvar suas alterações. Edit salva os valores dos membros de dados do conjunto de registros. Se você chamar Edit, fizer alterações e chamar Edit novamente, os valores do registro serão restaurados para o que eram antes da primeira chamada Edit.

Cuidado

Se você editar um registro e executar qualquer operação que se mova para outro registro sem chamar Update primeiro, suas alterações serão perdidas sem aviso. Além disso, se você fechar o conjunto de registros ou o banco de dados pai, seu registro editado será descartado sem aviso.

Em alguns casos, é recomendável atualizar uma coluna tornando-a Null (sem dados). Para fazer isso, chame SetFieldNull com um parâmetro TRUE para marcar o campo Null; isso também faz com que a coluna seja atualizada. Se você quiser que um campo seja gravado na fonte de dados mesmo que seu valor não tenha sido alterado, chame SetFieldDirty com um parâmetro TRUE. Isso funciona mesmo se o campo tivesse o valor Null.

A estrutura marca os membros de dados de campo alterados para garantir que eles sejam gravados no registro na fonte de dados pelo mecanismo de troca de campo de registro (DFX) do DAO. Alterar o valor de um campo geralmente define o campo sujo automaticamente, portanto, você raramente precisará chamar SetFieldDirty por conta própria, mas às vezes pode querer garantir que as colunas sejam explicitamente atualizadas ou inseridas, independentemente do valor que está no membro de dados do campo. O mecanismo DFX também emprega o uso de PSEUDO NULL. Para obter mais informações, confira CDaoFieldExchange::m_nOperation.

Se o mecanismo de buffer duplo não estiver sendo usado, alterar o valor do campo não definirá automaticamente o campo como sujo. Nesse caso, é necessário definir explicitamente o campo sujo. O sinalizador contido em m_bCheckCacheForDirtyFields controla essa verificação automática de campo.

Quando o objeto do conjunto de registros é bloqueado de modo pessimista em um ambiente multiusuário, o registro permanece bloqueado a partir do momento que Edit é usado até que a atualização seja concluída. Se o conjunto de registros for bloqueado de forma otimista, o registro será bloqueado e comparado com o registro pré-editado pouco antes de ser atualizado no banco de dados. Se o registro tiver sido alterado desde que você chamou Edit, a operação Update falha e o MFC gera uma exceção. você pode alterar o modo de bloqueio com SetLockingMode.

Observação

O bloqueio otimista é sempre usado em formatos de banco de dados externos, como ODBC e ISAM instalável.

O registro atual permanece atual depois que você chama Edit. Para chamar Edit, deve haver um registro atual. Se não houver nenhum registro atual ou se o conjunto de registros não se referir a um objeto de conjunto de registros do tipo tabela aberta ou do tipo dynaset, ocorrerá uma exceção. A chamada Edit faz com que a chamada CDaoException seja gerada sob as seguintes condições:

  • Não há registro atual.

  • O banco de dados ou conjunto de registros é somente leitura.

  • Nenhum campo no registro é atualizável.

  • O banco de dados ou conjunto de registros foi aberto para uso exclusivo por outro usuário.

  • Outro usuário bloqueou a página que contém seu registro.

Se o banco de dados der suporte a transações, você poderá tornar sua chamada Edit parte de uma transação. Você deve ligar CDaoWorkspace::BeginTrans antes de ligar Edit e depois que o conjunto de registros for aberto. Chamar CDaoWorkspace::CommitTrans não substitui a chamada Update para concluir a Edit operação. Para obter mais informações sobre transações, confira a classe CDaoWorkspace.

Para obter informações relacionadas, consulte os tópicos "Método AddNew", "Método Edit", "Método Delete", "Método Update" e "Propriedade Updatable" na Ajuda do DAO.

CDaoRecordset::FillCache

Chame essa função de membro para armazenar em cache um número especificado de registros do conjunto de registros.

void FillCache(
    long* pSize = NULL,
    COleVariant* pBookmark = NULL);

Parâmetros

pSize
Especifica o número de linhas a serem preenchidas no cache. Se você omitir esse parâmetro, o valor será determinado pela configuração da propriedade CacheSize do objeto DAO subjacente.

pBookmark
Um COleVariant que especifica um indicador. O cache é preenchido a partir do registro indicado por esse indicador. Se você omitir esse parâmetro, o cache será preenchido a partir do registro indicado pela propriedade CacheStart do objeto DAO subjacente.

Comentários

O cache melhora o desempenho de um aplicativo que recupera ou busca dados de um servidor remoto. Um cache é espaço na memória local que contém os dados buscados mais recentemente do servidor, com a suposição de que os dados provavelmente serão solicitados novamente enquanto o aplicativo estiver em execução. Quando os dados são solicitados, o mecanismo de banco de dados do Microsoft Jet verifica primeiro o cache dos dados em vez de buscá-los no servidor, o que leva mais tempo. O uso do cache de dados em fontes de dados não ODBC não tem efeito, pois os dados não são salvos no cache.

Em vez de esperar que o cache seja preenchido com registros conforme eles são buscados, você pode preencher explicitamente o cache a qualquer momento chamando a função de membro FillCache. Essa é uma maneira mais rápida de preencher o cache porque FillCache busca vários registros ao mesmo tempo, em vez de um de cada vez. Por exemplo, enquanto cada tela cheia de registros está sendo exibida, você pode fazer seu aplicativo chamar FillCache para buscar a próxima tela de registros.

Qualquer banco de dados ODBC acessado com objetos de conjunto de registros pode ter um cache local. Para criar o cache, abra um objeto de conjunto de registros da fonte de dados remota e chame as funções de membro SetCacheSize e SetCacheStart do conjunto de registros. Se lSize e lBookmark criarem um intervalo parcial ou totalmente fora do intervalo especificado por SetCacheSize e SetCacheStart, a parte do conjunto de registros fora desse intervalo será ignorada e não será carregada no cache. Se FillCache solicitar mais registros do que os restantes na fonte de dados remota, somente os registros restantes serão buscados e nenhuma exceção será gerada.

Os registros buscados no cache não refletem as alterações feitas simultaneamente nos dados de origem por outros usuários.

FillCache busca somente registros que não ainda não foram armazenados em cache. Para forçar uma atualização de todos os dados armazenados em cache, chame a função de membro SetCacheSize com um parâmetro lSize igual a 0, chame SetCacheSize novamente com o parâmetro lSize igual ao tamanho do cache solicitado originalmente e, em seguida, chame FillCache.

Para obter informações relacionadas, consulte o tópico "Método FillCache" na ajuda do DAO.

CDaoRecordset::Find

Chame essa função de membro para localizar uma cadeia de caracteres específica em um conjunto de registros do tipo dynaset ou snapshot usando um operador de comparação.

virtual BOOL Find(
    long lFindType,
    LPCTSTR lpszFilter);

Parâmetros

lFindType
Um valor que indica o tipo de operação Find desejada. Os valores possíveis são:

  • AFX_DAO_NEXT localiza o próximo local de uma cadeia de caracteres correspondente.

  • AFX_DAO_PREV localiza o local anterior de uma cadeia de caracteres correspondente.

  • AFX_DAO_FIRST localiza o primeiro local de uma cadeia de caracteres correspondente.

  • AFX_DAO_LAST localiza o último local de uma cadeia de caracteres correspondente.

lpszFilter
Uma expressão de cadeia de caracteres (como a cláusula WHERE em uma instrução SQL sem a palavra WHERE) usada para localizar o registro. Por exemplo:

rs.Find(AFX_DAO_FIRST, _T("EmployeeID = 7"));
rs.Find(AFX_DAO_NEXT, _T("LastName = 'Jones'"));

Valor de retorno

Diferente de zero se forem encontrados registros correspondentes, caso contrário, será 0.

Comentários

Você pode encontrar a primeira, próxima, anterior ou última instância da cadeia de caracteres. Find é uma função virtual, para que você possa substituí-la e adicionar sua própria implementação. As funções de membro FindFirst, FindLast, FindNext e FindPrev chamam a função de membro Find, para que você possa usar Find para controlar o comportamento de todas as operações Find.

Para localizar um registro em um conjunto de registros do tipo tabela, chame a função de membro Seek.

Dica

Quanto menor o conjunto de registros que você tiver, mais eficaz Find será. Em geral, e especialmente com dados ODBC, é melhor criar uma nova consulta que recupere apenas os registros desejados.

Para obter informações relacionadas, consulte o tópico "Métodos FindFirst, FindLast, FindNext, FindPrevious" na ajuda do DAO.

CDaoRecordset::FindFirst

Chame essa função de membro para localizar o primeiro registro que corresponda a uma condição especificada.

BOOL FindFirst(LPCTSTR lpszFilter);

Parâmetros

lpszFilter
Uma expressão de cadeia de caracteres (como a cláusula WHERE em uma instrução SQL sem a palavra WHERE) usada para localizar o registro.

Valor de retorno

Diferente de zero se forem encontrados registros correspondentes, caso contrário, será 0.

Comentários

A função de membro FindFirst inicia sua pesquisa desde o início do conjunto de registros e pesquisa até o final do conjunto de registros.

Se você quiser incluir todos os registros em sua pesquisa (não apenas aqueles que atendem a uma condição específica) use uma das operações Mover para mover de registro para registro. Para localizar um registro em um conjunto de registros do tipo tabela, chame a função de membro Seek.

Se um registro que corresponde aos critérios não for localizado, o ponteiro do registro atual será indeterminado e FindFirst retornará zero. Se o conjunto de registros contiver mais de um registro que atenda aos critérios, FindFirst localiza a primeira ocorrência, FindNext localiza a próxima ocorrência e assim por diante.

Cuidado

Se você editar o registro atual, salve as alterações chamando a função de membro Update antes de migrar para outro registro. Se você mover para outro registro sem atualizar, suas alterações serão perdidas sem aviso.

As funções de membro Find pesquisam no local e na direção especificada na tabela a seguir:

Localizar operações Começar Direção de pesquisa
FindFirst Início do conjunto de registros Fim do conjunto de registros
FindLast Fim do conjunto de registros Início do conjunto de registros
FindNext Registro atual Fim do conjunto de registros
FindPrevious Registro atual Início do conjunto de registros

Observação

Quando você chama FindLasto , o mecanismo de banco de dados do Microsoft Jet preenche totalmente o conjunto de registros antes de iniciar a pesquisa, se isso ainda não tiver sido feito. A primeira pesquisa pode levar mais tempo do que as pesquisas subsequentes.

No entanto, usar uma das operações Find não é o mesmo que chamar MoveFirst ou MoveNext, o que simplesmente torna o primeiro ou o próximo registro atual sem especificar uma condição. Você pode seguir uma operação Find com uma operação Move.

Esteja ciente das seguintes informações ao usar as operações Find:

  • Se Find retornar diferente de zero, o registro atual não será definido. Nesse caso, você deve posicionar o ponteiro de registro atual de volta para um registro válido.

  • Você não pode usar uma operação Find com um conjunto de registros do tipo instantâneo de rolagem somente para frente.

  • Você deve usar o formato de data dos EUA (mês-dia-ano) ao pesquisar campos que contenham datas, mesmo que não esteja usando a versão dos EUA do mecanismo de banco de dados do Microsoft Jet; caso contrário, os registros correspondentes podem não ser encontrados.

  • Ao trabalhar com bancos de dados ODBC e grandes dynasets, você pode descobrir que o uso das operações Find é lento, principalmente quando se trabalha com conjuntos de registros grandes. Você pode melhorar o desempenho usando consultas SQL com cláusulas ORDERBY ou WHERE personalizadas, consultas de parâmetro ou objetos CDaoQuerydef que recuperam registros indexados específicos.

Para obter informações relacionadas, consulte o tópico "Métodos FindFirst, FindLast, FindNext, FindPrevious" na ajuda do DAO.

CDaoRecordset::FindLast

Chame essa função de membro para localizar o último registro que corresponda a uma condição especificada.

BOOL FindLast(LPCTSTR lpszFilter);

Parâmetros

lpszFilter
Uma expressão de cadeia de caracteres (como a cláusula WHERE em uma instrução SQL sem a palavra WHERE) usada para localizar o registro.

Valor de retorno

Diferente de zero se forem encontrados registros correspondentes, caso contrário, será 0.

Comentários

A função de membro FindLast inicia sua pesquisa no fim do conjunto de registros e pesquisa de trás para frente em direção ao início do conjunto de registros.

Se você quiser incluir todos os registros em sua pesquisa (não apenas aqueles que atendem a uma condição específica) use uma das operações Mover para mover de registro para registro. Para localizar um registro em um conjunto de registros do tipo tabela, chame a função de membro Seek.

Se um registro que corresponde aos critérios não for localizado, o ponteiro do registro atual será indeterminado e FindLast retornará zero. Se o conjunto de registros contiver mais de um registro que atenda aos critérios, FindFirst localiza a primeira ocorrência, FindNext localiza a próxima ocorrência após a primeira ocorrência e assim por diante.

Cuidado

Se você editar o registro atual, salve as alterações chamando a função de membro Update antes de migrar para outro registro. Se você mover para outro registro sem atualizar, suas alterações serão perdidas sem aviso.

No entanto, usar uma das operações Find não é o mesmo que chamar MoveFirst ou MoveNext, o que simplesmente torna o primeiro ou o próximo registro atual sem especificar uma condição. Você pode seguir uma operação Find com uma operação Move.

Esteja ciente das seguintes informações ao usar as operações Find:

  • Se Find retornar diferente de zero, o registro atual não será definido. Nesse caso, você deve posicionar o ponteiro de registro atual de volta para um registro válido.

  • Você não pode usar uma operação Find com um conjunto de registros do tipo instantâneo de rolagem somente para frente.

  • Você deve usar o formato de data dos EUA (mês-dia-ano) ao pesquisar campos que contenham datas, mesmo que não esteja usando a versão dos EUA do mecanismo de banco de dados do Microsoft Jet; caso contrário, os registros correspondentes podem não ser encontrados.

  • Ao trabalhar com bancos de dados ODBC e grandes dynasets, você pode descobrir que o uso das operações Find é lento, principalmente quando se trabalha com conjuntos de registros grandes. Você pode melhorar o desempenho usando consultas SQL com cláusulas ORDERBY ou WHERE personalizadas, consultas de parâmetro ou objetos CDaoQuerydef que recuperam registros indexados específicos.

Para obter informações relacionadas, consulte o tópico "Métodos FindFirst, FindLast, FindNext, FindPrevious" na ajuda do DAO.

CDaoRecordset::FindNext

Chame essa função de membro para localizar o próximo registro que corresponda a uma condição especificada.

BOOL FindNext(LPCTSTR lpszFilter);

Parâmetros

lpszFilter
Uma expressão de cadeia de caracteres (como a cláusula WHERE em uma instrução SQL sem a palavra WHERE) usada para localizar o registro.

Valor de retorno

Diferente de zero se forem encontrados registros correspondentes, caso contrário, será 0.

Comentários

A função de membro FindNext inicia sua pesquisa no registro atual e pesquisa até o final do conjunto de registros.

Se você quiser incluir todos os registros em sua pesquisa (não apenas aqueles que atendem a uma condição específica) use uma das operações Mover para mover de registro para registro. Para localizar um registro em um conjunto de registros do tipo tabela, chame a função de membro Seek.

Se um registro que corresponde aos critérios não for localizado, o ponteiro do registro atual será indeterminado e FindNext retornará zero. Se o conjunto de registros contiver mais de um registro que atenda aos critérios, FindFirst localiza a primeira ocorrência, FindNext localiza a próxima ocorrência e assim por diante.

Cuidado

Se você editar o registro atual, salve as alterações chamando a função de membro Update antes de migrar para outro registro. Se você mover para outro registro sem atualizar, suas alterações serão perdidas sem aviso.

No entanto, usar uma das operações Find não é o mesmo que chamar MoveFirst ou MoveNext, o que simplesmente torna o primeiro ou o próximo registro atual sem especificar uma condição. Você pode seguir uma operação Find com uma operação Move.

Esteja ciente das seguintes informações ao usar as operações Find:

  • Se Find retornar diferente de zero, o registro atual não será definido. Nesse caso, você deve posicionar o ponteiro de registro atual de volta para um registro válido.

  • Você não pode usar uma operação Find com um conjunto de registros do tipo instantâneo de rolagem somente para frente.

  • Você deve usar o formato de data dos EUA (mês-dia-ano) ao pesquisar campos que contenham datas, mesmo que não esteja usando a versão dos EUA do mecanismo de banco de dados do Microsoft Jet; caso contrário, os registros correspondentes podem não ser encontrados.

  • Ao trabalhar com bancos de dados ODBC e grandes dynasets, você pode descobrir que o uso das operações Find é lento, principalmente quando se trabalha com conjuntos de registros grandes. Você pode melhorar o desempenho usando consultas SQL com cláusulas ORDERBY ou WHERE personalizadas, consultas de parâmetro ou objetos CDaoQuerydef que recuperam registros indexados específicos.

Para obter informações relacionadas, consulte o tópico "Métodos FindFirst, FindLast, FindNext, FindPrevious" na ajuda do DAO.

CDaoRecordset::FindPrev

Chame essa função de membro para localizar o registro anterior que corresponda a uma condição especificada.

BOOL FindPrev(LPCTSTR lpszFilter);

Parâmetros

lpszFilter
Uma expressão de cadeia de caracteres (como a cláusula WHERE em uma instrução SQL sem a palavra WHERE) usada para localizar o registro.

Valor de retorno

Diferente de zero se forem encontrados registros correspondentes, caso contrário, será 0.

Comentários

A função de membro FindPrev inicia sua pesquisa no registro atual e pesquisa de trás para frente em direção ao início do conjunto de registros.

Se você quiser incluir todos os registros em sua pesquisa (não apenas aqueles que atendem a uma condição específica) use uma das operações Mover para mover de registro para registro. Para localizar um registro em um conjunto de registros do tipo tabela, chame a função de membro Seek.

Se um registro que corresponde aos critérios não for localizado, o ponteiro do registro atual será indeterminado e FindPrev retornará zero. Se o conjunto de registros contiver mais de um registro que atenda aos critérios, FindFirst localiza a primeira ocorrência, FindNext localiza a próxima ocorrência e assim por diante.

Cuidado

Se você editar o registro atual, salve as alterações chamando a função de membro Update antes de migrar para outro registro. Se você mover para outro registro sem atualizar, suas alterações serão perdidas sem aviso.

No entanto, usar uma das operações Find não é o mesmo que chamar MoveFirst ou MoveNext, o que simplesmente torna o primeiro ou o próximo registro atual sem especificar uma condição. Você pode seguir uma operação Find com uma operação Move.

Esteja ciente das seguintes informações ao usar as operações Find:

  • Se Find retornar diferente de zero, o registro atual não será definido. Nesse caso, você deve posicionar o ponteiro de registro atual de volta para um registro válido.

  • Você não pode usar uma operação Find com um conjunto de registros do tipo instantâneo de rolagem somente para frente.

  • Você deve usar o formato de data dos EUA (mês-dia-ano) ao pesquisar campos que contenham datas, mesmo que não esteja usando a versão dos EUA do mecanismo de banco de dados do Microsoft Jet; caso contrário, os registros correspondentes podem não ser encontrados.

  • Ao trabalhar com bancos de dados ODBC e grandes dynasets, você pode descobrir que o uso das operações Find é lento, principalmente quando se trabalha com conjuntos de registros grandes. Você pode melhorar o desempenho usando consultas SQL com cláusulas ORDERBY ou WHERE personalizadas, consultas de parâmetro ou objetos CDaoQuerydef que recuperam registros indexados específicos.

Para obter informações relacionadas, consulte o tópico "Métodos FindFirst, FindLast, FindNext, FindPrevious" na ajuda do DAO.

CDaoRecordset::GetAbsolutePosition

Retorna o número de registro do registro atual do objeto de um conjunto de registros.

long GetAbsolutePosition();

Valor de retorno

Um inteiro de 0 para o número de registros no conjunto de registros. Corresponde à posição ordinal do registro atual no conjunto de registros.

Comentários

O valor da propriedade AbsolutePosition do objeto DAO subjacente é baseado em zero; uma configuração 0 refere-se ao primeiro registro no conjunto de registros. Você pode determinar o número de registros preenchidos no conjunto de registros chamando GetRecordCount. Chamar GetRecordCount pode levar algum tempo porque deve acessar todos os registros para determinar a contagem.

Se não houver nenhum registro atual, como quando não há registros no conjunto de registros, - 1 será retornado. Se o registro atual for excluído, o valor da propriedade AbsolutePosition não será definido e o MFC gerará uma exceção se for referenciado. Para conjuntos de registros do tipo dynaset, novos registros são adicionados ao final da sequência.

Observação

Essa propriedade não se destina a ser usada como um número de registro substituto. Os indicadores ainda são a maneira recomendada de reter e retornar a uma determinada posição e são a única maneira de posicionar o registro atual em todos os tipos de objetos de conjunto de registros. Em particular, a posição de um determinado registro é alterada quando os registros anteriores são excluídos. Também não há garantia de que um determinado registro terá a mesma posição absoluta se o conjunto de registros for recriado novamente, pois a ordem dos registros individuais dentro de um conjunto de registros não é garantida, a menos que seja criada com uma instrução SQL usando uma cláusula ORDERBY .

Observação

Essa função de membro é válida somente para conjuntos de registros de tipo dynaset e de tipo de snapshot.

Para obter informações relacionadas, consulte o tópico "Propriedade AbsolutePosition" na ajuda do DAO.

CDaoRecordset::GetBookmark

Chame essa função de membro para obter o valor do indicador em um registro específico.

COleVariant GetBookmark();

Valor de retorno

Retorna um valor que representa o indicador no registro atual.

Comentários

Quando um objeto de conjunto de registros é criado ou aberto, cada um de seus registros já tem um indicador exclusivo se ele der suporte a eles. Chame CanBookmark para determinar se um conjunto de registros dá suporte a indicadores.

Você pode salvar o indicador do registro atual atribuindo o valor do indicador a um objeto COleVariant. Para retornar rapidamente a esse registro depois de mover para um registro diferente, chame SetBookmark com um parâmetro correspondente ao valor desse COleVariant objeto.

Observação

Chamar Requery altera os indicadores do DAO.

Para obter informações relacionadas, confira o tópico "Propriedade Bookmark" na ajuda do DAO.

CDaoRecordset::GetCacheSize

Chame essa função de membro para obter o número de registros armazenados em cache.

long GetCacheSize();

Valor de retorno

Um valor que especifica o número de registros em um conjunto de registros do tipo dynaset que contém dados a serem armazenados em cache localmente de uma fonte de dados ODBC.

Comentários

O cache de dados melhora o desempenho de um aplicativo que recupera dados de um servidor remoto por meio de objetos de conjunto de registros do tipo dynaset. Um cache é um espaço na memória local que contém os dados recuperados mais recentemente do servidor, caso os dados sejam solicitados novamente enquanto o aplicativo está em execução. Quando os dados são solicitados, o mecanismo de banco de dados do Microsoft Jet verifica primeiro o cache dos dados solicitados em vez de recuperá-los no servidor, o que leva mais tempo. Os dados que não vêm de uma fonte de dados ODBC não são salvos no cache.

Qualquer fonte de dados ODBC, como uma tabela anexada, pode ter um cache local.

Para obter informações relacionadas, consulte o tópico "CacheSize, Propriedades do CacheStart" na ajuda do DAO.

CDaoRecordset::GetCacheStart

Chame essa função de membro para obter o valor do indicador do primeiro registro no conjunto de registros a ser armazenado em cache.

COleVariant GetCacheStart();

Valor de retorno

Um COleVariant que especifica um valor que especifica o indicador do primeiro registro no conjunto de registros a ser armazenado em cache.

Comentários

O mecanismo de banco de dados do Microsoft Jet solicita registros dentro do intervalo de cache do cache e solicita registros fora do intervalo de cache do servidor.

Observação

Os registros recuperados do cache não refletem as alterações feitas simultaneamente nos dados de origem por outros usuários.

Para obter informações relacionadas, consulte o tópico "CacheSize, Propriedades do CacheStart" na ajuda do DAO.

CDaoRecordset::GetCurrentIndex

Chame essa função de membro para determinar o índice atualmente em uso em um objeto CDaoRecordset de tipo de tabela indexado.

CString GetCurrentIndex();

Valor de retorno

Um CString que contém o nome do índice atualmente em uso com um conjunto de registros do tipo tabela. Retorna uma cadeia de caracteres vazia se nenhum índice tiver sido definido.

Comentários

Esse índice é a base para ordenar registros em um conjunto de registros do tipo tabela e é usado pela função membro Seek para localizar registros.

Um objeto CDaoRecordset pode ter mais de um índice, mas pode usar apenas um índice por vez (embora um objeto CDaoTableDef possa ter vários índices definidos nele).

Para obter informações relacionadas, consulte o tópico "Índice de objeto" e a definição "Índice atual" na ajuda do DAO.

CDaoRecordset::GetDateCreated

Chame essa função de membro para recuperar a data e a hora em que uma tabela base foi criada.

COleDateTime GetDateCreated();

Valor de retorno

Um objeto COleDateTime que contém a data e a hora em que a tabela base foi criada.

Comentários

As configurações de data e hora são derivadas do computador no qual a tabela base foi criada.

Para obter informações relacionadas, confira o tópico "Propriedades DateCreated, LastUpdated" na ajuda do DAO.

CDaoRecordset::GetDateLastUpdated

Chame essa função de membro para recuperar a data e a hora em que o esquema foi atualizado pela última vez.

COleDateTime GetDateLastUpdated();

Valor de retorno

Um objeto COleDateTime que contém a data e a hora em que a estrutura da tabela base (esquema) foi atualizada pela última vez.

Comentários

As configurações de data e hora são derivadas do computador no qual a estrutura da tabela base (esquema) foi atualizada pela última vez.

Para obter informações relacionadas, confira o tópico "Propriedades DateCreated, LastUpdated" na ajuda do DAO.

CDaoRecordset::GetDefaultDBName

Chame essa função de membro para determinar o nome do banco de dados para este conjunto de registros.

virtual CString GetDefaultDBName();

Valor de retorno

Um CString que contém o caminho e o nome do banco de dados do qual esse conjunto de registros é derivado.

Comentários

Se um conjunto de registros for criado sem um ponteiro para um CDaoDatabase, esse caminho será usado pelo conjunto de registros para abrir o banco de dados padrão. Por padrão, essa função retorna uma cadeia de caracteres vazia. Quando ClassWizard deriva de um novo conjunto de registros de CDaoRecordset, ele criará essa função para você.

O exemplo a seguir ilustra o uso da barra invertida dupla (\\) na cadeia de caracteres, conforme necessário para que a cadeia de caracteres seja interpretada corretamente.

CString CCustSet::GetDefaultDBName()
{
   return _T("c:\\mydir\\datasrc.mdb");
}

CDaoRecordset::GetDefaultSQL

A estrutura chama essa função membro para obter a instrução SQL padrão na qual o conjunto de registros se baseia.

virtual CString GetDefaultSQL();

Valor de retorno

Um CString que contém a instrução SQL padrão.

Comentários

Pode ser um nome de tabela ou uma instrução SQL SELECT.

Você define indiretamente a instrução SQL padrão declarando sua classe de conjunto de registros com ClassWizard e ClassWizard executa essa tarefa para você.

Se você passar uma cadeia de caracteres SQL nula para Open, essa função será chamada para determinar o nome da tabela ou o SQL do conjunto de registros.

CDaoRecordset::GetEditMode

Chame essa função de membro para determinar o estado da edição, que é um dos seguintes valores:

short GetEditMode();

Valor de retorno

Retorna um valor que indica o estado da edição do registro atual.

Comentários

Valor Descrição
dbEditNone Nenhuma operação de bloqueio está em andamento.
dbEditInProgress O Edit foi chamado.
dbEditAdd O AddNew foi chamado.

Para obter informações relacionadas, confira o tópico "Propriedade EditMode" na ajuda do DAO.

CDaoRecordset::GetFieldCount

Chame essa função de membro para recuperar o número de campos (colunas) definidos no conjunto de registros.

short GetFieldCount();

Valor de retorno

O número de campos no conjunto de registros.

Comentários

Para obter informações relacionadas, confira o tópico "Propriedade Count" na ajuda do DAO.

CDaoRecordset::GetFieldInfo

Chame essa função de membro para obter informações sobre os campos em um conjunto de registros.

void GetFieldInfo(
    int nIndex,
    CDaoFieldInfo& fieldinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

void GetFieldInfo(
    LPCTSTR lpszName,
    CDaoFieldInfo& fieldinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

Parâmetros

nIndex
O índice baseado em zero do campo predefinido na coleção Fields do conjunto de registros, para pesquisa por índice.

fieldinfo
Uma referência a uma estrutura CDaoFieldInfo.

dwInfoOptions
Opções que especificam quais informações sobre o conjunto de registros a recuperar. As opções disponíveis estão listadas aqui junto com o que elas fazem com que a função retorne. Para obter o melhor desempenho, recupere apenas o nível de informações de que você precisa:

  • AFX_DAO_PRIMARY_INFO (Padrão) Nome, tipo, tamanho, atributos

  • AFX_DAO_SECONDARY_INFO Informações primárias, mais: posição ordinal, obrigatório, permitir comprimento zero, ordem de ordenação, nome estrangeiro, campo de origem, tabela de origem

  • AFX_DAO_ALL_INFO Informações primárias e secundárias, além de: Valor padrão, Regra de validação, Texto de validação

lpszName
O nome do campo.

Comentários

Uma versão da função permite pesquisar um campo por índice. A outra versão permite pesquisar um campo pelo nome.

Para obter uma descrição das informações retornadas, consulte a estrutura CDaoFieldInfo. Essa estrutura tem membros que correspondem aos itens de informações listados acima na descrição de dwInfoOptions. Quando você solicita informações em um nível, também obtém informações para qualquer nível anterior.

Para obter informações relacionadas, confira o tópico "Propriedade Attributes" na ajuda do DAO.

CDaoRecordset::GetFieldValue

Chame essa função de membro para recuperar dados em um conjunto de registros.

virtual void GetFieldValue(
    LPCTSTR lpszName,
    COleVariant& varValue);

virtual void GetFieldValue(
    int nIndex,
    COleVariant& varValue);

virtual COleVariant GetFieldValue(LPCTSTR lpszName);
virtual COleVariant GetFieldValue(int nIndex);

Parâmetros

lpszName
Um ponteiro para uma cadeia de caracteres que contém o nome de um campo.

varValue
Uma referência a um objeto COleVariant que armazenará o valor de um campo.

nIndex
Um índice baseado em zero do campo na coleção Fields do conjunto de registros, para pesquisa por índice.

Valor de retorno

As duas versões de GetFieldValue que retornam um valor retornam um objeto COleVariant que contém o valor de um campo.

Comentários

Você pode pesquisar um campo por nome ou por posição ordinal.

Observação

É mais eficiente chamar uma das versões dessa função membro que usa uma COleVariant referência de objeto como parâmetro, em vez de chamar uma versão que retorna um COleVariant objeto. As últimas versões dessa função são mantidas para compatibilidade com versões anteriores.

Use GetFieldValue e SetFieldValue para associar dinamicamente campos em tempo de execução em vez de associar colunas estaticamente usando o mecanismo DoFieldExchange.

GetFieldValue e o DoFieldExchange mecanismo pode ser combinado para melhorar o desempenho. Por exemplo, use GetFieldValue para recuperar um valor que você precisa apenas sob demanda e atribuir essa chamada a um botão "Mais Informações" na interface.

Para obter informações relacionadas, consulte os tópicos "Objeto Field" e "Propriedade Value" na ajuda do DAO.

CDaoRecordset::GetIndexCount

Chame essa função de membro para determinar o número de índices disponíveis no conjunto de registros do tipo tabela.

short GetIndexCount();

Valor de retorno

O número de índices no conjunto de registros do tipo tabela.

Comentários

GetIndexCount é útil para fazer loop em todos os índices no conjunto de registros. Para isso, use GetIndexCount com GetIndexInfo. Se você chamar essa função de membro em conjuntos de registros de tipo dynaset ou de snapshot, o MFC lançará uma exceção.

Para obter informações relacionadas, confira o tópico "Propriedade Attributes" na ajuda do DAO.

CDaoRecordset::GetIndexInfo

Chame essa função de membro para obter vários tipos de informações sobre um índice definido na tabela base subjacente a um conjunto de registros.

void GetIndexInfo(
    int nIndex,
    CDaoIndexInfo& indexinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

void GetIndexInfo(
    LPCTSTR lpszName,
    CDaoIndexInfo& indexinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

Parâmetros

nIndex
O índice baseado em zero na coleção Indexes da tabela, para pesquisa por posição numérica.

indexinfo
Uma referência a uma estrutura CDaoIndexInfo.

dwInfoOptions
Opções que especificam quais informações sobre o índice a recuperar. As opções disponíveis estão listadas aqui junto com o que elas fazem com que a função retorne. Para obter o melhor desempenho, recupere apenas o nível de informações de que você precisa:

  • AFX_DAO_PRIMARY_INFO (Padrão) Nome, Informações de Campo, Campos

  • AFX_DAO_SECONDARY_INFO Informações primárias, além disso: Primário, Exclusivo, Clusterizado, IgnoreNulls, Obrigatório, Estrangeiro

  • AFX_DAO_ALL_INFO Informações primárias e secundárias, além de: Contagem Distinta

lpszName
Um ponteiro para o nome do objeto de índice, para pesquisa por nome.

Comentários

Uma versão da função permite pesquisar um índice por sua posição na coleção. A outra versão permite pesquisar um índice pelo nome.

Para obter uma descrição das informações retornadas, consulte a estrutura CDaoIndexInfo. Essa estrutura tem membros que correspondem aos itens de informações listados acima na descrição de dwInfoOptions. Quando você solicita informações em um nível, também obtém informações para qualquer nível anterior.

Para obter informações relacionadas, confira o tópico "Propriedade Attributes" na ajuda do DAO.

CDaoRecordset::GetLastModifiedBookmark

Chame essa função de membro para recuperar o indicador do registro adicionado ou atualizado mais recentemente.

COleVariant GetLastModifiedBookmark();

Valor de retorno

Um COleVariant que contém um indicador que indica o registro adicionado ou alterado mais recentemente.

Comentários

Quando um objeto de conjunto de registros é criado ou aberto, cada um de seus registros já tem um indicador exclusivo se ele der suporte a eles. Chame GetBookmark para determinar se o conjunto de registros dá suporte a indicadores. Se o conjunto de registros não der suporte a indicadores, a CDaoException será gerado.

Quando você adiciona um registro, ele aparece no final do conjunto de registros e não é o registro atual. Para tornar o novo registro atual, chame GetLastModifiedBookmark e, depois, chame SetBookmark para retornar ao registro recém-adicionado.

Para obter informações relacionadas, confira o tópico "Propriedade LastModified" na ajuda do DAO.

CDaoRecordset::GetLockingMode

Chame essa função de membro para determinar o tipo de bloqueio em vigor para o conjunto de registros.

BOOL GetLockingMode();

Valor de retorno

Diferente de zero se o tipo de bloqueio for pessimista, caso contrário, será 0 para bloqueio de registro otimista.

Comentários

Quando o bloqueio pessimista está em vigor, a página de dados que contém o registro que você está editando é bloqueada assim que você chama a função de membro Editar . A página é desbloqueada quando você chama a função de membro Update ou Close ou qualquer uma das operações Move ou Find.

Quando o bloqueio otimista está em vigor, a página de dados que contém o registro é bloqueada somente enquanto o registro está sendo atualizado com a função de membro Update.

Ao trabalhar com fontes de dados ODBC, o modo de bloqueio é sempre otimista.

Para obter informações relacionadas, consulte os tópicos "Propriedade LockEdits" e "Comportamento de bloqueio em aplicativos multiusuários" na ajuda do DAO.

CDaoRecordset::GetName

Chame essa função de membro para recuperar o nome do conjunto de registros.

CString GetName();

Valor de retorno

Um CString que contém o nome do conjunto de registros.

Comentários

O nome do conjunto de registros deve começar com uma letra e pode conter no máximo 40 caracteres. Ele pode incluir números e caracteres de sublinhado, mas não pode incluir pontuação ou espaços.

Para obter informações relacionadas, confira o tópico "Propriedade Name" na ajuda do DAO.

CDaoRecordset::GetParamValue

Chame essa função de membro para recuperar o valor atual do parâmetro especificado armazenado no objeto DAOParameter subjacente.

virtual COleVariant GetParamValue(int nIndex);
virtual COleVariant GetParamValue(LPCTSTR lpszName);

Parâmetros

nIndex
A posição numérica do parâmetro no objeto DAOParameter subjacente.

lpszName
O nome do parâmetro cujo valor você deseja.

Valor de retorno

Um objeto da classe COleVariant que contém o valor do parâmetro.

Comentários

Você pode acessar o parâmetro por nome ou por sua posição numérica na coleção.

Para obter informações relacionadas, consulte o tópico "Objeto Parameter" na ajuda do DAO.

CDaoRecordset::GetPercentPosition

Ao trabalhar com um conjunto de registros do tipo dynaset ou de snapshot, se você chamar GetPercentPosition antes de preencher totalmente o conjunto de registros, a quantidade de movimentação será relativa ao número de registros acessados conforme indicado chamando GetRecordCount.

float GetPercentPosition();

Valor de retorno

Um número entre 0 e 100 que indica o local aproximado do registro atual no objeto recordset com base em uma porcentagem dos registros no conjunto de registros.

Comentários

Você pode passar para o último registro chamando MoveLast para concluir a população de todos os conjuntos de registros, mas isso pode levar um tempo significativo.

Você pode chamar GetPercentPosition todos os três tipos de objetos de conjunto de registros, incluindo tabelas sem índices. No entanto, você não pode chamar GetPercentPosition instantâneos de rolagem somente para frente ou em um conjunto de registros aberto a partir de uma consulta de passagem em um banco de dados externo. Se não houver nenhum registro atual ou se o registro atual tiver sido excluído, a CDaoException será gerado.

Para obter informações relacionadas, consulte o tópico "Propriedade PercentPosition" na ajuda do DAO.

CDaoRecordset::GetRecordCount

Chame essa função de membro para descobrir quantos registros em um conjunto de registros foram acessados.

long GetRecordCount();

Valor de retorno

Retorna o número de registros acessados em um objeto de conjunto de registros.

Comentários

GetRecordCount não indica quantos registros estão contidos em um conjunto de registros do tipo dynaset ou instantâneo até que todos os registros tenham sido acessados. Essa chamada de função de membro pode levar um tempo significativo para ser concluída.

Depois que o último registro tiver sido acessado, o valor retornado indicará o número total de registros não especificados no conjunto de registros. Para forçar o último registro a ser acessado, chame a função de membro MoveLast ou FindLast do conjunto de registros. Você também pode usar uma Contagem de SQL para determinar o número aproximado de registros que sua consulta retornará.

À medida que seu aplicativo exclui registros em um conjunto de registros do tipo dynaset, o valor retornado de GetRecordCount diminui. No entanto, os registros excluídos por outros usuários não são refletidos até GetRecordCount que o registro atual seja posicionado em um registro excluído. Se você executar uma transação que afete a contagem de registros e, posteriormente, reverta a transação, GetRecordCount não refletirá o número real de registros restantes.

O valor de GetRecordCount de um conjunto de registros do tipo instantâneo não é afetado por alterações nas tabelas subjacentes.

O valor de GetRecordCount de um conjunto de registros do tipo tabela reflete o número aproximado de registros na tabela e é afetado imediatamente à medida que os registros de tabela são adicionados e excluídos.

Um conjunto de registros sem registros retorna um valor de 0. Ao trabalhar com tabelas anexadas ou bancos de dados ODBC, GetRecordCount sempre retorna - 1. Chamar a função de membro Requery em um conjunto de registros redefine o valor de GetRecordCount exatamente como se a consulta fosse executada novamente.

Para obter informações relacionadas, confira o tópico "Propriedade RecordCount" na ajuda do DAO.

CDaoRecordset::GetSQL

Chame essa função de membro para obter a instrução SQL que foi usada para selecionar os registros do conjunto de registros quando ele foi aberto.

CString GetSQL() const;

Valor de retorno

Um CString que contém a instrução SQL.

Comentários

Geralmente, essa será uma instrução SELECT do SQL.

Normalmente, a cadeia de caracteres retornada por GetSQL é diferente de qualquer cadeia de caracteres que você possa ter passado para o conjunto de registros no parâmetro lpszSQL para a função de membro Open. Isso ocorre porque o conjunto de registros constrói um instrição SQL completa baseada no que você passou para Open, no que você especificou com ClassWizard e no que você especificou nos membros de dados m_strFilter e m_strSort.

Observação

Chame essa função de membro somente depois de chamar Open.

Para obter informações relacionadas, confira o tópico "Propriedade SQL" na ajuda do DAO.

CDaoRecordset::GetType

Chame essa função de membro depois de abrir o conjunto de registros para determinar o tipo do objeto do conjunto de registros.

short GetType();

Valor de retorno

Um dos seguintes valores que indica o tipo de um conjunto de registros:

  • dbOpenTable Conjunto de registros do tipo tabela

  • dbOpenDynaset Conjunto de registros do tipo dynaset

  • dbOpenSnapshot Conjunto de registros do tipo snapshot

Comentários

Para obter informações relacionadas, confira o tópico "Propriedade Type" na ajuda do DAO.

CDaoRecordset::GetValidationRule

Chame essa função de membro para determinar a regra usada para validar dados.

CString GetValidationRule();

Valor de retorno

Um CString objeto que contém um valor que valida os dados em um registro à medida que eles são alterados ou adicionados a uma tabela.

Comentários

Essa regra é baseada em texto e é aplicada sempre que a tabela subjacente é alterada. Se os dados não forem legais, o MFC gerará uma exceção. A mensagem de erro retornada é o texto da propriedade ValidationText do objeto de campo subjacente, se especificado, ou o texto da expressão especificado pela propriedade ValidationRule do objeto de campo subjacente. Você pode chamar GetValidationText para obter o texto da mensagem de erro.

Por exemplo, um campo em um registro que requer o dia do mês pode ter uma regra de validação, como "DIA ENTRE 1 E 31".

Para obter informações relacionadas, consulte o tópico "Propriedade ValidationRule" na ajuda do DAO.

CDaoRecordset::GetValidationText

Chame essa função de membro para recuperar o texto da propriedade ValidationText do objeto de campo subjacente.

CString GetValidationText();

Valor de retorno

Um CString objeto que contém o texto da mensagem que é exibida se o valor de um campo não atender à regra de validação do objeto de campo subjacente.

Comentários

Para obter informações relacionadas, consulte o tópico "Propriedade ValidationText" na ajuda do DAO.

CDaoRecordset::IsBOF

Chame essa função de membro antes de mover de registro para registro para saber se deslocou foi antes do primeiro registro do conjunto de registros.

BOOL IsBOF() const;

Valor de retorno

Diferente de zero se o conjunto de registros não contiver registros ou se você tiver se deslocado para trás antes do primeiro registro; caso contrário, será 0.

Comentários

Você também pode chamar IsBOF com IsEOF para determinar se o conjunto de registros contém registros ou se está vazio. Imediatamente após você chamar Open, se o conjunto de registros não contiver registros, IsBOF retornará diferente de zero. Quando você abre um conjunto de registros que tem pelo menos um registro, o primeiro registro é o registro atual e IsBOF retorna 0.

Se o primeiro registro for o registro atual e você chamar MovePrev, IsBOF retornará posteriormente diferente de zero. Se IsBOF retornar diferente de zero e você chamar MovePrev, uma exceção será gerada. Se IsBOF retornar diferente de zero, o registro atual será indefinido e qualquer ação que exija um registro atual resultará em uma exceção.

Efeito de métodos específicos em configurações IsBOF e IsEOF:

  • Chamar Open* internamente faz o primeiro registro no conjunto de registros do registro atual chamando MoveFirst. Portanto, chamar Open em um conjunto vazio de registros faz com que IsBOF e IsEOF retornem diferente de zero. (Consulte a tabela a seguir para obter o comportamento de uma chamada ou MoveFirst ou MoveLast com falha.)

  • Todas as operações Move que localizam com êxito um registro fazem com que IsBOF e IsEOF retornem 0.

  • Uma chamada AddNew seguida por uma chamada Update que insere com êxito um novo registro fará com que IsBOF retorne 0, mas somente se IsEOF já não for zero. O estado de IsEOF sempre permanecerá inalterado. Conforme definido pelo mecanismo de banco de dados do Microsoft Jet, o ponteiro de registro atual de um conjunto de registros vazio está no final de um arquivo, portanto, qualquer novo registro é inserido após o registro atual.

  • Qualquer Delete chamada, mesmo que remova o único registro restante de um conjunto de registros, não alterará o valor de IsBOF ou IsEOF.

Esta tabela mostra quais operações move são permitidas com combinações diferentes de IsBOF/ IsEOF.

Estado MoveFirst, MoveLast MovePrev,

Move < 0
Move 0 MoveNext,

Move > 0
IsBOF=nonzero,

IsEOF=0
Permitido Exceção Exceção Permitido
IsBOF=0,

IsEOF=nonzero
Permitido Permitido Exceção Exceção
Ambos diferentes de zero Exceção Exceção Exceção Exceção
Ambos 0 Permitido Permitido Permitido Permitido

Permitir uma operação Move não significa que a operação localizará um registro com êxito. Ele apenas indica que uma tentativa de executar a operação Move especificada é permitida e não gerará uma exceção. O valor das funções de membro IsBOF e IsEOF pode ser alterado como resultado da tentativa de movimentação.

O efeito das operações Move que não localizam um registro no valor e IsBOF IsEOF nas configurações é mostrado na tabela a seguir.

Operações IsBOF IsEOF
MoveFirst, MoveLast Diferentes de zero Diferentes de zero
Move 0 Nenhuma alteração Nenhuma alteração
MovePrev, Move< 0 Diferentes de zero Nenhuma alteração
MoveNext, Move> 0 Nenhuma alteração Diferentes de zero

Para obter informações relacionadas, confira o tópico "Propriedades BOF, EOF" na ajuda do DAO.

CDaoRecordset::IsDeleted

Chame essa função de membro para determinar se o registro atual foi excluído.

BOOL IsDeleted() const;

Valor de retorno

Diferente de zero se o conjunto de registros estiver posicionado em um registro excluído; caso contrário, será 0.

Comentários

Se você se deslocar para um registro e IsDeleted retornar TRUE (diferente de zero), você deverá mover para outro registro antes de executar qualquer outra operação de conjunto de registros.

Observação

Você não precisa verificar o status excluído para registros em um conjunto de registros do tipo snapshot ou de tabela. Como os registros não podem ser excluídos de um snapshot, não há necessidade de chamar IsDeleted. Para conjuntos de registros do tipo tabela, os registros excluídos são realmente removidos do conjunto de registros. Depois que um registro for excluído, seja por você, por outro usuário ou em outro conjunto de registros, você não poderá rolar de volta para esse registro. Portanto, não há necessidade de chamar IsDeleted.

Quando você exclui um registro de um dynaset, ele é removido do conjunto de registros e você não pode rolar de volta para esse registro. No entanto, se um registro em um dynaset for excluído por outro usuário ou em outro conjunto de registros com base na mesma tabela, IsDeleted retornará TRUE quando você rolar posteriormente para esse registro.

Para obter informações relacionadas, consulte os tópicos "Método Delete", "Propriedade LastModified" e "Propriedade EditMode" na ajuda do DAO.

CDaoRecordset::IsEOF

Chame essa função de membro quando você se deslocar de registro para registro para saber se você foi antes do último registro do conjunto de registros.

BOOL IsEOF() const;

Valor de retorno

Diferente de zero se o conjunto de registros não contiver registros ou se você tiver se deslocado para além do último registro; caso contrário, será 0.

Comentários

Você também pode chamar IsEOF para determinar se o conjunto de registros contém registros ou se está vazio. Imediatamente após você chamar Open, se o conjunto de registros não contiver registros, IsEOF retornará diferente de zero. Quando você abre um conjunto de registros que tem pelo menos um registro, o primeiro registro é o registro atual e IsEOF retorna 0.

Se o último registro for o registro atual e você chamar MoveNext, IsEOF retornará posteriormente diferente de zero. Se IsEOF retornar diferente de zero e você chamar MoveNext, uma exceção será gerada. Se IsEOF retornar diferente de zero, o registro atual será indefinido e qualquer ação que exija um registro atual resultará em uma exceção.

Efeito de métodos específicos em configurações IsBOF e IsEOF:

  • Chamar Open internamente faz o primeiro registro no conjunto de registros do registro atual chamando MoveFirst. Portanto, chamar Open em um conjunto vazio de registros faz com que IsBOF e IsEOF retornem diferente de zero. (Consulte a tabela a seguir para obter o comportamento de uma chamada ou uma chamada MoveFirst com falha.)

  • Todas as operações Move que localizam com êxito um registro fazem com que IsBOF e IsEOF retornem 0.

  • Uma chamada AddNew seguida por uma chamada Update que insere com êxito um novo registro fará com que IsBOF retorne 0, mas somente se IsEOF já não for zero. O estado de IsEOF sempre permanecerá inalterado. Conforme definido pelo mecanismo de banco de dados do Microsoft Jet, o ponteiro de registro atual de um conjunto de registros vazio está no final de um arquivo, portanto, qualquer novo registro é inserido após o registro atual.

  • Qualquer Delete chamada, mesmo que remova o único registro restante de um conjunto de registros, não alterará o valor de IsBOF ou IsEOF.

Esta tabela mostra quais operações move são permitidas com combinações diferentes de IsBOF/ IsEOF.

Estado MoveFirst, MoveLast MovePrev,

Move < 0
Move 0 MoveNext,

Move > 0
IsBOF=nonzero,

IsEOF=0
Permitido Exceção Exceção Permitido
IsBOF=0,

IsEOF=nonzero
Permitido Permitido Exceção Exceção
Ambos diferentes de zero Exceção Exceção Exceção Exceção
Ambos 0 Permitido Permitido Permitido Permitido

Permitir uma operação Move não significa que a operação localizará um registro com êxito. Ele apenas indica que uma tentativa de executar a operação Move especificada é permitida e não gerará uma exceção. O valor das funções de membro IsBOF e IsEOF pode ser alterado como resultado da tentativa de movimentação.

O efeito das operações Move que não localizam um registro no valor e IsBOF IsEOF nas configurações é mostrado na tabela a seguir.

Operações IsBOF IsEOF
MoveFirst, MoveLast Diferentes de zero Diferentes de zero
Move 0 Nenhuma alteração Nenhuma alteração
MovePrev, Move< 0 Diferentes de zero Nenhuma alteração
MoveNext, Move> 0 Nenhuma alteração Diferentes de zero

Para obter informações relacionadas, confira o tópico "Propriedades BOF, EOF" na ajuda do DAO.

CDaoRecordset::IsFieldDirty

Chame essa função de membro para determinar se o membro de dados de campo especificado de um dynaset foi sinalizado como "sujo" (alterado).

BOOL IsFieldDirty(void* pv);

Parâmetros

pv
Um ponteiro para o membro de dados de campo cujo status você deseja verificar ou NULL para determinar se algum dos campos está sujo.

Valor de retorno

Diferente de zero se o membro de dados de campo especificado estiver sinalizado como sujo; caso contrário, será 0.

Comentários

Os dados em todos os membros de dados de campo sujo são transferidos para o registro na fonte de dados quando o registro atual é atualizado por uma chamada para a Update função membro de CDaoRecordset (após uma chamada para Edit ou AddNew). Com esse conhecimento, você pode executar outras etapas, como dessinalizar o membro de dados do campo para marcar a coluna para que ela não seja gravada na fonte de dados.

IsFieldDirty é implementado por meio de DoFieldExchange.

CDaoRecordset::IsFieldNull

Chame essa função de membro para determinar se o membro de dados de campo especificado de um dynaset foi sinalizado como "sujo" (alterado).

BOOL IsFieldNull(void* pv);

Parâmetros

pv
Um ponteiro para o membro de dados de campo cujo status você deseja verificar ou NULL para determinar se algum dos campos é Null.

Valor de retorno

Diferente de zero se o membro de dados de campo especificado estiver sinalizado como Null; caso contrário, será 0.

Comentários

(Na terminologia de banco de dados, Null significa "não ter valor" e não é o mesmo que NULL em C++.) Se um membro de dados de campo for sinalizado como Nulo, ele será interpretado como uma coluna do registro atual para a qual não há valor.

Observação

Em determinadas situações, o uso IsFieldNull pode ser ineficiente, como ilustra o exemplo de código a seguir:

COleVariant varValue;
void *pField = &(rs.m_Age);
int nField = 2;

// this code is inefficient because data
// must be retrieved for both IsFieldNull
// and GetFieldValue
if (!rs.IsFieldNull(pField))
   rs.GetFieldValue(nField, varValue);

// this code is more efficient
rs.GetFieldValue(nField, varValue);
if (varValue.vt == VT_NULL)
   varValue.Attach(varNewVal); // do something

Observação

Se você estiver usando a associação dinâmica de registros, sem derivar de CDaoRecordset, certifique-se de usar VT_NULL conforme mostrado no exemplo.

CDaoRecordset::IsFieldNullable

Chame essa função de membro para determinar se o membro de dados de campo especificado é "anulável" (pode ser definido como um valor nulo; C++ NULL não é o mesmo que Null, que, na terminologia do banco de dados, significa "não ter valor").

BOOL IsFieldNullable(void* pv);

Parâmetros

pv
Um ponteiro para o membro de dados de campo cujo status você deseja verificar ou NULL para determinar se algum dos campos é Null.

Valor de retorno

Diferente de zero se o membro de dados de campo especificado puder ser definido como Null; caso contrário, será 0.

Comentários

Um campo que não pode ser Null deve ter um valor. Se você tentar definir esse campo como Null ao adicionar ou atualizar um registro, a fonte de dados rejeitará a adição ou atualização e Update lançará uma exceção. A exceção ocorre quando você chama Update, não quando você chama SetFieldNull.

CDaoRecordset::IsOpen

Chame essa função de membro para determinar se o conjunto de registros está aberto.

BOOL IsOpen() const;

Valor de retorno

Diferente de zero se a função do membro Open ou Requery do objeto do conjunto de registros tiver sido chamada anteriormente e o conjunto de registros não tiver sido fechado; caso contrário, será 0.

Comentários

CDaoRecordset::m_bCheckCacheForDirtyFields

Contém um sinalizador que indica se os campos armazenados em cache são marcados automaticamente como sujos (alterados) e Null.

Comentários

O sinalizador é TRUE por padrão. A configuração nesse membro de dados controla todo o mecanismo de buffer duplo. Se você definir o sinalizador como TRUE, poderá desativar o cache em uma base campo a campo usando o mecanismo DFX. Se você definir o sinalizador como FALSE, precisa chamar SetFieldDirty e SetFieldNull.

Defina esse membro de dados antes de chamar Open. Esse mecanismo é principalmente para facilitar o uso. O desempenho pode ser mais lento devido ao buffer duplo de campos à medida que as alterações são feitas.

CDaoRecordset::m_nFields

Contém o número de membros de dados de campo na classe de conjunto de registros e o número de colunas selecionadas pelo conjunto de registros da fonte de dados.

Comentários

O construtor da classe conjunto de registros deve inicializar m_nFields com o número correto de campos associados estaticamente. O ClassWizard grava essa inicialização para você ao usá-la para declarar sua classe de conjunto de registros. Você também pode gravá-lo manualmente.

A estrutura usa esse número para gerenciar a interação entre os membros dos dados de campo e as colunas correspondentes do registro atual na fonte de dados.

Observação

Esse número deve corresponder ao número de colunas de saída registradas DoFieldExchange após uma chamada para SetFieldType com o parâmetro CDaoFieldExchange::outputColumn.

Você pode associar colunas dinamicamente por meio de CDaoRecordset::GetFieldValue e CDaoRecordset::SetFieldValue. Se você fizer isso, não precisará incrementar a contagem para m_nFields refletir o número de chamadas de função DFX em sua DoFieldExchange função membro.

CDaoRecordset::m_nParams

Contém o número de membros de dados de parâmetro na classe de conjunto de registros, o número de parâmetros passados com a consulta do conjunto de registros.

Comentários

Se a classe do conjunto de registros tiver membros de dados de parâmetro, o construtor da classe deverá inicializar m_nParams com o número correto. O valor de m_nParams é 0 por padrão. Se você adicionar membros de dados de parâmetro, o que você deve fazer manualmente, também deve adicionar manualmente uma inicialização no construtor de classe para refletir o número de parâmetros (que devem ser pelo menos tão grandes quanto o número de espaços reservados '' em sua cadeia de caracteres m_strFilter ou m_strSort).

A estrutura usa esse número quando parametriza a consulta do conjunto de registros.

Observação

Esse número deve corresponder ao número de "params" registradas em DoFieldExchange após uma chamada para SetFieldType com o parâmetro CFieldExchange::param.

Para obter informações relacionadas, consulte o tópico "Objeto Parameter" na ajuda do DAO.

CDaoRecordset::m_pDAORecordset

Contém um ponteiro para a interface OLE para o objeto de conjunto de registros DAO subjacente ao objeto CDaoRecordset.

Comentários

Use este ponteiro se precisar acessar a interface do DAO diretamente.

Para obter informações relacionadas, consulte o tópico "Conjunto de registros" na ajuda do DAO.

CDaoRecordset::m_pDatabase

Contém um ponteiro para o objeto CDaoDatabase por meio do qual o conjunto de registros está conectado a uma fonte de dados.

Comentários

Essa variável é definida de duas maneiras. Normalmente, você passa um ponteiro para um objeto CDaoDatabase já aberto ao construir o objeto do conjunto de registros. Se você passar NULL em vez disso, CDaoRecordset cria um objeto CDaoDatabase para você e o abre. Em ambos os casos, CDaoRecordset armazena o ponteiro nessa variável.

Normalmente, você não precisará usar diretamente o ponteiro armazenado no m_pDatabase. No entanto, se você escrever suas próprias extensões para CDaoRecordset, talvez seja necessário usar o ponteiro. Por exemplo, talvez você precise do ponteiro se lançar seu(s) próprio(s) CDaoException(s).

Para obter informações relacionadas, consulte o tópico "Objeto Database" na ajuda do DAO.

CDaoRecordset::m_strFilter

Contém uma cadeia de caracteres usada para construir a cláusula WHERE de uma instrução SQL.

Comentários

Ele não inclui a palavra reservada WHERE para filtrar o conjunto de registros. O uso desse membro de dados não é aplicável a conjuntos de registros do tipo tabela. O uso de m_strFilter não tem efeito ao abrir um conjunto de registros usando um ponteiro CDaoQueryDef.

Use o formato de data dos EUA (mês-dia-ano) ao filtrar campos que contêm datas, mesmo que não esteja usando a versão dos EUA do mecanismo de banco de dados do Microsoft Jet; caso contrário, os dados podem não ser filtrados conforme o esperado.

Para obter informações relacionadas, confira o tópico "Propriedade Filter" na ajuda do DAO.

CDaoRecordset::m_strSort

Contém uma cadeia de caracteres que contém a cláusula ORDERBY de uma instrução SQL sem as palavras reservadas ORDERBY.

Comentários

Você pode classificar objetos de conjunto de registros de tipo dynaset e snapshot.

Você não pode classificar objetos de conjunto de registros do tipo tabela. Para determinar a ordem de classificação de um conjunto de registros do tipo tabela, chame SetCurrentIndex.

O uso de m_strSort não tem efeito ao abrir um conjunto de registros usando um ponteiro CDaoQueryDef.

Para obter informações relacionadas, confira o tópico "Propriedade Sort" na ajuda do DAO.

CDaoRecordset::Move

Chame essa função de membro para posicionar os registros lRows do conjunto de registros do registro atual.

virtual void Move(long lRows);

Parâmetros

lRows
O número de registros a serem movidos para frente ou para trás. Os valores positivos avançam até o final do conjunto de registros. Valores negativos se movem para trás, em direção ao início.

Comentários

Você pode mover para frente ou para trás. Move( 1 ) é equivalente a MoveNext e Move( -1 ) é equivalente a MovePrev.

Cuidado

Chamar qualquer uma das funções Move gera uma exceção se o conjunto de registros não tiver registros. Em geral, chame ambos IsBOF e IsEOF antes de uma operação de movimentação para determinar se o conjunto de registros tem registros. Depois de chamar Open ou Requery, chame IsBOF ou IsEOF.

Observação

Se você tiver se deslocado para além do início ou final do conjunto de registros (IsBOF ou IsEOF retorna diferente de zero), uma chamada para Move gera um CDaoException.

Observação

Se você chamar qualquer uma das funções Move enquanto o registro atual estiver sendo atualizado ou adicionado, as atualizações serão perdidas sem aviso.

Quando você chama Move um instantâneo de rolagem somente para frente, o parâmetro lRows deve ser um número inteiro positivo e os indicadores não são permitidos, para que você possa avançar apenas.

Para fazer o primeiro, o último, o próximo ou o registro anterior em um conjunto de registros do registro atual, chame a função de membro MoveFirst, MoveLast, MoveNext ou MovePrev.

Para obter informações relacionadas, consulte os tópicos "Método Move" e "Método MoveFirst, MoveLast, MoveNext, MovePrevious" na ajuda do DAO.

CDaoRecordset::MoveFirst

Chame essa função de membro para fazer o primeiro registro no conjunto de registros (se houver) o registro atual.

void MoveFirst();

Comentários

Você não precisa chamar MoveFirst imediatamente depois de abrir o conjunto de registros. Nesse momento, o primeiro registro (se houver) é automaticamente o registro atual.

Cuidado

Chamar qualquer uma das funções Move gera uma exceção se o conjunto de registros não tiver registros. Em geral, chame ambos IsBOF e IsEOF antes de uma operação de movimentação para determinar se o conjunto de registros tem registros. Depois de chamar Open ou Requery, chame IsBOF ou IsEOF.

Observação

Se você chamar qualquer uma das funções Move enquanto o registro atual estiver sendo atualizado ou adicionado, as atualizações serão perdidas sem aviso.

Use as funções Move para mover de registro para registro sem aplicar uma condição. Use as operações Find para localizar registros em um objeto de conjunto de registros do tipo dynaset ou do tipo snapshot que satisfaça uma determinada condição. Para localizar um registro em um objeto de conjunto de registros do tipo tabela, chame Seek.

Se o conjunto de registros se referir a um conjunto de registros do tipo tabela, o movimento seguirá o índice atual da tabela. Você pode definir o índice atual usando a propriedade Index do objeto DAO subjacente. Se você não definir o índice atual, a ordem dos registros retornados será indefinida.

Se você chamar MoveLast em um objeto de conjunto de registros com base em uma query ou querydef do SQL, a consulta será forçada à conclusão e o objeto do conjunto de registros será totalmente preenchido.

Você não pode chamar a MoveFirst função de membro or MovePrev com um instantâneo de rolagem somente para frente.

Para mover a posição do registro atual em um objeto de conjunto de registros, um número específico de registros para frente ou para trás, chame Move.

Para obter informações relacionadas, consulte os tópicos "Método Move" e "Método MoveFirst, MoveLast, MoveNext, MovePrevious" na ajuda do DAO.

CDaoRecordset::MoveLast

Chame essa função de membro para tornar o último registro (se houver) no conjunto de registros o registro atual.

void MoveLast();

Comentários

Cuidado

Chamar qualquer uma das funções Move gera uma exceção se o conjunto de registros não tiver registros. Em geral, chame ambos IsBOF e IsEOF antes de uma operação de movimentação para determinar se o conjunto de registros tem registros. Depois de chamar Open ou Requery, chame IsBOF ou IsEOF.

Observação

Se você chamar qualquer uma das funções Move enquanto o registro atual estiver sendo atualizado ou adicionado, as atualizações serão perdidas sem aviso.

Use as funções Move para mover de registro para registro sem aplicar uma condição. Use as operações Find para localizar registros em um objeto de conjunto de registros do tipo dynaset ou do tipo snapshot que satisfaça uma determinada condição. Para localizar um registro em um objeto de conjunto de registros do tipo tabela, chame Seek.

Se o conjunto de registros se referir a um conjunto de registros do tipo tabela, o movimento seguirá o índice atual da tabela. Você pode definir o índice atual usando a propriedade Index do objeto DAO subjacente. Se você não definir o índice atual, a ordem dos registros retornados será indefinida.

Se você chamar MoveLast em um objeto de conjunto de registros com base em uma query ou querydef do SQL, a consulta será forçada à conclusão e o objeto do conjunto de registros será totalmente preenchido.

Para mover a posição do registro atual em um objeto de conjunto de registros, um número específico de registros para frente ou para trás, chame Move.

Para obter informações relacionadas, consulte os tópicos "Método Move" e "Método MoveFirst, MoveLast, MoveNext, MovePrevious" na ajuda do DAO.

CDaoRecordset::MoveNext

Chame essa função de membro para tornar o próximo registro no conjunto de registros o registro atual.

void MoveNext();

Comentários

É recomendável que você ligue IsBOF antes de tentar mover para o registro anterior. Uma chamada para MovePrev lançar um CDaoException if IsBOF retorna diferente de zero, indicando que você já rolou antes do primeiro registro ou que nenhum registro foi selecionado pelo conjunto de registros.

Cuidado

Chamar qualquer uma das funções Move gera uma exceção se o conjunto de registros não tiver registros. Em geral, chame ambos IsBOF e IsEOF antes de uma operação de movimentação para determinar se o conjunto de registros tem registros. Depois de chamar Open ou Requery, chame IsBOF ou IsEOF.

Observação

Se você chamar qualquer uma das funções Move enquanto o registro atual estiver sendo atualizado ou adicionado, as atualizações serão perdidas sem aviso.

Use as funções Move para mover de registro para registro sem aplicar uma condição. Use as operações Find para localizar registros em um objeto de conjunto de registros do tipo dynaset ou do tipo snapshot que satisfaça uma determinada condição. Para localizar um registro em um objeto de conjunto de registros do tipo tabela, chame Seek.

Se o conjunto de registros se referir a um conjunto de registros do tipo tabela, o movimento seguirá o índice atual da tabela. Você pode definir o índice atual usando a propriedade Index do objeto DAO subjacente. Se você não definir o índice atual, a ordem dos registros retornados será indefinida.

Para mover a posição do registro atual em um objeto de conjunto de registros, um número específico de registros para frente ou para trás, chame Move.

Para obter informações relacionadas, consulte os tópicos "Método Move" e "Método MoveFirst, MoveLast, MoveNext, MovePrevious" na ajuda do DAO.

CDaoRecordset::MovePrev

Chame essa função de membro para tornar o próximo registro no conjunto de registros o registro atual.

void MovePrev();

Comentários

É recomendável que você ligue IsBOF antes de tentar mover para o registro anterior. Uma chamada para MovePrev lançar um CDaoException if IsBOF retorna diferente de zero, indicando que você já rolou antes do primeiro registro ou que nenhum registro foi selecionado pelo conjunto de registros.

Cuidado

Chamar qualquer uma das funções Move gera uma exceção se o conjunto de registros não tiver registros. Em geral, chame ambos IsBOF e IsEOF antes de uma operação de movimentação para determinar se o conjunto de registros tem registros. Depois de chamar Open ou Requery, chame IsBOF ou IsEOF.

Observação

Se você chamar qualquer uma das funções Move enquanto o registro atual estiver sendo atualizado ou adicionado, as atualizações serão perdidas sem aviso.

Use as funções Move para mover de registro para registro sem aplicar uma condição. Use as operações Find para localizar registros em um objeto de conjunto de registros do tipo dynaset ou do tipo snapshot que satisfaça uma determinada condição. Para localizar um registro em um objeto de conjunto de registros do tipo tabela, chame Seek.

Se o conjunto de registros se referir a um conjunto de registros do tipo tabela, o movimento seguirá o índice atual da tabela. Você pode definir o índice atual usando a propriedade Index do objeto DAO subjacente. Se você não definir o índice atual, a ordem dos registros retornados será indefinida.

Você não pode chamar a MoveFirst função de membro or MovePrev com um instantâneo de rolagem somente para frente.

Para mover a posição do registro atual em um objeto de conjunto de registros, um número específico de registros para frente ou para trás, chame Move.

Para obter informações relacionadas, consulte os tópicos "Método Move" e "Método MoveFirst, MoveLast, MoveNext, MovePrevious" na ajuda do DAO.

CDaoRecordset::Open

Você deve chamar essa função de membro para recuperar os registros do conjunto de registros.

virtual void Open(
    int nOpenType = AFX_DAO_USE_DEFAULT_TYPE,
    LPCTSTR lpszSQL = NULL,
    int nOptions = 0);

virtual void Open(
    CDaoTableDef* pTableDef,
    int nOpenType = dbOpenTable,
    int nOptions = 0);

virtual void Open(
    CDaoQueryDef* pQueryDef,
    int nOpenType = dbOpenDynaset,
    int nOptions = 0);

Parâmetros

nOpenType
Um dos seguintes valores:

  • dbOpenDynaset Um conjunto de registros do tipo Dynaset com deslocamento bidirecional. Esse é o padrão.

  • dbOpenTable Um conjunto de registros do tipo tabela com deslocamento bidirecional.

  • dbOpenSnapshot Um conjunto de registros do tipo snapshot com deslocamento bidirecional.

lpszSQL
Um ponteiro de cadeia de caracteres que contém um dos seguintes:

  • Um ponteiro NULL.

  • O nome de um ou mais tabledefs e/ou querydefs (separados por vírgulas).

  • Uma instrução SQL SELECT (opcionalmente com uma cláusula SQL WHERE ou ORDERBY).

  • Um consulta de passagem.

nOptions
Uma ou mais das opções listadas abaixo. O valor padrão é 0. Os valores possíveis são:

  • dbAppendOnly Você só pode acrescentar novos registros (somente conjunto de registros do tipo dynaset). Essa opção significa literalmente que os registros só podem ser acrescentados. As classes de banco de dados ODBC do MFC têm uma opção somente acréscimo que permite que os registros sejam recuperados e acrescentados.

  • dbForwardOnly O conjunto de registros é um instantâneo de rolagem somente para frente.

  • dbSeeChanges Gere uma exceção se outro usuário estiver alterando os dados que você está editando.

  • dbDenyWrite Outros usuários não podem modificar ou adicionar registros.

  • dbDenyRead Outros usuários não podem exibir registros (somente conjunto de registros do tipo tabela).

  • dbReadOnly Você só pode exibir registros; outros usuários podem modificá-los.

  • dbInconsistent Atualizações inconsistentes são permitidas (somente conjunto de registros do tipo dynaset).

  • dbConsistent Somente atualizações inconsistentes são permitidas (somente conjunto de registros do tipo dynaset).

Observação

As constantes dbConsistent e dbInconsistent são mutuamente exclusivas. Você pode usar um ou outro, mas não ambos em uma determinada instância de Open.

pTableDef
Um ponteiro para um objeto CDaoTableDef. Essa versão é válida somente para conjuntos de registros do tipo tabela. Ao usar essa opção, o CDaoDatabase ponteiro usado para construir o CDaoRecordset não é usado; em vez disso, o banco de dados no qual o tabledef reside é usado.

pQueryDef
Um ponteiro para um objeto CDaoQueryDef. Essa versão é válida somente para conjuntos de registros de tipo dynaset e de tipo de snapshot. Ao usar essa opção, o CDaoDatabase ponteiro usado para construir o CDaoRecordset não é usado; em vez disso, o banco de dados no qual o querydef reside é usado.

Comentários

Antes de chamar Open, você deve construir o objeto do conjunto de registros. Há várias maneiras de fazer isso:

  • Ao construir o objeto do conjunto de registros, passe um ponteiro para um objeto CDaoDatabase que já está aberto.

  • Ao construir o objeto recordset, passe um ponteiro para um CDaoDatabase objeto que não está aberto. O conjunto de registros abre um objeto CDaoDatabase, mas não o fechará quando o objeto do conjunto de registros for fechado.

  • Ao construir o objeto do conjunto de registros, passe um ponteiro NULL. O objeto do conjunto de registros chama GetDefaultDBName para obter o nome do Microsoft Access. Arquivo MDB a ser aberto. O conjunto de registros então abre um objeto CDaoDatabase e o mantém aberto enquanto o conjunto de registros estiver aberto. Quando você chama Close no conjunto de registros, o objeto CDaoDatabase também é fechado.

    Observação

    Quando o conjunto de registros abre o objeto CDaoDatabase, ele abre a fonte de dados com acesso não exclusivo.

Para a versão de Open que usa o parâmetro lpszSQL, depois que o conjunto de registros estiver aberto, você poderá recuperar registros de várias maneiras. A primeira opção é ter funções DFX em seu DoFieldExchange. A segunda opção é usar a associação dinâmica chamando a função de membro GetFieldValue. Essas opções podem ser implementadas separadamente ou em combinação. Se eles forem combinados, você terá que passar a instrução SQL por conta própria na chamada para Open.

Quando você usa a segunda versão de Open onde você passa um CDaoTableDef objeto, as colunas resultantes estão disponíveis para você associar via DoFieldExchange e o mecanismo DFX e/ou associar dinamicamente via GetFieldValue.

Observação

Você só pode chamar Open usando um objeto CDaoTableDef para conjuntos de registros do tipo tabela.

Quando você usa a terceira versão de Open onde você passa um CDaoQueryDef objeto, essa consulta é executada e as colunas resultantes estão disponíveis para você associar via DoFieldExchange e o mecanismo DFX e/ou associar dinamicamente via GetFieldValue.

Observação

Você só pode chamar Open usando um objeto CDaoQueryDef para conjuntos de registros do tipo dynaset e do tipo snapshot.

Para a primeira versão de Open que usa o parâmetro lpszSQL, os registros são selecionados com base nos critérios mostrados na tabela a seguir.

Valor do parâmetro lpszSQL Os registros selecionados são determinados por Exemplo
NULO Cadeia de caracteres retornada por GetDefaultSQL.
Uma lista separada por vírgulas de um ou mais nomes tabledefs e/ou querydef. Todas as colunas representadas no DoFieldExchange. "Customer"
Lista de colunas SELECT da lista de tabela FROM As colunas especificadas do(s) tabledef(s) e/ou querydef(s) especificado(s). "SELECT CustId, CustName

FROM Customer"

O procedimento usual é passar NULL para Open; nesse caso, Open chama GetDefaultSQL, uma função membro substituível que o ClassWizard gera ao criar uma classe derivada CDaoRecordset. Esse valor fornece o(s) nome(s) tabledef(s) e/ou querydef(s) que você especificou no ClassWizard. Em vez disso, você pode especificar outras informações no parâmetro lpszSQL.

Independentemente do que você passar, Open constrói uma cadeia de caracteres SQL final para a consulta (a cadeia de caracteres pode ter cláusulas SQL WHERE e ORDERBY acrescentadas à cadeia de caracteres lpszSQL que você passou) e, em seguida, executa a consulta. Você pode examinar a cadeia de caracteres construída chamando GetSQL depois de chamar Open.

Os membros de dados de campo da classe de conjunto de registros são associados às colunas dos dados selecionados. Se algum registro for retornado, o primeiro registro se tornará o registro atual.

Se você quiser definir opções para o conjunto de registros, como um filtro ou uma classificação, defina m_strSort ou m_strFilter depois de construir o objeto do conjunto de registros, mas antes de chamar Open. Se você quiser atualizar os registros no conjunto de registros depois que o conjunto de registros já estiver aberto, chame Requery.

Se você chamar Open um conjunto de registros do tipo dynaset ou do tipo instantâneo, ou se a fonte de dados se referir a uma instrução SQL ou a um tabledef que representa uma tabela anexada, não será possível usar dbOpenTable o argumento de tipo; se o fizer, o MFC gerará uma exceção. Para determinar se um objeto tabledef representa uma tabela anexada, crie um objeto CDaoTableDef e chame sua função de membro GetConnect.

Use o dbSeeChanges sinalizador se quiser interceptar as alterações feitas por outro usuário ou outro programa em sua máquina quando estiver editando ou excluindo o mesmo registro. Por exemplo, se dois usuários começarem a editar o mesmo registro, o primeiro usuário a chamar a função de membro Update terá êxito. Quando Update é chamado pelo segundo usuário, um CDaoException é gerado. Da mesma forma, se o segundo usuário tentar chamar Delete para excluir o registro e ele já tiver sido alterado pelo primeiro usuário, ocorrerá um CDaoException.

Normalmente, se o usuário receber esse CDaoException durante a atualização, seu código deverá atualizar o conteúdo dos campos e recuperar os valores recém-modificados. Se a exceção ocorrer no processo de exclusão, seu código poderá exibir os novos dados de registro para o usuário e uma mensagem indicando que os dados foram alterados recentemente. Neste ponto, seu código pode solicitar uma confirmação de que o usuário ainda deseja excluir o registro.

Dica

Use a opção de deslocamento somente para frente (dbForwardOnly) para melhorar o desempenho quando seu aplicativo fizer uma única passagem por um conjunto de registros aberto de uma fonte de dados ODBC.

Para obter informações relacionadas, consulte o tópico "Método OpenRecordset" na ajuda do DAO.

CDaoRecordset::Requery

Chame essa função de membro para recompilar (atualizar) um conjunto de registros.

virtual void Requery();

Comentários

Se algum registro for retornado, o primeiro registro se tornará o registro atual.

Para que o conjunto de registros reflita as adições e exclusões que você ou outros usuários estão fazendo à fonte de dados, você deve recompilar o conjunto de registros chamando Requery. Se o conjunto de registros for um dynaset, ele refletirá automaticamente as atualizações que você ou outros usuários fazem em seus registros existentes (mas não adições). Se o conjunto de registros for um instantâneo, você deverá chamar Requery para refletir edições de outros usuários, bem como adições e exclusões.

Para um dynaset ou um instantâneo, chame Requery quando quiser recompilar o conjunto de registros usando valores de parâmetro. Defina o novo filtro ou classifique definindo m_strFilter e m_strSort antes de chamar Requery. Defina novos parâmetros atribuindo novos valores a membros de dados de parâmetro antes de chamar Requery.

Se a tentativa de recompilar o conjunto de registros falhar, o conjunto de registros será fechado. Antes de chamar Requery, você pode determinar se o conjunto de registros pode ser requerido chamando a função de membro CanRestart. CanRestart não garante que Requery terá êxito.

Cuidado

Chame Requery somente depois que você tiver chamado Open.

Observação

Chamar Requery os favoritos do DAO de alterações.

Você não pode chamar Requery em um conjunto de registros do tipo dynaset ou do tipo snapshot se a chamada de CanRestart retornar 0, nem pode usá-lo em um conjunto de registros do tipo tabela.

Se IsBOF e IsEOF retornarem diferente de zero depois de você chamar Requery, a consulta não retornará nenhum registro e o conjunto de registros não conterá dados.

Para obter informações relacionadas, consulte o tópico "Método Requery" na ajuda do DAO.

CDaoRecordset::Seek

Chame essa função de membro para localizar o registro em um objeto de conjunto de registros do tipo tabela indexado que atende aos critérios especificados para o índice atual e transforma esse registro no registro atual.

BOOL Seek(
    LPCTSTR lpszComparison,
    COleVariant* pKey1,
    COleVariant* pKey2 = NULL,
    COleVariant* pKey3 = NULL);

BOOL Seek(
    LPCTSTR lpszComparison,
    COleVariant* pKeyArray,
    WORD nKeys);

Parâmetros

lpszComparison
Uma das seguintes expressões de cadeia de caracteres: "<", "<=", "=", ">=" ou ">".

pKey1
Um ponteiro para um COleVariant cujo valor corresponde ao primeiro campo no índice. Obrigatória.

pKey2
Um ponteiro para um COleVariant cujo valor corresponde ao segundo campo no índice, se houver. Assume o padrão de NULL.

pKey3
Um ponteiro para um COleVariant cujo valor corresponde ao terceiro campo no índice, se houver. Assume o padrão de NULL.

pKeyArray
Um ponteiro para uma matriz de variantes. O tamanho da matriz corresponde ao número de campos no índice.

nKeys
Um inteiro correspondente ao tamanho da matriz, que é o número de campos no índice.

Observação

on't especifique curingas nas chaves. Curingas farão com que Seek retorne registros correspondentes.

Valor de retorno

Diferente de zero se forem encontrados registros correspondentes, caso contrário, será 0.

Comentários

Use a segunda versão de Seek (matriz) para lidar com índices de quatro campos ou mais.

Seek habilita a pesquisa de índice de alto desempenho em conjuntos de registros do tipo tabela. Você deve definir o índice atual chamando SetCurrentIndex antes de chamar Seek. Se o índice identificar um campo de chave não exclusivo ou campos, Seek localize o primeiro registro que atenda aos critérios. Se você não definir um índice, uma exceção será lançada.

Se você não estiver criando um conjunto de registros UNICODE, os objetos deverão ser declarados COleVariant explicitamente ANSI. Isso pode ser feito usando a forma COleVariant::COleVariant( lpszSrc , vtSrc ) do construtor com vtSrc definido como VT_BSTRT (ANSI) ou usando a COleVariant função SetString( lpszSrc , vtSrc ) com vtSrc definido como .VT_BSTRT

Ao chamar Seek, você passa um ou mais valores de chave e um operador de comparação ("<", "<=", "=", ">=" ou ">"). Seek pesquisa pelos campos de chave especificados e localiza o primeiro registro que atende aos critérios especificados por lpszComparison e pKey1. Depois de encontrado, Seek retorna diferente de zero e torna esse registro atual. Se Seek não conseguir localizar uma correspondência, Seek retornará zero e o registro atual será indefinido. Ao usar o DAO diretamente, você deve verificar explicitamente a propriedade NoMatch.

Se lpszComparison for "=", ">=" ou ">", Seek começará no início do índice. Se lpszComparison for "<" ou "<=", Seek começará no final do índice e pesquisará para trás, a menos que haja entradas de índice duplicadas no final. Nesse caso, Seek começa em uma entrada arbitrária entre as entradas de índice duplicadas no final do índice.

Não precisa haver um registro atual quando você usa Seeko .

Para localizar um registro em um conjunto de registros do tipo dynaset ou do tipo instantâneo que satisfaça uma condição específica, use as operações Localizar. Para incluir todos os registros, não apenas aqueles que satisfazem uma condição específica, use as operações Mover para mover de registro para registro.

Você não pode chamar Seek uma tabela anexada de qualquer tipo porque as tabelas anexadas devem ser abertas como conjuntos de registros do tipo dynaset ou instantâneo. No entanto, se você chamar CDaoDatabase::Open para abrir diretamente um banco de dados ISAM instalável, poderá chamar Seek em tabelas nesse banco de dados, embora o desempenho possa ser lento.

Para obter informações relacionadas, consulte o tópico "Método Seek" na ajuda do DAO.

CDaoRecordset::SetAbsolutePosition

Define o número de registro relativo do registro atual do objeto de um conjunto de registros.

void SetAbsolutePosition(long lPosition);

Parâmetros

lPosition
Corresponde à posição ordinal do registro atual no conjunto de registros.

Comentários

Chamar SetAbsolutePosition permite que você posicione o ponteiro de registro atual para um registro específico com base em sua posição ordinal em um conjunto de registros do tipo dynaset ou do tipo snapshot. Você também pode determinar o número do registro atual chamando GetAbsolutePosition.

Observação

Essa função de membro é válida somente para conjuntos de registros de tipo dynaset e de tipo de snapshot.

O valor da propriedade AbsolutePosition do objeto DAO subjacente é baseado em zero; uma configuração 0 refere-se ao primeiro registro no conjunto de registros. Definir um valor maior que o número de registros preenchidos faz com que o MFC gere uma exceção. Você pode determinar o número de registros preenchidos no conjunto de registros chamando a função de membro GetRecordCount.

Se o registro atual for excluído, o valor da propriedade AbsolutePosition não será definido e o MFC gerará uma exceção se for referenciado. Novos registros são adicionados ao final da sequência.

Observação

Essa propriedade não se destina a ser usada como um número de registro substituto. Os indicadores ainda são a maneira recomendada de reter e retornar a uma determinada posição e são a única maneira de posicionar o registro atual em todos os tipos de objetos de conjunto de registros que dá suporte a indicadores. Em particular, a posição de um determinado registro é alterada quando os registros anteriores são excluídos. Também não há garantia de que um determinado registro terá a mesma posição absoluta se o conjunto de registros for recriado novamente, pois a ordem dos registros individuais dentro de um conjunto de registros não é garantida, a menos que seja criada com uma instrução SQL usando uma cláusula ORDERBY .

Para obter informações relacionadas, consulte o tópico "Propriedade AbsolutePosition" na ajuda do DAO.

CDaoRecordset::SetBookmark

Chame essa função de membro para posicionar o conjunto de registros no registro que contém o indicador especificado.

void SetBookmark(COleVariant varBookmark);

Parâmetros

varBookmark
Um objeto COleVariant que contém o valor do indicador para um registro específico.

Comentários

Quando um objeto de conjunto de registros é criado ou aberto, cada um de seus registros já tem um indicador. Você pode recuperar o indicador do registro atual chamando GetBookmark e salvando o valor em um objeto COleVariant. Posteriormente, você pode retornar a esse registro chamando SetBookmark usando o valor do indicador salvo.

Observação

Chamar Requery altera os indicadores do DAO.

Se você não estiver criando um conjunto de registros UNICODE, o objeto deverá ser declarado COleVariant explicitamente ANSI. Isso pode ser feito usando a forma COleVariant::COleVariant( lpszSrc , vtSrc ) do construtor com vtSrc definido como VT_BSTRT (ANSI) ou usando a COleVariant função SetString( lpszSrc , vtSrc ) com vtSrc definido como .VT_BSTRT

Para obter informações relacionadas, consulte os tópicos "Propriedade Bookmark" e "Propriedade Bookmarkable" na ajuda do DAO.

CDaoRecordset::SetCacheSize

Chame essa função de membro para definir o número de registros que serão armazenados em cache.

void SetCacheSize(long lSize);

Parâmetros

lSize
Especifica o número de registros. Um valor típico é 100. Um configuração de 0 desativa o armazenamento em cache. A configuração deve estar entre 5 e 1.200 registros. O cache pode usar uma quantidade considerável de memória.

Comentários

Um cache é um espaço na memória local que contém os dados recuperados mais recentemente do servidor, caso os dados sejam solicitados novamente enquanto o aplicativo está em execução. O cache de dados melhora o desempenho de um aplicativo que recupera dados de um servidor remoto por meio de objetos de conjunto de registros do tipo dynaset. Quando os dados são solicitados, o mecanismo de banco de dados do Microsoft Jet verifica primeiro o cache dos dados solicitados em vez de recuperá-los no servidor, o que leva mais tempo. Os dados que não vêm de uma fonte de dados ODBC não são salvos no cache.

Qualquer fonte de dados ODBC, como uma tabela anexada, pode ter um cache local. Para criar o cache, abra um objeto de conjunto de registros da fonte de dados remota, chame as funções de membro SetCacheSize e SetCacheStart e, em seguida, chame a função de membro FillCache ou passe pelos registros usando uma das operações Move. O parâmetro lSize da função de membro SetCacheSize pode ser baseado no número de registros com os quais seu aplicativo pode trabalhar ao mesmo tempo. Por exemplo, se você estiver usando um conjunto de registros como a fonte dos dados a serem exibidos na tela, poderá passar o SetCacheSize parâmetro lSize como 20 para exibir 20 registros de uma vez.

Para obter informações relacionadas, consulte o tópico "CacheSize, Propriedades do CacheStart" na ajuda do DAO.

CDaoRecordset::SetCacheStart

Chame essa função de membro para especificar o indicador do primeiro registro no conjunto de registros a ser armazenado em cache.

void SetCacheStart(COleVariant varBookmark);

Parâmetros

varBookmark
Um COleVariant que especifica um valor que especifica o indicador do primeiro registro no conjunto de registros a ser armazenado em cache.

Comentários

Você pode usar o valor de indicador de qualquer registro para o parâmetro varBookmark da função de membro SetCacheStart. Faça o registro que você deseja iniciar o cache com o registro atual, estabeleça um indicador para esse registro usando SetBookmark e passe o valor do indicador como o parâmetro para a função de membro SetCacheStart.

O mecanismo de banco de dados do Microsoft Jet solicita registros dentro do intervalo de cache do cache e solicita registros fora do intervalo de cache do servidor.

Os registros recuperados do cache não refletem as alterações feitas simultaneamente nos dados de origem por outros usuários.

Para forçar uma atualização de todos os dados armazenados em cache, passe o parâmetro lSize de SetCacheSize como 0, chame SetCacheSize novamente com o tamanho do cache solicitado originalmente e, depois, chame a função de membro FillCache.

Se você não estiver criando um conjunto de registros UNICODE, o objeto deverá ser declarado COleVariant explicitamente ANSI. Isso pode ser feito usando a forma COleVariant::COleVariant( lpszSrc , vtSrc ) do construtor com vtSrc definido como VT_BSTRT (ANSI) ou usando a COleVariant função SetString( lpszSrc , vtSrc ) com vtSrc definido como .VT_BSTRT

Para obter informações relacionadas, consulte o tópico "propriedades CacheSize, CacheStart" na ajuda do DAO.

CDaoRecordset::SetCurrentIndex

Chame essa função de membro para definir um índice em um conjunto de registros do tipo tabela.

void SetCurrentIndex(LPCTSTR lpszIndex);

Parâmetros

lpszIndex
Um ponteiro que contém o nome do índice a ser definido.

Comentários

Os registros nas tabelas base não são armazenados em nenhuma ordem específica. A configuração de um índice altera a ordem dos registros retornados do banco de dados, mas não afeta a ordem na qual os registros são armazenados. O índice específico precisa ter sido definido. Se você tentar usar um objeto de índice que não existe ou se o índice não estiver definido quando você chamar Seek, o MFC gerará uma exceção.

Você pode criar um novo índice para a tabela chamando CDaoTableDef::CreateIndex e acrescentando o novo índice à coleção Indexes do tabledef subjacente chamando CDaoTableDef::Append e reabrindo o conjunto de registros.

Os registros retornados de um conjunto de registros do tipo tabela só podem ser ordenados pelos índices definidos para o tabledef subjacente. Para classificar registros em outra ordem, você pode abrir um conjunto de registros do tipo dynaset ou do tipo instantâneo usando uma cláusula SQL ORDERBY armazenada em CDaoRecordset::m_strSort.

Para obter informações relacionadas, consulte o tópico "Índice de objeto" e a definição "Índice atual" na ajuda do DAO.

CDaoRecordset::SetFieldDirty

Chame essa função de membro para sinalizar um membro de dados de campo do conjunto de registros como alterado ou inalterado.

void SetFieldDirty(
    void* pv,
    BOOL bDirty = TRUE);

Parâmetros

pv
Contém o endereço de um membro de dados de campo no conjunto de registros ou NULL. Se for NULL, todos os membros de dados de campo no conjunto de registros serão sinalizados. (C++ NULL não é o mesmo que Null na terminologia do banco de dados, que significa "não ter valor".)

bDirty
TRUE se o membro de dados de campo deve ser sinalizado como "sujo" (alterado). Caso contrário, FALSE se o membro de dados de campo for sinalizado como "limpo" (inalterado).

Comentários

Marcar campos como inalterados garante que o campo não seja atualizado.

A estrutura marca os membros de dados de campo alterados para garantir que eles sejam gravados no registro na fonte de dados pelo mecanismo de troca de campo de registro (DFX) do DAO. Alterar o valor de um campo geralmente coloca o campo sujo automaticamente, portanto, você raramente precisará chamar SetFieldDirty a si mesmo, mas às vezes pode querer garantir que as colunas sejam explicitamente atualizadas ou inseridas, independentemente do valor que está no membro de dados do campo. O mecanismo DFX também emprega o uso de PSEUDO NULL. Para obter mais informações, confira CDaoFieldExchange::m_nOperation.

Se o mecanismo de buffer duplo não estiver sendo usado, alterar o valor do campo não definirá automaticamente o campo como sujo. Nesse caso, é necessário definir explicitamente o campo como sujo. O sinalizador contido em m_bCheckCacheForDirtyFields controla essa verificação automática de campo.

Observação

Chame essa função de membro somente depois de chamar Edit ou Add New.

O uso de NULL para o primeiro argumento da função aplicará a função a todos os campos outputColumn, não campos param em CDaoFieldExchange. Por exemplo, a chamada

SetFieldDirty(NULL);

definirá apenas outputColumn os campos como NULL; Os campos de parâmetro não são afetados.

Para trabalhar em um param, você deve fornecer o endereço real do param individual no qual deseja trabalhar, como:

SetFieldDirty(&m_strParam);

Isso significa que você não pode definir todos os campos de parâmetro como NULL, como pode fazer com outputColumn os campos.

SetFieldDirty é implementado por meio de DoFieldExchange.

CDaoRecordset::SetFieldNull

Chame essa função de membro para sinalizar um membro de dados de campo do conjunto de registros como Null (especificamente sem valor) ou como não Null.

void SetFieldNull(
    void* pv,
    BOOL bNull = TRUE);

Parâmetros

pv
Contém o endereço de um membro de dados de campo no conjunto de registros ou NULL. Se for NULL, todos os membros de dados de campo no conjunto de registros serão sinalizados. (C++ NULL não é o mesmo que Null na terminologia do banco de dados, que significa "não ter valor".)

bNull
Diferente zero se o for preciso sinalizar o membro de dados do campo como sem valor (Null). Caso contrário, 0 se o membro de dados de campo for sinalizado como não nulo.

Comentários

SetFieldNull é usado para campos associados ao DoFieldExchange mecanismo.

Quando você adiciona um novo registro a um conjunto de registros, todos os membros de dados de campo são inicialmente definidos como um valor nulo e sinalizados como "sujos" (alterados). Quando você recupera um registro de uma fonte de dados, suas colunas já têm valores ou são nulas. Se não for apropriado tornar um campo Null, um CDaoException será gerado.

Se você estiver usando o mecanismo de buffer duplo, por exemplo, se desejar especificamente designar um campo do registro atual como não tendo um valor, chame SetFieldNull com bNull definido como TRUE para sinalizá-lo como Null. Se um campo tiver sido marcado anteriormente como Nulo e você quiser dar a ele um valor, defina seu novo valor. Você não precisa remover o sinalizador Null com SetFieldNull. Para determinar se o campo tem permissão para ser nulo, chame IsFieldNullable.

Se você não estiver usando o mecanismo de buffer duplo, alterar o valor do campo não definirá automaticamente o campo como sujo e não nulo. Você deve definir especificamente os campos sujos e não nulos. O sinalizador contido em m_bCheckCacheForDirtyFields controla essa verificação automática de campo.

O mecanismo DFX emprega o uso de PSEUDONULL. Para obter mais informações, confira CDaoFieldExchange::m_nOperation.

Observação

Chame essa função de membro somente depois de chamar Edit ou Add New.

O uso de NULL para o primeiro argumento da função aplicará a função somente aos campos outputColumn, não campos param em CDaoFieldExchange. Por exemplo, a chamada

SetFieldNull(NULL);

definirá apenas outputColumn os campos como NULL; Os campos de parâmetro não são afetados.

CDaoRecordset::SetFieldValue

Chame essa função de membro para definir o valor de um campo, seja por posição ordinal ou alterando o valor da cadeia de caracteres.

virtual void SetFieldValue(
    LPCTSTR lpszName,
    const COleVariant& varValue);

virtual void SetFieldValue(
    int nIndex,
    const COleVariant& varValue);

void SetFieldValue(
    LPCTSTR lpszName,
    LPCTSTR lpszValue);

void SetFieldValue(
    int nIndex,
    LPCTSTR lpszValue);

Parâmetros

lpszName
Um ponteiro para uma cadeia de caracteres contendo o nome de um campo.

varValue
Uma referência a um objeto COleVariant que contém o valor do conteúdo do campo.

nIndex
Um inteiro que representa a posição ordinal do campo na coleção Fields do conjunto de registros (baseada em zero).

lpszValue
Um ponteiro para uma cadeia de caracteres que contém o valor do conteúdo do campo.

Comentários

Use SetFieldValue e GetFieldValue para associar dinamicamente campos em tempo de execução em vez de associar colunas estaticamente usando o mecanismo DoFieldExchange.

Se você não estiver criando um conjunto de registros UNICODE, deverá usar um formulário que não contenha um COleVariant parâmetro ou o objeto deverá ser declarado SetFieldValue COleVariant explicitamente ANSI. Isso pode ser feito usando a forma COleVariant::COleVariant( lpszSrc , vtSrc ) do construtor com vtSrc definido como VT_BSTRT (ANSI) ou usando a COleVariant função SetString( lpszSrc , vtSrc ) com vtSrc definido como .VT_BSTRT

Para obter informações relacionadas, consulte os tópicos "Objeto Field" e "Propriedade Value" na ajuda do DAO.

CDaoRecordset::SetFieldValueNull

Chame essa função de membro para definir o campo como um valor Null.

void SetFieldValueNull(int nIndex);
void SetFieldValueNull(LPCTSTR lpszName);

Parâmetros

nIndex
O índice do campo no conjunto de registros, para pesquisa por índice baseado em zero.

lpszName
O nome do campo no conjunto de registros, para pesquisa por nome.

Comentários

C++ NULL não é o mesmo que Null, que, na terminologia do banco de dados, significa "não ter valor".

Para obter informações relacionadas, consulte os tópicos "Objeto Field" e "Propriedade Value" na ajuda do DAO.

CDaoRecordset::SetLockingMode

Chame essa função de membro para definir o tipo de bloqueio do conjunto de registros.

void SetLockingMode(BOOL bPessimistic);

Parâmetros

bPessimistic
Um sinalizador que indica o tipo de bloqueio.

Comentários

Quando o bloqueio pessimista está em vigor, a página 2K que contém o registro que você está editando é bloqueada assim que você chama a função de Edit membro. A página é desbloqueada quando você chama a função de membro Update ou Close, ou qualquer uma das operações Move ou Find.

Quando o bloqueio otimista está em vigor, a página 2K que contém o registro é bloqueada somente enquanto o registro está sendo atualizado com a função de membro Update.

Se uma página estiver bloqueada, nenhum outro usuário poderá editar registros na mesma página. Se você chamar SetLockingMode e passar um valor diferente de zero e outro usuário já tiver a página bloqueada, uma exceção será gerada quando você chamar Edit. Outros usuários podem ler dados de páginas bloqueadas.

Se você chamar SetLockingMode com um valor zero e chamar Update posteriormente enquanto a página estiver bloqueada por outro usuário, ocorrerá uma exceção. Para ver as alterações feitas em seu registro por outro usuário (e perder suas alterações), chame a função de membro SetBookmark com o valor do indicador do registro atual.

Ao trabalhar com fontes de dados ODBC, o modo de bloqueio é sempre otimista.

CDaoRecordset::SetParamValue

Chame essa função de membro para definir o valor de um parâmetro no conjunto de registros em tempo de execução.

virtual void SetParamValue(
    int nIndex,
    const COleVariant& varValue);

virtual void SetParamValue(
    LPCTSTR lpszName,
    const COleVariant& varValue);

Parâmetros

nIndex
A posição numérica do parâmetro na coleção Parameters do querydef.

var
O valor a ser definido; consulte Comentários.

lpszName
O nome do parâmetro cujo valor você deseja definir.

Comentários

O parâmetro já deve ter sido estabelecido como parte da cadeia de caracteres SQL do conjunto de registros. Você pode acessar o parâmetro por nome ou por sua posição de índice na coleção.

Especifique o valor a ser definido como um objeto COleVariant. Para obter informações sobre como definir o valor desejado e o tipo em seu objeto COleVariant, consulte a classe COleVariant. Se você não estiver criando um conjunto de registros UNICODE, o objeto deverá ser declarado COleVariant explicitamente ANSI. Isso pode ser feito usando a forma COleVariant::COleVariant( lpszSrc , vtSrc ) do construtor com vtSrc definido como VT_BSTRT (ANSI) ou usando a COleVariant função SetString( lpszSrc , vtSrc ) com vtSrc definido como .VT_BSTRT

CDaoRecordset::SetParamValueNull

Chame essa função de membro para definir o parâmetro como um valor Null.

void SetParamValueNull(int nIndex);
void SetParamValueNull(LPCTSTR lpszName);

Parâmetros

nIndex
O índice do campo no conjunto de registros, para pesquisa por índice baseado em zero.

lpszName
O nome do campo no conjunto de registros, para pesquisa por nome.

Comentários

C++ NULL não é o mesmo que Null, que, na terminologia do banco de dados, significa "não ter valor".

CDaoRecordset::SetPercentPosition

Chame essa função de membro para definir um valor que altera o local aproximado do registro atual no objeto do conjunto de registros com base em uma porcentagem dos registros no conjunto de registros.

void SetPercentPosition(float fPosition);

Parâmetros

fPosition
Um número entre 0 e 100.

Comentários

Ao trabalhar com um conjunto de registros do tipo dynaset ou do tipo instantâneo, primeiro preencha o conjunto de registros movendo-se para o último registro antes de chamar SetPercentPosition. Se você chamar SetPercentPosition antes de preencher totalmente o conjunto de registros, a quantidade de movimentação será relativa ao número de registros acessados conforme indicado pelo valor de GetRecordCount. Você pode mover para o último registro chamando MoveLast.

Depois de chamar SetPercentPosition, o registro na posição aproximada correspondente a esse valor se tornará atual.

Observação

Não é recomendável chamar SetPercentPosition para mover o registro atual para um registro específico em um conjunto de registros. Em vez disso, chame a função de membro SetBookmark.

Para obter informações relacionadas, consulte o tópico "Propriedade PercentPosition" na ajuda do DAO.

CDaoRecordset::Update

Chame essa função de membro após uma chamada para a função de membro AddNew ou Edit.

virtual void Update();

Comentários

Essa chamada é necessária para concluir a operação AddNew ou Edit.

Tanto AddNew quanto Edit preparam um buffer de edição no qual os dados adicionados ou editados são colocados para salvar na fonte de dados. Update salva os dados. Somente os campos marcados ou detectados como alterados são atualizados.

Se a fonte de dados suportar transações, você fazer Update chamar (e sua chamada AddNew ou Edit correspondente) parte de uma transação.

Cuidado

Se você chamar Update sem chamar AddNew ou Edit primeiro, Update gerará um CDaoException. Se você chamar AddNew ou Edit, deve chamar Update antes de chamar MoveNext ou fechar o conjunto de registros ou a conexão da fonte de dados. Caso contrário, suas alterações serão perdidas sem notificação.

Quando o objeto do conjunto de registros é bloqueado de modo pessimista em um ambiente multiusuário, o registro permanece bloqueado a partir do momento que Edit é usado até que a atualização seja concluída. Se o conjunto de registros for bloqueado de forma otimista, o registro será bloqueado e comparado com o registro pré-editado pouco antes de ser atualizado no banco de dados. Se o registro tiver sido alterado desde que você chamou Edit, a operação Update falha e o MFC gera uma exceção. você pode alterar o modo de bloqueio com SetLockingMode.

Observação

O bloqueio otimista é sempre usado em formatos de banco de dados externos, como ODBC e ISAM instalável.

Para obter informações relacionadas, consulte os tópicos "Método AddNew", "Método CancelUpdate", "Método Delete", "Propriedade LastModified", "Método Update" e "Propriedade EditMode" na ajuda do DAO.

Confira também

Classe CObject
Gráfico da hierarquia
Classe CDaoTableDef
Classe CDaoWorkspace
Classe CDaoDatabase
Classe CDaoQueryDef