Using Tools: 9.2 pccom: Running PCCOM on the Target

PCCOM is a DOS program that monitors the serial port and responds to commands received on the line. All I/O is interrupt driven with XON/XOFF flow control active on the host machine and obeyed on the target machine.

PCCOM uses the PTTY environment variable of DOS, if it exists. This variable contains communications settings detailing baud rate, COM port, and communications interrupt level. You can override the PTTY settings with command-line options to PCCOM when running it. The following command-line options are allowed:

/b:baud: Specify the baud used for file transfer and serial communications. The baud parameter may be one of the following values: 300, 1200, 2400, 9600, 19200, or 38400. Unambiguous abbreviations may be used (e.g. 9 for 9600 baud or 38 for 38400 baud). The default baud rate is 19200 bps.
/c:port Specify the COM port used for serial communications. The parameter may be one of 1, 2, 3, or 4. The COM ports for Zoomer are: COM 1 the built-in serial port (this is the default).
COM 2 the infrared transceiver.
/i:interrupt: Specify interrupts that should be ignored by PCCOM. This is useful if peripherals share an interrupt number that may confuse PCCOM. The interrupt parameter is one or more numbers of the interrupt(s) to be ignored, in hexadecimal.
/I:irq: Specify the IRQ level for serial line communications. This parameter is rarely required. The irq parameter is the number of the IRQ level to be used.

Quitting PCCOM

PCCOM may be quit either directly or remotely. To quit PCCOM directly, simply hit the Enter key (or the q key) on the machine on which PCCOM is running. If it does not quit on the first keystroke, hit the key again.

To quit PCCOM remotely, issue the quit escape sequence <Esc>EX through the serial line from the host machine. See below for a description of the commands that can be issued remotely.

Remote PCCOM Commands

PCCOM doesn't care what machine originates a remote command; its sole purpose is to evaluate and execute commands received through the serial port it's monitoring. Thus, a command sent by one Zoomer to another will exact the same response as a command sent by a development host machine to a target development machine.

On some computers (depending on BIOS), commands are copied from DOS to the serial port using the "echo" command. (If the computer executing remote commands has a different BIOS, you may get an error like "write fault error writing to device com#"; in this case, you must make sure that the characters sent to the serial port in the end are the same as those shown in the table below.) For example, to send the "quit" command to the remote machine, you could use the DOS command

C:>echo EscEX > com1

where Esc (in italics) represents the Escape character (0x1B).

No matter what method you use to send the character sequences to the serial port, the following commands may be executed remotely. Sending and receiving files remotely is more involved and is therefore discussed in the next section; it is not complicated, however.

All arguments to PCCOM remote commands must end with a delimiter character--an exlamation mark by default. Because of this, file operation commands will not work on files with exclamation points in their names by default. However, there is a PCCom command to use a different delimiter character.

Command	Sequence	Description
Send File	<Esc>XF<Ctrl-A> (<Esc>XF<0x01>)	Send a file from the host to the remote machine using the PCCOM file transfer protocol (see below).
Get File	<Esc>XF<Ctrl-D> (<Esc>XF<0x04>)	Retrieve a file from the remote machine using the PCCOM file transfer protocol (see below).
Turn EchoBack On	<Esc>EBon!	Turn EchoBack on.All text displayed on the target machine will also display on the host machine. Carriage returns are marked by semicolon (";") characters.
Turn EchoBack Off	<Esc>EBoff!	Turn EchoBack off.
Display EchoBack State	<Esc>EB!	Display a string signalling whether EchoBack is turned on. If it's turned on, "Echoback = off" appears on the target machine. If it's turned on, "Echoback = on" appears.
Turn Acknowledge On	<Esc>AKon!	Whenever a transaction is complete, the host will display "Ack Received." or "Nak Recieved." as appropriate.
Turn Acknowledge Off	<Esc>AKoff!	Turn off acknowledgement.
Display Acknowledge State	<Esc>AK!	Display a string signalling whether Acknowledge is turned on. If it's turned on, "ACK/NAK = on" appears on the target machine; otherwise "ACK/NAK = off" appears.
Send Ack Signal	<Esc>ACK	Sends an Ack signal, just as is sent by the target machine when acknowledgements are turned on.
Send NAK Signal	<Esc>NAK	Sends a NAK signal, just as is sent by the target machine when acknowledgements are turned on.
Copy File	<Esc>CPsrc!dest!	Copy the file named in the src argument to the file named in the dest argument. File name arguments may be full or relative paths with or without drive letters. This is equivalent to the DOS COPY command.
Move File	<Esc>MVsrc!dest!	Move the file named in the src argument to the file named in the dest argument. File name arguments may be full or relative paths; no drive letters are allowed. This is equivalent to the DOS MOVE command.
Delete File	<Esc>RFfile!	Remove the named file; the file argument may be a full path or a file in the current directory. This is equivalent to the DOS DEL command.
Change Drive	<Esc>CDdrive:!	Change the working volume to the drive named in the drive argument. This is equivalent to changing the drive in DOS by typing the drive letter followed by a colon (e.g. C:).
Change Directory	<Esc>CDdir!	Change the working directory to that named. The dir argument may be a full or relative path; no drive letter is allowed. This is the equivalent of the DOS CD command.
Show Current Path	<Esc>CD!	Print the current directory's path. This is equivalent to the DOS CD command with no arguments passed.
List Files in Dir	<Esc>LS	List files in the current working directory. This is equivalent to the DOS DIR command with no arguments.
List Files with Details	<Esc>LM	List files in the current working directory, together with the file's DOS attributes, the long name of each GEOS file, and the release number associated with each GEOS file. The DOS attributes are shown with the following flags: a: archive d: sub directory v: volume file s: system h: hidden r: read only
List Files, Full Details	<Esc>LL	List files in the current directory with all information returned by LM, described above, and the token of the creating geode and the document token. Tokens consist of four characters and a `ManufacturerID` --most `ManufacturerID` values will appear as a number, but PCCom will translate those values that it knows about into a mnemonic code: GEO: Geoworks APP: Application Local PLM: Palm Computing WIZ: SchoolView CLB: Creative Labs DSL: DOS Launcher AOL: America Online ITU: Intuit SDK: Default SDK AGD: Association of GEOS Developers
Display Free Space	<Esc>FSd:!	Display the free space on the drive named by the d argument.
	<Esc>FS!	Display the free space on the current drive.
Display Drives	<Esc>AD	Display available drives. The target machine will display one line for each drive, showing the drive's letter and DOS name.
Create Directory	<Esc>MDdir!	Create a new directory according to the dir argument. The dir argument may be a full or relative path. This is the equivalent of the DOS MKDIR command.
Delete Directory	<Esc>RDdir!	Remove the directory named in the dir argument. The dir argument may be a full or relative path; this is equivalent to the DOS RMDIR and RD commands.
Clear Screen	<Esc>cl	Clear the screen of the target machine. This is equivalent to the DOS CLS command.
Display Delimiter	<Esc>DD	Displays the current delimiter character (`!' by default).
Change Delimiter	<Esc>DX <char><old delimiter>	Use a different character as the delimiter. By default, the exclamation mark (`!') is the delimiter character. The character delimiter must lie between the ascii values of 0x21 (exclamation mark) and 0x7e (tilde).
Exit PCCOM	<Esc>EX	Exit PCCOM on the remote machine.

Sending and Receiving Files

If you are using the GEOS SDK, you will do most of your file sending and receiving using the programs PCS, PCSEND, and PCGET. These programs send commands to the serial port, and then follow them by either providing or receiving packaged file data. These three programs are detailed below; following them is a section of the file transfer protocol of PCCOM if you are writing your own remote-access program(s).

PCGET

If PCCOM is running on the target machine, the PCGET program can be executed on the host to retrieve a file from the target. This simple program merely retrieves the file and copies it into the host's working directory under the same name.

PCGET takes the following arguments; only the file name is required. The other arguments are optional and may be used to override the settings in the host machine's PTTY environment variable (see above, under "Running PCCOM on the Target (or on the Zoomer)").

pcget [/b:baud][/c:port][/I:irq] file

/b:baud: Specify the baud used for file transfer. The baud parameter may be one of the following values: 300, 1200, 2400, 9600, 19200, or 38400. Unambiguous abbreviations may be used (e.g. 9 for 9600 baud or 38 for 38400 baud). The default baud rate is 19200 bps.
/c:port Specify the COM port used. The port parameter may be one of 1, 2, 3, or 4. The COM ports for Zoomer are: COM 1 the built-in serial port (this is the default),
COM 2 the infrared transceiver.
/I:irq: Specify the IRQ level for the transfer. This parameter is rarely required. The irq parameter is the number of the IRQ level to be used.
file: Specify the file to be retrieved. The file parameter may be a full or a relative path or a simple file name. The file will be copied from the target to the host into the host's current working directory, with the same name.

PCSEND

If PCCOM is running on the target (remote) machine, PCSEND may be executed on the host machine to download a file to the target. PCSEND will only send a single file, though it may send the file to any directory on the target. To send multiple files, or to download specific geodes to their proper locations in the GEOS 2.0 directory tree, use the PCS program instead.

The command line options of PCSEND are shown below. Only the file to be sent is required; if no other argument is passed, the file will be sent to the target's current working directory.

pcsend [/b:baud][/c:port][/I:irq] file [/d:dest]

/b:baud: Specify the baud used for file transfer. The baud parameter may be one of the following values: 300, 1200, 2400, 9600, 19200, or 38400. Unambiguous abbreviations may be used (e.g. 9 for 9600 baud or 38 for 38400 baud). The default baud rate is 19200 bps.
/c:port Specify the COM port used. The port parameter may be one of 1, 2, 3, or 4. The COM ports for Zoomer are: COM 1 the built-in serial port (this is the default),
COM 2 the infrared transceiver.
/I:irq: Specify the IRQ level for the transfer. This parameter is rarely required. The irq parameter is the number of the IRQ level to be used.
file: Specify the file to be sent. The file parameter may be a full or a relative path or a simple file name. The file will be downloaded to the target machine's current working directory, unless the /d parameter is also passed (see below).
/d:dest: Specify a full or relative destination path for the file.

PCS

If PCCOM is running on the target machine, PCS may be executed on the host machine to send multiple files to predetermined directories on the target. PCS is most often used by GEOS developers using the GEOS development kit, when they are downloading their recently-compiled geodes to the target for debugging.

The PCS program makes use of a list of constraints-tokens and their source and destination files and directories-located in the files ROOT_DIR\INCLUDE\PCS.PAT and ROOT_DIR\INCLUDE\SEND on the SDK host machine. (ROOT_DIR is a DOS environment variable set up by the SDK installation program indicating the top directory into which the SDK files were installed.) The format of these two files is described at the end of this section.

The command-line parameters of PCS are shown below. Note that a file name is not used by PCS; instead, if no token or directory is given, PCS will download all appropriate files in the current working directory. As with PCSEND and PCGET, the baud, COM port, and IRQ level arguments are all optional and may be used to override the settings in the PTTY environment variable.

pcs [/n][/Sf][/t][/b:b][/c:p][/I:i][dir|file|token]

/n: If /n is specified, PCS will send non-EC geodes only. Without this argument, PCS will send only EC geodes.
/Sf: Specify a file containing a list of files to be sent. The file argument is the name of the file.
/t: If the /t argument is used anywhere on the command line, file names specified at the end of the command (see the last argument) will be interpreted as tokens. A token may equate to numerous files as defined in the SEND file.
/b:b: Specify the baud used for file transfer. The baud parameter may be one of the following values: 300, 1200, 2400, 9600, 19200, or 38400. Unambiguous abbreviations may be used (e.g. 9 for 9600 baud or 38 for 38400 baud). The default baud rate is 19200 bps.
/c:p Specify the COM port used. The port parameter may be one of 1, 2, 3, or 4. The COM ports for Zoomer are: COM 1 the built-in serial port (this is the default),
COM 2 the infrared transceiver.
/I:i: Specify the IRQ level for the transfer. This parameter is rarely required. The irq parameter is the number of the IRQ level to be used.
dir|file|token: Specify a directory containing the geodes to be downloaded, the files to be downloaded, or tokens to be interpreted. If no directory, file, or token is specified, PCS will download the appropriate files in the current working directory. If a directory is specified, PCS will download all the appropriate files in that directory. If file names are specified (multiple files and/or directories may be specified), all affected files will be send.

If the /t argument appears anywhere in the command line (see above), this set of arguments will be interpreted as tokens. See directly below for token use and interpretation.

When using a token, PCS looks in the ROOT_DIR\INCLUDE\SEND file for the token to determine which files should be sent. Generally, all executables associated with an application, library, or mechanism are sent when the appropriate token is passed. Look in the SEND file to find out what the accepted tokens are and what they send.

For example, if the SEND file contained the lines

PC	DRIVER/VIDEO/DUMB/HGC/HGC					GEO

PCB	DRIVER/VIDEO/DUMB/HGC/HGC					GEO

PCB	DRIVER/MOUSE/LOGIBUS/LOGIBUS					GEO

then typing

pcs /t pc

would send just the HGCEC.GEO file to the proper directory on the target. Typing

pcs /t pcb

would download both HGCEC.GEO and LOGIBUSE.GEO to their proper directories. A listing of all the supported tokens can be found in the SEND file.

GEOS SDK TechDocs |

9.1 PCCOM Background | Next:

9.3 File Transfer Protocol of PCCOM