16.8.3　SQLNativeSql，SQLNativeSqlW : Hitachi Advanced Data Binder AP開発ガイド

(1)　機能

HADB ODBCドライバが修正したSQL文字列を返却します。この関数はSQL文を実行しません。

(2)　形式

SQLNativeSqlの場合

SQLRETURN SQLNativeSql
(
  SQLHDBC         ConnectionHandle,         /* In */
  SQLCHAR       * InStatementText,          /* In */
  SQLINTEGER      TextLength1,              /* In */
  SQLCHAR       * OutStatementText,         /* Out */
  SQLINTEGER      BufferLength,             /* In */
  SQLINTEGER    * TextLength2Ptr            /* Out */
)

SQLNativeSqlWの場合

SQLRETURN SQLNativeSqlW
(
  SQLHDBC         ConnectionHandle,         /* In */
  SQLWCHAR      * InStatementText,          /* In */
  SQLINTEGER      TextLength1,              /* In */
  SQLWCHAR      * OutStatementText,         /* Out */
  SQLINTEGER      BufferLength,             /* In */
  SQLINTEGER    * TextLength2Ptr            /* Out */
)

ページの先頭へ

(3)　引数

ConnectionHandle：

接続ハンドルを指定します。

InStatementText：

変換元のSQL文字列を指定します。SQL文字列中に，注釈（/*〜*/）は指定できませんが，インデクス指定（/*>>〜<<*/）などは指定できます。

TextLength1：

*InStatementTextの長さ^※を指定します。

InStatementTextに指定したSQL文字列がNULL終端文字で終わる場合，SQL_NTSを指定できます。

OutStatementText：

変換後のSQL文字列を返すバッファを指すポインタを指定します。

BufferLength：

*OutStatementTextの長さ^※を指定します。

この長さにNULL終端文字の長さは含まれます。SQL_NTSは指定できません。

TextLength2Ptr：

*OutStatementTextに返す，有効な長さ^※の合計を返すバッファへのポインタを指定します。HADB ODBCドライバはSQL文字列の有効な長さ^※を返します。この長さにNULL終端文字は含まれません。

重要: ここに格納されたSQL文字列の長さ^※が，BufferLengthからNULL終端文字分を引いた長さ^※より大きい場合，OutStatementTextに格納される文字列はBufferLengthからNULL終端文字分を引いた長さ^※に切り捨てられ，末尾にNULL終端文字が付加されます。

注※

長さの単位は，SQLNativeSqlの場合はバイト長，SQLNativeSqlWの場合は文字数となります。

ページの先頭へ

(4)　戻り値

SQL_SUCCESS，SQL_SUCCESS_WITH_INFO，SQL_ERROR，またはSQL_INVALID_HANDLEが返されます。

ページの先頭へ

(5)　SQLSTATE

この関数では次のSQLSTATEを返します。

SQLSTATE	説明	備考	返却
`01000`	一般警告	−	×
`01004`	文字列データの右側が切り捨てられた	`*OutStatementText`バッファの大きさが不足しているため，SQL文字列全体を格納できませんでした（情報が切り捨てられました）。このとき，`SQL_SUCCESS_WITH_INFO`を返します。	○
`01S51`	文字コード変換時に置き換えが発生した	変換できない文字コードを検出し，指定の文字に置き換えました。このとき，`SQL_SUCCESS_WITH_INFO`を返します。	○
`08003`	接続が存在しない	`ConnectionHandle`が接続状態ではありません。	○
`08S01`	通信リンク失敗	−	×
`22007`	無効な日付時刻形式	`*InStatementText`のエスケープ句に，無効な日付，時刻またはタイムスタンプの値が指定されています。	×
`24000`	無効なカーソル状態	ステートメントが指定するカーソルが，結果セットの前または後ろにあります。	×
`5C002`	文字コードの変換エラー	変換できない文字コードを検出しました。	○
`5C051`	SQL文のテキスト文字列の長さが，16,000,000文字を超えた	SQL文のテキスト文字列が16,000,000文字以下の場合でも，ドライバマネージャの文字コード変換によって16,000,000文字を超えることがあります。このときも，この`SQLSTATE`が返されます。	○
`HY000`	一般エラー	−	×
`HY001`	メモリ割り当てエラー	−	×
`HY009`	NULLポインタの不正使用	`*InStatementText`がNULLポインタです。	○
`HY010`	関数シーケンスエラー	−	○
`HY013`	メモリ管理エラー	メモリオブジェクトにアクセスできないため，関数の呼び出しを処理できません。	×
`HY090`	無効な文字列長または無効なバッファ長	`TextLength1`に0より小さく，かつ`SQL_NTS`以外の値が指定されています。 `BufferLength`は0より小さい値ですが，`OutStatementText`はNULLポインタではありません。 `BufferLength`に無効な値（`SQL_NTS`）が指定されました。	○
`HY109`	無効なカーソル位置	カーソルの現在行はすでに削除されているか，またはフェッチできない行です。	×
`HYT01`	接続タイムアウト終了	データソースが要求に応答する前に接続タイムアウト時間が経過しました。接続タイムアウト時間は，`SQLSetConnectAttr`または`SQLSetConnectAttrW`の`SQL_ATTR_CONNECTION_TIMEOUT`で設定できます。	×
`IM001`	ドライバはこの関数をサポートしていない	−	×

（凡例）

○：HADB ODBCドライバが返すことがあるSQLSTATEです。

×：HADB ODBCドライバが返さないSQLSTATEです。

−：なし。

ページの先頭へ

(6)　エスケープ句の構文規則

指定されたSQL文内のエスケープ句を，HADBが実行できる形式に変換して返します。エスケープ句の構文規則を次に示します。

エスケープ句 ::= 日付・時刻・時刻印のエスケープシーケンス
　　　　　　　｜ LIKE述語のエスケープ文字のエスケープシーケンス
　　　　　　　｜ 外結合のエスケープシーケンス
　　　　　　　｜ スカラ関数のエスケープシーケンス
日付・時刻・時刻印のエスケープシーケンス ::= 日付のエスケープシーケンス
　　　　　　　　　　　　　　　　　　｜ 時刻のエスケープシーケンス
　　　　　　　　　　　　　　　　　　｜ 時刻印のエスケープシーケンス
日付のエスケープシーケンス ::=
　　　　　エスケープ開始子 d 日付データの既定の文字列表現 ^※1 エスケープ終了子
時刻のエスケープシーケンス ::=
　　　　　エスケープ開始子 t 時刻データの既定の文字列表現 ^※2 エスケープ終了子
時刻印のエスケープシーケンス ::=
　　　　　エスケープ開始子 ts 時刻印データの既定の文字列表現 ^※3 エスケープ終了子
LIKE述語のエスケープ文字のエスケープシーケンス ::=
　　　　　エスケープ開始子 escape エスケープ文字 エスケープ終了子
外結合のエスケープシーケンス ::= エスケープ開始子 oj 結合表 エスケープ終了子
スカラ関数のエスケープシーケンス ::= エスケープ開始子 fn スカラ関数 エスケープ終了子
スカラ関数 ::= 標準形式のスカラ関数 ^※4
エスケープ開始子 ::= '{'
エスケープ終了子 ::= '}'

注※1: 'YYYY-MM-DD'で表される文字列表現のことです。
注※2: 'hh:mm:ss[.nn....n]'で表される文字列表現のことです。nn....nはp桁の小数秒です。nは0〜9，pは0，3，6，9，または12です。
注※3: 'YYYY-MM-DD hh:mm:ss[.nn....n]'で表される文字列表現のことです。nn....nはp桁の小数秒です。nは0〜9，pは0，3，6，9，または12です。
注※4: 標準形式のスカラ関数については，「表16‒7　標準形式とHADB形式が異なるスカラ関数の変換内容一覧」を参照してください。

なお，下線部には，エスケープ句を指定できません。また，ODBCドライバでは構文解析をしないで，変換後もそのままとし，HADBサーバの構文解析に任せます。

エスケープシーケンスのキーワードを次に示します。キーワードでは，大文字と小文字を区別しません。

日付のエスケープシーケンス内の"d"
時刻のエスケープシーケンス内の"t"
時刻印のエスケープシーケンス内の"ts"
LIKE述語のエスケープ文字のエスケープシーケンス内の"escape"
外結合のエスケープシーケンス内の"oj"
スカラ関数のエスケープシーケンス内の"fn"

エスケープ句の入力規則を次に示します。

エスケープ句内の区切り文字には，半角空白が指定できます。
区切り文字は，エスケープ開始子の後ろ，キーワードの後ろ，およびエスケープ終了子の前に挿入できます。
1つのSQL文中に，複数のエスケープ句を指定できます。
HADB ODBCドライバは指定されたSQL文内のエスケープ句を，HADBが実行できる形式に変換します。変換するのは，｛　｝で囲まれたエスケープ句内だけです。エスケープ句外は変換しません。

エスケープ句の変換規則を次の表に示します。

表16‒6　エスケープ句の変換規則
対象エスケープ句	変換前	変換後
日付	`エスケープ開始子` `d` `日付データの既定の文字列表現エスケープ終了子`	`DATE日付データの既定の文字列表現`
時刻	`エスケープ開始子` `t` `時刻データの既定の文字列表現エスケープ終了子`	`TIME時刻データの既定の文字列表現`
時刻印	`エスケープ開始子` `ts` `時刻印データの既定の文字列表現エスケープ終了子`	`TIMESTAMP時刻印データの既定の文字列表現`
LIKE	`エスケープ開始子` `escape` `エスケープ文字エスケープ終了子`	`escape エスケープ文字`
外結合	`エスケープ開始子` `oj` `結合表エスケープ終了子`	`結合表`
スカラ関数	`エスケープ開始子` `fn` `スカラ関数エスケープ終了子`	`HADB形式のスカラ関数`^※

注※

標準形式のスカラ関数を，HADB形式に変換します。

標準形式とHADB形式が異なるスカラ関数の変換内容を次の表に示します。

基本的に，スカラ関数の引数の個数チェックはしません。

表16‒7　標準形式とHADB形式が異なるスカラ関数の変換内容一覧
スカラ関数	変換前の形式	変換後の形式（HADB形式）
数学関数	`CEILING(number)`	`CEIL(number)`
	`LOG(float)`	`LN(float)`
	`RAND([number,` `number])`	`RANDOM([number,` `number])`
	`TRUNCATE(number[, places])`	`TRUNC(number[,` `places])`
文字列関数	`CHAR(code)`	`CHR(code)`
	`LCASE(string)`	`LOWER(string)`
	`OCTET_LENGTH(string)`	`LENGTHB(string)`
	`SUBSTRING(string, start[,` `length])`	`SUBSTR(string,` `start[, length])`
	`UCASE(string)`	`UPPER(string)`
時刻と日付の関数	`CURRENT_DATE()`	`CURRENT_DATE`
時刻と日付の関数	`CURRENT_TIME()`	`CURRENT_TIME`

スカラ関数のエスケープ句内に指定した特定のスカラ関数の場合，HADBがサポートするデータ型名や日時単位以外にODBC規約に定められたキーワードおよびHADBが独自に定めたキーワードを指定できます。これらのキーワードを指定した場合，ODBCドライバがHADBで使用可能な形式に変換します。スカラ関数に指定可能なキーワードを次の表に示します。

表16‒8　スカラ関数に指定可能なキーワード
スカラ関数	指定可能なキーワード
`CAST` `CONVERT`	次のSQLデータ型名を指定できます。 `SQL_CHAR` `SQL_VARCHAR` `SQL_LONGVARCHAR` `SQL_WCHAR` `SQL_WVARCHAR` `SQL_WLONGVARCHAR` `SQL_DECIMAL` `SQL_NUMERIC` `SQL_TINYINT` `SQL_SMALLINT` `SQL_INTEGER` `SQL_BIGINT` `SQL_REAL` `SQL_FLOAT` `SQL_DOUBLE` `SQL_BIT` `SQL_BINARY` `SQL_VARBINARY` `SQL_LONGVARBINARY` `SQL_DATE` `SQL_TYPE_DATE` `SQL_TIME` `SQL_TYPE_TIME` `SQL_TIMESTAMP` `SQL_TYPE_TIMESTAMP` `SQL_INTERVAL_MONTH` `SQL_INTERVAL_YEAR` `SQL_INTERVAL_YEAR_TO_MONTH` `SQL_INTERVAL_DAY` `SQL_INTERVAL_HOUR` `SQL_INTERVAL_MINUTE` `SQL_INTERVAL_SECOND` `SQL_INTERVAL_DAY_TO_HOUR` `SQL_INTERVAL_DAY_TO_MINUTE` `SQL_INTERVAL_DAY_TO_SECOND` `SQL_INTERVAL_HOUR_TO_MINUTE` `SQL_INTERVAL_HOUR_TO_SECOND` `SQL_INTERVAL_MINUTE_TO_SECOND` `SQL_GUID`
`TIMESTAMPADD` `TIMESTAMPDIFF`	次の日時単位キーワードを指定できます。 `SQL_TSI_DAYOFYEAR` `SQL_TSI_FRAC_SECOND` `SQL_TSI_SECOND` `SQL_TSI_MINUTE` `SQL_TSI_HOUR` `SQL_TSI_DAY` `SQL_TSI_WEEK` `SQL_TSI_MONTH` `SQL_TSI_QUARTER` `SQL_TSI_YEAR`

メモ: スカラ関数のエスケープ句内に上記の表のキーワードを指定する場合，大文字および小文字は区別されません。

キーワードの変換規則を次の表に示します。

表16‒9　キーワードの変換規則
変換対象キーワード	変換後の形式	HADBでの使用可否
`SQL_CHAR`	`CHAR`	〇
`SQL_VARCHAR`	`VARCHAR`	〇
`SQL_LONGVARCHAR`	`SQL_LONGVARCHAR`	×
`SQL_WCHAR`	`SQL_WCHAR`	×
`SQL_WVARCHAR`	`SQL_WVARCHAR`	×
`SQL_WLONGVARCHAR`	`SQL_WLONGVARCHAR`	×
`SQL_DECIMAL`	`DECIMAL`	〇
`SQL_NUMERIC`	`DECIMAL`	〇
`SQL_TINYINT`	`SQL_TINYINT`	×
`SQL_SMALLINT`	`SQL_SMALLINT`	×
`SQL_INTEGER`	`SMALLINT`	〇
`SQL_BIGINT`	`INTEGER`	〇
`SQL_REAL`	`SQL_REAL`	×
`SQL_FLOAT`	`DOUBLE`	〇
`SQL_DOUBLE`	`DOUBLE`	〇
`SQL_BIT`	`SQL_BIT`	×
`SQL_BINARY`	`BINARY`	〇
`SQL_VARBINARY`	`VARBINARY`	〇
`SQL_LONGVARBINARY`	`SQL_LONGVARBINARY`	×
`SQL_DATE`	`DATE`	〇
`SQL_TYPE_DATE`	`DATE`	〇
`SQL_TIME`	`TIME`	〇
`SQL_TYPE_TIME`	`TIME`	〇
`SQL_TIMESTAMP`	`TIMESTAMP`	〇
`SQL_TYPE_TIMESTAMP`	`TIMESTAMP`	〇
`SQL_INTERVAL_MONTH`	`SQL_INTERVAL_MONTH`	×
`SQL_INTERVAL_YEAR`	`SQL_INTERVAL_YEAR`	×
`SQL_INTERVAL_YEAR_TO_MONTH`	`SQL_INTERVAL_YEAR_TO_MONTH`	×
`SQL_INTERVAL_DAY`	`SQL_INTERVAL_DAY`	×
`SQL_INTERVAL_HOUR`	`SQL_INTERVAL_HOUR`	×
`SQL_INTERVAL_MINUTE`	`SQL_INTERVAL_MINUTE`	×
`SQL_INTERVAL_SECOND`	`SQL_INTERVAL_SECOND`	×
`SQL_INTERVAL_DAY_TO_HOUR`	`SQL_INTERVAL_DAY_TO_HOUR`	×
`SQL_INTERVAL_DAY_TO_MINUTE`	`SQL_INTERVAL_DAY_TO_MINUTE`	×
`SQL_INTERVAL_DAY_TO_SECOND`	`SQL_INTERVAL_DAY_TO_SECOND`	×
`SQL_INTERVAL_HOUR_TO_MINUTE`	`SQL_INTERVAL_HOUR_TO_MINUTE`	×
`SQL_INTERVAL_HOUR_TO_SECOND`	`SQL_INTERVAL_HOUR_TO_SECOND`	×
`SQL_INTERVAL_MINUTE_TO_SECOND`	`SQL_INTERVAL_MINUTE_TO_SECOND`	×
`SQL_GUID`	`SQL_GUID`	×
`SQL_TSI_DAYOFYEAR`	`DAYOFYEAR`	〇
`SQL_TSI_FRAC_SECOND`	`NANOSECOND`	〇
`SQL_TSI_SECOND`	`SECOND`	〇
`SQL_TSI_MINUTE`	`MINUTE`	〇
`SQL_TSI_HOUR`	`HOUR`	〇
`SQL_TSI_DAY`	`DAY`	〇
`SQL_TSI_WEEK`	`WEEK`	〇
`SQL_TSI_MONTH`	`MONTH`	〇
`SQL_TSI_QUARTER`	`QUARTER`	〇
`SQL_TSI_YEAR`	`YEAR`	〇

（凡例）

〇：HADBで使用できます。

×：HADBで使用できません。

ページの先頭へ

16.8.3 SQLNativeSql，SQLNativeSqlW

(1) 機能

(2) 形式

(3) 引数

(4) 戻り値

(5) SQLSTATE

(6) エスケープ句の構文規則

16.8.3　SQLNativeSql，SQLNativeSqlW

(1)　機能

(2)　形式

(3)　引数

(4)　戻り値

(5)　SQLSTATE

(6)　エスケープ句の構文規則