Instrucciones de programación

Descargar controlador ODBC

Este artículo describe consideraciones de programación para aplicaciones que utilizan el controlador ODBC de Microsoft para SQL Server en Linux o macOS. Algunos enlaces apuntan a material nativo de SQL Server Native Client. Esas páginas proporcionan contexto histórico de la API.

Elige una versión del controlador

Utiliza el controlador ODBC 18 de Microsoft para SQL Server, la línea actual de controladores, para nuevos desarrollos. El controlador ODBC 17 de Microsoft para SQL Server sigue teniendo soporte para las aplicaciones que ya lo implementan, tal y como se describe en el ciclo de vida de soporte. El controlador ODBC 13, que se incluyó con SQL Server 2017, es elegible para soporte extendido hasta el 12 de octubre de 2027, solo bajo un acuerdo de soporte ampliado.

Especifica el nombre del controlador instalado en tu cadena de conexión, entre llaves:

Driver={ODBC Driver 18 for SQL Server}

Driver={ODBC Driver 17 for SQL Server}

En un nombre de fuente de datos (DSN) en odbc.ini, usa el nombre sin llaves, por ejemplo Driver = ODBC Driver 18 for SQL Server. Para la sintaxis de la DSN, consulte Palabras clave de la cadena de conexión y nombres de fuentes de datos (DSNs).

Para la configuración de conexión específica de la versión, véase Diferencias entre versiones principales. Para fechas de soporte y compatibilidad con el sistema operativo, consulte el ciclo de vida de soporte y los requisitos del sistema.

Crear una aplicación

Para consultar las ubicaciones de los encabezados, el orden, los comandos del compilador, los nombres de las bibliotecas y un ejemplo de C++, véase Desarrollar aplicaciones en C y C++ con el controlador ODBC y Conectar y consultar con C++ y ODBC.

Una aplicación ODBC puede utilizar Múltiples Conjuntos de Resultados Activos (MARS) y otras características específicas de SQL Server incluyendo msodbcsql.h después de los encabezados de unixODBC (sql.h, sqlext.h, sqltypes.h, y sqlucode.h). Usa los mismos nombres simbólicos para los elementos específicos de SQL Server que usas en las aplicaciones ODBC de Windows.

Buscar capacidades del driver

Comienza con la Referencia del Programador ODBC para la interfaz estándar de programación de aplicaciones (API). Luego usa la documentación actual del controlador para el comportamiento específico del controlador.

La visión general del controlador ODBC de Microsoft para SQL Server enlaza con la documentación del controlador. Los siguientes artículos de SQL Server Native Client proporcionan contexto de API para aplicaciones que utilizan el controlador en Linux y macOS:

Limitations

Las siguientes funciones no han sido verificadas para funcionar correctamente en el controlador ODBC en Linux y macOS:

Características no admitidas

Las siguientes funciones no están disponibles en el controlador ODBC en Linux y macOS:

  • Transacciones distribuidas a través del SQL_ATTR_ENLIST_IN_DTC atributo. El controlador soporta transacciones XA a través del Coordinador de transacciones distribuidas de Microsoft (DTC). Para más información, consulte Usar transacciones XA con DTC.

  • Duplicación de la base de datos.

  • FILESTREAM.

  • Análisis del rendimiento del controlador ODBC, tratado en SQLSetConnectAttr, y los siguientes atributos de conexión relacionados con el rendimiento:

    • SQL_COPT_SS_PERF_DATA
    • SQL_COPT_SS_PERF_DATA_LOG
    • SQL_COPT_SS_PERF_DATA_LOG_NOW
    • SQL_COPT_SS_PERF_QUERY
    • SQL_COPT_SS_PERF_QUERY_INTERVAL
    • SQL_COPT_SS_PERF_QUERY_LOG

  • SQLBrowseConnect antes de la versión 17.2.

  • Tipos de intervalo C, como SQL_C_INTERVAL_YEAR_TO_MONTH, documentados en Data Type Identifiers and Descriptors.

  • El SQL_CUR_USE_ODBC valor del atributo SQL_ATTR_ODBC_CURSORS de SQLSetConnectAttr.

Procesar datos de caracteres

En Linux y macOS, utiliza búferes UTF-16 SQLWCHAR con APIs ODBC de carácter amplio en lugar del tipo nativo wchar_t . La interfaz del driver utiliza unidades de código de 16 bits.

Codificaciones de caracteres

Para los drivers ODBC 13 y 13.1, debes usar UTF-8 para los SQLCHAR datos. Estas versiones no soportan ninguna otra codificación.

A partir del controlador ODBC 17, los conjuntos de caracteres y codificaciones soportados para datos SQLCHAR incluyen:

Nota

Debido a iconv diferencias entre musl y glibc, muchas de estas localizaciones no son compatibles con Alpine Linux. Para más información, véase Diferencias funcionales respecto a glibc.

Nombre Descripción
UTF-8 Unicode
CP437 MS-DOS Latinoamericano de EE. UU.
CP850 MS-DOS Latín 1
CP874 Latín/tailandés
CP932 Japonés (página de códigos de Windows 932)
CP936 Chino simplificado, GBK
CP949 Coreano (página de códigos de Windows 949)
CP950 Chino tradicional, Big5
CP1250 Centroeuropeo
CP1251 Cirílico
CP1252 Europa occidental
CP1253 Griego
CP1254 Turco
CP1255 Hebreo
CP1256 Árabe
CP1257 Báltico
CP1258 Vietnamita
ISO-8859-1 Latín-1
ISO-8859-2 Latín-2
ISO-8859-3 Latín-3
ISO-8859-4 Latín-4
ISO-8859-5 Latín/cirílico
ISO-8859-6 Latín/árabe
ISO-8859-7 Latín/griego
ISO-8859-8 Hebreo
ISO-8859-9 Turco
ISO-8859-13 Latín-7
ISO-8859-15 Latín-9

Cuando te conectas, el controlador detecta la configuración regional actual del proceso en el que está cargado. Si la configuración regional utiliza una de las codificaciones listadas, el controlador utiliza esa codificación para datos de SQLCHAR (caracteres estrechos). De lo contrario, por defecto es UTF-8. Los procesos se inician por defecto en la C configuración regional, lo que hace que el controlador use UTF-8 de forma predeterminada. Si una aplicación necesita una de las codificaciones listadas, llame a setlocale antes de conectar. Especifica la configuración regional explícitamente, o usa una cadena vacía (por ejemplo, setlocale(LC_ALL, "")) para usar la configuración regional del entorno.

En un entorno típico de Linux o macOS donde la codificación es UTF-8, los usuarios del controlador ODBC 17 que actualicen desde 13 o 13.1 no notarán diferencias. Las aplicaciones que usan una codificación setlocale listada que no sea UTF-8 necesitan usar esa codificación para los datos hacia y desde el driver en lugar de UTF-8.

Debes usar UTF-16LE (little endian) para los datos de SQLWCHAR.

Cuando asignas parámetros de entrada usando SQLBindParameter, si especificas un tipo SQL de carácter estrecho como SQL_VARCHAR, el controlador convierte los datos suministrados de la codificación cliente a la codificación del lado servidor para ese parámetro. La codificación depende de la intercalación; no siempre es la página de códigos 1252. Para los parámetros de salida, el controlador lleva a cabo la conversión desde la codificación especificada en la información de intercalación asociada con los datos a la codificación del cliente. Los caracteres en la codificación de origen que no son representables en la codificación de destino se convierten en un signo de interrogación (?).

Para evitar esta pérdida de datos al vincular parámetros de entrada, especifique un tipo de carácter SQL Unicode como SQL_WVARCHAR. El controlador convierte la codificación del cliente a UTF-16, que puede representar todos los caracteres Unicode. La columna o parámetro objetivo también debe ser un tipo Unicode (nchar, nvarchar o ntext) o un tipo con una intercalación o codificación que pueda representar todos los datos fuente originales. Para los parámetros de salida, especifique un tipo SQL Unicode y un tipo C Unicode (SQL_C_WCHAR), que haga que el controlador devuelva datos como UTF-16, o un tipo C estrecho con una codificación cliente que pueda representar los datos fuente. UTF-8 siempre puede representar estos datos.

Para más información sobre colaciones y codificaciones, consulte Intercalación y compatibilidad con Unicode.

Existen diferencias de conversión entre las versiones de Windows y Linux o macOSiconv:

  • Para la página de códigos 1255, el byte 0xCA se convierte en punto 0x05BA de código UTF-16 en Windows y 0x00CA en macOS y Linux con libiconv versiones anteriores a la 1.15.
  • Las bibliotecas de Linux iconv sin la revisión de 2003 de Big5/CP950 (BIG5-2003) no convierten correctamente los caracteres añadidos en esa revisión.
  • Para la página de códigos 932 (japonés, Shift-JIS), la decodificación de los caracteres no definidos en el estándar de codificación difiere. Por ejemplo, byte 0x80 se convierte en U+0080 en Windows y puede convertirse en U+30FB en Linux y macOS, dependiendo de la versión iconv.

En los controladores ODBC 13 y 13.1, separar caracteres multibyte UTF-8 o pares sustitutos UTF-16 entre SQLPutData búferes provoca corrupción de datos. Utiliza buffers de streaming que no terminen en codificaciones parciales de caracteres. Esta limitación fue eliminada en ODBC Driver 17.

Para obtener orientación sobre codificación de caracteres, conversión, vinculación de parámetros y tamaño de búfer, véase Problemas conocidos.

Openssl

A partir del controlador ODBC 17.4, el controlador carga OpenSSL dinámicamente, lo que permite ejecutarse en sistemas con versiones 1.0 o 1.1 sin archivos de controlador separados. A partir de la versión 17.9, el controlador admite OpenSSL 3.0 además de las versiones anteriores. Cuando hay múltiples versiones de OpenSSL, el controlador intenta cargar una versión soportada desde sus rutas de búsqueda de biblioteca.

Versión del controlador Versiones de OpenSSL admitidas
De 17.4 a 17.8 1.0, 1.1
versiones 17.x desde la 17.9 y todas las versiones del Driver 18 1.0, 1.1, 3.0

OpenSSL 4 no es compatible. En macOS, un enlace Homebrew openssl que apunta a OpenSSL 4 puede impedir que el controlador cargue OpenSSL incluso cuando OpenSSL 3 esté instalado. Revisa la ruta de la biblioteca así como las versiones instaladas.

Nota

Podría producirse un conflicto potencial si la aplicación que utiliza el controlador, o uno de sus componentes, se vincula con o carga dinámicamente una versión diferente de OpenSSL. Si hay varias versiones de OpenSSL en el sistema y la aplicación lo utiliza, asegúrate de que la versión cargada por la aplicación y el controlador coincidan. Los errores pueden corromper la memoria y puede que no se manifiesten de forma obvia o consistente.

Alpine Linux

El tamaño predeterminado de la pila para hilos nuevos en musl es de 128 KB, a menos que el ejecutable solicite un valor predeterminado mayor. Un hilo puede superar este límite cuando llama al driver. Vincula una aplicación ODBC en Alpine Linux con -Wl,-z,stack-size=<size_in_bytes> para solicitar una pila de hilos predeterminada más grande. Las aplicaciones que crean hilos con un tamaño de pila explícito también deben elegir un tamaño adecuado para esos hilos.

La pila del hilo principal y la pila predeterminada para hilos nuevos no tienen la misma configuración. En sistemas glibc , el valor predeterminado para nuevos hilos normalmente sigue el límite de recursos de la pila del proceso, con un respaldo específico de la arquitectura cuando ese límite es ilimitado. No asumas un valor predeterminado fijo de 2 MB entre los sistemas Linux.

Notas adicionales

Para crear una conexión de administrador dedicado (DAC) desde una aplicación ODBC, establece Server=tcp:<server>,<dac_port>Dedicated Administrator Connection=Yes en tu cadena de conexión. Usa el puerto DAC descubierto, no el puerto de conexión normal de la instancia. Por ejemplo, si el puerto del DAC es 33000, establezca Server=tcp:<server>,33000. Estos fragmentos de cadena de conexión especifican solo el punto final, no la autenticación. Configura la autenticación y la validación del certificado del servidor por separado.

El usuario debe ser miembro de la función de servidor sysadmin. El acceso remoto requiere activar la opción de conexiones de administrador remoto del servidor. Para requisitos de acceso, configuración del servidor y procedimientos de administración desde la línea de comandos, véase Conexión de diagnóstico para administradores de bases de datos. Para la detección de puertos, véase puerto DAC.

El gestor de controladores unixODBC gestiona los atributos de las sentencias que se transmiten SQLSetConnectAttr de la misma manera que el Administrador de controladores de Windows. Las opciones de sentencias ODBC 2.x, como SQL_ATTR_QUERY_TIMEOUT y SQL_ATTR_MAX_ROWS, se aplican a sentencias existentes y nuevas en la conexión. Los atributos ODBC 3.x solo de sentencias, como SQL_ATTR_ROW_ARRAY_SIZE y SQL_ATTR_PARAMSET_SIZE, devuelven SQLSTATE HY092. Los atributos definidos tanto en el nivel de conexión como en la sentencia, como SQL_ATTR_METADATA_ID, pueden establecerse en cualquiera de los dos niveles. Establecer atributos solo de sentencias a nivel de conexión está obsoleto en ODBC 3.x, así que llama a SQLSetStmtAttr en su lugar. Para más información, consulte la función SQLSetConnectAttr.

En aplicaciones altamente multihilo, la validación de handles de unixODBC puede convertirse en un cuello de botella de rendimiento. Compilar unixODBC con --enable-fastvalidate podría mejorar el rendimiento. Sin embargo, esta opción podría hacer que las aplicaciones que pasan handles inválidos a APIs ODBC se bloqueen en lugar de devolver SQL_INVALID_HANDLE.

Para los pasos de instalación y configuración de la plataforma, véase:

Contenido relacionado

  • Se actualizó por última vez el