16.8.3 SQLNativeSql,SQLNativeSqlW
- 〈この項の構成〉
(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 |
無効な文字列長または無効なバッファ長 |
|
○ |
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が実行できる形式に変換します。変換するのは,{ }で囲まれたエスケープ句内だけです。エスケープ句外は変換しません。
エスケープ句の変換規則を次の表に示します。
対象エスケープ句 |
変換前 |
変換後 |
---|---|---|
日付 |
エスケープ開始子 d 日付データの既定の文字列表現 エスケープ終了子 |
DATE日付データの既定の文字列表現 |
時刻 |
エスケープ開始子 t 時刻データの既定の文字列表現 エスケープ終了子 |
TIME時刻データの既定の文字列表現 |
時刻印 |
エスケープ開始子 ts 時刻印データの既定の文字列表現 エスケープ終了子 |
TIMESTAMP時刻印データの既定の文字列表現 |
LIKE |
エスケープ開始子 escape エスケープ文字 エスケープ終了子 |
escape エスケープ文字 |
外結合 |
エスケープ開始子 oj 結合表 エスケープ終了子 |
結合表 |
スカラ関数 |
エスケープ開始子 fn スカラ関数 エスケープ終了子 |
HADB形式のスカラ関数※ |
- 注※
-
標準形式のスカラ関数を,HADB形式に変換します。
標準形式と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で使用可能な形式に変換します。スカラ関数に指定可能なキーワードを次の表に示します。
スカラ関数 |
指定可能なキーワード |
---|---|
CAST CONVERT |
次のSQLデータ型名を指定できます。
|
TIMESTAMPADD TIMESTAMPDIFF |
次の日時単位キーワードを指定できます。
|
- メモ
-
スカラ関数のエスケープ句内に上記の表のキーワードを指定する場合,大文字および小文字は区別されません。
キーワードの変換規則を次の表に示します。
変換対象キーワード |
変換後の形式 |
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で使用できません。