Contents
1. Features
2. Startup
A. DOS
B. MS Windows
C. QNX
D. Remote Start
3. Options
4. Examples
5. Printer Commands
6. Information Codes
7. Speaker Sounds
A. At Hot-key Entry
B. During Operation
C. At Hot-key Exit
8. Limitations
Multi-MIPS, 39 Duchess Ave
London Canada N6C 1N3, FeMick@hotmail.com
Copyright (c) 1986 - 1996, Multi-MIPS
QNXT is software that enables computers running DOS to communicate with computers running QNX using a modem or a direct serial link. It has the following features:
a well-behaved DOS TSR as defined by Article 11 of The MS-DOS Encyclopedia
compatible with QCP, Quantum Communication Protocol, file transfers
compatible with Microsoft Windows 3.xx
with QCP_for_DOS, will process background file transfers under Microsoft Windows 3.xx
may occupy as little as about 8k bytes of memory
supports QNX keyboard mapping, screen colour and printer control
permits hot-keying between itself and either the DOS command line or a DOS application
with multiple serial lines, it is practical to load multiple copies and hot-key amoung them
may respond to coded requests from the QNX machine to automatically start most any DOS program, including QCP_for_DOS
permits the use of any IRQ level and any port address
supports baud rates up to 115200
contains its own screen, keyboard, UART and printer drivers so uses no BIOS or DOS services during the emulation
has the following options: serial port address, baud rate, remote start, TSR & run execution modes, hot key combination, IRQ level, keyboard buffer size, line printer number, multiplex ID value, memory allocation for remote start, printer buffer size, QNXT enquire, remove from memory, save/restore screen & mouse, UART buffer size, UART buffer write to disk, and screen scroll
options default to commonly used values
options may be controlled both through a QNXT environment string and from the command line
certain options may be controlled directly by software in the DOS machine and indirectly by software in the QNX machine
activated by hot key or by software in the DOS machine
See section 6, Information Codes, for explainations of the various number codes which may occur during startup, and for the DOS end process return codes.
To load QNXT as a TSR type
qnxt
and press Enter. To activate the TSR press the hot key combination: the default consists of pressing both shift keys together. To return to the interrupted application press the hot key combination again.
Under MS DOS 5 or newer you may load QNXT with the loadhigh command. QNXT may then occupy zero bytes of conventional memory.
Double-click on the QNXT icon. The QNXT window will appear. When finished either minimize the window or press the hot key combination to exit back to MS Windows. It is suggested that options e1 and s0 be set in qnxt.pif.
You may need set the terminal type using either tcap or tset. For a qnx-2 system use one of:
tcap set qnxt
tset qnxt
For a qnx-4 system use one of:
tcap set qnxt2
tset qnxt2
You may wish to use the stty command to set optional characteristics for your particular terminal. The following qnx stty options are recommended as useful choices. There are many more. Please see your QNX manual.
stty up=a1 down=a9 baud=????? >$mdm
Three QNXT options (x, c and n) were designed to permit QNXT to start QCP_for_DOS in response to pre-determined signals from a remote QNX machine. The implementation is general enough that they can be used to have QNXT start most any DOS program in the DOS machine in response to these signals.
This is particularly useful if the DOS machine is running Windows. QNXT and QCP_for_DOS together may then process background file transfers which are initiated by the remote QNX machine. It is most useful in this case to load QNXT with options e1, s0 and x1, and then to minimize it.
The values of some QNXT options and data structures may be controlled directly by software in the DOS machine and indirectly by software in the QNX machine. This feature is described in the API documentation.
Options may be assigned values both through the DOS QNXT environment string and from the command line. The program processes the environment string first so that the command line may be used to override environment string settings.
Options are interpreted and their values set, not when the hot key is pressed, but when QNXT is initially loaded. All options may be changed by removing QNXT from memory (r option) and then re-loading it with the desired options. Some options may be changed by software calls as described in the API documentation.
Each option is specified by a single letter which may be concatenated with a decimal or hexadecimal number. If the number is omitted zero is assumed. Options are separated by one or more spaces. Options may be in either upper or lower case (are not case sensitive) and may be specified in any sequence.
Default value: hexadecimal 3f8
Acceptable values: hexadecimal 100 through fff8
See examples 2, 3, 5
Choose 3f8 for COM1. Choose 2f8 for COM2. Choose another value
for a specialized communication board. See also the i
option.
Default value: 2400
Acceptable values: 0, 2 - 65535
See examples 3, 11, 12
A value of zero is interpreted to mean 115200 baud. For technical
reasons a value of 1 is not valid. All other values are interpreted
literally. See also the u option when assigning a baud
rate value.
Default value: 16 hexadecimal
Acceptable values: 00 - ff hexadecimal
Recommended values: some of 00 - 1f hexadecimal
See examples 13, 14 and 15
QNXT will load and run a DOS program when it encounters two consecutive occurences of this character, or when it receives the three-character sequence hexadecimal 06, 00, ff. If the DOS program is QCP_for_DOS, it is started in receive mode after 16, 16 or in send mode after 06, 00, ff. In normal circumstances commonly occuring codes such as those for enter or line feed should not be used. See also the n and x options.
Default value: 0
Acceptable values: 0, 1
See example 11
Choose 0 for TSR execution mode. In this mode, QNXT is loaded
immediately, remains memory resident until removed with the r
option or by re-booting, and is started whenever the hot key combination
is pressed.
Choose 1 for run execution mode. In this mode, QNXT is loaded and run immediately. It does not remain memory resident after the hot key is pressed to exit.
It is suggerted to use e0 when running from DOS, and e1 when running from Windows.
Default value: 3
Acceptable values: 3, 5, 6, 7
See example 5
QNXT distinguishes between LeftShift and RightShift but does not
distinguish between LeftCtrl and RightCtrl.
3 LeftShift and RightShift
5 Ctrl and RightShift
6 Ctrl and LeftShift
7 Ctrl and LeftShift and
RightShift
Default value: 4
Acceptable values: 2, 3, 4, 5, 7
See examples 2, 3, 5
Choose 4 for COM1. Choose 3 for COM2. Choose another value
for a specialized communication board. See also the a
option.
Default value: 16
Acceptable values: 0 - 65535
All buffer sizes are rounded up to the next multiple of 16 bytes.
Specifying zero results in the maximum buffer size of 65536 bytes.
The keyboard buffer need exceed 16 bytes only if data is being
keyed in continuously at a rate greater than the output baud rate
for the serial port, as established by the b option.
Default value: 1
Acceptable values: 1, 2, 3, 4
See example 8
Default value: hexadecimal db
Acceptable values: hexadecimal c0 - ff
See examples 5, 10
This option need be specified only if multiple instances of QNXT
are to be loaded, or if another TSR program is to be loaded which
uses QNXT's default multiplex ID value.
Default value: approximately 120K/16
Acceptable values: 0 - 65535
See examples 13, 14 and 15
This option specifies the decimal number of paragraphs (groups of 16 bytes) of memory required by the DOS program. This memory may be allocated from conventional memory, and will be unavailable to other programs in the DOS system until QNXT is removed from memory either using the r option or by re-booting. The value is calculated by dividing the actual number of bytes needed by 16 and rounding up. QCP_for_DOS requires approximately 120K bytes. See also the c and x options.
Default value: 16
Acceptable values: 0 - 65535
See examples 7, 8
All buffer sizes are rounded up to the next multiple of 16 bytes.
Specifying zero results in the maximum buffer size of 65536 bytes.
How large the printer buffer needs to be will depend on the
relative speeds of the arriving serial data and of the printer.
When operating at 2400 baud, data arrives at the serial port at approximately 240 characters per second since one character consists of eight data bits, one start bit and one stop bit, and [2400 / (8+1+1) == 240]. A 2400 baud MNP5 modem may send data to the serial port at 9600 baud, which is equal to approximately 960 characters per second. Modems and direct serial links to QNX may currently transmit data at up to 38400 baud which is equal to approximately 3840 characters per second.
The printer may be considerably slower, printing at 100 to 300 characters per second. Typically, the printer will be slower than the serial connection and data will accumulate in the printer buffer.
[The escape sequences used in the following paragraphs are discussed in section 5, Printer Commands.]
At 2400 baud with a printer operating at around 200 characters per second, the default buffer size of 16 bytes for the printer is sufficient to allow use of the Esc ^ and Esc W printer commands which direct data coming from the serial port to the printer. At higher baud rates or with a slower printer a larger buffer may be necessary, else the printer buffer contents will "wrap around" and data will be lost.
A buffer size of 82 bytes is required if the Esc V command is to be used to print the current line. A buffer size of 2050 bytes is required if the Esc / command is to be used to print the current screen contents. These sizes allow for screen data plus carriage-return and line-feed characters for each line. If one of these two printer escape sequence commands is received and the printer buffer is too small, QNXT sounds the speaker and continues as if the command had not occurred.
Default value: 00
Acceptable values: 00 - ff hexadecimal
Recommended value: 05, <Ctrl-E>
If a non-zero value is specified, then QNXT will transmit its
banner to the QNX machine upon receipt of this code. This option
permits the operator at, or a program in, a QNX machine to check
if QNXT is active in the remote DOS machine.
No value is specified.
See examples 9, 10
Remove from memory the instance of QNXT indicated by the m
option. If m is not specified the default value is used.
Multiple instances of QNXT must be removed in the reverse
order to which they were loaded.
Default value: 1
Acceptable values: 0, 1, 2, 3; s1 may be concatenated
with a path, ending with a backslash, to a disk drive and directory
See examples 6, 11, 12
For running under MS Windows the recommended choice is s0; otherwise, the recommended choice is s1 with a RAM disk.
s0 means do not save the screen or the mouse state, and consequently uses the least memory. The hot key may be used only when the screen is in a text mode. On each entry and exit, the cursor is initialized to screen location row 24 column zero, and the screen is neither cleared nor scrolled.
s1 means save the screen to disk and the mouse state to memory. The hot key may be used when the screen is in a graphics mode if the screen is VGA.
For s1, the screen save files are named QNXT?DOS.QDC and QNXT?QNX.QDC, representing the saved DOS and QNX screens respectively, and are by default stored in the directory which was current when QNXT was loaded. The ? in these file names is replaced with the one-byte, multiplex-ID code for the particular instance of QNXT in order to ensure uniqueness. Existing files with these names are overwritten. QNXT?QNX.QDC is always 4004 bytes in size. QNXT?DOS.QDC will be 4004 bytes for a text mode save and 153600 bytes for a VGA graphics mode save.
s1 has an optional syntax which may be used to specify a drive and directory where these files will be located. Screen saves will be faster if a RAM disk is used.
s2 means save both the screen and the mouse state to memory. The hot key may be used only when the screen is in a text mode. This option uses 4000 bytes of memory more than option s1 and screen saves are very fast.
s3 means save both the screen and the mouse state to memory. The hot key may be used when the screen is in either a text mode or a VGA graphics mode This option uses 150k+4000 bytes of memory more than s1. There may be sufficient memory left to run only a smaller graphics application, but screen saves are very fast.
Default value: 64
Acceptable values: 0 - 65535
See examples 3, 4, 5
See also the w option, section 5 Printer Commands and section
7 Speaker Sounds
All buffer sizes are rounded up to the next multiple of 16 bytes.
Specifying 0 results in the maximum buffer size of 65536 bytes.
The UART buffer may need to exceed 16 bytes if any of the following
four conditions exist:
to accumulate data which may arrive at the serial port while QNXT is in background; this could occur after hot keying from QNXT to DOS, or while hot-keying amoung multiple copies of QNXT
to accumulate larger amounts of data for subsequent examination, perhaps for problem determination; see also the w option
to support an external function as discussed separately in the API documentation
to account for the effect of speaker sounds; see next, and also section 7, Speaker Sounds
The speaker sound made by QNXT in response to Ctrl+G and to certain error conditions takes approximately 1/5th of a second. During this period data arriving at the serial port continues to be buffered. If the UART buffer is too small relative to the baud rate it will "wrap around" during the 1/5th second and data will be lost.
The minimum safe buffer size depends on the effective baud rate. In order to accommodate the 1/5th second speaker sound, the buffer size must be at least [(baud / 10)*5] bytes. Baud/10 gives characters per second since one byte is equal to eight data bits plus one start bit plus one stop bit. Dividing by 5 gives characters per 1/5th second.
for 2400 baud, the minimum safe buffer size is [(2400 / 10)*5], which is equal to 48 bytes
for a 2400 baud MNP5 modem connected at 9600 baud, the minimum safe buffer size is [(9600 / 10)*5], which is equal to 192 bytes
for a 28800 baud v.42bis modem connected at 38400 baud, the minimum safe buffer size is [(38400 / 10)*5], which is equal to 768 bytes
The default buffer size has been set to 64 bytes to absolutely ensure successful operation at the default 2400 baud rate.
Default value: 0
Acceptable values: 0, 1
Choose 1 to create the file QNXT?LOG.QDC upon exit from
QNXT. This file is stored in the same directory as the screen
save files. See also the s option. Any existing file
with this name is overwritten. The ? in this file name is replaced
with the one-byte, multiplex-ID code for the particular instance
of QNXT in order to ensure a unique file name.
QNXT?LOG.QDC contains all of the data from the UART buffer, that is, the data that has arrived at the serial port and has been displayed on the screen. The data in the buffer is normalized from the ring buffer format as it is written out to the file so that it is in the correct sequence. The buffer can be up to 64K bytes in size so that a reasonably large history of screen data may be captured and examined. See also the u option.
QNXT fills the UART buffer with text question marks immediately after the memory for it is allocated. The QNXT?LOG.QDC file can therefore usually be examined by a text editor, although if the buffer has not been filled, some editors may complain about the line of question marks being too long. This file may also be examined using the program DUMP.EXE provided in the BIN directory of the TQDC distribution disk.
Default value: 0
Acceptable values: 0, 1; x1 may be concatenated with
the path, file name and file extension for the DOS program; the
default is c:\tqdc\bin\qcp.exe.
See examples 13, 14 and 15
Choose x1 to have QNXT automatically start QCP_for_DOS.
Under DOS, QNXT must be the active, forground program. (Option e1, or option e0 and hot-keyed to the forground) Under Windows, QNXT may be in background and may be minimized; other programs may be run in forground while QCP_for_DOS transfers files in the background.
QNXT sounds one beep and sends the hexadecimal sequence 16, 18, 18 if the exit code of the DOS program is non-zero. For QCP_for_DOS the non-zero exit-code indicates that the file transfer was not successful, and the 16, 18, 18 terminates the QNX QCP program. See also the c and n options.
Default value: 0
Acceptable values: 0, 1
The default option z0 causes QNXT to scroll the screen
when the cursor advances past the bottom-right row:column position.
Option z1 causes QNXT to reposition the cursor to row
0 column 0, the top-left corner of the screen.
When QNXT receives an ESC z sequence, it sets option z0. When QNXT receives an ESC Z sequence, it sets option z1. This permits a program at the QNX end, or a console operator at the DOS end, to change the z option dynamically.
Choose values specified in the QNXT environment string and default values.
Choose interrupt request line (IRQ) 3 and port address 2f8; that is, choose COM2.
Choose IRQ 5, port address hexadecimal 238, 38400 baud and an 800 byte UART buffer.
Choose a 2000 byte UART buffer so that the user may hot key out of QNXT and into DOS, and still keep at least the last screen full of data that may arrive while in DOS.
To load multiple copies of QNXT, each copy must have a unique IRQ level, serial port address, hot key code and multiplex ID value. In this example each copy is given a 2000 byte UART buffer so that at least one full screen of data will be retained for each while in background. The first copy uses defaults. The second copy uses chosen values. The user may hot key between these two instances of QNXT by hot keying to DOS between them.
Choose the default option to save screens to disk, but specify that the screen save files should be in the root directory of disk drive e:, which may be a RAM drive.
Specify an 82 character printer buffer so that the Esc V printer command can be used to print the current line.
Choose LPT2 and specify a 2050 byte printer buffer so that the Esc / printer command can be used to print the current screen contents.
Remove from memory the instance of QNXT which has the multiplex ID code m equal to the default value hexadecimal db.
Remove from memory the instance of QNXT which has the multiplex ID code m equal to the value hexadecimal e4.
Choose run mode, 1200 baud and screen save to memory, text mode only.
Assuming the environment string setting of the previous example, override the baud rate with 2400 and disable the screen save option.
Prepare to remote-start QCP_for_DOS from c:\tqdc\bin\qcp.exe.
Prepare to remote-start QCP_for_DOS from e:\comm\qcp.exe.
Prepare to remote-start myprog.exe from c:\ in 64K bytes of memory (64k = 65536; 65536 / 16 = 4096), in response to 1f 1f or in response to 06, 00, ff.
The local printer is controlled by escape sequence commands which may be sent by software from the QNX machine or entered at the local terminal. Please read about option p, printer buffer size, and section 7, Speaker Sounds if these commands are to be used. The commands are:
If the printer is on line, all data which is sent to the display is also sent to the printer.
Data is no longer sent to the printer.
If the printer is on line, all data is sent to the printer without being displayed.
Data is no longer sent to the printer; the screen display is re-enabled.
The line containing the cursor is sent to the printer followed by a return and line feed. This command requires a printer buffer of at least 82 bytes (option p82). If the buffer is too small, QNXT sounds the speaker and continues as if the command had not occurred.
The current screen image of 25 lines of 80 characters each is sent to the printer; each line is followed by a return and line feed. This command requires a printer buffer of at least 2050 bytes (option p2050). If the buffer is too small, QNXT sounds the speaker and continues as if the command had not occurred.
These codes may be displayed when QNXT is loaded.
When QNXT executes the DOS end process function (interrupt 21h/4ch), the return code is set to 1 if one of these information codes was generated and to 0 otherwise. This can be applied in the if errorlevel statement when loading QNXT from a DOS batch file, or when loading QNXT from another program with the DOS Load and Execute Program function, int 21h/4bh.
The 1nnn, 2nnn, 3000, 5000, 5800, 6000 and 7000(i) codes are user errors which are easily corrected, usually by retyping the command with syntax corrections. The 4nnn, 50mm and 7000(ii) errors, marked with an asterisk in the table, are probably indicative of a corrupt operating system. You should re-boot the system and try again.
Information Meaning
Code
1nnn syntax error in QNXT environment string
2nnn syntax error in command line arguments
nnn = invalid option
000
001 invalid a value, serial port address
002 invalid b value, baud rate
003 invalid c value, remote start character
code
005 invalid e value, execution mode
008 invalid h value, hot key value
009 invalid i value, IRQ
011 invalid k value, keyboard buffer size
012 invalid l value, line printer number
013 invalid m value, multiplex ID value
014 invalid n value, remote start memory
alloc'n
016 invalid p value, printer buffer size
017 invalid q value, enquire QNXT
018 invalid r value, remove from memory
019 invalid s value, screen save
021 invalid u value, UART buffer size
023 invalid w value, QNXT?LOG.QDC
024 invalid x value, remote start
026 invalid z value, screen scroll
3000 the QNXT program is already in memory
using the default or given multiplex ID;
a different multiplex ID code may be
chosen or QNXT may be removed from memory
using the r option
4nnn* DOS function request 48h, 49h or 4ah
failed
nnn = 000* unable to free environment space
001* unable to allocate UART buffer
002* unable to allocate keyboard buffer
003* unable to allocate printer buffer
004* unable to allocate 4000 byte screen save
area
005* unable to execute set block function
006* unable to allocate VGA state save area
007* unable to allocate 150k byte VGA save
area
008* unable to allocate mouse state save area
5nnn error while trying to remove QNXT
nnn = 800 QNXT is not loaded with the given or
default m value, so it cannot be removed
nnn = 0mm* DOS function request 49h was unable to
free some memory block(s) occupied by
QNXT. The mm indicates which memory
block(s) could not be freed. When
translated from hexadecimal into binary,
the bits of mm, from right to left,
indicate: QNXT program, 4000 byte
screen save area, VGA state save area,
150k byte VGA save area, mouse state save
area, UART buffer, keyboard buffer and
printer buffer.
6000 incorrect DOS version; must be 3.1 or
newer
7000 (i) the chosen screen save option is not
* compatible either with the current video
mode or with the screen type, or
(ii) unable to open files for saving or
restoring the screen
See also option u, UART buffer size and section 5, Printer Commands.
The cases following that are marked with an asterisk are probably indicative of a corrupt operating system. You should re-boot the system and try again.
A single beep with QNXT starting anyway indicates one of the following:
no printer is on line
* an error occurred while attempting to reset the CapsLock, NumLock and ScrollLock keyboard LEDs
A single beep with QNXT not starting indicates one of the following, and that the hot key should be pressed again:
* the 8259a programmable interrupt controller is busy
* BIOS interrupt 05h, 10h or 13h is busy
* DOS is busy
A double beep with QNXT not starting indicates that the hot key has been disallowed by the API software. See the API documentation, C Language Interface function qnxt_hotkey(), and Assembly Language Interface functions 2 and 3. To correct this condition, QNXT may be re-allowed by the API software, or removed with the r option and then reloaded.
A triple beep with QNXT not starting indicates one of the following:
the chosen screen save option is not compatible either with the current video mode or with the screen type
* unable to open files for saving or restoring the screen [QNXT?DOS.QDC, QNXT?QNX.QDC]
A single beep with QNXT continuing indicates one of the following:
a printer command escape sequence has arrived at the serial port and either a printer is not on line or the printer buffer (p option) is too small
an undefined key combination was pressed
* the keyboard controller sent a resend, an unexpected acknowledge or a buffer overrun indicator
A single beep may indicate that
* an error occurred while QNXT was attempting to reset the CapsLock, NumLock and ScrollLock keyboard LEDs
A single or double beep may indicate that
* QNXT is unable to open files for saving or restoring the screen [option s, QNXT?DOS.QDC, QNXT?QNX.QDC], or for writing out the UART buffer [option w, QNXT?LOG.QDC]
The following features are not currently incorporated into the QNXT software. These may be added in future versions. Please contact Multi-MIPS if your application requires any of these or other features.
does not support compose characters, that is, the specialized use of the Alt key to generate codes from the keyboard
permits the hot key during graphics modes for VGA monitors only, and during text modes for all monitors
does not support DOS versions previous to 3.1
does not co-exist with multiple instances of itself using different serial ports on a single IRQ level; rather, each port requires its own IRQ level (see also the i option)