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