FairCom ISAM for C

Enabling Notification for Actions on a File

This section discusses the steps required to enable notification for actions on a file.

Open the Files

To enable notification for actions on a c-tree data file, start by opening the data file using a
c-tree file open API function. For example:

COUNT datno;

datno = OpenFileWithResources(-1, "customer.dat", ctSHARED);

Open a Server-Side Queue (system queue)

After opening the data file, open a server-side (system) queue on which notification messages will be placed.

NINT qhandle;

qhandle = ctSysQueueOpen("myNotificationQueue", 0);

Establish Notification

After creating the server-side (system) queue, establish notification for actions on the file using the ctNotify() c-tree API function. The ctNotify() function is used to cause the server to send messages to a system queue when the specified action is taken on the specified c-tree data and index files. The syntax for the ctNotify() function is:

ctCONV NINT ctDECL ctNotify(NINT opcode, NINT objhandle, NINT qhandle,

NINT contents, NINT controls);

Parameters

The ctNotify opcode parameter specifies which actions on the resource should be notified. The following values are supported:

Values	Explanation	Level
ctNT_ADDREC	Notify that a new record was added to the data file	ISAM
ctNT_DELREC	Notify that a record was deleted	ISAM
ctNT_RWTREC	Notify that a record was modified	ISAM
ctNT_CLSOBJ	Notify that an object was closed
ctNT_ISMUPD	Notify on any change (add, delete or rewrite) to data file. This is identical to ctNT_ADDREC \| ctNT_DELREC \| ctNT_RWTREC	ISAM
ctNT_TOUCH	Notify that the file was updated, only once per transaction. This opcode cannot be used in combination with others and the contents parameter must be 0. No details of the update are conveyed, only a “ping” that the file has been touched.	ISAM and low-level
ctNT_PARTIAL	Notify that a notification request was started in the middle of a transaction and not all the updates generated a notification. One of the first four opcodes in this table must also be specified when using this option.	ISAM
ctNT_ISMUPP	defined as: #define ctNT_ISMUPD (ctNT_ADDREC \| ctNT_DELREC \| ctNT_RWTREC)

The ctNotify objhandle parameter is the file number (datno) of an ISAM data file and qhandle is a server-side (system) queue handle returned by a call to ctSysQueueOpen().

The contents parameter determines what optional details are returned in the variable-length region of the notification message and may be set to the following values or any combination (by OR-ing) of them:

Values	Explanation
ctNT_CON_UNQKEY	Unique key
ctNT_CON_NODNAM	Node name of actor
ctNT_CON_RECBUF	Record buffer on add or update (not on delete)

To receive different notification contents for different actions, multiple calls to ctNotify() are required. For example, to get unique key values on a record delete notification, and full record images on either an add or rewrite notification, two ctNotify() calls are required: one call with a contents field of ctNT_CON_RECBUF to set up the add and rewrite notification, and one call with a contents field of ctNT_CON_UNQKEY for the delete.

The controls parameter is reserved for future use and must be set to zero.

ctNotify returns NO_ERROR (0) on success.

For example, to monitor ISAM updates to a data file, a call of the form below will cause each ISAM update to the data file specified by datno to generate an entry in the queue specified by qhandle.

ctNotify(ctNT_ISMUPD,datno,qhandle,0,0);