OCI SODA関数

次の表は、この章で説明しているOCI SODA関数を示しています。

表36-1 OCI SODA関数

関数	用途
OCISodaCollCreate()	デフォルトのメタデータ設定を使用して、新規ドキュメント・コレクションを作成します。
OCISodaCollCreateWithMetadata()	メタデータを使用して、新規ドキュメント・コレクションを作成します。
OCISodaCollOpen()	コレクションを開きます。
OCISodaCollList()	指定されたサービス・コンテキスト・ハンドル・パラメータに関連付けられているスキーマ内のコレクションをリストします。
OCISodaCollGetNext()	コレクション・カーソルから次のコレクションを取得します。
OCISodaCollDrop()	データベースからコレクションを削除します。
OCISodaDocCreate()	ドキュメントを作成します。
OCISodaDocCreateWithKey()	ドキュメント・キーおよびコンテンツを含むドキュメントを作成します。
OCISodaDocCreateWithKeyAndMType()	ドキュメント・キー、コンテンツおよびメディア・タイプを含むドキュメントを作成します。
OCISodaFindOneWithKey()	指定されたキーに基づいて、コレクション内の単一のドキュメントを検索します。
OCISodaInsert()	コレクションにドキュメントを挿入します。
OCISodaInsertAndGet()	ドキュメントをコレクションに挿入し、コンテンツ以外のドキュメント・コンポーネント(キー、バージョン、タイムスタンプなど)を含む結果ドキュメントを返します。
OCISodaInsertAndGetWithCtnt()	コンテンツのみを使用してコレクションにドキュメントを挿入し、コンテンツ以外のドキュメント・コンポーネントを含む結果ドキュメント・ハンドルを返します。
OCISodaInsertWithCtnt()	コンテンツのみを使用してコレクションにドキュメントを挿入します。
OCISodaRemoveOneWithKey()	指定されたキーに基づいて、コレクションからドキュメントを削除します。
OCISodaReplOneAndGetWithKey()	指定されたキーに基づいて、コレクション内のドキュメントを置き換えて、ドキュメント・コンポーネントを含む結果ドキュメントへのハンドルを戻します。これには、更新されたコンポーネント(最終変更のタイムスタンプ、バージョン、メディア・タイプなど)が含まれます。
OCISodaReplOneWithKey()	指定されたキーに基づいて、コレクション内のドキュメントを置き換えます。

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_SUCCESSです。

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

使用上のノート

• 指定した名前のコレクションがすでに存在する場合、この関数はOCISodaCollOpen()として機能し、既存のコレクションをオープンします。

例

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

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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_SUCCESSです。

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

使用上のノート

• 指定した名前のコレクションがすでに存在し、指定したメタデータと同じメタデータがそのコレクションに含まれている場合、この関数はOCISodaCollOpen()として機能し、既存のコレクションをオープンします。指定したコレクション名と一致しないメタデータがコレクションに含まれている場合、エラーが戻されます。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。 ノート: この操作では、データベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

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

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

使用上のノート

なし。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。 ノート: この操作では、データベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

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

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

使用上のノート

なし。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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パラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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_SUCCESSです。

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

使用上のノート

• この関数はコレクションを削除するだけであり、コレクション・ハンドルを解放しません。メモリー・リークが発生しないように、OCIHandleFree()をコールして、コレクション・ハンドルを解放してください。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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 ドキュメントの作成

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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パラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

次のコード・スニペットは、キーを含むドキュメントの作成方法を示しています。

例36-3 キーを含むドキュメントの作成

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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パラメータに必要なエラー情報が示されます。

使用上のノート

なし。

例

例 36-4 キーおよびマルチメディア・タイプを含むドキュメントの作成

次のリンクを参照してください。

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

OCISodaFindOneWithKey()

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

用途

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

構文

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。 ノート: この操作では、データベースを変更しませんが、このモードを使用して、別のラウンドトリップを実行せずに既存のトランザクションをコミットできます。

戻り値

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

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

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

使用上のノート

なし。

例

例36-5 キーを使用した1つのドキュメントの検索

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。

戻り値

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

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

使用上のノート

なし。

例

次のリンク先の例を参照してください: https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。

戻り値

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

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

使用上のノート

なし。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

OCISodaInsertAndGetWithCtnt()

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

用途

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

構文

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)	ドキュメント・コンテンツを含む文字列。
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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。

戻り値

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

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

使用上のノート

なし。

例

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

OCISodaInsertWithCtnt()

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

用途

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

構文

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)	ドキュメントのコンテンツです。
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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。

戻り値

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

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

使用上のノート

なし。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

OCISodaRemoveOneWithKey()

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

用途

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

構文

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。

戻り値

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

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

使用上のノート

なし。

例

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

OCISodaReplOneAndGetWithKey()

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

用途

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

構文

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。

戻り値

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

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

使用上のノート

なし。

例

次のリンク先の例を参照してください:

https://docs.oracle.com/en/database/oracle/oracle-database/18/adsdc/index.html

OCISodaReplOneWithKey()

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

用途

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

構文

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: 操作がこのモードで実行され、正常に完了すると、完了後にカレント・トランザクションがコミットされます。(modeパラメータOCI_SODA_ATOMIC_COMMITは、OCIStmtExecute()に対するOCI_COMMIT_ON_SUCCESSと同様に動作します)。

戻り値

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

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

使用上のノート

なし。

例

「OCISodaFindOneWithKey()」の例を参照してください。