FairCom ISAM for C

ctNotify

Send notification messages to a queue.

Short Name

ctNotify()

Type

ISAM function.

Declaration

NINT ctNotify(NINT opcode, NINT objhandle, NINT qhandle, NINT contents,

NINT controls)

Description

Using the facilities of c-tree system queues, client applications can direct FairCom Server to monitor the use of a resource such as a data file and place notification messages on a queue. To use the notification process the user must open a queue using ctSysQueueOpen(), use ctNotify() to write the notification, ctSysQueueRead() to read the notification messages and ctSysQueueClose() to close the notification queue.

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

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful close of the queue.
10	SPAC_ERR	INTREE() parameters require too much space.
48	FMOD_ERR	Operation incompatible with type of file.
90	NQUE_ERR	Could not create queue.
446	BMOD_ERR	Bad mode: parameter out of range.
458	SWRT_ERR	Write permission not granted.
514	CQUE_ERR	Queue has already been closed.
754	QOWN_ERR	Only queue creator can perform operation.
755	SQUE_ERR	A system queue is required.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

NINT eRet;

NINT qhandle = ctSysQueueOpen("myqueue", 0);

if (qhandle < 0)

printf("ctSysQueueOpen failed with code %d\n", -qhandle);

else

{

eRet = ctNotify(ctNT_ADDREC, datno, qhandle, 0, 0);

if (eRet)

printf("ctNotify failed with code %d\n", eRet);

}

Limitations

Client/Server mode only.