About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / s390 / 3270.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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 a
51	configuration file under /etc/modprobe.d/.  If you are working on a VM
52	virtual machine, you 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 a file in /etc/modprobe.d/*.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 a file /etc/modprobe.d/*.conf to automatically
88		load the driver when it's needed.  With this line added, you will see
89		login prompts appear on your 3270s as soon as boot is complete (or
90		with emulated 3270s, as soon as you dial into your vm guest using the
91		command "DIAL <vmguestname>").  Since the line-mode major number is
92		227, the line to add should be:
93			alias char-major-227 tub3270
94	
95		3. Define graphic devices to your vm guest machine, if you
96		haven't already.  Define them before you reboot (reipl):
97			DEFINE GRAF 620
98			DEFINE GRAF 621
99			DEFINE GRAF 622
100			DEFINE GRAF 623
101	
102		4. Reboot.  The reboot process scans hardware devices, including
103		3270s, and this enables the tub3270 driver once loaded to respond
104		correctly to the configuration requests of the next step.  If
105		you have chosen 3270 console support, your console now behaves
106		as a 3270, not a 3215.
107	
108		5. Run the 3270 configuration script config3270.  It is
109		distributed in this same directory, Documentation/s390, as
110		config3270.sh.	Inspect the output script it produces,
111		/tmp/mkdev3270, and then run that script.  This will create the
112		necessary character special device files and make the necessary
113		changes to /etc/inittab.
114	
115		Then notify /sbin/init that /etc/inittab has changed, by issuing
116		the telinit command with the q operand:
117			cd Documentation/s390
118			sh config3270.sh
119			sh /tmp/mkdev3270
120			telinit q
121	
122		This should be sufficient for your first time.	If your 3270
123		configuration has changed and you're reusing config3270, you
124		should follow these steps:
125			Change 3270 configuration
126			Reboot
127			Run config3270 and /tmp/mkdev3270
128			Reboot
129	
130	Here are the testing steps in detail:
131	
132		1. Bring up an x3270 window, or use an actual hardware 3278 or
133		3279, or use the 3270 emulator of your choice.  You would be
134		running the emulator on your PC or workstation.  You would use
135		the command, for example,
136			x3270 vm-esa-domain-name &
137		if you wanted a 3278 Model 4 with 43 rows of 80 columns, the
138		default model number.  The driver does not take advantage of
139		extended attributes.
140	
141		The screen you should now see contains a VM logo with input
142		lines near the bottom.  Use TAB to move to the bottom line,
143		probably labeled "COMMAND  ===>".
144	
145		2. Use the DIAL command instead of the LOGIN command to connect
146		to one of the virtual 3270s you defined with the DEF GRAF
147		commands:
148			dial my-vm-guest-name
149	
150		3. You should immediately see a login prompt from your
151		Linux-390 operating system.  If that does not happen, you would
152		see instead the line "DIALED TO my-vm-guest-name   0620".
153	
154		To troubleshoot:  do these things.
155	
156		A. Is the driver loaded?  Use the lsmod command (no operands)
157		to find out.  Probably it isn't.  Try loading it manually, with
158		the command "insmod tub3270".  Does that command give error
159		messages?  Ha!  There's your problem.
160	
161		B. Is the /etc/inittab file modified as in installation step 3
162		above?  Use the grep command to find out; for instance, issue
163		"grep 3270 /etc/inittab".  Nothing found?  There's your
164		problem!
165	
166		C. Are the device special files created, as in installation
167		step 2 above?  Use the ls -l command to find out; for instance,
168		issue "ls -l /dev/3270/tty620".  The output should start with the
169		letter "c" meaning character device and should contain "227, 1"
170		just to the left of the device name.  No such file?  no "c"?
171		Wrong major number?  Wrong minor number?  There's your
172		problem!
173	
174		D. Do you get the message
175			 "HCPDIA047E my-vm-guest-name 0620 does not exist"?
176		If so, you must issue the command "DEF GRAF 620" from your VM
177		3215 console and then reboot the system.
178	
179	
180	
181	OPERATION.
182	
183	The driver defines three areas on the 3270 screen:  the log area, the
184	input area, and the status area.
185	
186	The log area takes up all but the bottom two lines of the screen.  The
187	driver writes terminal output to it, starting at the top line and going
188	down.  When it fills, the status area changes from "Linux Running" to
189	"Linux More...".  After a scrolling timeout of (default) 5 sec, the
190	screen clears and more output is written, from the top down.
191	
192	The input area extends from the beginning of the second-to-last screen
193	line to the start of the status area.  You type commands in this area
194	and hit ENTER to execute them.
195	
196	The status area initializes to "Linux Running" to give you a warm
197	fuzzy feeling.  When the log area fills up and output awaits, it
198	changes to "Linux More...".  At this time you can do several things or
199	nothing.  If you do nothing, the screen will clear in (default) 5 sec
200	and more output will appear.  You may hit ENTER with nothing typed in
201	the input area to toggle between "Linux More..." and "Linux Holding",
202	which indicates no scrolling will occur.  (If you hit ENTER with "Linux
203	Running" and nothing typed, the application receives a newline.)
204	
205	You may change the scrolling timeout value.  For example, the following
206	command line:
207		echo scrolltime=60 > /proc/tty/driver/tty3270
208	changes the scrolling timeout value to 60 sec.  Set scrolltime to 0 if
209	you wish to prevent scrolling entirely.
210	
211	Other things you may do when the log area fills up are:  hit PA2 to
212	clear the log area and write more output to it, or hit CLEAR to clear
213	the log area and the input area and write more output to the log area.
214	
215	Some of the Program Function (PF) and Program Attention (PA) keys are
216	preassigned special functions.  The ones that are not yield an alarm
217	when pressed.
218	
219	PA1 causes a SIGINT to the currently running application.  You may do
220	the same thing from the input area, by typing "^C" and hitting ENTER.
221	
222	PA2 causes the log area to be cleared.  If output awaits, it is then
223	written to the log area.
224	
225	PF3 causes an EOF to be received as input by the application.  You may
226	cause an EOF also by typing "^D" and hitting ENTER.
227	
228	No PF key is preassigned to cause a job suspension, but you may cause a
229	job suspension by typing "^Z" and hitting ENTER.  You may wish to
230	assign this function to a PF key.  To make PF7 cause job suspension,
231	execute the command:
232		echo pf7=^z > /proc/tty/driver/tty3270
233	
234	If the input you type does not end with the two characters "^n", the
235	driver appends a newline character and sends it to the tty driver;
236	otherwise the driver strips the "^n" and does not append a newline.
237	The IBM 3215 driver behaves similarly.
238	
239	Pf10 causes the most recent command to be retrieved from the tube's
240	command stack (default depth 20) and displayed in the input area.  You
241	may hit PF10 again for the next-most-recent command, and so on.  A
242	command is entered into the stack only when the input area is not made
243	invisible (such as for password entry) and it is not identical to the
244	current top entry.  PF10 rotates backward through the command stack;
245	PF11 rotates forward.  You may assign the backward function to any PF
246	key (or PA key, for that matter), say, PA3, with the command:
247		echo -e pa3=\\033k > /proc/tty/driver/tty3270
248	This assigns the string ESC-k to PA3.  Similarly, the string ESC-j
249	performs the forward function.  (Rationale:  In bash with vi-mode line
250	editing, ESC-k and ESC-j retrieve backward and forward history.
251	Suggestions welcome.)
252	
253	Is a stack size of twenty commands not to your liking?  Change it on
254	the fly.  To change to saving the last 100 commands, execute the
255	command:
256		echo recallsize=100 > /proc/tty/driver/tty3270
257	
258	Have a command you issue frequently?  Assign it to a PF or PA key!  Use
259	the command
260		echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270 
261	to execute the commands mkdir foobar and cd foobar immediately when you
262	hit PF24.  Want to see the command line first, before you execute it?
263	Use the -n option of the echo command:
264		echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
265	
266	
267	
268	Happy testing!  I welcome any and all comments about this document, the
269	driver, etc etc.
270	
271	Dick Hitt <rbh00@utsglobal.com>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog