2.6 EVENT SYSTEM

2.6.1 Purpose

The Event system of CCS provides the facility to register for notification of event to an attribute of a database point. This enables a process to be informed when a database value is written to the registered attribute.

Event notification is done via a specific message type sent to the process that registered the event.

A specialized message parsing function has to be used to retrieve the different parts of the notification message.

2.6.2 Basic Concepts

The CCS Event system is based upon the database event notification of RTAP, fully emulated under CCS_LITE and LCC.

An event can be attached to a database attribute of type: SCALAR, VECTOR or TABLE. On attributes of type SCALAR the occurrence of event's can be filtered in order to trigger only on specific values e.g. rising (evtGREATER) or falling (evtLESS) values. Filtering does not apply to attributes of type: VECTOR and TABLE.

On WS whre the concept of database attribute quality exists, a new type of event has been introduced with the JAN2006 release: it is now also possible to request event notification on a change of quality.

Upon successful event attachment an Id is returned that is used as a reference to event related calls.

When a new database value is written a CCS message of type msgTYPE_EVENT is sent to the process that attached an event to that attribute, whenever the filter is matched.

The message received upon occurrence of a database event contains the following information:

· Attribute name.

· Trigger condition.

· Process writing the value.

· Attribute information depending on the type of the attribute.

· An optional part user defined.

A function is provided to parse and strip of the necessary event information.

The attribute information on SCALAR attribute includes the value as well as the quality before and after the write. On attributes of type VECTOR and TABLE the range of elements written is returned, so that only that specific part of the vector or the table can be read.

Notification of events can be disabled and re-enabled, which can be used for temporary stop of event notification. For a permanent stop of event notification the event must be detached. After an event attach the event is automatically enabled.

Attachment of attributes in a remote environment database is possible. The following configurations are supported:

Attachment from FULL CCS to events occurring in remote environments of type FULL CCS & LCU

Attachment from CCS_LITE to events occuring in remote environments of type FULL CCS, CCS_LITE, LCU

The same process can attach the same attribute several times (up to 64 times) but this implies that several event notification messages will be received.

An extended event attach function, available only on Workstations, allows the user to specify some additional information to be appended to the event notification message and to indicate a process different from the caller as destination for the notification message.

2.6.3 Examples

/*

* Local Headers

*/

#include "vltPort.h"

/*

* System Headers

*/

#include <stdio.h>

#include <evt.h>

void main (int argc, char ** argv)

{

evtEVENT_ID eventId, event;

evtDATA eventInfo;

msgHEADER *message;

msgRECEIVEFILTER msgFilter;

msgPROCESSID triggerProc;

dbSYMADDRESS dbAttribute;

dbATTRTYPE attrType;

vltUINT8 trigger;

vltUINT8 oldQuality,newQuality;

vltINT16 oldValue,newValue;

vltUINT8 startField,endField;

vltUINT16 startElem, endElem;

ccsCOMPL_STAT stat;

dbTYPE dataType;

ccsERROR error;

if (ccsInit(argv[0],0,NULL,NULL,&error) != SUCCESS)

{

/* Error handling */

}

strcpy(dbAttribute,":MYBRANCH:MYPOINT.myattribute");

if ( evtAttach(dbAttribute,evtANY_WRITE,&eventId,&error) == FAILURE)

{

/* Error handling */

}

/*

* After this point a message arrives when there is written

* to ":MYBRANCH:MYPOINT.myattribute".

*/

if (msgSetFilter(NULL, NULL, msgANY_MESSAGE, 0,

"", &msgFilter, &error) == FAILURE)

{

/* Error handling */

}

if (msgRecvMsg(&msgFilter,msgNO_TIMEOUT, &message, &error) != SUCCESS)

{

/* Error handling */

}

if (message->msgType == msgTYPE_EVENT)

{

if (evtParseMsg( message, &event, &trigger, &triggerProc,

dbAttribute, &attrType, &eventInfo,NULL,

&error) == FAILURE)

{

/* Error handling */

}

switch (attrType)

{

case dbSCALAR: /* Get information on a scalar attribute */

dataType = eventInfo.scalar.dataType;

oldQuality = eventInfo.scalar.oldQuality;

newQuality = eventInfo.scalar.newQuality;

dbMemCpy((char *)&oldValue,eventInfo.scalar.oldValue,dbINT16);

dbMemCpy((char *)&newValue,eventInfo.scalar.newValue,dbINT16);

break;

case dbVECTOR: /* Get information on a vector attribute */

startElem = eventInfo.vector.startElem;

endElem = eventInfo.vector.endElem;

break;

case dbTABLE: /* Get information on a table attribute */

startElem = eventInfo.table.startElem;

endElem = eventInfo.table.endElem;

startField = eventInfo.table.startField;

endField = eventInfo.table.endField;

break;

}

}

stat = ccsExit(&error);

}

2.6.4 Reference

PROCEDURES

evtAttach(). Attaches event notification to database attribute.

evtAttachExt(). Extended event attach allows additional features.

evtDetach(). Detaches an attached event.

evtIsEqual() Compares two event Id's..

evtParseMsg(). Parses the event message and returns event information.

evtSingleDisable(). Disables the event notification.

evtSingleEnable(). Re-enables the event notification.

INCLUDE FILES

evt.h Contains constants, types and function prototypes of the event system

Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com