1. Programmer's Guide
  2. OCI SODA Functions
  3. OCI SODA Functions

36.2 OCI SODA Functions

The following table lists the OCI SODA functions that are described in this chapter.

Table 36-1 OCI SODA Functions

Function Purpose
OCISodaCollCreate()

Creates a new document collection with default metadata settings.
OCISodaCollCreateWithMetadata()

Creates a new document collection with metadata.
OCISodaCollOpen()

Opens the collection.
OCISodaCollList()

Lists the collections in the schema associated with the supplied service context handle parameter.
OCISodaCollGetNext()

Gets the next collection from the collection cursor.
OCISodaCollDrop()

Drops a collection from the database.
OCISodaDocCreate()

Creates a document.
OCISodaDocCreateWithKey()

Creates a document with document key and content.
OCISodaDocCreateWithKeyAndMType()

Creates a document with document key, content, and media type.
OCISodaFindOneWithKey()

Finds a single document in a collection given a key.
OCISodaInsert()

Inserts a document into a collection.
OCISodaInsertAndGet()

Inserts a document into a collection and returns a result document containing document components, such as key, version, and timestamp, except for content.
OCISodaInsertAndGetWithCtnt()

Inserts a document into a collection using just the content and returns a result document handle with the document components, except for content.
OCISodaInsertWithCtnt()

Inserts a document into a collection using just the content.
OCISodaRemoveOneWithKey()

Removes a document from a collection given a key.
OCISodaReplOneAndGetWithKey()

Replaces a document in a collection given a key and returns the handle to the result document containing document components, including the updated ones, such as last-modified timestamp, version, and media type.
OCISodaReplOneWithKey()

Replaces a document in a collection given a key.

36.2.1 OCISodaCollCreate()

Creates a new document collection with default metadata settings.

Purpose

To create a new document collection with default metadata settings.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
collname (IN)

The name of the collection.
collnamelen (IN)

The length of the collection name.
collection (OUT)

Allocates the collection handle representing the document collection that was created. Call OCIHandleFree() to free the collection handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

Returns

OCI_SUCCESS, if the collection is successfully created.

OCI_ERROR, if the collection is not created. The OCIError parameter has the necessary error information.

Usage Notes

  • If the collection with the specified name already exists, then this function acts as OCISodaCollOpen() and opens the existing collection.

Examples

Example 36-1 Creating a Collection

See the example in Oracle Database SODA for C Developer's Guide.

36.2.2 OCISodaCollCreateWithMetadata()

Creates a new document collection with metadata.

Purpose

To create a new document collection with metadata.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
collname (IN)

The name of the collection.
collnamelen (IN)

The length of the collection name.
metadata (IN)

The JSON string that contains the collection metadata information. If metadata is NULL, it uses the default metadata settings to create the collection.

metadatalen (IN)

The length of the metadata JSON string.
collection (OUT)

Allocates the collection handle representing the document collection that was created. Call OCIHandleFree() to free the collection handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

Returns

OCI_SUCCESS, if the collection is successfully created.

OCI_ERROR, if the collection is not created. The OCIError parameter has the necessary error information.

Usage Notes

  • If the collection with the specified name already exists and that collection has metadata equivalent to the supplied metadata, then this function acts as OCISodaCollOpen() and opens the existing collection. If the collection contains metadata that does not match with the specified collection name, then an error is returned.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.3 OCISodaCollOpen()

Opens the collection.

Purpose

To open the collection.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
collname (IN)

The name assigned to the collection.
collnamelen (IN)

The length of the collection name.
coll (OUT)

Allocates the collection handle and returns it with the specified collection name. The function returns OCI_SUCCESS if there are no errors while trying to open the collection. If the collection with the supplied name is not present, that is not considered an error and returns OCI_SUCCESS, but the collection-handle pointer returns as NULL. So a way to check if the collection exists and was successfully opened, is to check that the coll (OUT) pointer is not NULL after this function returns with OCI_SUCCESS. Call OCIHandleFree() to free the collection handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

    Note:

    This operation does not make any changes to the database; however, you can use this mode to commit an existing transaction without performing another round trip.

Returns

OCI_SUCCESS, if there were no errors while trying to open the collection.

OCI_ERROR, if errors were encountered while trying to open the collection. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the examples in Oracle Database SODA for C Developer's Guide and Oracle Database SODA for C Developer's Guide.

36.2.4 OCISodaCollList()

Lists the collections in the schema associated with the supplied service context handle parameter.

Purpose

To list the collections in the schema.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
startname (IN)

The collection start name. Can be set to NULL and stnamelen set to the value 0 to return all existing collections.

stnamelen (IN)

The length of the collection start name.
cur (OUT)

Allocates the collection cursor handle and returns it. The collection cursor represents the collection list. Call OCIHandleFree() to free the collection cursor handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

    Note:

    This operation does not make any changes to the database; however, you can use this mode to commit an existing transaction without performing another round trip.

Returns

OCI_SUCCESS, if getting a cursor over all collections in the schema is successful.

OCI_ERROR, if getting a cursor over all collections in the schema is not successful. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.5 OCISodaCollGetNext()

Gets the next collection from the collection cursor.

Purpose

Get the next collection from the collection cursor.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
cur (IN)

The collection cursor handle remains valid when allocated by OCISodaCollList(). Call OCIHandleFree() to free the collection cursor handle when it is no longer required.

coll (OUT)

Allocates the collection handle and returns it to the next collection to be found. Call OCIHandleFree() to free the collection handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

Returns

OCI_SUCCESS, if the next collection is returned from the specified cursor.

OCI_ERROR, if there was an error fetching the next collection. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in Oracle Database SODA for C Developer's Guide

36.2.6 OCISodaCollDrop()

Drops a collection from the database.

Purpose

To drop a collection from the database.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
coll (IN)

The collection to be dropped. If coll no longer references an existing collection, then no error is returned, but isDropped is FALSE indicating the drop operation was not successful after the invocation of OCISodaCollDrop().

isDropped (OUT)

Returns the status of the drop operation: TRUE if the drop operation is successful, FALSE if the drop operation is not successful.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

Returns

OCI_SUCCESS, if dropping the collection is successful.

OCI_ERROR, if dropping the collection failed. The OCIError parameter has the necessary error information.

Usage Notes

  • This function only drops the collection; it does not free the collection handle. Call OCIHandleFree() to free the collection handle to avoid memory leaks.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.7 OCISodaDocCreate()

Creates a document.

Purpose

To create a document.

Syntax

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

Parameters

Parameter Description
envhp (IN)

The environment handle.
content(IN)

A string containing the document content.
contentLength (IN)

The string length of the content parameter.
docFlags (IN)
Used to detect JSON encoding while creating a document. Valid flag options are:
  • OCI_DEFAULT — If you use this parameter value then you are, in effect, declaring that the document content is in the character set defined by the environment handle (or environment variable NLS_LANG, if not set for the handle). If that is not the case for a given document, then the result of trying to write the document is unpredictable.

  • OCI_SODA_DETECT_JSON_ENC — Automatically detects the encoding of the document content as either UTF-8, UTF-16 LE, or UTF-16 BE. If you use this parameter value then you are, in effect, declaring that the document content is either UTF-8, UTF-16 LE, or UTF-16 BE. If that is not the case for a given document, then the result of trying to write the document is unpredictable.

document (OUT)

Allocates and returns the document handle. Call OCIHandleFree() to free the document handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

Returns

OCI_SUCCESS, if the document is successfully created.

OCI_ERROR, if the document creation failed. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

Example 36-2 Creating a Document

See the example in Oracle Database SODA for C Developer's Guide.

36.2.8 OCISodaDocCreateWithKey()

Creates a document with a document key and content.

Purpose

To create a document with a document key and content.

Syntax

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

Parameters

Parameter Description
envhp (IN)

The environment handle.
content (IN)

A string containing the document content.
contentLength (IN)

The string length of the content parameter.
key (IN)

A string that contains the document key. The key can be NULL.

For example, in the default case, collection has auto-generated keys, so you do not want to set the key on the document (if you do, you get an error when you pass such a doc to a write operation, such as insert). You only want to set a non-NULL key if your collection is configured with client-assigned keys, which is not the default.

keylen (IN)

The length of the key string.
docFlags (IN)
The flags used to create a document. Valid flag options are:
  • OCI_DEFAULT — If you use this parameter value then you are, in effect, declaring that the document content is in the character set defined by the environment handle (or environment variable NLS_LANG, if not set for the handle). If that is not the case for a given document, then the result of trying to write the document is unpredictable.

  • OCI_SODA_DETECT_JSON_ENC — Automatically detects the encoding of the document content as either UTF-8, UTF-16 LE, or UTF-16 BE. If you use this parameter value then you are, in effect, declaring that the document content is either UTF-8, UTF-16 LE, or UTF-16 BE. If that is not the case for a given document, then the result of trying to write the document is unpredictable.

document (OUT)

Allocates and returns the document handle. Call OCIHandleFree() to free the document handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

Returns

OCI_SUCCESS, if the document is successfully created.

OCI_ERROR, if the document creation failed. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

This code snippet shows how to create a document with a key.

Example 36-3 Creating a Document with a Key

See the example in Oracle Database SODA for C Developer's Guide.

36.2.9 OCISodaDocCreateWithKeyAndMType()

Creates a document with a document key, content, and media type.

Purpose

To create a document with a document key, content, and media type.

Syntax

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);

Parameters

Parameter Description
envhp (IN)

The environment handle.
content (IN)

A string containing the document content.
contentLength (IN)

The string length of the content parameter.
key (IN)

A string that contains the document key. The key can be NULL.

For example, in the default case, collection has auto-generated keys, so you do not want to set the key on the document (if you do, you get an error when you pass such a doc to a write operation, such as insert). You only want to set a non-NULL key if your collection is configured with client-assigned keys, which is not the default.

keylen (IN)

The length of the key string.
mediaType (IN)

A string that contains the document media type. If no media type value is specified, it defaults to "application/json". By specifying a value, you can create non-JSON documents (using a media type other than "application/json").

mediaTypeLength (IN)

The length of the media type string.
docFlags (IN)
The flags used to create the document. Valid flag options are:
  • OCI_DEFAULT — If you use this parameter value then you are, in effect, declaring that the document content is in the character set defined by the environment handle (or environment variable NLS_LANG, if not set for the handle). If that is not the case for a given document, then the result of trying to write the document is unpredictable.

  • OCI_SODA_DETECT_JSON_ENC — Automatically detects the encoding of the document content as either UTF-8, UTF-16 LE, or UTF-16 BE. If you use this parameter value then you are, in effect, declaring that the document content is either UTF-8, UTF-16 LE, or UTF-16 BE. If that is not the case for a given document, then the result of trying to write the document is unpredictable.

document (OUT)

Allocates and returns the document handle. Call OCIHandleFree() to free the document handle when it is no longer required.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

Returns

OCI_SUCCESS, if the document is successfully created.

OCI_ERROR, if the document creation failed. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

Example 36-4 Creating a Document with a Key and Multimedia Type

See Oracle Database SODA for C Developer's Guide for more information about this function.

36.2.10 OCISodaFindOneWithKey()

Finds a single document in a collection given a key.

Purpose

To find a single document in a collection given a key.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
coll (IN)

The collection to search for the document.
key (IN)

The key used to identify the document.
keylen (IN)

The length of the key.
docFlags (IN)
The following flags control the encoding of the returned document's content. Valid flag options are:
  • OCI_DEFAULT — Document content is returned in the character set defined by the environment handle (or environment variable NLS_LANG, if not set for the handle).

  • OCI_SODA_AS_STORED — Document content is returned in the character set in which the content was stored in the database. Use this parameter value only for BLOB content. If the content is not stored in a BLOB instance then an error is raised.

  • OCI_SODA_AS_AL32UTF8 — Document content is returned in the character set AL32UTF8.

doc (OUT)

Allocates and returns the document handle if the document is found in the collection. If the document is not found in the collection, a NULL document is returned and the function returns OCI_NO_DATA. Call OCIHandleFree() to free the collection handle when the find operation completes.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

    Note:

    This operation does not make any changes to the database; however, you can use this mode to commit an existing transaction without performing another round trip.

Returns

OCI_SUCCESS, if the document is found in the specified collection.

OCI_NO_DATA, if the document was not found.

OCI_ERROR, if there was an error in trying to find the document. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

Example 36-5 Finding One Document Using a Key

See the example in Oracle Database SODA for C Developer's Guide.

36.2.11 OCISodaInsert()

Inserts a document into a collection.

Purpose

To insert a document into a collection.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
collection (IN)

The collection handle for an existing collection.
document (IN)

The handle of the document that is to be inserted into the collection.
errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

Returns

OCI_SUCCESS, if the document insertion into the specified collection is successful.

OCI_ERROR, if the document insertion failed. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.12 OCISodaInsertAndGet()

Inserts a document into a collection, returning a result document containing all document components except for content.

Purpose

To insert a document into a collection, returning a result document containing all document components except for content. The components generated by SODA during the insert, such as key (if the collection has auto-assigned keys), last-modified timestamp, created-on timestamp, and version, are returned as part of the result document.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
collection (IN)

The collection handle for an existing collection.
document (IN/OUT)

The handle of the document that is to be inserted into the collection. Returns the result document through this same parameter as it is an IN/OUT.

Caution:

Because the result document is returned using the same parameter, you need to save a reference to the input document handle so that you can free it later, along with the result document handle, using OCIHandleFree(). If you do not save a reference to the input document handle, it is overwritten with a reference to the result document, and the input document handle will never be properly freed (it's a memory leak).

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

Returns

OCI_SUCCESS, if the document insertion into the specified collection is successful.

OCI_ERROR, if the document insertion failed. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.13 OCISodaInsertAndGetWithCtnt()

Inserts a document into a collection using just the content, returning a result document containing all document components except for content.

Purpose

To insert a document into a collection using just the content, returning a result document containing all document components except for content. The components generated by SODA during the insert, such as key (if the collection has auto-assigned keys), last-modified timestamp, created-on timestamp, and version, are returned as part of the result document.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
collection (IN)

The collection handle for an existing collection.

key (IN)

A string that contains the document key. Must be NULL if inserting a document into a collection configured for auto-generated keys.

keyLength (IN)

The length of the key string. Must be 0 if inserting a document into a collection configured for auto-generated keys.
content (IN)

A string containing the document content.
contentLength (IN)

The string length of the content parameter.

docFlags (IN)
The encoding flags used to indicate the encoding of the supplied document's content. Valid flag options are:
  • OCI_DEFAULT — If you use this parameter value then you are, in effect, declaring that the document content is in the character set defined by the environment handle (or environment variable NLS_LANG, if not set for the handle). If that is not the case for a given document, then the result of trying to write the document is unpredictable.

  • OCI_SODA_DETECT_JSON_ENC — Automatically detects the encoding of the document content as either UTF-8, UTF-16 LE, or UTF-16 BE. If you use this parameter value then you are, in effect, declaring that the document content is either UTF-8, UTF-16 LE, or UTF-16 BE. If that is not the case for a given document, then the result of trying to write the document is unpredictable.

document (OUT)

Allocates and returns a result document containing all document components except for content. The components generated by SODA during the insert, such as key (if the collection has auto-assigned keys), last-modified timestamp, created-on timestamp, and version, are returned as part of the result document.

If NULL is passed for this parameter, then the result document is not returned. (In other words, the function then behaves identically to the OCISodaInsertWithCtnt() function, which does not return a result document).

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

Returns

OCI_SUCCESS, if the document insertion into the specified collection is successful.

OCI_ERROR, if the document insertion failed. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See Oracle Database SODA for C Developer's Guide for more information about this function.

36.2.14 OCISodaInsertWithCtnt()

Inserts a document into a collection using just the content.

Purpose

To insert a document into a collection using just the content.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
collection (IN)

The collection handle for an existing collection.

key (IN)

A string that contains the document key. Must be NULL if inserting a document into a collection configured for auto-generated keys.

keyLength (IN)

The length of the key string. Must be 0 if inserting a document into a collection configured for auto-generated keys.
content (IN)

The content of the document.
contentLength (IN)

The length of the document content.
docFlags (IN)
The encoding flags used to indicate the encoding of the supplied document's content. Valid flag options are:
  • OCI_DEFAULT — If you use this parameter value then you are, in effect, declaring that the document content is in the character set defined by the environment handle (or environment variable NLS_LANG, if not set for the handle). If that is not the case for a given document, then the result of trying to write the document is unpredictable.

  • OCI_SODA_DETECT_JSON_ENC — Automatically detects the encoding of the document content as either UTF-8, UTF-16 LE, or UTF-16 BE. If you use this parameter value then you are, in effect, declaring that the document content is either UTF-8, UTF-16 LE, or UTF-16 BE. If that is not the case for a given document, then the result of trying to write the document is unpredictable.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

Returns

OCI_SUCCESS, if the document insertion into the specified collection is successful.

OCI_ERROR, if the document insertion failed. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.15 OCISodaRemoveOneWithKey()

Removes a document from a collection given a key.

Purpose

To remove a document from a collection given a key.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
coll (IN)

The collection handle for an existing collection.
key (IN)

The key of the document to be removed.
keylength (IN)

The length of key of the document to be removed.
isRemoved (OUT)

Returns TRUE if a document was found with the specified key and removed; FALSE if no document could be found with the specified key.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

Returns

OCI_SUCCESS, if the document with the specified key was not found. OCI_SUCCESS is still returned (and isRemoved will be set to FALSE). Check that the isRemoved parameter is set to TRUE to know whether the document has been removed.

OCI_ERROR, if the document removal operation failed during execution due to a SQL error. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.16 OCISodaReplOneAndGetWithKey()

Replaces a document in a collection given a key and returns the handle to the result document.

Purpose

To replace a document in a collection given a key and return the handle to the result document containing all components except content, including the updated ones, such as the last-modified timestamp and version.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
coll (IN)

The collection handle for an existing collection.
key (IN)

The key used to identify the document.
keylength (IN)

The length of the key.
document (IN/OUT)

The document handle to use as the replacement of the document currently in the collection. Only the content and media type component from this handle is used during the replace operation (that is, this operation replaces the content and media type of the document in the collection). Other components, if set on the input document, are ignored. Returns the result document through this same parameter as it is an IN/OUT.

Caution:

Because the result document is returned using the same parameter, you need to save a reference to the input document handle so that you can free it later, along with the result document handle, using OCIHandleFree(). If you do not save a reference to the input document handle, it is overwritten with a reference to the result document, and the input document handle will never be properly freed (it's a memory leak).

isReplaced (OUT)

Returns TRUE if a document was found with the specified key and replaced; FALSE if no document could be found with the specified key.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

Returns

OCI_SUCCESS, if the document with the specified key was not found. OCI_SUCCESS is still returned (and isReplaced will be set to FALSE). Check that the isReplaced parameter is set to TRUE to know whether the document has been replaced.

OCI_ERROR, if the document replacement operation failed during execution due to a SQL error. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in Oracle Database SODA for C Developer's Guide.

36.2.17 OCISodaReplOneWithKey()

Replaces a document in a collection given a key.

Purpose

To replace a document in a collection given a key.

Syntax

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

Parameters

Parameter Description
svchp (IN)

The service context handle.
coll (IN)

The collection handle for an existing collection.
key (IN)

The key used to identify the document.
keylength (IN)

The length of the key.
document (IN)

The document handle to use as the replacement of the document currently in the collection. Only the content and media type component from this handle is used during the replace operation (that is, this operation replaces the content and media type of the document in the collection). Other components, if set on the input document, are ignored.
isReplaced (OUT)

Returns TRUE if a document was found with the specified key and replaced; FALSE if no document could be found with the specified key.

errhp (IN/OUT)

The error handle.
mode (IN)
Specifies the mode of execution. Valid modes are:

  • OCI_DEFAULT — Is the default mode. It means execute the operation as is with no special modes.

  • OCI_SODA_COMMIT_ON_SUCCESS — When an operation executes in this mode and it completes successfully then the current transaction is committed after completion. (Mode parameter OCI_SODA_COMMIT_ON_SUCCESS acts analogously to how OCI_COMMIT_ON_SUCCESS acts for OCIStmtExecute().)

Returns

OCI_SUCCESS, if the document with the specified key was not found. OCI_SUCCESS is still returned (and isReplaced will be set to FALSE). Check that the isReplaced parameter is set to TRUE to know whether the document has been replaced.

OCI_ERROR, if the document replacement operation failed during execution due to a SQL error. The OCIError parameter has the necessary error information.

Usage Notes

None.

Examples

See the example in OCISodaFindOneWithKey().