0001 ===============================
0002 IBM 3270 Display System support
0003 ===============================
0004
0005 This file describes the driver that supports local channel attachment
0006 of IBM 3270 devices. It consists of three sections:
0007
0008 * Introduction
0009 * Installation
0010 * Operation
0011
0012
0013 Introduction
0014 ============
0015
0016 This paper describes installing and operating 3270 devices under
0017 Linux/390. A 3270 device is a block-mode rows-and-columns terminal of
0018 which I'm sure hundreds of millions were sold by IBM and clonemakers
0019 twenty and thirty years ago.
0020
0021 You may have 3270s in-house and not know it. If you're using the
0022 VM-ESA operating system, define a 3270 to your virtual machine by using
0023 the command "DEF GRAF <hex-address>" This paper presumes you will be
0024 defining four 3270s with the CP/CMS commands:
0025
0026 - DEF GRAF 620
0027 - DEF GRAF 621
0028 - DEF GRAF 622
0029 - DEF GRAF 623
0030
0031 Your network connection from VM-ESA allows you to use x3270, tn3270, or
0032 another 3270 emulator, started from an xterm window on your PC or
0033 workstation. With the DEF GRAF command, an application such as xterm,
0034 and this Linux-390 3270 driver, you have another way of talking to your
0035 Linux box.
0036
0037 This paper covers installation of the driver and operation of a
0038 dialed-in x3270.
0039
0040
0041 Installation
0042 ============
0043
0044 You install the driver by installing a patch, doing a kernel build, and
0045 running the configuration script (config3270.sh, in this directory).
0046
0047 WARNING: If you are using 3270 console support, you must rerun the
0048 configuration script every time you change the console's address (perhaps
0049 by using the condev= parameter in silo's /boot/parmfile). More precisely,
0050 you should rerun the configuration script every time your set of 3270s,
0051 including the console 3270, changes subchannel identifier relative to
0052 one another. ReIPL as soon as possible after running the configuration
0053 script and the resulting /tmp/mkdev3270.
0054
0055 If you have chosen to make tub3270 a module, you add a line to a
0056 configuration file under /etc/modprobe.d/. If you are working on a VM
0057 virtual machine, you can use DEF GRAF to define virtual 3270 devices.
0058
0059 You may generate both 3270 and 3215 console support, or one or the
0060 other, or neither. If you generate both, the console type under VM is
0061 not changed. Use #CP Q TERM to see what the current console type is.
0062 Use #CP TERM CONMODE 3270 to change it to 3270. If you generate only
0063 3270 console support, then the driver automatically converts your console
0064 at boot time to a 3270 if it is a 3215.
0065
0066 In brief, these are the steps:
0067
0068 1. Install the tub3270 patch
0069 2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf`
0070 3. (If VM) define devices with DEF GRAF
0071 4. Reboot
0072 5. Configure
0073
0074 To test that everything works, assuming VM and x3270,
0075
0076 1. Bring up an x3270 window.
0077 2. Use the DIAL command in that window.
0078 3. You should immediately see a Linux login screen.
0079
0080 Here are the installation steps in detail:
0081
0082 1. The 3270 driver is a part of the official Linux kernel
0083 source. Build a tree with the kernel source and any necessary
0084 patches. Then do::
0085
0086 make oldconfig
0087 (If you wish to disable 3215 console support, edit
0088 .config; change CONFIG_TN3215's value to "n";
0089 and rerun "make oldconfig".)
0090 make image
0091 make modules
0092 make modules_install
0093
0094 2. (Perform this step only if you have configured tub3270 as a
0095 module.) Add a line to a file `/etc/modprobe.d/*.conf` to automatically
0096 load the driver when it's needed. With this line added, you will see
0097 login prompts appear on your 3270s as soon as boot is complete (or
0098 with emulated 3270s, as soon as you dial into your vm guest using the
0099 command "DIAL <vmguestname>"). Since the line-mode major number is
0100 227, the line to add should be::
0101
0102 alias char-major-227 tub3270
0103
0104 3. Define graphic devices to your vm guest machine, if you
0105 haven't already. Define them before you reboot (reipl):
0106
0107 - DEFINE GRAF 620
0108 - DEFINE GRAF 621
0109 - DEFINE GRAF 622
0110 - DEFINE GRAF 623
0111
0112 4. Reboot. The reboot process scans hardware devices, including
0113 3270s, and this enables the tub3270 driver once loaded to respond
0114 correctly to the configuration requests of the next step. If
0115 you have chosen 3270 console support, your console now behaves
0116 as a 3270, not a 3215.
0117
0118 5. Run the 3270 configuration script config3270. It is
0119 distributed in this same directory, Documentation/s390, as
0120 config3270.sh. Inspect the output script it produces,
0121 /tmp/mkdev3270, and then run that script. This will create the
0122 necessary character special device files and make the necessary
0123 changes to /etc/inittab.
0124
0125 Then notify /sbin/init that /etc/inittab has changed, by issuing
0126 the telinit command with the q operand::
0127
0128 cd Documentation/s390
0129 sh config3270.sh
0130 sh /tmp/mkdev3270
0131 telinit q
0132
0133 This should be sufficient for your first time. If your 3270
0134 configuration has changed and you're reusing config3270, you
0135 should follow these steps::
0136
0137 Change 3270 configuration
0138 Reboot
0139 Run config3270 and /tmp/mkdev3270
0140 Reboot
0141
0142 Here are the testing steps in detail:
0143
0144 1. Bring up an x3270 window, or use an actual hardware 3278 or
0145 3279, or use the 3270 emulator of your choice. You would be
0146 running the emulator on your PC or workstation. You would use
0147 the command, for example::
0148
0149 x3270 vm-esa-domain-name &
0150
0151 if you wanted a 3278 Model 4 with 43 rows of 80 columns, the
0152 default model number. The driver does not take advantage of
0153 extended attributes.
0154
0155 The screen you should now see contains a VM logo with input
0156 lines near the bottom. Use TAB to move to the bottom line,
0157 probably labeled "COMMAND ===>".
0158
0159 2. Use the DIAL command instead of the LOGIN command to connect
0160 to one of the virtual 3270s you defined with the DEF GRAF
0161 commands::
0162
0163 dial my-vm-guest-name
0164
0165 3. You should immediately see a login prompt from your
0166 Linux-390 operating system. If that does not happen, you would
0167 see instead the line "DIALED TO my-vm-guest-name 0620".
0168
0169 To troubleshoot: do these things.
0170
0171 A. Is the driver loaded? Use the lsmod command (no operands)
0172 to find out. Probably it isn't. Try loading it manually, with
0173 the command "insmod tub3270". Does that command give error
0174 messages? Ha! There's your problem.
0175
0176 B. Is the /etc/inittab file modified as in installation step 3
0177 above? Use the grep command to find out; for instance, issue
0178 "grep 3270 /etc/inittab". Nothing found? There's your
0179 problem!
0180
0181 C. Are the device special files created, as in installation
0182 step 2 above? Use the ls -l command to find out; for instance,
0183 issue "ls -l /dev/3270/tty620". The output should start with the
0184 letter "c" meaning character device and should contain "227, 1"
0185 just to the left of the device name. No such file? no "c"?
0186 Wrong major number? Wrong minor number? There's your
0187 problem!
0188
0189 D. Do you get the message::
0190
0191 "HCPDIA047E my-vm-guest-name 0620 does not exist"?
0192
0193 If so, you must issue the command "DEF GRAF 620" from your VM
0194 3215 console and then reboot the system.
0195
0196
0197
0198 OPERATION.
0199 ==========
0200
0201 The driver defines three areas on the 3270 screen: the log area, the
0202 input area, and the status area.
0203
0204 The log area takes up all but the bottom two lines of the screen. The
0205 driver writes terminal output to it, starting at the top line and going
0206 down. When it fills, the status area changes from "Linux Running" to
0207 "Linux More...". After a scrolling timeout of (default) 5 sec, the
0208 screen clears and more output is written, from the top down.
0209
0210 The input area extends from the beginning of the second-to-last screen
0211 line to the start of the status area. You type commands in this area
0212 and hit ENTER to execute them.
0213
0214 The status area initializes to "Linux Running" to give you a warm
0215 fuzzy feeling. When the log area fills up and output awaits, it
0216 changes to "Linux More...". At this time you can do several things or
0217 nothing. If you do nothing, the screen will clear in (default) 5 sec
0218 and more output will appear. You may hit ENTER with nothing typed in
0219 the input area to toggle between "Linux More..." and "Linux Holding",
0220 which indicates no scrolling will occur. (If you hit ENTER with "Linux
0221 Running" and nothing typed, the application receives a newline.)
0222
0223 You may change the scrolling timeout value. For example, the following
0224 command line::
0225
0226 echo scrolltime=60 > /proc/tty/driver/tty3270
0227
0228 changes the scrolling timeout value to 60 sec. Set scrolltime to 0 if
0229 you wish to prevent scrolling entirely.
0230
0231 Other things you may do when the log area fills up are: hit PA2 to
0232 clear the log area and write more output to it, or hit CLEAR to clear
0233 the log area and the input area and write more output to the log area.
0234
0235 Some of the Program Function (PF) and Program Attention (PA) keys are
0236 preassigned special functions. The ones that are not yield an alarm
0237 when pressed.
0238
0239 PA1 causes a SIGINT to the currently running application. You may do
0240 the same thing from the input area, by typing "^C" and hitting ENTER.
0241
0242 PA2 causes the log area to be cleared. If output awaits, it is then
0243 written to the log area.
0244
0245 PF3 causes an EOF to be received as input by the application. You may
0246 cause an EOF also by typing "^D" and hitting ENTER.
0247
0248 No PF key is preassigned to cause a job suspension, but you may cause a
0249 job suspension by typing "^Z" and hitting ENTER. You may wish to
0250 assign this function to a PF key. To make PF7 cause job suspension,
0251 execute the command::
0252
0253 echo pf7=^z > /proc/tty/driver/tty3270
0254
0255 If the input you type does not end with the two characters "^n", the
0256 driver appends a newline character and sends it to the tty driver;
0257 otherwise the driver strips the "^n" and does not append a newline.
0258 The IBM 3215 driver behaves similarly.
0259
0260 Pf10 causes the most recent command to be retrieved from the tube's
0261 command stack (default depth 20) and displayed in the input area. You
0262 may hit PF10 again for the next-most-recent command, and so on. A
0263 command is entered into the stack only when the input area is not made
0264 invisible (such as for password entry) and it is not identical to the
0265 current top entry. PF10 rotates backward through the command stack;
0266 PF11 rotates forward. You may assign the backward function to any PF
0267 key (or PA key, for that matter), say, PA3, with the command::
0268
0269 echo -e pa3=\\033k > /proc/tty/driver/tty3270
0270
0271 This assigns the string ESC-k to PA3. Similarly, the string ESC-j
0272 performs the forward function. (Rationale: In bash with vi-mode line
0273 editing, ESC-k and ESC-j retrieve backward and forward history.
0274 Suggestions welcome.)
0275
0276 Is a stack size of twenty commands not to your liking? Change it on
0277 the fly. To change to saving the last 100 commands, execute the
0278 command::
0279
0280 echo recallsize=100 > /proc/tty/driver/tty3270
0281
0282 Have a command you issue frequently? Assign it to a PF or PA key! Use
0283 the command::
0284
0285 echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
0286
0287 to execute the commands mkdir foobar and cd foobar immediately when you
0288 hit PF24. Want to see the command line first, before you execute it?
0289 Use the -n option of the echo command::
0290
0291 echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
0292
0293
0294
0295 Happy testing! I welcome any and all comments about this document, the
0296 driver, etc etc.
0297
0298 Dick Hitt <rbh00@utsglobal.com>
