OCI XML DB Functions

Table 23-2 lists the OCI XML DB functions that are described in this chapter.

Table 23-2 OCI XML DB Functions  

Function Purpose

"OCIBinXmlCreateReposCtxFromConn()"

Create metadata connection context

"OCIBinXmlCreateReposCtxFromCPool()"

Create metadata connection context connection pool

"OCIBinXmlSetFormatPref()"

Specify that images transferred are in binary XML format

"OCIBinXmlSetReposCtxForConn()"

Associate data connection with the metadata connection

"OCIXmlDbFreeXmlCtx()"

Free an XML context

"OCIXmlDbInitXmlCtx()"

Initialize an XML context for XML data from the database


OCIBinXmlCreateReposCtxFromConn()

Purpose

Creates a metadata connection context (OCIBinXmlReposCtx) from the specified OCIEnv/OCISvcCtx dedicated OCI connection. Note that this connection is dedicated to metadata use.

Syntax

sword OCIBinXmlCreateReposCtxFromConn (   OCIEnv             *env, 
                                          OCISvcCtx          *svcctx,
                                          OCIError           *err,
                                          OCIBinXmlReposCtx  **ctx);

Parameters

env (IN)

The environment handle.

svcctx (IN)

The handle to the connection to be used to access the metadata.

err (IN)

The error handle.

ctx (OUT)

The metadata context that is created and returned.

Returns

Returns -1 for error, 0 for success. The err parameter contains more information about the error.

OCIBinXmlCreateReposCtxFromCPool()

Purpose

Creates a metadata connection context (OCIBinXmlReposCtx) from the specified connection pool. A connection from the connection pool is used whenever any information from the token repository is needed.

Syntax

sword OCIBinXmlCreateReposCtxFromCPool (   OCIEnv             *env, 
                                           OCICPool           *cpool,
                                           OCIError           *err,
                                           OCIBinXmlReposCtx  **ctx);

Parameters

env (IN)

The environment handle.

cpool (IN)

The handle to the connection to be used to access the metadata.

err (IN)

The error handle.

ctx (OUT)

The metadata context that is created and returned.

Returns

Returns -1 for error, 0 for success. The err parameter contains more information about the error.

OCIBinXmlSetFormatPref()

Purpose

Specifies that the images being transferred between client and server for the XML document be in binary XML format. In the future, all communication will be in the binary XML format. Binary XML-aware applications can set this.

Syntax

sword OCIBinXmlSetFormatPref (   xmldomdoc   *doc,
                                 ub4         formattype);

Parameters

doc (IN)

The pointer to the domdoc to which the preference is to be applied.

formattype (IN)

The type of format to be used for pickling. Currently the only values allowed are OCIXML_FORMATTYPE_TEXT and OCIXML_FORMATTYPE_BINXML.

Returns

Returns -1 for error, 0 for success.

Related Functions

OCIBinXmlSetReposCtxForConn()

OCIBinXmlSetReposCtxForConn()

Purpose

Associates the data connection with the metadata connection. Note that with a dedicated connection, the environment handle must be the same for the data connection and for the metadata connection.

Syntax

sword OCIBinXmlSetReposCtxForConn (   OCISvcCtx          *dataconn,
                                      OCIBinXmlReposCtx  *reposctx);

Parameters

dataconn (IN)

The data connection handle.

reposctx (IN)

The pointer to the metadata connection.

Returns

Returns -1 for error, 0 for success. The err parameter contains more information about the error.

Related Functions

OCIBinXmlSetFormatPref()

OCIXmlDbFreeXmlCtx()

Purpose

Frees any allocations made by the call to OCIXmlDbInitXmlCtx().

Syntax

void OCIXmlDbFreeXmlCtx ( xmlct   *xctx ); 

Parameters

xctx (IN)

The XML context to terminate.

Comments

See Also:

"Using OCI XML DB Functions" for a usage example

Returns

Returns -1 for error, 0 for success.

Related Functions

OCIXmlDbInitXmlCtx()

OCIXmlDbInitXmlCtx()

Purpose

Initializes an XML context for XML data from the database.

Syntax

xmlctx *OCIXmlDbInitXmlCtx (   OCIEnv                *envhp,
                               OCISvcCtx             *svchp,
                               OCIError              *errhp,
                               ocixmldbparam         *params,
                               ub4                   num_params ); 

Parameters

envhp (IN)

The OCI environment handle.

svchp (IN)

The OCI service handle.

errhp (IN)

The OCI error handle.

params (IN)

The optional possible values in this array are pointers to either the OCI duration, in which the default value is OCI_DURATION_SESSION, or to an error handler that is a user-registered callback of prototype:

void (*err_handler) (sword errcode, (const OraText *) errmsg);

The two parameters of err_handler are:

errcode (OUT)

A numeric error value.

errmsg (OUT)

The error message text.

num_params (IN)

Number of parameters to be read from params. If the value of num_params exceeds the size of array params, unexpected behavior results.

Comments

See Also:

"Using OCI XML DB Functions" for a usage example

Returns

Returns either:

  • A pointer to structure xmlctx, with error handler and callbacks populated with appropriate values. This is later used for all OCI calls.

  • NULL, if no database connection is available.

Related Functions

OCIXmlDbFreeXmlCtx()