solidDB Help : solidDB reference : SQL: Statements : MESSAGE : MESSAGE FORWARD
  
MESSAGE FORWARD
Note Applies to only solidDB Advanced Replication configurations.
MESSAGE unique‑message‑name FORWARD
   [TO {'connect‑string' | node‑name}]
   [TIMEOUT {number‑of‑seconds | FOREVER}]
   [COMMITBLOCK block‑size‑in‑rows]
   [{OPTIMISTIC | PESSIMISTIC}]
Access requirements
In replica: Valid master user or SYS_SYNC_ADMIN_ROLE
Usage
Use the MESSAGE FORWARD statement to send a message (that was completed and made persistent with the MESSAGE END statement) to the master database.
The MESSAGE FORWARD statement can be executed only on replica databases.
If a forwarded message fails due to a communication error, you must explicitly use the MESSAGE FORWARD statement again to resend the message.
Note When working with the messages, autocommit mode must be switched off.
Parameters, clauses, keywords, and variables
▪ TO: Specifies the recipient of the message. It is only necessary to use the TO keyword when a new replica is being registered with the master database; that is, when the first message is sent from a replica database to the master database.
– connect‑string: A valid connect string, see Managing network connections. In the context of a MESSAGE FORWARD statement, a connect string must be enclosed in single quotation marks.
– node‑name : A valid alphanumeric sequence. If the node name is a reserved word, enclose the node name in double quotation marks. For example:
-- On master
SET SYNC NODE "master";
--On replica
MESSAGE refresh_severe_bugs2 FORWARD TO "master" TIMEOUT FOREVER;
▪ TIMEOUT: Defines how long the replica database waits for the reply message.
If TIMEOUT is not used, the message is forwarded to the master database and the replica database does not wait for the reply. In this case, the reply can be retrieved by using a separate MESSAGE GET REPLY statement, see MESSAGE GET REPLY.
▪ COMMITBLOCK: Indicates the number of rows that are processed before the data is committed. By default, the MESSAGE FORWARD statement commits all rows as one transaction. If the reply of the sent message contains refreshes of large publications, include the COMMITBLOCK keyword in order to commit the data in more than one transaction and ensure good performance for the operation. It is recommended that there are no on-line users accessing the database when the COMMITBLOCK keyword is used.
▪ OPTIMISTIC | PESSIMISTIC: Include the PESSIMISTIC keyword so that the MESSAGE FORWARD statement uses table-level pessimistic locking when it is initially executed (see Pessimistic and optimistic concurrency controls). If the PESSIMISTIC mode is specified, all other concurrent access to the table is blocked until the synchronization message has completed. If you use OPTIMISTIC mode, the MESSAGE FORWARD statement might fail due to a concurrency conflict.
When a transaction acquires an exclusive lock to a table, the General.TableLockWaitTimeout parameter determines the wait period of the transaction after which the exclusive or shared lock is released, see General section.
Result set
If the MESSAGE FORWARD statement also retrieves the reply, the statement returns a result set.
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 statement 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 database
 
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 connect string is:
tcp localhost 1315
then the following MESSAGE statements 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 can 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
25060
Column column‑name does not exist on publication publication‑name resultset in table table‑name.
Return values from master database
 
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 ;
Go up to
MESSAGE