This chapter provides an overview of the OCI interface for XStream.
This chapter contains these topics:
Since Oracle Database 11g Release 2, APIs, known as XStream Out and XStream In, are available.
This technology enables high performance, near real-time information-sharing infrastructure between Oracle databases and non-Oracle databases, non-RDBMS Oracle products, file systems, third party software applications, and so on. XStream is built on the infrastructure used by Oracle Streams.
OCI XStream functions in OCI XStream Functions
XStream Out allows a remote client to attach to an outbound server and extract row changes in the form of logical change records (LCRs).
To use XStream Out, a capture process and an outbound server must be created. All data types supported by Oracle Streams, including LOB,
XMLType, are supported by XStream. The capture process and the outbound server need not be on the same database instance. After the capture process and the outbound server have started, row changes are captured and sent to the outbound server. An external client application can connect to this outbound server using OCI. After the connection is established, the client application can loop while waiting for LCRs from the outbound server. The client application can register a client-side callback to be invoked each time an LCR is received. At any time, the client application can detach from the outbound server as needed. Upon restart, the outbound server knows where in the redo stream to start streaming LCRs to the client application.
To replicate non-Oracle data into Oracle databases, use XStream In.
This technology allows a remote client application to attach to an inbound server and send row and DDL changes in the form of LCRs.
An external client application connects to the inbound server using OCI. After the connection is established, the client application acts as the capture agent for the inbound server by streaming LCRs to it. A client application can attach to only one inbound server for each database connection, and each inbound server only allows one client application to attach to it.
XStream In concepts in Oracle Database XStream Guide
Each LCR has a position attribute.
The position of an LCR identifies its placement in the stream of LCRs in a transaction.
Position order in an LCR in Oracle Database XStream Guide
XStream Out implicitly converts character data in LCRs from the outbound server database character set to the client application character set. XStream In implicitly converts character data in LCRs from the client application character set to the inbound server database character set.
To improve performance, complete the following tasks:
Analyze the LCR data flow from the source to the destination.
Set the client character set of the OCI client application to the one that minimizes character conversion, incurs no data loss, and takes advantage of the implicit conversion done by XStream or the destination.
For XStream Out, in general, setting the client application character set to the outbound server database character set is the best practice.
This chapter describes the attributes for OCI handles and descriptors, which can be read with
OCIAttrGet() and modified with
For each handle type, the attributes that can be read or changed are listed. Each attribute listing includes the following information:
The following modes are valid:
READ - The attribute can be read using
WRITE - The attribute can be modified using
READ/WRITE - The attribute can be read using
OCIAttrGet(), and it can be modified using
This is a description of the purpose of the attribute.
This is the data type of the attribute. If necessary, a distinction is made between the data type for
The following server handle attributes are available:
For XStream Out, the ACK interval is the minimum interval in seconds that the outbound server receives the processed low position from the client application. After each ACK interval, the outbound server ends any in-progress
OCIXStreamOutLCRCallbackReceive() call so that the processed low position cached at the client application can be sent to the outbound server.
For XStream In, the ACK interval is the minimum interval in seconds that the inbound server sends the processed low position to the client application. After each ACK interval, any in-progress
OCIXStreamInLCRCallbackSend() call is terminated for the inbound server to send a new processed low position to the client application.
The default value for
OCI_ATTR_XSTREAM_ACK_INTERVAL is 30 seconds. This attribute is checked only during the
OCIXStreamInAttach() calls. Thus, it must be set before invoking these APIs; otherwise, the default value is used.
The idle timeout is the number of seconds of idle the outbound server waits for an LCR before terminating the
The default for
OCI_ATTR_XSTREAM_IDLE_TIMEOUT is one second. This attribute is checked only during the
OCIXStreamInAttach() call. Thus, it must be set before invoking these APIs; otherwise, the default value is used.