Sensoray 2410 API - Manual (Page 9)

Sensoray 24xx Programming Guide
5
Sessions and Transactions
Chapter 4: Sessions and Transactions
4.1 Overview
Most API functions involve transactions between the client and an I/O module over a telnet session. When the application program
invokes a transaction by calling an API function, the API internally executes a four-step process:
• Translate the API function and its arguments to an equivalent shell command.
• Send the command to the I/O module via telnet.
• Receive the reply from the I/O module via telnet.
• Translate the reply to the form expected by the application program.
Transaction functions are designed to insulate the application programmer from the cumbersome details of network programming
and packet parsing.
4.1.1 Blocking Behavior
All transaction functions are blocking functions, which means that calls to those functions will not return until the transaction (i.e.,
the above four-step process) has completed.
4.1.2 Thread Safety
All transaction functions are thread safe, so it is permissible for multiple API calls to be in progress at the same time on a single
session. For example, an application may be partitioned into multiple threads (e.g., analog I/O thread, digital I/O thread, serial
communication thread) such that each thread asynchronously invokes its own private transactions over a common session. In most
cases, a thread will be blocked and its transaction will be held off if another transaction is already in progress on the same session.
4.2 Concurrent Transactions
Each I/O module supports up to three simultaneous telnet sessions and, as a result, up to three overlapped transactions may be in
progress at the same time on an I/O module.
An Ethernet client may run multiple threads and/or processes in which each thread or process concurrently executes simultaneous
transactions with an I/O module, with each transaction running on a unique session. Simultaneous transactions may also involve
more than one Ethernet client. For example, it is permissible for two or three different Ethernet clients to simultaneously execute
transactions on one module. Each of the three possible simultaneous transactions may be invoked by any arbitrary Ethernet client.
For best performance, multi-threaded applications should communicate over dedicated sessions whenever possible (i.e., one thread
per session). This is because transactions on different sessions can be overlapped, whereas transactions that share a common
session are executed serially.
4.3 Errors
Various errors can occur when interacting with I/O modules over a network. When an error is detected during a session transaction,
it is only known to the session in which it occurs. Sessions are not aware of errors in other sessions.
When an error is detected, the currently executing API function is terminated and, if the error is classified as “fatal,” the error is
permanently logged to the session. Subsequent transaction attempts on the same session will fail if a fatal error has been logged.
Each session’s error log is retained across multiple transaction attempts, effectively propagating a fatal error across any number of
API calls, client threads, and client network interfaces.
4.3.1 Error Passing Mechanism
Most API functions have an argument named err , which is a pointer to an error code that is allocated by the calling thread. Each
thread typically sets its error code to ERR_NONE (zero) before calling an API function to indicate no errors are pending. Every
subsequent call to an API function may change the value of the error code. If the error code is not ERR_NONE when an API function
is called, the function will be aborted and the error code will not be modified. Because of this “error propagation” behavior, it may
not be necessary to check for errors at the end of every transaction. Instead, the application may be designed to catch errors at the