AdsDDSetSubscriptionProperty

Advantage Client Engine

Set the property of an existing subscription in the data dictionary.

Syntax

UNSIGNED32 ENTRYPOINT AdsDDSetSubscriptionProperty( ADSHANDLE hDictionary,

UNSIGNED8 *pucSubscriptionName,

UNSIGNED16 usPropertyID,

VOID *pvProperty,

UNSIGNED16 usPropertyLen );

 

Parameters

hDictionary (I)

A data dictionary connection.

pucSubscriptionName (I)

The name of a subscription in the database.

usPropertyID (I)

Index of the property to set. See Remarks for allowed values.

pvProperty (I)

Pointer to property value to be stored in the data dictionary.

usPropertyLen (I)

Length of the property pointed to by the pvProperty parameter.

Special Return Codes

AE_INVALID_PROPERTY_ID

Either the value supplied in usPropertyID is not a valid article property, or the specified property cannot be retrieved.

AE_INVALID_OBJECT_NAME

The subscription specified by pucSubscriptionName cannot be located in the data dictionary.

Remarks

AdsDDSetSubscriptionProperty sets one property for the specified subscription in the database. The new property overwrites the existing property in the data dictionary. The following are the valid values of usPropertyID and the expected value in pvProperty and usPropertyLen.

Note This function can be called inside a transaction, but will not be part of the transaction. Any changes it makes cannot be rolled back.

usPropertyID

Description

ADS_DD_COMMENT

Changes the subscription description. The pvProperty is expected to be a NULL terminated string. usPropertyLen is the length of the string including the NULL terminator. If pvProperty is NULL or an empty string, the description is removed.

ADS_DD_SUBSCR_PUBLICATION_NAME

Changes the publication that this subscription uses. pvProperty must point to a NULL terminated string that is the name of an existing publication object in the data dictionary.

ADS_DD_SUBSCR_TARGET

Changes the target database for the replication updates. pvProperty cannot be NULL or an empty string for this option. usPropertyLen is the length of the string including the NULL terminator.

ADS_DD_SUBSCR_USERNAME

Changes the user name that Advantage Database Server uses when making a replication connection to the target. usPropertyLen is the length of the string including the NULL terminator. If pvProperty is NULL or an empty string, the user name is removed.

ADS_DD_SUBSCR_PASSWORD

Changes the password that Advantage Database Server uses when making a replication connection to the target. usPropertyLen is the length of the string including the NULL terminator. If pvProperty is NULL or an empty string, the password is removed.

ADS_DD_SUBSCR_FORWARD

Sets the flag that specifies whether or not replication updates are forwarded. pvProperty is expected to contain a 2 byte (UNSIGNED16) value that is 0 (FALSE) or 1 (TRUE).

ADS_DD_SUBSCR_ENABLED

Sets the flag that specifies whether or not this subscription is enabled. pvProperty is expected to contain a 2 byte (UNSIGNED16) value that is 0 (FALSE) or 1 (TRUE).

ADS_DD_SUBSCR_QUEUE_NAME

Changes the replication queue that stores pending replication updates. If the current queue is currently not empty, the error AE_SUBSCRIPTION_QUEUE_NOT_EMPTY will be returned. pvProperty cannot be NULL or an empty string for this option. usPropertyLen is the length of the string including the NULL terminator.

ADS_DD_SUBSCR_OPTIONS

Set the additional options that control the subscription behavior. pvProperty is expected to contain a 4 byte (UNSIGNED32) value that can contain the following values OR’ed together: ADS_DEFAULT, ADS_SUBSCR_QUEUE_IS_STATIC, ADS_SUBSCR_AIS_TARGET, ADS_SUBSCR_IGNORE_FAILED_REP, and ADS_SUBSCR_LOG_FAILED_REP_DATA. See AdsDDCreateSubscription for additional information on the subscription options.

ADS_DD_USER_DEFINED_PROP

Changes the user defined subscription property. If pvProperty is NULL, the user-defined property is removed. The user-defined property is set, read, and interpreted by the application. It is not used by Advantage.

ADS_DD_SUBSCR_PAUSED

Sets the flag that specifies whether or not this subscription is paused. Paused subscriptions place replication updates in the queue, but the updates do not get sent to the target server until the subscription is un-paused. pvProperty is expected to contain a 2 bytes (UNSIGNED16) value that is 0 (FALSE) or 1 (TRUE).

Example

// Turn on forwarding

usVal = TRUE;

ulRet = AdsDDSetSubscriptionProperty( hConn, "mysub",

   ADS_DD_SUBSCR_FORWARD, &usVal, 2 );

 

// change the replication queue name

strcpy( aucBuf, "myrepqueue.adt" );

ulRet = AdsDDSetSubscriptionProperty( hConn, "mysub",

   ADS_DD_SUBSCR_QUEUE_NAME,

   aucBuf, (UNSIGNED16)( strlen(aucBuf) + 1 ));

 

See Also

AdsDDCreateSubscription

AdsDDGetSubscriptionProperty