************ Getting files on and off a Sol Virtual Disk ************

There are a number of ways to get files from the PC host computer onto
a Sol virtual disk.  Some of them more closely match how this process
happens on a real machine.  Although it works, it can be tedious and
is error prone.  Solace comes with a couple programs, IMPORT.COM and
EXPORT.COM, that make transferring files much easier.

First the use of these utility programs is given, then this is followed
with some credits and technical details.


*********************  IMPORT  *********************

Purpose:
       Import a file from the PC into the Solace emulator.

Usage:
       import [-n] [pcfilename [cpmfilename]]

Parameters:
       -n converts incoming lf to cr/lf on output;
       pcfilename  - name of the PC file to import; and
       cpmfilename - name of the file in CP/M (must not exist);

Notes:
       When started with no arguments, import will prompt for all args.
       If only the pcfilename is specified, the cpmfilename will be 
       assumed to have the same name.

       Also note that the CP/M CCP converts all command line arguments to
       upper case, therefore if pcfilename is specified on the command
       line then it will be taken as all upper case.


*********************  EXPORT  *********************

Purpose:
      Export a file from the Solace emulator to pc.

Usage:
      EXPORT cpmfileref [$[T][L]]

Parameters:
      cpmfileref - name of the file in CP/M to export (wildcards allowed).
      $ indicates options to export:
      	T - treat files as text (cr,lf -> lf, stop at sub)
      	L - make lowercase UNIX filenames.

Notes:
      The CP/M CCP converts all command line arguments to upper
      case, therefore the file will be exported as an all upper case
      file name (unless $L is used).

      Also, CP/M does not keep an accurate file size.  Binary files
      are always multiples of 128 byte blocks; text file end at the
      first sub character.

      There are bdos calls to locate matching file references - Find
      First and Find Next.  It would be simple to uses these calls
      to find each file and export each file as it is found.  Wrong!
      In the Find Next bdos call, my CP/M bible states "No other
      file operation should be done between two search requests
      because the BDOS may lose its position in the directory.  In
      some version of the system this request can use used following
      Close File to find the next file after the one closed.  This
      technique is not recommended".  I tested this and after
      opening the first file, Find Next returns file not found.  So
      I first create a list of matching files and then export each
      file in the list.  A "STAT DSK:" reports that my disks can
      hold 128 directory entries.  At 11 bytes a file this would
      require less than 1.5KBytes - just be careful if you have a
      hard disk with *HEAPS* of directory entries.


********************* Credits *********************

Tim Mann wrote xtrs, an excellent unix-based TRS-80 emulator:

	http://www.tim-mann.org/xtrs.html
	(still valid as of oct 4, 2001)

Tim defined the instruction extensions and wrote the code that
handled them.  With Tim's permission, Solace implemnts a subset
of his extensions using Tim's original code (slightly warmed-over
to make it compatible with Solace's code base).

Please see Tim's web site if you desire to make a derivative work,
rather than using my hacked up versions.  The filenames have changed
somewhat to make them not specific to the trs-80:

	trs_imp_exp.c ---> emt_traps.c
	trs_imp_exp.h ---> emt_traps.h


Roland Gerlach wrote import.com and export.com for xtrs:

	http://www.rkga.com.au/~roland/trs-80/cpm-xtrs/
	(still valid as of oct 4, 2001)

The original source was modified to use only 8080 instructions, intel
mnemonics, and CP/M 2.2 MAC.COM macro syntax.  The import.asm source code
was modified from the original to use the same definition libraries that
export.asm was already using.  The original filenames have been modified
somewhat to be compatible with MAC conventions and to remove
trs80-specific naming:

	cpm.mlb    ---> cpm.lib
	xtrs.mlb   ---> emtdefs.lib
	import.mac ---> import.asm
	export.mac ---> export.asm

If you desire to make a derivative work from the sources provided
here, please instead contact Roland and start with the originals,
not my hacked up version.


********************* Technical Details *********************

The 8080 emulator code gives special meaning to certain pairs of
instructions that are otherwise illegal on a real 8080 (or Z-80 for that
matter).  When these specific illegal byte sequences are executed, Solace
gives them "magic" powers.  One instruction sequence (0EDh 030h) causes
the 8080 to open a file on the pc host, with a file descriptor returned in
the DE register pair.  There are similar instructions that cause a block
of data to be read or written from the host computer.

import.com and export.com are simply file copying programs that use
these magic ops to do half of the transfer, one 128 byte block at a
time.

Look at emt_traps.h in the source directory for an explanation of all
the traps.  Again, not all of them have been implemented by Solace.


********************* Other Methods *********************

Besides import and export, there are other ways to get information
between the PC and the emulated Sol.

Method #1:

On the PC side, convert whatever file you want transferred into a an
Intel-HEX format file.  There are many utilities out on the internet
that can do this.

Using the "LOADH" command from the debugger, or by using the main menu
item "File/Load Program..." read in the .hex file.  Then from CP/M, use
the built-in SAVE command.  SAVE requires that you know how many 256-byte
pages the file will require.  For example, you'd type "SAVE 5 FOO.TXT" for
a file that was 1200 bytes long.

Likewise, a the Solace-specific "ENT" format can be used instead of the
HEX format.


Method #2:

To transfer an ASCII file, open up ED from within a running CP/M session
on Solace.  Type "i"<CR> to start inserting text.  Next, from the Solace
main menu, select the "File/Run Script..." item and select the source
ASCII file.  Magically, ED starts echoing the file as if someone was
rapidly typing it all in.  After the transfer is over, type "E"<CR> to
exit the editor.

Although this technique works only for straight ASCII files, binary
files can be tranferred by first converting them to Intel HEX files,
transferring them as ASCII, then using the CP/M utility "LOAD.COM" to
convert the HEX file back to binary.

Method #3:

The first two methods describe a way to get a file from a PC to Solace.
This one provides a way to get information from Solace back to the PC.  It
basically is method #1 in reverse.

Get the file you want transfered into memory at some location you can
determine.  Fire up the Solace debugger and use the "SAVE" or "SAVEH"
command to dump a range of memory to a file.  Once the transfer is done,
convert the hex file back to a binary file on the host PC.

All-in-all, the IMPORT.COM and EXPORT.COM utilties are a godsend.


********************* Final note *********************

In using import, note carefully that the "-n" in the following usage

    import -n c:\blah.bar blah.bar

means perform cr/lf mangling, while in the interactive mode,

    import
    Convert lf to cr lf .....: N

the "N" means *don't* do the cr/lf mangling.

In using export, note that unlike import, there is no prompting mode.
It is required to specify the filename after the "export" command.