This chapter gives a reference of the tools included in this development kit. This chapter is not intended to teach you how to use the tools; it provides a reference only. To learn how to use most of the tools, see the Tutorial included in the development kit and the First Steps chapter in the Concepts book.
10.1 Tools Summary
The tools provided in this kit are listed below. Each is described in full in the following sections.
pmake “Make” utility which has knowledge of Goc. The pmake tool manages geode compilation and linking, making appropriate calls to Goc and Glue.
Goc C preprocessor which is aware of programming constructs specific to GEOS programming. The Goc tool looks for special keywords (such as @class and @object) and creates the proper GEOS data structures so that the geode will work correctly after being compiled and linked. Chances are you won’t call Goc directly but will instead use pmake, which will call Goc in turn.
Esp Assembler with awareness of GEOS programming constructs. Also includes support for creating enumerated types, complicated records, and more. Chances are you won’t call Esp directly but will instead use pmake, which will call Esp in turn.
Glue GEOS linker. This determines how the program’s resources should be set up and how those resources can be relocated. It determines file offsets and how to access library functions. As with Goc, you probably won’t call Glue directly but will instead use it through pmake.
grev Revision number generator. This is a handy utility for generating revision numbers for geodes, which may be used to keep track of library protocols. The pmake program uses grev to keep track of incremental changes; if you make large changes to a geode at some point, you can use grev to modify your geode’s revision file to reflect your changes.
mkmf Makefile maker. Creates a MAKEFILE which will in turn be used by pmake to determine how to create the geode’s files.
pccom Communication manager. Sets up communication over serial lines. This manages data transfer and protocols when sending files between machines or debugging.
pcs Geode downloader. Sends geodes from the development machine to their proper directory on the target machine.
pcsend File downloader. Sends an arbitrary file from the development machine to an arbitrary directory on the target machine.
pcget File uploader. Retrieves an arbitrary file on the target machine, transferring it to any directory on the development machine.
Swat GEOS debugger. This program runs on the development machine, monitoring GEOS programs running on the target machine.
10.2 Typical Development Session
The Tutorial shows in detail how to write, compile, download, and debug an application. As a quick guide, however, the following list recaps the steps in a typical development session:
On the development machine, use a text editor (perhaps the one that came with your compiler) to write or edit the source (.c and .goc files, perhaps .asm or .ui files if you have the Esp assembler), header (.h and .goh files, perhaps .def files if you have the Esp assembler), and Glue parameters (.gp files) for your geode.The source files for the geode should be arranged within your development directory.
If you have never compiled the geode before or have added or included new files since the last compilation, you must run mkmf to create or update the MAKEFILE.
If you have added or included new files since the last compilation, you should execute pmake depend so that the compiler will know which files need to be remade if one is altered.
Run pmake. This compiles and links the geode’s source files, using directions provided by the MAKEFILE.
Now you must download the compiled geode to the target machine. Use pcs to send the geode to the proper directory on the target machine (or pcsend if you have a particular destination directory in mind).
To test the geode, either run it on the target machine or run swat from the development machine to debug it.
10.3 File Types
You may be curious to know what sorts of files you’ll be working with. If you have to work with someone else’s code, then being able to find your away around their files (knowing which are sources, which are objects, and which are chaff) can be very useful.
*.goc - These are Goc source files. You will write these files. They contain both standard C code and GEOS constructs (such as objects and messages).
*.goh - These are Goc header files. You will write these files and include others. They provide definitions used by your .goc files (in the same relation as between standard C source and header files). Unlike standard C header files, these are included using the @include Goc keyword.
.poh**, **.ph - These are files generated to optimize the @inclusion of .goh files. Goc will automatically generate these when they don’t already exist.
.doh**, **.dh - These are files generated to optimize the @inclusion of .goh files. They contain dependency information.
*.c - These are standard C source files. You may write these as source files, using only standard ANSI C constructions. The Goc preprocessor will create .c files from .goc files. Thus, if you see two files with the same prefix, but one has the .c suffix and the other has the .goc suffix, then you know that the first was created from the second.
Note that Goc will create the generated .c file in the directory where it is invoked. Thus if your development tree contains files PROG\DIR1\CODE.GOC and PROG\DIR2\CODE.GOC, then if you convert these using Goc from the PROG directory, then one of the generated .c files will overwrite the other. Thus, you should never give .goc files the same prefix, even if they are in different directories.
*.h - These are standard C header files. You may write these and include them using the ANSI C #include directive.
*.asm - These are standard GEOS assembly source files, which may be assembled with the Esp assembler, if you have it. They may contain both standard assembly and Esp constructs.
*.def - These are standard GEOS assembly header files, which you may write or include if you have access to the Esp assembler.
*.mk, makefile - These are “makefiles,” files which contain scripts which the pmake tool will interpret and use to automatically compile and link your geode. In a source directory there will be a file called MAKEFILE (created with the mkmf tool) and probably a file called DEPENDS.MK (created by calling pmake depend). If you wish to customize how your geode is made, you will probably write a file called LOCAL.MK, containing your custom makefile script. The INCLUDE directory contains several .mk files, which will be #included by other makefiles.
*.gp - These are “Glue parameter” or “geode parameter” files, which will give the Glue linker information necessary when linking a geode. You will write this file. The pmake program assumes that a geode’s .gp file will have name geode.GP, where geode is taken from the name of the directory containing the geode’s source (e.g. in the example above, pmake would expect the .gp file to be named PROG.GP).
*.ldf - These are library definition files. Glue uses these files when linking your geode; they determine how your calls to a GEOS library will be encoded. If you are writing a library, then you will create one of these files by means of a pmake lib. The pmake program looks for .ldf files in the INCLUDE\LDF directory.
*.rev - This is a revision file, used to keep track of a program’s revision and protocol levels (useful for tracking compatibility). The pmake tool will look for a file with name geode.REV, where geode is taken from the name of the directory containing the geode’s source (e.g. in the example above, pmake would expect the .rev file to be named PROG.REV). The pmake program uses grev to create and maintain the .rev file; you should use grev yourself when you need to signal a major revision.
*.rsc - Localization resource file. This file contains information which will be used by the ResEdit localization tool.
*.obj - These are object files. These are files created by a C compiler or Esp which may be linked to form an executable. The pmake program uses Glue to link the object files.
*.ebj - These are error-checking object files. GEOS supports the notion of “error-checking code.” When you write your programs, you can mark some commands as “error checking commands.” These commands might make sure that a routine is passed valid arguments or perhaps purposefully destroy some information which was not guaranteed preserved by a routine. Such commands may prove time-consuming but are useful for making sure that an application is robust. The pmake program will create two versions of your application-one which includes the EC (Error Checking) code, and one which doesn’t. Run the EC program to check for correctness, but use the non-EC version when the program should be fast (i.e. this is the version you should give to your customers).
The .obj files will be linked to form a non-EC executable; .ebj files to form an EC executable.
*.geo - This is a Geode, a GEOS executable (either an application, library, or driver), the end result of your efforts. These are the files containing the code for GEOS programs which the user will interact with. They are created by linking together a number of .obj files, with additional information provided by a .gp file. You will place these files in your GEOS testing directory on your target machine (along with *ec.geo files, described below).
*ec.geo - This is an error checking geode. (See above for quick descriptions of error checking code and geodes.) They are created by linking together a number of .obj and .ebj files, with additional information provided by a .gp file.
*.sym - This is a symbol file, containing symbolic debugging information which the Swat debugger can use to access the geode’s data structures.
*ec.sym - This is the symbol file of the error checking version of a geode.
tmp*.* - These are temporary files which pmake will create and destroy while making your executable. The pmake program uses these files to pass arguments to the other tools. Thus, if you see a file of this name in your directory and you didn’t create it, you can assume that pmake was interrupted in a recent make and was unable to erase the file (and thus it is safe for you to erase it).
.tcl, .tlc - These are Tcl files, files containing Tool Command Language source code, used by the Swat debugging tool. The .tcl files contain Tcl source code, the .tlc files contain compiled Tcl code. The source code may be edited by any text editor and Swat will interpret it; compiled code runs more quickly, but can only be changed by editing the source code and re-compiling.
If you are writing a GEOS C application, you will write the following types of files:
Source files: .goc files, optional .c files.
Glue parameters file: geode.GP.
Optional header files: .goh files, .h files.
Optional custom make file: LOCAL.MK.
After you have made your geode the first time (creating a makefile with mkmf, a dependencies file with pmake depend, and the geode itself with pmake), your directory should contain the following additional file types:
Intermediary C files: .c files (made by transforming .goc files).
Makefile: MAKEFILE
Dependencies file: DEPEND.MK
Revision file: geode.REV.
Object files: .obj and .ebj files.
Symbol files: .sym files
Geodes: .geo files.
10.4 Esp
Esp (pronounced “esp”) is the GEOS assembler. It creates object files from Esp code - said code using a superset of MASM syntax. These object files may then be linked by means of the Glue tool.
Most users will never call Esp directly, instead going through pmake, which will make the proper calls to Esp for the most common cases.
Esp takes the following options:
-2 - Code produced should be DBCS-characters will be two bytes instead of one.
-Idirectory - Specifies an additional directory in which to look for included files.
-ofilename - Name to give to created object file.
-wwarntype
-Wwarntype - Turn warnings off or on
unref - Warn if a symbol that can only be used during this assembly isn’t.
field - Warn if structure field used with . operator when lhs isn’t of the type that contains the field
shadow - Warn if a local variable or procedure overrides a definition in a larger scope
private - Warn if a private method or instance variable is used outside a method handler or friend function related to the class that defined the thing
unreach - Warn about code that cannot be reached. This is very simplistic unknown Warn if a far call is made to a routine whose segment is unknown
record - Warn if a record initializer doesn’t contain all the fields of the record
fall_thru - Warn if a function falls into another one without a .fall_thru directive
inline_data - Warn if a variable is defined where execution can reach
unref_local - Warn if a local label isn’t ever referenced
jmp - Warn if out-of-range jumps are transformed into short jumps around near jumps
assume - Warn when override is generated based on segment assumptions
all - Used to turn all warnings on or off.
-M - This assembly is just for the purpose of determining what the source file’s dependencies is. Instead of creating an object file, Esp will create a temporary file which the dependencies maker will use to determine the dependencies.
-d - Activate’s Esp debugging mode. Useful only when trying to track down a bug in Esp.
10.5 Glue
Glue is the GEOS linker. It creates GEOS or DOS executables from object files. (It can also create GEOS VM and font files, if you have the appropriate tools.) These object files may have been created by a C compiler, or by the Esp assembler. To create the executables, Glue must create a combined file, resolve external declarations, determine how to call libraries, and apportion the code and data into resources. Glue will also create a .sym file - a file containing symbolic debugging information which the Swat debugger will use for viewing the geode’s data.
Most users will never call Glue directly, instead going through pmake, which will make the proper calls to Glue for the most common cases.
The Glue application takes the following arguments:
glue @file
glue <flags> <objFile>+ [-l<objFile>]*
@file - The Glue linker should take its arguments from the file file in addition to those on the command line. This may come in handy if you often use the same long string of options. Since you may need to pass Glue more arguments than may be input on the command line, sometimes this option is necessary.
Note that if you use this option, then all arguments must be included in the file-there should be no others on the command line itself.
The pmake program uses this option to pass arguments to Glue.
-Lpath - Specifies where Glue looks for .ldf (library definition) files. These files are placed in a standard directory by the system makefiles on a “pmake lib¨.
-Nstring - Specify a copyright notice.
-Oe - Creating DOS executable (“.exe”) file. Of course, this option is not valid if the object files contain GEOS directives which will not work outside GEOS.
-Oc - Creating DOS command (“.com”) file. Of course, this option is not valid if the object files contains GEOS directives which will not work outside of GEOS.
-Ogfile - Creating GEOS executable (“.geo”) file. You must provide the name of the geode’s Glue parameters file (the .GP file). For information about setting up a parameter file, see “First Steps: Hello World,” Chapter 4 of the Concepts Book.
When creating a .geo file, you may pass any of the following options:
-E - Link Error checking version of geode.
-Rnumber - Specify release number of geode (e.g. 3.2.1.0).
-Pnumber - Specify protocol number of geode (e.g. 1.0).
-Tnumber - File type.
-l - Creating a library; Glue should create .ldf file.
-Ov - Creating GEOS Virtual Memory (.vm) file. Using this option, you may create .vm storage files as set up by the Esp assembler. You may pass the following options when creating .vm files (if you don’t know the meaning of some of these terms, see “Virtual Memory,” Chapter 18 of the Concepts Book):
-Anumber - VMAttributes to use for the file.
-Cnumber - Compaction threshold.
-Mstring - Map block segment name.
-Pnumber - Protocol number (e.g. 2.5.0.3).
-Rnumber - Release number (e.g. 12.3).
-iname - A .geo file from which to get the table of imported libraries. This allows the VM file to be opened by that geode and objects in the file to be used.
-ttoken - File token
-ctoken - Creator’s manufacturer token.
-lstring - File’s long name.
-unotes - File’s user notes.
-Nstring - Copyright notice which will be embedded in header of .GEO or .VM files.
-Gnumber - You should never have to use this option. This specifies a non-standard GEOS release number (e.g. 1.3); if this release used a different VM header than GEOS 2.0, Glue will still construct the proper header as long as this option is passed. Since the default release number is 2, developers for 2.X do not need this option.
-Wall - Requests that Glue output all optional warnings.
-Wunref - Requests that Glue output optional unreferenced global symbol warnings.
-d - Dump memory. Normally used only when debugging Glue.
-m - Provide memory map in output. This information gives information about the sizes of various parts of the geode. This information proves especially helpful when making geodes work with small devices.
-nll - Disables the output of line numbers for local memory segments for any application with 163 resources or more.
-ofile - Specify name of output file (e.g. WOROPRO.GEO).
-q - Leave the symbolic information behind even if an error was encountered. Normally, this flag is used only when debugging Glue.
-r - Maps segment relocations to non-shared resources to resource IDs. This is normally used only by multi-launchable C applications. When running more than one instance of a multi-launchable application, the system only uses one copy of the read-only portion of the application. The system makes separate copies of the writable data for each instance of the application. This can lead to conflict when the relocation instructions for the read-only data uses the handle or segment of a writable resource; which copy should be responsible for providing these addresses? If you don’t pass this flag and Glue detects the above situation, Glue will simply refuse to make the application multi-launchable. This flag instructs Glue to instead use the resource ID of the writable resource where it would normally use the segment or handle of that resource.
If you use this option, make sure that if you use the address of a variable in a resource other than dgroup that you use GeodeGetOptrNS() and lock down or dereference the handle of the returned optr.
-sfile - Specify name of symbol file (the .SYM file).
-z - Output localization information.
10.6 Goc
Goc is the GEOS C preprocessor, which will turn your .goc file into something a regular C compiler can understand. It will traverse the .goc file, detect Goc keywords (e.g. @class, @object), turn these keywords into appropriate pieces of code, and write the resulting file out to a .c file. Note that Goc acts as a simple filter, and will only make changes where it detects Goc constructs; it won’t touch your regular C code at all.
Under normal circumstances, you will not invoke Goc directly. Instead, pmake will make calls to Goc when compiling .goc files.
If for some reason you do need to invoke Goc directly, you may wish to know about its command line arguments:
goc @file
goc [args] <file>
@file - Command-line arguments are stored in a file-Goc will read this file and treat the contents as its arguments. If you use this option, then all the arguments must be in the file-no others may appear on the command line itself.
Redirect output to standard out.
-Dmacro - Set variable macro to one (e.g. “-D__GEOS__”)
-Dmacro=value - Set variable macro to value.
-Idir - Specify additional include directory
-I- - Turn off relative inclusion.
-Lname - Specify name of library being compiled. Must match argument to @deflib Goc keyword in library’s .goh file, if it has one.
-M - Help pmake generate dependency information.
-cb - Generate information for Borland compiler.
-d - Turn on all debugging information.
-dd - Output @default debugging information. (See “GEOS Programming,” Chapter 5 of the Concepts Book to find out what @default means).
GEOS supports two version numbers for each geode. The first of these is the release number, used to uniquely identify the release of the geode. The protocol number tracks the external interface of the file. This is used to determine what versions of related geodes can be used together. The kernel will use these numbers to prevent loading of incompatible executable files.
The grev utility generates proper revision numbers. Normally, it is called automatically by pmake, so if you are just making a small change to a file, you need not call it directly. However, you may wish to. When using grev, you must think about how major a change you are making; a large change means that you should change an earlier number of the release number. A change from 1.2.3.4 to 2.0.0.0 should signal a larger step than a change to 1.2.3.5.
The pmake program uses grev to automatically create revision numbers for geodes; it passes these values to Glue, which in turn places the protocol and revision numbers in the .geo and .sym files.
There are three widely used methods for incrementing release numbers with respect to public releases (for which a specific release number is desired for marketing, say “2.0.0”). The problem comes because it is not known until after a release has been built whether it will be the release or not (since bugs may be found).
The first method is to keep separate public release numbers and internal release numbers. This is awkward and confusing and is generally done when it is too late to do anything else.
The second method is to number successive revisions “1.14.0.12”, “1.14.0.13”, “1.14.0.14” and so on until the final revision is made which is numbered “2.0.0.0”. The problem with this is that one never quite knows whether or not a revision is the final one (since bugs may be found).
The third method is to number successive revisions “2.0.0.12”, “2.0.0.13”, “2.0.0.14” and so on. The released “2.0.0” revision is then the last engineering revision starting with “2.0.0.X”. The disadvantage of this method is that it can seem non-obvious at first and requires a little bookkeeping to know the engineering number of the released version.
The protocol number is changed whenever the external interface for the file changes. For the kernel and for libraries the protocol reflects the order as well as the parameters and behavior of external entry points. For applications the protocol reflects the object names, types and attributes. Changes that do not affect the external interface (changing the implementation of a routine, changing the moniker or hints of an object) do not change the protocol number.
The major protocol number reflects incompatible changes in interface, such as rearranging the order of entry points. The minor protocol number reflects upwardly compatible changes in the protocol (such as adding an entry point at the end of a jump table or using a bit formerly marked as “reserved”).
Each executable file contains protocol compatibility information (a protocol number) for all other executable files on which it depends. For example, a simple application might be compatible with kernel protocol “34.2” and UI protocol “19.7”. Thus the application is compatible with kernels “34.2” through “34.65535” and with UIs “19.7” through “19.65535”.
A protocol number is also stored with each state file to determine if the state can be recovered by the currently running application.
The grev tool uses a file (normally marked with a .rev suffix) in the geode’s development directory to keep track of the revision number. The file is organized chronologically, with later entries at the beginning of the file. It contains
one line for each compilation, denoting the revision number (which is incremented on each compilation), optional user name, the date, and an optional comment. By default, pmake will only change the last part of the release number.
one line for each protocol change, denoting the protocol number, optional user name, the date, and an optional comment.
The grev utility takes the following arguments:
grev commandfile **[-P
-R
-s] [-B branch]** [rev] [“comment”]
file is the name of the revision file (ending in .REV)
rev is only used for the newrev command, see below.
The -P option causes grev to give minimal output, printing only the protocol number.
The -R option causes grev to print only the revision number.
The -s option MUST be given to save changes to file. If this flag is not passed, the change will only be displayed to the screen.
The -B option causes grev to use branch rather than the trunk.
These options are referred to as [flags] in the list below.
Possible commands are:
newfile[flags][“comment”] Create a new revision record, listing comment as an initial revision for the base (0.0.0.0 release, 0.0 protocol). This command may only be executed in the geode’s development directory. [flags] can be given, but will have no effect.
infofile[flags] Print the current release and protocol from the revision file.
getprotofile[flags] Print only the current protocol from the revision file. The -P option works as stated above.
newprotomajorfile[flags][“comment”] NPMfile[flags][“comment”] Increase the major protocol number by one, setting the minor number to zero. The comment argument is listed as the reason for the change in the file. You must give the -s option to save changes to file. The -P option works as stated above.
newprotominorfile[flags][“comment”] npmfile[flags][“comment”] Increase the minor protocol number by one. The comment string is listed as the reason for the change in the file. You must give the -s option to save changes to file. The -P option works as stated above.
newrevfile[flags]A.B.C [“comment”] Update release number to A.B.C.0 The comment is listed as the reason for the change. You must give the -s option to save changes to file.
newchangefile[flags][“comment”] Up release number from A.B.C.D to A.B.C+1.0. The comment is listed as the reason for the change. You must give the -s option to save changes to file. The -R option works as stated above.
newengfile[flags][“comment”] nefile[flags][“comment”] Increase release number from A.B.C.D to A.B.C.D+1. The comment is listed as the reason for the change. You must give the -s option to save changes to file. The -R option works as stated above.
help Print out a detailed help.
10.8 mkmf
The mkmf tool exists to create a file named MAKEFILE. The pmake program will use this file as a sort of script, using it to determine how to compile and link the geode. However, makefiles can get rather complicated, so it is best to create them using mkmf instead of by hand.
For information about customizing this boilerplate makefile, see section 10.13.
The mkmf tool uses the following rules to build the makefile:
The geode name is taken from the name of the directory in which you run mkmf. Among other things, this means that if you change the name of your development directory, you should also run mkmf again.
Any file in the current directory or its subdirectories will be considered a source file if it has one of the following suffixes: .asm, .def, .ui, .c, .h, .goc, or .goh (except that .c files which are generated from .goc files will not be considered sources).
For each .asm, .c, or .goc file, an .obj file with corresponding name will be added to the makefile variable OBJS.
If there are subdirectories, then each subdirectory is considered to hold the source for a module of the program, and mkmf will work with the files in this subdirectory as a unit. The module’s name will be added to the CMODULES variable if it contains .c or .goc files; if it contains .asm files, then it will be added to the MODULES list. When using pmake, each module will be considered something that can be made, a sort of intermediate step towards making the whole geode. If you do not wish the files in a subdirectory to be incorporated in the program, create a file in the directory called NO_MKMF. This file need have no contents.
10.9 pccom
The pccom tool manages communication between the development and target machines. It assumes that the machines are connected by a single serial line. All I/O is interrupt-driven with XON/XOFF flow control active on the development machine and obeyed on the target machine.
Note that it is possible to use some features of pccom from within GEOS. For more information about this, see “PCCom Library,” Chapter 22 of the Concepts Book.
10.9.1 PCCOM Background
PCCOM is used in two primary situations. First, it is used by GEOS software developers when transferring files or when debugging an application. In this situation, the developer runs PCCOM on the target machine and then runs PCS, PCSEND, or PCGET, on the host machine. All of these programs know how to interact with PCCOM.
Second, it is used by DOS programs when transferring files to and from Zoomer devices or other devices that require remote file manipulation. In this case, the host machine runs a program which copies escape character sequences to the appropriate serial port, prompting PCCOM to act.
10.9.2 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.
10.9.2.1 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 EX through the serial line from the host machine. See below for a description of the commands that can be issued remotely.
10.9.2.2 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 most computers, 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 need to access the serial port differently; 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 an exclamation point. Although this character is normally an acceptable character within DOS file names, PCCOM will treat it as the argument delineator character. Because of this, file operation commands will not work on files with exclamation points in their names.
Command Sequence Description
Send File <Esc>XF1 Send a file from the host to the remote machine using the PCCOM file transfer protocol (see below).
Get File <Esc>XF2 Retrieve a file from the remote machine using the PCCOM file transfer protocol (see below).
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 with or without drive letters. 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; 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.
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. This is equivalent to the DOS CLS command.
Exit PCCOM <Esc>EX Exit PCCOM on the remote machine.
10.9.2.3 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 and/or a new destination file name.
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.
/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.
10.9.3 File Transfer Protocol of PCCOM
If you need to create your own file transfer program or module, you can use the basic PCCOM commands and a special transfer protocol to send or receive files over the serial link. This is useful, for example, if you have an existing Windows or DOS program to which you would like the to add the ability to transfer files to or from the Zoomer (or another unit running PCCOM).
10.9.3.1 Sending a File to the Remote Machine
Sending a file to the remote machine involves the steps below. A file may be sent by any program that can access the serial port.
1 - Notify PCCOM that a file is on its way. Send the Send File escape character sequence to the serial port, notifying PCCOM that a file is about to be sent to it. The escape sequence is