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