• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1===============================
2IBM 3270 Display System support
3===============================
4
5This file describes the driver that supports local channel attachment
6of IBM 3270 devices.  It consists of three sections:
7
8	* Introduction
9	* Installation
10	* Operation
11
12
13Introduction
14============
15
16This paper describes installing and operating 3270 devices under
17Linux/390.  A 3270 device is a block-mode rows-and-columns terminal of
18which I'm sure hundreds of millions were sold by IBM and clonemakers
19twenty and thirty years ago.
20
21You may have 3270s in-house and not know it.  If you're using the
22VM-ESA operating system, define a 3270 to your virtual machine by using
23the command "DEF GRAF <hex-address>"  This paper presumes you will be
24defining four 3270s with the CP/CMS commands:
25
26	- DEF GRAF 620
27	- DEF GRAF 621
28	- DEF GRAF 622
29	- DEF GRAF 623
30
31Your network connection from VM-ESA allows you to use x3270, tn3270, or
32another 3270 emulator, started from an xterm window on your PC or
33workstation.  With the DEF GRAF command, an application such as xterm,
34and this Linux-390 3270 driver, you have another way of talking to your
35Linux box.
36
37This paper covers installation of the driver and operation of a
38dialed-in x3270.
39
40
41Installation
42============
43
44You install the driver by installing a patch, doing a kernel build, and
45running the configuration script (config3270.sh, in this directory).
46
47WARNING:  If you are using 3270 console support, you must rerun the
48configuration script every time you change the console's address (perhaps
49by using the condev= parameter in silo's /boot/parmfile).  More precisely,
50you should rerun the configuration script every time your set of 3270s,
51including the console 3270, changes subchannel identifier relative to
52one another.  ReIPL as soon as possible after running the configuration
53script and the resulting /tmp/mkdev3270.
54
55If you have chosen to make tub3270 a module, you add a line to a
56configuration file under /etc/modprobe.d/.  If you are working on a VM
57virtual machine, you can use DEF GRAF to define virtual 3270 devices.
58
59You may generate both 3270 and 3215 console support, or one or the
60other, or neither.  If you generate both, the console type under VM is
61not changed.  Use #CP Q TERM to see what the current console type is.
62Use #CP TERM CONMODE 3270 to change it to 3270.  If you generate only
633270 console support, then the driver automatically converts your console
64at boot time to a 3270 if it is a 3215.
65
66In brief, these are the steps:
67
68	1. Install the tub3270 patch
69	2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf`
70	3. (If VM) define devices with DEF GRAF
71	4. Reboot
72	5. Configure
73
74To test that everything works, assuming VM and x3270,
75
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
80Here 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
84	patches.  Then do::
85
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
95	module.)  Add a line to a file `/etc/modprobe.d/*.conf` to automatically
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
100	227, the line to add should be::
101
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):
106
107		- DEFINE GRAF 620
108		- DEFINE GRAF 621
109		- DEFINE GRAF 622
110		- DEFINE GRAF 623
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
120	config3270.sh.  Inspect the output script it produces,
121	/tmp/mkdev3270, and then run that script.  This will create the
122	necessary character special device files and make the necessary
123	changes to /etc/inittab.
124
125	Then notify /sbin/init that /etc/inittab has changed, by issuing
126	the telinit command with the q operand::
127
128		cd Documentation/s390
129		sh config3270.sh
130		sh /tmp/mkdev3270
131		telinit q
132
133	This should be sufficient for your first time.  If your 3270
134	configuration has changed and you're reusing config3270, you
135	should follow these steps::
136
137		Change 3270 configuration
138		Reboot
139		Run config3270 and /tmp/mkdev3270
140		Reboot
141
142Here 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
147	the command, for example::
148
149		x3270 vm-esa-domain-name &
150
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
161	commands::
162
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
189	D. Do you get the message::
190
191		 "HCPDIA047E my-vm-guest-name 0620 does not exist"?
192
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
198OPERATION.
199==========
200
201The driver defines three areas on the 3270 screen:  the log area, the
202input area, and the status area.
203
204The log area takes up all but the bottom two lines of the screen.  The
205driver writes terminal output to it, starting at the top line and going
206down.  When it fills, the status area changes from "Linux Running" to
207"Linux More...".  After a scrolling timeout of (default) 5 sec, the
208screen clears and more output is written, from the top down.
209
210The input area extends from the beginning of the second-to-last screen
211line to the start of the status area.  You type commands in this area
212and hit ENTER to execute them.
213
214The status area initializes to "Linux Running" to give you a warm
215fuzzy feeling.  When the log area fills up and output awaits, it
216changes to "Linux More...".  At this time you can do several things or
217nothing.  If you do nothing, the screen will clear in (default) 5 sec
218and more output will appear.  You may hit ENTER with nothing typed in
219the input area to toggle between "Linux More..." and "Linux Holding",
220which indicates no scrolling will occur.  (If you hit ENTER with "Linux
221Running" and nothing typed, the application receives a newline.)
222
223You may change the scrolling timeout value.  For example, the following
224command line::
225
226	echo scrolltime=60 > /proc/tty/driver/tty3270
227
228changes the scrolling timeout value to 60 sec.  Set scrolltime to 0 if
229you wish to prevent scrolling entirely.
230
231Other things you may do when the log area fills up are:  hit PA2 to
232clear the log area and write more output to it, or hit CLEAR to clear
233the log area and the input area and write more output to the log area.
234
235Some of the Program Function (PF) and Program Attention (PA) keys are
236preassigned special functions.  The ones that are not yield an alarm
237when pressed.
238
239PA1 causes a SIGINT to the currently running application.  You may do
240the same thing from the input area, by typing "^C" and hitting ENTER.
241
242PA2 causes the log area to be cleared.  If output awaits, it is then
243written to the log area.
244
245PF3 causes an EOF to be received as input by the application.  You may
246cause an EOF also by typing "^D" and hitting ENTER.
247
248No PF key is preassigned to cause a job suspension, but you may cause a
249job suspension by typing "^Z" and hitting ENTER.  You may wish to
250assign this function to a PF key.  To make PF7 cause job suspension,
251execute the command::
252
253	echo pf7=^z > /proc/tty/driver/tty3270
254
255If the input you type does not end with the two characters "^n", the
256driver appends a newline character and sends it to the tty driver;
257otherwise the driver strips the "^n" and does not append a newline.
258The IBM 3215 driver behaves similarly.
259
260Pf10 causes the most recent command to be retrieved from the tube's
261command stack (default depth 20) and displayed in the input area.  You
262may hit PF10 again for the next-most-recent command, and so on.  A
263command is entered into the stack only when the input area is not made
264invisible (such as for password entry) and it is not identical to the
265current top entry.  PF10 rotates backward through the command stack;
266PF11 rotates forward.  You may assign the backward function to any PF
267key (or PA key, for that matter), say, PA3, with the command::
268
269	echo -e pa3=\\033k > /proc/tty/driver/tty3270
270
271This assigns the string ESC-k to PA3.  Similarly, the string ESC-j
272performs the forward function.  (Rationale:  In bash with vi-mode line
273editing, ESC-k and ESC-j retrieve backward and forward history.
274Suggestions welcome.)
275
276Is a stack size of twenty commands not to your liking?  Change it on
277the fly.  To change to saving the last 100 commands, execute the
278command::
279
280	echo recallsize=100 > /proc/tty/driver/tty3270
281
282Have a command you issue frequently?  Assign it to a PF or PA key!  Use
283the command::
284
285	echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
286
287to execute the commands mkdir foobar and cd foobar immediately when you
288hit PF24.  Want to see the command line first, before you execute it?
289Use the -n option of the echo command::
290
291	echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
292
293
294
295Happy testing!  I welcome any and all comments about this document, the
296driver, etc etc.
297
298Dick Hitt <rbh00@utsglobal.com>
299