Clase CDatabase

Representa una conexión a un origen de datos, a través de la que puede trabajar con el origen de datos.

Sintaxis

class CDatabase : public CObject

Miembros

Constructores públicos

Nombre	Descripción
CDatabase::CDatabase	Construye un objeto CDatabase. Debe inicializar el objeto llamando a OpenEx u Open.

Métodos públicos

Nombre	Descripción
CDatabase::BeginTrans	Inicia una "transacción" (una serie de llamadas reversibles a las funciones miembro AddNew, Edit, Delete y Update de la clase CRecordset ) en el origen de datos conectado. El origen de datos debe admitir transacciones para que BeginTrans tenga efecto.
CDatabase::BindParameters	Permite enlazar parámetros antes de llamar a CDatabase::ExecuteSQL.
CDatabase::Cancel	Cancela una operación asincrónica o un proceso de un segundo subproceso.
CDatabase::CanTransact	Devuelve un valor distinto de cero si el origen de datos admite transacciones.
CDatabase::CanUpdate	Devuelve un valor distinto de cero si el objeto CDatabase se puede actualizar (no es de solo lectura).
CDatabase::Close	Cierra la conexión con el origen de datos.
CDatabase::CommitTrans	Completa una transacción iniciada por BeginTrans. Se llevan a cabo los comandos de la transacción que modifican el origen de datos.
CDatabase::ExecuteSQL	Ejecuta una instrucción SQL. No se devuelven registros de datos.
CDatabase::GetBookmarkPersistence	Identifica las operaciones en las que los marcadores son persistentes en los objetos de conjunto de registros.
CDatabase::GetConnect	Devuelve la cadena de conexión ODBC usada para conectar el objeto CDatabase a un origen de datos.
CDatabase::GetCursorCommitBehavior	Identifica el efecto de confirmar una transacción en un objeto de conjunto de registros abierto.
CDatabase::GetCursorRollbackBehavior	Identifica el efecto de revertir una transacción en un objeto de conjunto de registros abierto.
CDatabase::GetDatabaseName	Devuelve el nombre de la base de datos en uso actualmente.
CDatabase::IsOpen	Devuelve un valor distinto de cero si el objeto CDatabase está conectado actualmente a un origen de datos.
CDatabase::OnSetOptions	Lo llama el marco de trabajo para establecer las opciones de conexión estándar. La implementación predeterminada establece el valor de tiempo de espera de las consultas. Puede establecer estas opciones con antelación llamando a SetQueryTimeout.
CDatabase::Open	Establece una conexión a un origen de datos (mediante un controlador ODBC).
CDatabase::OpenEx	Establece una conexión a un origen de datos (mediante un controlador ODBC).
CDatabase::Rollback	Invierte los cambios realizados durante la transacción actual. El origen de datos vuelve a su estado anterior, tal y como se define en la llamada a BeginTrans, sin modificar.
CDatabase::SetLoginTimeout	Establece el número de segundos después del cual se agotará el tiempo de espera de un intento de conexión al origen de datos.
CDatabase::SetQueryTimeout	Establece el número de segundos después de los cuales se agotará el tiempo de espera de las operaciones de consulta de base de datos. Afecta a todas las llamadas posteriores a Open, AddNew, Edit y Delete del conjunto de registros.

Miembros de datos públicos

Nombre	Descripción
CDatabase::m_hdbc	Manipulador de la conexión de conectividad abierta de bases de datos (ODBC) a un origen de datos. Tipo HDBC.

Comentarios

Un origen de datos es una instancia específica de los datos hospedados por algún sistema de administración de bases de datos (DBMS). Entre los ejemplos, se incluyen Microsoft SQL Server, Microsoft Access, Borland dBASE y xBASE. Puede tener uno o varios objetos CDatabase activos a la vez en la aplicación.

Nota:

Si está trabajando con las clases de Objetos de acceso a datos (DAO) en lugar de las clases de Conectividad abierta de bases de datos (ODBC), use la clase CDaoDatabase en su lugar. Para más información, consulte el artículo Información general: programación de bases de datos.

Para usar CDatabase, construya un objeto CDatabase y llame a su función miembro OpenEx. Esto abre una conexión. Después, al construir objetos CRecordset para operar en el origen de datos conectado, pase al constructor del conjunto de registros un puntero al objeto CDatabase. Cuando termine de usar la conexión, llame a la función miembro Close y destruya el objeto CDatabase. Close cierra los conjuntos de registros que no se hayan cerrado anteriormente.

Para obtener más información sobre CDatabase, consulte los artículos Origen de datos (ODBC) y Programación del acceso a datos (MFC/ATL).

Jerarquía de herencia

CObject

CDatabase

Requisitos

Encabezado: afxdb.h

CDatabase::BeginTrans

Llame a esta función miembro para iniciar una transacción con el origen de datos conectado.

BOOL BeginTrans();

Valor devuelto

Distinto de cero si la llamada se realizó correctamente y los cambios solo se confirman manualmente; de lo contrario, 0.

Comentarios

Una transacción consta de una o varias llamadas a las funciones miembro AddNew, Edit, Delete y Update de un objeto CRecordset. Antes de comenzar una transacción, el objeto CDatabase ya se debe haber conectado al origen de datos mediante una llamada a su función miembro OpenEx o Open. Para finalizar la transacción, llame a CommitTrans para aceptar todos los cambios en el origen de datos (y llevarlos a cabo) o llame a Rollback para anular toda la transacción. Llame a BeginTrans después de abrir los conjuntos de registros implicados en la transacción y lo más cerca posible de las operaciones de actualización reales.

Precaución

En función del controlador ODBC, abrir un conjunto de registros antes de llamar a BeginTrans puede causar problemas al llamar a Rollback. Debe comprobar el controlador específico que usa. Por ejemplo, al usar el controlador de Microsoft Access incluido en Microsoft ODBC Desktop Driver Pack 3.0, debe tener en cuenta el requisito del motor de base de datos Jet de no iniciar una transacción en ninguna base de datos que tenga un cursor abierto. En las clases de base de datos de MFC, un cursor abierto significa un objeto CRecordset abierto. Para obtener más información, consulte la Nota técnica 68.

BeginTrans también puede bloquear los registros de datos en el servidor, en función de la simultaneidad solicitada y de las funcionalidades del origen de datos. Para obtener información sobre el bloqueo de datos, consulte el artículo Conjunto de registros: bloqueo de registros (ODBC).

Las transacciones definidas por el usuario se explican en el artículo Transacción (ODBC).

BeginTrans establece el estado en el que se puede revertir la secuencia de transacciones (invertida). Para establecer un nuevo estado para las reversiones, confirme cualquier transacción actual y vuelva a llamar a BeginTrans.

Precaución

Es un error llamar de nuevo a BeginTrans sin llamar a CommitTrans o Rollback.

Llame a la función miembro CanTransact para determinar si el controlador admite transacciones para una base de datos determinada. También debe llamar a GetCursorCommitBehavior y GetCursorRollbackBehavior para determinar la compatibilidad con la conservación del cursor.

Para obtener más información sobre las transacciones, consulte el artículo Transacción (ODBC).

Ejemplo

Consulte el artículo Transacción: realizar una transacción en un conjunto de registros (ODBC).

CDatabase::BindParameters

Invalide BindParameters cuando necesite enlazar parámetros antes de llamar a CDatabase::ExecuteSQL.

virtual void BindParameters(HSTMT hstmt);

Parámetros

hstmt
Manipulador de instrucción ODBC para el que desea enlazar parámetros.

Comentarios

Este enfoque es útil cuando no se necesita el conjunto de resultados de un procedimiento almacenado.

En la invalidación, llame a SQLBindParameters y a las funciones de ODBC relacionadas para enlazar los parámetros. MFC llama a la invalidación antes de llamar a ExecuteSQL. No es necesario llamar a SQLPrepare; ExecuteSQL llama a SQLExecDirect y destruye el elemento hstmt, que se usa solo una vez.

CDatabase::Cancel

Llame a esta función miembro para solicitar que el origen de datos cancele una operación asincrónica en curso o un proceso de un segundo subproceso.

void Cancel();

Comentarios

Tenga en cuenta que las clases de ODBC de MFC ya no usan procesamiento asincrónico; para realizar una operación asincrónica, debe llamar directamente a la función SQLSetConnectOptionde la API de ODBC. Para obtener más información, vea el tema que trata sobre ejecución asincrónica.

CDatabase::CanTransact

Llame a esta función miembro para determinar si la base de datos permite transacciones.

BOOL CanTransact() const;

Valor devuelto

Distinto de cero si los conjuntos de registros que usan este objeto CDatabase permiten transacciones; en caso contrario, 0.

Comentarios

Para obtener información sobre las transacciones, consulte el artículo Transacción (ODBC).

CDatabase::CanUpdate

Llame a esta función miembro para determinar si el objeto CDatabase permite actualizaciones.

BOOL CanUpdate() const;

Valor devuelto

Un valor distinto de cero si el objeto CDatabase permite actualizaciones; de lo contrario, 0, lo que indica que se ha pasado TRUE en bReadOnly al abrir el objeto CDatabase o que el propio origen de datos es de solo lectura. El origen de datos es de solo lectura si una llamada a la función SQLGetInfo de la API de ODBC para SQL_DATASOURCE_READ_ONLY devuelve y.

Comentarios

No todos los controladores admiten actualizaciones.

CDatabase::CDatabase

Construye un objeto CDatabase.

CDatabase();

Comentarios

Después de construir el objeto, debe llamar a su función miembro OpenEx u Open para establecer una conexión con un origen de datos especificado.

Es posible que le resulte cómodo insertar el objeto CDatabase en la clase de documento.

Ejemplo

En este ejemplo, se muestra el uso de CDatabase en una clase derivada de CDocument.

// This fragment is taken from the declaration for CMyDatabaseDoc
// CMyDatabaseDoc is derived from CDocument.
public:
// Declare a CDatabase embedded in the document
CDatabase m_dbCust;

 

// Initialize when needed
CDatabase *CMyDatabaseDoc::GetDatabase()
{
   // Connect the object to a data source
   if (!m_dbCust.IsOpen() && !m_dbCust.OpenEx(NULL))
      return NULL;

   return &m_dbCust;
}

CDatabase::Close

Llame a esta función miembro si desea desconectarse de un origen de datos.

virtual void Close();

Comentarios

Debe cerrar los conjuntos de registros asociados al objeto CDatabase antes de llamar a esta función miembro. Dado que Close no destruye el objeto CDatabase, puede volver a usar el objeto abriendo una nueva conexión al mismo origen de datos o a otro origen de datos.

Se cancelan todas las instrucciones AddNew o Edit pendientes de los conjuntos de registros que usan la base de datos y se revierten todas las transacciones pendientes. Los conjuntos de registros dependientes del objeto CDatabase se dejan en un estado indefinido.

Ejemplo

// Close the current connection
m_dbCust.Close();

// Perhaps connect the object to a
// different data source
m_dbCust.OpenEx(_T("DSN=MFC_ODBCTest;UID=JOES"));

CDatabase::CommitTrans

Llame a esta función miembro al completar las transacciones.

BOOL CommitTrans();

Valor devuelto

Distinto de cero si las actualizaciones se han confirmado correctamente; de lo contrario, 0. Si se produce un error en CommitTrans, el estado del origen de datos es indefinido. Debe comprobar los datos para determinar su estado.

Comentarios

Una transacción consta de una serie de llamadas a las funciones miembro AddNew, Edit, Delete y Update de un objeto CRecordset que comenzó con una llamada a la función miembro BeginTrans. CommitTrans confirma la transacción. De manera predeterminada, las actualizaciones se confirman inmediatamente; llamar a BeginTrans hace que se retrase la confirmación de las actualizaciones hasta que se llame a CommitTrans.

Hasta que llame a CommitTrans para finalizar una transacción, puede llamar a la función miembro Rollback para anular la transacción y dejar el origen de datos en su estado original. Para comenzar una nueva transacción, vuelva a llamar a BeginTrans.

Para obtener más información sobre las transacciones, consulte el artículo Transacción (ODBC).

Ejemplo

Consulte el artículo Transacción: realizar una transacción en un conjunto de registros (ODBC).

CDatabase::ExecuteSQL

Llame a esta función miembro cuando tenga que ejecutar un comando SQL directamente.

void ExecuteSQL(LPCTSTR lpszSQL);

Parámetros

lpszSQL
Puntero a una cadena terminada en null que contiene un comando SQL válido que se va a ejecutar. Puede pasar un elemento CString.

Comentarios

Cree el comando como una cadena terminada en null. ExecuteSQL no devuelve registros de datos. Si desea operar en los registros, use un objeto de conjunto de registros en su lugar.

La mayoría de los comandos de un origen de datos se emiten mediante objetos de conjunto de registros, que admiten comandos para seleccionar datos, insertar nuevos registros, eliminar registros y editar registros. Sin embargo, no todas las funcionalidades de ODBC son compatibles directamente con las clases de base de datos, por lo que es posible que en ocasiones necesite realizar una llamada SQL directa con ExecuteSQL.

Ejemplo

try
{
   m_dbCust.ExecuteSQL(
       _T("UPDATE Taxes ")
       _T("SET Rate = '36' ")
       _T("WHERE Name = 'Federal'"));
}
catch (CDBException *pe)
{
   // The error code is in pe->m_nRetCode
   pe->ReportError();
   pe->Delete();
}

CDatabase::GetBookmarkPersistence

Llame a esta función miembro para averiguar la persistencia de los marcadores en un objeto de conjunto de registros tras determinadas operaciones.

DWORD GetBookmarkPersistence() const;

Valor devuelto

Máscara de bits que identifica las operaciones en las que los marcadores son persistentes en un objeto de conjunto de registros. Para conocer más detalles, vea la sección Comentarios.

Comentarios

Por ejemplo, si llama a CRecordset::GetBookmark y, luego, a CRecordset::Requery, es posible que el marcador obtenido de GetBookmark ya no sea válido. Debe llamar a GetBookmarkPersistence antes de llamar a CRecordset::SetBookmark.

En la siguiente tabla se enumeran los valores de máscara de bits que se pueden combinar para el valor devuelto de GetBookmarkPersistence.

Valor de máscara de bits	Persistencia de marcador
SQL_BP_CLOSE	Los marcadores son válidos después de una operación Requery.
SQL_BP_DELETE	El marcador de una fila es válido después de una operación Delete en esa fila.
SQL_BP_DROP	Los marcadores son válidos después de una operación Close.
SQL_BP_SCROLL	Los marcadores son válidos después de cualquier operación Move. Esto sencillamente indica si los marcadores se admiten en el conjunto de registros, tal y como devuelve CRecordset::CanBookmark.
SQL_BP_TRANSACTION	Los marcadores son válidos después de que una transacción se haya confirmado o revertido.
SQL_BP_UPDATE	El marcador de una fila es válido después de una operación Update en esa fila.
SQL_BP_OTHER_HSTMT	Los marcadores asociados con un objeto de conjunto de registros son válidos en un segundo conjunto de registros.

Para más información sobre este valor devuelto, consulte la función SQLGetInfo de la API de ODBC en Windows SDK. Para más información sobre los marcadores, consulte el artículo Conjunto de registros: marcadores y posiciones absolutas (ODBC).

CDatabase::GetConnect

Llame a esta función miembro para recuperar la cadena de conexión utilizada durante la llamada a OpenEx o a Open que conectó el objeto CDatabase a un origen de datos.

const CString GetConnect() const;

Valor devuelto

Elemento constCString que contiene la cadena de conexión si se ha llamado a OpenEx o a Open; de lo contrario, una cadena vacía.

Comentarios

Consulte CDatabase::Open para obtener una descripción de cómo se crea la cadena de conexión.

CDatabase::GetCursorCommitBehavior

Llame a esta función miembro para determinar cómo afecta una operación CommitTrans a los cursores en los objetos de conjunto de registros abiertos.

int GetCursorCommitBehavior() const;

Valor devuelto

Valor que indica el efecto de las transacciones en objetos de conjunto de registros abiertos. Para conocer más detalles, vea la sección Comentarios.

Comentarios

En la tabla siguiente, se enumeran los posibles valores devueltos para GetCursorCommitBehavior y el efecto correspondiente en el conjunto de registros abierto.

Valor devuelto	Efecto en objetos CRecordset
SQL_CB_CLOSE	Llame a CRecordset::Requery inmediatamente después de la confirmación de la transacción.
SQL_CB_DELETE	Llame a CRecordset::Close inmediatamente después de la confirmación de la transacción.
SQL_CB_PRESERVE	Continúe normalmente con las operaciones de CRecordset.

Para más información sobre este valor devuelto, consulte la función SQLGetInfo de la API de ODBC en Windows SDK. Para obtener más información sobre las transacciones, consulte el artículo Transacción (ODBC).

CDatabase::GetCursorRollbackBehavior

Llame a esta función miembro para determinar cómo afecta una operación Rollback a los cursores en los objetos de conjunto de registros abiertos.

int GetCursorRollbackBehavior() const;

Valor devuelto

Valor que indica el efecto de las transacciones en objetos de conjunto de registros abiertos. Para conocer más detalles, vea la sección Comentarios.

Comentarios

En la tabla siguiente, se enumeran los posibles valores devueltos para GetCursorRollbackBehavior y el efecto correspondiente en el conjunto de registros abierto.

Valor devuelto	Efecto en objetos CRecordset
SQL_CB_CLOSE	Llame a CRecordset::Requery inmediatamente después de la reversión de la transacción.
SQL_CB_DELETE	Llame a CRecordset::Close inmediatamente después de la reversión de la transacción.
SQL_CB_PRESERVE	Continúe normalmente con las operaciones de CRecordset.

Para más información sobre este valor devuelto, consulte la función SQLGetInfo de la API de ODBC en Windows SDK. Para obtener más información sobre las transacciones, consulte el artículo Transacción (ODBC).

CDatabase::GetDatabaseName

Llame a esta función miembro para recuperar el nombre de la base de datos conectada actualmente (siempre que el origen de datos defina un objeto con nombre llamado "database").

CString GetDatabaseName() const;

Valor devuelto

Elemento CString que contiene el nombre de la base de datos si se ejecuta correctamente; de lo contrario, un objeto CString vacío.

Comentarios

Esto no es lo mismo que el nombre del origen de datos (DSN) especificado en la llamada a OpenEx o a Open. Lo que devuelve GetDatabaseName depende de ODBC. En general, una base de datos es una colección de tablas. Si esta entidad tiene un nombre, GetDatabaseName lo devuelve.

Por ejemplo, podría mostrar este nombre en un encabezado. Si se produce un error al recuperar el nombre desde ODBC, GetDatabaseName devuelve un valor CString vacío.

CDatabase::IsOpen

Llame a esta función miembro para determinar si el objeto CDatabase está conectado actualmente a un origen de datos.

BOOL IsOpen() const;

Valor devuelto

Valor distinto de cero si el objeto CDatabase está conectado actualmente; de lo contrario, 0.

CDatabase::m_hdbc

Contiene un manipulador público a una conexión de origen de datos ODBC: un "manipulador de conexión".

Comentarios

Normalmente, no tendrá que acceder directamente a esta variable miembro. En su lugar, el marco de trabajo asigna el manipulador al llamar a OpenEx o a Open. El marco de trabajo desasigna el manipulador cuando se llama al operador delete en el objeto CDatabase. Tenga en cuenta que la función miembro Close no desasigna el manipulador.

Sin embargo, en algunas circunstancias, es posible que tenga que usar el manipulador directamente. Por ejemplo, si tiene que llamar directamente a funciones de la API de ODBC en lugar de mediante la clase CDatabase, puede que necesite un manipulador de conexión para pasar como parámetro. Consulte el ejemplo de código siguiente.

Ejemplo

// Using m_hdbc for a direct ODBC API call.
// m_dbCust is the CDatabase object; m_hdbc is
// its HDBC member variable
nRetCode = ::SQLGetInfo(m_dbCust.m_hdbc, SQL_ODBC_SQL_CONFORMANCE,
                        &nValue, sizeof(nValue), &cbValue);

CDatabase::OnSetOptions

El marco de trabajo llama a esta función miembro al ejecutar directamente una instrucción SQL con la función miembro ExecuteSQL.

virtual void OnSetOptions(HSTMT hstmt);

Parámetros

hstmt
Manipulador de la instrucción ODBC para la que se establecen las opciones.

Comentarios

CRecordset::OnSetOptions también llama a esta función miembro.

OnSetOptions establece el valor del tiempo de espera de inicio de sesión. Si ha habido llamadas anteriores a SetQueryTimeout y a la función miembro, OnSetOptions refleja los valores actuales; de lo contrario, establece los valores predeterminados.

Nota:

Antes de MFC 4.2, OnSetOptions establece también el modo de procesamiento en sincrónico o asincrónico. A partir de MFC 4.2, todas las operaciones son sincrónicas. Para realizar una operación asincrónica, debe realizar una llamada directa a la función SQLSetPos de la API de ODBC.

No es necesario invalidar OnSetOptions para cambiar el valor del tiempo de espera. En su lugar, para personalizar el valor del tiempo de espera de las consultas, llame a SetQueryTimeout antes de crear un conjunto de registros; OnSetOptions usará el nuevo valor. Los valores establecidos se aplican a las operaciones posteriores en todos los conjuntos de registros y llamadas SQL directas.

Invalide OnSetOptions si desea establecer opciones adicionales. La invalidación debe llamar al método OnSetOptions de la clase base antes o después de llamar a la función SQLSetStmtOption de la API de ODBC. Siga el método que se muestra en la implementación predeterminada de OnSetOptions del marco de trabajo.

CDatabase::Open

Llame a esta función miembro para inicializar un objeto CDatabase recién construido.

virtual BOOL Open(
    LPCTSTR lpszDSN,
    BOOL bExclusive = FALSE,
    BOOL bReadOnly = FALSE,
    LPCTSTR lpszConnect = _T("ODBC;"),
    BOOL bUseCursorLib = TRUE);

Parámetros

lpszDSN
Especifica un nombre de origen de datos: un nombre registrado en ODBC mediante el programa Administrador de ODBC. Si se especifica un valor de DSN en lpszConnect (con el formato "DSN=<origen-de-datos>"), no se debe especificar de nuevo en lpszDSN. En este caso, lpszDSN debe ser NULL. De lo contrario, puede pasar NULL si desea presentar al usuario el cuadro de diálogo Origen de datos, en el que el usuario puede seleccionar un origen de datos. Para obtener más información, consulte Comentarios.

bExclusive
No se admite en esta versión de la biblioteca de clases. Actualmente, se produce un error en una aserción si este parámetro es TRUE. El origen de datos siempre se abre como compartido (no exclusivo).

bReadOnly
TRUE si tiene previsto que la conexión sea de solo lectura y prohibir las actualizaciones en el origen de datos. Todos los conjuntos de registros dependientes heredan este atributo. El valor predeterminado es FALSE.

lpszConnect
Especifica una cadena de conexión. La cadena de conexión concatena información, posiblemente incluyendo un nombre de origen de datos, un identificador de usuario válido en el origen de datos, una cadena de autenticación de usuario (contraseña, si el origen de datos requiere una) y otra información. La cadena de conexión completa debe tener como prefijo la cadena "ODBC;" (mayúsculas o minúsculas). La cadena "ODBC;" se usa para indicar que es una conexión a un origen de datos ODBC; esto es por compatibilidad ascendente cuando las versiones futuras de la biblioteca de clases pudieran admitir orígenes de datos que no son ODBC.

bUseCursorLib
TRUE si desea que se cargue el archivo DLL de la biblioteca de cursores de ODBC. La biblioteca de cursores enmascara alguna funcionalidad del controlador ODBC subyacente, lo que impide eficazmente el uso de conjuntos dinámicos (si el controlador los admite). Los únicos cursores admitidos si se carga la biblioteca de cursores son instantáneas estáticas y cursores de solo avance. El valor predeterminado es TRUE. Si tiene previsto crear un objeto de conjunto de registros directamente desde CRecordset sin derivarlo, no debe cargar la biblioteca de cursores.

Valor devuelto

Distinto de cero si la conexión se realiza correctamente; de lo contrario, 0 si el usuario elige Cancelar cuando se le presenta un cuadro de diálogo que solicita más información de conexión. En todos los demás casos, el marco de trabajo produce una excepción.

Comentarios

El objeto de base de datos se debe inicializar para poder usarlo para construir un objeto de conjunto de registros.

Nota:

Llamar a la función miembro OpenEx es la manera preferida de conectarse a un origen de datos e inicializar el objeto de base de datos.

Si los parámetros de la llamada a Open no contienen suficiente información para realizar la conexión, el controlador ODBC abre un cuadro de diálogo para obtener la información necesaria del usuario. Cuando se llama a Open, la cadena de conexión, lpszConnect, se almacena de forma privada en el objeto CDatabase y está disponible mediante una llamada a la función miembro GetConnect.

Si quiere, puede abrir su propio cuadro de diálogo antes de llamar a Open para obtener información del usuario, como una contraseña, y luego agregar esa información a la cadena de conexión que se pasa a Open. O puede que quiera guardar la cadena de conexión que se pasa para poder reutilizarla la próxima vez que la aplicación llame a Open en un objeto CDatabase.

También puede usar la cadena de conexión en varios niveles de autorización de inicio de sesión (cada uno para un objeto CDatabase diferente) o para transmitir otra información específica del origen de datos. Para obtener más información sobre las cadenas de conexión, consulte el capítulo 5 en Windows SDK.

Es posible que se agote el tiempo de espera de un intento de conexión si, por ejemplo, el host de DBMS no está disponible. Si se produce un error en el intento de conexión, Open produce una excepción CDBException.

Ejemplo

// m_dbCust is a CDatabase object embedded in a CDocument class

if (bDefault)
{
   // Connect the object to a data source (no password)
   // the ODBC connection dialog box will always remain hidden
   m_dbCust.Open(_T("MFC_ODBCTest"), FALSE, FALSE, _T("ODBC;UID=JOES"));
}
else
{
   // ...Or, query the user for all connection information
   m_dbCust.Open(NULL);
}

CDatabase::OpenEx

Llame a esta función miembro para inicializar un objeto CDatabase recién construido.

virtual BOOL OpenEx(
    LPCTSTR lpszConnectString,
    DWORD dwOptions = 0);

Parámetros

lpszConnectString
Especifica una cadena de conexión ODBC. Esto incluye el nombre del origen de datos, así como otra información opcional, como un identificador de usuario y una contraseña. Por ejemplo, "DSN=SQLServer_Source;UID=SA;PWD=abc123" es una posible cadena de conexión. Tenga en cuenta que si pasa NULL para lpszConnectString, el cuadro de diálogo Origen de datos pedirá al usuario que seleccione un origen de datos.

dwOptions
Máscara de bits que especifica una combinación de los valores siguientes. El valor predeterminado es 0, lo que significa que la base de datos se abrirá como compartida con acceso de escritura, no se cargará el archivo DLL de la biblioteca de cursores ODBC y el cuadro de diálogo de conexión ODBC solo se mostrará si no hay suficiente información para establecer la conexión.

• No se admite CDatabase::openExclusive en esta versión de la biblioteca de clases. Un origen de datos siempre se abre como compartido (no exclusivo). Actualmente, se produce un error en una aserción si especifica esta opción.

• CDatabase::openReadOnly abre el origen de datos como de solo lectura.

• CDatabase::useCursorLib carga el archivo DLL de la biblioteca de cursores ODBC. La biblioteca de cursores enmascara alguna funcionalidad del controlador ODBC subyacente, lo que impide eficazmente el uso de conjuntos dinámicos (si el controlador los admite). Los únicos cursores admitidos si se carga la biblioteca de cursores son instantáneas estáticas y cursores de solo avance. Si tiene previsto crear un objeto de conjunto de registros directamente desde CRecordset sin derivarlo, no debe cargar la biblioteca de cursores.

• CDatabase::noOdbcDialog no se muestra el cuadro de diálogo de conexión ODBC, independientemente de si se proporciona suficiente información de conexión.

• CDatabase::forceOdbcDialog se muestra siempre el cuadro de diálogo de conexión ODBC.

Valor devuelto

Distinto de cero si la conexión se realiza correctamente; de lo contrario, 0 si el usuario elige Cancelar cuando se le presenta un cuadro de diálogo que solicita más información de conexión. En todos los demás casos, el marco de trabajo produce una excepción.

Comentarios

El objeto de base de datos se debe inicializar para poder usarlo para construir un objeto de conjunto de registros.

Si el parámetro lpszConnectString de la llamada a OpenEx no contiene suficiente información para realizar la conexión, el controlador ODBC abre un cuadro de diálogo para obtener la información necesaria del usuario, siempre que no haya establecido CDatabase::noOdbcDialog o CDatabase::forceOdbcDialog en el parámetro dwOptions. Cuando se llama a OpenEx, la cadena de conexión, lpszConnectString, se almacena de forma privada en el objeto CDatabase y está disponible mediante una llamada a la función miembro GetConnect.

Si quiere, puede abrir su propio cuadro de diálogo antes de llamar a OpenEx para obtener información del usuario, como una contraseña, y luego agregar esa información a la cadena de conexión que se pasa a OpenEx. O puede que quiera guardar la cadena de conexión que se pasa para poder reutilizarla la próxima vez que la aplicación llame a OpenEx en un objeto CDatabase.

También puede usar la cadena de conexión en varios niveles de autorización de inicio de sesión (cada uno para un objeto CDatabase diferente) o para transmitir otra información específica del origen de datos. Para obtener más información sobre las cadenas de conexión, consulte el capítulo 6 de la Referencia del programador de ODBC.

Es posible que se agote el tiempo de espera de un intento de conexión si, por ejemplo, el host de DBMS no está disponible. Si se produce un error en el intento de conexión, OpenEx produce una excepción CDBException.

Ejemplo

// m_dbCust is a CDatabase object embedded in a CDocument class.

// Connect the object to a read-only data source where
// the ODBC connection dialog box will always remain hidden
m_dbCust.OpenEx(_T("DSN=MFC_ODBCTest;UID=JOES"),
                CDatabase::openReadOnly | CDatabase::noOdbcDialog);

CDatabase::Rollback

Llame a esta función miembro para invertir los cambios realizados durante una transacción.

BOOL Rollback();

Valor devuelto

Distinto de cero si la transacción se ha invertido correctamente; de lo contrario, 0. Si se produce un error en una llamada a Rollback, los estados del origen de datos y la transacción son indefinidos. Si Rollback devuelve 0, debe comprobar el origen de datos para determinar su estado.

Comentarios

Todas las CRecordset AddNewllamadas , Edit, Deletey Update ejecutadas desde la última BeginTrans se revierten al estado que existía en el momento de esa llamada.

Después de una llamada a Rollback, la transacción ha terminado y debe volver a llamar a BeginTrans para otra transacción. El registro que era actual antes de llamar a BeginTrans se convierte en el registro actual de nuevo después de llamar a Rollback.

Después de una reversión, el registro actual antes de la reversión sigue siendo actual. Para obtener más información sobre el estado del conjunto de registros y el origen de datos después de una reversión, consulte el artículo Transacción (ODBC).

Ejemplo

Consulte el artículo Transacción: realizar una transacción en un conjunto de registros (ODBC).

CDatabase::SetLoginTimeout

Llame a esta función miembro ( antes de llamar a OpenEx o a Open) para invalidar el número predeterminado de segundos permitido antes de que se agote el tiempo de espera de una conexión de origen de datos intentada.

void SetLoginTimeout(DWORD dwSeconds);

Parámetros

dwSeconds
Número de segundos que se permiten antes de que se agote el tiempo de espera de un intento de conexión.

Comentarios

Un intento de conexión podría agotar el tiempo de espera si, por ejemplo, el DBMS no está disponible. Llame a SetLoginTimeout después de construir el objeto CDatabase sin inicializar, pero antes de llamar a OpenEx o a Open.

El valor predeterminado del tiempo de espera de inicio de sesión es de 15 segundos. No todos los orígenes de datos admiten la capacidad de especificar un valor de tiempo de espera de inicio de sesión. Si el origen de datos no admite el tiempo de espera, obtendrá la salida de seguimiento, pero no una excepción. Un valor de 0 significa "infinito".

CDatabase::SetQueryTimeout

Llame a esta función miembro para invalidar el número predeterminado de segundos que se permiten antes de que se agote el tiempo de espera de las operaciones posteriores en el origen de datos conectado.

void SetQueryTimeout(DWORD dwSeconds);

Parámetros

dwSeconds
Número de segundos que se permiten antes de que se agote el tiempo de espera de un intento de consulta.

Comentarios

Una operación puede agotar el tiempo de espera debido a problemas de acceso a la red, un tiempo excesivo de procesamiento de las consultas, etc. Llame a SetQueryTimeout antes de abrir el conjunto de registros o antes de llamar a las funciones miembro AddNew, Update o Delete del conjunto de registros si desea cambiar el valor de tiempo de espera de la consulta. La configuración afecta a todas las llamadas posteriores a Open, AddNew, Update y Delete para cualquier conjunto de registros asociado a este objeto CDatabase. El cambio del valor de tiempo de espera de consulta de un conjunto de registros después de abrirlo no modifica el valor del conjunto de registros. Por ejemplo, las operaciones Move posteriores no usan el nuevo valor.

El valor predeterminado del tiempo de espera de consulta es de 15 segundos. No todos los orígenes de datos admiten la capacidad de establecer un valor de tiempo de espera de consulta. Si establece un valor de tiempo de espera de consulta de 0, no se produce ningún tiempo de espera; la comunicación con el origen de datos puede dejar de responder. Este comportamiento puede ser útil durante el desarrollo. Si el origen de datos no admite el tiempo de espera, obtendrá la salida de seguimiento, pero no una excepción.

Consulte también

CObject (clase)
Gráfico de jerarquías
CRecordset (clase)