# zx CP/M Command Line Emulator

zx allows execution of CP/M 2.2 and 3.X application from a Windows command line. It is compatible with Windows XP and greater (both 32 and 64 bit).

zx is basically a port of a subset of the zxcc package by John Elliott. The GPLv2 licensing carries forward. Please refer to the zxcc web page for more information.

While the original zxcc package was generally intended to allow execution of the Hi-Tech C CP/M compiler under Unix, zx is slightly more general and intended to allow running most CP/M tools. Specific changes were incorporated to improve interactice console operation of CP/M applications.

## Setup

The zx application (zx.exe) may be copied to any directory for execution. The bios.bin file must be copied to the same directory. For ease of use, you will probably want the directory to part of your PATH environment variable so that you can run the tool from any location.

You will also need the CP/M applications that you want to run. zx will load files fromthe current directory or one of the following directories based on file type. Any of the following environment variables may be defined to determine where zx searches for the respective file types:

- ZXBINDIR may contain a single path which will be searched for executable files (usually *.com)
- ZXLIBDIR may contain a single path which will be search for library files (usually *.lib)
- ZXINCDIR may contain a single path which will be searched for include files (usually *.inc)

## Usage

In general CP/M applications are executed by prefixing the CP/M command line with "zx". So for example, you could assemble a test.asm using rmac with a command line like:

> `zx rmac hello`

In this case, rmac.com would need to be in the directory specified by environment variable ZXBINDIR or in the current directory. Also, hello.asm would need to be in the current directory.

### Filenames

Where you would normally enter a CP/M filename you instead enter a Windows filename. Note that you will need to use a forward slash instead of the traditional backslash as a directory separator. The filename itself (as opposed to any directories in its path) must obey CP/M 8.3 naming conventions.

Where the documentation requires a CP/M drive letter/user number you should enter a path complete with trailing slash, for example:

> `-I/usr/src/linux-80/include/`

## Technical

zx emulates a subset of CP/M 3; hopefully enough to run the most CP/M tools. It can be used as a limited general-purpose CP/M 3 emulator provided the emulated program only uses a common subset of system calls.

Syntax for zx is:

> `zx comfile.com arg1 arg2 ...`

The comfile is the program to run; zx searches the current directory and ZXBINDIR for it.

The arguments are parsed in this way:

- Any argument starting with a - sign is passed to the CP/M program as-is, minus the leading - sign.
- Any argument starting with a + sign is parsed as a filename (see below) and then concatenated to the previous argument.
- Any argument starting "+-" is concatenated without being parsed.
- All other arguments are parsed as filenames. The path is converted to a CP/M driveletter.

For example:

> `zx foo.com --Q -A /src/main --I +/src/sub +-, +/foo/bar`

would pass these arguments to foo.com:

> `-Q A d:main -Id:sub,e:bar`

The other programs are merely wrappers that convert their command lines into the form required by zx.

## Errors

Any errors raised by the zx runtime system will be prefixed with `zx:`. Some errors you may encounter are:

Unsupported BDOS call
  Part of CP/M 3 that the program uses has not been emulated. Add the required functionality to zxbdos.c and recompile.
Z80 encountered invalid trap
  The CP/M program being run attempted to call the zx runtime system with an unknown call number.

## Acknowledgements

- zxcc was written by John Elliott
- Hi-Tech C was written by Hi-Tech Software.
- The Z80 emulation engine was written by Ian Collier.
- Thanks to Jacob Nevins, Andy Parkins and others for bug fix suggestions.