qodem

NAME

qodem − Qodem Terminal Emulator

SYNOPSIS

qodem [ −−capfile FILENAME ]

[ −−logfile FILENAME ]
[ −−keyfile FILENAME ]
[ −−xl8file FILENAME ]
[ −−xlufile FILENAME ]
[ −−scrfile FILENAME ]
[ −−config FILENAME ]
[ −−create−config FILENAME ]
[ −−dotqodem−dir DIRNAME ]
[ −x | −−exit−on−completion ]
[ −−doorway MODE ]
[ −−codepage CODEPAGE ]
[ −−emulation EMULATION ]
[ −−status−line { on | off } ]
[ −−play MUSIC ]
[ −−play−exit ]
[ −−read−only ]
[ −−geometry COLSxROWS ]
[ [ −−xterm ] |
[ [ −−dial n ] |
[ [ −−connect HOST [ −−connect−method method ]
[ −−username name ] ] |

args... ]

qodem −−version
qodem [ −−help | −h | −? ]

DESCRIPTION

Qodem is an open−source clone implementation of the popular DOS−based Qmodem serial communications program. Qodem incorporates many features that are useful on several kinds of text−based consoles such as scrollback buffer, session capture, screen dump, dialing directory, and also includes serial port handling and modem dialing.

The major features of Qodem are:

* Unicode display: translation of CP437 (PC VGA), VT100 DEC Special
Graphics characters, VT220 National Replacement Character sets,
etc., to Unicode

* Terminal interface conveniences: scrollback buffer, capture file,
screen dump, dialing directory, keyboard macros, script support

* Connection methods: serial, local shell, command line, telnet,
ssh, rlogin, raw socket

* Emulations: ANSI, Avatar, VT52, VT100/102, VT220, Linux, XTerm,
PETSCII (Commodore), and ATASCII (Atari).

* Transfer protocols: Xmodem, Ymodem, Zmodem, and Kermit

OPTIONS

−−capfile FILENAME

Capture the entire session and save to FILENAME.

−−logfile FILENAME

Start the session log and log to FILENAME.

−−keyfile FILENAME

Load keyboard macros from FILENAME.

−−xl8file FILENAME

Load 8-bit translate tables from FILENAME.

−−xlufile FILENAME

Load Unicode translate tables from FILENAME.

−−scrfile FILENAME

Start script FILENAME after connect.

−−config FILENAME

Load options from FILENAME (only).

−−create−config FILENAME

Write a new options file to FILENAME and exit.

−−dotqodem−dir DIRNAME

Use DIRNAME instead of $HOME/.qodem for config/data files.

−−read−only

Disable all writes to disk. No config files will be saved, downloads are disabled, scripts are disabled, no screen dump, capture, logging, etc.

−x −−exit−on−completion

Exit after connection/command finishes.

−−doorway MODE

Select doorway MODE. Valid values for MODE are "doorway", "mixed", and "off".

−−codepage CODEPAGE

Select codepage CODEPAGE. See Alt−; list for valid codepages. Example: "CP437", "CP850", "Windows−1252", etc.

−−emulation EMULATION

Select emulation EMULATION. Valid values are "ansi", "avatar", "debug", "vt52", "vt100", "vt102", "vt220", "linux", "l_utf8", "xterm", "x_utf8", "petscii", and "atascii".

−−status−line { on | off }

If "on" enable status line. If "off" disable status line.

−−play MUSIC

Play the MUSIC string as ANSI Music. For more information on ANSI Music, see http://www.textfiles.com/artscene/ansimusic/, or the GWBASIC PLAY statement.

−−play−exit

If −−play was specified, exit immediately after playing MUSIC.

−−geometry COLSxROWS

Request text window size COLS x ROWS.

−−dial n

Immediately open a connection to the phone book entry number n. The first phone book entry has n=1.

−−connect HOST

Immediately open a connection to HOST. The default connection method is "ssh" unless specified with the −−connect−method option.

−−connect−method METHOD

Use METHOD to connect for the −−connect option. Valid values are "ssh", "rlogin", "telnet", "socket", and "shell".

−−username USERNAME

Use USERNAME when connecting with the −−connect option. This value is passed on the command line to ssh, and rlogin.

−−xterm

Enables X11 terminal mode: phonebook and serial port are disabled, status line is turned off at startup, doorway is set to MIXED mode, a shell is opened, and Qodem exits when the shell session exits.

args...

Spawn a local shell and pass args to it.

−−version

Display program version and brief public domain dedication statement.

−−help, −h, −?

Display usage screen.

TERMINAL REQUIREMENTS

Qodem requires the following characteristics of its shell/terminal:

* Unicode capability. The raw Linux console, UXTerm, URxvt,
Konsole, and gnome-terminal all work well.

* A Unicode font that includes the CP437 (PC VGA) glyphs.

* The meta key must use escape prefixing rather than setting the 8th
bit on the character. Many terminal emulators do this by
default. Qodem sends an xterm escape sequence to enable this
behavior. For XTerm, this can be enabled by clicking
CTRL−Mouse1 (left button) and checking "Meta Sends Escape", or by
adding the following lines to ~/.Xresources:
XTerm*metaSendsEscape: true
UXTerm*metaSendsEscape: true

CONNECTION METHODS

Qodem supports the following connection methods:

CMDLINE

Spawns the command line in a pseudo-tty.

EMULATIONS

Emulations supported by Qodem and their status follows. Note that TTY, DEBUG, ANSI.SYS, AVATAR, LINUX, and XTERM emulations can be set to CP437 (DOS VGA), ISO−8859−1, CP720 (DOS Arabic), CP737 (DOS Greek), CP775 (DOS Baltic Rim), CP850 (DOS West European), CP852 (DOS Central European), CP857 (DOS Turkish), CP858 (DOS West European+Euro), CP860 (DOS Portuguese), CP862 (DOS Hebrew), CP863 (DOS Quebecois), CP866 (DOS Cyrillic), Windows−1250 (Central/East European), Windows−1251 (Cyrillic), Windows−1252 (West European), KOI8−R (Russian), and KOI8−U (Ukrainian).

When 8−bit characters are used (see Alt−; Codepage below), the C0 control characters (0x00 − 0x1F, 0x7F) are mapped to the equivalent CP437 glyphs when there are no glyphs defined in that range for the set codepage.

PETSCII

This very loosely emulates a 40-column Commodore 64/128. Colors are not quite right due to the IBM CGA colors being unable to match the Commodore colors. Uppercase/lowercase affect new characters rather than the whole screen. This emulation requires the C64 Pro Mono font from Style, available at http://style64.org/c64-truetype/ . (Note that this font is only licensed to software packages that are "freely provided to end users". Entities wishing to ship packages that are not "freely provided to end users" will need to either remove this font, or negotiate a separate license agreement by contacting Style at http://style64.org/contact-style .)

ATASCII

This emulates the 8-bit Atari 400/800 series.

FILE TRANSFER PROTOCOLS

Protocols supported by Qodem and their status follows:

INTERFACE

Phone Book
When Qodem first starts up, by default it will start in the phone book. The menu on the bottom half of the screen lists the various actions available. When editing a phone book entry, the status line will change to show options for each field. Connecting to a system or leaving the phone book puts Qodem in Terminal Mode.

Terminal Mode
Terminal Mode is the main Qodem terminal emulator interface. Alt−Z will bring up a help menu. While in Terminal Mode the following actions are supported:
Alt−D Phone Book

This brings up the phone book.

Alt−G Term Emulation

This brings up a menu to select the terminal emulation. Selecting the active terminal emulation will prompt to reset the emulation state; this may be useful to recover from corrupted escape sequences.

Alt−C Clear Screen

This clears the screen and homes the cursor.

Alt−F Execute Script

This prompts for a filename, and then executes that file as a script. Any program that reads from standard input and writes to standard output can be run as a script. See the section below on script support.

Alt−K Send BREAK

When connected via serial mode or modem, this calls tcsendbreak() to send a true "Break Signal" on the serial line.

Alt−P Capture File

Enable/disable capture to file. Four capture formats are supported: "raw", "normal", "html", and "ask". "Raw" format saves every byte as received from the other side before emulation processing; "normal" saves UTF−8 characters after emulation processing; "html" saves in HTML format with Unicode entities and color attributes after emulation processing; "ask" will bring up a dialog to select which format to use every time capture is enabled. ASCII file transfers will be included in the capture file; other file transfers (Xmodem, Ymodem, Zmodem, Kermit) are excluded from the capture file.

Alt−S Split Screen

This actives split screen mode, in which local characters are accumulated in a buffer before sending to the remote side. To send carriage return, enter "^M".

Alt−T Screen Dump

This prompts for a filename, and then saves the current view to that file. Three screen dump formats are supported: "normal", "html", and "ask". "normal" saves UTF−8 characters after emulation processing; "html" saves in HTML format with Unicode entities and color attributes after emulation processing; "ask" will bring up a dialog to select which format to use every time the screen is dumped.

Alt−Y COM Parameters

This brings up a menu to alter the serial port settings.

PgUp Upload Files

This brings up the file upload menu. Note that CTRL−PgUp and ALT−PgUp may also work depending on the terminfo for the host terminal.

PgDn Download Files

This brings up the file download menu. Note that CTRL−PgDn and ALT−PgDn may also work depending on the terminfo for the host terminal.

Alt−\ Alt Code Key

This brings up a dialog to enter the 3−digit decimal value (0−255) for an 8−bit byte or a 4−digit hexadecimal value (0−ffff) for a 16−bit Unicode character (L_UTF8 and X_UTF8 only).

Alt−; Codepage

This brings up a dialog to change the current codepage. Codepages are limited by the current emulation. VT52, VT100, VT102, VT220, L_UTF8, X_UTF8, PETSCII, and ATASCII have their own codepage; LINUX, XTERM, ANSI, AVATAR, TTY, and DEBUG emulations can be set to: CP437 (VGA), ISO−8859−1, CP720 (Arabic), CP737 (Greek), CP775 (Baltic Rim), CP850 (Western European), CP852 (Central European), CP857 (Turkish), CP858 (Western European with euro), CP860 (Portuguese), CP862 (Hebrew), CP863 (Quebec French), CP866 (Cyrillic), CP1250 (Central/Eastern European), CP1251 (Cyrillic), CP1252 (Western European), KOI8_R (Russian),and KOI8_U (Ukrainian).

Alt−/ Scroll Back

This selects the scrollback buffer. When viewing the buffer, "S" saves to file and "C" clears the scrollback buffer. By default Qodem supports up to 20000 lines of scrollback; this can be changed by editing scrollback_max in scrollback.c. Three scrollback save formats are supported: "normal", "html", and "ask". "normal" saves UTF−8 characters after emulation processing; "html" saves in HTML format with Unicode entities and color attributes after emulation processing; "ask" will bring up a dialog to select which format to use every time the scrollback is saved.

Alt−H Hangup/Close

This hangs up the modem (drops DTR) or closes the remote connection (kills the child process).

Alt−L Log View

This brings the session log up in an editor. The session log stores information about connect, disconnect, and file upload/download events.

Alt−M Mail Reader

This spawns the mail reader, by default mm.

Alt−X Exit Qodem

This prompts to exit Qodem. When not connected, Ctrl−C will also bring up the exit prompt.

Alt−A Translate Tables

This brings up the translate tables editor. Both incoming and outgoing bytes can be changed or stripped (set to ASCII NUL (0)). Note that 8-bit INPUT translation occurs before both emulation processing and UTF−8 decoding. Unicode INPUT translation occurs before code points are written to the scrollback buffer; Unicode OUTPUT translation occurs after code points are read from the keyboard.

Alt−J Function Keys

This brings up the keyboard macro editor. Keyboard macros support substitutions for control characters including carriage return ("^M"), the phone book entry username ("$USERNAME"), and the phone book entry password ("$PASSWORD").

Alt−N Configuration

This brings the qodemrc options file up in an editor.

Alt−: Colors

This brings the colors.cfg colors file up in an editor.

Alt−O Modem Config

This brings up the modem configuration dialog.

Alt−R OS Shell

This spawns a system shell.

Alt−V View File

This brings up a prompt to view a file in an editor.

Alt−W List Directory

This brings up a directory listing.

Alt−0 Session Log

This toggles the session log on or off.

Alt−1 XON/XOFF Flow Ctrl

When connected via modem or serial port, this toggles XON/XOFF on or off.

Alt−2 Backspace/Del Mode

This selects whether the backspace key on the keyboard sends an ASCII backspace (^H) or an ASCII DEL (127) character. Alt−\ 0 0 8 can always be used to send true backspace; Alt−\ 1 2 7 can be used to send true DEL. Note that VT220 emulation always sends DEL when the backspace key is pressed.

Alt−3 Line Wrap

This toggles line wrap mode on or off. When line wrap mode is enabled, if a character is received when the cursor is at the right margin it will wrap to the first column of the next line.

Alt−4 Display NULL

This selects whether ASCII NUL (0) will be displayed as a blank/space or stripped.

Alt−5 Host Mode

This switches Qodem into Host Mode.

Alt−6 Batch Entry Window

This brings up the list of upload files used by Ymodem, Zmodem, and Kermit uploads.

Alt−7 Status Line Info

This selects between two formats for the status line.

Alt−8 Hi−Bit Strip

This selects whether or not to clear the 8th bit of all incoming bytes. Note that high−bit stripping occurs before both emulation processing and UTF−8 decoding.

Alt−9 Serial Port

This opens or closes the serial port. If already connected to a non−serial/modem remote host, this does nothing.

Alt−B Beeps & Bells

This toggles beep support on or off. When beep support is on, beeps from the remote host will be played by Qodem. In LINUX emulation, Qodem supports setting the tone and duration of the beep as specified in console−codes(4).

Alt−E Half/Full Duplex

This toggles between half and full duplex.

Alt−I Qodem Information

This displays the Qodem splash screen which includes the version and build date.

Alt−U Scrollback Record

This selects whether or not lines that scroll off the top of the screen will be saved to the scrollback buffer.

Alt−= Doorway Mode

This selects between three doorway modes: "Doorway OFF", "Doorway MIXED" and "Doorway FULL". When doorway mode is "Doorway OFF", terminal mode responds to all of its command keys as described in this section. When doorway mode is "Doorway FULL", all Alt− command keystrokes except Alt−= are passed to the remote side. When doorway mode is "Doorway MIXED", terminal mode supports a few commands but passes the majority of Alt− command keystrokes to the remote side. The default commands supported in "Doorway MIXED" mode are:
Alt−D Phone Book
Alt−P Capture
Alt−T Screen Dump
Alt−Y COM Parameters
Alt−Z Menu
Alt−/ Scrollback
Alt−PgUp or Ctrl−PgUp Upload Files
Alt−PgDn or Ctrl−PgDn Download Files

Alt−− Status Lines

This toggles the status line on or off.

Alt−+ CR/CRLF Mode

This toggles whether or not received carriage returns imply line feed or not.

Alt−, ANSI Music

This toggles ANSI music support on or off.

UNICODE SUPPORT

Qodem supports Unicode (UTF−8 encoding only) in the following functions only: keyboard macros; phone book entries (NAME, USERNAME, and PASSWORD); modem device name.

UTF−8 is NOT supported in filenames, modem strings, and remote addresses.

SCRIPT SUPPORT

Qodem does not have its own scripting language. Instead, any program that reads and writes to the standard input and output can be run as a Qodem script:

* Characters sent from the remote connection are visible to the
script in its standard input.

* Characters the script emits to its standard output are passed on
the remote connection.

* Messages to the standard error are reported to the user and also
recorded in the session log.

Since scripts are communicating with the remote system and not Qodem itself, they are unable to script Qodem’s behavior, e.g. change the terminal emulation, hangup and dial another phone book entry, download a file, etc. However, they can be written in any language, and they can be tested outside Qodem.

Scripts replace the user, and as such have similar constraints:

* Script standard input, output, and error must all be in UTF−8 encoding.

* Scripts should send carriage return (0x0D, or \r) instead of new
line (0x0A, or \n) to the remote side − the same as if a user
pressed the Enter key. They should expect to see either bare
carriage return (0x0D, or \r) or carriage return followed by
newline (0x0D 0x0A, or \r\n) from the remote side.

* Input and output translate byte translation (the Alt−A Translate Tables) are honored for scripts.

* While a script is running:
− Zmodem and Kermit autostart are disabled.
− Keyboard function key macros are disabled.
− Qodem functions accessed through the Alt−character
combinations and PgUp/PgDn are unavailable.
− Pressing Alt−P will pause the script.

* While a script is paused:
− The script will receive nothing on its standard input.
− Anything in the script’s standard output will be held until
the script is resumed.
− The script process will not be signaled; it may continue
running in its own process.
− The only Alt−character function recognized is AltP to
resume the script. All other Alt− keys will be ignored.
− Keys pressed will be sent directly to the remote system.
− Keyboard function key macros will work.

Scripts are launched in two ways:

* In TERMINAL mode, press Alt−F and enter the script filename. The
script will start immediately.

* In the phone book, add a script filename to a phone book entry.
The script will start once that entry is connected.

Script command−line arguments can be passed directly in both the Alt−F script dialog and the phone book linked script field. For example, pressing Alt−F and entering "my_script.pl arg1" will launch my_script.pl and with its first command−line argument ($ARGV[0] in Perl) set to "arg1".

ENVIRONMENT VARIABLES

Qodem makes use of the following variables:

ESCDELAY

This is a timeout value in milliseconds used by the ncurses get_wch() and wget_wch() functions to determine if a user pressed bare ESCAPE. On some systems pressing ESCAPE may require up to a full second before Qodem can process it. For Qodem backtick (’) can be used instead of ESCAPE.

FILES

$HOME/.qodem/qodemrc

Qodem options/configuration file. Inline comments describe the options.

SEE ALSO

xqodem(1), mm(1), kermit(1), gkermit(1), minicom(1), rlogin(1), ssh(1), telnet(1), xterm(1), vttest(1), console−codes(4)

BUGS

The screensaver might not load under all circumstances even after the timeout has passed.

HOMEPAGE

The Qodem homepage is at <http://qodem.sourceforge.net>. The code repository is hosted at <https://gitlab.com/AutumnMeowMeow/qodem>.

PUBLIC DOMAIN NOTICE

Written 2003−2017 by Autumn Lamonte

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.