The Oracle Call Interface (OCI) includes an interface for XStream. This chapter provides an introduction to the OCI interface for XStream.
This chapter contains these topics:
This chapter provides an overview of the OCI interface for XStream. For detailed information about XStream concepts, see XStream Out concepts in Oracle Database XStream Guide.
See Also:
OCI XStream functions in Chapter 26
Configuring XStream Out in Oracle Database XStream Guide
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.
See Also:
OCI XStream functions in Chapter 26XStream Out allows a remote client to attach to an outbound server and extract row changes in the form of logical change records (LCRs). For the basics of LCRs, see Oracle Streams Concepts and Administration.
To use XStream Out, a capture process and an outbound server must be created. All data types supported by Oracle Streams, including LOB, LONG, and 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.
See Also:
Introduction to XStream Out in Oracle Database XStream GuideTo 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.
See Also:
XStream In concepts in Oracle Database XStream GuideEach LCR has a position attribute. The position of an LCR identifies its placement in the stream of LCRs in a transaction.
See Also:
Position order in an LCR in Oracle Database XStream GuideXStream 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 OCIAttrSet().
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 OCIAttrGet().
WRITE - The attribute can be modified using OCIAttrSet().
READ/WRITE - The attribute can be read using OCIAttrGet(), and it can be modified using OCIAttrSet().
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 READ and WRITE modes.
The following server handle attributes are available:
READ/WRITE
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 OCIXStreamOutLCRReceive() or 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 OCIXStreamInLCRSend() or 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 OCIXStreamOutAttach() or OCIXStreamInAttach() calls. Thus, it must be set before invoking these APIs; otherwise, the default value is used.
ub4 */ub4
READ/WRITE
The idle timeout is the number of seconds of idle the outbound server waits for an LCR before terminating the OCIXStreamOutLCRReceive() or OCIXStreamOutLCRCallbackReceive() call.
The default for OCI_ATTR_XSTREAM_IDLE_TIMEOUT is one second. This attribute is checked only during the OCIXStreamOutAttach() or OCIXStreamInAttach() call. Thus, it must be set before invoking these APIs; otherwise, the default value is used.
ub4 */ub4