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, [email protected]

Copyright (c) 1986 - 1996, Multi-MIPS

1. Features

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

2. Startup

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.

DOS

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.

MS Windows

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.

QNX

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

Remote Start

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.

3. Options

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.

Option 1

a serial port address

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.

Option 2

b baud rate

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.

Option 3

c remote-start character

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.

Option 4

e execution mode

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.

Option 5

h hot key code

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                      


Option 6

i IRQ level

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.

Option 7

k keyboard buffer size

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.

Option 8

l line printer number

Default value: 1
Acceptable values: 1, 2, 3, 4
See example 8

Option 9

m multiplex ID value

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.

Option 10

n memory allocation for the DOS program

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.

Option 11

p printer buffer size

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.

Option 12

q enquire QNXT

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.

Option 13

r remove QNXT from memory

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.

Option 14

s save/restore screen and mouse state

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.

Option 15

u UART buffer size

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.

Option 16

w create log file

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.

Option 17

x remote-start QCP_for_DOS or other DOS program

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.

Option 18

z screen scroll

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.

4. Examples

Example 1

qnxt

Choose values specified in the QNXT environment string and default values.

Example 2

set qnxt=i3 a2f8

Choose interrupt request line (IRQ) 3 and port address 2f8; that is, choose COM2.

Example 3

set qnxt=i5 a238 b38400 u800

Choose IRQ 5, port address hexadecimal 238, 38400 baud and an 800 byte UART buffer.

Example 4

set qnxt=u2000

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.

Example 5

set qnxt=u2000
qnxt
qnxt i3 a2f8 h5 mef

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.

Example 6

set qnxt=s1e:\

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.

Example 7

set qnxt=p82

Specify an 82 character printer buffer so that the Esc V printer command can be used to print the current line.

Example 8

set qnxt=l2 p2050

Choose LPT2 and specify a 2050 byte printer buffer so that the Esc / printer command can be used to print the current screen contents.

Example 9

qnxt r

Remove from memory the instance of QNXT which has the multiplex ID code m equal to the default value hexadecimal db.

Example 10

qnxt r me4

Remove from memory the instance of QNXT which has the multiplex ID code m equal to the value hexadecimal e4.

Example 11

set qnxt=e1 b1200 s2

Choose run mode, 1200 baud and screen save to memory, text mode only.

Example 12

qnxt b2400 s

Assuming the environment string setting of the previous example, override the baud rate with 2400 and disable the screen save option.

Example 13

qnxt x1

Prepare to remote-start QCP_for_DOS from c:\tqdc\bin\qcp.exe.

Example 14

qnxt x1e:\comm\qcp.exe

Prepare to remote-start QCP_for_DOS from e:\comm\qcp.exe.

Example 15

qnxt c1f n4096 x1c:\myprog.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.

5. Printer Commands

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:

Esc ^

Enable printer with display.

If the printer is on line, all data which is sent to the display is also sent to the printer.

Esc _

Reset Esc ^.

Data is no longer sent to the printer.

Esc W

Enable printer without display.

If the printer is on line, all data is sent to the printer without being displayed.

Esc X

Reset escape W.

Data is no longer sent to the printer; the screen display is re-enabled.

Esc V

Line print.

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.

Esc /

Page print.

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.

6. Information Codes

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                       



7. Speaker Sounds

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.

At Hot-key Entry

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]

During Operation

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

At Hot-key Exit

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]

8. Limitations

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)