Documentation/s390/3270.rst

   1 ===============================
   2 IBM 3270 Display System support
   3 ===============================
   4
   5 This file describes the driver that supports local channel attachment
   6 of IBM 3270 devices.  It consists of three sections:
   7
   8         * Introduction
   9         * Installation
  10         * Operation
  11
  12
  13 Introduction
  14 ============
  15
  16 This paper describes installing and operating 3270 devices under
  17 Linux/390.  A 3270 device is a block-mode rows-and-columns terminal of
  18 which I'm sure hundreds of millions were sold by IBM and clonemakers
  19 twenty and thirty years ago.
  20
  21 You may have 3270s in-house and not know it.  If you're using the
  22 VM-ESA operating system, define a 3270 to your virtual machine by using
  23 the command "DEF GRAF <hex-address>"  This paper presumes you will be
  24 defining four 3270s with the CP/CMS commands:
  25
  26         - DEF GRAF 620
  27         - DEF GRAF 621
  28         - DEF GRAF 622
  29         - DEF GRAF 623
  30
  31 Your network connection from VM-ESA allows you to use x3270, tn3270, or
  32 another 3270 emulator, started from an xterm window on your PC or
  33 workstation.  With the DEF GRAF command, an application such as xterm,
  34 and this Linux-390 3270 driver, you have another way of talking to your
  35 Linux box.
  36
  37 This paper covers installation of the driver and operation of a
  38 dialed-in x3270.
  39
  40
  41 Installation
  42 ============
  43
  44 You install the driver by installing a patch, doing a kernel build, and
  45 running the configuration script (config3270.sh, in this directory).
  46
  47 WARNING:  If you are using 3270 console support, you must rerun the
  48 configuration script every time you change the console's address (perhaps
  49 by using the condev= parameter in silo's /boot/parmfile).  More precisely,
  50 you should rerun the configuration script every time your set of 3270s,
  51 including the console 3270, changes subchannel identifier relative to
  52 one another.  ReIPL as soon as possible after running the configuration
  53 script and the resulting /tmp/mkdev3270.
  54
  55 If you have chosen to make tub3270 a module, you add a line to a
  56 configuration file under /etc/modprobe.d/.  If you are working on a VM
  57 virtual machine, you can use DEF GRAF to define virtual 3270 devices.
  58
  59 You may generate both 3270 and 3215 console support, or one or the
  60 other, or neither.  If you generate both, the console type under VM is
  61 not changed.  Use #CP Q TERM to see what the current console type is.
  62 Use #CP TERM CONMODE 3270 to change it to 3270.  If you generate only
  63 3270 console support, then the driver automatically converts your console
  64 at boot time to a 3270 if it is a 3215.
  65
  66 In brief, these are the steps:
  67
  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
  73
  74 To test that everything works, assuming VM and x3270,
  75
  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.
  79
  80 Here are the installation steps in detail:
  81
  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::
  85
  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
  93
  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::
 101
 102                 alias char-major-227 tub3270
 103
 104         3. Define graphic devices to your vm guest machine, if you
 105         haven't already.  Define them before you reboot (reipl):
 106
 107                 - DEFINE GRAF 620
 108                 - DEFINE GRAF 621
 109                 - DEFINE GRAF 622
 110                 - DEFINE GRAF 623
 111
 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.
 117
 118         5. Run the 3270 configuration script config3270.  It is
 119         distributed in this same directory, Documentation/s390, as
 120         config3270.sh.  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.
 124
 125         Then notify /sbin/init that /etc/inittab has changed, by issuing
 126         the telinit command with the q operand::
 127
 128                 cd Documentation/s390
 129                 sh config3270.sh
 130                 sh /tmp/mkdev3270
 131                 telinit q
 132
 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::
 136
 137                 Change 3270 configuration
 138                 Reboot
 139                 Run config3270 and /tmp/mkdev3270
 140                 Reboot
 141
 142 Here are the testing steps in detail:
 143
 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::
 148
 149                 x3270 vm-esa-domain-name &
 150
 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.
 154
 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  ===>".
 158
 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::
 162
 163                 dial my-vm-guest-name
 164
 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".
 168
 169         To troubleshoot:  do these things.
 170
 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.
 175
 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!
 180
 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!
 188
 189         D. Do you get the message::
 190
 191                  "HCPDIA047E my-vm-guest-name 0620 does not exist"?
 192
 193         If so, you must issue the command "DEF GRAF 620" from your VM
 194         3215 console and then reboot the system.
 195
 196
 197
 198 OPERATION.
 199 ==========
 200
 201 The driver defines three areas on the 3270 screen:  the log area, the
 202 input area, and the status area.
 203
 204 The log area takes up all but the bottom two lines of the screen.  The
 205 driver writes terminal output to it, starting at the top line and going
 206 down.  When it fills, the status area changes from "Linux Running" to
 207 "Linux More...".  After a scrolling timeout of (default) 5 sec, the
 208 screen clears and more output is written, from the top down.
 209
 210 The input area extends from the beginning of the second-to-last screen
 211 line to the start of the status area.  You type commands in this area
 212 and hit ENTER to execute them.
 213
 214 The status area initializes to "Linux Running" to give you a warm
 215 fuzzy feeling.  When the log area fills up and output awaits, it
 216 changes to "Linux More...".  At this time you can do several things or
 217 nothing.  If you do nothing, the screen will clear in (default) 5 sec
 218 and more output will appear.  You may hit ENTER with nothing typed in
 219 the input area to toggle between "Linux More..." and "Linux Holding",
 220 which indicates no scrolling will occur.  (If you hit ENTER with "Linux
 221 Running" and nothing typed, the application receives a newline.)
 222
 223 You may change the scrolling timeout value.  For example, the following
 224 command line::
 225
 226         echo scrolltime=60 > /proc/tty/driver/tty3270
 227
 228 changes the scrolling timeout value to 60 sec.  Set scrolltime to 0 if
 229 you wish to prevent scrolling entirely.
 230
 231 Other things you may do when the log area fills up are:  hit PA2 to
 232 clear the log area and write more output to it, or hit CLEAR to clear
 233 the log area and the input area and write more output to the log area.
 234
 235 Some of the Program Function (PF) and Program Attention (PA) keys are
 236 preassigned special functions.  The ones that are not yield an alarm
 237 when pressed.
 238
 239 PA1 causes a SIGINT to the currently running application.  You may do
 240 the same thing from the input area, by typing "^C" and hitting ENTER.
 241
 242 PA2 causes the log area to be cleared.  If output awaits, it is then
 243 written to the log area.
 244
 245 PF3 causes an EOF to be received as input by the application.  You may
 246 cause an EOF also by typing "^D" and hitting ENTER.
 247
 248 No PF key is preassigned to cause a job suspension, but you may cause a
 249 job suspension by typing "^Z" and hitting ENTER.  You may wish to
 250 assign this function to a PF key.  To make PF7 cause job suspension,
 251 execute the command::
 252
 253         echo pf7=^z > /proc/tty/driver/tty3270
 254
 255 If the input you type does not end with the two characters "^n", the
 256 driver appends a newline character and sends it to the tty driver;
 257 otherwise the driver strips the "^n" and does not append a newline.
 258 The IBM 3215 driver behaves similarly.
 259
 260 Pf10 causes the most recent command to be retrieved from the tube's
 261 command stack (default depth 20) and displayed in the input area.  You
 262 may hit PF10 again for the next-most-recent command, and so on.  A
 263 command is entered into the stack only when the input area is not made
 264 invisible (such as for password entry) and it is not identical to the
 265 current top entry.  PF10 rotates backward through the command stack;
 266 PF11 rotates forward.  You may assign the backward function to any PF
 267 key (or PA key, for that matter), say, PA3, with the command::
 268
 269         echo -e pa3=\\033k > /proc/tty/driver/tty3270
 270
 271 This assigns the string ESC-k to PA3.  Similarly, the string ESC-j
 272 performs the forward function.  (Rationale:  In bash with vi-mode line
 273 editing, ESC-k and ESC-j retrieve backward and forward history.
 274 Suggestions welcome.)
 275
 276 Is a stack size of twenty commands not to your liking?  Change it on
 277 the fly.  To change to saving the last 100 commands, execute the
 278 command::
 279
 280         echo recallsize=100 > /proc/tty/driver/tty3270
 281
 282 Have a command you issue frequently?  Assign it to a PF or PA key!  Use
 283 the command::
 284
 285         echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
 286
 287 to execute the commands mkdir foobar and cd foobar immediately when you
 288 hit PF24.  Want to see the command line first, before you execute it?
 289 Use the -n option of the echo command::
 290
 291         echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
 292
 293
 294
 295 Happy testing!  I welcome any and all comments about this document, the
 296 driver, etc etc.
 297
 298 Dick Hitt <rbh00@utsglobal.com>