1qodem(1)                    General Commands Manual                   qodem(1)
2
3
4

NAME

6       qodem - Qodem Terminal Emulator
7
8

SYNOPSIS

10       qodem [ --enable-capture FILENAME ]
11             [ [ --connect HOST [ --connect-method method ]
12               [ --username name ]                          ] |
13               args...                                      ]
14
15
16       qodem [ --help | -h | -? ]
17
18

DESCRIPTION

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

TERMINAL REQUIREMENTS

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

EMULATIONS

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

FILE TRANSFER PROTOCOLS

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

INTERFACE

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

UNICODE SUPPORT

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

SCRIPT SUPPORT

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

OPTIONS

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

ENVIRONMENT VARIABLES

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

FILES

487       $HOME/.qodem/qodemrc
488              Qodem  options/configuration file.  Inline comments describe the
489              options.
490
491

SEE ALSO

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

BUGS

498       The  screensaver  might not load under all circumstances even after the
499       timeout has passed.
500
501

HOMEPAGE

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)
Impressum