1qodem(1) General Commands Manual qodem(1)
2
3
4
6 qodem - Qodem Terminal Emulator
7
8
10 qodem [ --enable-capture FILENAME ]
11 [ [ --connect HOST [ --connect-method method ]
12 [ --username name ] ] |
13 args... ]
14
15
16 qodem [ --help | -h | -? ]
17
18
20 Qodem is an open-source clone implementation of the popular DOS-based
21 Qmodem serial communications program. Qodem incorporates many features
22 that are useful on all kinds of text-based consoles such as scrollback
23 buffer, session capture, screen dump, dialing directory, and also
24 includes serial port handling and modem dialing.
25
26 The major features of Qodem are:
27
28 * Unicode display: translation of CP437 (PC VGA), VT100 DEC Special
29 Graphics characters, VT220 National Replacement Character sets,
30 etc., to Unicode
31
32 * Terminal interface conveniences: scrollback buffer, capture file,
33 screen dump, dialing directory, keyboard macros, script support
34
35 * Connection methods: serial, local shell, command line, telnet,
36 ssh, rlogin, rsh
37
38 * Emulations: ANSI, Avatar, VT52, VT100/102, VT220, Linux, and XTerm
39
40 * Transfer protocols: Xmodem, Ymodem, Zmodem, and Kermit
41
42
44 Qodem requires the following characteristics of its shell/terminal:
45
46 * Unicode capability. The raw Linux console, UXTerm, URxvt,
47 Konsole, and gnome-terminal all work well.
48
49 * A Unicode font that includes the CP437 (PC VGA) glyphs.
50
51 * The meta key must use escape prefixing rather than setting the 8th
52 bit on the character. Many terminal emulators do this by
53 default. Qodem sends an xterm escape sequence to enable this
54 behavior. For XTerm, this can be enabled by clicking
55 CTRL-Mouse1 (left button) and checking "Meta Sends Escape", or by
56 adding the following lines to ~/.Xresources:
57 XTerm*metaSendsEscape: true
58 UXTerm*metaSendsEscape: true
59
60
62 Emulations supported by Qodem and their status follows. Note that TTY,
63 DEBUG, ANSI.SYS, AVATAR, LINUX, and XTERM emulations can use both CP437
64 (PC VGA) and ISO-8859-1 glyphs for 8-bit characters (see Alt-; Codepage
65 below). If ISO-8859-1 is used, the C0 control characters (0x00 - 0x1F)
66 are mapped to the equivalent CP437 glyphs since there are no glyphs
67 defined in that range for ISO-8859-1.
68
69 ANSI This is the DOS-based "ANSI.SYS" emulation plus a few more codes
70 than the original ANSI.SYS. It supports DSR 6 (Cursor Position)
71 which many BBSes used to "autodetect" ANSI, and the following
72 ANSI X3.64 functions: ICH, DCH, IL, DL, VPA, CHA, CHT, and REP.
73 It also supports "ANSI Music" sequences that follow the "PLAY"
74 command syntax; it plays these tones via SDL.
75
76 AVATAR This is the BBS-era Avatar ("Advanced Video Attribute Terminal
77 Assembler and Recreator") emulation. It supports all of the
78 "Extended AVT/0" commands as per George A. Stanislav's 1 May
79 1989 document except for transmitting PC keyboard scan codes.
80 It also includes ANSI fallback capability.
81
82 VT52 Fairly complete. Does not support HOLD SCREEN mode. Graphics
83 mode glyphs that do not have direct Unicode equivalents render
84 as a hatch.
85
86 VT100 Identical to VT102 except in how it responds to Device
87 Attributes function.
88
89 VT102 Fairly complete. Double-width characters are not displayed with
90 wide glyhps due to curses-based output. Does not support smooth
91 scrolling, printing, keyboard locking, keyboard leds, and hard‐
92 ware tests. Many numeric keypad characters also do not work
93 correctly due to console NUM LOCK handling. 132-column output
94 is only supported if the host console / window is already 132
95 columns or wider; Qodem does not issue resize commands to the
96 host console for 80/132 column switching codes.
97
98 VT220 Fairly complete. Converts National Replacement Character sets
99 and DEC Supplemental Graphics characters to Unicode. In addi‐
100 tion to limitations of VT102, also the following features are
101 not supported: user-defined keys (DECUDK), downloadable fonts
102 (DECDLD), VT100/ANSI compatibility mode (DECSCL).
103
104 TTY This emulation supports bare control character handling
105 (backspace, newline, etc.) and litte else. Characters that
106 would be overwritten with underscores are instead made under‐
107 lined as old teletypes would do.
108
109 DEBUG This emulation displays all incoming characters in a format sim‐
110 ilar to a hex dump.
111
112 LINUX This emulation has two modes: PC VGA (LINUX) and UTF-8 (L_UTF8).
113 This emulation is similar to VT102 but also recognizes the Linux
114 private mode sequences and ECMA-48 sequences VPA, CNL, CPL, ECH,
115 CHA, VPA, VPR, and HPA. In addition to VT102 limitations, also
116 the following features are not supported: selecting ISO 646/ISO
117 8859-1/UTF-8 character sets, X11 mouse reporting.
118
119 XTERM This emulation has two modes: PC VGA (XTERM) and UTF-8 (X_UTF8).
120 It is mostly identical to LINUX but also recognizes a few XTerm
121 sequences and discards them to maintain a clean display. It
122 does not support many of the features unique to XTerm such as
123 Tektronix 4014 mode, mouse tracking, alternate screen buffer,
124 and many more.
125
126
128 Protocols supported by Qodem and their status follows:
129
130 XMODEM Supports original Xmodem, Xmodem-1k, Xmodem-CRC16, and Xmodem-G.
131 Also supports "Xmodem Relaxed", a variant of original Xmodem
132 with longer timeouts.
133
134 YMODEM Supports Ymodem and Ymodem-G. If a file exists, it will be
135 appended to.
136
137 ZMODEM Supports resume (crash recovery) and auto-start. Does not yet
138 support changing block size on errors, so transfers over unreli‐
139 able serial/modem connections might incur significant perfor‐
140 mance penalties.
141
142 KERMIT Supports the original robust (slow) Kermit plus streaming and
143 autostart. On reliable connections with streaming it should
144 perform reasonably well. Does not yet support long or
145 extra-long packets, RESEND/REGET, server mode, or sliding win‐
146 dows.
147
148
150 Phonebook
151 When qodem first starts up, by default it will start in the phonebook.
152 The menu on the bottom half of the screen lists the various actions
153 available. When editing a phonebook entry, the status line will change
154 to show options for each field. Connecting to a system or leaving the
155 phonebook puts qodem in Terminal Mode.
156
157 Terminal Mode
158 Terminal Mode is the main qodem terminal emulator interface. Alt-Z
159 will bring up a help menu. While in Terminal Mode the following
160 actions are supported:
161
162 Alt-D Phonebook
163 This brings up the phonebook.
164
165 Alt-G Term Emulation
166 This brings up a menu to select the terminal emulation. Select‐
167 ing the active terminal emulation will prompt to reset the emu‐
168 lation state; this may be useful to recover from corrupted
169 escape sequences.
170
171 Alt-C Clear Screen
172 This clears the screen and homes the cursor.
173
174 Alt-F Execute Script
175 This prompts for a filename, and then executes that file as a
176 script. Any program that reads from standard input and writes
177 to standard output can be run as a script. See the section
178 below on script support.
179
180 Alt-K Send BREAK
181 When connected via serial mode or modem, this calls tcsend‐
182 break() to send a true "Break Signal" on the serial line.
183
184 Alt-P Capture File
185 Enable/disable capture to file. Three capture formats are sup‐
186 ported: "raw", "text", and "html". "Raw" format saves every
187 byte as received from the other side before emulation process‐
188 ing; "text" saves UTF-8 characters after emulation processing;
189 "html" saves in HTML format with Unicode entities and color
190 attributes after emulation processing. ASCII file transfers
191 will be included in the capture file; other file transfers (Xmo‐
192 dem, Ymodem, Zmodem, Kermit) are excluded from the capture file.
193
194 Alt-S Split Screen
195 This actives split screen mode, in which local characters are
196 accumulated in a buffer before sending to the remote side. To
197 send carriage return, enter "^M".
198
199 Alt-T Screen Dump
200 This prompts for a filename, and then saves the current view to
201 that file.
202
203 Alt-Y COM Parameters
204 This brings up a menu to alter the serial port settings.
205
206 PgUp Upload Files
207 This brings up the file upload menu. Note that CTRL-PgUp and
208 ALT-PgUp may also work depending on the terminfo for the host
209 terminal.
210
211 PgDn Download Files
212 This brings up the file download menu. Note that CTRL-PgDn and
213 ALT-PgDn may also work depending on the terminfo for the host
214 terminal.
215
216 Alt-\ Compose Key
217 This brings up a dialog to enter the 3-digit decimal value
218 (0-255) for an 8-bit byte or a 4-digit hexadecimal value
219 (0-ffff) for a 16-bit Unicode character (L_UTF8 and X_UTF8
220 only).
221
222 Alt-; Codepage
223 This brings up a dialog to change the current codepage. Code‐
224 pages are limited by the current emulation. VT52, VT100, VT102,
225 VT220, L_UTF8, and X_UTF8 can only be set to the DEC codepage;
226 LINUX, XTERM, ANSI, AVATAR, TTY, and DEBUG emulations can be set
227 to either CP437 (VGA) or ISO-8859-1.
228
229 Alt-/ Scroll Back
230 This selects the scrollback buffer. When viewing the buffer,
231 "S" saves to file and "C" clears the scrollback buffer. By
232 default qodem supports up to 20000 lines of scrollback; this can
233 be changed by editing scrollback_max in scrollback.c.
234
235 Alt-H Hangup/Close
236 This hangs up the modem (drops DTR) or closes the remote connec‐
237 tion (kills the child process).
238
239 Alt-L Log View
240 This brings the session log up in an editor. The session log
241 stores information about connect, disconnect, and file
242 upload/download events.
243
244 Alt-M Mail Reader
245 This spawns the mail reader, by default mm.
246
247 Alt-X Exit Qodem
248 This prompts to exit qodem. When not connected, Ctrl-C will
249 also bring up the exit prompt.
250
251 Alt-A Translate Table
252 This brings up the translate table editor. Both incoming and
253 outgoing bytes can be changed or stripped (set to ASCII NUL
254 (0)). Note that translation occurs before both emulation pro‐
255 cessing and UTF-8 decoding.
256
257 Alt-J Function Keys
258 This brings up the keyboard macro editor. Keyboard macros sup‐
259 port substitutions for carriage return ("^M"), the phonebook
260 entry username ("$USERNAME"), and the phonebook entry password
261 ("$PASSWORD").
262
263 Alt-N Configuration
264 This brings the qodemrc options file up in an editor.
265
266 Alt-O Modem Config
267 This brings up the modem configuration dialog.
268
269 Alt-R OS Shell
270 This spawns a system shell.
271
272 Alt-V View File
273 This brings up a prompt to view a file in an editor.
274
275 Alt-W List Directory
276 This brings up a directory listing.
277
278 Alt-0 Session Log
279 This toggles the session log on or off.
280
281 Alt-1 XON/XOFF Flow Ctrl
282 When connected via modem or serial port, this toggles XON/XOFF
283 on or off.
284
285 Alt-2 Backspace/Del Mode
286 This selects whether the backspace key on the keyboard sends an
287 ASCII backspace (^H) or an ASCII DEL (127) character. Ctrl-H
288 can always be used to send true backspace; Ctrl-? can be used to
289 send true DEL. Note that VT220 emulation always sends DEL when
290 the backspace key is pressed.
291
292 Alt-3 Line Wrap
293 This toggles line wrap mode on or off. When line wrap mode is
294 enabled, if a character is received when the cursor is at the
295 right margin it will wrap to the first column of the next line.
296
297 Alt-4 Display NULL
298 This selects whether ASCII NUL (0) will be displayed as a
299 blank/space or stripped.
300
301 Alt-6 Batch Entry Window
302 This brings up the list of upload files used by Ymodem, Zmodem,
303 and Kermit uploads.
304
305 Alt-7 Status Line Info
306 This selects between two formats for the status line.
307
308 Alt-8 Hi-Bit Strip
309 This selects whether or not to clear the 8th bit of all incoming
310 bytes. Note that high-bit stripping occurs before both emula‐
311 tion processing and UTF-8 decoding.
312
313 Alt-9 Serial Port
314 This opens or closes the serial port. If already connected to a
315 non-serial/modem remote host, this does nothing.
316
317 Alt-B Beeps & Bells
318 This toggles beep support on or off. When beep support is on,
319 beeps from the remote host will be played by qodem. In LINUX
320 emulation, qodem supports setting the tone and duration of the
321 beep as specified in console-codes(4).
322
323 Alt-E Half/Full Duplex
324 This toggles between half and full duplex.
325
326 Alt-I Qodem Information
327 This displays the qodem splash screen which includes the version
328 and build date.
329
330 Alt-U Scrollback Record
331 This selects whether or not lines that scroll off the top of the
332 screen will be saved to the scrollback buffer.
333
334 Alt-= Doorway Mode
335 This selects between three doorway modes: "Doorway OFF", "Door‐
336 way MIXED" and "Doorway FULL". When doorway mode is "Doorway
337 OFF", terminal mode responds to all of its command keys as
338 described in this section. When doorway mode is "Doorway FULL",
339 all Alt- command keystrokes except Alt-= are passed to the
340 remote side. When doorway mode is "Doorway MIXED", terminal
341 mode supports a few commands but passes the majority of Alt-
342 command keystrokes to the remote side. The default commands
343 supported in "Doorway MIXED" mode are:
344 Alt-D Phonebook
345 Alt-P Capture
346 Alt-T Screen Dump
347 Alt-Y COM Parameters
348 Alt-Z Menu
349 Alt-/ Scrollback
350 Alt-PgUp or Ctrl-PgUp Upload Files
351 Alt-PgDn or Ctrl-PgDn Download Files
352
353 Alt-- Status Lines
354 This toggles the status line on or off.
355
356 Alt-+ CR/CRLF Mode
357 This toggles whether or not received carriage returns imply line
358 feed or not.
359
360 Alt-, ANSI Music
361 This toggles ANSI music support on or off.
362
363
365 Qodem supports Unicode (UTF-8 encoding only) in the following functions
366 only: keyboard macros; phonebook entries (NAME, USERNAME, and PASS‐
367 WORD); modem device name.
368
369 UTF-8 is NOT supported in filenames, modem strings, and remote
370 addresses.
371
372
374 Qodem does not have its own scripting language. Instead, any program
375 that reads and writes to the standard input and output can be run as a
376 Qodem script:
377
378 * Characters sent from the remote connection are visible to the
379 script in its standard input.
380
381 * Characters the script emits to its standard output are passed on
382 the remote connection.
383
384 * Messages to the standard error are reported to the user and also
385 recorded in the session log.
386
387 Since scripts are communicating with the remote system and not Qodem
388 itself, they are unable to script Qodem's behavior, e.g. change the
389 terminal emulation, hangup and dial another phonebook entry, download a
390 file, etc. However, they can be written in any language, and they can
391 be tested outside Qodem.
392
393 Scripts replace the user, and as such have similar constraints:
394
395 * Script standard input, output, and error must all be in UTF-8
396 encoding.
397
398 * Scripts should send carriage return (0x0D, or \r) instead of new
399 line (0x0A, or \n) to the remote side - the same as if a user
400 pressed the Enter key. They should expect to see either bare
401 carriage return (0x0D, or \r) or carriage return followed by
402 newline (0x0D 0x0A, or \r\n) from the remote side.
403
404 * Input and output translate byte translation (the Alt-A Translate
405 Tables) are honored for scripts.
406
407 * While a script is running:
408 - Zmodem and Kermit autostart are disabled.
409 - Keyboard function key macros are disabled.
410 - Qodem functions accessed through the Alt-character
411 combinations and PgUp/PgDn are unavailable.
412 - Pressing Alt-P will pause the script.
413
414 * While a script is paused:
415 - The script will receive nothing on its standard input.
416 - Anything in the script's standard output will be held until
417 the script is resumed.
418 - The script process will not be signaled; it may continue
419 running in its own process.
420 - The only Alt-character function recognized is AltP to
421 resume the script. All other Alt- keys will be ignored.
422 - Keys pressed will be sent directly to the remote system.
423 - Keyboard function key macros will work.
424
425 Scripts are launched in two ways:
426
427 * In TERMINAL mode, press Alt-F and enter the script filename. The
428 script will start immediately.
429
430 * In the phonebook, add a script filename to a phonebook entry. The
431 script will start once that entry is connected.
432
433 Script command-line arguments can be passed directly in both the Alt-F
434 script dialog and the phonebook linked script field. For example,
435 pressing Alt-F and entering "my_script.pl arg1" will launch
436 my_script.pl and with its first command-line argument ($ARGV[0] in
437 Perl) set to "arg1".
438
439
440
442 --enable-capture FILENAME
443 Capture the entire session and save to FILENAME.
444
445 --connect HOST
446 Immediately open a connection to HOST. The default connection
447 method is "ssh" unless specified with the --connect-method
448 option.
449
450 --connect-method METHOD
451 Use METHOD to connect for the --connect and --dial options.
452 Valid values are "ssh", "rlogin", "rsh", "telnet", and "shell".
453
454 --username USERNAME
455 Use USERNAME when connecting with the --connect option. This
456 value is passed on the command line to ssh, rsh, and rlogin.
457
458 args...
459 Spawn a local shell and pass args to it.
460
461 --help, -h, -?
462 Display usage screen.
463
464
466 Qodem makes use of the following variables:
467
468 HOME The user's home directory. Qodem creates two directories:
469 $HOME/.qodem for qodem's internal files (phonebook, keyboard
470 macro files, translate tables, etc.) and $HOME/qodem for
471 uploaded and downloaded files, session log, capture, etc.
472
473 EDITOR If present, this will be used when spawning external editors
474 (log view, edit configuration, view file, edit phonebook note).
475 If not present, by default (editable in the options file) use
476 vi.
477
478 ESCDELAY
479 This is a timeout value in milliseconds used by the ncurses
480 get_wch() and wget_wch() functions to determine if a user
481 pressed bare ESCAPE. On some systems pressing ESCAPE may
482 require up to a full second before qodem can process it. For
483 qodem backtick (`) can be used instead of ESCAPE.
484
485
487 $HOME/.qodem/qodemrc
488 Qodem options/configuration file. Inline comments describe the
489 options.
490
491
493 xqodem(1), mm(1), kermit(1), gkermit(1), minicom(1), rlogin(1), rsh(1),
494 ssh(1), telnet(1), xterm(1), vttest(1), console-codes(4)
495
496
498 The screensaver might not load under all circumstances even after the
499 timeout has passed.
500
501
503 The qodem homepage is at <http://qodem.sourceforge.net>.
504
505
507 Copyright © 2010 Kevin Lamonte
508
509 This program is free software; you can redistribute it and/or modify it
510 under the terms of the GNU General Public License as published by the
511 Free Software Foundation; either version 2 of the License, or (at your
512 option) any later version.
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535 August 15, 2010 qodem(1)