SQL Guide : solidDB® SQL statements : MESSAGE : MESSAGE FORWARD
  
MESSAGE FORWARD
MESSAGE unique_message_name FORWARD
[TO {'connect_string' | node_name | "node_name"} ]
[TIMEOUT {number_of_seconds | FOREVER} ]
[COMMITBLOCK block_size_in_rows]
[{OPTIMISTIC | PESSIMISTIC}]
Usage
After a message has been completed and made persistent with the MESSAGE END statement, it can be sent to the master database using the MESSAGE FORWARD statement. The MESSAGE FORWARD statement is applicable only in advanced replication configurations. It can be issued only on the replica databases.
It is only necessary to specify the recipient of the message with keyword TO when a new replica is being registered with the master database; that is, when the first message from a replica to the master server is sent.
The connect_string must be a valid connect string, such as:
tcp [host_computer_name] server_port_number
In the context of a MESSAGE FORWARD command, a connect string must be delimited in single quotation marks.
The node_name (without quotation marks) is a valid alphanumeric sequence that is not a reserved word. The "node_name" (in double quotation marks) is used if the node name is a reserved word; in this case, the double quotation marks ensure that the node name is treated as a delimited identifier. For example, since the word “master” is a reserved word, the word is placed in double quotation marks when it is used as a node name:
-- On master
SET SYNC NODE "master";
--On replica
MESSAGE refresh_severe_bugs2 FORWARD TO "master" TIMEOUT FOREVER;
Each sent message has a reply message. The TIMEOUT property defines how long the replica server will wait for the reply message.
If a TIMEOUT is not defined, the message is forwarded to the master and the replica does not fetch the reply. In this case the reply can be retrieved with a separate MESSAGE GET REPLY call.
If the reply of the sent message contains REFRESHes of large publications, the size of the REFRESH commit block, that is, the number of rows that are committed in one transaction, can be defined using the COMMITBLOCK property. This has a positive impact on the performance of the replica database. It is recommended that there are no on-line users accessing the database when the COMMITBLOCK property is being used.
As part of the MESSAGE FORWARD operation, you can specify table-level pessimistic locking when the reply message is initially executed in the replica. If the PESSIMISTIC mode is specified, all other concurrent access to the table affected is blocked until the synchronization message has completed. If the optimistic mode is used, the MESSAGE FORWARD operation can fail due to a concurrency conflict.
When a transaction acquires an exclusive lock to a table, the General.TableLockWaitTimeout parameter setting determines the wait period of the transaction after which the exclusive or shared lock is released.
If a forwarded message fails in delivery due to a communication error, you must explicitly use the MESSAGE FORWARD to resend the message. Once re-sent, MESSAGE FORWARD re-executes the message.
Note When working with the messages, the autocommit mode must be switched off.
Result set
If the MESSAGE FORWARD also retrieves the reply, the statement returns a result set. The result set returned is the same as the one returned with the statements MESSAGE GET REPLY and MESSAGE.
The columns of the result set are as follows:
Column name
Description
Partno
Message part number
Type
The type of result set row. Possible types are:
0: Message part start
1: This type is not in use
2: The message was a propagation message and the status of that operation is stored in the return message
3: Task
4: Subscription task
5: Type of refresh (FULL or INCREMENTAL)
6: MESSAGE DELETE status
Masterid
Master ID
Msgid
Message ID
Errcode
Message error code. Zero if successful.
Errstr
Message error string. NULL is successful.
Insertcount
Number of inserted rows to replica.
Type=3: Total number of insert
Type=4: Row inserts restored from replica history to replica base table
Type=5: Insert operations received from master
Deletecount
Type = 3: Total number of deletes
Type = 4: Row deletes restored from replica base table
Type = 5: Delete operations received from master
Bytecount
Size of message in bytes. Indicated in result received from command MESSAGE END. Otherwise 0.
Info
Information of the current task.
 
Type = 0: then Message name
 
Type = 3: Publication name
 
Type = 4: Table name
 
Type = 5: FULL/INCREMENTAL
Return values from replica
Error code
Description
13XXX
Table level error
21XXX
Communication error
10006
Concurrency conflict (simultaneous other operation)
13047
No privilege for operation
13056
Insert not allowed for pseudo column
25005
Message message_name is already active
25013
Message name message_name not found
25018
Illegal message state
In the replica, the message can only be executed using the MESSAGE FORWARD statement if the message is ended and the ending transaction is committed.
25024
Master not defined
This message is produced if double quotation marks, rather than single quotation marks, are used around the connect_string in a MESSAGE FORWARD statement.
For example, if the master node is given the node name “master” (which is a reserved word and therefore should be delimited by double quotation marks), and if that node’s connect string is:
tcp localhost 1315
then the MESSAGE statements shown below are correct:
--On the replica
...
--double quotation marks
MESSAGE msg1 BEGIN TO "master";
...
--single quotation marks
MESSAGE msg2 FORWARD TO 'tcp localhost 1315';
Note that the MESSAGE BEGIN statement defines (within the replica server) what the node name of the master is. The MESSAGE FORWARD statement may contain the connect string to the server.
25026
Not a valid master user
25031
Transaction is active, operation failed
25035
Message message_name is in use.
A user is currently creating or forwarding this message.
25040
User id user_id is not found.
While executing a message reply an attempt to map a master user to a local replica id failed.
25041
Subscription to publication publication_name not found
25048
Publication publication_name request info not found
25052
Failed to set node name to node_name.
25054
Table table_name is not set for synchronization history
25055
Connect information is allowed only when not registered
The connect info in MESSAGE message_name FORWARD TO connect_info options is allowed only if the replica has not yet been registered to the master database.
25056
Autocommit not allowed
25057
The replica database has already been registered to a master database
25057
The replica database has already been registered to a master database
25060
Column column_name does not exist on publication publication_name resultset in table table_name
Return values from master
Error code
Description
13XXX
Table level error
13124
User id num not found
This message is generated, for example, if the user has been dropped.
25016
Message not found, replica ID replica_id, message ID message_id
25056
Autocommit not allowed
Examples
Forward message, wait for the reply for 60 seconds:
MESSAGE MyMsg001 FORWARD TIMEOUT 60 ;
Forward message to a master server that runs on the “mastermachine.acme.com” machine. Do not wait for the reply message.
MESSAGE MyRegistrationMsg FORWARD TO 'tcp mastermachine.acme.com 1313';
Forward message, wait for the reply for 5 minutes (300 seconds) and commit the data of the refreshed publications to replica database in transactions of maximum of 1000 rows.
MESSAGE MyMsg001 FORWARD TIMEOUT 300 COMMITBLOCK 1000 ;
See also
MESSAGE