Pilote ODBC Prise en charge de l’API

Le pilote Snowflake ODBC prend en charge la version 3.52 de l’ODBC API. Ce chapitre répertorie les routines ODBC pertinentes pour Snowflake, et indique si elles sont prises en charge. Les routines sont organisées en catégories en fonction de la fonction qu’elles remplissent.

Pour la référence API complète , voir Microsoft ODBC Programmer’s Reference.

Dans ce chapitre :

Connexion à une source de données

Nom de la fonction

Pris en charge

Remarques

SQLAllocHandle

SQLConnect

SQLDriverConnect

SQLAllocEnv

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC.

SQLAllocConnect

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC.

SQLBrowseConnect

Obtention d’informations sur un pilote et une source de données

Nom de la fonction

Pris en charge

Remarques

SQLDataSources

SQLDrivers

SQLGetInfo

SQLGetFunctions

SQLGetTypeInfo

Définition et récupération des attributs du pilote

Nom de la fonction

Pris en charge

Remarques

SQLSetConnectAttr

Le paramètre SQL_ATTR_METADATA_ID affecte uniquement les fonctions SQLTables et SQLColumns (et non les autres fonctions de catalogue prises en charge).

SQLGetConnectAttr

Le mode lecture seule n’est pas pris en charge. SQL_MODE_READ_ONLY est transmis au pilote, mais Snowflake écrit toujours dans la base de données. . . De plus, certains attributs ont été introduits après la version 3.52 de l’API : SQL_ATTR_ASYNC_DBC_EVENT, SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE, SQL_ATTR_ASYNC_DBC_PCALLBACK, SQL_ATTR_ASYNC_DBC_PCONTEXT, SQL_ATTR_DBC_INFO_TOKEN.

SQLSetConnectOption

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC.

SQLGetConnectOption

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC.

SQLSetEnvAttr

SQLGetEnvAttr

L’attribut SQL_ATTR_CONNECTION_POOLING a été introduit après la version 3.52 de l’API ODBC et n’est pas pris en charge.

SQLSetStmtAttr

SQL_ATTR_CURSOR_SCROLLABLE only supports a SQL_NONSCROLLABLE value. . SQL_ATTR_USE_BOOKMARKS only supports a SQL_UB_OFF value. . . For compatibility with third-party tools, SQL_ATTR_ENABLE_AUTO_IPD defaults to true, even though the ODBC standard says it should default to false. . . Setting SQL_ATTR_METADATA_ID only affects the SQLTables and SQLColumns functions (and not the other supported catalog functions). . . Unsupported attributes: SQL_ATTR_SIMULATE_CURSOR, SQL_ATTR_FETCH_BOOKMARK_PTR, SQL_ATTR_KEYSET_SIZE.

SQLGetStmtAttr

Outre les attributs standard, l’implémentation Snowflake prend en charge l’attribut SQL_SF_STMT_ATTR_LAST_QUERY_ID, qui permet à l’utilisateur de récupérer l’ID de requête le plus récent associé au descripteur d’instructions spécifié. Un exemple partiel est présenté dans la section Exemples ci-dessous.

SQLSetStmtOption

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC. Remplacé par SQLSetStmtAttr.

SQLGetStmtOption

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC. Remplacé par SQLGetStmtAttr.

SQLParamOptions

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC. Remplacé par SQLSetStmtAttr.

Chacune des fonctions précédentes a une fonction correspondante qui accepte les caractères larges (unicode). Chacune de ces fonctions unicode porte le nom indiqué ci-dessus, suivi de « W ». Par exemple, la fonction SQLGetStmtAttr, qui accepte un tableau de caractères en tant que troisième paramètre, a une fonction correspondante appelée SQLGetStmtAttrW, qui accepte un tableau wchar en tant que troisième paramètre.

Comportement spécifique à Snowflake

  • SQLSetConnectAttr

    Cette méthode prend en charge deux attributs spécifiques à Snowflake :

    Nom d’attribut

    Description

    SQL_SF_CONN_ATTR_APPLICATION

    Cela remplace la valeur spécifiée par le paramètre APPLICATION dans le registre ou le fichier .ini.

    SQL_SF_CONN_ATTR_PRIV_KEY

    Il s’agit d’un pointeur EVP_PKEY* qui pointe vers une copie en mémoire de la clé privée. Cela remplace les paramètres PRIV_KEY_FILE et PRIV_KEY_PWD du registre ou du fichier .ini. Snowflake recommande d’utiliser cet attribut pour définir la clé privée.

Définition et récupération de champs descripteurs

Nom de la fonction

Pris en charge

Remarques

SQLGetDescField

SQLGetDescRec

SQLSetDescField

SQLSetDescRec

Préparation de requêtes SQL

Nom de la fonction

Pris en charge

Remarques

SQLAllocStmt

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC.

SQLBindParameter

SQLPrepare

SQLGetCursorName

SQLSetCursorName

SQLSetScrollOptions

Pris en charge par le pilote Snowflake, mais obsolète dans l’API ODBC.

SQLSetParam

Pris en charge par le pilote Snowflake, mais obsolète dans la version 2.x de l’API ODBC. Remplacé par SQLBindParameter.

Note

Il existe une limite supérieure à la taille des données que vous pouvez lier. Pour plus de détails, voir Limites de la taille du texte de requête.

Soumission de requêtes

Nom de la fonction

Pris en charge

Remarques

SQLExecute

SQLExecDirect

SQLNativeSql

SQLDescribeParam

Quel que soit le type de données lié au paramètre, Snowflake effectue une conversion côté serveur et retourne un VARCHAR avec une longueur maximale de 16777216.

SQLNumParams

SQLParamData

Non pris en charge car le streaming n’est pas pris en charge.

SQLPutData

Non pris en charge car le streaming n’est pas pris en charge.

Récupération de résultats et d’informations sur les résultats

Nom de la fonction

Pris en charge

Remarques

SQLBindCol

SQLError

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC. Remplacé par SQLGetDiagRec.

SQLGetData

SQLGetDiagField

SQLGetDiagRec

SQLRowCount

SQLNumResultCols

SQLDescribeCol

SQLColAttribute

SQLColAttributes

Pris en charge par le pilote Snowflake, mais obsolète dans la version 2.x de l’API ODBC. Remplacé par SQLColAttribute.

SQLFetch

SQLFetchScroll

L’argument FetchOrientation prend uniquement en charge la valeur SQL_FETCH_NEXT. Tous les autres types d’extraction échouent.

SQLExtendedFetch

Remplacé par SQLFetchScroll dans le pilote version 3.x de l’API.

SQLSetPos

Snowflake ne prend pas en charge cette fonctionnalité.

SQLBulkOperations

Snowflake ne prend pas en charge cette fonctionnalité.

Obtention d’informations sur les tables système de la source de données (fonctions du catalogue)

Nom de la fonction

Pris en charge

Remarques

SQLColumnPrivileges

Renvoie un ensemble de résultats vide.

SQLColumns

SQLForeignKeys

SQLPrimaryKeys

SQLProcedureColumns

Renvoie un ensemble de résultats vide.

SQLProcedures

Snowflake n’a pas de langage procédural, donc cette fonction renvoie un ensemble de résultats vide.

SQLSpecialColumns

Renvoie un ensemble de résultats vide.

SQLStatistics

Renvoie un ensemble de résultats vide.

SQLTablePrivileges

Renvoie un ensemble de résultats vide.

SQLTables

Si le paramètre transmis à la fonction est « TABLE », la fonction renvoie tous les types de tables, y compris les tables transitoires et les tables temporaires. . . Si le paramètre transmis à la fonction est « VIEW », la fonction renvoie tous les types de vues, y compris les vues matérialisées. . . Si le paramètre transmis à la fonction est « TABLE, VIEW » ou « % », la fonction renvoie des informations sur tous les types de tables et tous les types de vues.

Si le nom transmis à la fonction de catalogue a un caractère non valide ou si le nom ne correspond à aucun objet de base de données, la fonction renvoie un jeu de résultats vide.

Le paramètre SQL_ATTR_METADATA_ID affecte uniquement les fonctions SQLTables et SQLColumns.

Mettre fin à une instruction

Nom de la fonction

Pris en charge

Remarques

SQLFreeStmt

SQLCloseCursor

SQLCancel

SQLEndTran

SQLTransact

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC. Remplacé par SQLEndTran.

Mettre fin à une connexion

Nom de la fonction

Pris en charge

Remarques

SQLCancelHandle

Introduit dans l’API après la version 3.52.

SQLDisconnect

SQLFreeHandle

SQLFreeConnect

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC.

SQLFreeEnv

Pris en charge par le pilote Snowflake, mais obsolète dans la version 3.x de l’API ODBC.

Fonctions diverses

Nom de la fonction

Pris en charge

Remarques

SQLCompleteAsync

Introduit dans l’API après la version 3.52.

Types de données SQL personnalisés

Certains types de données SQL pris en charge par Snowflake n’ont pas de mappage direct dans ODBC (par exemple, TIMESTAMP_*tz, VARIANT). Pour permettre au pilote ODBC de fonctionner avec les types de données non pris en charge, le fichier d’en-tête fourni avec le pilote inclut les définitions des types de données personnalisés suivants :

////////////////////////////////////////////////////////////////////////////////////////////////////
/// Custom SQL Data Type Definition
///
///
////////////////////////////////////////////////////////////////////////////////////////////////////

#define SQL_SF_TIMESTAMP_LTZ 2000
#define SQL_SF_TIMESTAMP_TZ  2001
#define SQL_SF_TIMESTAMP_NTZ 2002
#define SQL_SF_ARRAY         2003
#define SQL_SF_OBJECT        2004
#define SQL_SF_VARIANT       2005

Le code suivant illustre un exemple d’utilisation des types de données personnalisés :

// bind insert as timestamp_ntz
SQLRETURN rc;
rc = SQLPrepare(odbc.StmtHandle,
               (SQLCHAR *) "insert into testtimestampntz values (?)",
               SQL_NTS);

 SQL_TIMESTAMP_STRUCT bindData;
 SQLLEN datalen = sizeof(SQL_TIMESTAMP_STRUCT);
 bindData.year = 2017;
 bindData.month = 11;
 bindData.day = 30;
 bindData.hour = 18;
 bindData.minute = 17;
 bindData.second = 5;
 bindData.fraction = 123456789;

 rc = SQLBindParameter(
   odbc.StmtHandle, 1, SQL_PARAM_INPUT,
   SQL_C_TIMESTAMP, SQL_SF_TIMESTAMP_NTZ,
   100, 0, &bindData, sizeof(bindData), &datalen);

 rc = SQLExecute(odbc.StmtHandle);

 // query table
 rc = SQLExecDirect(odbc.StmtHandle, (SQLCHAR *)"select * from testtimestampntz", SQL_NTS);

 rc = SQLFetch(odbc.StmtHandle);

 // fetch data as timestamp
 SQL_TIMESTAMP_STRUCT ret;
 SQLLEN retLen = (SQLLEN) 0;
 rc = SQLGetData(odbc.StmtHandle, 1, SQL_C_TIMESTAMP, &ret, (SQLLEN)sizeof(ret), &retLen);

Exemples

Cette section fournit des exemples d’utilisation de l’API.

Récupération de l’ID de la dernière requête Snowflake

La récupération de l’ID de la dernière requête est une extension Snowflake au standard ODBC.

Pour récupérer l’ID de la dernière requête, appelez la fonction SQLGetStmtAttr (ou SQLGetStmtAttrW) en transmettant l’attribut SQL_SF_STMT_ATTR_LAST_QUERY_ID et un tableau de caractères suffisamment grand pour contenir l’ID de requête.

L’exemple ci-dessous montre comment récupérer l’ID de requête pour une requête :

// Space to store the query ID.
// The SQLGetStmtAttr() function fills this in with the actual ID.
char queryId[37];   // Maximum 36 chars plus string terminator.

// The length (in characters) of the query ID. The SQLGetStmtAttr() function fills this in
// with the actual length of the query ID (usually 36).
SQLINTEGER idLen;

// Execute a query.
rc = SQLExecDirect(odbc.StmtHandle, (SQLCHAR *) "select 1", SQL_NTS);

// Retrieve the query ID (queryId) and the length of that query ID (idLen).
SQLGetStmtAttr(odbc.StmtHandle, SQL_SF_STMT_ATTR_LAST_QUERY_ID, queryId, sizeof(queryId), &idLen);

Si vous travaillez sous Linux ou macOS, appelez SQLGetStmtAttrW et transmettez les paramètres du type de données approprié (par exemple, « wchar » plutôt que « char »).