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