OCI SODA関数

関数	用途
`OCISodaBulkInsert()`	コレクションにドキュメント配列を挿入します。
`OCISodaBulkInsertAndGet()`	コレクションにドキュメント配列を挿入し、結果ドキュメント配列を取得します。
`OCISodaBulkInsertAndGetWithOpts ()`	オプション付きSODAドキュメントを複数挿入します。
`OCISodaBulkInsertAndGetWithCtnt()`	コレクションにドキュメント配列を挿入し、結果ドキュメント配列を取得します。入力ドキュメントは、コンテンツ文字列の配列およびキーの配列として表されます。
`OCISodaBulkInsertWithCtnt()`	コレクションにドキュメントの配列を挿入します。ドキュメントは、コンテンツ文字列の配列およびキーの配列として表されます。
`OCISodaCollCreate()`	デフォルトのメタデータ設定を使用して、新規ドキュメント・コレクションを作成します。
`OCISodaCollCreateWithMetadata()`	メタデータを使用して、新規ドキュメント・コレクションを作成します。
`OCISodaCollDrop()`	データベースからコレクションを削除します。
`OCISodaCollGetNext()`	コレクション・カーソルから次のコレクションを取得します。
`OCISodaCollList()`	指定されたサービス・コンテキスト・ハンドル・パラメータに関連付けられているスキーマ内のコレクションをリストします。
`OCISodaCollOpen()`	コレクションを開きます。
`OCISodaDataGuideGet()`	JSONデータ・ガイド情報を取得します。
`OCISodaDataGuideGetWithOpts ()`	オプション付きデータ・ガイドを取得します。
`OCISodaDocCount()`	コレクションからのドキュメントの数をカウントします。
`OCISodaDocCountWithFilter()`	例による問合せ(QBE)フィルタ・ドキュメントに基づいて、コレクション内のドキュメントの数をカウントします。
`OCISodaDocCreate()`	ドキュメントを作成します。
`OCISodaDocCreateWithKey()`	ドキュメント・キーおよびコンテンツを含むドキュメントを作成します。
`OCISodaDocCreateWithKeyAndMType()`	ドキュメント・キー、コンテンツおよびメディア・タイプを含むドキュメントを作成します。
`OCISodaDocGetNext()`	コレクション内の次のドキュメントを取得します。
`OCISodaFind()`	コレクション内のドキュメントを検索します。
`OCISodaFindOne()`	コレクション内の単一のドキュメントを検索します。
`OCISodaFindOneWithKey()`	指定されたキーに基づいて、コレクション内の単一のドキュメントを検索します。
`OCISodaIndexCreate()`	索引仕様を使用して索引を作成します。
`OCISodaIndexDrop()`	索引を削除します。
`OCISodaInsert()`	コレクションにドキュメントを挿入します。
`OCISodaInsertAndGet()`	ドキュメントをコレクションに挿入し、結果ドキュメントを戻します。
`OCISodaInsertAndGetWithOpts ()`	オプション付きSODAドキュメントを挿入します。
`OCISodaInsertAndGetWithCtnt()`	ドキュメントをコレクションに挿入し、結果ドキュメントを戻します。入力ドキュメントは、コンテンツ文字列およびキーとして表されます
`OCISodaInsertWithCtnt()`	コレクションにドキュメントを挿入します。ドキュメントは、コンテンツ文字列およびキーとして表されます
`OCISodaRemove()`	一致するドキュメントをコレクションから削除します。
`OCISodaRemoveOneWithKey()`	指定されたキーに基づいて、コレクションからドキュメントを削除します。
`OCISodaReplOne()`	コレクション内のドキュメントを置き換えます。
`OCISodaReplOneAndGet()`	コレクション内のドキュメントを置き換えます。入力ドキュメントは、コンテンツ文字列によってのみ表されます。
`OCISodaReplOneAndGetWithCtnt()`	コレクション内のドキュメントを置き換え、結果ドキュメントを取得します。入力ドキュメントは、コンテンツ文字列によってのみ表されます。
`OCISodaReplOneAndGetWithKey()`	指定されたキーに基づいてコレクション内のドキュメントを置き換え、結果ドキュメントを戻します。
`OCISodaReplOneWithCtnt()`	コレクション内のドキュメントを置き換えます。ドキュメントは、コンテンツ文字列によってのみ表されます。
`OCISodaReplOneWithKey()`	指定されたキーに基づいて、コレクション内のドキュメントを置き換えます。
`OCISodaSave()`	ドキュメントをコレクションに保存します。
`OCISodaSaveAndGet()`	ドキュメントをコレクションに保存し、メタデータ情報を含むドキュメントを戻します。
`OCISodaSaveAndGetWithOpts ()`	オプション付きSODAドキュメントを保存します。
`OCISodaOperKeysSet()`	操作オプション・ハンドルのキーの配列を設定します。

36.2.1 OCISodaBulkInsert()

コレクションにドキュメントの配列を挿入します。

用途

コレクションにドキュメントの配列を挿入します。

構文

sword OCISodaBulkInsert(OCISvcCtx            *svchp,
                        OCISodaColl          *collection,
                        OCISodaDoc          **documentarray,
                        ub4                   arraylen,
                        OCISodaOutputOptions *opoptns,
                        OCIError             *errhp,
                        ub4                   mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
documentarray (IN)	コレクションに挿入するドキュメントのハンドルの配列です。
arrarylen (IN)	`documentarray`パラメータに指定されたドキュメント・ハンドル配列の長さです。
opoptns (OUT)	出力オプション・ハンドルです。次の属性が有効です。 `OCI_ATTR_SODA_DOC_COUNT`—挿入されたドキュメントの数です。ノート: エラーが発生した場合、`OCI_ATTR_SODA_DOC_COUNT`にはエラー発生前に挿入されたドキュメントの数が含まれます。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメント配列の挿入に成功した場合は、OCI_SUCCESSです。

ドキュメント配列の挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.2 OCISodaBulkInsertAndGet()

ドキュメントの配列をコレクションに挿入し、コンテンツを除くすべてのドキュメント・コンポーネントを含む結果ドキュメントの配列を戻します。

用途

ドキュメントの配列をコレクションに挿入し、結果ドキュメントの配列を戻します。結果ドキュメントには、コンテンツを除くすべてのドキュメント・コンポーネントが含まれます。挿入中にSODAで生成されたコンポーネント(キー(自動で割り当てられたキーがコレクションにある場合)、最終変更のタイムスタンプ、作成時のタイムスタンプ、バージョンなど)は、結果ドキュメントとともに戻されます。

構文

sword OCISodaBulkInsertAndGet(OCISvcCtx            *svchp,
                              OCISodaColl          *collection,
                              OCISodaDoc          **documentarray,
                              ub4                   arraylen,
                              OCISodaOutputOptions *opoptns,
                              OCIError             *errhp,
                              ub4                   mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
documentarray (IN/OUT)	コレクションに挿入するドキュメントのハンドルの配列です。ノート: 結果ドキュメントは同じパラメータを使用して返されるため、後で`OCIHandleFree()`メソッドを使用して各結果ドキュメント・ハンドルとともに入力ドキュメント・ハンドルを解放できるように、各入力ドキュメント・ハンドルへの参照を保存する必要があります。各入力ドキュメント・ハンドルへの参照を保存しない場合、その参照は結果ドキュメントへの参照で上書きされ、入力ドキュメント・ハンドルが正しく解放されなくなります(メモリー・リークにつながります)。
arrarylen (IN)	`documentarray`パラメータに指定されたドキュメント・ハンドル配列の長さです。
opoptns (OUT)	出力オプション・ハンドルです。次の属性が有効です。 `OCI_ATTR_SODA_DOC_COUNT`: 挿入されたドキュメントの数です。エラーが発生した場合、`OCI_ATTR_SODA_DOC_COUNT`には、エラー発生前に挿入されたドキュメントの数が含まれます。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメント配列の挿入に成功した場合は、OCI_SUCCESSです。

ドキュメント配列の挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.3 OCISodaBulkInsertAndGetWithOpts()

オプション付きSODAドキュメントを複数挿入します。

用途

オプション付きSODAドキュメントを複数挿入します。

構文

sword OCISodaBulkInsertAndGetWithOpts(OCISvcCtx                 *svchp,
                                      OCISodaColl               *collection,
                                      OCISodaDoc               **documentarray,
                                      ub4                        arraylen,
                                      OCISodaOperationOptions   *oproptns,
                                      OCISodaOutputOptions      *opoptns,
                                      OCIError                  *errhp,
                                      ub4                        mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
collection (IN)	挿入するコレクション・ハンドルです。
documentarray (IN/OUT)	挿入するドキュメント配列です。
arrarylen (IN)	挿入するドキュメント配列の長さです。
oproptns (IN)	操作オプション・ハンドルです。
opoptns (OUT)	出力オプション・ハンドルです。
errhp (IN)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

OCI_SUCCESS (ドキュメントが挿入されていた場合)。

36.2.4 OCISodaBulkInsertAndGetWithCtnt()

ドキュメントの配列を、そのコンテンツのみを使用してコレクションに挿入し、コンテンツを除くすべてのドキュメント・コンポーネントを含む結果ドキュメントの配列を戻します。

用途

ドキュメントの配列を、そのコンテンツのみを使用してコレクションに挿入し、結果ドキュメントの配列を戻します。各結果ドキュメントには、コンテンツを除くすべてのドキュメント・コンポーネントが含まれます。

ノート:

これは、ドキュメント・ハンドルを作成せずにJSONドキュメントを挿入する便利なメソッドです。より一般的なメソッドはOCISodaBulkInsertAndGetです。

構文

sword OCISodaBulkInsertAndGetWithCont(OCISvcCtx             *svchp,
                                      OCISodaColl           *collection,
                                      void                 **contentStrings,
                                      ub4                   *contentStringLengths,
                                      OraText              **keys,
                                      ub4                   *keyLengths,
                                      ub4                    arrayLength,
                                      ub4                    docFlags,
                                      OCISodaDoc           **documents,
                                      OCISodaOutputOptions  *opoptns,
                                      OCIError              *errhp
                                      ub4                    mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
contentStrings (IN)	ドキュメントのJSONコンテンツを含む文字列の配列です。ノート: このメソッドは、JSONドキュメントに対してのみ機能します。
contentStringLengths (IN)	コンテンツ文字列の配列の長さです。
keys (IN)	挿入されたドキュメントのキーの配列です。コレクションにクライアント割当てキーがある場合は、キーを指定します。それ以外の場合は、NULLに設定します。
keyLengths (IN)	キーの長さの配列です。コレクションにクライアント割当てキーがある場合にのみ設定する必要があります。それ以外の場合は、NULLに設定する必要があります。
arrayLength (IN)	`contentStrings`配列と`keys`配列の長さです。
docFlags (IN)	指定されたドキュメントのコンテンツのエンコーディングを指定するために使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
documents (OUT)	コンテンツ以外のすべてのドキュメント・コンポーネントを含む結果ドキュメントの配列を戻します。各結果ドキュメントには、SODAの挿入コマンドによって生成されたキー(自動で割り当てられたキーがコレクションにある場合)、最終変更のタイムスタンプ、作成時のタイムスタンプ、バージョンなどのコンポーネントが含まれます。
opoptns (OUT)	出力オプション・ハンドルを指定します。次の属性が有効です。 `OCI_ATTR_SODA_DOC_COUNT`—挿入されたドキュメントの数です。ノート: エラーが発生した場合、`OCI_ATTR_SODA_DOC_COUNT`にはエラー発生前に挿入されたドキュメントの数が含まれます。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの挿入に成功した場合は、OCI_SUCCESSです。

ドキュメントの挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.5 OCISodaBulkInsertWithCtnt()

ドキュメントの配列を、そのコンテンツのみを使用してコレクションに挿入します。

用途

ドキュメントの配列を、そのコンテンツのみを使用してコレクションに挿入します。

ノート:

これは、ドキュメント・ハンドルを作成せずにJSONドキュメントを挿入する便利なメソッドです。より一般的なメソッドはOCISodaBulkInsertです。

構文

sword OCISodaBulkInsertWithCtnt(OCISvcCtx            *svchp,
                                OCISodaColl          *collection,
                                void                **contentStrings,
                                ub4                  *contentStringLengths,
                                OraText             **keys,
                                ub4                  *keyLengths,
                                ub4                   arrayLength,
                                ub4                   docFlags,
                                OCISodaOutputOptions *opoptns,
                                OCIError             *errhp, 
                                ub4                   mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
contentStrings (IN)	ドキュメントのJSONコンテンツを含む文字列の配列です。このメソッドはJSONドキュメントに対してのみ機能します。
contentStringLengths (IN)	コンテンツ文字列の配列の長さです。
keys (IN)	挿入されたドキュメントのキーの配列です。コレクションにクライアント割当てキーがある場合は、キーを指定します。それ以外の場合は、NULLに設定します。
keyLengths (IN)	キーの長さの配列です。コレクションにクライアント割当てキーがある場合にのみ設定する必要があります。それ以外の場合は、NULLに設定する必要があります。
arrayLength (IN)	`contentStrings`配列と`keys`配列の長さです。
docFlags (IN)	ドキュメントの作成に使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
opoptns (OUT)	出力オプション・ハンドルを指定します。次の属性が有効です。 `OCI_ATTR_SODA_DOC_COUNT`—挿入されたドキュメントの数です。ノート: エラーが発生した場合、`OCI_ATTR_SODA_DOC_COUNT`にはエラー発生前に挿入されたドキュメントの数が含まれます。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの挿入に成功した場合は、OCI_SUCCESSです。

ドキュメントの挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例については、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.6 OCISodaCollCreate()

デフォルトのメタデータ設定を使用して、新規ドキュメント・コレクションを作成します。

用途

デフォルトのメタデータ設定を使用して、新規ドキュメント・コレクションを作成します。

構文

sword OCISodaCollCreate(OCISvcCtx       *svchp,
                        const OraText   *collname,
                        ub4              collnamelen,
                        OCISodaColl    **collection,
                        OCIError        *errhp,
                        ub4              mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collname (IN)	コレクションの名前。
collnamelen (IN)	コレクション名の長さです。
collection (OUT)	作成されたドキュメント・コレクションを表すコレクション・ハンドルを割り当てます。コレクション・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。 `OCI_SODA_COLL_CREATE_MAP` - 既存の表に対する新しいコレクション・マッピングを作成します。デフォルトのコレクション・メタデータに一致する正しい形状が表にあることを確認するために、最小限のチェックが実行されます。このチェックに失敗すると、この関数はエラーを戻します。

戻り値

コレクションが正常に作成された場合は、OCI_SUCCESSです。

コレクションが作成されない場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

指定した名前のコレクションがすでに存在する場合、この関数はOCISodaCollOpen()として機能し、既存のコレクションをオープンします。
この関数は、SQL DDL操作とは異なり、実行の前後にコミット操作を実行しません。(OCI_SODA_ATOMIC_COMMITモードを指定した場合のみ、操作の実行後に現在のトランザクションがコミットされます。)

例

例36-1 コレクションの作成

例は、SODA for Cを使用したドキュメント・コレクションの作成を参照してください。

36.2.7 OCISodaCollCreateWithMetadata()

メタデータを使用して、新規ドキュメント・コレクションを作成します。

用途

メタデータを使用して、新規ドキュメント・コレクションを作成します。

構文

sword OCISodaCollCreateWithMetadata(OCISvcCtx      *svchp,
                                    const OraText  *collname,
                                    ub4             collnamelen,
                                    OraText        *metadata,
                                    ub4             metadatalen,
                                    OCISodaColl   **collection,
                                    OCIError       *errhp,
                                    ub4             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collname (IN)	コレクションの名前。
collnamelen (IN)	コレクション名の長さです。
metadata (IN)	コレクション・メタデータ情報を含むJSON文字列です。`metadata`が`NULL`の場合は、デフォルトのメタデータ設定を使用してコレクションが作成されます。
metadatalen (IN)	メタデータJSON文字列の長さです。
collection (OUT)	作成されたドキュメント・コレクションを表すコレクション・ハンドルを割り当てます。コレクション・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT` - デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。 `OCI_SODA_COLL_CREATE_MAP` - 既存の表に対する新しいコレクション・マッピングを作成します。メタデータ・パラメータが`NULL`の場合、指定したコレクション・メタデータまたはデフォルトのメタデータに一致する正しい形状が表にあることを確認するために、最小限のチェックが実行されます。このチェックに失敗すると、この関数はエラーを戻します。

戻り値

コレクションが正常に作成された場合は、OCI_SUCCESSです。

コレクションが作成されない場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

指定した名前のコレクションがすでに存在し、指定したメタデータと同じメタデータがそのコレクションに含まれている場合、この関数はOCISodaCollOpen()として機能し、既存のコレクションをオープンします。指定したコレクション名と一致しないメタデータがコレクションに含まれている場合、エラーが戻されます。
この関数は、SQL DDL操作とは異なり、実行の前後にコミット操作を実行しません。(OCI_SODA_ATOMIC_COMMITモードを指定した場合のみ、操作の実行後に現在のトランザクションがコミットされます。)

例

例については、SODA for Cを使用したドキュメント・コレクションの作成を参照してください。

36.2.8 OCISodaCollDrop()

データベースからコレクションを削除します。

用途

データベースからコレクションを削除します。

構文

sword OCISodaCollDrop(OCISvcCtx   *svchp,
                      OCISodaColl *coll,
                      boolean     *isDropped,
                      OCIError    *errhp,
                      ub4          mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
coll (IN)	削除するコレクションです。`coll`が既存のコレクションを参照していない場合、エラーは戻されませんが、`isDropped`は`FALSE`であり、`OCISodaCollDrop()`の起動後に削除操作が成功しなかったことを示します。
isDropped (OUT)	削除操作のステータスを戻します。削除操作が成功した場合は、`TRUE`を戻し、削除操作が失敗した場合は、`FALSE`を戻します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。 `OCI_SODA_COLL_DROP_PURGE` - このモードを設定すると、データ表が削除されます。 `OCI_SODA_COLL_DROP_MAPPED_TABLE`- このモードを設定すると、マップされたコレクションの削除中にデータ表が削除されます。

戻り値

コレクションの削除が成功した場合は、OCI_SUCCESSです。

コレクションの削除が失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

この関数はコレクションを削除するだけであり、コレクション・ハンドルを解放しません。メモリー・リークが発生しないように、OCIHandleFree()をコールして、コレクション・ハンドルを解放してください。
この関数は、SQL DDL操作とは異なり、実行の前後にコミット操作を実行しません。(OCI_SODA_ATOMIC_COMMITモードを指定した場合のみ、操作の実行後に現在のトランザクションがコミットされます。)

例

例は、SODA for Cを使用したドキュメント・コレクションの削除を参照してください。

36.2.9 OCISodaCollGetNext()

コレクション・カーソルから次のコレクションを取得します。

用途

コレクション・カーソルから次のコレクションを取得します。

構文

sword OCISodaCollGetNext(OCISvcCtx                *svchp,
                         const OCISodaCollCursor  *cur,
                         OCISodaColl             **coll,
                         OCIError                 *errhp,
                         ub4                       mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
cur (IN)	`OCISodaCollList()`によって割り当てられた場合、コレクション・カーソル・ハンドルは有効のままです。コレクション・カーソル・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
coll (OUT)	コレクション・ハンドルを割り当て、検出される次のコレクションにそれを戻します。コレクション・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。

戻り値

次のコレクションが、指定したカーソルから戻された場合は、OCI_SUCCESSです。

次のコレクションのフェッチ時にエラーが発生した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用した既存のコレクションの検出を参照してください。

36.2.10 OCISodaCollList()

指定されたサービス・コンテキスト・ハンドル・パラメータに関連付けられているスキーマ内のコレクションをリストします。

用途

スキーマ内のコレクションをリストします。

構文

sword OCISodaCollList(OCISvcCtx          *svchp,
                      const OraText      *startname,
                      ub4                 stnamelen,
                      OCISodaCollCursor **cur,
                      OCIError           *errhp,
                      ub4                 mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
startname (IN)	コレクション開始名です。`NULL`に設定し、`stnamelen`を値0 (ゼロ)に設定すると、既存のすべてのコレクションを戻すことができます。
stnamelen (IN)	コレクション開始名の長さです。
cur (OUT)	コレクション・カーソル・ハンドルを割り当て、それを返します。コレクション・カーソルは、コレクション・リストを表します。コレクション・カーソル・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaCollList()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

スキーマのすべてのコレクションにわたるカーソルの取得に成功した場合は、OCI_SUCCESSです。

スキーマのすべてのコレクションにわたるカーソルの取得に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用した既存のコレクションの検出を参照してください。

36.2.11 OCISodaCollOpen()

コレクションを開きます。

用途

コレクションを開きます。

構文

sword OCISodaCollOpen(OCISvcCtx      *svchp,
                      const OraText  *collname,
                      ub4             collnamelen,
                      OCISodaColl   **coll,
                      OCIError       *errhp,
                      ub4             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collname (IN)	コレクションに割り当てられた名前です。
collnamelen (IN)	コレクション名の長さです。
coll (OUT)	コレクション・ハンドルを割り当て、指定されたコレクション名とともに戻します。コレクションをオープンする際にエラーがなければ、この関数は`OCI_SUCCESS`を返します。指定した名前のコレクションが存在しない場合は、エラーとはみなされず、`OCI_SUCCESS`が戻されますが、コレクション・ハンドル・ポインタは`NULL`として戻ります。そのため、コレクションが存在して正常にオープンしたかどうかを確認するには、この関数が`OCI_SUCCESS`を戻した後に`coll (OUT)`ポインタが`NULL`ではないことを確認します。コレクション・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaCollOpen()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

コレクションをオープンする際にエラーが発生しなかった場合は、OCI_SUCCESSです。

コレクションをオープンする際にエラーが検出された場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用した既存のドキュメント・コレクションのオープンを参照してください。

36.2.12 OCISodaDataGuideGet()

JSONデータ・ガイド情報を取得します。

用途

JSONデータ・ガイド情報を取得します。

構文

sword OCISodaDataGuideGet(OCISvcCtx           *svchp,
                           const OCISodaColl  *collection,
                           ub4                 docFlags,
                           OCISodaDoc        **doc,
                           OCIError           *errhp,
                           ub4                 mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
collection(IN)	コレクション・ハンドルです。
docFlags (IN)	次の各フラグは、戻されたドキュメントのコンテンツのエンコーディングを制御します。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`—ドキュメント・コンテンツは、環境ハンドル(ハンドルに設定されていない場合、環境変数`NLS_LANG`)で定義されている文字セットで戻されます。 `OCI_SODA_AS_AL32UTF8`—ドキュメント・コンテンツは文字セットAL32UTF8で戻されます。
doc (OUT)	JSONデータ・ガイドを表すコンテンツを含むドキュメント・ハンドルです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaDataGuideGet()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

指定したコレクションのデータ・ガイド情報の取得が成功した場合は、OCI_SUCCESSです。

データ・ガイド情報の取得がエラーになった場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクションのデータ・ガイドの取得を参照してください。

36.2.13 OCISodaDataGuideGetWithOpts ()

問合せから選択したドキュメントの場合のみ、データ・ガイドが最初から動的に作成されます。データ・ガイド対応JSON検索索引は必要ありません。

用途

データ・ガイドを取得します。

構文

sword OCISodaDataGuideGetWithOpts(OCISvcCtx                *svchp,
                                  const OCISodaColl        *collection,
                                  OCISodaOperationOptions  *optns,
                                  ub4                       format,
                                  ub4                       flags,
                                  ub4                       docFlags,
                                  OCISodaDoc              **doc,
                                  OCIError                 *errhp,
                                  ub4                       mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
collection(IN)	挿入するコレクション・ハンドルです。
optns (IN)	操作オプション・ハンドルです。
format (IN)	OCI SODA DataGuide形式: `OCI_SODA_DG_FMT_HIERARCHICAL` : 階層的データ・ガイドは、ネストされたJSONデータを持つオブジェクトとして、JSONで表されます。これは、JSONスキーマ(バージョン4、json-schema-core)で定義されているものと同じ形式です。 `OCI_SODA_DG_FMT_FLAT`: フラット・データ・ガイドはJSONでオブジェクトの配列として表され、それぞれがドキュメント・セット内の特定のパスのJSONデータを示します。
flags (IN)	OCI SODA DataGuideフラグ: `OCI_SODA_DATAGUIDE_PRETTY` : 返されたデータ・ガイドを適切なインデントで読みやすくするには、このフラグ・ビットを使用します。 `OCI_SODA_DATAGUIDE_GEOJSON` : GeoJSONタイプを自動検出するには、データ・ガイドでこのフラグ・ビットを使用します。 `OCI_SODA_DATAGUIDE_GATHER_STATS`: 統計情報を収集するには、データ・ガイドでこのフラグ・ビットを使用します。
docflags (IN)	ドキュメント・フラグです。
doc (OUT)	ドキュメントです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

OCI_SUCCESS (データ・ガイドが取得されている場合)。

36.2.14 OCISodaAsOfTimestampGet ()

データベース・タイムスタンプ値を文字列としてフェッチします。

用途

データベース・タイムスタンプ値を文字列としてフェッチします。

構文

sword OCISodaAsOfTimestampGet(OCISvcCtx      *svchp,
                              void           *tstamp,
                              ub4            *tstampLen,
                              OCIError       *errhp,
                              ub4             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
tstamp (IN/OUT)	データベースのタイムスタンプ値です。
tstampLen (OUT)	タイムスタンプ文字列の長さです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。

戻り値

OCI_SUCCESS (操作が成功した場合)。

データ・ガイド情報の取得がエラーになった場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

入力タイムスタンプ・バッファ(tstamp)のサイズは、少なくともOCI_SODA_TIMESTAMP_MAXSIZEである必要があります。OCIEnvNlsCreate()関数でSQL CHARデータにOCI_UTF16IDを指定した場合、tstampはOCI_SODA_TIMESTAMP_MAXSIZEサイズのutext配列(Utext tstamp[OCI_SODA_TIMESTAMP_MAXSIZE])である必要があります。

36.2.15 OCISodaAsOfScnGet ()

データベースのSCN値をフェッチします。

用途

データベースのSCN値をフェッチします。

構文

sword OCISodaAsOfScnGet(OCISvcCtx        *svchp,
                          ub8            *scn,
                          OCIError       *errhp,
                          ub4             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
scn (OUT)	データベースのSCN値です。

errhp (IN)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

OCI_SUCCESS (操作が成功した場合)。

36.2.16 OCISodaDocCount()

操作オプション・ハンドルで設定された属性に一致するドキュメントの数をカウントします。操作オプション・ハンドルに属性が設定されていない場合、この関数はコレクション内のすべてのドキュメントの数をカウントします。

用途

操作オプション・ハンドルで設定された属性に一致するドキュメントの数をカウントします。操作オプション・ハンドルに属性が設定されていない場合、この関数はコレクション内のすべてのドキュメントの数をカウントします。

構文

sword OCISodaDocCount(OCISvcCtx                     *svchp,
                      const OCISodaColl             *coll,
                      const OCISodaOperationOptions *optns,
                      ub8                           *numdocs,
                      OCIError                      *errhp,
                      ub4                            mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
optns (IN)	操作オプション・ハンドルです。スキップ属性と制限属性が操作オプション・ハンドルに設定されている場合、エラーが戻されます。
numdocs (OUT)	操作オプション・ハンドルで設定された属性(ある場合)に一致するコレクション内のドキュメントの数です。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaDocCount()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

指定したコレクションからのドキュメントのカウントに成功した場合は、OCI_SUCCESSです。

ハード・エラーによりドキュメントのカウントが失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、見つかったドキュメントの数のカウントを参照してください。

36.2.17 OCISodaDocCountWithFilter()

フィルタ仕様に一致するドキュメントの数をカウントします。

用途

フィルタ仕様に一致するドキュメントの数をカウントします。

ノート:

これは、フィルタ仕様に一致するドキュメントをカウントするための便利なメソッドです。ドキュメントをカウントするための、より一般的なメソッドは、フィルタ仕様または他の基準に一致するドキュメントをカウントできるOCISodaDocCount()です。

構文

sword OCISodaDocCountWithFilter(OCISvcCtx         *svchp, 
                                const OCISodaColl *coll, 
                                const OraText     *filterSpec, 
                                ub4                filterSpecLen,
                                ub8               *numdocs,
                                OCIError          *errhp,
                                ub4                mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
filterSpec (IN)	コレクション内のドキュメントの検索に使用されるJSONフィルタ文字列です。
filterSpecLen (IN)	フィルタ文字列の長さです。
numdocs (OUT)	フィルタと一致するコレクション内のドキュメントの数です。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaDocCountWithFilter()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

指定したコレクションからのドキュメントのカウントに成功した場合は、OCI_SUCCESSです。

ハード・エラーによりドキュメントのカウントが失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

36.2.18 OCISodaDocCreate()

ドキュメントを作成します。

用途

ドキュメントを作成します。

構文

sword OCISodaDocCreate (OCIEnv            *envhp,
                        const void        *content,
                        ub4                contentLength,
                        ub4                docFlags,
                        OCISodaDoc       **document,
                        OCIError          *errhp,
                        ub4                mode);

パラメータ

パラメータ	説明
envhp (IN)	環境ハンドルです。
content(IN)	ドキュメント・コンテンツを含む文字列。
contentLength (IN)	コンテンツ・パラメータの文字列長。
docFlags (IN)	ドキュメントの作成中にJSONエンコーディングを検出するために使用します。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
document (OUT)	ドキュメント・ハンドルを割り当てて、戻します。ドキュメント・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。

戻り値

ドキュメントが正常に作成された場合は、OCI_SUCCESSです。

ドキュメントの作成に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例36-2 ドキュメントの作成

例は、SODA for Cを使用したドキュメントの作成を参照してください。

36.2.19 OCISodaDocCreateWithKey()

ドキュメント・キーおよびコンテンツを含むドキュメントを作成します。

用途

ドキュメント・キーおよびコンテンツを含むドキュメントを作成します。

構文

sword OCISodaDocCreateWithKey(OCIEnv        *envhp,
                              const void    *content,
                              ub4            contentLength,
                              const OraText *key,
                              ub4            keylen,
                              ub4            docFlags,
                              OCISodaDoc   **document,
                              OCIError      *errhp,
                              ub4            mode);

パラメータ

パラメータ	説明
envhp (IN)	環境ハンドルです。
content (IN)	ドキュメント・コンテンツを含む文字列。
contentLength (IN)	コンテンツ・パラメータの文字列長。
key (IN)	ドキュメント・キーを含む文字列です。キーは`NULL`にできます。たとえば、デフォルトの場合、コレクションに自動生成キーがあるため、ドキュメントにキーを設定する必要はありません(設定すると、挿入などの書込み操作にドキュメントを渡すときにエラーが発生します)。コレクションがクライアント割当てキーで構成されている場合(デフォルトではありません)、`NULL`でないキーのみを設定します。
keylen (IN)	キー文字列の長さです。
docFlags (IN)	ドキュメントの作成に使用されるフラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
document (OUT)	ドキュメント・ハンドルを割り当てて、戻します。ドキュメント・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。

戻り値

ドキュメントが正常に作成された場合は、OCI_SUCCESSです。

ドキュメントの作成に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントの作成を参照してください。

36.2.20 OCISodaDocCreateWithKeyAndMType()

ドキュメント・キー、コンテンツおよびメディア・タイプを含むドキュメントを作成します。

用途

ドキュメント・キー、コンテンツおよびメディア・タイプを含むドキュメントを作成します。

構文

sword OCISodaDocCreateWithKeyAndMType(OCIEnv               *envhp,
                                      const void           *content,
                                      ub4                   contentLength,
                                      const OraText        *key,
                                      ub4                   keylen,
                                      const OraText        *mediaType,
                                      ub4                   mediaTypeLength,
                                      ub4                   docFlags,
                                      OCISodaDoc          **document,
                                      OCIError             *errhp,
                                      ub4                   mode);

パラメータ

パラメータ	説明
envhp (IN)	環境ハンドルです。
content (IN)	ドキュメント・コンテンツを含む文字列。
contentLength (IN)	コンテンツ・パラメータの文字列長。
key (IN)	ドキュメント・キーを含む文字列です。キーは`NULL`にできます。たとえば、デフォルトの場合、コレクションに自動生成キーがあるため、ドキュメントにキーを設定する必要はありません(設定すると、挿入などの書込み操作にドキュメントを渡すときにエラーが発生します)。コレクションがクライアント割当てキーで構成されている場合(デフォルトではありません)、`NULL`でないキーのみを設定します。
keylen (IN)	キー文字列の長さです。
mediaType (IN)	ドキュメント・メディア・タイプを含む文字列です。メディア・タイプ値が指定されていない場合は、デフォルトで「`application/json`」になります。値を指定すると、(「`application/json`」以外のメディア・タイプを使用して) JSONでないドキュメントを作成できます。
mediaTypeLength (IN)	メディア・タイプ文字列の長さです。
docFlags (IN)	ドキュメントの作成に使用されるフラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
document (OUT)	ドキュメント・ハンドルを割り当てて、戻します。ドキュメント・ハンドルが不要になった場合は、`OCIHandleFree()`をコールしてそのハンドルを解放します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。

戻り値

ドキュメントが正常に作成された場合は、OCI_SUCCESSです。

ドキュメントの作成に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントの作成を参照してください。

36.2.21 OCISodaDocGetNext()

カーソルから次のドキュメントを取得します。

用途

カーソルから次のドキュメントを取得します。

構文

sword OCISodaDocGetNext(OCISvcCtx                *svchp,
                        const OCISodaDocCursor   *cursor,
                        OCISodaDoc              **doc,
                        OCIError                 *errhp,
                        ub4                       mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
cursor (IN)	ドキュメント結果のカーソルです。
doc (OUT)	カーソルから戻されるドキュメント・ハンドル。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルトのモードです。この関数をコールすると、その文が実行されます。

戻り値

指定されたコレクション内でドキュメントが検出された場合は、OCI_SUCCESSです。

ドキュメントの検索に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

データが見つからない場合はOCI_NO_DATAです(終了基準)。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクションでのドキュメントの検索を参照してください。

36.2.22 OCISodaFind()

操作オプション入力ハンドルで設定された属性と一致するコレクション内のドキュメントを検索します。条件が設定されていない場合、コレクション内のすべてのドキュメントが戻されます。

用途

操作オプション入力ハンドルで設定された属性と一致するコレクション内のドキュメントを検索します。条件が設定されていない場合は、コレクション内のすべてのドキュメントが戻されます。

構文

sword OCISodaFind(OCISvcCtx                      *svchp, 
                  const OCISodaColl              *coll, 
                  const OCISodaOperationOptions  *findOptions,
                  ub4                             docFlags,
                  OCISodaDocCursor              **cursor,
                  OCIError                       *errhp,
                  ub4                             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	ドキュメントを検索するコレクションです。
findOptions (IN)	検索操作を実行するための属性を伴う操作オプション・ハンドルです。属性が設定されていない場合は、コレクション内のすべてのドキュメントが戻されます。
docFlags (IN)	次の各フラグは、戻されたドキュメントのコンテンツのエンコーディングを制御します。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`—ドキュメント・コンテンツは、環境ハンドル(ハンドルに設定されていない場合、環境変数NLS_LANG)で定義されている文字セットで戻されます。 `OCI_SODA_AS_STORED`—ドキュメント・コンテンツは、そのコンテンツがデータベースに格納されていた際の文字セットで戻されます。このパラメータ値は、BLOBコンテンツに対してのみ使用してください。コンテンツがBLOBインスタンスに格納されていない場合は、エラーが発生します。 `OCI_SODA_AS_AL32UTF8`—ドキュメント・コンテンツは文字セット`AL32UTF8`で戻されます。
cursor (OUT)	ドキュメント結果のカーソルです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaFindOneWithKey()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

指定されたコレクション内でドキュメントが検出された場合は、OCI_SUCCESSです。

OCI_ERROR(ハード・エラーの場合)。OCIErrorパラメータに必要なエラー情報が示されます。

データが見つからない場合はOCI_NO_DATAです(終了基準)。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクションでのドキュメントの検索を参照してください。

36.2.23 OCISodaFindOne()

操作オプション入力ハンドルで設定された属性と一致するコレクション内のドキュメントを検索します。設定されている属性と一致するドキュメントがコレクション内に複数ある場合は、最初のドキュメントが戻されます。

用途

操作オプション入力ハンドルで設定された属性と一致するコレクション内のドキュメントを検索します。設定されている属性と一致するドキュメントがコレクション内に複数ある場合は、最初のドキュメントが戻されます。

構文

sword OCISodaFindOne(OCISvcCtx                      *svchp, 
                     const OCISodaColl              *coll, 
                     const OCISodaOperationOptions  *findOptions,
                     ub4                             docFlags, 
                     OCISodaDoc                    **doc,
                     OCIError                       *errhp,
                     ub4                             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	ドキュメントを検索するコレクションです。
findOptions (IN)	検索操作を実行するための属性を伴う操作オプション・ハンドルです。一致するドキュメントがコレクション内に複数ある場合は、最初のドキュメントが戻されます。
docFlags (IN)	次の各フラグは、戻されたドキュメントのコンテンツのエンコーディングを制御します。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`—ドキュメント・コンテンツは、環境ハンドル(ハンドルに設定されていない場合、環境変数NLS_LANG)で定義されている文字セットで戻されます。 `OCI_SODA_AS_STORED`—ドキュメント・コンテンツは、そのコンテンツがデータベースに格納されていた際の文字セットで戻されます。このパラメータ値は、BLOBコンテンツに対してのみ使用してください。コンテンツが`BLOB`インスタンスに格納されていない場合は、エラーが発生します。 `OCI_SODA_AS_AL32UTF8` —ドキュメント・コンテンツは文字セット`AL32UTF8`で戻されます。
doc (OUT)	ドキュメントが見つかりました(ドキュメントが見つからない場合は`NULL`を戻します)。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaFindOneWithKey()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

指定されたコレクション内でドキュメントが検出された場合は、OCI_SUCCESSです。

ドキュメントの検索に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクションでのドキュメントの検索を参照してください。

36.2.24 OCISodaFindOneWithKey()

指定されたキーに基づいて、コレクション内の単一のドキュメントを検索します。

用途

指定されたキーに基づいて、コレクション内の単一のドキュメントを検索します。

ノート:

これは、キーでドキュメントを検索する便利なメソッドです。より一般的なメソッドはOCISodaFindOneです。

構文

sword OCISodaFindOneWithKey(OCISvcCtx          *svchp,
                            const OCISodaColl  *coll,
                            const OraText      *key,
                            ub4                 keylen,
                            ub4                 docFlags,
                            OCISodaDoc        **doc,
                            OCIError           *errhp,
                            ub4                 mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
coll (IN)	ドキュメントを検索するコレクションです。
key (IN)	ドキュメントの識別に使用されるキーです。
keylen (IN)	キーの長さです。
docFlags (IN)	次の各フラグは、戻されたドキュメントのコンテンツのエンコーディングを制御します。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`—ドキュメント・コンテンツは、環境ハンドル(ハンドルに設定されていない場合、環境変数`NLS_LANG`)で定義されている文字セットで戻されます。 `OCI_SODA_AS_STORED`—ドキュメント・コンテンツは、そのコンテンツがデータベースに格納されていた際の文字セットで戻されます。このパラメータ値は、`BLOB`コンテンツに対してのみ使用してください。コンテンツがBLOBインスタンスに格納されていない場合は、エラーが発生します。 `OCI_SODA_AS_AL32UTF8`—ドキュメント・コンテンツは文字セットAL32UTF8で戻されます。
doc (OUT)	ドキュメントがコレクション内で検出された場合、ドキュメント・ハンドルを割り当てて、戻します。ドキュメントがコレクション内で検出されない場合、`NULL`ドキュメントが戻され、関数は`OCI_NO_DATA`を戻します。検索操作の完了時に`OCIHandleFree()`をコールしてコレクション・ハンドルを解放してください。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。ノート: `OCISodaFindOneWithKey()`はデータベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

指定されたコレクション内でドキュメントが検出された場合は、OCI_SUCCESSです。

ドキュメントが検出されなかった場合は、OCI_NO_DATAです。

ドキュメントの検索の際にエラーが発生した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクションでのドキュメントの検索を参照してください。

36.2.25 OCISodaIndexCreate()

索引仕様を使用して索引を作成します。

用途

索引仕様を使用して索引を作成します。指定できるのは、Bツリー、JSON検索索引、空間の3種類の索引仕様です。

構文

sword OCISodaIndexCreate(OCISvcCtx         *svchp,
                         const OCISodaColl *coll,
                         const OraText     *indexspec,
                         ub4                speclen,
                         OCIError          *errhp,
                         ub4                mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	索引を付けるコレクションのハンドル。
indexspec (IN)	索引仕様です。
speclen(IN)	索引仕様の長さです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT` - デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションに対する索引の作成が成功した場合は、OCI_SUCCESSです。

索引の作成がエラーになった場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

この関数は、SQL DDL操作とは異なり、実行の前後にコミット操作を実行しません。(OCI_SODA_ATOMIC_COMMITモードを指定した場合のみ、操作の実行後に現在のトランザクションがコミットされます。)

例

例は、SODA for Cを使用したコレクション内のドキュメントの索引付けを参照してください。

関連トピック

36.2.26 OCISodaIndexDrop()

索引を削除します。

用途

索引を削除します。

構文

sword OCISodaIndexDrop(OCISvcCtx   *svchp,
                       OraText     *indexname,
                       ub4          indexnamelen,
                       boolean     *isDropped,
                       OCIError    *errhp,
                       ub4          mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
indexname (IN)	索引名です。
indexnamelen(IN)	索引名の長さです。
isDropped (OUT)	削除操作のステータスを戻します。削除操作が成功した場合は`TRUE`、指定した名前の索引が存在しない場合は`FALSE`です。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_INDEX_DROP_FORCE` - 索引を強制的に削除します。JSON検索索引または空間索引にのみ使用します。Bツリー索引の削除はサポートされていません。ノート: FORCEフラグの詳細は、DROP INDEXを参照してください。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションでの索引の削除が成功した場合は、OCI_SUCCESSです。

索引の削除がエラーになった場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

この関数は、SQL DDL操作とは異なり、実行の前後にコミット操作を実行しません。(OCI_SODA_ATOMIC_COMMITモードを指定した場合のみ、操作の実行後に現在のトランザクションがコミットされます。)

例

例については、SODA for Cを使用した索引の削除を参照してください。

36.2.27 OCISodaInsert()

コレクションにドキュメントを挿入します。

用途

コレクションへのドキュメントの挿入

構文

sword OCISodaInsert(OCISvcCtx   *svchp,
                    OCISodaColl *collection,
                    OCISodaDoc  *document,
                    OCIError    *errhp,
                    ub4          mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
document (IN)	コレクションに挿入されるドキュメントのハンドルです。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの挿入に成功した場合は、OCI_SUCCESSです。

ドキュメントの挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.28 OCISodaInsertAndGet()

ドキュメントをコレクションに挿入し、コンテンツ以外のすべてのドキュメント・コンポーネントを含む結果ドキュメントを返します。

用途

ドキュメントをコレクションに挿入し、コンテンツ以外のすべてのドキュメント・コンポーネントを含む結果ドキュメントを返します。挿入中にSODAで生成されたコンポーネント(キー(自動で割り当てられたキーがコレクションにある場合)、最終変更のタイムスタンプ、作成時のタイムスタンプ、バージョンなど)は、結果ドキュメントの一部として戻されます。

構文

sword OCISodaInsertAndGet(OCISvcCtx      *svchp,
                          OCISodaColl    *collection,
                          OCISodaDoc    **document,
                          OCIError       *errhp,
                          ub4             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
document (IN/OUT)	コレクションに挿入されるドキュメントのハンドルです。`IN/OUT`のパラメータであるため、この同じパラメータを使用して結果ドキュメントを返します。注意: 結果ドキュメントは同じパラメータを使用して返されるため、後で`OCIHandleFree()`を使用して結果ドキュメント・ハンドルとともに入力ドキュメント・ハンドルを解放できるように、入力ドキュメント・ハンドルへの参照を保存する必要があります。入力ドキュメント・ハンドルへの参照を保存しない場合、その参照は結果ドキュメントへの参照で上書きされ、入力ドキュメント・ハンドルが正しく解放されなくなります(これはメモリー・リークです)。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの挿入に成功した場合は、OCI_SUCCESSです。

ドキュメントの挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.29 OCISodaInsertAndGetWithOpts ()

オプション付きSODAドキュメントを挿入します。

用途

オプション付きSODAドキュメントを挿入します。

構文

sword OCISodaInsertAndGetWithOpts(OCISvcCtx                 *svchp,
                                  OCISodaColl               *collection,
                                  OCISodaDoc               **document,
                                  OCISodaOperationOptions   *oproptns,
                                  OCIError                  *errhp,
                                  ub4                        mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	挿入するコレクション・ハンドルです。
document (IN/OUT)	挿入および返されるドキュメント・ハンドルです。
oproptns (IN)	操作オプション・ハンドル
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

OCI_SUCCESS (ドキュメントが挿入されている場合)。

36.2.30 OCISodaInsertAndGetWithCtnt()

コンテンツのみを使用してコレクションにドキュメントを挿入し、コンテンツ以外のすべてのドキュメント・コンポーネントを含む結果ドキュメントを返します。

用途

コンテンツのみを使用してコレクションにドキュメントを挿入し、コンテンツ以外のすべてのドキュメント・コンポーネントを含む結果ドキュメントを返します。挿入中にSODAで生成されたコンポーネント(キー(自動で割り当てられたキーがコレクションにある場合)、最終変更のタイムスタンプ、作成時のタイムスタンプ、バージョンなど)は、結果ドキュメントの一部として戻されます。

ノート:

これは、ドキュメント・ハンドルを作成せずにJSONドキュメントを挿入する便利なメソッドです。より一般的なメソッドはOCISodaInsertAndGetです。

構文

sword OCISodaInsertAndGetWithCtnt(OCISvcCtx        *svchp,
                                  OCISodaColl      *collection,
                                  const OraText    *key,
                                  ub4               keyLength,
                                  const void       *content,
                                  ub4               contentLength,
                                  ub4               docFlags,
                                  OCISodaDoc      **document,
                                  OCIError         *errhp,
                                  ub4               mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
key (IN)	ドキュメント・キーを含む文字列です。自動生成キーについて構成されているコレクションにドキュメントを挿入する場合は、`NULL`である必要があります。
keyLength (IN)	キー文字列の長さです。自動生成キーについて構成されているコレクションにドキュメントを挿入する場合は、0 (ゼロ)である必要があります。
content (IN)	ドキュメントのJSONコンテンツを含む文字列です。ノート: このメソッドは、JSONドキュメントに対してのみ機能します。
contentLength (IN)	`content`パラメータの文字列長です。
docFlags (IN)	指定されたドキュメントのコンテンツのエンコーディングを指定するために使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
document (OUT)	コンテンツ以外のすべてのドキュメント・コンポーネントを含む結果ドキュメントを割り当てて、戻します。挿入中にSODAで生成されたコンポーネント(キー(自動で割り当てられたキーがコレクションにある場合)、最終変更のタイムスタンプ、作成時のタイムスタンプ、バージョンなど)は、結果ドキュメントの一部として戻されます。 `NULL`がこのパラメータに渡された場合、結果ドキュメントは戻されません。(つまり、関数はその後、結果ドキュメントを戻さない`OCISodaInsertWithCtnt()`関数と同様に動作します)。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの挿入に成功した場合は、OCI_SUCCESSです。

ドキュメントの挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.31 OCISodaInsertWithCtnt()

コンテンツのみを使用してコレクションにドキュメントを挿入します。

用途

コンテンツのみを使用してコレクションにドキュメントを挿入します。

ノート:

これは、ドキュメント・ハンドルを作成せずにJSONドキュメントを挿入する便利なメソッドです。より一般的なメソッドはOCISodaInsertです。

構文

sword OCISodaInsertWithCtnt(OCISvcCtx           *svchp,
                            OCISodaColl         *collection,
                            const OraText       *key,
                            ub4                  keyLength,
                            const void          *content,
                            ub4                  contentLength,
                            ub4                  docFlags,
                            OCIError            *errhp,
                            ub4                  mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	既存のコレクションのコレクション・ハンドルです。
key (IN)	ドキュメント・キーを含む文字列です。自動生成キーについて構成されているコレクションにドキュメントを挿入する場合は、`NULL`である必要があります。
keyLength (IN)	キー文字列の長さです。自動生成キーについて構成されているコレクションにドキュメントを挿入する場合は、0 (ゼロ)である必要があります。
content (IN)	ドキュメントのJSONコンテンツを含む文字列です。ノート: このメソッドは、JSONドキュメントに対してのみ機能します。
contentLength (IN)	ドキュメント・コンテンツの長さです。
docFlags (IN)	指定されたドキュメントのコンテンツのエンコーディングを指定するために使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの挿入に成功した場合は、OCI_SUCCESSです。

ドキュメントの挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したドキュメントのコレクションへの挿入を参照してください。

36.2.32 OCISodaRemove()

操作オプション入力ハンドルで設定された属性と一致するドキュメントをコレクションから削除します。属性が設定されていない場合は、コレクション内のすべてのドキュメントが削除されます。

用途

操作オプション入力ハンドルで設定された属性と一致するドキュメントをコレクションから削除します。属性が設定されていない場合は、コレクション内のすべてのドキュメントが削除されます。

構文

sword OCISodaRemove(OCISvcCtx                       *svchp,
                    const OCISodaColl               *coll,
                    const OCISodaOperationOptions   *optns,
                    ub8                             *removeCount,
                    OCIError                        *errhp,
                    ub4                              mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
optns (IN)	削除操作を実行するための属性を伴う操作オプション・ハンドルです。属性が設定されていない場合、コレクション内のすべてのドキュメントが削除されます。`OCI_ATTR_SODA_SKIP`属性と`OCI_ATTR_SODA_LIMIT`属性が操作オプション・ハンドルに設定されている場合、それらは無視されます。つまり、削除などの書込み操作には適用されません。
removeCount (OUT)	削除されたドキュメントの数です。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションから1つ以上のドキュメントが削除された場合は、OCI_SUCCESSです。

ドキュメントの削除に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクションからのドキュメントの削除を参照してください。

36.2.33 OCISodaRemoveOneWithKey()

指定されたキーに基づいて、コレクションからドキュメントを削除します。

用途

指定されたキーに基づいて、コレクションからドキュメントを削除します。

ノート:

これは、単一キーを使用してドキュメントを削除する便利なメソッドです。より一般的なメソッドはOCISodaRemoveです。

構文

sword OCISodaRemoveOneWithKey(OCISvcCtx          *svchp,
                              const OCISodaColl  *coll,
                              const OraText      *key,
                              ub4                 keylength,
                              boolean            *isRemoved,
                              OCIError           *errhp,
                              ub4                 mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
key (IN)	削除するドキュメントのキーです。
keylength (IN)	削除するドキュメントのキーの長さです。
isRemoved (OUT)	指定したキーを含むドキュメントが検出された場合は、`TRUE`を戻し、ドキュメントが削除されます。指定したキーを含むドキュメントが検出されなかった場合は、`FALSE`を戻します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したキーを含むドキュメントが検出されなかった場合は、OCI_SUCCESSです。OCI_SUCCESSは依然として返されます(ただし、isRemovedはFALSEに設定されます)。ドキュメントが削除されたかどうかを確認するには、isRemovedパラメータがTRUEに設定されていることを確認してください。

SQLエラーにより、ドキュメントの削除操作が実行中に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクションからのドキュメントの削除を参照してください。

36.2.34 OCISodaReplOne()

操作オプション入力ハンドルで設定された属性と一致するドキュメントを置き換えます。

用途

操作オプション入力ハンドルで設定された属性と一致するドキュメントを置き換えます。置換するドキュメントを一意に識別するため、少なくともOCI_ATTR_SODA_KEYキーを操作オプションに設定する必要があります。その他の属性を設定することもできます。

構文

sword OCISodaReplOne(OCISvcCtx                       *svchp,
                     const OCISodaColl               *coll,
                     const OCISodaOperationOptions   *optns,
                     OCISodaDoc                      *document, 
                     boolean                         *isReplaced,
                     OCIError                        *errhp,
                     ub4                              mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
optns (IN)	置換操作を実行するための属性を伴う操作オプション・ハンドルです。置換するドキュメントを一意に識別するため、キーとして少なくとも`OCI_ATTR_SODA_KEY`属性を設定する必要があります。それ以外の場合、操作はエラーを戻します。`OCI_ATTR_SODA_VERSION`や`OCI_ATTR_SODA_FILTER`などの他の属性を設定することもできます。`OCI_ATTR_SODA_SKIP`属性と`OCI_ATTR_SODA_LIMIT`属性が操作オプション・ハンドルに設定されている場合、それらは無視されます。つまり、置換などの書込み操作には適用されません。
document (IN)	コレクション内の現在のドキュメントの置換えとして使用するドキュメント・ハンドルです。このハンドルのコンテンツおよびメディア・タイプのコンポーネントのみが置換操作中に使用されます(つまり、この操作は、コレクション内のそのドキュメントのコンテンツおよびメディア・タイプを置き換えます)。他のコンポーネント(入力ドキュメントに設定されている場合)は無視されます。
isReplaced (OUT)	ドキュメントが置換されているかどうかを示します。置換される場合は`TRUE`を、そうでない場合は`FALSE`を戻します。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT` - デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定されたコレクション内でドキュメントが置換された場合は、OCI_SUCCESSです。

ドキュメントの置換に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクション内のドキュメントの置換を参照してください。

36.2.35 OCISodaReplOneAndGet()

操作オプション入力ハンドルで設定された属性と一致するドキュメントを置換し、結果ドキュメントへのハンドルを戻します。

用途

操作オプション入力ハンドルで設定された属性と一致するドキュメントを置換し、結果ドキュメントへのハンドルを戻します。置換するドキュメントを一意に識別するため、少なくともOCI_ATTR_SODA_KEYキーを操作オプションに設定する必要があります。その他の属性を設定することもできます。

構文

sword OCISodaReplOneAndGet(OCISvcCtx                       *svchp,
                           const OCISodaColl               *coll,
                           const OCISodaOperationOptions   *optns,
                           OCISodaDoc                     **document,
                           boolean                         *isReplaced,
                           OCIError                        *errhp,
                           ub4                              mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
optns (IN)	置換操作を実行するための属性を伴う操作オプション・ハンドルです。置換するドキュメントを一意に識別するため、キーとして少なくとも`OCI_ATTR_SODA_KEY`属性を設定する必要があります。それ以外の場合、操作はエラーを戻します。`OCI_ATTR_SODA_VERSION`や`OCI_ATTR_SODA_FILTER`などの他の属性を設定することもできます。`OCI_ATTR_SODA_SKIP`属性と`OCI_ATTR_SODA_LIMIT`属性が操作オプション・ハンドルに設定されている場合、それらは無視されます。つまり、置換などの書込み操作には適用されません。
document (IN/OUT)	コレクション内の現在のドキュメントの置換えとして使用するドキュメント・ハンドルです。このハンドルのコンテンツおよびメディア・タイプのコンポーネントのみが置換操作中に使用されます(つまり、この操作は、コレクション内のそのドキュメントのコンテンツおよびメディア・タイプを置き換えます)。他のコンポーネント(入力ドキュメントに設定されている場合)は無視されます。`IN/OUT`のパラメータであるため、この同じパラメータを使用して結果ドキュメントを返します。注意: 結果ドキュメントは同じパラメータを使用して返されるため、後で`OCIHandleFree()`を使用して結果ドキュメント・ハンドルとともに入力ドキュメント・ハンドルを解放できるように、入力ドキュメント・ハンドルへの参照を保存する必要があります。入力ドキュメント・ハンドルへの参照を保存しない場合、その参照は結果ドキュメントへの参照で上書きされ、入力ドキュメント・ハンドルが正しく解放されなくなります(これはメモリー・リークです)。
isReplaced (OUT)	ドキュメントが置換されているかどうかを示します。置換される場合は`TRUE`を、そうでない場合は`FALSE`を戻します。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定されたコレクション内でドキュメントが置換された場合は、OCI_SUCCESSです。

ハード・エラーによりドキュメントの置換が失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクション内のドキュメントの置換を参照してください。

36.2.36 OCISodaReplOneAndGetWithCtnt()

操作オプション入力ハンドルで設定された属性と一致するドキュメントのコンテンツを新しいコンテンツで置換し、結果ドキュメントへのハンドルを戻します。

用途

操作オプション入力ハンドルで設定された属性と一致するドキュメントのコンテンツを新しいコンテンツに置き換え、コンテンツ以外のすべてのコンポーネントを含む結果ドキュメントへのハンドルを戻します。これには、更新されたコンポーネント(最終変更のタイムスタンプやバージョンなど)が含まれます。置換するドキュメントを一意に識別するため、少なくともOCI_ATTR_SODA_KEYキーを操作オプションに設定する必要があります。その他の属性を設定することもできます。

ノート:

これは、置換するドキュメントのドキュメント・ハンドルを作成せずにドキュメントをJSONドキュメントに置き換えるための便利なメソッドです。より一般的なメソッドはOCISodaReplOneAndGetです。このメソッドはJSONドキュメント専用です。つまり、指定した置換ドキュメントはJSONドキュメントであることが必要です。コレクションで置き換えるターゲット・ドキュメントは、JSONドキュメントでもそうでなくてもかまいません。

構文

sword OCISodaReplOneAndGetWithCtnt(OCISvcCtx                     *svchp,
                                   const OCISodaColl             *coll,
                                   const OCISodaOperationOptions *optns,
                                   const void                    *content,
                                   ub4                            contentLen,
                                   ub4                            docFlags,
                                   OCISodaDoc                   **document,
                                   boolean                       *isReplaced,
                                   OCIError                      *errhp,
                                   ub4                            mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
optns (IN)	置換操作を実行するための属性を伴う操作オプション・ハンドルです。置換するドキュメントを一意に識別するため、キーとして少なくとも`OCI_ATTR_SODA_KEY`属性を設定する必要があります。それ以外の場合、操作はエラーを戻します。`OCI_ATTR_SODA_VERSION`や`OCI_ATTR_SODA_FILTER`などの他の属性を設定することもできます。`OCI_ATTR_SODA_SKIP`属性と`OCI_ATTR_SODA_LIMIT`属性が操作オプション・ハンドルに設定されている場合、それらは無視されます。つまり、置換などの書込み操作には適用されません。
content (IN)	ドキュメントのJSONコンテンツを含む文字列です。ノート: このメソッドは、JSONドキュメントに対してのみ機能します。
contentLen (IN)	ドキュメント・コンテンツの長さです。
docFlags (IN)	指定されたドキュメントのコンテンツのエンコーディングを指定するために使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
document (OUT)	結果ドキュメントには、最終変更のタイムスタンプやバージョンなど、更新されたものを含む、コンテンツを除くすべてのコンポーネントが含まれます。
isReplaced (OUT)	ドキュメントが置換されているかどうかを示します。置換される場合は`TRUE`を、そうでない場合は`FALSE`を戻します。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定されたコレクション内でドキュメントが置換された場合は、OCI_SUCCESSです。

ドキュメントの置換に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクション内のドキュメントの置換を参照してください。

36.2.37 OCISodaReplOneAndGetWithKey()

指定されたキーに基づいて、コレクション内のドキュメントを置き換えて、結果ドキュメントへのハンドルを戻します。

用途

指定されたキーに基づいて、コレクション内のドキュメントを置き換えて、コンテンツ以外のすべてのコンポーネントを含む結果ドキュメントへのハンドルを戻します。これには、更新されたコンポーネント(最終変更のタイムスタンプやバージョンなど)が含まれます。

ノート:

これは、キーでドキュメントを置換する便利なメソッドです。より一般的なメソッドはOCISodaReplOneAndGetです。

構文

sword OCISodaReplOneAndGetWithKey(OCISvcCtx         *svchp,
                                  const OCISodaColl *coll,
                                  const OraText     *key,
                                  ub4                keylength,
                                  OCISodaDoc       **document,
                                  boolean           *isReplaced,
                                  OCIError          *errhp,
                                  ub4                mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
key (IN)	ドキュメントの識別に使用されるキーです。
keylength (IN)	キーの長さです。
document (IN/OUT)	コレクション内の現在のドキュメントの置換えとして使用するドキュメント・ハンドルです。このハンドルのコンテンツおよびメディア・タイプのコンポーネントのみが置換操作中に使用されます(つまり、この操作は、コレクション内のそのドキュメントのコンテンツおよびメディア・タイプを置き換えます)。他のコンポーネント(入力ドキュメントに設定されている場合)は無視されます。`IN/OUT`のパラメータであるため、この同じパラメータを使用して結果ドキュメントを返します。注意: 結果ドキュメントは同じパラメータを使用して返されるため、後で`OCIHandleFree()`を使用して結果ドキュメント・ハンドルとともに入力ドキュメント・ハンドルを解放できるように、入力ドキュメント・ハンドルへの参照を保存する必要があります。入力ドキュメント・ハンドルへの参照を保存しない場合、その参照は結果ドキュメントへの参照で上書きされ、入力ドキュメント・ハンドルが正しく解放されなくなります(これはメモリー・リークです)。
isReplaced (OUT)	指定したキーを含むドキュメントが検出された場合は、`TRUE`を戻し、ドキュメントは置換されます。指定したキーを含むドキュメントが検出できなかった場合は、`FALSE`を戻します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したキーを含むドキュメントが検出されなかった場合は、OCI_SUCCESSです。OCI_SUCCESSが依然として返されます(ただし、isReplacedはFALSEに設定されます)。ドキュメントが置き換えられたかどうかを確認するには、isReplacedパラメータがTRUEに設定されていることを確認します。

SQLエラーにより、ドキュメントの置換操作が実行中に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクション内のドキュメントの置換を参照してください。

36.2.38 OCISodaReplOneWithCtnt()

操作オプション入力ハンドルで設定された属性と一致するドキュメントのコンテンツを新しいコンテンツに置換します。

用途

操作オプション入力ハンドルで設定された属性と一致するドキュメントのコンテンツを新しいコンテンツに置換します。置換するドキュメントを一意に識別するため、少なくともOCI_ATTR_SODA_KEYキーを操作オプションに設定する必要があります。その他の属性を設定することもできます。

ノート:

これは、置換するドキュメントのドキュメント・ハンドルを作成せずにドキュメントをJSONドキュメントに置き換えるための便利なメソッドです。より一般的なメソッドはOCISodaReplOneです。このメソッドはJSONドキュメント専用です。つまり、指定した置換ドキュメントはJSONドキュメントであることが必要です。コレクションで置き換えるターゲット・ドキュメントは、JSONドキュメントでもそうでなくてもかまいません。

構文

sword OCISodaReplOneWithCtnt(OCISvcCtx                       *svchp,
                             const OCISodaColl               *coll,
                             const OCISodaOperationOptions   *optns,
                             const void                      *content,
                             ub4                              contentLength,
                             ub4                              docFlags,
                             boolean                         *isReplaced,
                             OCIError                        *errhp,
                             ub4                              mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキストです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
optns (IN)	置換操作を実行するための属性を伴う操作オプション・ハンドルです。置換するドキュメントを一意に識別するため、キーとして少なくとも`OCI_ATTR_SODA_KEY`属性を設定する必要があります。それ以外の場合、操作はエラーを戻します。`OCI_ATTR_SODA_VERSION`や`OCI_ATTR_SODA_FILTER`などの他の属性を設定することもできます。`OCI_ATTR_SODA_SKIP`属性と`OCI_ATTR_SODA_LIMIT`属性が操作オプション・ハンドルに設定されている場合、それらは無視されます。つまり、置換などの書込み操作には適用されません。
content (IN)	ドキュメントのJSONコンテンツを含む文字列です。ノート: このメソッドは、JSONドキュメントに対してのみ機能します。
contentLength (IN)	ドキュメント・コンテンツの長さです。
docFlags (IN)	指定されたドキュメントのコンテンツのエンコーディングを指定するために使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`：このパラメータ値を使用している場合、ドキュメント・コンテンツは環境ハンドル(ハンドルに設定されていない場合は、環境変数`NLS_LANG`)で定義されている文字セットであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。 `OCI_SODA_DETECT_JSON_ENC`—UTF-8、UTF-16 LE、UTF-16 BEのいずれかとして、ドキュメント・コンテンツのエンコーディングを自動的に検出します。このパラメータ値を使用する場合、ドキュメント・コンテンツがUTF-8、UTF-16 LE、UTF-16 BEのいずれかであることを実質的に宣言しています。つまり、指定されたドキュメントにこれが該当しない場合、ドキュメント書込みの結果は予測できません。
isReplaced (OUT)	ドキュメントが置換されているかどうかを示します。置換される場合は`TRUE`を、そうでない場合は`FALSE`を戻します。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定されたコレクション内でドキュメントが置換された場合は、OCI_SUCCESSです。

ドキュメントの置換に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクション内のドキュメントの置換を参照してください。

36.2.39 OCISodaReplOneWithKey()

指定されたキーに基づいて、コレクション内のドキュメントを置き換えます。

用途

指定されたキーに基づいて、コレクション内のドキュメントを置き換えます。

ノート:

これは、キーでドキュメントを置換する便利なメソッドです。より一般的なメソッドはOCISodaReplOneです。

構文

sword OCISodaReplOneWithKey (OCISvcCtx           *svchp,
                             const OCISodaColl   *coll,
                             const OraText       *key,
                             ub4                  keylength,
                             OCISodaDoc          *document,
                             boolean             *isReplaced,
                             OCIError            *errhp,
                             ub4                  mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
coll (IN)	既存のコレクションのコレクション・ハンドルです。
key (IN)	ドキュメントの識別に使用されるキーです。
keylength (IN)	キーの長さです。
document (IN)	コレクション内の現在のドキュメントの置換えとして使用するドキュメント・ハンドルです。このハンドルのコンテンツおよびメディア・タイプのコンポーネントのみが置換操作中に使用されます(つまり、この操作は、コレクション内のそのドキュメントのコンテンツおよびメディア・タイプを置き換えます)。他のコンポーネント(入力ドキュメントに設定されている場合)は無視されます。
isReplaced (OUT)	指定したキーを含むドキュメントが検出された場合は、`TRUE`を戻し、ドキュメントは置換されます。指定したキーを含むドキュメントが検出できなかった場合は、`FALSE`を戻します。
errhp (IN/OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したキーを含むドキュメントが検出されなかった場合は、OCI_SUCCESSです。OCI_SUCCESSが依然として返されます(ただし、isReplacedはFALSEに設定されます)。ドキュメントが置き換えられたかどうかを確認するには、isReplacedパラメータがTRUEに設定されていることを確認します。

SQLエラーにより、ドキュメントの置換操作が実行中に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例は、SODA for Cを使用したコレクション内のドキュメントの置換を参照してください。

36.2.40 OCISodaSave()

ドキュメントをコレクションに保存します。

用途

ドキュメントをコレクションに保存します。

この関数は、クライアントが割り当てたキーが使用される場合、または指定したキーを持つドキュメントがコレクションにすでに存在する場合に、入力ドキュメントに置換されるという点を除いて、挿入関数と同等です。このコレクションにクライアントが割り当てたキーが構成され、そのキーが入力ドキュメントに指定されている場合を除き、キーは自動的に作成されます。

構文

sword OCISodaSave(OCISvcCtx   *svchp,
                  OCISodaColl *collection,
                  OCISodaDoc  *document,
                  OCIError    *errhp,
                  ub4          mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	開いているコレクション。
document (IN)	コレクションへのコンテンツの挿入に使用されるドキュメント・ハンドルです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルトのモードです。この関数をコールすると、その文が実行されます。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの保存に成功した場合は、OCI_SUCCESSです。

ドキュメントの保存に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

OCISodaDocCreateWithKeyAndMType()の例を参照してください。

36.2.41 OCISodaSaveAndGet()

ドキュメントをコレクションに保存し、メタデータ情報を含むドキュメントを戻します。

用途

ドキュメントをコレクションに保存し、キー、バージョン、タイムスタンプ情報などのメタデータ情報を含むドキュメントを戻します。

この関数は、クライアントが割り当てたキーが使用される場合、または指定したキーを持つドキュメントがコレクションにすでに存在する場合に、入力ドキュメントに置換されるという点を除いて、挿入関数と同等です。このコレクションにクライアントが割り当てたキーが構成され、そのキーが入力ドキュメントに指定されている場合を除き、キーは自動的に作成されます。

構文

sword OCISodaSaveAndGet(OCISvcCtx      *svchp,
                        OCISodaColl    *collection,
                        OCISodaDoc    **document,
                        OCIError       *errhp,
                        ub4             mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	開いているコレクション。
document (IN/OUT)	コレクションに保存されるドキュメント構造。`OCISodaDocCreate()`のコールのキー・パラメータが`NULL`の場合、ドキュメント・パラメータには、自動生成されたキーに加えて、バージョン、作成タイムスタンプなどの他の情報が含まれています。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルトのモードです。この関数をコールすると、その文が実行されます。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの保存に成功した場合は、OCI_SUCCESSです。

ドキュメントの保存に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

OCISodaDocCreateWithKeyAndMType()の例を参照してください。

36.2.42 OCISodaSaveAndGetWithOpts()

オプション付きSODAドキュメントを保存します。

用途

オプション付きSODAドキュメントを保存します。

構文

sword OCISodaSaveAndGetWithOpts(OCISvcCtx                *svchp,
                                OCISodaColl              *collection,
                                OCISodaDoc              **document,
                                OCISodaOperationOptions  *oproptns,
                                OCIError                 *errhp,
                                ub4                       mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	挿入するコレクション・ハンドルです。
document (IN/OUT)	挿入および返されるドキュメント・ハンドルです。
oproptns (IN)	操作オプション・ハンドルです。
errhp (IN)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。 `OCI_SODA_ATOMIC_COMMIT`—操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

OCI_SUCCESS (ドキュメントが保存されている場合)。

36.2.43 OCISodaSaveWithCtnt()

ドキュメントとそのコンテンツをコレクションに保存します。

用途

指定したキーを持つドキュメントを保存します。

この関数は、クライアントが割り当てたキーが使用される場合、または指定したキーを持つドキュメントがコレクションにすでに存在する場合に、入力ドキュメントに置換されるという点を除いて、挿入関数と同等です。このコレクションにクライアントが割り当てたキーが構成され、そのキーが入力ドキュメントに指定されている場合を除き、キーは自動的に作成されます。

構文

sword OCISodaSaveWithCtnt(OCISvcCtx         *svchp, 
                          OCISodaColl       *collection, 
                          const OraText     *key, 
                          ub4                keylength, 
                          const void        *content,
                          ub4                contentlen,
                          ub4                docFlags,
                          OCIError          *errhp,
                          ub4                mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	開いているコレクション。
key (IN)	保存するドキュメントの指定されたキー。
keylength(IN)	キーの長さです。
content (IN)	ドキュメントの`content`を含む文字列。
contentlen(IN)	`content`の文字列の長さです。
docFlags (IN)	ドキュメントの保存に使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`—デフォルト値。 `OCI_SODA_DETECT_JSON_ENC`—JSONのエンコーディングを検出します。 `OCI_SODA_AS_STORED`—`BLOB`列に格納されている状態で取得します。 `OCI_SODA_AS_AL32UTF8`—`UTF-8`として取得します。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルトのモードです。この関数をコールすると、その文が実行されます。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

コレクションが正常に作成された場合は、OCI_SUCCESSです。

コレクションが作成されない場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

OCISodaDocCreateWithKeyAndMType()の例を参照してください。

36.2.44 OCISodaSaveAndGetWithCtnt()

ドキュメントをコレクションに保存し、新しいドキュメント・ハンドルを取得します。

用途

指定されたキーおよび新しいドキュメント・ハンドルを持つドキュメントを保存し、保存されたドキュメントを取得します。

この関数は、クライアントが割り当てたキーが使用される場合、または指定したキーを持つドキュメントがコレクションにすでに存在する場合に、入力ドキュメントに置換されるという点を除いて、挿入関数と同等です。このコレクションにクライアントが割り当てたキーが構成され、そのキーが入力ドキュメントに指定されている場合を除き、キーは自動的に作成されます。

構文

sword OCISodaSaveAndGetWithCont(OCISvcCtx         *svchp, 
                                OCISodaColl       *collection, 
                                const OraText     *key, 
                                ub4                keylength, 
                                const void        *content, 
                                ub4                contentlen,
                                ub4                docFlags,
                                OCISodaDoc       **document,
                                OCIError          *errhp,
                                ub4                mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	開いているコレクション。
key (IN)	保存するドキュメントの指定されたキー。
keylength(IN)	キーの長さです。
content (IN)	ドキュメントのコンテンツを含む文字列。
contentlen(IN)	`content`の文字列の長さです。
docFlags (IN)	ドキュメントの保存に使用されるエンコーディング・フラグです。有効なフラグ・オプションは、次のとおりです。 `OCI_DEFAULT`—デフォルト値。 `OCI_SODA_DETECT_JSON_ENC`—JSONのエンコーディングを検出します。 `OCI_SODA_AS_STORED`—`BLOB`列に格納されている状態で取得します。 `OCI_SODA_AS_AL32UTF8`—`UTF-8`として取得します。
document (IN/OUT)	保存されたドキュメントのメタデータを含むドキュメント・ハンドルです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルトのモードです。この関数をコールすると、その文が実行されます。 `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。

戻り値

指定したコレクションへのドキュメントの挿入に成功した場合は、OCI_SUCCESSです。

ドキュメントの挿入に失敗した場合は、OCI_ERRORです。OCIErrorパラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

OCISodaDocCreateWithKeyAndMType()の例を参照してください。

36.2.45 OCISodaCollTruncate()

SODAドキュメント・コレクションを切り捨てます。

用途

ドキュメント・コレクションを切り捨てます。

sword OCISodaCollTruncate (OCISvcCtx *svchp,
                          const OCISodaColl   *collection,
                          OCIError            *errhp,                              
                          ub4                  mode);

パラメータ

パラメータ	説明
svchp (IN)	サービス・コンテキスト・ハンドルです。
collection (IN)	切り捨てるコレクションのコレクション・ハンドルです。
errhp (OUT)	エラー・ハンドルです。
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT` `OCI_SODA_ATOMIC_COMMIT` - 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。これにより、SODA操作による変更のみでなく、未処理のすべての変更がコミットされます。操作が失敗した場合、SODA操作に対する変更のみがロールバックされます。SODA操作の起動前に行われたコミットされていない変更はロールバックされません。 `OCI_SODA_TRUNCATE_REUSE_STORAGE`

戻り値

Oracleリターン・エラー・コード。

使用上のノート

なし。

36.2.46 OCISodaOperKeysSet()

操作オプション・ハンドルのキーの配列を設定します。

用途

操作オプション・ハンドルのキーの配列を設定します。操作オプション・ハンドルの属性は、標準のOCIAttrSet関数を使用して設定されます。OCIAttrSet関数はキーの配列の設定には使用されません。キーの配列とキー長の配列を両方設定する必要があるためです。

ノート:

関数OCIAttrSet()を使用して操作オプション・ハンドルに属性OCI_ATTR_SODA_KEYを設定し、関数OCISodaOperKeysSet()を使用して同じハンドルに複数のキーを設定する場合、2つの設定のうち新しい方のみが有効になります。最初に呼び出された関数の有効性は、2番目の関数によってオーバーライドされます。

構文

sword OCISodaOperKeysSet (const OCISodaOperationOptions  *operhp,
                          OraText                        **keysArray,
                          ub4                            *lengthsArray,
                          ub4                             count,
                          OCIError                       *errhp,
                          ub4                             mode);

パラメータ

パラメータ	説明
operhp (IN)	操作オプション・ハンドル
keysArray (IN)	`oratext*`キーの配列
lengthsArray (IN)	各キーに対応する`ub4`の長さの配列
count (IN)	キー配列の要素数
errhp (OUT)	エラー・ハンドル
mode (IN)	実行のモードを指定します。次のモードが有効です。 `OCI_DEFAULT`—デフォルト・モードです。これは、特殊でないモードでの操作の実行を意味します。

戻り値

キーが正常に設定された場合は、OCI_SUCCESSです。

使用上のノート

なし。

例

例は、ドキュメント・キーを指定した複数のドキュメントの検索およびドキュメント・キーを使用したコレクションからのドキュメントの削除を参照してください。