Función SQLCreateDataSource

Conformidad
Versión introducida: ODBC 2.0

Resumen
SQLCreateDataSource muestra un cuadro de diálogo con el que el usuario puede agregar un origen de datos.

Sintaxis

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);  

Argumentos

hwnd
[Entrada] Identificador de ventana principal.

lpszDS
[Entrada] Nombre del origen de datos. lpszDS puede ser un puntero nulo o una cadena vacía.

Devoluciones

SQLCreateDataSource devuelve TRUE si se crea el origen de datos. De lo contrario, devuelve FALSE.

Diagnóstico

Cuando SQLCreateDataSource devuelve FALSE, se puede obtener un valor *pfErrorCode asociado llamando a SQLInstallerError. En la tabla siguiente se enumeran los valores *pfErrorCode que SQLInstallerError puede devolver y explica cada uno de ellos en el contexto de esta función.

*pfErrorCode	Error	Descripción
ODBC_ERROR_GENERAL_ERR	Error general del instalador	Se produjo un error para el que no hubo ningún error de instalador específico.
ODBC_ERROR_INVALID_HWND	Identificador de ventana no válido	El argumento hwnd no era válido o NULL.
ODBC_ERROR_INVALID_DSN	DSN no válido	El argumento lpszDS contenía una cadena que no era válida para un DSN.
ODBC_ERROR_REQUEST_FAILED	Error de solicitud	Error en la llamada a ConfigDSN con la opción ODBC_ADD_DSN.
ODBC_ERROR_LOAD_LIBRARY_FAILED	No se pudo cargar el controlador ni la biblioteca de instalación del traductor	No se pudo cargar la biblioteca de instalación del controlador.
ODBC_ERROR_USER_CANCELED	Operación cancelada por el usuario	El usuario canceló la creación de un nuevo origen de datos.
ODBC_ERROR_CREATE_DSN_FAILED	No se pudo crear el DSN solicitado	No se pudo conectar a la base de datos; la llamada a SQLDriverConnect para un DSN de archivo no devolvió una conexión correcta. No se pudo escribir en el archivo.
ODBC_ERROR_OUT_OF_MEM	No hay memoria suficiente	El instalador no pudo realizar la función debido a una falta de memoria.

Comentarios

Si hwnd es null, SQLCreateDataSource devuelve FALSE. De lo contrario, muestra el cuadro de diálogo Crear nuevo origen de datos con una página del asistente para elegir el tipo de origen de datos que se va a configurar, como se muestra en la ilustración siguiente.

.

La opción predeterminada es Origen de datos de archivo. Cuando se ha elegido un origen de datos y se ha hecho clic en Siguiente, se muestra la siguiente página del asistente que contiene una lista de controladores instalados.

Si se hace clic en Cancelar , el cuadro de diálogo desaparece y SQLCreateDataSource devuelve FALSE con el código de error de ODBC_ERROR_USER_CANCELED. Si se ha seleccionado la opción Origen de datos de usuario o Origen de datos del sistema , el botón Avanzadas no está disponible.

Cuando se haga clic en el botón Siguiente , se producirá uno de los siguientes, en función del tipo de origen de datos seleccionado:

• Si se ha seleccionado Origen de datos de archivo, se muestra una página del asistente para que el usuario escriba un nombre de archivo.

• Si se ha seleccionado Origen de datos de usuario o Origen de datos del sistema , se muestra una página del asistente que muestra el tipo de origen de datos y el controlador para su revisión y, cuando se hace clic en Finalizar , se configura el origen de datos.

Si se hace clic en Avanzadas en la página del Asistente para crear nuevo origen de datos, se muestra una página del asistente para que el usuario escriba información específica del controlador. En el cuadro de texto de este cuadro de diálogo, escriba las palabras clave y el controlador separados por devoluciones, como se muestra en la ilustración siguiente.

Puede encontrar palabras clave adicionales específicas del controlador en la descripción de SQLDriverConnect. Se permiten todos excepto DSN .

El valor predeterminado de la opción Comprobar esta conexión es TRUE. Este valor predeterminado se aplica si se activa o no esta página del asistente. Si se hace clic en Aceptar , se almacena en caché la cadena especificada en el cuadro de texto y el valor de la opción Comprobar esta conexión . (Si se hace clic en el botón Cerrar o Cancelar , se pierde cualquier información específica del controlador recién especificada porque la cadena especificada en el cuadro de texto y el valor de la opción Comprobar esta conexión no se almacenan en caché).

Si el origen de datos de archivo se seleccionó en la primera página del asistente, después de seleccionar un controlador y se han especificado los valores de palabra clave en la página Asistente avanzado, se le pedirá al usuario que escriba un nombre de archivo. Haga clic en Examinar para buscar un nombre de archivo, en cuyo caso el directorio predeterminado del cuadro Examinar se especifica mediante una combinación de la ruta de acceso especificada por CommonFileDir en HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion y "ODBC\DataSources". (Si CommonFileDir era "C:\Program Files\Common Files", el directorio predeterminado sería "C:\Program Files\Common Files\ODBC\Data Sources").

Cuando se ha especificado un nombre de archivo y se hace clic en Siguiente , se comprueba la validez del nombre de archivo especificado en las reglas de nomenclatura de archivos estándar del sistema operativo. Si el nombre de archivo no es válido, un cuadro de mensaje de error notifica al usuario que se especificó un nombre de archivo no válido. Después de que el usuario confirme el cuadro de mensaje, el foco se devuelve a la página del asistente en la que se escribe el nombre de archivo. Si el nombre de archivo es válido, se muestra una página del asistente que muestra los pares de palabra clave-valor seleccionados para su revisión, como se muestra en la ilustración siguiente.

Si se hace clic en Finalizar y origen de datos de archivo se seleccionó como tipo de origen de datos y, si la opción Comprobar esta conexión es TRUE, se llama a SQLDriverConnect con las palabras clave SAVEFILE y DRIVER . El argumento DriverCompletion se establece en SQL_DRIVER_COMPLETE. El nombre de archivo de la palabra clave SAVEFILE es el nombre que se especificó o eligió, y el nombre del controlador para la palabra clave DRIVER es el nombre elegido. Si se especificó una cadena de conexión específica del controlador en la página Asistente avanzado, esa cadena se anexa después de la palabra clave DRIVER .

Si SQLDriverConnect devuelve SQL_SUCCESS, el Administrador de controladores ha creado el DSN de archivo. SQLCreateDataSource devuelve TRUE. Si SQLDriverConnect no devuelve SQL_SUCCESS, un cuadro de mensaje de advertencia indica que no se pudo establecer una conexión con el origen de datos. Todavía se puede crear un DSN con información de conexión mínima. Este cuadro de mensaje permite al usuario cancelar o continuar con la creación de DSN de archivo.

Si el usuario decide seguir creando el DSN, este proceso continúa como si la opción Comprobar esta conexión estuviera establecida en FALSE. Si el usuario decide cancelar, se devuelve FALSE para SQLCreateDataSource con un código de error de ODBC_ERROR_CREATE_DSN_FAILED.

Si el origen de datos de archivo se seleccionó como el tipo de origen de datos y la opción Comprobar esta conexión es FALSE, se crea un DSN de archivo con la palabra clave DRIVER y la cadena de conexión especificada por el usuario (si existe) desde la página Asistente avanzado. Si la creación del archivo se realizó correctamente, se devuelve TRUE para SQLCreateDataSource. Si la creación del archivo no se realizó correctamente, un cuadro de mensaje de error notifica al usuario el error que se devolvió del sistema operativo. False se devuelve para SQLCreateDataSource con un código de error de ODBC_ERROR_CREATE_DSN_FAILED. Para obtener más información sobre los orígenes de datos de archivos, vea Conexión mediante orígenes de datos de archivos o vea SQLDriverConnect.

Si usuario o origen de datos del sistema se seleccionó como tipo de origen de datos, se llama a ConfigDSN en la biblioteca de configuración del controlador con el ODBC_ADD_DSN fRequest. Para obtener más información, consulte ConfigDSN.

Funciones relacionadas

Para información acerca de	Vea
Administración de orígenes de datos	SQLManageDataSources