CRecordset classe

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

Sintaxe

class CRecordset : public CObject

Membros

Construtores públicos

Métodos públicos

Membros de dados públicos

Observações

Conhecidos como "conjuntos de registros", CRecordset os objetos são normalmente usados de duas formas: dynasets e snapshots. Um dynaset permanece sincronizado com atualizações de dados feitas por outros usuários. Um instantâneo é uma exibição estática dos dados. Cada formulário representa um conjunto de registros fixados no momento em que o conjunto de registros é aberto. Quando você rola para um registro em um dynaset, ele reflete as alterações feitas no registro, seja por outros usuários ou por outros conjuntos de registros em seu aplicativo.

Para trabalhar com qualquer tipo de conjunto de registros, você normalmente deriva uma classe de conjunto de registros específica do aplicativo de CRecordset. Os conjuntos de registros selecionam registros de uma fonte de dados e você pode:

• Percorra os registos.

• Atualize os registros e especifique um modo de bloqueio.

• Filtre o conjunto de registros para restringir quais registros ele seleciona daqueles disponíveis na fonte de dados.

• Classifique o conjunto de registros.

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

Para usar sua classe, abra um banco de dados e construa um objeto de conjunto de registros, passando o construtor um ponteiro para seu CDatabase objeto. Em seguida, chame a função de membro do conjunto de registros Open , onde você pode especificar se o objeto é um dynaset ou um instantâneo. A chamada Open seleciona dados da fonte de dados. Depois que o objeto recordset for aberto, use suas funções de membro e membros de dados para percorrer os registros e operar neles. As operações disponíveis dependem se o objeto é um dynaset ou um instantâneo, se é atualizável ou somente leitura (isso depende da capacidade da fonte de dados ODBC (Open Database Connectivity)) e se você implementou a busca de linha em massa. Para atualizar registros que podem ter sido alterados ou adicionados desde a Open chamada, chame a função de Requery membro do objeto. Chame a função de membro do Close objeto e destrua o objeto quando terminar com ele.

Em uma classe derivada CRecordset , a troca de campo de registro (RFX) ou a troca de campo de registro em massa (RFX em massa) é usada para dar suporte à leitura e atualização de campos de registro.

Para obter mais informações sobre conjuntos de registros e troca de campos de registro, consulte os artigos Visão geral: Programação de banco de dados, Conjunto de registros (ODBC),Conjunto de registros: Obtenção de registros em massa (ODBC) e Troca de campo de registro (RFX). Para obter um foco em dynasets e snapshots, consulte os artigos Dynaset e Snapshot.

Hierarquia de herança

CObject

CRecordset

Requerimentos

Cabeçalho:afxdb.h

CRecordset::AddNew

Prepara-se para adicionar um novo registro à tabela.

virtual void AddNew();

Observações

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

AddNew Prepara um novo registro vazio usando os membros de dados de campo do conjunto de registros. Depois de chamar AddNewo , defina os valores desejados nos membros de dados de campo do conjunto de registros. (Não é necessário chamar a função Editar membro para essa finalidade; use Edit apenas para registros existentes.) Quando você chama Update, os valores alterados nos membros de dados de campo são salvos na fonte de dados.

Se a fonte de dados oferecer suporte a transações, você poderá tornar sua AddNew chamada parte de uma transação. Para obter mais informações sobre transações, consulte classe CDatabase. Ligue CDatabase::BeginTrans antes de ligar AddNewpara .

É ilegal chamar AddNew um conjunto de registros cuja Open função de membro não tenha sido chamada. A CDBException é lançado se você chamar AddNew um conjunto de registros que não pode ser anexado. Você pode determinar se o conjunto de registros é atualizável chamando CanAppend.

Para obter mais informações, consulte os seguintes artigos: Recordset: How Recordsets Update Records (ODBC),Recordset: Adding, Updating, and Delete Records (ODBC) e Transaction (ODBC).

Exemplo

consulte Transação: Executando uma transação em um conjunto de registros (ODBC).

CRecordset::CanAppend

Determina se o conjunto de registros aberto anteriormente permite adicionar novos registros.

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 retornará 0 se você tiver aberto o conjunto de registros como somente leitura.

CRecordset::CanBookmark

Determina se o conjunto de registros permite marcar registros usando marcadores.

BOOL CanBookmark() const;

Valor de retorno

Diferente de zero se o conjunto de registros suportar marcadores; caso contrário, 0.

Observações

Esta função é independente da CRecordset::useBookmarks opção no dwOptions parâmetro da Open função membro. CanBookmark indica se o driver ODBC e o tipo de cursor fornecidos suportam favoritos. CRecordset::useBookmarks Indica se os favoritos estarão disponíveis, desde que sejam suportados.

Para obter mais informações sobre marcadores e navegação no conjunto de registros, consulte os artigos Recordset: Bookmarks and Absolute Positions (ODBC) e Recordset: Scrolling (ODBC).

CRecordset::Cancel

Solicita que a fonte de dados cancele uma operação assíncrona em andamento ou um processo de um segundo thread.

void Cancel();

Observações

As classes ODBC do MFC não usam mais processamento assíncrono; para executar uma operação assíncrona, você deve chamar diretamente a função SQLSetConnectOptionde API ODBC. Para obter mais informações, consulte "Executando funções de forma assíncrona" no Guia do programador do SDK ODBC.

CRecordset::CancelUpdate

Cancela quaisquer atualizações pendentes, causadas por uma Edit ou AddNew operação, antes Update de ser chamada.

void CancelUpdate();

Observações

Se a verificação automática de campo sujo estiver ativada, CancelUpdate restaurará as variáveis de membro para os valores que tinham antes Edit ou AddNew foram chamados, caso contrário, quaisquer alterações de valor permanecerão. Por padrão, a verificação automática de campos é habilitada quando o conjunto de registros é aberto. Para desativá-lo, você deve especificar o CRecordset::noDirtyFieldCheckdwOptions no parâmetro da função de membro aberto .

Para obter mais informações sobre como atualizar dados, consulte Recordset: Adicionando, atualizando e excluindo registros (ODBC).

CRecordset::CanRestart

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

BOOL CanRestart() const;

Valor de retorno

Diferente de zero se for permitida uma nova consulta; caso contrário, 0.

CRecordset::CanScroll

Determina se o conjunto de registros permite a rolagem.

BOOL CanScroll() const;

Valor de retorno

Diferente de zero se o conjunto de registros permitir rolagem; caso contrário, 0.

Observações

Para obter mais informações sobre rolagem, consulte Recordset: Scrolling (ODBC).

CRecordset::CanTransact

Determina se o conjunto de registros permite transações.

BOOL CanTransact() const;

Valor de retorno

Diferente de zero se o conjunto de registros permitir transações; caso contrário, 0.

Observações

Para obter mais informações, consulte Transação (ODBC).

CRecordset::CanUpdate

Determina 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; caso contrário, 0.

Observações

Um conjunto de registros pode ser somente leitura se a fonte de dados subjacente for somente leitura ou se você tiver especificado CRecordset::readOnly no dwOptions parâmetro quando abriu o conjunto de registros.

CRecordset::CheckRowsetError

Chamado para lidar com erros gerados durante a busca de registros.

virtual void CheckRowsetError(RETCODE nRetCode);

Parâmetros

nRetCode
Um código de retorno de função de API ODBC. Para obter detalhes, consulte Observações.

Observações

Essa função de membro virtual manipula erros que ocorrem quando os registros são buscados e é útil durante a busca de linha em massa. Você pode considerar a substituição CheckRowsetError para implementar seu próprio tratamento de erros.

CheckRowsetError é chamado automaticamente em uma operação de navegação do cursor, como Open, Requeryou qualquer Move operação. Ele passou o valor de retorno da função SQLExtendedFetchde API ODBC. A tabela a seguir lista os valores possíveis para o nRetCode parâmetro.

Para obter mais informações sobre SQLErroro , consulte o SDK do Windows. Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

CRecordset::Close

Fecha o conjunto de registros.

virtual void Close();

Observações

O ODBC HSTMT e toda a memória alocada para o conjunto de registros são deslocalizados. Normalmente, depois de chamar Close, você exclui o objeto do conjunto de registros C++ se ele foi alocado com new.

Você pode ligar Open novamente depois de ligar Close. Isso permite reutilizar o objeto do conjunto de registros. A alternativa é chamar Requery.

Exemplo

// Construct a snapshot object
CCustomer rsCustSet(NULL);

if (!rsCustSet.Open())
return;

// Use the snapshot ...

// Close the snapshot
rsCustSet.Close();

// Destructor is called when the function exits

CRecordset::CRecordset

Constrói um objeto CRecordset.

CRecordset(CDatabase* pDatabase = NULL);

Parâmetros

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

Observações

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

Passe NULL para o construtor do conjunto de registros para ter um CDatabase objeto construído e conectado para você automaticamente. Esta é uma abreviação útil que não requer que você construa e conecte um CDatabase objeto antes de construir seu conjunto de registros.

Exemplo

Para obter mais informações, consulte Recordset: Declaring a Class for a Table (ODBC).

CRecordset::Delete

Exclui o registro atual.

virtual void Delete();

Observações

Após uma exclusão bem-sucedida, os membros de dados de campo do conjunto de registros são definidos como um valor Nulo e você deve chamar explicitamente uma das Move funções para sair do registro excluído. Depois de sair do registro excluído, não é possível retornar a ele. Se a fonte de dados oferecer suporte a transações, você poderá tornar a Delete chamada parte de uma transação. Para obter mais informações, consulte Transação (ODBC).

Ao contrário AddNew de e Edit, uma chamada para Delete não é seguida por uma chamada para Update. Se uma Delete chamada falhar, os membros de dados de campo serão mantidos inalterados.

Exemplo

Este exemplo mostra um conjunto de registros criado no quadro de uma função. O exemplo pressupõe a existência de , uma variável membro do tipo m_dbCust já conectada à fonte de CDatabasedados.

// Create a derived CRecordset object
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if (rsCustSet.IsEOF() || !rsCustSet.CanUpdate() ||
   !rsCustSet.CanTransact())
{
   return;
}

m_dbCust.BeginTrans();

// Perhaps scroll to a new record...
// Delete the current record
rsCustSet.Delete();

// Finished commands for this transaction
if (IDYES == AfxMessageBox(_T("Commit transaction?"), MB_YESNO))
m_dbCust.CommitTrans();
else // User changed mind
m_dbCust.Rollback();

CRecordset::DoBulkFieldExchange

Chamado para trocar linhas em massa de dados da fonte de dados para o conjunto de registros. Implementa a troca de campo de registro em massa (RFX em massa).

virtual void DoBulkFieldExchange(CFieldExchange* pFX);

Parâmetros

pFX
Um ponteiro para um CFieldExchange objeto. A estrutura já terá configurado este objeto para especificar um contexto para a operação de troca de campo.

Observações

Quando a busca de linha em massa é implementada, a estrutura chama essa função de membro para transferir automaticamente dados da fonte de dados para o objeto do conjunto de registros. DoBulkFieldExchange também vincula 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.

Se a busca de linha em massa não for implementada, a estrutura chamará DoFieldExchange. Para implementar a busca de linha em massa, você deve especificar a CRecordset::useMultiRowFetch opção do parâmetro dwOptions na Open função member.

A troca de campo de registro em massa (RFX em massa) é semelhante à troca de campo de registro (RFX). Os dados são transferidos automaticamente da fonte de dados para o objeto do conjunto de registros. No entanto, não é possível chamar AddNew, Edit, Deleteou Update transferir as alterações de volta para a fonte de dados. Classe CRecordset atualmente não fornece um mecanismo para atualizar linhas em massa de dados, no entanto, você pode escrever suas próprias funções usando a função SQLSetPosODBC API .

O ClassWizard não suporta troca de campo de registro em massa; portanto, você deve substituir DoBulkFieldExchange manualmente gravando chamadas para as funções RFX em massa. Para obter mais informações sobre essas funções, consulte Funções de troca de campo de registro.

Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC). Para obter informações relacionadas, consulte Record Field Exchange (RFX).

CRecordset::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 a troca de campo de registro (RFX).

virtual void DoFieldExchange(CFieldExchange* pFX);

Parâmetros

pFX
Um ponteiro para um CFieldExchange objeto. A estrutura já terá configurado este objeto para especificar um contexto para a operação de troca de campo.

Observações

Quando a busca de linha em massa não é implementada, 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. DoFieldExchange também vincula 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.

Se a busca de linha em massa for implementada, a estrutura chamará DoBulkFieldExchange. Para implementar a busca de linha em massa, você deve especificar a CRecordset::useMultiRowFetchdwOptions opção do parâmetro na Open função membro.

A troca de dados de campo, chamada de troca de campo de registro (RFX), funciona em ambas as direções: dos membros de dados de campo do objeto do conjunto de registros para os campos do registro na fonte de dados e do registro na fonte de dados para o objeto do conjunto de registros.

A única ação que você normalmente deve executar para implementar DoFieldExchange sua classe de conjunto de registros derivada é criar a classe com ClassWizard e especificar os nomes e tipos de dados dos membros de dados de campo. Você também pode adicionar código ao que ClassWizard escreve para especificar membros de dados de parâmetro ou para lidar com quaisquer colunas vinculadas dinamicamente. Para obter mais informações, consulte Recordset: Dynamically Binding Data Columns (ODBC).

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 CCustomer::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputColumn);
   // Macros such as RFX_Text() and RFX_Int() are dependent on the
   // type of the member variable, not the type of the field in the database.
   // ODBC will try to automatically convert the column value to the requested type
   RFX_Long(pFX, _T("[CustomerID]"), m_CustomerID);
   RFX_Text(pFX, _T("[ContactFirstName]"), m_ContactFirstName);
   RFX_Text(pFX, _T("[PostalCode]"), m_PostalCode);
   RFX_Text(pFX, _T("[L_Name]"), m_L_Name);
   RFX_Long(pFX, _T("[BillingID]"), m_BillingID);

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param"), m_strParam);
}

Para obter mais informações sobre as funções RFX, consulte Record Field Exchange Functions.

Para obter mais exemplos e detalhes sobre DoFieldExchangeo , consulte Record Field Exchange: How RFX Works. Para obter informações gerais sobre RFX, consulte Record Field Exchange.

CRecordset::Edit

Permite alterações no registro atual.

virtual void Edit();

Observações

Depois de chamar Edito , você pode alterar os membros de dados de campo redefinindo diretamente seus valores. A operação é concluída quando você chama a Update função de membro para salvar as alterações na fonte de dados.

Edit salva os valores dos membros de dados do conjunto de registros. Se você chamar Edit, fazer alterações e, em seguida, chamar Edit novamente, os valores do registro serão restaurados para o que eram antes da primeira Edit chamada.

Em alguns casos, convém atualizar uma coluna tornando-a Nula (sem dados). Para fazer isso, chame SetFieldNull com um parâmetro de TRUE para marcar o campo Nulo, isso também faz com que a coluna seja atualizada. Se desejar 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 tiver o valor Nulo.

Se a fonte de dados oferecer suporte a transações, você poderá tornar a Edit chamada parte de uma transação. Ligue CDatabase::BeginTrans antes da chamada Edit e depois que o conjunto de registros for aberto. Além disso, chamar CDatabase::CommitTrans não Update substitui chamar para concluir a Edit operação. Para obter mais informações sobre transações, consulte classe CDatabase.

Dependendo do modo de bloqueio atual, o registro que está sendo atualizado pode ser bloqueado até Edit que você chame Update ou role para outro registro, ou pode ser bloqueado apenas durante a Edit chamada. Você pode alterar o modo de bloqueio com SetLockingMode.

O valor anterior do registro atual será restaurado se você rolar para um novo registro antes de chamar Update. A CDBException é lançado se você chamar Edit um conjunto de registros que não pode ser atualizado ou se não houver nenhum registro atual.

Para obter mais informações, consulte os artigos Transaction (ODBC) e Recordset: Locking Records (ODBC).

Exemplo

// To edit a record, first set up the edit buffer
rsCustSet.Edit();

// Then edit field data members for the record
rsCustSet.m_BillingID = 2795;
rsCustSet.m_ContactFirstName = _T("Jones Mfg");

// Finally, complete the operation
if (!rsCustSet.Update())
{
   // Handle the failure to update
   AfxMessageBox(_T("Couldn't update record!"));
}

CRecordset::FlushResultSet

Recupera o próximo conjunto de resultados de uma consulta predefinida (procedimento armazenado), se houver vários conjuntos de resultados.

BOOL FlushResultSet();

Valor de retorno

Diferente de zero se houver mais conjuntos de resultados a serem recuperados; caso contrário, 0.

Observações

Você deve ligar FlushResultSet somente quando terminar de usar o cursor no conjunto de resultados atual. Quando você recupera o próximo conjunto de resultados chamando FlushResultSet, seu cursor não é válido nesse conjunto de resultados, você deve chamar a MoveNext função de membro depois de chamar FlushResultSet.

Se uma consulta predefinida usa um parâmetro de saída ou parâmetros de entrada/saída, você deve chamar FlushResultSet até que ele retorne FALSE(o valor 0), a fim de obter esses valores de parâmetro.

FlushResultSet chama a função SQLMoreResultsde API ODBC . Se SQLMoreResults retornar SQL_ERROR ou SQL_INVALID_HANDLE, então FlushResultSet lançará uma exceção. Para obter mais informações sobre SQLMoreResultso , consulte o SDK do Windows.

Seu procedimento armazenado precisa ter campos acoplados se você quiser chamar FlushResultSet.

Exemplo

O código a seguir pressupõe que COutParamRecordset é um CRecordsetobjeto derivado baseado em uma consulta predefinida com um parâmetro de entrada e um parâmetro de saída, e com vários conjuntos de resultados. Observe a estrutura da DoFieldExchange substituição.

// DoFieldExchange override
//
// Only necessary to handle parameter bindings.
// Don't use CRecordset-derived class with bound
// fields unless all result sets have same schema
// OR there is conditional binding code.
void CCourses::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputParam);
   RFX_Long(pFX, _T("Param1"), m_nCountParam);
   // The "Param1" name here is a dummy name 
   // that is never used

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param2"), m_strNameParam);
   // The "Param2" name here is a dummy name 
   // that is never used
}

// Assume db is an already open CDatabase object
CCourses rs(&m_dbCust);
rs.m_strNameParam = _T("History");

// Get the first result set
// NOTE: SQL Server requires forwardOnly cursor 
//       type for multiple rowset returning stored 
//       procedures
rs.Open(CRecordset::forwardOnly,
   _T("{? = CALL GetCourses( ? )}"),
   CRecordset::readOnly);

// Loop through all the data in the first result set
while (!rs.IsEOF())
{
   CString strFieldValue;
   for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
   {
      rs.GetFieldValue(nIndex, strFieldValue);

      // TO DO: Use field value string.
   }
   rs.MoveNext();
}

// Retrieve other result sets...
while (rs.FlushResultSet())
{
   // must call MoveNext because cursor is invalid
   rs.MoveNext();

   while (!rs.IsEOF())
   {
      CString strFieldValue;
      for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
      {
         rs.GetFieldValue(nIndex, strFieldValue);

         // TO DO: Use field value string.
      }
      rs.MoveNext();
   }
}


// All result sets have been flushed. Cannot
// use the cursor, but the output parameter,
// m_nCountParam, has now been written.
// Note that m_nCountParam is not valid until
// CRecordset::FlushResultSet has returned FALSE,
// indicating no more result sets will be returned.

// TO DO: Use m_nCountParam

// Cleanup
rs.Close();

CRecordset::GetBookmark

Obtém o valor do indicador para o registro atual.

void GetBookmark(CDBVariant& varBookmark);

Parâmetros

varBookmark
Uma referência a um CDBVariant objeto que representa o marcador no registro atual.

Observações

Para determinar se os marcadores são suportados no conjunto de registros, chame CanBookmark. Para disponibilizar favoritos, se eles forem suportados, você deve definir a CRecordset::useBookmarks opção no dwOptions parâmetro da função de Open membro.

GetBookmark Atribui o valor do indicador para o registro atual a um CDBVariant objeto. Para retornar a esse registro a qualquer momento depois de mover para um registro diferente, chame SetBookmark com o objeto correspondente CDBVariant .

Para obter mais informações sobre marcadores e navegação no conjunto de registros, consulte os artigos Recordset: Bookmarks and Absolute Positions (ODBC) e Recordset: Scrolling (ODBC).

CRecordset::GetDefaultConnect

Chamado para obter a cadeia de conexão padrão.

virtual CString GetDefaultConnect();

Valor de retorno

A CString que contém a cadeia de conexão padrão.

Observações

A estrutura chama essa função de membro para obter a cadeia de conexão padrão para a fonte de dados na qual o conjunto de registros é baseado. ClassWizard implementa essa função para você, identificando a mesma fonte de dados que você usa para ClassWizard obter informações sobre tabelas e colunas. Você provavelmente achará conveniente confiar nessa conexão padrão ao desenvolver seu aplicativo. Mas a conexão padrão pode não ser apropriada para usuários do seu aplicativo. Se esse for o caso, você deve reimplementar essa função, descartando ClassWizarda versão do . Para obter mais informações sobre cadeias de conexão, consulte Fonte de dados (ODBC).

CRecordset::GetDefaultSQL

Chamado para obter a cadeia de caracteres SQL padrão para executar.

virtual CString GetDefaultSQL();

Valor de retorno

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

Observações

A estrutura chama essa função de membro para obter a instrução SQL padrão na qual o conjunto de registros se baseia. 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ê precisar da cadeia de caracteres da instrução SQL para seu próprio uso, chame GetSQL, que retorna a instrução SQL usada para selecionar os registros do conjunto de registros quando ele foi aberto. Você pode editar a cadeia de caracteres SQL padrão na substituição de GetDefaultSQL. Por exemplo, você pode especificar uma chamada para uma consulta predefinida usando uma CALL instrução. (Observe, no entanto, que, se você editar GetDefaultSQL, também precisará modificar m_nFields para corresponder ao número de colunas na fonte de dados.)

Para obter mais informações, consulte Recordset: Declaring a Class for a Table (ODBC).

CRecordset::GetFieldValue

Recupera dados de campo no registro atual.

void GetFieldValue(
    LPCTSTR lpszName,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringA& strValue
);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringW& strValue
);

void GetFieldValue(
    short nIndex,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    short nIndex,
    CStringA& strValue);

void GetFieldValue(
    short nIndex,
    CStringW& strValue);

Parâmetros

lpszName
O nome de um campo.

varValue Uma referência a um CDBVariant objeto que armazenará o valor do campo.

nFieldType
O tipo de dados ODBC C do campo. Usando o valor padrão, DEFAULT_FIELD_TYPE, força GetFieldValue a determinar o tipo de dados C do tipo de dados SQL, com base na tabela a seguir. Caso contrário, você pode especificar o tipo de dados diretamente ou escolher um tipo de dados compatível; Por exemplo, você pode armazenar qualquer tipo de dados no SQL_C_CHAR.

Para obter mais informações sobre tipos de dados ODBC, consulte os tópicos "Tipos de dados SQL" e "Tipos de dados C" no Apêndice D do SDK do Windows.

nIndex
O índice baseado em zero do campo.

strValue
Uma referência a um CString objeto que armazenará o valor do campo convertido em texto, independentemente do tipo de dados do campo.

Observações

Você pode procurar um campo por nome ou por índice. Você pode armazenar o valor do campo em um CDBVariant objeto ou em um CString objeto.

Se você implementou a busca de linha em massa, o registro atual será sempre posicionado no primeiro registro de um conjunto de linhas. Para usar GetFieldValue em um registro dentro de um determinado conjunto de linhas, você deve primeiro chamar a SetRowsetCursorPosition função de membro para mover o cursor para a linha desejada dentro desse conjunto de linhas. Então chame GetFieldValue para essa fila. Para implementar a busca de linha em massa, você deve especificar a CRecordset::useMultiRowFetchdwOptions opção do parâmetro na Open função membro.

Você pode usar GetFieldValue para buscar campos dinamicamente em tempo de execução em vez de vinculá-los estaticamente em tempo de design. Por exemplo, se você tiver declarado um objeto de conjunto de registros diretamente do , deverá usar CRecordset para recuperar os dados de campo; a troca de campos de registro (RFX) ou a troca de campos de GetFieldValueregistro em massa (RFX em massa) não será implementada.

GetFieldValue chama a função SQLGetDatade API ODBC . Se o driver gerar o valor SQL_NO_TOTAL para o comprimento real do valor do campo, GetFieldValue lançará uma exceção. Para obter mais informações sobre SQLGetDatao , consulte o SDK do Windows.

Exemplo

O código de exemplo a seguir ilustra chamadas para GetFieldValue um objeto de conjunto de registros declarado diretamente de CRecordset.

// Create and open a database object;
// do not load the cursor library
CDatabase db;
db.OpenEx(NULL, CDatabase::forceOdbcDialog);

// Create and open a recordset object
// directly from CRecordset. Note that a
// table must exist in a connected database.
// Use forwardOnly type recordset for best
// performance, since only MoveNext is required
CRecordset rs(&db);
rs.Open(CRecordset::forwardOnly, _T("SELECT * FROM Customer"));

// Create a CDBVariant object to
// store field data
CDBVariant varValue;

// Loop through the recordset,
// using GetFieldValue and
// GetODBCFieldCount to retrieve
// data in all columns
short nFields = rs.GetODBCFieldCount();
while (!rs.IsEOF())
{
   for (short index = 0; index < nFields; index++)
   {
      rs.GetFieldValue(index, varValue);
      // do something with varValue
   }
   rs.MoveNext();
}

rs.Close();
db.Close();

Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

CRecordset::GetODBCFieldCount

Recupera o número total de campos no objeto do conjunto de registros.

short GetODBCFieldCount() const;

Valor de retorno

O número de campos no conjunto de registros.

Observações

Para obter mais informações sobre como criar conjuntos de registros, consulte Recordset: Creating and Closing Recordsets (ODBC).

CRecordset::GetODBCFieldInfo

Obtém informações sobre os campos no conjunto de registros.

void GetODBCFieldInfo(
    LPCTSTR lpszName,
    CODBCFieldInfo& fieldinfo);

void GetODBCFieldInfo(
    short nIndex,
    CODBCFieldInfo& fieldinfo);

Parâmetros

lpszName
O nome de um campo.

fieldinfo
Uma referência a uma CODBCFieldInfo estrutura.

nIndex
O índice baseado em zero do campo.

Observações

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

Para obter uma descrição sobre as informações retornadas, consulte a CODBCFieldInfo estrutura.

Para obter mais informações sobre como criar conjuntos de registros, consulte Recordset: Creating and Closing Recordsets (ODBC).

CRecordset::GetRecordCount

Determina o tamanho do conjunto de registros.

long GetRecordCount() const;

Valor de retorno

O número de registos no conjunto de registos; 0 se o conjunto de registos não contiver registos; ou -1 se a contagem de registros não puder ser determinada.

Observações

CRecordset::GetRowsetSize

Obtém a configuração atual para o número de linhas que você deseja recuperar durante uma determinada busca.

DWORD GetRowsetSize() const;

Valor de retorno

O número de linhas a serem recuperadas durante uma determinada busca.

Observações

Se você estiver usando a busca de linha em massa, o tamanho padrão do conjunto de linhas quando o conjunto de registros é aberto é 25; caso contrário, é 1.

Para implementar a busca de linha em massa, você deve especificar a CRecordset::useMultiRowFetchdwOptions opção no parâmetro da função membro Open . Para alterar a configuração do tamanho do conjunto de linhas, chame SetRowsetSize.

Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

CRecordset::GetRowsFetched

Determina quantos registros foram recuperados após uma busca.

DWORD GetRowsFetched() const;

Valor de retorno

O número de linhas recuperadas da fonte de dados após uma determinada busca.

Observações

Isso é útil quando você implementou a busca de linhas em massa. O tamanho do conjunto de linhas normalmente indica quantas linhas serão recuperadas de uma busca. No entanto, o número total de linhas no conjunto de registros também afeta quantas linhas serão recuperadas em um conjunto de linhas. Por exemplo, se o conjunto de registros tiver 10 registros com uma configuração de tamanho de conjunto de linhas de quatro, fazer um loop pelo conjunto de registros chamando MoveNext fará com que o conjunto de linhas final tenha apenas dois registros.

Para implementar a busca de linha em massa, você deve especificar a CRecordset::useMultiRowFetch opção no parâmetro dwOptions da Open função membro. Para especificar o tamanho do conjunto de linhas, chame SetRowsetSize.

Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

Exemplo

CMultiCustomer rs(&m_dbCust);

// Set the rowset size
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// loop through the recordset by rowsets
while (!rs.IsEOF())
{
   for (int rowCount = 0; rowCount < (int)rs.GetRowsFetched(); rowCount++)
   {
      // do something
   }

   rs.MoveNext();
}

rs.Close();

CRecordset::GetRowStatus

Obtém o status de uma linha no conjunto de linhas atual.

WORD GetRowStatus(WORD wRow) const;

Parâmetros

wRow
A posição baseada em uma linha no conjunto de linhas atual. Esse valor pode variar de 1 até o tamanho do conjunto de linhas.

Valor de retorno

Um valor de status para a linha. Para obter detalhes, consulte Observações.

Observações

GetRowStatus Retorna um valor que indica qualquer alteração no status da linha desde a última vez que ela foi recuperada da fonte de dados ou que nenhuma linha correspondente a wRow foi buscada. A tabela a seguir lista os valores de retorno possíveis.

Para obter mais informações, consulte a função SQLExtendedFetch de API ODBC no SDK do Windows.

CRecordset::GetStatus

Determina o índice do registro atual no conjunto de registros e se o último registro foi visto.

void GetStatus(CRecordsetStatus& rStatus) const;

Parâmetros

rStatus
Uma referência a um objeto CRecordsetStatus. Para obter mais informações, veja Observações.

Observações

CRecordset tenta rastrear o índice, mas em algumas circunstâncias isso pode não ser possível. Consulte GetRecordCount para obter uma explicação.

A CRecordsetStatus estrutura tem a seguinte forma:

struct CRecordsetStatus
{
    long m_lCurrentRecord;
    BOOL m_bRecordCountFinal;
};

Os dois membros do CRecordsetStatus têm os seguintes significados:

• m_lCurrentRecord Contém o índice baseado em zero do registro atual no conjunto de registros, se conhecido. Se o índice não puder ser determinado, este membro conterá AFX_CURRENT_RECORD_UNDEFINED (-2). Se IsBOF for TRUE (conjunto de registros vazio ou tentativa de rolagem antes do primeiro registro), então m_lCurrentRecord será definido como AFX_CURRENT_RECORD_BOF (-1). Se no primeiro registro, então é definido como 0, segundo registro 1 e assim por diante.

• m_bRecordCountFinal Diferente de zero se o número total de registros no conjunto de registros tiver sido determinado. Geralmente, isso deve ser feito começando no início do conjunto de registros e chamando MoveNext até retornar diferente IsEOF de zero. Se esse membro for zero, a contagem de registros retornada por GetRecordCount, se não -1, é apenas uma contagem de "marca d'água alta" dos registros.

CRecordset::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.

const CString& GetSQL() const;

Valor de retorno

Uma const referência a um CString que contém a instrução SQL.

Observações

Isso geralmente será uma instrução SQL SELECT . A cadeia de caracteres retornada por GetSQL é somente leitura.

A cadeia de caracteres retornada por GetSQL normalmente é diferente de qualquer cadeia de caracteres que você possa ter passado para o conjunto de registros no lpszSQL parâmetro para a Open função membro. Isso ocorre porque o conjunto de registros constrói uma instrução SQL completa com base no que você passou para Open, o que você especificou com ClassWizard, o que você pode ter especificado nos membros e m_strFilter dados e m_strSort quaisquer parâmetros que você possa ter especificado. Para obter detalhes sobre como o conjunto de registros constrói essa instrução SQL, consulte Recordset: How Recordsets Select Records (ODBC).

CRecordset::GetTableName

Obtém o nome da tabela SQL na qual a consulta do conjunto de registros se baseia.

const CString& GetTableName() const;

Valor de retorno

Uma const referência a um CString que contém o nome da tabela, se o conjunto de registros for baseado em uma tabela, caso contrário, uma cadeia de caracteres vazia.

Observações

GetTableName só é válido se o conjunto de registros for baseado em uma tabela, não uma junção de várias tabelas ou uma consulta predefinida (procedimento armazenado). O nome é somente leitura.

CRecordset::IsBOF

Retorna diferente de zero se o conjunto de registros tiver sido posicionado antes do primeiro registro. Não há registro atual.

BOOL IsBOF() const;

Valor de retorno

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

Observações

Chame essa função de membro antes de rolar de registro em registro para saber se você foi antes do primeiro registro do conjunto de registros. Você também pode usar IsBOF junto com IsEOF para determinar se o conjunto de registros contém algum registro ou está vazio. Imediatamente após a chamada 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á diferente de zero. Se IsBOF retornar diferente de zero e você chamar MovePrev, ocorrerá um erro. Se IsBOF retornar diferente de zero, o registro atual será indefinido e qualquer ação que exija um registro atual resultará em um erro.

Exemplo

Este exemplo usa IsBOF e IsEOF para detetar os limites de um conjunto de registros à medida que o código rola pelo conjunto de registros em ambas as direções.

// Open a recordset; first record is current
// Open a recordset; first record is current
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if(rsCustSet.IsBOF())
   return;
   // The recordset is empty

// Scroll to the end of the recordset, past
// the last record, so no record is current
while (!rsCustSet.IsEOF())
   rsCustSet.MoveNext();

// Move to the last record
rsCustSet.MoveLast();

// Scroll to beginning of the recordset, before
// the first record, so no record is current
while(!rsCustSet.IsBOF())
   rsCustSet.MovePrev();

// First record is current again
rsCustSet.MoveFirst();

CRecordset::IsDeleted

Determina 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, 0.

Observações

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

O resultado de depende de muitos fatores, como o tipo de conjunto de registros, se o conjunto de registros é atualizável, se você especificou a IsDeleted opção quando abriu o conjunto de registros, se os pacotes de CRecordset::skipDeletedRecords drivers excluíram registros e se há vários usuários.

Para obter mais informações sobre CRecordset::skipDeletedRecords o empacotamento de drivers, consulte a função Abrir membro.

CRecordset::IsEOF

Retorna diferente de zero se o conjunto de registros tiver sido posicionado após o último registro. Não há registro atual.

BOOL IsEOF() const;

Valor de retorno

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

Observações

Chame essa função de membro enquanto rola de registro em registro para saber se você foi além do último registro do conjunto de registros. Você também pode usar IsEOF para determinar se o conjunto de registros contém algum registro ou está vazio. Imediatamente após a chamada 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 quando você chamar MoveNext, IsEOF retornará diferente de zero. Se IsEOF retornar diferente de zero e você chamar MoveNext, ocorrerá um erro. Se IsEOF retornar diferente de zero, o registro atual será indefinido e qualquer ação que exija um registro atual resultará em um erro.

Exemplo

Veja o exemplo para IsBOF.

CRecordset::IsFieldDirty

Determina se o membro de dados de campo especificado foi alterado desde Edit ou AddNew foi chamado.

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 tiver sido alterado desde a chamada AddNew ou Edit; caso contrário 0.

Observações

Os dados em todos os membros de dados de campo sujo serão transferidos para o registro na fonte de dados quando o registro atual for atualizado por uma chamada para a Update função de membro de CRecordset (após uma chamada para Edit ou AddNew).

A chamada IsFieldDirty redefinirá os efeitos das chamadas anteriores para SetFieldDirty , uma vez que o status sujo do campo é reavaliado. AddNew No caso, se o valor do campo atual for diferente do valor pseudonulo, o status do campo será definido como sujo. Edit No caso, se o valor do campo for diferente do valor armazenado em cache, o status do campo será definido como sujo.

IsFieldDirty é implementado através do DoFieldExchange.

Para obter mais informações sobre o sinalizador sujo, consulte Recordset: How Recordsets Select Records (ODBC).

CRecordset::IsFieldNull

Retorna diferente de zero se o campo especificado no registro atual for Nulo (não tiver valor).

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 é Nulo.

Valor de retorno

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

Observações

Chame essa função de membro para determinar se o membro de dados de campo especificado de um conjunto de registros foi sinalizado como Nulo. (Na terminologia do banco de dados, Null significa "sem 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.

IsFieldNull é implementado através do DoFieldExchange.

CRecordset::IsFieldNullable

Retorna diferente de zero se o campo especificado no registro atual puder ser definido como Nulo (sem 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 pode ser definido como um valor Nulo.

Observações

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 "sem valor").

Um campo que não pode ser Nulo deve ter um valor. Se você tentar definir um campo como Nulo 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.

Usando NULL para o primeiro argumento da função irá aplicar a função apenas a campos, não outputColumn camposparam. Por exemplo, a chamada

SetFieldNull(NULL);

definirá apenas outputColumn campos como NULL; param os campos não serão afetados.

Para trabalhar em param campos, você deve fornecer o endereço real da pessoa param em que deseja trabalhar, como:

SetFieldNull(&m_strParam);

Isso significa que você não pode definir todos os campos como param, como acontece com NULL os outputColumn campos.

IsFieldNullable é implementado através do DoFieldExchange.

CRecordset::IsOpen

Determina se o conjunto de registros já está aberto.

BOOL IsOpen() const;

Valor de retorno

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

CRecordset::m_hstmt

Contém um identificador para a estrutura de dados da instrução ODBC, do tipo HSTMT, associada ao conjunto de registros.

Observações

Cada consulta a uma fonte de dados ODBC está associada a um HSTMTarquivo .

Normalmente, você não precisa acessar o diretamente, mas pode precisar dele para a HSTMT execução direta de instruções SQL. A ExecuteSQL função de membro da classe CDatabase fornece um exemplo de uso m_hstmtdo .

CRecordset::m_nFields

Contém o número de membros de dados de campo na classe recordset; ou seja, o número de colunas selecionadas pelo conjunto de registros da fonte de dados.

Observações

O construtor para a classe recordset deve inicializar m_nFields com o número correto. Se você não implementou a busca de linha em massa, ClassWizard grava essa inicialização para você quando usá-la para declarar sua classe de conjunto de registros. Você também pode escrevê-lo manualmente.

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

Você pode vincular colunas dinamicamente, conforme explicado no artigo "Recordset: Dynamically Binding Data Columns". Se você fizer isso, deverá aumentar a contagem para m_nFields refletir o número de chamadas de função RFX ou RFX em massa em sua DoFieldExchange função ou DoBulkFieldExchange membro para as colunas vinculadas dinamicamente.

Para obter mais informações, consulte os artigos Recordset: Dynamically Binding Data Columns (ODBC) e Recordset: Fetching Records in Bulk (ODBC).

Exemplo

consulte Record Field Exchange: Usando RFX.

CRecordset::m_nParams

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

Observações

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

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

Exemplo

Consulte os artigos Recordset: Parameterizing a Recordset (ODBC) e Record Field Exchange: Using RFX.

CRecordset::m_pDatabase

Contém um ponteiro para o objeto através do CDatabase qual o conjunto de registros está conectado a uma fonte de dados.

Observações

Esta variável é definida de duas maneiras. Normalmente, você passa um ponteiro para um objeto já conectado CDatabase quando constrói o objeto do conjunto de registros. Se você passar NULL em vez disso, CRecordset cria um CDatabase objeto para você e o conecta. Em ambos os casos, CRecordset armazena o ponteiro nessa variável.

Normalmente, você não precisará usar diretamente o ponteiro armazenado no m_pDatabase. Se você escrever suas próprias extensões para CRecordset, no entanto, talvez seja necessário usar o ponteiro. Por exemplo, você pode precisar do ponteiro se lançar o seu próprio CDBExceptions. Ou você pode precisar dele se precisar fazer algo usando o mesmo CDatabase objeto, como executar transações, definir tempos limite ou chamar a ExecuteSQL função de membro da classe CDatabase para executar instruções SQL diretamente.

CRecordset::m_strFilter

Depois de construir o objeto recordset, mas antes de chamar sua Open função de membro, use esse membro de dados para armazenar uma CString cláusula contendo WHERE SQL.

Observações

O conjunto de registros usa essa cadeia de caracteres para restringir (ou filtrar) os registros selecionados durante a Open chamada ou Requery . Isso é útil para selecionar um subconjunto de registros, como "todos os vendedores baseados na Califórnia" ("estado = CA"). A sintaxe ODBC SQL para uma WHERE cláusula é

WHERE search-condition

Não inclua a WHERE palavra-chave em sua cadeia de caracteres. O quadro fornece-o.

Você também pode parametrizar sua cadeia de caracteres de filtro colocando espaços reservados '' nela, declarando um membro de dados de parâmetro em sua classe para cada espaço reservado e passando parâmetros para o conjunto de registros em tempo de execução. Isso permite que você construa o filtro em tempo de execução. Para obter mais informações, consulte Recordset: parametrizando um conjunto de registros (ODBC).

Para obter mais informações sobre cláusulas SQLWHERE, consulte SQL. Para obter mais informações sobre como selecionar e filtrar registros, consulte Recordset: Filtering Records (ODBC).

Exemplo

CCustomer rsCustSet(&m_dbCust);

// Set the filter
rsCustSet.m_strFilter = _T("L_Name = 'Flanders'");

// Run the filtered query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::m_strSort

Depois de construir o objeto recordset, mas antes de chamar sua Open função de membro, use esse membro de dados para armazenar uma CString cláusula contendo ORDER BY SQL.

Observações

O conjunto de registros usa essa cadeia de caracteres para classificar os registros que seleciona durante a Open chamada ou Requery . Você pode usar esse recurso para classificar um conjunto de registros em uma ou mais colunas. A sintaxe ODBC SQL para uma ORDER BY cláusula é

ORDER BY sort-specification [, sort-specification]...

onde uma especificação de classificação é um número inteiro ou um nome de coluna. Você também pode especificar a ordem crescente ou decrescente (a ordem é crescente por padrão) acrescentando "ASC" ou "DESC" à lista de colunas na cadeia de classificação. Os registros selecionados são classificados primeiro pela primeira coluna listada, depois pela segunda e assim por diante. Por exemplo, você pode solicitar um conjunto de registros "Clientes" pelo sobrenome e, em seguida, pelo nome. O número de colunas que você pode listar depende da fonte de dados. Para obter mais informações, consulte o SDK do Windows.

Não inclua a ORDER BY palavra-chave em sua cadeia de caracteres. O quadro fornece-o.

Para obter mais informações sobre cláusulas SQL, consulte SQL. Para obter mais informações sobre como classificar registros, consulte Recordset: Sorting Records (ODBC).

Exemplo

CCustomer rsCustSet(&m_dbCust);

// Set the sort string
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");

// Run the sorted query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::Move

Move o ponteiro do registro atual dentro do conjunto de registros, para frente ou para trás.

virtual void Move(
    long nRows,
    WORD wFetchType = SQL_FETCH_RELATIVE);

Parâmetros

nRows
O número de linhas para avançar ou retroceder. Os valores positivos avançam, no final do conjunto de registros. Os valores negativos andam para trás, para o início.

wFetchType
Determina o conjunto de linhas que Move será buscado. Para obter detalhes, consulte Observações.

Observações

Se você passar um valor de 0 para nRows, Move atualiza o registro atual, Move encerrará qualquer corrente AddNew ou Edit modo e restaurará o valor do registro atual anterior AddNew ou Edit chamado.

Move Reposiciona o conjunto de registros por conjuntos de linhas. Com base nos valores de nRows e wFetchType, Move obtém o conjunto de linhas apropriado e, em seguida, torna o primeiro registro nesse conjunto de linhas o registro atual. Se você não implementou a busca de linha em massa, o tamanho do conjunto de linhas é sempre 1. Ao buscar um conjunto de linhas, Move chama diretamente a CheckRowsetError função de membro para lidar com quaisquer erros resultantes da busca.

Dependendo dos valores que você passar, Move é equivalente a outras CRecordset funções de membro. Em particular, o valor de pode indicar uma função de wFetchType membro que é mais intuitiva e muitas vezes o método preferido para mover o registro atual.

A tabela a seguir lista os valores possíveis para wFetchType, o conjunto de linhas que Move será buscado com base em wFetchType e nRows, e qualquer função de membro equivalente correspondente a wFetchType.

Para obter mais informações sobre a navegação do conjunto de registros, consulte os artigos Recordset: Scrolling (ODBC) e Recordset: Bookmarks and Absolute Positions (ODBC). Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC). Para obter informações relacionadas, consulte a função SQLExtendedFetch de API ODBC no SDK do Windows.

Exemplo

// rs is a CRecordset or a CRecordset-derived object

// Change the rowset size to 5
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// Move to the first record in the recordset
rs.MoveFirst();

// Move to the sixth record
rs.Move(5);
// Other equivalent ways to move to the sixth record:
rs.Move(6, SQL_FETCH_ABSOLUTE);
rs.SetAbsolutePosition(6);
// In this case, the sixth record is the first record in the next rowset,
// so the following are also equivalent:
rs.MoveFirst();
rs.Move(1, SQL_FETCH_NEXT);

rs.MoveFirst();
rs.MoveNext();

CRecordset::MoveFirst

Torna o primeiro registro no primeiro conjunto de linhas o registro atual.

void MoveFirst();

Observações

Independentemente de a busca de linha em massa ter sido implementada, esse sempre será o primeiro registro no conjunto de registros.

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

Para obter mais informações sobre a navegação do conjunto de registros, consulte os artigos Recordset: Scrolling (ODBC) e Recordset: Bookmarks and Absolute Positions (ODBC). Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

Exemplo

Veja o exemplo para IsBOF.

CRecordset::MoveLast

Torna o primeiro registro no último conjunto de linhas completo o registro atual.

void MoveLast();

Observações

Se você não implementou a busca de linha em massa, seu conjunto de registros tem um tamanho de conjunto de linhas de 1, portanto MoveLast , passa para o último registro no conjunto de registros.

Para obter mais informações sobre a navegação do conjunto de registros, consulte os artigos Recordset: Scrolling (ODBC) e Recordset: Bookmarks and Absolute Positions (ODBC). Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

Exemplo

Veja o exemplo para IsBOF.

CRecordset::MoveNext

Torna o primeiro registro no próximo conjunto de linhas o registro atual.

void MoveNext();

Observações

Se você não implementou a busca de linha em massa, seu conjunto de registros tem um tamanho de conjunto de linhas de 1, portanto MoveNext , passa para o próximo registro.

Para obter mais informações sobre a navegação do conjunto de registros, consulte os artigos Recordset: Scrolling (ODBC) e Recordset: Bookmarks and Absolute Positions (ODBC). Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

Exemplo

Veja o exemplo para IsBOF.

CRecordset::MovePrev

Torna o primeiro registro no conjunto de linhas anterior o registro atual.

void MovePrev();

Observações

Se você não implementou a busca de linha em massa, seu conjunto de registros tem um tamanho de conjunto de linhas de 1, portanto MovePrev , é movido para o registro anterior.

Para obter mais informações sobre a navegação do conjunto de registros, consulte os artigos Recordset: Scrolling (ODBC) e Recordset: Bookmarks and Absolute Positions (ODBC). Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

Exemplo

Veja o exemplo para IsBOF.

CRecordset::OnSetOptions

Chamado para definir opções (usadas na seleção) para a instrução ODBC especificada.

virtual void OnSetOptions(HSTMT hstmt);

Parâmetros

hstmt
O HSTMT da instrução ODBC cujas opções devem ser definidas.

Observações

Chamada OnSetOptions para definir opções (usadas na seleção) para a instrução ODBC especificada. A estrutura chama essa função de membro para definir opções iniciais para o conjunto de registros. OnSetOptions determina o suporte da fonte de dados para cursores roláveis e simultaneidade de cursor e define as opções do conjunto de registros de acordo. (Enquanto OnSetOptions é usado para operações de seleção, OnSetUpdateOptions é usado para operações de atualização.)

Substituir OnSetOptions para definir opções específicas para o driver ou a fonte de dados. Por exemplo, se sua fonte de dados oferecer suporte à abertura para acesso exclusivo, você poderá substituir OnSetOptions para aproveitar essa capacidade.

Para obter mais informações sobre cursores, consulte ODBC.

CRecordset::OnSetUpdateOptions

Chamado para definir opções (usadas na atualização) para a instrução ODBC especificada.

virtual void OnSetUpdateOptions(HSTMT hstmt);

Parâmetros

hstmt
O HSTMT da instrução ODBC cujas opções devem ser definidas.

Observações

Chamada OnSetUpdateOptions para definir opções (usadas na atualização) para a instrução ODBC especificada. A estrutura chama essa função de membro depois que ela cria um HSTMT para atualizar registros em um conjunto de registros. (Considerando que OnSetOptions é usado para operações de seleção, OnSetUpdateOptions é usado para operações de atualização.) OnSetUpdateOptions determina o suporte da fonte de dados para cursores roláveis e para simultaneidade de cursor e define as opções do conjunto de registros de acordo.

Substitua OnSetUpdateOptions para definir opções de uma instrução ODBC antes que essa instrução seja usada para acessar um banco de dados.

Para obter mais informações sobre cursores, consulte ODBC.

CRecordset::Open

Abre o conjunto de registros recuperando a tabela ou executando a consulta que o conjunto de registros representa.

virtual BOOL Open(
    UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE,
    LPCTSTR lpszSQL = NULL,
    DWORD dwOptions = none);

Parâmetros

nOpenType
Aceite o valor AFX_DB_USE_DEFAULT_TYPEpadrão ou use um dos seguintes valores do enum OpenType:

• CRecordset::dynaset Um conjunto de registros com rolagem bidirecional. A abertura do conjunto de registros determina a associação e a ordem dos registros, mas as alterações feitas por outros usuários nos valores de dados são visíveis após uma operação de busca. Os dynasets também são conhecidos como conjuntos de registros orientados por conjuntos de chaves.

• CRecordset::snapshot Um conjunto de registros estático com rolagem bidirecional. A abertura do conjunto de registros determina a associação e a ordem dos registros. A obtenção de um registo determina os valores dos dados. As alterações feitas por outros usuários não ficam visíveis até que o conjunto de registros seja fechado e, em seguida, reaberto.

• CRecordset::dynamic Um conjunto de registros com rolagem bidirecional. As alterações feitas por outros usuários nos valores de associação, ordem e dados são visíveis após uma operação de busca. Muitos drivers ODBC não suportam esse tipo de conjunto de registros.

• CRecordset::forwardOnly Um conjunto de registros somente leitura com apenas rolagem para frente.

  Para CRecordset, o valor padrão é CRecordset::snapshot. O mecanismo de valor padrão permite que os assistentes do Visual C++ interajam com ODBC CRecordset e DAO CDaoRecordset, que têm padrões diferentes.

Para obter mais informações sobre esses tipos de conjuntos de registros, consulte Recordset (ODBC). Para obter informações relacionadas, consulte "Usando cursores de bloco e roláveis" no SDK do Windows.

lpszSQL
Um ponteiro de cadeia de caracteres contendo um dos seguintes:

• Um NULL ponteiro.

• O nome de uma tabela.

• Uma instrução SQL SELECT (opcionalmente com um SQL WHERE ou ORDER BY cláusula).

• Uma CALL instrução especificando o nome de uma consulta predefinida (procedimento armazenado). Tenha cuidado para não inserir espaço em branco entre a cinta encaracolada e a CALL palavra-chave.

Para obter mais informações sobre essa cadeia de caracteres, consulte a tabela e a discussão da função do ClassWizard na seção Comentários .

dwOptions
Uma máscara de bits, que pode especificar uma combinação dos valores listados abaixo. Algumas delas excluem-se mutuamente. O valor predefinido é none.

• CRecordset::none Nenhuma opção definida. Este valor de parâmetro é mutuamente exclusivo com todos os outros valores. Por padrão, o conjunto de registros pode ser atualizado com Edit ou Delete e permite anexar novos registros com AddNew. Updatability depende da fonte de dados e da nOpenType opção que você especificar. A otimização para adições em massa não está disponível. A busca de linhas em massa não será implementada. Os registros excluídos não serão ignorados durante a navegação do conjunto de registros. Os favoritos não estão disponíveis. A verificação automática de campo sujo é implementada.

• CRecordset::appendOnly Não permita Edit ou Delete no conjunto de registros. Permitir AddNew apenas. Esta opção exclui-se mutuamente com CRecordset::readOnlyo .

• CRecordset::readOnly Abra o conjunto de registros como somente leitura. Esta opção exclui-se mutuamente com CRecordset::appendOnlyo .

• CRecordset::optimizeBulkAdd Use uma instrução SQL preparada para otimizar a adição de muitos registros ao mesmo tempo. Aplica-se somente se você não estiver usando a função SQLSetPos de API ODBC para atualizar o conjunto de registros. A primeira atualização determina quais campos estão marcados como sujos. Esta opção exclui-se mutuamente com CRecordset::useMultiRowFetcho .

• CRecordset::useMultiRowFetch Implemente a busca de linha em massa para permitir que várias linhas sejam recuperadas em uma única operação de busca. Este é um recurso avançado projetado para melhorar o desempenho; No entanto, a troca de campo de registro em massa não é suportada pelo ClassWizard. Esta opção exclui-se mutuamente com CRecordset::optimizeBulkAddo . Se você especificar CRecordset::useMultiRowFetch, a opção CRecordset::noDirtyFieldCheck será ativada automaticamente (buffer duplo não estará disponível); em conjuntos de registros somente para encaminhamento, a opção CRecordset::useExtendedFetch será ativada automaticamente. Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

• CRecordset::skipDeletedRecords Ignore todos os registros excluídos ao navegar pelo conjunto de registros. Isso diminuirá o desempenho em certas buscas relativas. Essa opção não é válida em conjuntos de registros somente para encaminhamento. Se você chamar Move com o parâmetro nRows definido como 0, e o CRecordset::skipDeletedRecords conjunto de opções, Move afirmará. CRecordset::skipDeletedRecords é semelhante ao empacotamento de driver, o que significa que as linhas excluídas são removidas do conjunto de registros. No entanto, se o driver embalar registros, ele ignorará apenas os registros que você excluir; Ele não ignorará registros excluídos por outros usuários enquanto o conjunto de registros estiver aberto. CRecordset::skipDeletedRecords irá saltar linhas eliminadas por outros utilizadores.

• CRecordset::useBookmarks Pode usar marcadores no conjunto de registros, se suportado. Marca a recuperação lenta de dados, mas melhora o desempenho da navegação de dados. Não é válido em conjuntos de registros somente para encaminhamento. Para obter mais informações, consulte Recordset: Bookmarks and Absolute Positions (ODBC).

• CRecordset::noDirtyFieldCheck Desative a verificação automática de campo sujo (buffer duplo). Isto melhorará o desempenho; no entanto, você deve marcar manualmente os campos como sujos chamando as SetFieldDirty funções e SetFieldNull membro. O buffer duplo na classe CRecordset é semelhante ao buffer duplo na classe CDaoRecordset. No entanto, no CRecordset, você não pode habilitar o buffer duplo em campos individuais, basta habilitá-lo para todos os campos ou desativá-lo para todos os campos. Se você especificar a opção CRecordset::useMultiRowFetch, ela CRecordset::noDirtyFieldCheck será ativada automaticamente SetFieldDirty e SetFieldNull não poderá ser usada em conjuntos de registros que implementam a busca de linhas em massa.

• CRecordset::executeDirect Não use uma instrução SQL preparada. Para melhorar o desempenho, especifique esta opção se a Requery função de membro nunca será chamada.

• CRecordset::useExtendedFetch Implementar SQLExtendedFetch em vez de SQLFetch. Isso foi projetado para implementar a busca de linha em massa em conjuntos de registros somente para encaminhamento. Se você especificar a opção CRecordset::useMultiRowFetch em um conjunto de registros somente para encaminhamento, será CRecordset::useExtendedFetch ativado automaticamente.

• CRecordset::userAllocMultiRowBuffers O usuário alocará buffers de armazenamento para os dados. Use esta opção com CRecordset::useMultiRowFetch se quiser alocar seu próprio armazenamento. Caso contrário, a estrutura alocará automaticamente o armazenamento necessário. Para obter mais informações, consulte Recordset: Buscando registros em massa (ODBC). Especificar CRecordset::userAllocMultiRowBuffers sem especificar CRecordset::useMultiRowFetch resulta em uma asserção com falha.

Valor de retorno

Diferente de zero se o CRecordset objeto foi aberto com êxito, caso contrário, 0 se CDatabase::Open (se chamado) retorna 0.

Observações

Você deve chamar essa função de membro para executar a consulta definida pelo conjunto de registros. Antes de chamar Open, você deve construir o objeto recordset.

A conexão desse conjunto de registros com a fonte de dados depende de como você constrói o conjunto de registros antes de chamar Open. Se você passar um CDatabase objeto para o construtor do conjunto de registros que não foi conectado à fonte de dados, essa função de membro será usada GetDefaultConnect para tentar abrir o objeto de banco de dados. Se você passar NULL para o construtor do conjunto de registros, o construtor construirá um CDatabase objeto para você e Open tentará conectar o objeto de banco de dados. Para obter detalhes sobre como fechar o conjunto de registros e a conexão nessas circunstâncias variáveis, consulte Close.

Quando você chama Openo , uma consulta, geralmente uma instrução SQL SELECT , seleciona registros com base nos critérios mostrados na tabela a seguir.

O procedimento usual é passar NULL para Open, neste caso, Open chama GetDefaultSQL. Se você estiver usando uma classe derivada CRecordset , GetDefaultSQL forneça o(s) nome(s) da tabela especificado(s) em ClassWizard. Em vez disso, você pode especificar outras informações no lpszSQL parâmetro.

Seja o que for que você passar, constrói uma cadeia de caracteres SQL final para a consulta (a cadeia de caracteres pode ter SQL Open e WHERE cláusulas anexadas à ORDER BY cadeia de caracteres que você passou) e, em seguida, lpszSQL executa a consulta. Você pode examinar a cadeia de caracteres construída chamando depois de GetSQL chamar Open. Para obter mais detalhes sobre como o conjunto de registros constrói uma instrução SQL e seleciona registros, consulte Recordset: How Recordsets Select Records (ODBC).

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

Se desejar definir opções para o conjunto de registros, como um filtro ou classificação, especifique-as depois de construir o objeto do conjunto de registros, mas antes de chamar Open. Se desejar atualizar os registros no conjunto de registros depois que o conjunto de registros já estiver aberto, chame Requery.

Para obter mais informações, incluindo mais exemplos, consulte Recordset (ODBC),Recordset: How Recordsets Select Records (ODBC) e Recordset: Creating and Closing Recordsets (ODBC).

Exemplo

Os exemplos de código a seguir mostram diferentes formas da Open chamada.

// rsSnap, rsLName, and rsDefault are CRecordset or CRecordset-derived 
// objects

// Open rs using the default SQL statement, implement bookmarks, and turn 
// off automatic dirty field checking
rsSnap.Open(CRecordset::snapshot, NULL, CRecordset::useBookmarks |
   CRecordset::noDirtyFieldCheck);

// Pass a complete SELECT statement and open as a dynaset
rsLName.Open(CRecordset::dynaset, _T("Select L_Name from Customer"));

// Accept all defaults
rsDefault.Open();

CRecordset::RefreshRowset

Atualiza os dados e o status de uma linha no conjunto de linhas atual.

void RefreshRowset(
    WORD wRow,
    WORD wLockType = SQL_LOCK_NO_CHANGE);

Parâmetros

wRow
A posição baseada em uma linha no conjunto de linhas atual. Esse valor pode variar de zero ao tamanho do conjunto de linhas.

wLockType
Um valor que indica como bloquear a linha depois de ter sido atualizada. Para obter detalhes, consulte Observações.

Observações

Se você passar um valor de zero para wRow, todas as linhas do conjunto de linhas serão atualizadas.

Para usar RefreshRowseto CRecordset::useMulitRowFetch , você deve ter implementado a busca de linha em massa especificando a Open opção na função de membro.

RefreshRowset chama a função SQLSetPosde API ODBC . O wLockType parâmetro especifica o estado de bloqueio da linha após SQLSetPos a execução. A tabela a seguir descreve os valores possíveis para wLockType.

Para obter mais informações sobre SQLSetPoso , consulte o SDK do Windows. Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

CRecordset::Requery

Recria (atualiza) um conjunto de registros.

virtual BOOL Requery();

Valor de retorno

Diferente de zero se o conjunto de registros foi reconstruído com êxito; caso contrário, 0.

Observações

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 na fonte de dados, você deve reconstruir 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 fizerem 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 feitas por outros usuários e adições e exclusões.

Para um dynaset ou um snapshot, ligue Requery sempre que quiser reconstruir o conjunto de registros usando um novo filtro ou classificação, ou novos valores de parâmetro. Defina a nova propriedade de filtro ou classificação atribuindo novos valores a m_strFilter e m_strSort antes de chamar Requery. Defina novos parâmetros atribuindo novos valores aos membros de dados de parâmetros antes de chamar Requery. Se as cadeias de caracteres de filtro e classificação não forem alteradas, você poderá reutilizar a consulta, o que melhora o desempenho.

Se a tentativa de reconstruir o conjunto de registros falhar, o conjunto de registros será fechado. Antes de chamar Requeryo , você pode determinar se o conjunto de registros pode ser consultado novamente chamando a CanRestart função de membro. CanRestart não garante que Requery terá sucesso.

Exemplo

Este exemplo recria um conjunto de registros para aplicar uma ordem de classificação diferente.

CCustomer rsCustSet(&m_dbCust);

// Open the recordset
rsCustSet.Open();

// Use the recordset ...

// Set the sort order and Requery the recordset
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");
if (!rsCustSet.CanRestart())
return;    // Unable to requery

if (!rsCustSet.Requery())
// Requery failed, so take action
AfxMessageBox(_T("Requery failed!"));

CRecordset::SetAbsolutePosition

Posiciona o conjunto de registros no registro correspondente ao número de registro especificado.

void SetAbsolutePosition(long nRows);

Parâmetros

nRows
A posição ordinal baseada em um para o registro atual no conjunto de registros.

Observações

SetAbsolutePosition Move o ponteiro do registro atual com base nessa posição ordinal.

Para conjuntos de registros ODBC, uma configuração de posição absoluta de 1 refere-se ao primeiro registro no conjunto de registros; uma configuração de 0 refere-se à posição de início de arquivo (BOF).

Você também pode passar valores negativos para SetAbsolutePosition. Nesse caso, a posição do conjunto de registros é avaliada a partir do final do conjunto de registros. Por exemplo, SetAbsolutePosition( -1 ) move o ponteiro do registro atual para o último registro no conjunto de registros.

Para obter mais informações sobre navegação e marcadores do conjunto de registros, consulte os artigos Recordset: Scrolling (ODBC) e Recordset: Bookmarks and Absolute Positions (ODBC).

CRecordset::SetBookmark

Posiciona o conjunto de registros no registro que contém o marcador especificado.

void SetBookmark(const CDBVariant& varBookmark);

Parâmetros

varBookmark
Uma referência a um CDBVariant objeto que contém o valor do indicador para um registro específico.

Observações

Para determinar se os marcadores são suportados no conjunto de registros, chame CanBookmark. Para disponibilizar favoritos, se eles forem suportados, você deve definir a CRecordset::useBookmarks opção no dwOptions parâmetro da função de Open membro.

Para recuperar primeiro o indicador do registro atual, chame GetBookmark, que salva o valor do indicador em um CDBVariant objeto. Mais tarde, você pode retornar a esse registro chamando SetBookmark usando o valor de marcador salvo.

Para obter mais informações sobre marcadores e navegação no conjunto de registros, consulte os artigos Recordset: Bookmarks and Absolute Positions (ODBC) e Recordset: Scrolling (ODBC).

CRecordset::SetFieldDirty

Sinaliza 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 NULL, todos os membros de dados de campo no conjunto de registros forem sinalizados. (C++ NULL não é o mesmo que Null na terminologia do banco de dados, o que significa "sem 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 deve ser sinalizado como "limpo" (inalterado).

Observações

Marcar campos como inalterados garante que o campo não seja atualizado e resulte em menos tráfego SQL.

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 campos de registro (RFX). Alterar o valor de um campo geralmente define o campo sujo automaticamente, portanto, você raramente precisará chamar SetFieldDirty a si mesmo, mas às vezes convém garantir que as colunas sejam explicitamente atualizadas ou inseridas, independentemente do valor no membro de dados do campo.

Usando NULL para o primeiro argumento da função irá aplicar a função apenas a campos, não outputColumn camposparam. Por exemplo, a chamada

SetFieldNull(NULL);

definirá apenas outputColumn campos como NULL; param os campos não serão afetados.

Para trabalhar em param campos, você deve fornecer o endereço real da pessoa param em que deseja trabalhar, como:

SetFieldNull(&m_strParam);

Isso significa que você não pode definir todos os campos como param, como acontece com NULL os outputColumn campos.

CRecordset::SetFieldNull

Sinaliza um membro de dados de campo do conjunto de registros como Nulo (especificamente sem valor) ou como não Nulo.

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 NULL, todos os membros de dados de campo no conjunto de registros forem sinalizados. (C++ NULL não é o mesmo que Null na terminologia do banco de dados, o que significa "sem valor.")

bNull
Diferente de zero se o membro de dados de campo deve ser sinalizado como não tendo valor (Nulo). Caso contrário, 0 se o membro de dados de campo deve ser sinalizado como não-Nulo.

Observações

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 "sujo" (alterado). Quando você recupera um registro de uma fonte de dados, suas colunas já têm valores ou são Nulas.

Se você desejar especificamente designar um campo do registro atual como não tendo um valor, chame SetFieldNull com bNull set para TRUE sinalizá-lo como Nulo. Se um campo foi marcado anteriormente como Nulo e agora você deseja dar a ele um valor, defina seu novo valor. Não é necessário remover o sinalizador Nulo com SetFieldNull. Para determinar se o campo pode ser Nulo, chame IsFieldNullable.

Usando NULL para o primeiro argumento da função irá aplicar a função apenas a campos, não outputColumn camposparam. Por exemplo, a chamada

SetFieldNull(NULL);

definirá apenas outputColumn campos como NULL; param os campos não serão afetados.

Para trabalhar em param campos, você deve fornecer o endereço real da pessoa param em que deseja trabalhar, como:

SetFieldNull(&m_strParam);

Isso significa que você não pode definir todos os campos como param, como acontece com NULL os outputColumn campos.

SetFieldNull é implementado através do DoFieldExchange.

CRecordset::SetLockingMode

Define o modo de bloqueio como bloqueio "otimista" (o padrão) ou "pessimista". Determina como os registros são bloqueados para atualizações.

void SetLockingMode(UINT nMode);

Parâmetros

nMode
Contém um dos seguintes valores do enum LockMode:

• optimistic O bloqueio otimista bloqueia o registro que está sendo atualizado somente durante a chamada para Update.

• pessimistic O bloqueio pessimista bloqueia o registro assim que Edit é chamado e o mantém bloqueado até que a Update chamada seja concluída ou você mude para um novo registro.

Observações

Chame essa função de membro se precisar especificar qual das duas estratégias de bloqueio de registro o conjunto de registros está usando para atualizações. Por padrão, o modo de bloqueio de um conjunto de registros é optimistic. Você pode mudar isso para uma estratégia de bloqueio mais cautelosa pessimistic . Ligue SetLockingMode depois de construir e abrir o objeto do conjunto de registros, mas antes de chamar Edit.

CRecordset::SetParamNull

Sinaliza um parâmetro como Null (especificamente sem valor) ou como non-Null.

void SetParamNull(
    int nIndex,
    BOOL bNull = TRUE);

Parâmetros

nIndex
O índice baseado em zero do parâmetro.

bNull
Se TRUE (o valor padrão), o parâmetro é sinalizado como Null. Caso contrário, o parâmetro será sinalizado como não-Nulo.

Observações

Ao contrário SetFieldNulldo , você pode ligar SetParamNull antes de abrir o conjunto de registros.

SetParamNull é normalmente usado com consultas predefinidas (procedimentos armazenados).

CRecordset::SetRowsetCursorPosition

Move o cursor para uma linha dentro do conjunto de linhas atual.

void SetRowsetCursorPosition(WORD wRow, WORD wLockType = SQL_LOCK_NO_CHANGE);

Parâmetros

wRow
A posição baseada em uma linha no conjunto de linhas atual. Esse valor pode variar de 1 até o tamanho do conjunto de linhas.

wLockType
Valor que indica como bloquear a linha depois de ter sido atualizada. Para obter detalhes, consulte Observações.

Observações

Ao implementar a busca de linha em massa, os registros são recuperados por conjuntos de linhas, onde o primeiro registro no conjunto de linhas buscado é o registro atual. Para fazer outro registro dentro do conjunto de linhas o registro atual, chame SetRowsetCursorPosition. Por exemplo, você pode combinar SetRowsetCursorPosition com a GetFieldValue função de membro para recuperar dinamicamente os dados de qualquer registro do seu conjunto de registros.

Para usar SetRowsetCursorPositiono , você deve ter implementado a busca de linha em massa especificando a CRecordset::useMultiRowFetchdwOptions opção do parâmetro na Open função membro.

SetRowsetCursorPosition chama a função SQLSetPosde API ODBC . O wLockType parâmetro especifica o estado de bloqueio da linha após SQLSetPos a execução. A tabela a seguir descreve os valores possíveis para wLockType.

Para obter mais informações sobre SQLSetPoso , consulte o SDK do Windows. Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

CRecordset::SetRowsetSize

Especifica o número de registros que você deseja recuperar durante uma busca.

virtual void SetRowsetSize(DWORD dwNewRowsetSize);

Parâmetros

dwNewRowsetSize
O número de linhas a serem recuperadas durante uma determinada busca.

Observações

Essa função de membro virtual especifica quantas linhas você deseja recuperar durante uma única busca ao usar a busca de linha em massa. Para implementar a CRecordset::useMultiRowFetch busca de linha em massa, você deve definir a dwOptions opção no parâmetro da função membroOpen.

Ligue SetRowsetSize antes de ligar Open para definir inicialmente o tamanho do conjunto de linhas para o conjunto de registros. O tamanho padrão do conjunto de linhas ao implementar a busca de linhas em massa é 25.

Para obter a configuração atual para o tamanho do conjunto de linhas, chame GetRowsetSize.

Para obter mais informações sobre a busca de linhas em massa, consulte Recordset: Buscando registros em massa (ODBC).

CRecordset::Update

Conclui uma AddNew operação ou Edit salvando os dados novos ou editados na fonte de dados.

virtual BOOL Update();

Valor de retorno

Diferente de zero se um registro foi atualizado com êxito; caso contrário, 0 se nenhuma coluna tiver sido alterada. Se nenhum registro tiver sido atualizado ou se mais de um registro tiver sido atualizado, uma exceção será lançada. Uma exceção também é lançada para qualquer outra falha na fonte de dados.

Observações

Chame essa função de membro após uma chamada para a AddNew função ou Edit membro. Esta chamada é necessária para concluir a AddNew operação ou Edit .

Ambos AddNew e Edit preparar 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. Apenas os campos marcados ou detetados como alterados são atualizados.

Se a fonte de dados oferecer suporte a transações, você poderá tornar a Update chamada (e sua correspondente AddNew ou Edit chamada) parte de uma transação. Para obter mais informações sobre transações, consulte Transação (ODBC).

Para obter detalhes sobre como lidar com Update falhas, consulte Recordset: How Recordsets Update Records (ODBC).

Exemplo

consulte Transação: Executando uma transação em um conjunto de registros (ODBC).

Ver também

Classe CObject
Gráfico hierárquico
Classe CDatabase
Classe CRecordView