Sensoray 2410 API - Manual (Page 10)

Sensoray 24xx Programming Guide
6
Sessions and Transactions
end of a sequence of transactions, but only if it doesn’t need to know exactly where in the sequence the error occurred. This is done
by setting the error code to
ERR_NONE once before calling a sequence of API functions and then checking the error code after the
entire sequence has executed to determine if any errors occurred during the sequence.
This error propagation paradigm includes s24xx_SessionOpen() , which will set an appropriate error code and return NULL if it
fails to create a new session. Instead of checking for errors after calling s24xx_SessionOpen() , the application may continue
onward and attempt transactions as if the session had been successfully opened. All such attempts will fail and leave the error code
unchanged.
4.3.2 Error Handling
Most API functions return a boolean that indicates whether the operation completed successfully. False (zero) is returned if the
operation failed, otherwise True (non-zero) is returned. These functions return False if an error occurs during function execution or
if a previously detected error is pending when the function is called.
Programming languages typically define False as zero, but True has no universally accepted definition. Consequently, in the case
of API functions that return a boolean value, that value should generally be compared to False when deciding if an error occurred.
For example, in VB.NET this is the recommended practice:
If s24xx_SomeFunction() = False Then
' handle error ...
Else
' do this if no error ...
Endif
In addition, most functions include in their argument lists a pointer to the caller’s error code. When a function returns False (thus
indicating an error has occurred), the error type can be determined by inspecting the error code. The application can then take
corrective action based on the type of error that was detected.
It is not possible to restore communication on a session that has logged a fatal error; the session must be closed and, if
communication is to be resumed, a new session must be opened.
4.3.3 Error Codes
Symbolic Name Description
ERR_NONE No errors.
Initialization Errors
ERR_MALLOC Internal memory allocation failed.
ERR_SOCKETCREATE Failed to create socket.
ERR_SESSIONCONNECT Failed to open a TCP connection t the I/O module’s telnet server.
ERR_TOOMANYSESSIONS The I/O module’s telnet server is already running the maximum number of sessions.
Most I/O modules are limited to three concurrent sessions.
ERR_OPENSHELL Failed remote shell login.
ERR_THREADCREATE Failed to create internal thread.
ERR_CRITSECTCREATE Failed to create internal critical section.
ERR_CREATEMUTEX Failed to create internal mutex.
Fatal (unrecoverable) Run-time Errors
ERR_INVALIDSESSION Session handle is zero. This can happen if your application unsuccessfully attempted to
open a session and then continues on as if the session had opened.
ERR_SOCKET Socket error.
ERR_CONNCLOSED The session’s TCP connection closed unexpectedly. This can happen if an I/O module’s
watchdog times out due to network inactivity.
ERR_NETWORKWRITE The socket failed to transmit to the I/O module.