Qodem : About | Downloads | Screenshots | Getting Started | GitHub Project Page | SourceForge Project Page

Preface

In many Unix-like environments the terminal/command-line defaults are very different from the systems Qodem and Qmodem were originally designed to communicate with. These issues are described in detail below. Qodem has programmatic solutions to most of these issues, however one issue remains important: the text version of Qodem needs a good font to look right.

Introduction

Qodem strives to be faithful to the DOS-based Qmodem, however computers have changed significantly since the days of DOS. This guide is meant to help make a new user's experience with Qodem better.

Getting Qodem to work well on a stock Linux or Mac installation involves checking several things:

These items each have their own detailed sections below. Most of these things are due to how distributions set up their terminals differently from the raw Linux console. And the end is a section describing the setup I use.

But assuming that everything is set up well, how should Qodem work on its first run? That is the subject of the next section.

First Run

When Qodem runs for the first time, it will do several things:

  1. It will create several directories. On Unix-like systems, these are ~/.qodem, ~/.qodem/scripts, ~/qodem, and ~/qodem/host; on Windows, these are My Documents\qodem\prefs, My Documents\qodem\host, and My Documents\qodem\script. These directories are used to store configuration files, user-generated and Quicklearn-generated scripts, downloaded files, and host mode messages and files.
  2. On Unix-like systems, it will also create a FIFO (named pipe file) at ~/.qodem/scripts/script.stderr. This file is used to route a script's stderr stream to the display.
  3. Qodem will populate ~/.qodem with several files, including the Qodem options file (~/.qodem/qodemrc or My Documents\qodem\prefs\qodemrc.txt). The options file is a plain text file and can be edited by hand or by typing Alt-N in terminal mode. Blank lines and lines beginning with '#' are ignored. Every option has a description and a default value. If the options file is deleted, it will be re-created with defaults the next time Qodem runs.

Qodem will start in the phonebook screen:
Phonebook Initial
Image

The bottom line shows the status line. This line updates through most of the Qodem screens to provide hints on which actions are available.

Qodem populates its first phonebook with an entry for the local system, several bulletin boards, and some other terminal systems. From this point you can navigate to an entry and press Enter to connect.

Adding a new system to the phonebook is straightforward: press the Insert key or 'I' to see the new/revise entry screen:
Phonebook New Entry Image

Use the arrow keys to navigate between fields, the status line will update with each field. Some fields require selecting from a list, press F2 or the space bar to bring up the list and F10 or Enter to select the option. For this example, use the LOCAL method and X_UTF8 emulation:
Phonebook Entry Filled In Image

After you have gotten the entry set up, press F10 or Alt-Enter to save the entry:
Phonebook Saved Entry Image

Press Enter again to dial the entry and it will switch to terminal mode:
TERMINAL Mode Image

In terminal mode most keystrokes are passed to the remote system (in this case, the spawned shell). Pressing Alt-Z brings up a menu of other keystrokes:
TERMINAL Mode Menu Image

When ready to exit Qodem, press Alt-X while in terminal mode (or Ctrl-C if Qodem is offline) to bring up the exit dialog:
Exit Dialog Image

When you are ready to explore more BBS systems, press 'L' in the phonebook and use arrow keys to select the Telnet BBS Guide list of systems:
Phonebook Load File Dialog Image

Press Enter to load the list:
Phonebook Telnet BBS Guide Fonebook Image

Now go telnet away and enjoy!

Colors

If you would like to change Qodem's colors, edit the colors.cfg file in the preferences directory. The original Qmodem(tm) 5.0 themes are all present, simply remove the '#' to uncomment those lines. See below for shots of the Purple, Red, and Custom themes.

Qodem sporting Qmodem 5.0's Purple theme

Qodem sporting Qmodem 5.0's Red theme

Qodem sporting Qmodem 5.0's Custom theme

Screen

Qodem needs at least 80 columns by 25 rows (80x25). Most X11 terminals are configured for 80x24 by default and will need to be changed. Several options are available:

Font

Qodem requires a Unicode font that includes glyphs from the CP437 and DEC multinational character sets. Some good fonts to use are:

Unfortunately, no single font solves the issue best. The only font that seems to have every needed glyph and looks very good is uni_vga, however uni_vga can be small-and-sharp or larger-and-blurry on modern displays. The second best is Terminus: it looks very good and is only missing a handful of VT100 graphics glyphs that are very rarely used.

Keyboard

Qodem needs the keyboard to send the ESCape character for the Alt/Meta key. Many X11 terminals are configured for the Alt/Meta key to set the 8th bit by default and will need to be changed. Several options are available:

You can verify that the Alt/Meta key is sending ESCape by running 'cat' in the shell and typing Alt-X, you should see multiple characters (typically ^[x, maybe ←x) instead of one.

Locale

Locales are a complex issue for Qodem:

Much of this complexity arises due to Qodem's niche: it lives between DOS and Unix-like systems, and uses ncurses for output and gettext for translation. Getting it right from scratch can be a challenge, but fortunately the various distributions have made this much easier.

The most straightforward way to handle locales is:

  1. Ensure you are running a UTF-8 locale by checking the LANG environment variable in your shell. It should have "UTF-8" in the value somewhere, e.g. "en_US.UTF-8" .
  2. Edit qodemrc (or qodemrc.txt) and ensure that the value for utf8_lang matches your LANG environment variable value.
  3. qodemrc also has a iso8859_lang value that defaults to "C" (no translation). You can put another value here as long as it does NOT contain UTF-8, e.g. "en_US". If you get warnings about 'setlocale' then either leave it as "C" or try to add the locale to your system. On Debian, you can run 'dpkg-reconfigure locales' to add support for an 8-bit locale.

My Setup

Right now I run Qodem on Debian with the following packages installed: xfonts-terminus, xfonts-terminus-dos, and xterm.

When I am in X11 I just launch xqodem, which runs Qodem in a uxterm at 80x25. But when I want a general uxterm for command line work, I launch uxterm using this shell script:

#!/bin/bash

# uni_vga font
# This font has complete coverage of every glyph and looks great, but
# it is a bit small on large displays.  160x80 on a 1280x800 display.
# exec uxterm -fn -bolkhov-vga-medium-r-normal--16-160-75-75-c-80-iso10646-1

# Terminus font
# This font is small but can cram close to 160x80 on a 1280x800
# display.  It is only missing one unusual VT100 special graphics
# glyph.
# exec uxterm -fn -xos4-terminus-medium-r-normal--16-160-72-72-c-80-iso10646-1 -fg white -bg black

# Terminus font
# This font is very nice sized on my 17'' 1280x1024 display at 128x40
# characters.  It is only missing a couple of VT100 line drawing
# glyphs.
exec uxterm -fn -xos4-terminus-medium-r-normal--20-200-72-72-c-100-iso10646-1 -fg white -bg black

My ~/.Xresources looks like this:

! XTerm configuration to reproduce DOS colors.
! Credits to Emil Mikulic at http://dmr.ath.cx/notes/xterm.html
xterm*foreground: rgb:a8/a8/a8
xterm*background: rgb:00/00/00
xterm*color0: rgb:00/00/00
xterm*color1: rgb:a8/00/00
xterm*color2: rgb:00/a8/00
xterm*color3: rgb:a8/54/00
xterm*color4: rgb:00/00/a8
xterm*color5: rgb:a8/00/a8
xterm*color6: rgb:00/a8/a8
xterm*color7: rgb:a8/a8/a8
xterm*color8: rgb:54/54/54
xterm*color9: rgb:fc/54/54
xterm*color10: rgb:54/fc/54
xterm*color11: rgb:fc/fc/54
xterm*color12: rgb:54/54/fc
xterm*color13: rgb:fc/54/fc
xterm*color14: rgb:54/fc/fc
xterm*color15: rgb:fc/fc/fc
xterm*boldMode: false
xterm*boldColors: true
xterm*colorBDMode: true
xterm*colorBD: rgb:fc/fc/fc

I ran 'dpkg-reconfigure locales' and selected both 'en_US.UTF-8' and 'en_US' . My LANG environment variable is set to 'en_US.UTF-8'. My ~/.qodem/qodemrc has utf8_lang = en_US.UTF-8 and iso8859_lang = C.

More Resources

For more information on how Qodem is meant to work, refer to any of these: