Sensoray 2600 - Manual (Page 19)

Sensoray 2600 Programming Guide
15
Transactions
5.5.1 Gateway Error Propagation
When any gateway transaction error has been detected, construction of the transaction’s command packet is terminated and all
subsequent gateway transaction functions will fail and return the last error value. Because of this “error propagation” behavior, it
is usually unnecessary to check for transaction errors after each gateway transaction function is called. Instead, all transaction
errors can be caught when
S26_SchedExecute() returns.
Error propagation is extended to include S26_SchedOpen() , which returns zero if it fails to create a new transaction object.
Instead of checking for errors after calling S26_SchedOpen() , the application is permitted to schedule actions into the “void
transaction” and then execute the transaction as if it had been successfully created. At any point during action scheduling into or
upon execution of a void transaction, all scheduling and execution functions will return
GWERR_XACTALLOC to indicate the
transaction was not successfully created. For obvious reasons, no physical transaction will occur and no actions will be invoked.
5.5.2 Scope of Errors
Each transaction keeps track of its own errors. When a transaction error is detected, it is known only to the transaction in which it
occurs. Transactions are not aware of errors that have occurred in other transactions. Transaction errors are “cleared”
automatically when
S26_SchedExecute() returns, because the associated transaction object is released. The underlying cause of
a transaction error, however, may still be pending after the transaction is finished. For example, an IOM’s reset flag will remain
asserted until explicitly reset by the client, even though the resulting
GWERR_IOMRESET transaction error “disappears” when the
transaction is finished.
5.5.3 Error Handling
In the cases of both comport and gateway transaction errors, the application’s error handler should first determine if any errors
were detected; this can be quickly done by testing the error code for a zero value. If the value is not zero then the indicated error
must be processed by the error handler.
It is permissible to process the error code with a “switch” statement because the error codes are enumerated values. If a switch
statement is employed, however, the least significant byte of the error code must first be masked because it may contain additional
information about the error. Refer to the sample applications for examples of error handling.
Important: For each successful call to S26_SchedOpen() there must be a corresponding call to S26_SchedExecute() , even if
gateway errors are detected before S26_SchedExecute() is called. This ensures that resources allocated by S26_SchedOpen()
will be released, thereby preventing memory leaks and other potential problems.
5.6 Time-outs
Some of the gateway transaction functions and all of the comport transaction functions include a “ msec ” argument that specifies
the maximum number of milliseconds to wait for the MM to respond before declaring a time-out error (i.e., GWERR_MMNORESPOND ).
When calling these functions, the application must specify an appropriate milliseconds value. The choice of the milliseconds value
depends on several factors:
• Network traffic. High network traffic, caused by activities such as video multicasting, can interfere with the timely delivery of
packets to and from the MM. To prevent this, it is best to dedicate a private LAN for the 2600 I/O system.
• Router hops. Routers can lead to unpredictable latencies, especially when the other networks through which 2600 packets
flow have widely varying network traffic. A good policy is to eliminate routers from the 2600 communication path. If a 2600
client requires the services of a router, it is best to install two network interfaces in the client: one for the private 2600 network
and the other for the external network.
• CPU loading. A heavily loaded client-side CPU may introduce communication latency if it becomes compute-bound. The
solution to this problem is to reduce CPU loading or employ a faster CPU.
• Process priorities. Other network-related processes may “trump” the 2600 middleware’s network access requests if process
priorities are not set appropriately. The process that communicates with the 2600 system is usually classified as a “real-time”
process, and as such it should have relatively high priority. Note: high priority does not always guarantee real-time behavior,
especially with non real-time operating systems such as Windows.
• MM response time. Typically, only one transaction is in progress for a particular comport at any given time. As a result,
comport transaction times depend mostly on packet sizes and are therefore relatively predictable. Gateway transactions, on the
other hand, are less predictable. This is because a gateway transaction time depends not only on its command and response