Table of Contents
This chapter describes an overview of the TCP/IP gateway system and its operation and service types.
TCP/IP Gateway (TCP/IP Gateway, hereafter TCPGW) is a gateway provided in Tmax and is responsible for the interface between Tmax servers and non-Tmax servers (hereafter remote node). TCPGW is a type of Tmax server and works as a gateway between servers (UNIX, Windows, etc.) connected through TCP/IP.
TCPGW receives a message from the remote node and makes a tpacall to the applicable service and the service result is sent to the remote node server. Reversely, if a Tmax service makes a request through tpcall or other methods, then TCPGW sends the request message to the remote node and when it receives a reply, it makes a tpreturn to the initiator service. Since complex tasks required for connecting to other systems through TCP/IP such as opening the socket and sending/receiving messages are all handled by TCPGW, a developer only needs to implement the business logic.
The following diagram shows the basic operation of TCPGW.
TCPGW operates in the following two modes.
-
A service request initiated by Tmax
The service flow for this mode is represented by the dotted lines in [Figure 1.1]. A Tmax client makes a service request to the remote node. This is called an inbound service.
-
A service request initiated by the remote node
The service flow for this mode is represented by the solid lines in [Figure 1.1]. TCPGW receives a service request from a remote node and then processes it. This is called an outbound service.
TCPGW runs in the synchronous or asynchronous call method.
-
This method is represented by the dotted lines in [Figure 1.2]. A Tmax client or service calls TCPGW and waits until it receives a reply.
-
This method is represented by the solid lines in [Figure 1.2]. When the Tmax client calls a Tmax service, control is passed from that service to TCPGW and the service can receive other service requests. When TCPGW receives a reply from the remote node, the request is passed to the service that processes responses.
Note
TCPGW installed on Tmax is a type of Tmax server, and it must be configured as a server in the Tmax environment file. While general servers are created using a TCS or UCS server library, but TCPGW creates a server by linking external communication libraries (libtcpgw.a, libtcpgw.so) with a user-created program (custom.c). For detailed information about the Tmax environment configuration, refer to "Chapter 2. Environment Configuration" and "Chapter 3. User Programs and Functions".
TCPGW is created by linking Tmax libraries (libtcpgw.a, libtcpgw.so), with user created programs such as custom.c and custom.h. TCPGW created in this way communicates with the remote node and works as an intermediary in sending Tmax client requests to the remote node and enabling Tmax service to process requests from a remote node.
Depending on its operation mode, TCPGW operates as either a synchronous TCPGW or asynchronous TCPGW, and depending on its startup mode, it runs as wither a server TCPGW or a client TCPGW. The server and client modes determine which side initiates the connection when a remote node and TCPGW are connected. Once the connection is established, either party can request a service to the other party.
The synchronous method is where a Tmax client or server requests a service and receives a response. In the opposite case, when the remote node requests a service, TCPGW forwards the request to a Tmax service and returns the result to the remote node.
In the former case, TCPGW operation depends on whether the Tmax service that sent the request to the remote node is blocking or non-blocking. If non-blocking, the result from the remote node is immediately returned to the requested channel.
Note
When a Tmax client or server sends a request to the remote node in the synchronous mode, TCPGW and the remote node must share the UID (unique ID).
Blocking Service
In a blocking service, a Tmax server or client requests a service to TCPGW and waits for a response. If the service that received the client request makes a tpcall to the TCPGW service, then the Tmax service (SVC1 in the diagram) blocks until it receives the result from the remote node.
When TCPGW executes, the service called by the client calls TCPGW and blocks until it receives a reply. Even when tpacall is called, tpgetrply blocks until it receives a reply. In order to accommodate a large number of requests, many servers are required to make up for the blocking time period.
A blocking service is suitable for external communication since many servers are needed to prepare for external system failures (machines, network).
The following diagram shows the operating structure of TCPGW when calling a service in a blocking synchronous mode.
-
TCPGW and the remote node are in the connected state.
-
A Tmax client sends a tpcall to the Tmax service.
-
The Tmax service receives the client request, and sends a tpcall to TCPGW.
-
TCPGW sends the request to the connected remote node.
-
When the remote node sends a reply, TCPGW checks for any errors.
-
TCPGW sends a reply (tpreturn) to the initiator service.
-
The service returns the reply (tpreturn) to the Tmax client.
Non-Blocking Service
A non-blocking service cannot be used when a Tmax client directly requests services to TCPGW. It requires an intermediary server between the client and TCPGW to send/receive the request/reply to/from TCPGW and return the reply to the client. The sending and receiving services are placed in front of TCPGW. The Tmax client calls the sending service, and the sending service terminates after forwarding the request to TCPGW.
TCPGW requests a service to the remote node, receives a reply, and sends it to the receiving service. The receiving service returns the reply to the client. In other words, the client requests a service and receives a reply (synchronous), but the server forwards the request and then terminates (asynchronous).
A non-blocking service can process more requests with fewer servers than a blocking service. Since a blocking service calls TCPGW and then blocks, it requires more server processes to handle multiple requests simultaneously. However, since a non-blocking service is terminated after performing its tasks, it can process more requests with a small number of server processes.
A non-blocking service is more efficient for communication with external institutions.
The following diagram shows the operation of TCPGW in a non-blocking service.
-
TCPGW and the remote node are in the connected state.
-
A Tmax client sends a tpcall to the Tmax service.
-
The Tmax service receives the client request, and forwards (tpforward) it to TCPGW.
-
TCPGW sends the request to the connected remote node.
-
When the remote node sends a reply, TCPGW checks for any errors.
-
TCPGW sends the reply (tprelay) to the service that will process the return.
-
The service returns the reply (tpreturn) to the Tmax client.
Remote Synchronous Call Method
A remote node initiates a service request to TCPGW. TCPGW calls the requested service and receives a reply and sends it to the channel that requested the service. The remote node cannot make more than MAXSACALL number of concurrent calls to TCPGW as defined in the Tmax environment file.
The remote synchronous call method is the most universal way of calling a Tmax service from a remote node. TCPGW stores the remote node's channel information and uses it to find the channel to send the reply. Other requests can be made as needed before the reply is returned to the channel. Since TCPGW does not block the channel from the remote node and continues to receive other requests, requests are processed according to the TCPGW operation method.
The following diagram shows the operation of TCPGW when a service is called in the remote synchronous method.
-
TCPGW and the remote node are in the connected state.
-
The remote node sends a request to the channel connected with TCPGW.
-
TCPGW calls a Tmax service via tpacall().
-
TCPGW receives a reply and finds the channel where the request originated from.
-
If the channel is normally connected, then the result is returned to the remote node.
The asynchronous method is where a Tmax client, server, or remote node requests a service and does not receive a reply, or the request is processed in another program. A Tmax service requests the service to TCPGW and another service receives a reply.
A client request is processed asynchronously via tpacall without receiving a reply. Reversely, a service can be initiated from the remote node and may not receive a reply or receive the reply through another channel. This is called the asynchronous method.
Requesting a Service from Tmax
A Tmax service makes a request via tpacall with TPNOREPLY to TCPGW and then the service terminates. TCPGW sends a request to the remote node and when it receives a reply it makes a tpacall to another service.
The following diagram shows the TCPGW operation in an asynchronous service request.
-
TCPGW and the remote node are in the connected state.
-
A Tmax service sends a request to TCPGW via tpacall with TPNOREPLY.
-
TCPGW sends the request to the remote node.
-
TCPGW receives a reply from the remote node.
-
TCPGW calls another Tmax service via tpacall with TPNOREPLY.
Requesting a Service from the Remote
When a remote node requests a service to TCPGW, TCPGW calls the Tmax service via tpacall. After processing, the Tmax service sends a reply to TCPGW, and TCPGW uses any available channel to return the reply to the remote node.
The following diagram shows the operation of TCPGW when a service is requested from the remote node asynchronously.
-
A remote node sends a request to TCPGW.
-
TCPGW sends the request to the Tmax service via tpacall.
-
The Tmax service sends a reply to TCPGW.
-
TCPGW finds the channel connected to the remote node in the channel table and sends the reply via the channel.
The TCPGW server and the TCPGW client operations only differ in the way they connect and have the same functionality. The remote node connects to the TCPGW server that is in waiting. Either the remote node or the Tmax client can make a request to TCPGW.
The following diagram shows the operation of TCPGW server.
-
TCPGW waits for a connection request from the remote node when Tmax starts up.
-
The remote node connects to TCPGW.
This section describes other functions of the TCPGW.
The gateway header is used when calling TCPGW from the Tmax client or server. Other TCPGW libraries must be used to use the gateway header. The libtcpgw.a, and libtcpgw.so libraries are normally used, but the libtcpgw.gwh.a, or libtcpgw.gwh.so library must be used when using the gateway header. The gateway header must be placed in the very first offset position in all data buffers. When using the user header, it must be placed after the gateway header in the buffer.
The gateway header is used for various purposes, but only the svc item can be used in TCPGW. This item is used to specify the service name to process the reply data when using the non-blocking mode or the asynchronous method. The gateway header is usually used when a service request is processed in message units without using a user header.
TCPGW finds the service that will process the reply in the following order.
-
Gateway Header
-
User Header
-
[-S] Option
In general, TCPGW receives a single reply per request. Depending on the situation, multiple replies can be received and TCPGW processes them by calling the get_msg_info function in custom.c for each reply. The user determines if the received data is the last data and returns an appropriate value.
In the case of consecutive data, if 3 is returned as the return value, then TCPGW determines that there is more data to receive and waits for more data without replying to the client or service. When the user receives the last data and returns 1 as the REPLY value, TCPGW returns all received data to the client or service.
A non-blocking or asynchronous TCPGW requires a Tmax service that will process a request or reply sent from the remote node. Since TCPGW does not have service name information, the user must specify the service name. TCPGW uses the following 3 methods to discover the service name.
The service name mentioned here must be registered in the Tmax configuration file.
-
When a Tmax client or service calls TCPGW by specifying the service name in the gateway header, TCPGW uses this name first. This only applies when the gateway header is used.
-
Find the service name in the user header. When a Tmax client or service calls TCPGW, the user name can be specified in the user header and the user function get_service_name can be used to get the name.
-
The service name is specified in the [-S] of option of CLOPT. In this case, the same service is used for all messages.
Note
When a service is requested for the first time from a remote node, these methods are not used. Instead, the user must specify the service name when calling the get_msg_info function.
When TCPGW is configured completely in asynchronous mode, the user can specify the channel to the remote node in the [-a] option of the CLOPT section. In a completely asynchronous mode, no replies are exchanged between the two sides. The reply data must also be sent as a service request.
For example, if tpacall with TPNOREPLY is sent from a Tmax client or service to TCPGW, TCPGW sends data to the remote node and terminates the service without storing the UID or any other data related to the service request. When TCPGW receives a reply from the remote node, it processes the reply as another service request. The same applies to the reverse case when the remote node imitates a request.
In the previous case, the remote node channel can be specified in the [-u] option in the CLOPT section. The channel can be set in the following two ways.
-
When Tmax sends a service request to a remote node, TCPGW calls the get_channel_num function and the channel is defined by the user by analyzing the transmitted data.
-
When the remote node initiates the request, the get_msg_info function saves its channel information and calls the Tmax service. To send the result to the remote node, the Tmax service calls tpacall with TPNOREPLY to TCPGW. The user can call the get_channel_num function which uses the saved channel information to send the reply to the remote node. In this mode, the channel between TCPGW and the Tmax engine is not blocked and the reply can be sent to the channel that initiated the service.
The machine where TCPGW is running use the ASCII code (euc-kr for Korean). Since the machine of the remote node may use a different character encoding, its encoding must be converted to the one used on the TCPGW node in order to send and receive messages. Code conversion for this can be done on the remote or TCPGW node.
TCPGW only supports ASCII ↔ EBCDIC and Korean composition Hangul ↔ euc-kr conversions. When a message is sent from TCPGW to the remote node, character encoding is converted from ACII to EBCDIC and from euc-kr to Korean composition Hangul. When a message is received the remote, encoding is converted from EBCDIC to ASCII and from Korean composition Hangul to euc-kr.
TCPGW converts encoding per service processing unit. TCPGW registers the sending/receiving format (map file) based per service unit for conversion. To convert encoding between TCPGW and the remote node, the user must register the map file for all services.
The gateway header must also be used to use the code conversion function in TCPGW. Since TCPGW does not know the name of the service that sends a reply to the remote node, it must be included in the gateway header sent to TCPGW. The remote service name must be set in the pgmname item of the header, and TCPGW loads the map file using the set value and converts the encoding.
When a Tmax client or service sends a request to the remote node, TCPGW loads the map file using the pgmname value in the gateway header. When a service is requested from the remote node to Tmax, the map file is loaded with the service name specified in the get_msg_info function.
The following describes the method for registering the map file. The map file can be registered in the user-specified text file format.
# COMMSIZE is used for both INPUT/OUTPUT so enter the larger value # between INPUT/OUTPUT size. *COMMSIZE 1024 *INPUT #--------------------------------------------------------------- # item-name length data-type # data-type: CHAR, NUMERIC(UNPACK), KOREAN, BINARY, USER-TYPE #--------------------------------------------------------------- a 10 CHAR b 10 KOREAN c 5 NUMERIC d 10 BINARY *OUTPUT a 10 CHAR b 10 KOREAN c 5 NUMERIC d 10 BINARY e 3 USER1 e1 6 CHAR e2 10 KOREAN e3 8 BINARY
-
COMMSIZE
Length of the data that is sent/received to/from the remote node. Must enter the largest message length among all transmitted messages.
-
INPUT
Message that is sent from TCPGW to the remote node. When a service is requested from TCPGW to the remote node, register it in the request message format. When a service is requested from the remote node to Tmax, register it in the reply message format.
-
item-name (Item name)
Name used as a reference by the user. TCPGW recognizes it as an item name and doesn't use it internally.
-
length (item length)
Actual length of each item in the sent/received data. TCPGW internally use each item length to calculate the offset for use. The offset always starts from 0.
-
data-type (data type)
Data type of each sent/received data item.
Data Type Description CHAR All characters (English, numbers, Korean). NUMERIC Only numbers. Encoding is converted similar to CHAR type. This does not indicate an Integer. KOREAN All Korean data.
TCPGW always converts this type in 2 byte units. When Korean is included in CHAR, the start and end characters of Korean are included between Korean and other characters (English, numbers, special characters). However, this data type considers all characters as Korean and thus the start and end of Korean are included only at the start and end of the data.
BINARY Unconverted data. Use this type to keep the original data encoding. USER-TYPE Array data format.
When multiple items are displayed on the screen repeatedly, each item must be registered separately. Even if the repeat count is expressed in the data, encoding conversion is still difficult without knowing the actual repeat count. In such cases, array format data can be easily converted using a user-defined type.
-
OUTPUT
Message that is sent from the remote node to TCPGW. When a service is requested from TCPGW to the remote node, register it in the reply message format. When a service is requested from the remote node to Tmax, register it in the request message format.
USER1 in the previous map file is a user-defined type. The user can define a desired type name. The user defined data must be a number since it expresses repeated array data. When TCPGW considers a user defined-type as the array count.
The last item name of the array starts with a slash (/). In the previous example, e1, e2, and e3 are all recognized as array items, and conversion is executed e, the array count variable, number of times.
Caution
The array count is not registered in the map file, but is included in the message transmitted between TCPGW and the remote node.