Environment Configuration

This chapter describes the environment configuration of X25GW.

1. Overview

To configure an X25GW server, the following files must exist.

  • UNIX

    The following table shows the environment files for UNIX.

    Directory File Name

    lib

    lbx25gw.a, libx25gw.so, libtmaxgw.a, libtmaxgw.so

    lib64

    lbx25gw.a, libx25gw.so, libtmaxgw.a, libtmaxgw.so

  • Windows

    The following table shows the environment files for Windows.

    Directory File Name

    lib

    x25gw.dll, tmaxgw.dll

    lib64

    x25gw.lib, tmaxgw.lib

X25GW libraries are created in each directory when Tmax is installed. If custom.c or custom.h is needed, contact a technical support team.

X25GW is created by compiling the X25GW and properly created custom.c and custom.h files.

2. Tmax Environment Configuration

To use X25GW, X25GW must be configured as a server in the Tmax environment file. Configuration is similar to the UCS server among Tmax servers except that SVRTYPE is CUSTOM_GATEWAY instead of UCS. For X25GW, only the SERVER and SERVICE sections have to be configured.

The following is an example of a Tmax environment file.

*DOMAIN
tmax    SHMKEY = 88000,
        MINCLH = 1,
        MAXCLH = 1,
        TPORTNO = 8800

*NODE
tmax1   TMAXDIR = “/home/tmax”,
        APPDIR = “/home/tmax/appbin”

*SVRGROUP
svg1    NODENAME = tmax1

*SERVER
x25gw   SVGNAME = svg1,
        MIN = 1,
        MAX = 1,
        CPC = 10,
        SVRTYPE=CUSTOM_GATEWAY,
        CLOPT=”-- -F /home/tmax/config/x25gw.cfg –N 4096 –h 20”

*SERVICE
X25GW1  SVRNAME=x25gw, SVCTIME=20
X25GW2  SVRNAME=x25gw, SVCTIME=25
Item Description

MIN

Number of X25GW processes. If greater than 1, the channel information must be defined separately for each process. For more information, refer to X25GW Channel Configuration.

CPC

Number of channels between the Tmax engine and X25GW. When a Tmax client initiates a service call to the remote node, the CPC count must be set to the number of concurrent requests. When the remote node initiates the call, X25GW makes a request to the Tmax engine through tpacall which does not require as many channels.

CLOPT

For more information, refer to CLOPT Item (X25GW Option).

SVCTIME

X25GW can specify multiple services in a single server process and apply a different SVCTIME value for each service. If multiple services are specified in the SERVICE section each with a different SVCTIME value, then X25GW uses the specified SVCTIME values.
CLOPT Item (X25GW Option)

Since the items that can be registered in the Tmax configuration file for X25GW are limited, some options must be configured in the CLOPT item. The following options that define the operations of X25GW must be well understood.

Option Description

[-r]

Maximum number of attempts allowed for reconnecting to a remote node.

When X25GW has exceeded the limit, it will no longer attempt to connect to the remote node. (Default: Infinite)

[-N]

Maximum message size that can be transmitted between X25GW and remote node. Since X25GW allocates memory according to this setting, sufficient size should be set.

[-n]

Message size that can be transmitted at once between X25GW and the remote node.

A message whose size is set with the [-N] option is divided and transmitted in units specified by this setting. This size cannot be greater than the value of the [-N] option. (Default: same as the [-N] option)

[-t]

Interval (second) for reconnecting to the remote node. A channel that is disconnected from the remote node does not attempt to reconnect immediately but at the interval specified by this setting. (Default: 3 seconds)

[-k]

Key value for the shared memory to enable a user to store the state of the channel defined in the X25GW environment file.

X25GW does not allocate shared memory but only passes it to the user. When X25GW starts up, it passes the memory to the user inside the user routine (init_remote_info) so that the user can obtain the memory.

[-F]

Environment file that contains the channel information of X25GW.

[-S]

Receiving service name to call when X25GW is in the non-blocking or asynchronous mode.

When the non-blocking mode is used, Tmax’s sending service tpforwards the request to X25GW. Then X25GW registers the service name to tprelay the reply received from the remote node to the receiving service. In the asynchronous mode, the Tmax client or service requests a service to X25GW (tpacall with TPNOREPLY) and then shuts down. Later, the reply is usually received via TPNOREPLY from the remote node and is discarded. However, if the service name is specified, X25GW sends the reply to the specified service via tpacall. The specified service name must be a registered service name.

[-H]

Used when the user information is exchanged between a Tmax client or service and X25GW. Data specified in this option is temporarily stored in X25GW instead of being sent to the remote node. When the reply is received, the reply is attached to the user information and sent to the originating service.

This option is mostly used when the sending service sends data to the receiving service in the non-blocking mode.

[-h]

Same as the [-H] option except that this option is used for tpforward & tprelay calls while the [-H] option is used for both synchronous and asynchronous calls.

[-a]

Option to use X25GW in the asynchronous mode. In the asynchronous mode, a service shuts down after making a request. A service reply is treated as a new request.

[-u]

Channel to use when a Tmax client or service requests a service via X25GW to the remote node. To use this option, the [-k] option must be used to store the status information of the channel. If the specified channel is invalid, then X25GW returns an error.

[-Y]

Enables the recovery service to allow cancellation of the previously processed service when the result cannot be sent to the remote node after the service is normally processed on Tmax.

If the remote node and session are both disconnected after the remote node calls a Tmax service, the service result is not sent to the remote node and is discarded. This can create a problem since the service is processed normally but the remote node recognizes it as an error. If the service name is specified in this option, the reply is sent to the specified service instead when the gateway cannot send the reply to the remote node.

[-y]

Maximum message number (sequence number) that can be used as UID. (Default: 50000, and Maximum: 268435455)

2.1. Blocking Service

X25GW can operate in both synchronous/asynchronous mode when connected to the remote node.

*DOMAIN
...

*NODE
...

*SVRGROUP
...

*SERVER
x25gw   SVGNAME=svg1,
        MIN=1,
        MAX=1,
        CPC=10,
        SVRTYPE=CUSTOM_GATEWAY,
        CLOPT=”-- -F /home/tmax/config/x25gw.cfg”

*SERVICE
X25GW   SVRNAME=x25gw, SVCTIME=30

The previous environment configuration starts up a single X25GW instance named x25gw when Tmax starts up. The service name of x25gw is X25GW and the timeout is 30 seconds. If there is no reply within 30 seconds, a timeout error is returned. Timeout only checks requests from a Tmax client or service to the remote node. Services requested from the remote node must specify the timeout setting in the request.

X25GW uses the UID when a request is made to the remote node from a Tmax client or server. UID, the unique identifier of the message, must be passed to X25GW so that the reply can be sent to the originating client/server.

When a service is requested from the remote node, X25GW sends the reply to the requested channel. If the requested channel is disconnected, the data is abandoned.

2.2. Non-Blocking Service

Non-blocking X25GW is generally used when a service is requested from a Tmax service to the remote node. A general Tmax client cannot directly call services in this mode. Only the synchronous or asynchronous method can be used directly in the Tmax client.

*DOMAIN
...
*NODE
...

*SVRGROUP
...

*SERVER
x25gw       SVGNAME=svg1,
            MIN=1,
            MAX=1,
            CPC=5,
            SVRTYPE=CUSTOM_GATEWAY,
            CLOPT=”-- -F /home/tmax/config/x25gw.cfg –S RECVSVC –H 20”
sendsvr     MIN=1, MAX=1
secvsvr     MIN=1, MAX=1

*SERVICE
X25GW       SVRNAME=x25gw, SVCTIME=30
SENDSVC     SVRNAME=sendsvr
RECVSVC     SVRNAME=recvsvr

The previous environment configuration starts up a single X25GW instance named x25gw when Tmax starts up. The service name of x25gw is X25GW and the timeout is 30 seconds. If there is no reply within 30 seconds, then a timeout error is returned.

If a Tmax client or server initiates a call to the SENDSVC service, SENDSVC preprocesses the request and sends the control (tpforward) to the X25GW service.

X25GW first sends the channel cancellation message to the Tmax engine and requests the service to the remote node. When a reply is received, the result is sent (tprelay) to the service specified in the [-S] option. After RECVSVC processes the result and returns, the reply is sent to the originating client or service. Using the non-blocking mode, more requests can be processed using less number of service threads (SENDSVC). The UID is used to identify the request as in the blocking mode.

If the remote node does not return a reply within the set time (30s), then X25GW sends a timeout message to RECVSVC (tprelay). The RECVSVC service must check the tpurcode value and when the value is larger than 0 indicates an error which must be handled. The tpurcode is set and returned for all errors including timeout. For detailed information about errors, refer to X25GW Error Codes.

2.3. Remote Synchronous and Asynchronous X25GW

A service requested from the remote node can be specified as synchronous or asynchronous by setting the reply type in the X25GW environment configuration or setting TPNORELAY to the flags in the user defined function (get_msg_info). In the former case, the reply can be sent to another channel. In the latter case, the reply is not sent to the remote node.

*DOMAIN
...
*NODE
...

*SVRGROUP
...

*SERVER
x25gw        SVGNAME=svg1,
             MIN=1,
             MAX=1,
             CPC=5,
             SVRTYPE=CUSTOM_GATEWAY,
             CLOPT=”-- -F /home/tmax/config/x25gw.cfg”

*SERVICE
X25GW        SVRNAME=x25gw

When a Tmax service is requested from the remote node, X25GW uses tpacall and thus does not receive a reply. The number of allowed concurrent tpacalls is limited (default value: 8). When there are 8 or more concurrent requests, the MAXSACALL count must be set to an appropriate number in the DOMAIN section.

3. X25GW Channel Configuration

To enable the communication between X25GW and the remote node, the channel information must be configured in a separate file and the file name must be configured in the [-F] option. The instruction varies depending on the machine that will communicate with X25GW. The user must correctly understand the channel configuration items to facilitate a smooth communication between each machine and the remote node.

This section will first describe each channel items and then compare the items for each machine.

3.1. Channel Environment File

################################################################
################################################################
# x25gw_no | link_no | start_LCN_no | num_LCN | dir | reply_dedicated |
  devpath [| group_id]
#
# x25gw_no : x25gw process number. Starts from 0.
# link_no : x25 link number
# start_LCN_no : LCN (LU) start number
# num_LCN :  LCN (LU) count
# (start_LCN_no ~ (start_LCN_no + num_LCN))
# dir : LCN channel direction
#    in - For external system to tmax requests (Send)
#    out - For tmax to external system request (Receive)
#    any - any direction
# reply_dedicated : If set to yes, response to messages received through this LCN must be sent through this LCN.
                    If set to no, the response can be sent through any available LCN.
# devpath : x25 device path
# group_id : Channel group name (can be omitted)
################################################################
0 0 3 2 out no /dev/x25pkt
0 0 1 2 in  no /dev/x25pkt

The following table describes the channel configuration items.

Item Description

x25gw_no

Gateway number to identify X25GW process. Multiple processes can be configured in one X25GW channel configuration file when MIN item of the Tmax configuration file is equal to or greater than 2. X25GW processes connect to the remote node by loading the channel configuration that corresponds to its gateway number. Gateway number starts from 0 up to MIN value -1.

link_no

Link number to which the LCN belongs. One link can contain multiple LCNs (LUs). That is, many LCNs can share one link to communicate with the remote node.

start_LCN_no

Starting number of LU. One physical link can be divided into many logical LUs for communication.

num_LCN

Number of logical LUs, starting from the starting LCN number. When X25GW connects to the remote node, it creates as many channels as specified in this option.

dir

Channel type.

  • IN_CHANNEL: Request from the remote node to X25GW.

  • OUT_CHANNEL: Request from X25GW to the remote node.

  • ANY_CHANNEL: Both in/out requests.

reply_dedicated

Channel to send the response through.

  • yes: Response is sent to the channel of the request.

  • no: Response is sent to any applicable channel that is set to OUT_CHANNEL or ANY_CHANNEL.

devpath

Device name of X25GW which varies depending on the machine.

group_id

Group name of the channel. When two or more channels belong to the same group, round-robin load balancing is supported.

3.2. Machine Specific Channel Environment File

The following table describes the channel environment file for each machine.

Machine Item Description

IBM SUN

Channel information as described in Channel Environment File.

HP

devpath

For HP machines, an interface name (link name) is set to the device name item instead of the device name. Other items are same as for IBM or SUN.

NCR

start_LCN_no

Must always be 1. NCR machines have different local name for each LCN(LU).

num_LCN

Must always be 1.

devpath

Local name of each LCN. NCR communicates with the remote node using the local name and remote node name.

devpath2

Remote LCN name. Only applicable for NCR.

4. User Header Environment Configuration

A user header can be specified in X25GW. The user header can only be used when a service is requested from the Tmax client or service to the remote node, but not in the reverse direction. The data specified with the user header is not sent to the remote node but is stored in the temporary X25GW using its UID. When a reply is received, it finds the UID in the reply data and sends the user header data for the UID with the reply data. The length of the user header data can be up to 256 bytes.

The user header can be used in any mode, and can be specified in two ways. The user header length can be set differently when using the tpforward method (non-blocking) and when using other services (blocking, asynchronous).

*DOMAIN
...

*NODE
...

*SVRGROUP
...
*SERVER
x25gw        SVGNAME=svg1,
             MIN=1,
             MAX=1,
             CPC=10,
             SVRTYPE=CUSTOM_GATEWAY,
             CLOPT=”-- -F /home/tmax/config/x25gw.cfg –H 9 –h 10”

*SERVICE
X25GW        SVRNAME=x25gw

The [-H] option is used for specifying the user header for all service request types, while the [-h] option can only be used for the tpforward method (non-blocking).

In the previous environment configuration, 9 bytes of the transmitted data are stored for general services and10 bytes are stored for tpforward, and only the remaining data are sent to the remote node. When the reply is received from the remote node, the stored user header is attached to the reply data and returned.

The user can selectively use the user header through various methods.

The following is a typical method of using the user header.

  • Specifying tprelay or the asynchronous service name

    When it is used in the non-blocking method, the service to tprelay can be specified in the user header. When the service is also specified with the [-S] option, X25GW first calls the user function (get_service_name) in the user header and finds the service. When the service is not found, the service specified with the [-S] option is used. When a call is made using asynchronous method via tpacall with TPNOREPLAY, the reply data is processed as described above.

  • Storing key data

    In the non-blocking mode, there are separate sending and receiving service processes. The sending service processes tasks in the database and sends data to the remote node, and then terminates. This is often used when the receiving service needs to know the database key information that was processed by the sending service, or when the receiving service needs to store important information to rollback database changes when an error occurs on the remote node.