Qodem Getting Started Guide (2024)

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

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

• Screen - Qodem needs at least 80 columns by 25 rows and white text on black background.
• Font - Qodem needs a Unicode font that includes both the CP437 glyphs and the DEC multinational character sets.
• Keyboard - Qodem uses several function keys that modern environments often co-opt for other functions. Qodem will respond to other keystrokes if the function keys are unavailable. Also, Qodem needs the Alt or Meta key to send a separate escape character, NOT set the 8th bit.
• Locale - Qodem needs both a Unicode locale and a non-Unicode locale to use when spawning shells and connecting to other Unix-like systems.
• Other Qodem options - the Qodem options file may need to be edited further for a specific environment.

These items each have their own detailed sections below. Most ofthese things are due to how distributions set up their terminalsdifferently from the raw Linux console. And the end is a sectiondescribing the setup I use.

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

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:

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

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

Adding a new system to the phonebook is straightforward: press theInsert key or 'I' to see the new/revise entry screen:

Use the arrow keys to navigate between fields, the status line willupdate 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 toselect the option. For this example, use the LOCAL method and X_UTF8emulation:

After you have gotten the entry set up, press F10 or Alt-Enter to savethe entry:

Press Enter again to dial the entry and it will switch to terminalmode:

In terminal mode most keystrokes are passed to the remote system (inthis case, the spawned shell). Pressing Alt-Z brings up a menu ofother keystrokes:

When ready to exit Qodem, press Alt-X while in terminal mode (orCtrl-C if Qodem is offline) to bring up the exitdialog:

When you are ready to explore more BBS systems, press 'L' in thephonebook and use arrow keys to select the Telnet BBS Guide list ofsystems:

Press Enter to load the list:

Now go telnet away and enjoy!

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

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

• Pass "-geometry 80x25" on the terminal program's command line.
• Configure the terminal through its menu interface to use 80x25 or larger.

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

• Terminus. Some VT100 line-drawing characters may be missing, but CP437 coverage is very good.
• uni_vga. This is the default Linux console font (what one gets from executing 'setfont' with no arguments). You can download uni_vga including a version converted to TrueType at this link.
• Unifont. Generally looks OK, but some of the VT100 line-drawing characters are not very pretty.
• The default font on Mac OSX Terminal.app.

Unfortunately, no single font solves the issue best. The only fontthat 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 moderndisplays. The second best is Terminus: it looks very good and is onlymissing a handful of VT100 graphics glyphs that are very rarely used.

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

• Configure the terminal through its menu interface to send the ESCape key. On Mac Terminal.app look for the option labeled "Use option as meta key" in "Preferences → Settings → Keyboard" (Leopard 10.5 / Snow Leopard 10.6) or "Window Settings → Keyboard" (Tiger 10.4).
• Use uxterm, and add these lines to ~/.Xresources:

  XTerm*eightBitInput: trueXTerm*metaSendsEscape: trueUXTerm*eightBitInput: trueUXTerm*metaSendsEscape: true

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

Locales are a complex issue for Qodem:

• The locale of the terminal/console that Qodem uses to display glyphs to the user at the keyboard MUST be UTF-8. If it isn't, Qodem will look very ugly and might not handle keyboard input correctly either.
• When Qodem connects to remote systems, the code page of those systems depends on the terminal emulation:
  • TTY, DEBUG, ANSI, Avatar, LINUX, and XTERM emulations use 8 bit characters and can have different code pages for the high-bit characters. Qodem currently supports many DOS and Windows codepages including CP437, CP850, KOI8-R/U, Windows 1250/1251/1252, ISO-8859-1, and more.
  • VT52, VT100, and VT102 emulations are defined by their standards to be 7-bit only, so only ASCII characters and DEC Special Graphics characters will be seen.
  • VT220 emulation uses 8-bit characters but has multiple defined code pages for the high-bit characters (DEC multinational characters).
  • L_UTF8 and X_UTF8 use UTF-8 encoded characters throughout.
  • ATASCII and PETSCII have custom 8-bit encodings that are not quite ASCII. PETSCII in particular also needs the C64 Pro Mono font from Style.
• When the remote system is a Unix-like system, the LANG environment variable must be set correctly to get the remote system to send either 8-bit characters or UTF-8 encoded characters.

Much of this complexity arises due to Qodem's niche: it lives betweenDOS and Unix-like systems, and uses ncurses for output and gettext fortranslation. Getting it right from scratch can be a challenge, butfortunately 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.

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

When I am in X11 I just launch xqodem, which runs Qodemin a uxterm at 80x25. But when I want a general uxterm for commandline 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.htmlxterm*foreground: rgb:a8/a8/a8xterm*background: rgb:00/00/00xterm*color0: rgb:00/00/00xterm*color1: rgb:a8/00/00xterm*color2: rgb:00/a8/00xterm*color3: rgb:a8/54/00xterm*color4: rgb:00/00/a8xterm*color5: rgb:a8/00/a8xterm*color6: rgb:00/a8/a8xterm*color7: rgb:a8/a8/a8xterm*color8: rgb:54/54/54xterm*color9: rgb:fc/54/54xterm*color10: rgb:54/fc/54xterm*color11: rgb:fc/fc/54xterm*color12: rgb:54/54/fcxterm*color13: rgb:fc/54/fcxterm*color14: rgb:54/fc/fcxterm*color15: rgb:fc/fc/fcxterm*boldMode: falsexterm*boldColors: truexterm*colorBDMode: truexterm*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 hasutf8_lang = en_US.UTF-8 andiso8859_lang = C.

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

• The latest README
  
• The qodem man page