The VTSDriver API

The VTSDriver module is supplied with VTS. It includes the generic driver interface for VTS and is used in combination with each device-specific communication driver.

Several of the functions in VTSDriver are called directly from I/O tags. For example, AddRead is called by an input or status tag to request that data be sent from the driver. AddRead will call VTSRead in the device-specific communication driver to do the actual work according to the particular device’s requirements.

 

Started                  A flag to let you know that RPC is ready.

RPCStatus              Provides the client/server state.

AddRead                A subroutine called by I/O tags to request a read from the communication driver. Does not force a read to occur immediately.

                             Parameters:  

                             Address                   The address from which to get the data.

                             N                 The number of elements to get

                             Value           Either a pointer to the destination for the data or an object value if VTSDriver will call Value\NewData when data changes.

                             Rate            The data update period, measured in seconds.

NewData               Typically called from within an I/O tag when RefreshData is called and before the data is returned. NewData will only be called when there is new data available – including invalids.

                             Parameters:

                             Address                   From the original AddRead

                             TimeStamp   In seconds, UTC

                             Data            The new data – either a single value or an array of values.

                             Attribute      Data attributes. Single value or array, matching Data.

DelRead                 A module that must be called when the address changes.

Read                     A module that performs a one-shot read, the data from which will be sent only to the calling server.

Write                     The main subroutine used to request a write to the communication driver.

AddWrite               Deprecated. Was once used to request a write to the communication driver.

PollAll                    Forces all pending reads to occur immediately. This subroutine, which includes feedback, is especially useful with radio links where reads must occur when the link is established.

CoalesceRPC          Used to control RPC bandwidth.  While in the default state (on), whenever an I/O request is processed, only the message most recently added to the queue will be sent. In systems with a large amount of continuous throughput, doing otherwise might result in the queue overflowing if requests are added to the queue faster than they can be processed. In practice, it is very rare for messages to be lost.

                             If set to (off), new requests will be coalesced with old so that no messages are lost. This technique works best in situations where bursts of requests are interspersed with lulls in communication and there is a need to ensure that no information is lost.