]>
Commit | Line | Data |
---|---|---|
8b4a503d | 1 | =============================== |
1da177e4 | 2 | IBM 3270 Display System support |
8b4a503d | 3 | =============================== |
1da177e4 LT |
4 | |
5 | This file describes the driver that supports local channel attachment | |
6 | of IBM 3270 devices. It consists of three sections: | |
8b4a503d | 7 | |
1da177e4 LT |
8 | * Introduction |
9 | * Installation | |
10 | * Operation | |
11 | ||
12 | ||
8b4a503d MCC |
13 | Introduction |
14 | ============ | |
1da177e4 LT |
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 | |
8b4a503d | 24 | defining four 3270s with the CP/CMS commands: |
1da177e4 | 25 | |
8b4a503d MCC |
26 | - DEF GRAF 620 |
27 | - DEF GRAF 621 | |
28 | - DEF GRAF 622 | |
29 | - DEF GRAF 623 | |
1da177e4 LT |
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 | ||
8b4a503d MCC |
41 | Installation |
42 | ============ | |
1da177e4 LT |
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 | ||
970e2486 LDM |
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. | |
1da177e4 LT |
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: | |
8b4a503d | 67 | |
1da177e4 | 68 | 1. Install the tub3270 patch |
8b4a503d | 69 | 2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf` |
1da177e4 LT |
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, | |
8b4a503d | 75 | |
1da177e4 LT |
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 | |
8b4a503d MCC |
84 | patches. Then do:: |
85 | ||
1da177e4 LT |
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 | |
8b4a503d | 95 | module.) Add a line to a file `/etc/modprobe.d/*.conf` to automatically |
970e2486 LDM |
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 | |
8b4a503d MCC |
100 | 227, the line to add should be:: |
101 | ||
1da177e4 LT |
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): | |
8b4a503d MCC |
106 | |
107 | - DEFINE GRAF 620 | |
108 | - DEFINE GRAF 621 | |
109 | - DEFINE GRAF 622 | |
110 | - DEFINE GRAF 623 | |
1da177e4 LT |
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 | |
8b4a503d | 120 | config3270.sh. Inspect the output script it produces, |
1da177e4 LT |
121 | /tmp/mkdev3270, and then run that script. This will create the |
122 | necessary character special device files and make the necessary | |
bf6ee0ae | 123 | changes to /etc/inittab. |
1da177e4 LT |
124 | |
125 | Then notify /sbin/init that /etc/inittab has changed, by issuing | |
8b4a503d MCC |
126 | the telinit command with the q operand:: |
127 | ||
1da177e4 LT |
128 | cd Documentation/s390 |
129 | sh config3270.sh | |
130 | sh /tmp/mkdev3270 | |
131 | telinit q | |
132 | ||
8b4a503d | 133 | This should be sufficient for your first time. If your 3270 |
1da177e4 | 134 | configuration has changed and you're reusing config3270, you |
8b4a503d MCC |
135 | should follow these steps:: |
136 | ||
1da177e4 LT |
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 | |
8b4a503d MCC |
147 | the command, for example:: |
148 | ||
1da177e4 | 149 | x3270 vm-esa-domain-name & |
8b4a503d | 150 | |
1da177e4 LT |
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 | |
8b4a503d MCC |
161 | commands:: |
162 | ||
1da177e4 LT |
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 | ||
8b4a503d MCC |
189 | D. Do you get the message:: |
190 | ||
1da177e4 | 191 | "HCPDIA047E my-vm-guest-name 0620 does not exist"? |
8b4a503d | 192 | |
1da177e4 LT |
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. | |
8b4a503d | 199 | ========== |
1da177e4 LT |
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 | |
8b4a503d MCC |
224 | command line:: |
225 | ||
1da177e4 | 226 | echo scrolltime=60 > /proc/tty/driver/tty3270 |
8b4a503d | 227 | |
1da177e4 LT |
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, | |
8b4a503d MCC |
251 | execute the command:: |
252 | ||
1da177e4 LT |
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 | |
8b4a503d MCC |
267 | key (or PA key, for that matter), say, PA3, with the command:: |
268 | ||
1da177e4 | 269 | echo -e pa3=\\033k > /proc/tty/driver/tty3270 |
8b4a503d | 270 | |
1da177e4 LT |
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 | |
8b4a503d MCC |
278 | command:: |
279 | ||
1da177e4 LT |
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 | |
8b4a503d MCC |
283 | the command:: |
284 | ||
285 | echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270 | |
286 | ||
1da177e4 LT |
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? | |
8b4a503d MCC |
289 | Use the -n option of the echo command:: |
290 | ||
1da177e4 LT |
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> |