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