create article

Description

Creates an article for a table or function replication definition and specifies the publication that is to contain the article.

Syntax

create article article_name
        for pub_name
with primary at data_server.database
with replication definition {table_rep_def | function_rep_def}
        [where {column_name | @param_name}
                {< | > | >= | <= | = | &} value
        [and {column_name | @param_name}
                {< | > | >= | <= | = | &} value]...
        [or where {column_name | @param_name}
                {< | > | >= | <= | = | &} value 
        [and {column_name | @param_name}
                {< | > | >= | <= | = | &} value]...]...]

Parameters

article_name: A name for the article. It must conform to the rules for identifiers and be unique within the publication.

for pub_name: The name of the publication that contains the article.

with primary at data_server.database: Specifies the location of the primary data. If the primary database is part of a warm standby application, data_server.database is the name of the logical data server and database.

with replication definition table_rep_def: Specifies the name of the table replication definition the article is for.

with replication definition function_rep_def: Specifies the name of the function replication definition the article is for.

where: Sets criteria for the column or parameter values to be replicated via a subscription to the publication that contains this article. If no where clause is included, all rows or parameters are replicated.

A where clause is composed of one or more simple comparisons, where a searchable column or searchable parameter is compared to a literal value with one of the following relational operators: <, >, <=, >=, =, or &. (The & operator is supported only for rs_address columns or parameters.) You can join comparisons with the keyword and.

Column or parameter names used in a where clause must also be included in the searchable columns list of the table replication definition or the searchable parameters list of the function replication definition.

You can include multiple where clauses in an article, separated with the keyword or.

The maximum size of a where clause in an article is 255 characters.

column_name: A column name from the primary table, for an article that contains a table replication definition.

@param_name: A parameter name from a replicated stored procedure, for an article that contains a function replication definition.

value

A value for a specified column or parameter. See “Datatypes” for entry formats for values for different datatypes.

Column or parameter names used in the expression must be included in the searchable columns or searchable parameters list of the replication definition.

Examples

Example 1

Creates an article called titles_art for the publication pubs2_pub, based on the replication definition titles_rep:

create article titles_art
 for publication pubs2_pub
 with primary at TOKYO_DS.pubs2
 with replication definition titles_rep

Example 2

Creates an article called titles_art for the publication pubs2_pub, as in the previous example. This command includes a where clause that replicates only the rows for popular computing books, for which the type column is set to “popular_comp”:

create article titles_art
 for publication pubs2_pub
 with primary at TOKYO_DS.pubs2
 with replication definition titles_rep
 where type = 'popular_comp'

Example 3

Creates an article called titles_art for the publication pubs2_pub, as in the previous examples. This command includes two where clauses that together replicate the rows for both popular computing books and traditional cookbooks:

create article titles_art
 for publication pubs2_pub
 with primary at TOKYO_DS.pubs2
 with replication definition titles_rep
 where type = 'popular_comp'
 or where type = 'trad_cook'

Usage

Use create article to specify a replication definition for which you want to replicate data using a specified publication. Optional where clauses help determine which data is replicated.
Execute create article at the Replication Server that manages the database where the primary data is stored.
Using create article automatically invalidates the publication the article is for. You cannot create new subscriptions until you validate the publication. You cannot replicate data for the new articles until you refresh the subscription.
For more information about working with replication definitions, articles, and publications, see the Replication Server Administration Guide Volume 1.

For more information about subscribing to publications, refer to Chapter 10, “Managing Subscriptions,” in the same book.
Replication Server distributes information about a publication and its articles to a replicate site only when you create or refresh a subscription for the publication.

Requirements for using create article

Before executing create article, make sure that:
- The publication for which you are creating the article already exists.
- The replication definition for the article already exists.

Adding articles to a new publication

After you create a publication, you use create article to create articles and assign them to the publication. An article specifies a table replication definition or function replication definition and a parent publication. Optionally, it may also include where clauses according to the needs of the subscribing replicate site.

A publication must contain at least one article before it can be validated and before you can create subscriptions for it. See create publication for more information.

Articles and subscriptions

When you create a subscription for a publication, Replication Server creates an internal subscription for each of its articles.
Including multiple where clauses for an article, separated by the or keyword, allows you to work around the Replication Server restriction that allows only one where clause per subscription. A publication subscription cannot include a where clause—use where clauses in the articles instead.

Adding articles to a publication with a subscription

If you add a new article to an existing publication, or drop an article from the publication, the publication is invalidated. Although replication for existing articles continues unaffected, in order to begin replication for the new articles you must:
- Validate the publication when you finish making changes to the publication, then
- Refresh the publication subscription.
See create subscription and define subscription for more information on the two methods of refreshing publication subscriptions. See also validate publication.

Permissions

create article requires “create object” permission.