Event Types

9-5

Event Types

OPC Toolbox software supports several different types of events. Each event type has an associated toolbox object property that you can use to specify the function that executes when the event occurs.

The following table lists the supported event types, the name of the object property associated with the event, and a brief description of the event, including the object class associated with the event. For detailed information about these callback properties, see the reference information for the property.

The toolbox generates a specific set of information for each event and stores it in an event structure. To learn more about the contents of these event structures and how to retrieve this information, see “Retrieve Event Information” on page 9-9.

Events and Callback Function Properties

Event Callback Property Description Cancel

Async CancelAsyncFcn The toolbox generates a cancel async event when an asynchronous operation is cancelled. You cancel an asynchronous operation using the cancelasync function.

When a cancel async event occurs, the toolbox executes the function specified by the CancelAsyncFcn

property. By default, the toolbox executes the default callback function for this event, opccallback, which displays information about the cancel async event at the MATLAB command line.

Cancel async events occur at the dagroup object level.

DataChange DataChangeFcn The toolbox generates a data change event when the server notifies the toolbox that data for a group has changed. The server will notify the toolbox of data changes only if the group's Active property is set to 'on' and the Subscription property is set to 'on'.

For more information on controlling data change events, see “Data Change Events and Subscription” on page 7-11.

9

Event Callback Property Description

When a data change event occurs, the toolbox executes the function specified by the DataChangeFcn

property.

Data change events occur at the dagroup object level.

Error ErrorFcn The toolbox generates an error event when a run-time error occurs, such as a data type conversion error or time-out. Run-time errors do not include configuration errors such as setting an invalid property value.

When an error event occurs, the toolbox executes the function specified by the ErrorFcn property.

By default, the toolbox executes the default callback function for this event, opccallback, which displays the error message at the MATLAB command line.

Error events occur at the opcda client object level.

Read Async ReadAsyncFcn The toolbox generates a read async event when an asynchronous read operation completes. You execute an asynchronous read operation using the readasync function.

When a read async event occurs, the toolbox executes the function specified by the ReadAsyncFcn property.

By default, the toolbox executes the default callback function for this event, opccallback, which displays information about the read async event at the

MATLAB command line.

Read async events occur at the dagroup object level.

Records

Acquired RecordsAcquiredFcn The toolbox generates a records acquired event every time an integer multiple of a specified number of records have been acquired. You use the RecordsAcquiredFcnCount property to specify this number.

Event Types

9-7 Event Callback Property Description

When a records acquired event occurs, the toolbox executes the function specified by the RecordsAcquiredFcn property.

Records acquired events occur at the dagroup object level.

Shutdown ShutDownFcn The toolbox generates a shutdown event when the OPC server notifies the client that the server is about to shut down.

When a shutdown event occurs, the toolbox executes the function specified by the ShutDownFcn property, and the client object is then disconnected from the server. By default, the toolbox executes the default callback function for this event, opccallback, which displays information about the shutdown event at the MATLAB command line.

Shutdown events occur at the opcda client object level.

Start StartFcn The toolbox generates a start event when an object is started. You use the start function to start an object.

Note: If an error occurs in the start callback function, the object does not start.

When a start event occurs, the toolbox executes the function specified by the StartFcn property.

Start events occur at the dagroup object level.

Stop StopFcn The toolbox generates a stop event when the object stops running. An object stops running when the stop function is called, or when the specified number of records is acquired.

9

Event Callback Property Description

When a stop event occurs, the toolbox executes the function specified by the StopFcn property.

Stop events occur at the dagroup object level.

Timer TimerFcn The toolbox generates a timer event when an integer multiple of a specified amount of time expires. You use the TimerPeriod property to specify the amount of time. Time is measured relative to when the opcda client object is connected.

Note: Some timer events might not execute if your system is significantly slowed or if the TimerPeriod is set too small.

When a timer event occurs, the toolbox executes the function specified by the TimerFcn property.

Timer events occur at the opcda client object level.

Write Async WriteAsyncFcn The toolbox generates a write async event when an asynchronous write operation completes. You execute an asynchronous write operation using the writeasync function.

When a write async event occurs, the toolbox executes the function specified by the WriteAsyncFcn

property. By default, the toolbox executes the default callback function for this event, opccallback, which displays information about the write async event at the MATLAB command line.

Write async events occur at the dagroup object level.