aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/s390/3270.txt
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
commit1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch)
tree0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/s390/3270.txt
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
Diffstat (limited to 'Documentation/s390/3270.txt')
-rw-r--r--Documentation/s390/3270.txt274
1 files changed, 274 insertions, 0 deletions
diff --git a/Documentation/s390/3270.txt b/Documentation/s390/3270.txt
new file mode 100644
index 000000000000..0a044e647d2d
--- /dev/null
+++ b/Documentation/s390/3270.txt
@@ -0,0 +1,274 @@
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. 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
133Here 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
184OPERATION.
185
186The driver defines three areas on the 3270 screen: the log area, the
187input area, and the status area.
188
189The log area takes up all but the bottom two lines of the screen. The
190driver writes terminal output to it, starting at the top line and going
191down. When it fills, the status area changes from "Linux Running" to
192"Linux More...". After a scrolling timeout of (default) 5 sec, the
193screen clears and more output is written, from the top down.
194
195The input area extends from the beginning of the second-to-last screen
196line to the start of the status area. You type commands in this area
197and hit ENTER to execute them.
198
199The status area initializes to "Linux Running" to give you a warm
200fuzzy feeling. When the log area fills up and output awaits, it
201changes to "Linux More...". At this time you can do several things or
202nothing. If you do nothing, the screen will clear in (default) 5 sec
203and more output will appear. You may hit ENTER with nothing typed in
204the input area to toggle between "Linux More..." and "Linux Holding",
205which indicates no scrolling will occur. (If you hit ENTER with "Linux
206Running" and nothing typed, the application receives a newline.)
207
208You may change the scrolling timeout value. For example, the following
209command line:
210 echo scrolltime=60 > /proc/tty/driver/tty3270
211changes the scrolling timeout value to 60 sec. Set scrolltime to 0 if
212you wish to prevent scrolling entirely.
213
214Other things you may do when the log area fills up are: hit PA2 to
215clear the log area and write more output to it, or hit CLEAR to clear
216the log area and the input area and write more output to the log area.
217
218Some of the Program Function (PF) and Program Attention (PA) keys are
219preassigned special functions. The ones that are not yield an alarm
220when pressed.
221
222PA1 causes a SIGINT to the currently running application. You may do
223the same thing from the input area, by typing "^C" and hitting ENTER.
224
225PA2 causes the log area to be cleared. If output awaits, it is then
226written to the log area.
227
228PF3 causes an EOF to be received as input by the application. You may
229cause an EOF also by typing "^D" and hitting ENTER.
230
231No PF key is preassigned to cause a job suspension, but you may cause a
232job suspension by typing "^Z" and hitting ENTER. You may wish to
233assign this function to a PF key. To make PF7 cause job suspension,
234execute the command:
235 echo pf7=^z > /proc/tty/driver/tty3270
236
237If the input you type does not end with the two characters "^n", the
238driver appends a newline character and sends it to the tty driver;
239otherwise the driver strips the "^n" and does not append a newline.
240The IBM 3215 driver behaves similarly.
241
242Pf10 causes the most recent command to be retrieved from the tube's
243command stack (default depth 20) and displayed in the input area. You
244may hit PF10 again for the next-most-recent command, and so on. A
245command is entered into the stack only when the input area is not made
246invisible (such as for password entry) and it is not identical to the
247current top entry. PF10 rotates backward through the command stack;
248PF11 rotates forward. You may assign the backward function to any PF
249key (or PA key, for that matter), say, PA3, with the command:
250 echo -e pa3=\\033k > /proc/tty/driver/tty3270
251This assigns the string ESC-k to PA3. Similarly, the string ESC-j
252performs the forward function. (Rationale: In bash with vi-mode line
253editing, ESC-k and ESC-j retrieve backward and forward history.
254Suggestions welcome.)
255
256Is a stack size of twenty commands not to your liking? Change it on
257the fly. To change to saving the last 100 commands, execute the
258command:
259 echo recallsize=100 > /proc/tty/driver/tty3270
260
261Have a command you issue frequently? Assign it to a PF or PA key! Use
262the command
263 echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
264to execute the commands mkdir foobar and cd foobar immediately when you
265hit PF24. Want to see the command line first, before you execute it?
266Use the -n option of the echo command:
267 echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
268
269
270
271Happy testing! I welcome any and all comments about this document, the
272driver, etc etc.
273
274Dick Hitt <rbh00@utsglobal.com>