Table of Contents
This is user guide for Enduro/X TCP Gateway driver. The idea for this ATMI server process is that user can easy create networked applications by using Enduro/X standard package. The user does not have to deal with sockets library. The user program can call in different modes "TCPGATESV" service which in turn will send the framed packets to configured port:ip address. The gateway server supports different protocol modes. List of them:
The next chapters will describe all the possible operational modes.
Driver opens number of connections. When doing outgoing message delivery the user can specify channel id (by connection id) compiled or not compiled. If channel not specified, then random or round robin channel will be used.
For round-robin mode available connection sharing channel can be used. Any open connection will submit it’s ID in channel it’s handler. In case of async outgoing the connection thread will put it self back in channel when message is sent to network. In case of sync mode, the thread can put it self in channel list once it is made free. The marking connection as "idle" could be done by some kind of common function.
TCPGATESV in maintaining list of open connections wither dialed in our made the remote connection. Enduro/X driver in active mode is attempting to keep the number of configuration connections open if active. During the passive mode it limits the number of open connections set by configuration flag.
Configuration: The passive the mode is activated by type parameter. Value A means active, value P means passive. The maximum number of connections are configured with max_connection ini file parameter.
There are two major group of connection modes: persistent and non persistent. them persistent are ones when the connection is permanently open. And non persistent is when connection is open only during the request/reply pair.
configuration: the async mode with persistent channel can be configured with following flags:
req_reply = false
In case if Enduro/X is calling the network with out correlation, then TCPGATE service is called with tpcall(). The buffer contains following data:
Service TCPGATE receives in tpcall() mode following data:
Request buffer:
In case of error:
Configuration:
In case if network is sending us a message, and we run in non correlated mode (corr_svc not set in ini). Then incoming message is filled following data, and is delivered in asynchronous way (tpacall(), with TPNOREPLY) to the target ATMI server. The server receives following data:
Configuration:
In case if Enduro/X is willing to send the message to Network with correlation, then the UBF buffer must contain field EX_NETCORR. If the field is present the once the message is submitted to network, the correlator will be registered in to hash list as waiting for answers. When answer from network is received (or any other call), then message must be sent to correlation service. Which will parse the message and will provide back the correlation number. NOTE: The correlation service (corr_svc must be set in ini). The service have right to change the UBF buffer EX_NETDATA value. So that for example the correlation service have parsed the message and destination service do not have to parse it again. In case if correlation is found in registered list of waiters, then response message is sent to caller go routine (via channel). If the correlator number is not present in answer or the the waiter is not found in the correlator hash list (for example caller timed out), The message with all its content with EX_NETDATA (can be updated) and EX_NETCONNID and EX_NETCORR (optional) will be sent to incoming service in async mode (tpacall() with TPNOREPLY) to incoming_svc service configured in ini file.
Enduro/X-to-Net buffer:
Net-to-Enduro/X:
tpreturn() in case if found in correlation hash list or tpacall() if correlation is not found in hash list:
Configuration:
This is synchronous mode, meaning that one request/replay pair is transferred over the channel only one at time.
In this case Enduro/X synchronously invokes the TCPGATE service, but routine is waiting for answer from the channel. The correlator in this case is connection id. So once some socket receives the message, the list of waiters on connection ID are searched, if some entry is found, then answer is made (data sent to waiter channel). Then connection is removed from waiters list. In case if for incoming connection we cannot find connection id waiter, then if defined, we send the message to incoming_svc if set
Buffer out (to Net):
Reply buffer (or tpcall if connid waiter not found):
Buffer in response in case of timeout:
Configuration:
In case of Network sending requests to XATMI in sync mode. We receive request, we shall do the tpcall() synchronous. Wait for answer and send reply back to network. In case of timeout, we do not send anything. The incoming call will get the free XATMI context object (possibly wait for it). Timeout is controller by global Enduro/X configuration flag NDRX_TOUT.
Net→Ex request buffer:
XATMI Response buffer: - Mandatory: EX_NETDATA - data to send to network
Configuration:
In case of non persistent processing, new connection is open on every request.
In this case tcp driver must be in active mode. I will open new connection for every request. Once reply or timeout is received the connection is closed. The pool of connections is not needed, but driver is keeping the track of max open connections, if connections are over-reached, then reject message will be passed back to XATMI caller.
Ex→Net request buffer:
XATMI Response buffer:
or
XATMI Response buffer:
or
Configuration:
In this case TCP Driver is running in passive mode. And is waiting for incoming connections. When new connection is established, then new go routine is spawned. Then the call is made to XATMI service. The time-out is controlled by XATMI service invocation.
Ex→Net request buffer:
XATMI Response buffer:
Configuration:
The tcpgatesv will send the state information about each connection - established or not. Connection state data will be sent to status_svc service (if configured in ini). following data is present in status request messages:
In case of server starting up and we are running in active mode (type=A) we shall send for all max_connection the status that connection is closed.
The connection statuses are reported only in persistent connection mode (req_reply=0).
If parameter zero_keepalive is set to number greater than 0, then that is the number of seconds for which to each open connection connection zero length message is sent.
In case of service returns failure, for outgoing messages, Enduro/X tcpgateway driver will return error information in EX_NERROR_MSG and EX_NERROR_CODE fields:
0 - Succeed, no error
8 - Time-out (answer not received in time)
9 - Connection not found
For more details read on: https://www.endurox.org/dokuwiki