Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

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);

See also:

ctNotify, ctSysQueueOpen, ctSysQueueClose, ctSysQueueRead

TOCIndex