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 51/etc/modprobe.conf. If you are working on a VM virtual machine, you 52can 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 /etc/modprobe.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 /etc/modprobe.conf to automatically 88 load the driver when it's needed. With this line added, 89 you will see login prompts appear on your 3270s as soon as 90 boot is complete (or with emulated 3270s, as soon as you dial 91 into your vm guest using the command "DIAL <vmguestname>"). 92 Since the line-mode major number is 227, the line to add to 93 /etc/modprobe.conf should be: 94 alias char-major-227 tub3270 95 96 3. Define graphic devices to your vm guest machine, if you 97 haven't already. Define them before you reboot (reipl): 98 DEFINE GRAF 620 99 DEFINE GRAF 621 100 DEFINE GRAF 622 101 DEFINE GRAF 623 102 103 4. Reboot. The reboot process scans hardware devices, including 104 3270s, and this enables the tub3270 driver once loaded to respond 105 correctly to the configuration requests of the next step. If 106 you have chosen 3270 console support, your console now behaves 107 as a 3270, not a 3215. 108 109 5. Run the 3270 configuration script config3270. It is 110 distributed in this same directory, Documentation/s390, as 111 config3270.sh. Inspect the output script it produces, 112 /tmp/mkdev3270, and then run that script. This will create the 113 necessary character special device files and make the necessary 114 changes to /etc/inittab. 115 116 Then notify /sbin/init that /etc/inittab has changed, by issuing 117 the telinit command with the q operand: 118 cd Documentation/s390 119 sh config3270.sh 120 sh /tmp/mkdev3270 121 telinit q 122 123 This should be sufficient for your first time. If your 3270 124 configuration has changed and you're reusing config3270, you 125 should follow these steps: 126 Change 3270 configuration 127 Reboot 128 Run config3270 and /tmp/mkdev3270 129 Reboot 130 131Here are the testing steps in detail: 132 133 1. Bring up an x3270 window, or use an actual hardware 3278 or 134 3279, or use the 3270 emulator of your choice. You would be 135 running the emulator on your PC or workstation. You would use 136 the command, for example, 137 x3270 vm-esa-domain-name & 138 if you wanted a 3278 Model 4 with 43 rows of 80 columns, the 139 default model number. The driver does not take advantage of 140 extended attributes. 141 142 The screen you should now see contains a VM logo with input 143 lines near the bottom. Use TAB to move to the bottom line, 144 probably labeled "COMMAND ===>". 145 146 2. Use the DIAL command instead of the LOGIN command to connect 147 to one of the virtual 3270s you defined with the DEF GRAF 148 commands: 149 dial my-vm-guest-name 150 151 3. You should immediately see a login prompt from your 152 Linux-390 operating system. If that does not happen, you would 153 see instead the line "DIALED TO my-vm-guest-name 0620". 154 155 To troubleshoot: do these things. 156 157 A. Is the driver loaded? Use the lsmod command (no operands) 158 to find out. Probably it isn't. Try loading it manually, with 159 the command "insmod tub3270". Does that command give error 160 messages? Ha! There's your problem. 161 162 B. Is the /etc/inittab file modified as in installation step 3 163 above? Use the grep command to find out; for instance, issue 164 "grep 3270 /etc/inittab". Nothing found? There's your 165 problem! 166 167 C. Are the device special files created, as in installation 168 step 2 above? Use the ls -l command to find out; for instance, 169 issue "ls -l /dev/3270/tty620". The output should start with the 170 letter "c" meaning character device and should contain "227, 1" 171 just to the left of the device name. No such file? no "c"? 172 Wrong major number? Wrong minor number? There's your 173 problem! 174 175 D. Do you get the message 176 "HCPDIA047E my-vm-guest-name 0620 does not exist"? 177 If so, you must issue the command "DEF GRAF 620" from your VM 178 3215 console and then reboot the system. 179 180 181 182OPERATION. 183 184The driver defines three areas on the 3270 screen: the log area, the 185input area, and the status area. 186 187The log area takes up all but the bottom two lines of the screen. The 188driver writes terminal output to it, starting at the top line and going 189down. When it fills, the status area changes from "Linux Running" to 190"Linux More...". After a scrolling timeout of (default) 5 sec, the 191screen clears and more output is written, from the top down. 192 193The input area extends from the beginning of the second-to-last screen 194line to the start of the status area. You type commands in this area 195and hit ENTER to execute them. 196 197The status area initializes to "Linux Running" to give you a warm 198fuzzy feeling. When the log area fills up and output awaits, it 199changes to "Linux More...". At this time you can do several things or 200nothing. If you do nothing, the screen will clear in (default) 5 sec 201and more output will appear. You may hit ENTER with nothing typed in 202the input area to toggle between "Linux More..." and "Linux Holding", 203which indicates no scrolling will occur. (If you hit ENTER with "Linux 204Running" and nothing typed, the application receives a newline.) 205 206You may change the scrolling timeout value. For example, the following 207command line: 208 echo scrolltime=60 > /proc/tty/driver/tty3270 209changes the scrolling timeout value to 60 sec. Set scrolltime to 0 if 210you wish to prevent scrolling entirely. 211 212Other things you may do when the log area fills up are: hit PA2 to 213clear the log area and write more output to it, or hit CLEAR to clear 214the log area and the input area and write more output to the log area. 215 216Some of the Program Function (PF) and Program Attention (PA) keys are 217preassigned special functions. The ones that are not yield an alarm 218when pressed. 219 220PA1 causes a SIGINT to the currently running application. You may do 221the same thing from the input area, by typing "^C" and hitting ENTER. 222 223PA2 causes the log area to be cleared. If output awaits, it is then 224written to the log area. 225 226PF3 causes an EOF to be received as input by the application. You may 227cause an EOF also by typing "^D" and hitting ENTER. 228 229No PF key is preassigned to cause a job suspension, but you may cause a 230job suspension by typing "^Z" and hitting ENTER. You may wish to 231assign this function to a PF key. To make PF7 cause job suspension, 232execute the command: 233 echo pf7=^z > /proc/tty/driver/tty3270 234 235If the input you type does not end with the two characters "^n", the 236driver appends a newline character and sends it to the tty driver; 237otherwise the driver strips the "^n" and does not append a newline. 238The IBM 3215 driver behaves similarly. 239 240Pf10 causes the most recent command to be retrieved from the tube's 241command stack (default depth 20) and displayed in the input area. You 242may hit PF10 again for the next-most-recent command, and so on. A 243command is entered into the stack only when the input area is not made 244invisible (such as for password entry) and it is not identical to the 245current top entry. PF10 rotates backward through the command stack; 246PF11 rotates forward. You may assign the backward function to any PF 247key (or PA key, for that matter), say, PA3, with the command: 248 echo -e pa3=\\033k > /proc/tty/driver/tty3270 249This assigns the string ESC-k to PA3. Similarly, the string ESC-j 250performs the forward function. (Rationale: In bash with vi-mode line 251editing, ESC-k and ESC-j retrieve backward and forward history. 252Suggestions welcome.) 253 254Is a stack size of twenty commands not to your liking? Change it on 255the fly. To change to saving the last 100 commands, execute the 256command: 257 echo recallsize=100 > /proc/tty/driver/tty3270 258 259Have a command you issue frequently? Assign it to a PF or PA key! Use 260the command 261 echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270 262to execute the commands mkdir foobar and cd foobar immediately when you 263hit PF24. Want to see the command line first, before you execute it? 264Use the -n option of the echo command: 265 echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270 266 267 268 269Happy testing! I welcome any and all comments about this document, the 270driver, etc etc. 271 272Dick Hitt <rbh00@utsglobal.com> 273