ODBC (Open Database Connectivity)

ODBC (Open Database Connectivity)は、リレーショナル・データベース・マネージメント・システム (RDBMS) にアクセスするための共通インタフェースです。

ODBCとは

ODBC (Open Database Connectivity) は、リレーショナル・データベース・マネージメント・システム (RDBMS) にアクセスするための共通インタフェースです。

呼び出しレベル・インタフェース (Call Level Interface: CLI) が統一されていることにより、アプリケーションが呼び出すAPIの仕様が、複数の異なるRDBMS間で統一されています。

ハンドル

ODBCアプリケーションでは、データベース接続やSQL文などの基本的な機能をハンドルを使用して定義し、一連のリソースを管理している。

ODBCのハンドル
識別子	説明	データ型
SQL_HANDLE_ENV	環境ハンドル	SQLHENV
SQL_HANDLE_DBC	データベース接続ハンドル	SQLHDBC
SQL_HANDLE_STMT	ステートメント・ハンドル	SQLHSTMT
SQL_HANDLE_DESC	記述子ハンドル	SQLHDESC

ODBC関数の戻り値とエラー処理

ODBC関数の戻り値のデータ型は SQLRETURN である。ODBC関数の戻り値を表す識別子がヘッダファイルで定義されている。ODBC関数の戻り値を次の表に示す。

ODBC関数の戻り値
戻り値	意味	診断情報
SQL_SUCCESS	正常に終了した	なし
SQL_SUCCESS_WITH_INFO	正常に終了した	あり
SQL_NO_DATA_FOUND	これ以上のデータなし	なし
SQL_ERROR	失敗した	あり
SQL_INVALID_HANDLE	無効なハンドルがパラメータとして渡された	なし

ODBC関数呼び出しの戻り値が SQL_ERROR または SQL_SUCCESS_WITH_INFO だった場合、診断情報が生成されます。次のODBC関数を呼び出すことにより、診断情報を取得することができます。

SQLError （ODBCバージョン3より前）
SQLGetDiagRec （ODBCバージョン3以降）

ただし、これらの関数自体が診断情報を生成することはありません。

ハンドルの割り付け

次のODBC関数を呼び出すことにより、ハンドルを割り当てることができます。

SQLAllocEnv, SQLAllocConnect, SQLAllocStmt （ODBCバージョン3より前）
SQLAllocHandle （ODBCバージョン3以降）

ODBCバージョン3より前のバージョンでは、SQLAllocEnvやSQLAllocConnect、SQLAllocStmtのように、割り付けるハンドルの種類ごとに関数が分かれていましたが、ODBCバージョン3からSQLAllocHandle関数に統一されました。

環境ハンドルおよびデータベース接続ハンドルを割り当てる例を次に示します。

SQLHENV henv;
SQLHDBC hdbc;
SQLRETURN rc;

/* 環境ハンドルの割り当て */
rc = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
if (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO) {
  /* データベース接続ハンドルの割り当て */
  rc = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
  if (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO) {
    ...
  }
  /* データベース接続ハンドルの解放 */
  SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
/* 環境ハンドルの解放 */
SQLFreeHandle(SQL_HANDLE_ENV, henv);

データ・ソースへの接続

アプリケーションは、環境ハンドルとデータベース接続ハンドルを割り付けてからデータ・ソースに接続します。接続には、次の3種類のいずれかのODBC関数を使用します。

SQLConnect
SQLDriverConnect
SQLBrowseConnect

SQLConnect関数は最も簡単な接続関数で、データ・ソース名 (DSN)とユーザー名、パスワードを指定して、データ・ソースに接続します。

SQLDriverConnect関数は、接続文字列を指定してデータ・ソースに接続します。接続文字列には、データ・ソース名やユーザー名、パスワードだけでなく、様々な属性を指定することができます。ただし、プラットフォームに依存するため、汎用性が無くなることがあります。

データ・ソースとの接続を確立した後、SQLSetConnectOption関数を使用して、接続オプションを指定することができます。

SQL文の実行

ODBCには、SQL文を実行するために2つの方法が用意されています。

直接実行
準備後の実行

直接実行する場合、SQLExecDirect関数でSQL文を直接実行します。

準備後に実行する場合、あらかじめSQLPrepare関数でSQL文を準備しておき、SQLExecute関数で実行します。同じSQL文を繰り返し実行する場合には、準備しておいたSQL文を実行した方がパフォーマンスが向上します。

結果セットの取り出し

SQL文を実行した後、結果セットを取り出します。

SQLの実行結果（列）とアプリケーション・プログラム変数を関連付けるには、SQLBindCol関数でバインドします。

結果セットから1行ずつ行を取り出すには、SQLFetch関数を使用します。

結果セットからまとめて行を取り出すには、SQLExtendedFetch関数を使用します。

トランザクション制御

ODBCの仕様では、デフォルトで自動コミットが有効になっています。自動コミットのON/OFFを切り替えるには、SQLSetConnectOption関数を使用します。

自動コミットが有効な場合、SQL文を実行するたびに自動的にコミットが行われます。したがって、明示的にコミットを行う必要はありませんが、ロールバックすることができません。

自動コミットが無効な場合、コミットおよびロールバックを明示的に行うことができます。ODBCでは、 COMMIT や ROLLBACK などのSQL文でトランザクション制御は行いません。トランザクション制御は SQLTransact関数で行います。

データベースとの切断

データベースとの切断を行うには、SQLDisconnect関数を使用します。

データベースとの接続を確立する関数には、SQLConnectとSQLDriverConnectの2種類ありますが、どちらを使用して接続した場合でもSQLDisconnect関数で切断することができます。

ハンドルの解放

次のODBC関数を呼び出すことにより、ハンドルを解放することができます。

SQLFreeStmt, SQLFreeConnect, SQLFreeEnv （ODBCバージョン3より前）
SQLFreeHandle （ODBCバージョン3以降）

ODBCバージョン3より前のバージョンでは、SQLFreeConnect関数やSQLFreeEnv関数のように、解放するハンドルの種類ごとに関数が分かれていましたが、ODBCバージョン3からSQLFreeHandle関数に統一されました。

SQLAllocConnect

SQLAllocConnect関数は、データベース接続ハンドルと関連するリソースを割り当てるODBC関数です。SQLAllocConnect関数を呼び出す前に、SQLAllocEnv関数を呼び出して環境ハンドルを割り当てる必要があります。

ODBCバージョン3からは、SQLAllocHandle関数に置き換えられました。

構文

SQLRETURN SQLAllocConnect(
  SQLHENV  henv,
  SQLHDBC *phdbc
);

引数

henv: 環境ハンドルを指定します。
phdbc: データベース接続ハンドルを格納する領域を指すポインターを指定します。SQLAllocConnectが成功すると、データベース接続ハンドルが返されます。

戻り値

SQLAllocConnectは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効な環境ハンドル

SQLAllocEnv

SQLAllocEnv関数は、環境ハンドルと関連するリソースを割り当てるODBC関数です。

ODBCバージョン3からは、SQLAllocHandle関数に置き換えられました。

構文

SQLRETURN SQLAllocEnv(SQLHENV *phenv);

引数

phenv: 環境ハンドルを格納する領域を指すポインターを指定します。SQLAllocEnvが成功すると、環境ハンドルが返されます。

戻り値

SQLAllocEnvは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗

SQLAllocHandle

SQLAllocHandle関数は、ハンドルを割り付けるODBC関数です。

構文

SQLRETURN SQLAllocHandle(
  SQLSMALLINT  iType
  SQLINTEGER   hParent,
  SQLINTEGER  *pHandle
);

引数

iType

割り付けるハンドルの種類を示す識別子を指定します。指定できる識別子は、次のとおりです。

SQLAllocHandle の iType 引数
識別子	ハンドルの種類
SQL_HANDLE_ENV	環境ハンドル
SQL_HANDLE_DBC	データベース接続ハンドル
SQL_HANDLE_STMT	ステートメント・ハンドル
SQL_HANDLE_DESC	記述子ハンドル

hParent

割り付けるハンドルの親項目のハンドルを指定します。割り当てるハンドルの種類と親項目のハンドルとの関係は、次のとおりです。

SQLAllocHandle() の hParent 引数
割り当てるハンドルの種類	親項目のハンドル
環境ハンドル	無し (`SQL_NULL_HANDLE`)
データベース接続ハンドル	環境ハンドル
ステートメント・ハンドル	データベース接続ハンドル

環境ハンドルには親項目が存在しませんので、親項目のハンドルの代わりに、識別子 SQL_NULL_HANDLE を指定します。

pHandle

ハンドルを格納する領域へのポインターを指定します。この引数はプレースホルダです。実際にはSQLINTEGER型のポインタではなく、割り当てるハンドルに応じた型のポインタを指定します。ODBCプログラムに必要なハンドルの型は、次のとおりです。

SQLAllocHandle() の pHandle 引数
項目	ハンドルの型
環境ハンドル	SQLHENV
データベース接続ハンドル	SQLHDBC
ステートメント・ハンドル	SQLHSTMT
記述子ハンドル	SQLHDESC

戻り値

SQLAllocHandle関数の戻り値
戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なハンドル

SQLAllocStmt

SQLAllocStmt() は新規のステートメント・ハンドルを割り当て、このハンドルをデータベース接続ハンドルで指定した接続に関連付けます。 SQLAllocStmt() を呼び出す前に SQLConnect()を呼び出す必要があります。

ODBCバージョン3からは、SQLAllocHandle関数に置き換えられました。

構文

SQLRETURN SQLAllocStmt(
  SQLHDBC   hdbc,
  SQLHSTMT *phstmt
);

引数

hdbc: データベース接続ハンドルを指定します。
phstmt: ステートメント・ハンドルを格納する領域を指すポインターを指定します。SQLAllocStmtが成功すると、ステートメント・ハンドルが返されます。

戻り値

SQLAllocStmtは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なデータベース接続ハンドル

SQLBindCol

SQLBindCol() はアプリケーション・プログラム変数に対して列をバインドします。通常、 SQLBindCol() を呼び出す前に SQLExecDirect()を呼び出します。

構文

SQLRETURN SQLBindCol(
  SQLHSTMT     hstmt,
  SQLSMALLINT  iCol,
  SQLSMALLINT  fType,
  SQLPOINTER   pValue,
  SQLINTEGER   cbValueMax,
  SQLLEN      *pcbValue
);

引数

hstmt

ステートメント・ハンドルを指定します。

iCol

列番号（左から右へ順番に1から番号が付けられている）

fType

アプリケーション・データ・タイプを表す識別子を指定します。次のうちいずれかの識別子を指定します。

SQL_CHAR
SQL_VARCHAR
SQL_NUMERIC
SQL_DECIMAL
SQL_INTEGER
SQL_SMALLINT
SQL_BIGINT
SQL_FLOAT
SQL_REAL
SQL_DOUBLE
SQL_DATATIME
SQL_TYPE_DATE
SQL_TYPE_TIME
SQL_TYPE_TIMESTAMP

pValue

列データが保管されるバッファへのポインタ

cbValueMax

列データの保管に必要なバッファの最大サイズ（バイト単位）

pcbValue

列データのサイズを格納する領域へのポインタ

戻り値

SQLBindColは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なステートメント・ハンドル

SQLConnect

SQLConnect関数は、データベースへの接続を確立するODBC関数です。SQLConnect関数を呼び出す前に、データベース接続ハンドルを割り当てる必要があります。

構文

SQLRETURN SQLConnect(
  SQLHDBC      hdbc,
  SQLCHAR     *szDSN,
  SQLSMALLINT  cbDSN,
  SQLCHAR     *szUID,
  SQLSMALLINT  cbUID,
  SQLCHAR     *szPsw,
  SQLSMALLINT  cbPsw
);

引数

hdbc: データベース接続ハンドルを指定します。
szDSN: データソース名が格納された領域を指すポインターを指定します。
cbDSN: データソース名の長さを指定します。データソース名がNULLで終了している場合は、文字列がNULLで終わっていることを表す識別子SQL_NTSを指定することができます。
szUID: ユーザーIDが格納された領域を指すポインターを指定します。
cbUID: ユーザーIDの長さを指定します。ユーザーIDがNULLで終了している場合は、文字列がNULLで終わっていることを表す識別子SQL_NTSを指定することができます。
szPsw: パスワードが格納された領域を指すポインターを指定します。
cbPsw: パスワードの長さを指定します。パスワードがNULLで終了している場合は、文字列がNULLで終わっていることを表す識別子SQL_NTSを指定することができます。

戻り値

SQLConnectは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なデータベース接続ハンドル

SQLDisconnect

SQLDisconnectは接続ハンドルと関連する接続をクローズします。

構文

SQLRETURN SQLDisconnect(SQLHDBC hdbc);

引数

hdbc: データベース接続ハンドルを指定します。

戻り値

SQLDisconnectは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なデータベース接続ハンドル

SQLDriverConnect

SQLDriverConnect関数は、データベースへの接続を確立するODBC関数で、SQLConnectの代替関数です。

構文

SQLRETURN SQLDriverConnect(
  SQLHDBC      hdbc,
  SQLHWND      hWindow,
  SQLCHAR     *szConnStr,
  SQLSMALLINT  cbConnnStr,
  SQLCHAR     *szConnOut,
  SQLSMALLINT  cbConnOutMax,
  SQLSMALLINT *pcbConnOut,
  SQLSMALLINT  fDriverConpletion
);

引数

hdbc

データベース接続ハンドルを指定します。

hWindow

ウィンドウ・ハンドル（プラットフォーム依存）

szConnStr

接続文字列を指定します。接続文字列は「 属性 = 値 」の形式で属性を指定した文字列です。セミコロン記号で区切ることにより、複数の属性を列挙することができます。属性には次のようなものがあります（プラットフォームに依存）。

接続文字列の属性
属性	説明
DSN	データ・ソース名
UID	ユーザーID
PWD	ユーザーIDに対応したパスワード

cbConnnStr

接続文字列の長さを指定します。

szConnOut

完了接続文字列を格納する領域を指すポインターを指定します。データ・ソースへの接続に成功すると、引数 szConnOut で指定したバッファに、完了した接続文字列が格納されます。

cbConnOutMax

完了接続文字列を格納するバッファの最大サイズ

pcbConnOut

完了接続文字列のサイズ

fDriverConpletion

ユーザーにプロンプトで要求すればよいかを指定します。引数 fDriverConpletion に指定できる識別子を次に示します。

SQL_DRIVER_COMPLETE
SQL_DRIVER_COMPLETE_REQUIRED
SQL_DRIVER_NOPROMPT

戻り値

SQLDriverConnectは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なデータベース接続ハンドル
SQL_NO_DATA_FOUND	データが無い

使用例

SQLRETURN   rc;
SQLHDBC     hDbc;
SQLCHAR     szConnStr[] = "DSN=SalesDB;UID=scott;PWD=tiger;";
SQLCHAR     szConnOut[255];
SQLSMALLINT cbConnOut;

rc = SQLDriverConnect(hDbc,
                    NULL
                    szConnStr,
                    SQL_NTS,
                    szConnOut,
                    255,
                    &cbConnOut,
                    SQL_DRIVER_NOPROMPT);

SQLError

SQLError 関数は、診断情報を取得します。他の関数呼び出しの戻り値がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOだったときに、情報を取得できます。

ODBCバージョン3からは、SQLGetDiagRec関数に置き換えられました。

構文

SQLRETURN SQLError(
  SQLHENV      henv,
  SQLHDBC      hdbc,
  SQLHSTMT     hstmt,
  SQLCHAR     *szSqlState,
  SQLINTEGER  *pfNativeError,
  SQLCHAR     *szErrorMsg,
  SQLSMALLINT  cbErroMsgMax,
  SQLSMALLINT *pcbErrorMsg
);

引数

henv: 環境ハンドルを指定します。
hdbc: データベース接続ハンドルを指定します。
hstmt: ステートメント・ハンドルを指定します。
szSqlState: 状態値
pfNativeError: 元のエラー・コード
szErrorMsg: メッセージ文字列を格納する領域を指すポインターを指定します。SQLErrorが成功すると、メッセージ文字列が返されます。
cbErrorMsgMax: メッセージ文字列を格納する領域の最大サイズを指定します。SQL_MAX_MESSAGE_LENGTH + 1 より小さい値を指定したときは、エラー・メッセージが途中で切り捨てられる場合があります。
pcbErrorMsg: メッセージ文字列のバイト数を格納する領域を指すポインターを指定します。SQLErrorが成功すると、メッセージ文字列のバイト数が返されます。

戻り値

SQLErrorは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なハンドル
SQL_NO_DATA_FOUND	エラー無し

SQLExecDirect

SQLExecDirect関数は、指定されたSQLステートメントを直接実行するODBC関数です。

構文

SQLRETURN SQLExecDirect(
  SQLHSTMT   hstmt,
  SQLCHAR    szSqlStr,
  SQLINTEGER cbSqlStr
);

引数

hstmt: ステートメント・ハンドルを指定します。
szSqlStr: SQLステートメント文字列が格納された領域を指すポインターを指定します。
cbSqlStr: SQLステートメント文字列の長さを指定します。SQLステートメント文字列がNULLで終了している場合は、文字列がNULLで終わっていることを表す識別子SQL_NTSを指定することができます。

戻り値

SQLExecDirectは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なステートメント・ハンドル
SQL_NO_DATA_FOUND	SQL文の検索条件に合う行が無い

SQLExecute

SQLExecute関数は、SQLPrepare関数で準備されたSQL文を実行するODBC関数です。

構文

SQLRETURN SQLExecute(SQLHSTMT hstmt);

引数

hstmt: ステートメント・ハンドルを指定します。

戻り値

SQLExecuteは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なステートメント・ハンドル
SQL_NO_DATA_FOUND	SQL文の検索条件に合う行が無い

SQLExtendedFetch

SQLExtendedFetch関数は、各バインド列ごとに複数の行が入った行セットを戻すことで、SQLFetch関数の機能を拡張をします。

構文

SQLRETURN SQLExtendedFetch(
  SQLHSTMT     hstmt,
  SQLSMALINT   fFetchOrientation,
  SQLINTEGER   FetchOffset,
  SQLINTEGER  *pRowCount,
  SQLSMALLINT *RowStatusArray
);

引数

hstmt: ステートメント・ハンドルを指定します。
fFetchOrientation: 取り出しの方向
FetchOffset: 未使用（予約済み）
pRowCount: 取り出した行の数を格納する領域を指すポインターを指定します。SQLExtendedFetchが成功すると、取り出した行の数が返ります。
RowStatusArray: 状況値の配列

戻り値

SQLExtendedFetchは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なステートメント・ハンドル
SQL_NO_DATA_FOUND	結果セットに行が無い

SQLFreeConnect

SQLFreeConnect関数は、SQLAllocConnect関数で割り付けた接続ハンドルを解放するODBC関数です。

ODBCバージョン3からは、SQLFreeHandle関数に置き換えられました。

構文

SQLRETURN SQLFreeConnect(SQLHDBC hdbc);

引数

hdbc: 解放するデータベース接続ハンドルを指定します。

戻り値

SQLFreeConnectは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なデータベース接続ハンドル

SQLFetch

SQLFetch() は結果セットの次の行にカーソルを進め、バインド列を更新します。

構文

SQLRETURN SQLFetch(SQLHSTMT hstmt);

引数

hstmt: ステートメント・ハンドルを指定します。

戻り値

SQLFetchは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なステートメント・ハンドル
SQL_NO_DATA_FOUND	結果セットに行が無いか、結果セットの全ての行の取り出しが完了した

SQLFreeEnv

SQLFreeEnv関数は、SQLAllocEnv関数で割り付けた環境ハンドルを解放するODBC関数です。

ODBCバージョン3からは、SQLFreeHandle関数に置き換えられました。

構文

SQLRETURN SQLFreeEnv(SQLHENV henv);

引数

henv: 解放する環境ハンドルを指定します。

戻り値

SQLFreeEnvは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効な環境ハンドル

SQLFreeHandle

SQLFreeHandle 関数は、SQLAllocHandle関数で割り付けたハンドルを解放するODBC関数です。

構文

SQLRETURN SQLFreeHandle(
  SQLSMALLINT iType,
  SQLINTEGER  iHandle
);

引数

iType

解放するハンドルの種類を示す識別子を指定します。指定できる識別子は、次のとおりです。

開放するハンドルの種類
識別子	ハンドルの種類
SQL_HANDLE_ENV	環境ハンドル
SQL_HANDLE_DBC	接続ハンドル
SQL_HANDLE_STMT	ステートメント・ハンドル
SQL_HANDLE_DESC	記述子ハンドル

iHandle

解放するハンドルを指定します。

戻り値

SQLFreeHandleは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なハンドル

SQLFreeStmt

SQLFreeStmt() はステートメント・ハンドルを解放します。 SQLFreeStmt() を呼び出す前に SQLAllocStmt()を呼び出す必要があります。

構文

SQLRETURN SQLFreeStmt(
  SQLHSTMT    hstmt,
  SQLSMALLINT fOption
);

引数

hstmt

解放するステートメント・ハンドルを指定します。

fOption

オプションを指定します。次の識別子のうち、いずれかを指定します。

オプション
識別子	説明
SQL_CLOSE	ステートメント・ハンドルをクローズして、保留中の結果は破棄する。

戻り値

SQLFetchは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なステートメント・ハンドル

SQLGetDiagRec

SQLGetDiagRec関数は、診断情報を取得します。他のODBC関数呼び出しの戻り値がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOだったときに、診断情報を取得できます。

構文

SQLRETURN SQLGetDiagRec(
  SQLSMALLINT  iType,
  SQLINTEGER   handle,
  SQLSMALLINT  recNum,
  SQLCHAR     *szSqlState,
  SQLINTEGER  *pfNativeError,
  SQLCHAR     *szErrorMsg,
  SQLSMALLINT  cbErroMsgMax,
  SQLSMALLINT *pcbErrorMsg
);

引数

iType

診断情報を取得するハンドルの種類を示す識別子を指定します。指定できる識別子は、次のとおりです。

ハンドルの種類
識別子	ハンドルの種類
SQL_HANDLE_ENV	環境ハンドル
SQL_HANDLE_DBC	接続ハンドル
SQL_HANDLE_STMT	ステートメント・ハンドル
SQL_HANDLE_DESC	記述子ハンドル

handle

診断情報が必要なハンドルを指定します。

recNum

エラー・レコード番号（最初が1）

szSqlState

状態値

pfNativeError

元のエラー・コード

szErrorMsg

メッセージ文字列を格納する領域を指すポインターを指定します。SQLGetDiagRecが成功すると、メッセージ文字列が返されます。

cbErrorMsgMax

メッセージ文字列を格納する領域の最大サイズを指定します。引数 cbErrorMsgMax にSQL_MAX_MESSAGE_LENGTH + 1 より小さい値を指定したときは、エラー・メッセージが途中で切り捨てられる場合があります。

pcbErrorMsg

メッセージ文字列のバイト数を格納する領域を指すポインターを指定します。SQLGetDiagRecが成功すると、メッセージ文字列のバイト数が返されます。

戻り値

SQLGetDiagRecは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なハンドル
SQL_NO_DATA_FOUND	エラー無し

SQLGetInfo

SQLGetInfoは、一般情報を取得するODBC関数です。

構文

SQLRETURN SQLGetInfo(
  SQLHDBC     hdbc,
  SQLSMALLINT fInfoType,
  SQLPOINTER  pInfoValue,
  SQLSMALLINT cbInfoValueMax,
  SQLSMALLINT *pcbInfoValue
);

引数

hdbc

データベース接続ハンドルを指定します。

fInfoType

取得する情報の種類を指定します。

取得する情報の種類
値	形式	説明
SQL_DATA_SOURCE_NAME	文字列	接続先のデータソース名
SQL_DBMS_NAME	文字列	DBMSの製品名

使用するDBMS固有の情報タイプを指定できることがあります。

pInfoValue

取得した情報を格納する領域へのポインターを指定します。

cbInfoValueMax

引数 pInfoValue が指す領域のサイズを指定します。

pcbInfoValue

取得した情報のサイズを格納する領域へのポインターを指定します。取得した情報が文字列の場合は、終端のNULLを含まないサイズを返します。

戻り値

SQLGetInfoは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なデータベース接続ハンドル

SQLPrepare

SQLPrepare関数は、SQL文を準備するODBC関数です。準備したSQL文は、SQLExecute関数で実行することができます。

構文

SQLRETURN SQLPrepare(
  SQLHSTMT   hstmt,
  SQLCHAR    szSqlStr,
  SQLINTEGER cbSqlStr
);

引数

hstmt: ステートメント・ハンドルを指定します。
szSqlStr: SQLステートメント文字列が格納された領域を指すポインターを指定します。
cbSqlStr: SQLステートメント文字列の長さを指定します。SQLステートメント文字列がNULLで終了している場合は、文字列がNULLで終わっていることを表す識別子SQL_NTSを指定することができます。

戻り値

SQLPrepareは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なステートメント・ハンドル

SQLSetConnectOption

SQLSetConnectOption関数は、接続オプションを指定するODBC関数です。

構文

SQLRETURN SQLSetConnectOption(
  SQLHDBC     hdbc,
  SQLSMALLINT fOption,
  SQLPOINTER  pvParam
);

引数

hdbc

データベース接続ハンドルを指定します。

fOption

接続オプション。OCIヘッダファイル内で定義されているマクロの識別子を指定する。指定できる識別子を次の表に示す。

接続オプション
識別子	意味
SQL_AUTOCOMMIT	自動コミットのON/OFFを指定します。ODBCの仕様では、自動コミットはONがデフォルトです。

pvParam

接続オプションに設定する値を指定します。指定できる値は、引数 fOption によって異なります。

引数 fOption にSQL_AUTOCOMMITを指定した場合は、次の値を指定することができます。

接続オプションに設定する値
識別子	意味
SQL_AUTOCOMMIT_ON	自動コミットON
SQL_AUTOCOMMIT_OFF	自動コミットOFF

戻り値

SQLSetConnectOptionは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_SUCCESS_WITH_INFO	成功（警告あり）
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なデータベース接続ハンドル

SQLTransact

SQLTransact関数は、接続中の現在のトランザクションをコミットまたはロールバックするODBC関数です。

構文

SQLRETURN SQLTransact(
  SQLHENV     henv,
  SQLHDBC     hdbc,
  SQLSMALLINT fType
);

引数

henv

環境ハンドルを指定します。

hdbc

データベース接続ハンドルを指定します。

fType

コミット又はロールバックの種別を表す識別子を指定します。

コミット又はロールバックの種別
識別子	意味
SQL_COMMIT	コミット
SQL_ROLLBACK	ロールバック

戻り値

SQLTransactは次に示すSQLRETURN型の戻り値を返す。

戻り値	説明
SQL_SUCCESS	成功
SQL_ERROR	失敗
SQL_INVALID_HANDLE	無効なハンドル