Using PuTTY with OpenQM

Sep 2023.

PuTTY is a freely available telnet (or ssh) client available for both Windows and Linux environments.

By default, PuTTY reports itself to OpenQM as xterm. This means that OpenQM sets its terminal type to xterm. However, the default configuration of PuTTY does not match the OpenQM definition of xterm in the terminfo database. Therefore, you will need to play around with terminal definitions to get the best connection.

The main differences between the default PuTTY settings and the xterm definition used by OpenQM are for Function keys 1 to 4, and the keyboard arrow keys. The colour settings are also incorrect.

To fix all of these, we need to create a terminal definition for PuTTY, but we have a choice about how we do that. PuTTY has many configuration options. We need to choose whether to accept the default PuTTY configuration, or whether we configure PuTTY to be closer to xterm before creating our terminal definition. We will cover both approaches below:

Creating a PuTTY terminal definition

The OpenQM terminal definitions are contained in the file terminfo.src which can be found in the QMSYS folder (C:\QMSYS or /usr/qmsys ). Open this file using a text editor, copy the xterm definition, and save it as terminfo.mods (in the QMSYS folder).

Now edit this definition to match the following:

putty|PuTTY terminal emulator,
    am, xenl, km, mir, msgr, mc5i, bce,
    cols#80, it#8, lines#24, colors#16, pairs#64, mouse#4,
    cbt=\E[Z, bel=^G, cr=\r, csr=\E[%i%p1%d;%p2%dr, tbc=\E[3g, clear=\E[H\E[2J,
    el=\E[K, ed=\E[J, hpa=\E[%i%p1%dG, cup=\E[%i%p1%d;%p2%dH, cud1=\n,
    home=\E[H, civis=\E[?25l, cub1=\b, cnorm=\E[?25h, cuf1=\E[C, cuu1=\E[A,
    cvvis=\E[?25h, dch1=\E[P, dl1=\E[M, smacs=^N, blink=\E[5m, bold=\E[1m,
    smcup=\E[?1048h\E[?1047h, smir=\E[4h, invis=\E[8m, rev=\E[7m, smso=\E[7m,
    smul=\E[4m, ech=\E[%p1%dX, rmacs=^O, sgr0=\E[m^O, rmcup=\E[?1047l\E[?1048l,
    rmir=\E[4l, rmso=\E[27m, rmul=\E[24m, flash=\E[?5h\E[?5l,
    is2=\E[!p\E[?3;4l\E[4l\E>, il1=\E[L, kbs=\177, kdch1=\E[3~, kcud1=\E[B,
    kf1=\EOP, kf10=\E[21~, kf2=\EOQ, kf3=\EOR, kf4=\EOS, kf5=\E[15~,
    kf6=\E[17~, kf7=\E[18~, kf8=\E[19~, kf9=\E[20~, khome=\E[1~, kich1=\E[2~,
    kcub1=\E[D, knp=\E[6~, kpp=\E[5~, kcuf1=\E[C, kcuu1=\E[A, rmkx=\E[?1l\E>,
    smkx=\E[?1h\E=, dch=\E[%p1%dP, dl=\E[%p1%dM, cud=\E[%p1%dB, ich=\E[%p1%d@,
    il=\E[%p1%dL, cub=\E[%p1%dD, cuf=\E[%p1%dC, cuu=\E[%p1%dA, mc0=\E[i,
    mc4=\E[4i, mc5=\E[5i, rs1=\Ec, rs2=\E[!p\E[?3;4l\E[4l\E>, rc=\E8,
    vpa=\E[%i%p1%dd, sc=\E7, ind=\n, ri=\EM,
    hts=\EH, ht=\t, ka1=\EOw, ka3=\EOu, kb2=\EOy, kc1=\EOq, kc3=\EOs,
    smam=\E[?7h, rmam=\E[?7l, enacs=\E(B\E)0, kbeg=\EOE, kend=\E[4~, kent=\EOM,
    kf11=\E[23~, kf12=\E[24~, kf13=\E[25~, kf14=\E[26~, kf15=\E[28~,
    kf16=\E[29~, kf17=\E[31~, kf18=\E[32~, kf19=\E[33~, kf20=\E[34~, el1=\E[1K,
    u6=\E[%i%d;%dR, u7=\E[6n, op=\E[39;49m,
    kmous=\E[M, setaf=\E[3%p1%dm, setab=\E[4%p1%dm

The changes from the standard xterm definition have been bolded.

These changes update the arrow key definitions recognised by OpenQM to those used by PuTTY. It also updates the setting of foreground and background colours.

You may find that you need to make further amendments to this item (see the OpenQM help to find the structure of items in the terminfo database) if you find some keys do not work as expected.

Save your new terminfo.mods item. Now, compile it using the qmtic utility:

Open a command prompt in the QMSYS folder, and type the following:

./bin/qmtic -p/usr/qmsys/terminfo -v -x terminfo.mods

Or, if you are using Windows:

.\bin\qmtic -pC:\QMSYS\terminfo -v -x terminfo.mods

This will create an an entry named putty in the terminfo database. Note that this command will NOT overwrite an existing entry because we have included the -x option.

Changing the PuTTY configuration

The PuTTY configuration options are detailed in the documentation. We want to look particularly at the Function key settings.

The important option here is to use the Xterm R6 setting that changes the response of the F1 to F4 keys to match those used in the OpenQM xterm definition.

Configure PuTTY as follows:

  • Under Session set the connection type to Telnet and the port to whatever port OpenQM is using (4242 by default)
  • Under Terminal > Keyboard set the 'Function keys and keypad' to Xterm R6
  • Under Window set columns and rows to match your usual TERM settings (particularly if these have been changed from the OpenQM defaults in the LOGIN paragraph)
    • The Windows version of PuTTY also has a setting here to control what happens when you resize the window. Set this to Change the size of the font
  • Set the lines of scrollback to something reasonably large (say 10,000)
  • Under Translation, you may want to change the character set
  • Under Fonts you may want to change the display font
  • Under Data’ change the ‘Terminal-type string’ to putty
  • Back on Session, set a name for the session details (say QM) in the Saved Sessions edit box and click on Save.

When you connect using these settings, PuTTY identifies itself as putty (from the Data setting), and OpenQM will automatically select the putty terminal definition that we created. If you run the TERM command after logging in you should see something like this:

Screen width : 132
Screen depth : 35
Printer width: 1000
Printer depth: 32000
Terminal type: putty

This shows that OpenQM has correctly selected the putty terminal definition, and applied the other settings from our LOGIN paragraph.

If you find that some keys to not work correctly, you will need to update the terminal definition. Before we do this, we need to find out what codes are being sent by the keys that are not working as you expect. OpenQM makes this task reasonably straightforward.

Once you have logged in, type:


Now press a key on the keyboard. OpenQM will show you the codes being sent to the database, and give you the string that you need to enter into the terminfo definition to match the codes being sent. For example, here is the Right Arrow key:

5B    [
43    C
Terminfo: \E[C

OpenQM remains in this query mode until you press the spacebar.

Once you have the keycodes you need, update the terminfo.mods item you created with your new key codes; delete the old compiled version of putty; and then re-compile the terminfo.mods item. Finally, try your new terminal definition to see if it works properly.

Alternate configuration

If you want to use the default keyboard configuration in PuTTY (meaning that the 'Function keys and keypad' setting is left at ESC[n~ ), then you will need to make some additional changes to the terminfo.mods definition for PuTTY.

Open your terminfo.mods item, and replace the line that starts with kf1= to read:

    kf1=\E[11~, kf10=\E[21~, kf2=\E[12~, kf3=\E[13~, kf4=\E[14~, kf5=\E[15~,

Once again, the changes from the standard definition have been bolded.

Save these changes, delete any existing terminal definition for PuTTY in the database, and compile the terminfo.mods item using the command above.