c-tree Server Queues and Notification

c-tree Server System Queues

With c-tree Server-based queues, client programs, connected to the same server, can pass information among each other, emulating a powerful inter-process communications mechanism that is portable, scalable and distributed.

c-tree Server-based queues, also referred to as system queues, extend the concepts of c-tree inter-thread queue routines by providing two additional features:

• System queues operate across the client/server boundary.
• System queues can be named so that different clients connected to the same c-tree Server may share the same queue.
• Server-based queues provide the foundation on which the c-tree Server's file notification feature is built.

c-tree Server Notifications

Notification is a novel evolution of our enhanced system queue support. Using the facilities of c-tree system queues, client applications can direct the c-tree Server to monitor a data file and place notification messages on a queue when changes are made to the file.

On exciting application of notification has been a c-tree Server replication model for non-transaction processed files. Passing notification messages as records are added, deleted and updated allow a central master c-tree Server to notify geographically remote servers of changes and update accordingly.

Each notification message includes the following details:

• The type of operation (add, delete, or update)
• For a transaction-controlled file, the transaction number in which the change occurred
• The record offset of the modified record.

The following optional information can also be included in notification messages:

• The unique key value involved in the operation. (An update may return both old and new key values.)
• The record image involved in the operation. (An update may return both old and new record images.)

The node name of the client that performed the operation.

Customer Notification Callbacks with the c-tree Server SDK

Instead of passing the notification information to a queue, use the c-tree Server SDK to make calls to ctCallback to associate a callback function to a notification. This callback is a user function assigned to perform a specific custom task to the application when notified. An excellent use of this could be to build an audit trail for a particular action taken with the c-tree Server. Ledger updates and reporting events are other possible candidates.

ctCallback is used in the same manner as ctNotify except that the third parameter is a pointer to a callback function instead of a queue handle:

NINT ctCallback(NINT opcode, NINT objhandle, 
	ctCallbackPtr cbptr, NINT contents, NINT controls);

A notification setup with ctCallback causes the function pointed to by cbptr to be called (instead of a message written to a queue). This capability is only available with the Server SDK, and ctCallback can only be called from code compiled into the server itself (using the server SDK).

The prototype for the callback function pointer is:

typedef NINT (*ctCallbackPtr)(pVOID msg, NINT msglen, 
	pVOID aux, NINT auxlen);

The callback function returns NO_ERROR on success and a non-zero value on failure. Parameter msg and the optional parameter aux are input parameters. If both msg and aux are passed in, then they should be conceptually pasted together to form one long message.

It is important to note that as currently coded, the target file's header semaphore is held while the callback function is executed. Therefore the callback function cannot introduce pauses or delays or attempt to lock the header of the target file.

How do I Put c-tree Queues and Notification Into My Application?

Grab all the details in Chapters 9 and 10 of the V8.14 Update Guide found on our support documentation web site.