SQLGetPosition() - ストリングの開始位置を見つける

SQLGetPosition() は、LOB 値 (ソース) 内の 1 つのストリングの開始位置を戻します。 ソース値は LOB ロケーターでなければなりませんが、検索ストリングは LOB ロケーターでも リテラル・ストリングでも構いません。

ソースおよび検索 LOB ロケーターは、現行トランザクションでのフェッチまたは SQLGetSubString() 呼び出し で、データベースから戻される任意の値が可能です。

SQLGetPosition() の ODBC 仕様

表 1. SQLGetPosition() の仕様
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);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetPosition() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドルを指定します。 これは、どのステートメント・ハンドルでも構いませんが、割り振り済みであっても、現在、 準備済みステートメントがそのハンドルに割り当てられていないハンドルです。
SQLSMALLINT LocatorCType 入力 ソース LOB ロケーターの C タイプを指定します。この引数では、次のいずれかの値を指定する必要があります。
  • SQL_C_BLOB_LOCATOR - BLOB データの場合
  • SQL_C_CLOB_LOCATOR - CLOB データの場合
  • SQL_C_DBCLOB_LOCATOR - DBCLOB データの場合
SQLINTEGER ロケーター 入力 ソース LOB ロケーターを指定します。
SQLINTEGER SearchLocator 入力 検索ストリングを参照する LOB ロケーターを指定します。
次の条件が両方とも満たされない場合は、引数は無視されます。
  • 引数 SearchLiteral が NULL ポインターを指定。
  • 引数 SearchLiteralLength が 0 に設定。
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 出力 常にゼロに設定されます。
注:
  1. これは、DBCLOB データの場合でもバイト単位です。

使用法

SQLGetPosition() を SQLGetSubString() と一緒に使用すると、あるストリングの一部をランダムに 取得できます。SQLGetSubString() を使用するためには、ストリング全体の中のサブストリングのロケーションをあらかじめ知っておく必要があります。 検索ストリングを使用してサブストリングの開始位置を 見つける場合は、SQLGetPosition() を使用します。

引数 Locator および SearchLocator (これらの引数を使用する 場合) には、有効であればどの LOB ロケーターを入れても構いませんが、そのロケーターは、 明示的に解放 (FREE LOCATOR ステートメントを使用して) されていないか、または LOB ロケーター作成時の トランザクションが終了したため暗黙的に解放されていないロケーターです。

引数 Locator および SearchLocator には、同じタイプの LOB ロケーター を指定する必要があります。

ステートメント・ハンドルは、いずれの準備済みステートメント またはカタログ関数呼び出しにも関連付けてはなりません。

戻りコード

SQLGetPosition() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLGetPosition() の SQLSTATE
SQLSTATE 説明 説明
07006 変換が無効です。 引数 LocatorCType で指定した値と、LOB ロケーター値のいずれかとの組み合わせは無効です。
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
0F001 現在 LOB トークン変数は何の値も表していません。 引数 Locator または SearchLocator 用に指定された値は、 現在 LOB ロケーターではありません。
42818 演算子または関数のオペランドに互換性がありません。 検索パターンの長さが 4000 バイトを超えています。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2® ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY009 NULL ポインターの使用は無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 引数 LocatedAt が指定するポインターが NULL です。
  • 引数 FromPosition の引数値が 0 より大きくありません。
  • 引数 LocatorCType は、以下のいずれの値でもありません。
    • SQL_C_CLOB_LOCATOR
    • SQL_C_BLOB_LOCATOR
    • SQL_C_DBCLOB_LOCATOR
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY090 ストリングまたはバッファーの長さが無効です。 SearchLiteralLength の値が 1 より小さく、SQL_NTS ではありません。
HYC00 ドライバーは使用できません。 アプリケーションは、現在、ラージ・オブジェクトをサポートしない データ・ソースに接続されています。

制約事項

この関数を使用できるのは、ラージ・オブジェクトをサポートしている Db2 サーバーに接続されている場合だけです。 引数 fFunction を SQL_API_SQLGETPOSITION に設定して SQLGetFunctions() を 呼び出して、出力引数 fExists をチェックし、この関数が現行の接続でサポート されているかどうかを判別してください。

例

以下の例 は、ラージ・オブジェクトからサブストリング を取り出すアプリケーションを示しています。ラージ・オブジェクトでのこのサブストリングの開始位置を見つけるために、 アプリケーションは SQLGetPosition() を呼び出します。
図 1. ラージ・オブジェクトからサブストリングを取り出すアプリケーション
/* ... */
    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 #:
/* ... */