2IBM 3270 Display System support
   5This file describes the driver that supports local channel attachment
   6of IBM 3270 devices.  It consists of three sections:
   8        * Introduction
   9        * Installation
  10        * Operation
  16This paper describes installing and operating 3270 devices under
  17Linux/390.  A 3270 device is a block-mode rows-and-columns terminal of
  18which I'm sure hundreds of millions were sold by IBM and clonemakers
  19twenty and thirty years ago.
  21You may have 3270s in-house and not know it.  If you're using the
  22VM-ESA operating system, define a 3270 to your virtual machine by using
  23the command "DEF GRAF <hex-address>"  This paper presumes you will be
  24defining four 3270s with the CP/CMS commands:
  26        - DEF GRAF 620
  27        - DEF GRAF 621
  28        - DEF GRAF 622
  29        - DEF GRAF 623
  31Your network connection from VM-ESA allows you to use x3270, tn3270, or
  32another 3270 emulator, started from an xterm window on your PC or
  33workstation.  With the DEF GRAF command, an application such as xterm,
  34and this Linux-390 3270 driver, you have another way of talking to your
  35Linux box.
  37This paper covers installation of the driver and operation of a
  38dialed-in x3270.
  44You install the driver by installing a patch, doing a kernel build, and
  45running the configuration script (, in this directory).
  47WARNING:  If you are using 3270 console support, you must rerun the
  48configuration script every time you change the console's address (perhaps
  49by using the condev= parameter in silo's /boot/parmfile).  More precisely,
  50you should rerun the configuration script every time your set of 3270s,
  51including the console 3270, changes subchannel identifier relative to
  52one another.  ReIPL as soon as possible after running the configuration
  53script and the resulting /tmp/mkdev3270.
  55If you have chosen to make tub3270 a module, you add a line to a
  56configuration file under /etc/modprobe.d/.  If you are working on a VM
  57virtual machine, you can use DEF GRAF to define virtual 3270 devices.
  59You may generate both 3270 and 3215 console support, or one or the
  60other, or neither.  If you generate both, the console type under VM is
  61not changed.  Use #CP Q TERM to see what the current console type is.
  62Use #CP TERM CONMODE 3270 to change it to 3270.  If you generate only
  633270 console support, then the driver automatically converts your console
  64at boot time to a 3270 if it is a 3215.
  66In brief, these are the steps:
  68        1. Install the tub3270 patch
  69        2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf`
  70        3. (If VM) define devices with DEF GRAF
  71        4. Reboot
  72        5. Configure
  74To test that everything works, assuming VM and x3270,
  76        1. Bring up an x3270 window.
  77        2. Use the DIAL command in that window.
  78        3. You should immediately see a Linux login screen.
  80Here are the installation steps in detail:
  82        1.  The 3270 driver is a part of the official Linux kernel
  83        source.  Build a tree with the kernel source and any necessary
  84        patches.  Then do::
  86                make oldconfig
  87                (If you wish to disable 3215 console support, edit
  88                .config; change CONFIG_TN3215's value to "n";
  89                and rerun "make oldconfig".)
  90                make image
  91                make modules
  92                make modules_install
  94        2. (Perform this step only if you have configured tub3270 as a
  95        module.)  Add a line to a file `/etc/modprobe.d/*.conf` to automatically
  96        load the driver when it's needed.  With this line added, you will see
  97        login prompts appear on your 3270s as soon as boot is complete (or
  98        with emulated 3270s, as soon as you dial into your vm guest using the
  99        command "DIAL <vmguestname>").  Since the line-mode major number is
 100        227, the line to add should be::
 102                alias char-major-227 tub3270
 104        3. Define graphic devices to your vm guest machine, if you
 105        haven't already.  Define them before you reboot (reipl):
 107                - DEFINE GRAF 620
 108                - DEFINE GRAF 621
 109                - DEFINE GRAF 622
 110                - DEFINE GRAF 623
 112        4. Reboot.  The reboot process scans hardware devices, including
 113        3270s, and this enables the tub3270 driver once loaded to respond
 114        correctly to the configuration requests of the next step.  If
 115        you have chosen 3270 console support, your console now behaves
 116        as a 3270, not a 3215.
 118        5. Run the 3270 configuration script config3270.  It is
 119        distributed in this same directory, Documentation/s390, as
 120  Inspect the output script it produces,
 121        /tmp/mkdev3270, and then run that script.  This will create the
 122        necessary character special device files and make the necessary
 123        changes to /etc/inittab.
 125        Then notify /sbin/init that /etc/inittab has changed, by issuing
 126        the telinit command with the q operand::
 128                cd Documentation/s390
 129                sh
 130                sh /tmp/mkdev3270
 131                telinit q
 133        This should be sufficient for your first time.  If your 3270
 134        configuration has changed and you're reusing config3270, you
 135        should follow these steps::
 137                Change 3270 configuration
 138                Reboot
 139                Run config3270 and /tmp/mkdev3270
 140                Reboot
 142Here are the testing steps in detail:
 144        1. Bring up an x3270 window, or use an actual hardware 3278 or
 145        3279, or use the 3270 emulator of your choice.  You would be
 146        running the emulator on your PC or workstation.  You would use
 147        the command, for example::
 149                x3270 vm-esa-domain-name &
 151        if you wanted a 3278 Model 4 with 43 rows of 80 columns, the
 152        default model number.  The driver does not take advantage of
 153        extended attributes.
 155        The screen you should now see contains a VM logo with input
 156        lines near the bottom.  Use TAB to move to the bottom line,
 157        probably labeled "COMMAND  ===>".
 159        2. Use the DIAL command instead of the LOGIN command to connect
 160        to one of the virtual 3270s you defined with the DEF GRAF
 161        commands::
 163                dial my-vm-guest-name
 165        3. You should immediately see a login prompt from your
 166        Linux-390 operating system.  If that does not happen, you would
 167        see instead the line "DIALED TO my-vm-guest-name   0620".
 169        To troubleshoot:  do these things.
 171        A. Is the driver loaded?  Use the lsmod command (no operands)
 172        to find out.  Probably it isn't.  Try loading it manually, with
 173        the command "insmod tub3270".  Does that command give error
 174        messages?  Ha!  There's your problem.
 176        B. Is the /etc/inittab file modified as in installation step 3
 177        above?  Use the grep command to find out; for instance, issue
 178        "grep 3270 /etc/inittab".  Nothing found?  There's your
 179        problem!
 181        C. Are the device special files created, as in installation
 182        step 2 above?  Use the ls -l command to find out; for instance,
 183        issue "ls -l /dev/3270/tty620".  The output should start with the
 184        letter "c" meaning character device and should contain "227, 1"
 185        just to the left of the device name.  No such file?  no "c"?
 186        Wrong major number?  Wrong minor number?  There's your
 187        problem!
 189        D. Do you get the message::
 191                 "HCPDIA047E my-vm-guest-name 0620 does not exist"?
 193        If so, you must issue the command "DEF GRAF 620" from your VM
 194        3215 console and then reboot the system.
 201The driver defines three areas on the 3270 screen:  the log area, the
 202input area, and the status area.
 204The log area takes up all but the bottom two lines of the screen.  The
 205driver writes terminal output to it, starting at the top line and going
 206down.  When it fills, the status area changes from "Linux Running" to
 207"Linux More...".  After a scrolling timeout of (default) 5 sec, the
 208screen clears and more output is written, from the top down.
 210The input area extends from the beginning of the second-to-last screen
 211line to the start of the status area.  You type commands in this area
 212and hit ENTER to execute them.
 214The status area initializes to "Linux Running" to give you a warm
 215fuzzy feeling.  When the log area fills up and output awaits, it
 216changes to "Linux More...".  At this time you can do several things or
 217nothing.  If you do nothing, the screen will clear in (default) 5 sec
 218and more output will appear.  You may hit ENTER with nothing typed in
 219the input area to toggle between "Linux More..." and "Linux Holding",
 220which indicates no scrolling will occur.  (If you hit ENTER with "Linux
 221Running" and nothing typed, the application receives a newline.)
 223You may change the scrolling timeout value.  For example, the following
 224command line::
 226        echo scrolltime=60 > /proc/tty/driver/tty3270
 228changes the scrolling timeout value to 60 sec.  Set scrolltime to 0 if
 229you wish to prevent scrolling entirely.
 231Other things you may do when the log area fills up are:  hit PA2 to
 232clear the log area and write more output to it, or hit CLEAR to clear
 233the log area and the input area and write more output to the log area.
 235Some of the Program Function (PF) and Program Attention (PA) keys are
 236preassigned special functions.  The ones that are not yield an alarm
 237when pressed.
 239PA1 causes a SIGINT to the currently running application.  You may do
 240the same thing from the input area, by typing "^C" and hitting ENTER.
 242PA2 causes the log area to be cleared.  If output awaits, it is then
 243written to the log area.
 245PF3 causes an EOF to be received as input by the application.  You may
 246cause an EOF also by typing "^D" and hitting ENTER.
 248No PF key is preassigned to cause a job suspension, but you may cause a
 249job suspension by typing "^Z" and hitting ENTER.  You may wish to
 250assign this function to a PF key.  To make PF7 cause job suspension,
 251execute the command::
 253        echo pf7=^z > /proc/tty/driver/tty3270
 255If the input you type does not end with the two characters "^n", the
 256driver appends a newline character and sends it to the tty driver;
 257otherwise the driver strips the "^n" and does not append a newline.
 258The IBM 3215 driver behaves similarly.
 260Pf10 causes the most recent command to be retrieved from the tube's
 261command stack (default depth 20) and displayed in the input area.  You
 262may hit PF10 again for the next-most-recent command, and so on.  A
 263command is entered into the stack only when the input area is not made
 264invisible (such as for password entry) and it is not identical to the
 265current top entry.  PF10 rotates backward through the command stack;
 266PF11 rotates forward.  You may assign the backward function to any PF
 267key (or PA key, for that matter), say, PA3, with the command::
 269        echo -e pa3=\\033k > /proc/tty/driver/tty3270
 271This assigns the string ESC-k to PA3.  Similarly, the string ESC-j
 272performs the forward function.  (Rationale:  In bash with vi-mode line
 273editing, ESC-k and ESC-j retrieve backward and forward history.
 274Suggestions welcome.)
 276Is a stack size of twenty commands not to your liking?  Change it on
 277the fly.  To change to saving the last 100 commands, execute the
 280        echo recallsize=100 > /proc/tty/driver/tty3270
 282Have a command you issue frequently?  Assign it to a PF or PA key!  Use
 283the command::
 285        echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
 287to execute the commands mkdir foobar and cd foobar immediately when you
 288hit PF24.  Want to see the command line first, before you execute it?
 289Use the -n option of the echo command::
 291        echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
 295Happy testing!  I welcome any and all comments about this document, the
 296driver, etc etc.
 298Dick Hitt <>