SQLGetPosition() - ストリングの開始位置を見つける
SQLGetPosition() は、LOB 値 (ソース) 内の 1 つのストリングの開始位置を戻します。 ソース値は LOB ロケーターでなければなりませんが、検索ストリングは LOB ロケーターでも リテラル・ストリングでも構いません。
ソースおよび検索 LOB ロケーターは、現行トランザクションでのフェッチまたは SQLGetSubString() 呼び出し で、データベースから戻される任意の値が可能です。
SQLGetPosition() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| なし | なし | なし |
構文
SQLRETURN SQLGetPosition (SQLHSTMT hstmt,
SQLSMALLINT LocatorCType,
SQLINTEGER SourceLocator,
SQLINTEGER SearchLocator,
SQLCHAR FAR *SearchLiteral,
SQLINTEGER SearchLiteralLength,
SQLUINTEGER FromPosition,
SQLUINTEGER FAR *LocatedAt,
SQLINTEGER FAR *IndicatorValue);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドルを指定します。 これは、どのステートメント・ハンドルでも構いませんが、割り振り済みであっても、現在、 準備済みステートメントがそのハンドルに割り当てられていないハンドルです。 |
| SQLSMALLINT | LocatorCType | 入力 | ソース LOB ロケーターの C タイプを指定します。この引数では、次のいずれかの値を指定する必要があります。
|
| SQLINTEGER | ロケーター | 入力 | ソース LOB ロケーターを指定します。 |
| SQLINTEGER | SearchLocator | 入力 | 検索ストリングを参照する LOB ロケーターを指定します。
次の条件が両方とも満たされない場合は、引数は無視されます。
|
| SQLCHAR * | SearchLiteral | 入力 | この引数は、検索ストリング・リテラルを入れることができるストレージ域を
指します。
SearchLiteralLength が 0 の場合、このポインターは NULL でなければなりません。 |
| SQLINTEGER | SearchLiteralLength | 入力 | SearchLiteral のストリングの長さ (バイト)。1 この引数の値が 0 の場合、LOB ロケーターを用いて検索ストリングを指定し ます。(引数 SearchLocator は、LOB ロケーターによって表される場合は、 検索ストリングを指定します。) |
| SQLUINTEGER | FromPosition | 入力 | BLOB および CLOB の場合、この引数は、ソース・ストリング内で検索が開始される バイト位置を指定します。DBCLOB の場合は、この引数は、検索が開始される文字を指定します。 開始バイト または開始文字には番号 1 が付けられます。 |
| SQLUINTEGER * | LocatedAt | 出力 | 検索ストリングが見つかった位置を指定します。BLOB および CLOB の場合、これのロケーションはバイト位置
です。DBCLOB の場合、これロケーションは文字位置です。
検索ストリングが見つからなかった場合は、この引数はゼロを戻します。
ソース・ストリングの長さがゼロの場合、値 1 が戻されます。 |
| SQLINTEGER * | IndicatorValue | 出力 | 常にゼロに設定されます。 |
| 注:
|
|||
使用法
SQLGetPosition() を SQLGetSubString() と一緒に使用すると、あるストリングの一部をランダムに 取得できます。SQLGetSubString() を使用するためには、ストリング全体の中のサブストリングのロケーションをあらかじめ知っておく必要があります。 検索ストリングを使用してサブストリングの開始位置を 見つける場合は、SQLGetPosition() を使用します。
引数 Locator および SearchLocator (これらの引数を使用する 場合) には、有効であればどの LOB ロケーターを入れても構いませんが、そのロケーターは、 明示的に解放 (FREE LOCATOR ステートメントを使用して) されていないか、または LOB ロケーター作成時の トランザクションが終了したため暗黙的に解放されていないロケーターです。
引数 Locator および SearchLocator には、同じタイプの LOB ロケーター を指定する必要があります。
ステートメント・ハンドルは、いずれの準備済みステートメント またはカタログ関数呼び出しにも関連付けてはなりません。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 07006 | 変換が無効です。 | 引数 LocatorCType で指定した値と、LOB ロケーター値のいずれかとの組み合わせは無効です。 |
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 0F001 | 現在 LOB トークン変数は何の値も表していません。 | 引数 Locator または SearchLocator 用に指定された値は、 現在 LOB ロケーターではありません。 |
| 42818 | 演算子または関数のオペランドに互換性がありません。 | 検索パターンの長さが 4000 バイトを超えています。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2® ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY009 | NULL ポインターの使用は無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | SearchLiteralLength の値が 1 より小さく、SQL_NTS ではありません。 |
| HYC00 | ドライバーは使用できません。 | アプリケーションは、現在、ラージ・オブジェクトをサポートしない データ・ソースに接続されています。 |
制約事項
この関数を使用できるのは、ラージ・オブジェクトをサポートしている Db2 サーバーに接続されている場合だけです。 引数 fFunction を SQL_API_SQLGETPOSITION に設定して SQLGetFunctions() を 呼び出して、出力引数 fExists をチェックし、この関数が現行の接続でサポート されているかどうかを判別してください。
例
/* ... */
SQLCHAR stmt2[] =
"SELECT resume FROM emp_resume "
"WHERE empno = ? AND resume_format = 'ascii'";
/* ... */
/******************************************************************
** Get CLOB locator to selected resume **
*******************************************************************/
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
7, 0, Empno.s, sizeof(Empno.s), &Empno.ind);
printf("¥n>Enter an employee number:¥n");
gets(Empno.s);
rc = SQLExecDirect(hstmt, stmt2, SQL_NTS);
rc = SQLBindCol(hstmt, 1, SQL_C_CLOB_LOCATOR, &ClobLoc1, 0,
&pcbValue);
rc = SQLFetch(hstmt);
/******************************************************************
Search CLOB locator to find "Interests"
Get substring of resume (from position of interests to end)
*******************************************************************/
rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &lhstmt);
/* Get total length */
rc = SQLGetLength(lhstmt, SQL_C_CLOB_LOCATOR, ClobLoc1, &SLength, &Ind);
/* Get Starting position */
rc = SQLGetPosition(lhstmt, SQL_C_CLOB_LOCATOR, ClobLoc1, 0,
"Interests", 9, 1, &Pos1, &Ind);
buffer = (SQLCHAR *)malloc(SLength - Pos1 + 1);
/* Get just the "Interests" section of the Resume CLOB */
/* (From Pos1 to end of CLOB) */
rc = SQLGetSubString(lhstmt, SQL_C_CLOB_LOCATOR, ClobLoc1, Pos1,
SLength - Pos1, SQL_C_CHAR, buffer, SLength - Pos1 +1,
&OutLength, &Ind);
/* Print Interest section of Employee's resume */
printf("¥nEmployee #:
/* ... */