Contents

1. Features
2. General Description
3. Startup
A DOS
B MS Windows
C Remote Start
4. How QCP_for_DOS Works
5. QCP_OPTS.QDC
6. Standard Options
7. Additional Options
8. Examples
9. Limitations
Multi-MIPS, 39 Duchess Ave

London Canada N6C 1N3, FeMick@hotmail.com

Copyright (c) 1991-1996, Multi-MIPS

1. Features

QCP_for_DOS is software that enables QCP file transfers between a DOS machine and a QNX machine using a modem or direct serial link. It has the following features:

compatible with QCP, the Quantum Communication Protocol

compatible with Microsoft Windows 3.xx

may process background file transfers under Windows

may be started by the remote QNX machine, providing automated background file transfers initiated by the remote QNX machine

may be run from another DOS program, which may itself control the remote QNX QCP, providing automated file transfers initiated by the local DOS machine

permits file transfers directly to QNX and DOS devices such as printers

allows options to be set, either both from the environment and from the command line, or from a file

options specified on the command line override options specified in the environment

optionally creates a QCP command with appropriate options and sends it over the serial line to automatically start QCP running in the remote machine

optionally permits the user to enter both the local and remote QCP commands

permits the use of any IRQ level and any port address

supports baud rates up to 115200

2. General Description

This section is adapted from the file qcp.doc from QUICS, the Quantum Interactive Conferencing System.

QCP_for_DOS provides an error checked file transfer protocol for transmitting and receiving files. The QCP protocol achieves high efficiency on packet switched networks by using a 2k byte packet size and high reliability due to the use of 16 bit CRCs.

The QCP protocol is specific to the QNX environment and automatically sends files with their path name, attribute, permission and date fields intact. QCP_for_DOS sends files with read permission and with read, write and modify attributes. The G= and M= options are used to specify the group and member numbers of the owner of a file sent to a QNX system.

Should a send or receive fail because of a problem at the QNX end, the error message generated by QCP at the QNX end is sent through the QCP protocol to QCP_for_DOS and displayed on the local screen. If transmission errors occur, only the parts of the packet that were received in error are re-transmitted.

QCP requires that the timer administrator task be running in the background on the QNX machine. This can be accomplished by executing the following command on the QNX machine:
timer &
This command may be placed in the sys.init file of the QNX machine so that the timer administrator task is always installed.

3. Startup

Under DOS

use QNXT or other communication software to connect to the remote QNX machine and log in

optionally type a command on the QNX command line to run QCP in the QNX machine, but do not press enter; this step is normally omitted

return to DOS, leaving QNX either at the command line prompt or optionally at the typed-but-not-entered QCP command

run the QCP_for_DOS program, either from the command line or from your software; see section 7 for examples

after the file transfer is apparently complete, wait until the DOS prompt re-appears, or until your software receives the DOS return code from QCP_for_DOS

to abort an on-going file transfer press the escape key, the space bar or the enter key once and answer the "Abort send/receive (y/n) ?" prompt by pressing a y or n key; the prompt may be delayed up to a full packet transmission time

if QCP is running at the remote end of a serial line and the user wishes to abort it, a Ctrl+V Ctrl+X Ctrl+X sequence should be typed; line breaks (as generated by typing Ctrl+Break) are ignored by QCP.

Under MS Windows

use QNXT or other communication software to connect to the remote QNX machine and log in

optionally type a command on the QNX command line to run QCP in the QNX machine, but do not press enter; this step is normally omitted

exit the communication software and return to MS Windows, leaving QNX either at the command line prompt or optionally at the typed-but-not-entered QCP command

double-click on the QCP icon; the QCP window will appear

append options if necessary to the provided QCP command and press Enter; see section 7 for examples

after the file transfer is apparently complete, wait until the QCP window becomes inactive and then close the window to exit back to MS Windows

to abort an on-going file transfer press the escape key, the space bar or the enter key once and answer the "Abort send/receive (y/n) ?" prompt by pressing a y or n key; the prompt may be delayed up to a full packet transmission time

if QCP is running at the remote end of a serial line and the user wishes to abort it, a Ctrl+V Ctrl+X Ctrl+X sequence should be typed; line breaks (as generated by typing Ctrl+Break) are ignored by QCP

Remote Start

Remote start means that software in, or an operator at, the QNX machine will initiate the file transfer. Some setup must be done on the DOS machine so that QCP_for_DOS will be ready to run. QNXT must be loaded in the DOS machine with options set so that it will recognize the signal from QNX to load and start QCP_for_DOS. Under Windows, QNXT may be running minimized.

from the DOS machine, use QNXT with the x1 option to connect to the remote QNX machine, log in, and disable echo on the serial line (stty -echo). Consider also the s0, c, n, e1, a, b, and i options

on the DOS machine, possibly create a QCP_RMOT.QDC file as described below

from the QNX machine, enter commands such as:

qcp $mdm se file_name
qcp $term3 re

When QCP_for_DOS is remote-started, it processes options only from the file QCP_RMOT.QDC, and only from the first line of this file. The DOS QCP environment string, the DOS command line, the keyboard and subsequent lines of QCP_RMOT.QDC cannot be accessed in this circumstance. QCP_for_DOS looks for this file only in the current directory. If running under windows, you may use the startup directory option in the PIF file for QNXT (not the PIF file for QCP_for_DOS) to establish this directory. QCP_for_DOS processes this file only if it has been remote-started.

Before processing this file, QCP_for_DOS sets -Auto, +Echo and +Pshell. These options are normally required for a remote start but may be overridden by options specified in QCP_RMOT.QDC. The option line may not contain the program name qcp, or the se and re options. Following is an example of the possible content of QCP_RMOT.QDC:

file1 +t A=238 I=3

When QCP_for_DOS is remote-started in send mode (QNX QCP receiving) there must be a QCP_RMOT.QDC file present in the current directory to specify the file(s) to be sent. If it is remote-started in receive mode (QNX QCP sending) there may be but need not be a QCP_RMOT.QDC file. A QCP_RMOT.QDC file is especially required if A=, I=, or B= options are not the default.

4. How QCP_for_DOS Works

The terminology send and receive is always relative to the DOS end of the file transfer. Send means send from DOS to QNX; receive means receive to DOS from QNX.

process options from the file QCP_RMOT.QDC

if remote-started skip the next three steps else reset all options to defaults and continue

if started from the command-line with no arguments, process options from the file QCP_OPTS.QDC and skip the next two steps

process options from the DOS QCP environment string

process options from the command line that was entered on the DOS machine

request and process missing required options, if any

determine the correct options for both the sending end and the receiving end of the file transfer

save the IER, LCR and MCR registers of the UART, save and take over the interrupt vector, and initialize the serial port

optionally disable echo (stty -echo) on the serial line

optionally create a QCP command for the remote QNX

optionally activate the remote QCP either by sending this command or by sending just an Enter character to activate any typed-but-not-entered QCP command; may take no action so as to permit another DOS program to activate the remote QCP

cooperate with the QNX QCP program to execute the file transfer

after the transfer is apparently complete, wait for either one of $, %, #, or : followed by a space, or for 5 seconds of no received characters, to ensure that the QNX QCP program has ended

optionally restore echo (stty +echo) on the serial line

re-load the IER, LCR and MCR registers of the UART with their original values, and restore the interrupt vector

set the DOS return code as follows:

     0       the file transfer succeeded    

     1       question mark found in         
             options                        

     2       invalid option(s) encountered  

     4       the file transfer failed       


5. QCP_OPTS.QDC

This file is processed if it exists in the current directory, and only if QCP_for_DOS is started with no command line options, as:

qcp<Enter>

The DOS QCP environment string is ignored in this case so that only options in this file control the file transfers. This file may contain a series of QCP_for_DOS option strings, each on a new line. All options are reset to the default values before processing the next line of this file. These option strings may alternately send and receive files. It is not necessary to use +R within QCP_OPTS.QDC as QCP_for_DOS processes all lines in this file. Following is an example of the possible content of QCP_OPTS.QDC:

re file1 +t
se x=index_file
re file2 +B

6. Standard Options

This section is adapted from the file qcp.doc from QUICS, the Quantum Interactive Conferencing System. In these option descriptions the codes

[se re QNX DOS]

indicate whether the option applies to sending and/or receiving, and whether it is interpreted at the QNX or DOS end of the file transfer.

Option 1

? [QNX DOS]

The usage message printed when QCP_for_DOS is invoked by
QCP ?
is:

QCP_for_DOS Vn.n (date) Copyright (c) 1991-1996 Multi-MIPS
Use: qcp se | re [options]* [f=forced_filename | p=prefix]
[x=index_file]* src_file[,dst_file]*
Options: +-make_dir +-newest +-relaxed_timing +-today +-verbose
l=logfile s=packet_size
+-Auto +-Binary +Debug +-Echo +Memory +-Pshell +-Quiet +-Restart
A=address B=baud D=qnx_device G=group I=irq M=member Q=multiplex_ID
Note: use * instead of = in DOS QCP environment string

The options may be specified in any order, are separated by one space, are case sensitive and are abbreviated to their first letter. Those that apply only to QCP_for_DOS are specified in upper case. The se or re parameter and either a file name or an index file are required.

Wherever the QNX version of the QCP program supports either a plus or a minus prefix, QCP_for_DOS supports both the plus and the minus so that options specified on the command line may override those specified in a DOS QCP environment string.

When options are specified in a DOS QCP environment string, an asterisk is used instead of the equal sign. DOS does not permit the use of equal signs in an environment string.

Before filenames are sent to the QNX machine, drive information is removed and backslash "\" is changed to forward slash "/". When file names are received from the QNX machine, node and drive information is removed and forward slash "/" is changed to backslash "\".

Option 2

re [re QNX DOS]

The file transfer will be a receive from the QNX end to the DOS end. Assuming the default option +Auto, a "qcp se" command is constructed by QCP_for_DOS. Options that were specified that apply to se only, and those that apply to both se and re are appended to this command and it is sent to the remote QNX machine. QCP_for_DOS then cooperates with the QNX QCP program to execute the file transfer.

Option 3

se [se QNX DOS]

The file transfer will be a send from the DOS end to the QNX end. Assuming the default option +Auto, a "qcp re" command is constructed by QCP_for_DOS. Options that were specified that apply to re only, and those that apply to both re and se are appended to this command and it is sent to the remote QNX machine. QCP_for_DOS then cooperates with the QNX QCP program to execute the file transfer.

Option 4

src_file[,dst_file] [se QNX DOS]

See example 10
A file can be read under one name, src_file, at the sending end and sent to the receiving end to be received under a different name, dst_file.

Note that at any place where a filename is permitted, a QNX or DOS device may be specified. This permits, for example, copying files directly from DOS to a QNX printer and from QNX to a DOS printer.

Option 5

f=forced_filename [re QNX DOS]

See examples 3, 4, 5
The file name that received files will be saved with is forced to forced_filename regardless of the original filename. The f= option applies only at the receive end of a file transfer. Consequently, when executing a QCP send, forced_filename will be a QNX pathname, and when executing a QCP receive, forced_filename will be a DOS pathname. Also, see the notes following the descriptions of options 4 and 7.

Option 6

l=logfile [se QNX DOS]

After each file send, logfile is opened and has the following information appended to it: the current time, the letters "SND", a number one if the send succeeded else a number zero, and the file name. A log file is maintained only at the send end of a file transfer. Consequently, when executing a QCP send, logfile will be a DOS pathname, and when executing a QCP receive, logfile will be a QNX pathname.

Option 7

p=prefix [re QNX DOS]

See examples 6, 7, 8, 9, 13, 14, 15
The prefix is applied to incoming file names. This option is useful to force received files to reside in a particular directory or to contain particular characters at the start of their filenames. The p= option applies only at the receive end of a file transfer. Consequently, when executing a QCP send, prefix may be a QNX pathname, and when executing a QCP receive, prefix may be a DOS pathname.

Note that the two options p= and f= are mutually exclusive. A forced filename will take precedence over a prefix.

Option 8

s=packet_size [se QNX DOS]

The default value for the packet-size is 2k bytes. The maximum value is 2k bytes; the minimum is 96 bytes. Each transmission is of packet_size bytes, divided into eight sub-packets. The size of each sub-packet includes eight bytes of overhead. In the event of transmission errors, only the sub-packets in error are retransmitted.

Option 9

x=index_file [se QNX DOS]

See examples 8, 9
Index_file is a file that contains a list of files to send. Files named within an index file can make use of the src_file,dst_file notation. The x= option applies only at the send end of a file transfer. Consequently, when executing a QCP send, index_file will be a DOS pathname, and when executing a QCP receive, index_file will be a QNX pathname.

QNX index files can be created with the command
files -v >index_file
DOS index files can be created with the command
dir /b >index_file

Option 10

+make_dir [re DOS]
-make_dir [re QNX DOS]

Default: +make_dir
See example 13
The automatic creation of subdirectories is permitted or suppressed. This option applies only at the receive end of a file transfer.

Option 11

+newest [re QNX DOS]
-newest [re DOS]

Default: -newest
See example 15
The QCP protocol determines if the file being received bears a date newer than the date on the file if it is already on disk. If the incoming file is newer or the file does not already exist it will be received, otherwise a "skipped" message will be displayed. This option applies only at the receive end of a file transfer.

Option 12

+relaxed_timing [se re QNX DOS]
-relaxed_timing [se re DOS]

Default: -relaxed_timing
Invoking this option scales all time-outs within QCP to be four times as large. Retry limits are twice as large. This option is most useful in situations where long time-out values are not a problem, such as for file transfers that are to run unattended or overnight.

Option 13

+today's_date [re QNX DOS]
-today's_date [re DOS]

Default: -today's_date
See example 16
QCP puts today's date and time on any received files instead of the original date and time of the file.

Option 14

+verbose [se re QNX DOS]
-verbose [se re QNX DOS]

Default: N/A
The -verbose option eliminates all output to the screen except for error messages. The +verbose option is intended for debugging purposes only and is not intended to be applied by users of QCP_for_DOS.

7. Additional Options

These options are not part of the QNX version of the QCP program - they apply only to QCP_for_DOS. In these option descriptions the codes

[se re DOS]

indicate whether the option applies to sending or receiving, and that it is interpreted only at the DOS end of the file transfer. These options are specified in upper case.

Option 15

A=address [se re DOS]

Default: hexadecimal 3f8
This is the address of the serial port. Values in the range hexadecimal 0100 through fff8 are permitted. The default value represents COM1. See also the B= and I= options.

Option 16

B=baud [se re DOS]

Default: decimal 2400
Values in the range 0 through 65535 are permitted. The value 0 represents 115200 baud; the value 1 is not valid; all other values are interpreted literally as the baud rate for the serial port. See also the A= and I= options.

Option 17

G=group [se DOS]

Default: 255
See examples 12, 15
This group number will be applied to files sent to QNX. Values in the range 0 through 255 are permitted.

Option 18

I=irq [se DOS]

Default: 4
This is the IRQ level or interrupt request level for the serial port. Values in the set {2, 3, 4, 5, 7} are permitted. The default value represents COM1. See also the A= and B= options.

Option 19

M=member [se DOS]

Default: 255
See examples 12, 14
This member number will be applied to files sent to QNX. Values in the range 0 through 255 are permitted.

Option 20

Q=multiplex_ID [se re DOS]

Default: hexadecimal db
See example 14
The multiplex ID is a two-digit hexadecimal code used to identify an instance of QNXT which may be in the memory of the DOS machine. It needs to be specified if that instance of QNXT does not have the default value. QCP_for_DOS uses this code to disable the QNXT hot-key during file transfers, if QNXT and QCP_for_DOS are using the same serial port address.

Option 21

+Auto [se re DOS]
-Auto [se re DOS]

Default: +Auto
See example 11
The default +Auto causes QCP_for_DOS to construct and send a complete QCP command to activate QCP at the QNX end.

The command sent by the default +Auto option is always the counterpart of the one specified. That is, if "qcp se" was specified "qcp re" is sent; if "qcp se" was specified then "qcp re" is sent. The options that are sent with the command are both those that apply only to the counterpart of the given command, and also those that apply regardless of which command was given.

-Auto prevents the sending of a qcp command. QCP_for_DOS can then be activated by another DOS process which is responsible for activating the remote QCP. See also the Pshell and Echo options.

Option 22

+Binary [se re DOS]
-Binary [se re DOS]

Default: -Binary
See examples 12, 15
The file to be transferred is a binary file (+Binary) or a text file (-Binary). For sending text files, carriage return and line feed pairs are translated into record separators. For receiving text files, record separators are translated into carriage return and line feed pairs. For binary files these translations are not performed.

Option 23

+Debug [se re DOS]

Default: -Debug

Causes QCP_for_DOS to create files named QCP_IN.QDC and QCP_OU.QDC. The former is a log of all bytes received from the serial port and the latter is all bytes output to the serial port. These files may be examined using the program DUMP.EXE provided in the BIN directory of the TQDC distribution disk.

Option 24

+Echo [se re DOS]

-Echo [se re DOS]

Default: -Echo
The default option -Echo causes echo to be disabled (stty -echo) on the serial line before the file transfer is initiated, and to be subsequently restored (stty +echo). +Echo causes these actions to be not taken.

Option 25

+Memory [se re DOS]

Default: -Memory
Causes QCP_for_DOS to create a file named QCP_MEM.QDC when it terminates. Multi-MIPS uses the information in this file to calculate the quantity of memory that QNXT needs to allocate in order to remote-start QCP_for_DOS. This option requires DOS 6 or newer.

Option 26

+Pshell [se re DOS]

-Pshell [se re DOS]

Default: -Pshell
+Pshell prevents the transmission of the Enter code sent to activate a qcp command at the QNX end. QCP_for_DOS can then be activated by another DOS process which is responsible for activating the remote QCP. See also the Auto and Echo options.

Option 27

+Quiet [se re DOS]

-Quiet [se re DOS]

Default: -Quiet
Once the +Quiet option has been processed there is no output to the DOS screen from QCP_for_DOS.

Option 28

+Restart [se re DOS]

-Restart [se re DOS]

Default: -Restart
Causes QCP_for_DOS to restart after executing the file transfers associated with the current command line. +R must be specified on each of a series of command lines except for the last. All options are reset to the default values before restarting. It is not necessary to use +R within QCP_OPTS.QDC as QCP_for_DOS always processes all lines in this file.

8. Examples

With each example the command automatically sent to the QNX machine by the default option +Auto is given in brackets "[]".

DOS pathnames use the backslash "\" and drive letters while QNX pathnames use the forward slash "/" and drive numbers. It is sometimes important therefore to know if a given option will be processed by the QCP program at the QNX end or by QCP_for_DOS at the DOS end. This information is given with the option descriptions in the previous sections and is illustrated in these examples.

The terminology "send" and "receive" is always relative to the DOS end of the file transfer. Send means send from DOS to QNX; receive means receive to DOS from QNX.

Example 1

qcp re january.dat

[qcp se january.dat]
The file named january.dat in the current directory on the QNX machine will be received to the current directory on the DOS machine. Default values and values specified in a DOS QCP environment string apply for all options.

Example 2

qcp se january.dat

[qcp re]
The file named january.dat in the current directory on the DOS machine will be sent to the current directory on the QNX machine. Default values and values specified in a DOS QCP environment string apply for all options.

Example 3

qcp se f=$lpt textfile.doc

[qcp re f=$lpt]
The file named textfile.doc in the current directory of the DOS machine will be sent directly to the printer $lpt on the QNX machine.

Example 4

qcp re f=lpt1 textfile.doc

[qcp se textfile.doc]
The file named textfile.doc in the current directory of the QNX machine will be received directly to the printer lpt1 on the DOS machine.

Example 5

qcp re f=sales.dat january.dat

[qcp se january.dat]
The file named january.dat in the current directory on the QNX machine will be received to the current directory on the DOS machine. On the DOS machine the file name will be forced to sales.dat.

Example 6

qcp re p=c:\dnload\ january.dat

[qcp se january.dat]
The file named january.dat in the current directory on the QNX machine will be received to the directory \dnload on drive c: of the DOS machine. The p= option is always interpreted at the receive end of a file transfer, so in this example it specifies a DOS pathname.

Example 7

qcp se p=3:/upload/ january.dat

[qcp re p=3:/upload/]
The file named january.dat in the current directory on the DOS machine will be sent to the directory /upload on drive 3: of the QNX machine. The p= option is always interpreted at the receive end of a file transfer, so in this example it specifies a QNX pathname.

Example 8

qcp se x=c:\modem\files p=3:/upload/

[qcp re p=3:/upload/]
Each of the files named in the index file "files", which itself is in the directory \modem on drive c: of the DOS machine, will be sent to the directory /upload on drive 3: of the QNX machine. The x= option is always interpreted at the send end of a file transfer, so in this example it specifies a DOS pathname. Since the p= option is always interpreted at the receive end, it specifies a QNX pathname.

Example 9

qcp re x=3:/modem/files p=c:\dnload\

[qcp se x=3:/modem/files]
Each of the files named in the index file "files", which itself is in the directory /modem on drive 3: of the QNX machine, will be received to the directory \dnload on drive c: of the DOS machine. The x= option is always interpreted at the send end of a file transfer, so in this example it specifies a QNX pathname. Since the p= option is always interpreted at the receive end, it specifies a DOS pathname.

Example 10

qcp se july95.dat,july.95.data

[qcp re]
The file named july95.dat in the current directory on the DOS machine will be sent to the current directory on the QNX machine. The file will be named july.95.data at the QNX end.

Example 11

qcp re -A

[<Enter>]
A file on the QNX machine will be received to the current directory on the DOS machine. QCP_for_DOS assumes that either the user has typed a "qcp se" command with appropriate options on the QNX command line but did not press enter, or that another DOS process has sent such a command to the remote QNX. QCP_for_DOS will not construct and send a QCP command, but rather will send an enter code only.

Example 12

qcp se G=010 M=005 +B program.obj

[qcp re]
The file named program.obj in the current directory on the DOS machine will be sent to the current directory on the QNX machine. It will be owned by group 010, member 005 and will be sent according to the rules for a binary file transfer; that is no translation will be done on carriage return and line feed characters.

Example 13

qcp se -m p=3: d:\document\notes.doc

[qcp re -m p=3:]
The file notes.doc from the directory \document on drive d: of the DOS machine will be sent to the directory /document on drive 3: of the QNX machine. Because the -m option is specified, if the directory /document does not exist on drive 3: of the QNX machine the file transfer will be aborted. QCP_for_DOS removes the DOS drive designation d: and changes each backslash "\" to forward slash "/" before sending the pathname to the QNX machine.

Example 14

qcp re Q=c8 p=gmd prog.c

[qcp se prog.c]
The hot-key will be disabled for the instance of QNXT which has the multiplex ID code hexadecimal c8. The file prog.c will be received from the QNX machine and will be given the filename gmdprog.c on the DOS machine.

Example 15

set qcp=se G*012 M*123 +B +n p*3:/upload/

[qcp re +n p=3:/upload/]

Note that when options are specified in a DOS QCP environment string, an asterisk is used instead of the equal sign. DOS does not permit the use of equal signs in an environment string.

With this environment string active, the user need only type
qcp january.dat
and press enter to activate the file transfer and apply all of the options in the set statement. The file january.dat will be sent from the current directory of the DOS machine to the directory /upload on drive 3: of the QNX machine. The file will be owned by group 012, member 123. The file will be transferred according to the rules for a binary file and will be transferred only if it is newer than an existing file of the same path and name on the QNX machine.

Example 16

qcp re +t picture.gif

[qcp se picture.gif]
Assuming that the DOS QCP environment string has been set as in the previous example, the re parameter on this command line will override the se in the environment string. The +b and +n from the environment string and the +t from the command line all apply so that if the file picture.gif is newer than an existing file of the same name, or if no file of that name exists, it will be received according to the rules for a binary file transfer, and will have todays date applied to it.

9. Limitations

If the src_file,dst_file option or the f= option is not used, files to be received from a QNX system to a DOS system should have filenames that are compatible with DOS filename conventions.