34 DBMS_CDC_SUBSCRIBE

Syntax

DBMS_CDC_SUBSCRIBE.ACTIVATE_SUBSCRIPTION (
     subscription_name  IN VARCHAR2);

Parameters

Exceptions

Usage Notes

• The ACTIVATE_SUBSCRIPTION procedure indicates that the subscriber is finished subscribing to tables, and the subscription is ready to start accessing change data.

• Once the subscriber activates the subscription:

  • No additional source tables can be added to the subscription.

  • Change Data Capture holds the available data for the source tables and sets the subscription window to empty.

  • The subscriber must use the EXTEND_WINDOW procedure to see the initial set of change data.

  • The subscription cannot be activated again.

• A subscription cannot be activated if the underlying change set has reached its end_date parameter value.

Syntax

DBMS_CDC_SUBSCRIBE.CREATE_SUBSCRIPTION (
     change_set_name      IN  VARCHAR2,
     description          IN  VARCHAR2,
     subscription_name    IN  VARCHAR2);

Parameters

Exceptions

Usage Notes

• The CREATE_SUBSCRIPTION procedure allows a subscriber to register interest in a change set associated with source tables of interest.

• A subscriber can query the ALL_PUBLISHED_COLUMNS view to see all the published source tables for which the subscriber has privileges and the change sets in which the source table columns are published.

• Subscriptions are not shared among subscribers; rather, each subscription name is validated against a given subscriber's login ID.

• Subscriptions cannot be created if the underlying change set has reached its end_date parameter value.

Syntax

DBMS_CDC_SUBSCRIBE.DROP_SUBSCRIPTION (
     subscription_name  IN VARCHAR2);

Parameters

Exceptions

Usage Notes

Subscribers should be diligent about dropping subscriptions that are no longer needed so that change data will not be held in the change tables unnecessarily.

Syntax

DBMS_CDC_SUBSCRIBE.EXTEND_WINDOW (
     subscription_name  IN VARCHAR2,
     upper_bound        IN DATE DEFAULT NULL);

Parameters

Exceptions

Usage Notes

• Until the subscriber calls the EXTEND_WINDOW procedure to begin receiving change data, the subscription window remains empty.

  • The first time that the subscriber calls the EXTEND_WINDOW procedure, it establishes the initial boundaries for the subscription window.

  • Subsequent calls to the EXTEND_WINDOW procedure extend the high boundary of the subscription window so that new change data can be seen.

• Oracle recommends that subscribers not view change tables directly. Instead, subscribers should use the DBMS_CDC_SUBSCRIBE package and access data through subscriber views only. Control column values are guaranteed to be consistent only when viewed through subscriber views that have been updated with a call to the EXTEND_WINDOW procedure.

• When the underlying change set for a subscription has reached its end_date parameter value, subsequent calls to the EXTEND_WINDOW procedure will not raise the high boundary.

• Subscriptions employing synchronous Change Data Capture are not allowed to extend the window to a specified date. Hence, the upper_bound parameter should not be specified.

Syntax

DBMS_CDC_SUBSCRIBE.PURGE_WINDOW (
     subscription_name   IN VARCHAR2,
     lower_bound         IN DATE DEFAULT NULL);

Parameters

Exceptions

Usage Notes

• When finished with a set of changes, the subscriber purges the subscription window with the PURGE_WINDOW procedure. By this action, the subscriber performs the following functions:

  • Informs Change Data Capture that the subscriber is finished with the current set of change data.

  • Enables Change Data Capture to remove change data that is no longer needed by any subscribers.

  Change Data Capture manages the change data to ensure that it is available as long as there are subscribers who need it.

• When the underlying change set for a subscription has reached its end_date parameter value, subsequent calls to the PURGE_WINDOW procedure will not move the low boundary.

Syntax

There are two versions of syntax for the SUBSCRIBE procedure, as follow:

• Using source schema and source table

  When this syntax is used, Change Data Capture will attempt to find a single publication ID that contains the specified source_table and column_list. If such a publication cannot be found, then Change Data Capture returns an error.

  DBMS_CDC_SUBSCRIBE.SUBSCRIBE (
       subscription_name    IN VARCHAR2,
       source_schema        IN VARCHAR2,
       source_table         IN VARCHAR2,
       column_list          IN VARCHAR2,
       subscriber_view      IN VARCHAR2);
  

• Using publication IDs

  When this syntax is used, Change Data Capture will use the publication ID to identify the change table. If the columns specified in the column_list parameter are not in the identified change table, then Change Data Capture returns an error.

  DBMS_CDC_SUBSCRIBE.SUBSCRIBE (
     subscription_name    IN VARCHAR2,
     publication_id       IN NUMBER,
     column_list          IN VARCHAR2,
     subscriber_view      IN VARCHAR2);
  

Parameters

Exceptions

Usage Notes

• The SUBSCRIBE procedure allows a subscriber to subscribe to one or more published source tables and to specific columns in each source table. Each call to the SUBSCRIBE procedure can specify only a single source table or publication ID. The subscriber can make multiple calls to the SUBSCRIBE procedure to include multiple source tables or publications IDs in a subscription.

• If the columns of interest are all in a single publication, the subscriber can call the SUBSCRIBE procedure using the source_schema and source_table parameters or using the publication_id parameter. However, if there are multiple publications on a single source table and these publications share some columns, and if any of the shared columns will be used by a single subscription, then the subscriber should call the SUBSCRIBE procedure using the publication_id parameter.

• The subscriber can subscribe to any valid publication ID on which the subscriber has privileges to access. The subscriber can find valid publication IDs on which the subscriber has access by querying the ALL_PUBLISHED_COLUMNS view.

• A subscriber can query the ALL_PUBLISHED_COLUMNS view to see all the published source table columns accessible to the subscriber.

• Subscriptions must be created before a subscriber calls the SUBSCRIBE procedure. Change Data Capture does not guarantee that there will be any change data available at the moment the subscription is created.

• Subscribers can subscribe only to published columns from the source table. All of the columns specified in a single call to the SUBSCRIBE procedure must come from the same publication. Any control columns associated with the underlying change table are added to the subscription automatically.

• All specified source tables or publications must be in the change set that is associated with the named subscription.

• A single source table can have more than one publication defined on it. A subscriber can subscribe to one or more of these publications. However a subscriber can subscribe to a particular publication only once.

• Each publication in a subscription has its own subscriber view. Subscriber views are used to query the change data encompassed by the subscription's current window. Subscriber views are created in the schema of the subscriber.

• A subscriber cannot subscribe to a publication within a change set that has reached its end_date parameter value.