Replication Server Function Strings
===================================

The goal of examples provided is to take advantage of Replication Server
availability to customize database modifications, such as insert, update,
delete, and stored procedure execution, to convert them into calls to the 
messaging system.

The information regarding the data modification operation is send as a 
select statement for XML.

Requirements
------------
	- Good knowledge of Replication Server setup and configuration.
	- Some specific information about the messaging service provider

Setup
-----

   1.- Create a new Replication Server database connection that will be used
       to send messages.
       For instance, new connection name is MSG_DS.MSG_DB This name will be
       used for examples, you will need to change commands below to use
       your own connection name.

   2.- Create a new function string class.

       Connect to the Replication Server that will be the primary for the
       new class and execute:

		create function string class
		msg_function_class
		set parent to rs_default_function_class
		go

   3.- Check if new function string class has been created.

       Connect to the Replication Server that will be the primary for the
       new class and execute:

		admin show_function_classes
		go


    4.- Alter the database connection to the replicated site to make use
        of the new function string class:

		alter connection to MSG_DS.MSG_DB
		set function string class msg_function_class

    5.- Some of the function strings generated on this examples contain
	more than one command in the output template. The database connection
	to the replicated site has to be configured with 'batch' set to 'on.
	Default value is 'on', but if you are re-using an existing connection
	double check it has the correct value.

	If this is not the case run following command:

		alter connection to MSG_DS.MSG_DB set batch to 'on'

    6.- By default, Replication Server may groups several transactions into
	a single one. However, we want to allow clients reading messages 
	identify which command belongs to a specific transaction. Setting
	dsi_xact_group_size to '-1' will force Replication Server to do not
	group transactions.

	Configure the connection that will be used for messaging to do not
	perform grouping:

		alter connection to  MSG_DS.MSG_DB set 
		dsi_xact_group_size to '-1'
		go

    7.- Suspend and resume the connection to be sure changes take effect

		suspend connection to MSG_DS.MSG_DB
		go
		resume connection to MSG_DS.MSG_DB
		go

    8.- Grant messaging_role to the maintenance user Replication Server is
	using to connect to MSG_DS.MSG_DB.

	For example:

		sp_role "grant", messaging_role, rterep_maint
		go

    9.- Create replication definitions for those objects in the primary database
	you are interested on sending messages.

	Check http://www.codexchange.sybase.com/ for replication definition
	generation

   10.- Execute the script messaging_fs_generation.sql. The 
	messaging_fs_generation.sql script is located in the same directory as
	this README.

	This script will create a stored procedure in the RSSD that will be
	used in later steps to generate function strings.

        For example:
		isql -Usa -Psa_pwd -SASE_RSSD -DRSSD -i sample_msg_fs.sql

	Where ASE_RSSD is the dataserver holding the RSSD that controls the
	affected Replication Server.


   11.- Identify the servicer provider that will be used to send messages.

	For example:

		Service Provider: tibco_jms://silverton:7222

   12.- Identify the destination (queue or topic) to be used when sending
	messages.

	For example:
		
		Destination: "queue=queue.sample: 

   13.- Identify the service provider user name to be used when sending
        messages.

	For example:

		User = messaging_user

   14.- Execute the stored procedure genfs_msg to generate function strings
	with class scope.

        Syntax:

		messaging_fs_generation < "class"| "repdef">, 
					[Primary Dataserver Name], 
					[Primary Database Name], 
					[replication definition name],  
					<provider>, 
					<queue or topic>, 
					<provider_login>
					[,password]

	
	Output from this stored procedure needs to be collected into a file,
	that will be used later.

	For example, execute:

	isql -Usa -Psa_pwd -SASE_RSSD -DRSSD << EOF > msg_fs_class.rcl
	messaging_fs_generation "class", MSG_DS, MSG_DB, null, 
				"tibco_jms://silverton:7222", 
				"queue=queue.sample", messaging_user
	go
	EOF

   15.- Execute the stored procedure generate_fstrings_messaging to generate 
	function strings with replication definition scope.

	
	Output from this stored procedure needs to be collected into a file,
	that will be used later.

	For example, execute:


	isql -Usa -Psa_pwd -SASE_RSSD -DRSSD << EOF > msg_fs_repdef.rcl
 	messaging_fs_generation "repdef",  MSG_DS, MSG_DB, null, 
				"tibco_jms://silverton:7222", 
				"queue=queue.sample", messaging_user
	go
	EOF

	Execution above will generate function strings for all replication
	definitions with primary site MSG_DS.MSG_DB	


   16.- Execute generated file msg_fs_class.rcl against the affected Replication
	Server

	For example, execute:

	isql -Usa -Psa_pwd -SRS_NAME -i msg_fs_class.rcl

   17.- Execute generated file msg_fs_repdef.rcl against the affected 
	Replication Server.

	For example, execute:
	isql -Usa -Psa_pwd -SRS_NAME -i msg_fs_repdef.rcl


   18.- Now you can create subscriptions. 


After creating the subscriptions, replication of ASE DML events to the 
messaging bus will be configured. DML done to the primary tables  as well as
stored procedure executions will be posted as messages to the message bus.

Notes
-----

    1.-	Stored procedure messaging_fs_generation internally uses a variable
	named @msg, defined as varchar(255). Starting with ASE 125x char/
	varchar variables can be defined with a maximun length of 16384. Hoever,
	because this stored procedure has to be created in the RSSD, and the
	server holding it could be a lower version than 125x, the choise
	of 255 was preferred.

    2.-	CR 345155. Function string rs_raw_object_serialization cannot be 
	customized.
	The stored procedure messaging_fs_generation does not generate code
	for this function string.

    3.- Replication Server does not make use of rs_rollback function string.
	In a Warm Standby configuration and using large transactions configu
	ration, Replication Server may try to apply a rollbacked transaction.
	In such cases, Replication Server does not execute a rollback command,
	instead it will terminate the connection to the replicate site.

    4.- Transactional mode for ASE realtime services is SIMPLE. If a different
	behaviour is needed, function strings will need to be modified.

	This is accomplished via a set option:

		set transactional messaging FULL
		set transactional messaging SIMPLE
		set transactional messaging NONE

	We recommend to include this set option in function string rs_usedb.
        Connect to the Replication Server that is the primary site for the
        new class and execute:

	create function string  rs_usedb for msg_function_class
	with overwrite output language
	'
		use ?rs_destination_db!sys_raw?;
		set transactional messaging FULL;
	'

    5.- The stored procedure messaging_fs_generation does not provide and
	option to include the schema describing the message body.


Limitations
-----------

    1.- Replication Server does not provide special functions strings for
	Data Modification Language operations. Thus in a Warm Standby 
	configuration replicating DML, we cannot send messages to notify 
	schema creation or modification.

    2.- Due to Replication Server problem, CR 346246, rs_writetext function
	string cannot be customize in order to send columns with text/image 
	data to the messaging system.
