3270 Gateway for Linux

What is the 3270 Gateway?

The 3270 Gateway for Linux is a software product which provides 3270 access via TCP/IP to an IBM mainframe (OS/390, MVS, or VSE) host system, without the need to run TCP/IP on the mainframe.

To the mainframe, the gateway appears to be a LAN-attached 3174 cluster controller with up to 255 SNA 3270 terminals. To the TCP/IP network, the gateway acts as a tn3270 server. Each tn3270 client which connects to the gateway appears as an SNA 3270 terminal on the mainframe.

The diagram below shows an example configuration:


+--------+
| tn3270 |___
| client |   \                                +------+         +----+
+--------+    \                               | 37x5 |        /    /|
               \           Linux              |  or  |       +----+ |
+--------+                +---------+         | 3172 | SNA   |    | |
| tn3270 |___ TCP/IP  ____| 3270    |         |  or  |=======|9672| |
| client |    network     | Gateway |         | 3174 |       |    | |
+--------+                +---------+         +------+       |    |/
               /               |                  |          +----+
+--------+    /              ------------------------        S/390
| tn3270 |___/                Token-Ring or Ethernet        Mainframe
| client |                          SNA 802.2
+--------+
 Win95/NT/Unix

What software is required for the 3270 Gateway?

The 3270 Gateway requires a Linux system using kernel version 2.2.5 or later.
A Token-Ring or Ethernet connection is required to a 37x5 Communications Controller, a 3172 Interconnect Controller, or a 3174 Cluster Controller on the mainframe SNA network. The mainframe VTAM system (OS/390, MVS, or VSE) must be configured to access the 3270 Gateway as a LAN-attached PU type 2.0. Communication via AS/400 or Microsoft SNA Server is also possible.
Each client system requires tn3270 client software. For Windows clients, you can use popular commercial packages such as IBM Personal Communications 3270, Attachmate Extra, Dynacomm Elite, Vista tn3270, or QWS3270. For Unix clients, you can use tn3270 or X3270.

How to install and configure the 3270 Gateway for Linux

How to install the DLPI/DLC software

Login as root and download dlc-2.3.tar.gz to your home directory.
Unpack the DLPI/DLC source files in your home directory:
tar xvzf dlc-2.3.tar.gz
Change to the dlpi directory:
cd dlpi
Determine your Linux kernel version by entering the command
uname -r
The DLPI/DLC is distributed with precompiled modules for kernel versions 2.2.5 and 2.2.10. If your kernel version is one of these, you can skip to the next step. If you are using a different kernel version, you must recompile the modules for your kernel. Refer to the dlpi/README file for details.
Now you must copy the dlc.o, dlpi.o, and ibmtr.o modules from the dlpi/2.2.x subdirectory into /lib/modules/2.2.x/net. You can do this by issuing this command in the dlpi directory:
make install

How to install the 3270 Gateway software

First install the DLPI/DLC support as described above.
Login as root and download gw3270-1.11.tar.gz to your home directory.
Unpack the downloaded file into your home directory:
tar xvzf gw3270-1.11.tar.gz
Copy the executable file to /usr/sbin:
cp gw3270/tn3270d /usr/sbin
Copy the startup script to /etc/rc.d:
cp gw3270/rc.gw3270 /etc/rc.d

How to configure the 3270 Gateway

The gateway configuration parameters are contained in the startup script. Before starting the gateway, edit the file /etc/rc.d/rc.gw3270 and set the parameters as described below:

TN3270_PORT: This is the port number which tn3270 clients will use to connect to the 3270 Gateway. Choose a port number which is not used by any other service (see /etc/services for a list of port numbers). The port number is specified as a decimal number. The recommended port number is 24.
ADAPTER: This is the name of the LAN adapter which you will use to connect to the mainframe communications controller. Specify tr0 for the Token-Ring adapter or eth0 for the Ethernet adapter.
LOCAL_SAP: This is the identifier of the Service Access Point for the Gateway. Specify a 2-digit hexadecimal number. If you are running only one gateway, specify LOCAL_SAP=04. For subsequent gateways on the same machine, specify SAP values 08, 0C, 10 (SNA SAP identifiers are always a multiple of 4). This value must match the third and fourth digits of the DIALNO operand in the PATH statement in the VTAM switched major node for the gateway.
REMOTE_MACADDR: This is the address of the LAN adapter in the host communications controller. Specify a 12-digit hexadecimal number. For attachment via a 37x5, this value must match the LOCADD parameter in the LINE statement for the LAN adapter in the NCP definition. For attachment via a 3172, this value must match the MAC address of the LAN adapter.
REMOTE_SAP: This is the identifier of the Service Access Point on the host communications controller. Specify a 2-digit hexadecimal number. For attachment via a 3x75, specify REMOTE_SAP=04. For attachment via a 3172, this value must match the SAPADDR parameter of the PORT statement in the VTAM XCA major node for the 3172.
LOCAL_XID: This is the XID value which the gateway sends to the host during connection establishment. Specify an 8-digit hexadecimal number. The first three digits must match the IDBLK parameter of the PU statement in the VTAM switched major node for this gateway. The last five digits must match the IDNUM parameter of the PU statement in the VTAM switched major node for this gateway. The IDBLK is meant to represent the gateway device type -- typical IDBLK values are 017 and 05D, although any non-zero value can be used. The IDNUM is any non-zero value chosen to uniquely identify the PU in the network.
LOG_LEVEL: This parameter controls the messages issued by the 3270 Gateway. Possible values are: 0 (no messages), 1 (connection messages), 2 (trace all SNA headers), 3 (trace SNA headers and data).

How to override the token-ring adapter address

The patch to the ibmtr.c driver supplied with dlc-2.3 and above allows you to override the hardwired adapter address of your IBM Token-Ring adapter with a locally-administered address in the range 400000000000 to 7FFFFFFFFFFF. This is necessary to establish communications with devices such as the IBM 3174 which do not allow you to specify MAC addresses containing hexadecimal digits. To specify a locally-administered address, add a line like this to your /etc/conf.modules file:

         options ibmtr mac=400031740222

How to configure the mainframe VTAM definitions

You must define a VTAM switched major node for the 3270 Gateway. The following is an example:


SW3270  VBUILD TYPE=SWNET,                                             X
               MAXNO=1,                                                X
               MAXGRP=1
PUXXXX   PU    ADDR=01,                                                X
               PUTYPE=2,                                               X
               IDBLK=05D,                                              X
               IDNUM=21436,                                            X
               DISCNT=NO,                                              X
               MAXOUT=3,                                               X
               MAXDATA=1024,                                           X
               MAXPATH=1,                                              X
               PASSLIM=1,                                              X
               DLOGMOD=D4C32782,                                       X
               ISTATUS=ACTIVE
PTHXXXX  PATH  DIALNO=010410005A443832,                                X
               GRPNM=GRPXXXX
LUXXXX02 LU    LOCADDR=2
LUXXXX03 LU    LOCADDR=3
LUXXXX04 LU    LOCADDR=4
LUXXXX05 LU    LOCADDR=5

This example shows 4 LU definitions. Up to 255 LUs can be defined, each must have a unique LOCADDR in the range 1-255. Each LU represents one concurrent client connection to the 3270 Gateway.
The GRPNM parameter must match the label on the GROUP statement for the LAN adapter in the NCP definition (for connection via a 37x5) or in the XCA major node (for connection via a 3172).
For connection via a 37x5, the first two digits of the DIALNO parameter must match the PORTADD parameter in the LINE statement for the LAN adapter in the NCP definition. For connection via a 3172, the first two digits of the DIALNO parameter are ignored.
The third and fourth digits of the DIALNO parameter must match the LOCAL_SAP parameter in the 3270 Gateway configuration file.
The last twelve digits of the DIALNO parameter must match the MAC address of the LAN adapter in the system running the 3270 Gateway. Use the ifconfig command to find out the LAN adapter address:
ifconfig tr0 or
ifconfig eth0

How to configure the tn3270 clients

The precise method of configuring each client will depend on the particular tn3270 product chosen, but in each case you will need to specify a hostname and a port number. The hostname must be the name or IP address of the Linux system running the 3270 Gateway, and the port number must match the TN3270_PORT parameter in the 3270 Gateway configuration file.

How to start the 3270 Gateway

Login as root and enter:
/etc/rc.d/rc.gw3270
Activate the VTAM switched major node on the mainframe.

How to display the status of the 3270 Gateway

You can obtain a status display by connecting to the gateway using a regular (non-3270) telnet client, as shown in this example:


# telnet hgunix1 24

Connected to TN3270D 1.10 at hgunix1.snipix.co.uk (Linux 2.2.5)

---PU STATUS---    --PUID--   PID  PORT ---SSCPID--- LS HOST-MACADDR RS INTF
ACTIV CONNECTED    05D21436   557    24 040000000000 04 00AA00AE5786 04 eth0

LU STATUS ----CLIENT----  LU STATUS ----CLIENT----  LU STATUS ----CLIENT----
002 ACT/S 192.168.200.137 003 ACT/S 192.168.200.133 004 ACTIV
005 ACTIV

Connection closed by remote host.

How many clients can the 3270 Gateway support?

The gateway is a PU type 2.0, and is therefore limited by the SNA architecture to 255 LUs. So the answer is 255 clients per gateway. To support more than 255 clients, you can run multiple instances of the gateway on a single Linux machine. Each instance will require unique settings for the TN3270_PORT, LOCAL_SAP, and LOCAL_XID parameters in its configuration file, and each gateway instance must have a PU definition with associated LUs in the VTAM switched major node. The number of gateways which can be realistically supported by a single Linux machine will depend on the capacity of the machine.

Last updated 31 Mar 2000