home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / emulate / systems / z80mu / z80mu.doc < prev    next >
Text File  |  1985-12-08  |  196KB  |  5,657 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                  "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide                 "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide
  10.  
  11.                                        or
  12.  
  13.                    The Care and Feeding of Your Imaginary Z80                   The Care and Feeding of Your Imaginary Z80
  14.  
  15.                                        or
  16.  
  17.                          Fakeware For The Techie Masses!                         Fakeware For The Techie Masses!
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                       A Guide to the Complete Z80 Emulator                      A Guide to the Complete Z80 Emulator
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.      Describing the first of a two-part series of 8080, Z80, and CP/M
  36.      emulators for the IBM PC. This document describes Z80MU (version 2.1,                                                       Z80MU
  37.      dated 10/30/85), a software emulation of the Z80 and CP/M 2.2.  The
  38.      second product - if it ever gets out the door - includes hardware
  39.      emulation of the 8080, using the NEC V20 8088-compatible processor
  40.      chip.
  41.  
  42.      Program written by Joan Riff for Computerwise Consulting Services.                        Joan Riff
  43.  
  44.      Placed in the public domain. No copyright notice. No legal mumbo-jumbo.
  45.      No request for a financial contribution. No warrantee. Just a bunch of
  46.      marvelous software magic.
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  57.  
  58.  
  59.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 1
  60.      INTRODUCTION
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.                                   INTRODUCTION                                  INTRODUCTION
  75.  
  76.  
  77.      What is it?      ___________
  78.  
  79.  
  80.      Z80MU is a software emulator of the ZILOG Z80 processor, which runs on
  81.      the IBM PC. It also provides an emulation of Digital Research's CP/M
  82.      version 2.2 operating system. 
  83.  
  84.  
  85.      It includes the following facilities: 
  86.  
  87.           Complete emulation of Z80 object code, including all six
  88.                active bits within the Z80 Flags Register. 
  89.       
  90.           Emulation of CP/M 2.2, with the exception of hardware-specific
  91.                functions. 
  92.       
  93.           Advanced commands for debugging Z80 software (eliminating the
  94.                need for DDT.COM), including: 
  95.       
  96.                Illegal Opcode control (treat 'em as FAULTs or NOPs). 
  97.       
  98.                BDOS function trace. 
  99.       
  100.                Instruction TRACE and NOTRACE, with Z80 PC traceback. 
  101.       
  102.                Breakpoints. 
  103.       
  104.                Dump CP/M memory in HEX and ASCII. 
  105.       
  106.                Patch CP/M memory in HEX, decimal, binary, ASCII charac-
  107.                     ters, or ASCII strings. 
  108.       
  109.                Symbolic labels may be defined and used instead of CP/M
  110.                     addresses. 
  111.  
  112.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  113.  
  114.  
  115.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 2
  116.      INTRODUCTION
  117.  
  118.       
  119.                Z80 register and flag display and alter, including
  120.                     alternate regs/flags and IFF1, IFF2, IMF, I, R regs.
  121.       
  122.                CP/M memory move and find. 
  123.       
  124.                Intel HEX files can be properly read into CP/M memory,
  125.                     as well as created from CP/M memory. 
  126.       
  127.           An "emulated terminal" for full-screen CP/M applications.
  128.       
  129.  
  130.           A full disassembler much like Ward Christensen's RESOURCE,
  131.                built right in, with: 
  132.       
  133.                Symbolic addresses. 
  134.       
  135.                Control breakpoints for Instructions, Bytes (DB), Words
  136.                     (DW), Table of Words (DW), and Storage (DS). 
  137.       
  138.                Automatic label generation. 
  139.       
  140.                Comments associated with Z80 addresses.
  141.       
  142.       
  143.           Online help summaries. 
  144.       
  145.           SUBMIT file support (built right in - no need for SUBMIT.COM).
  146.       
  147.           Access to all PCDOS programs and commands. 
  148.       
  149.           CP/M software reads and writes PCDOS files, and can be
  150.                organized with PCDOS directory structure (instead of
  151.                using CP/M's "user number" idea). 
  152.       
  153.  
  154.      Z80MU (from now on called "the Emulator") can be used quite transpar-
  155.      ently to run CP/M applications on the IBM PC. It contains many advanced
  156.      commands not found in CP/M, but there's no law that says that you have
  157.      to use 'em all. By ignoring the advanced commands, you can run the
  158.      emulated CP/M all day long and you'll swear that you're running CP/M. 
  159.       
  160.      You can also take advantage of the advanced commands and features, and
  161.      have a user interface more powerful than that available with CP/M. 
  162.       
  163.      Advanced Z80 programmers can even ignore CP/M entirely and use the
  164.      Emulator as a generic Z80 development tool for developing device
  165.      controllers and other non-CP/M based Z80 code.
  166.       
  167.  
  168. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  169.  
  170.  
  171.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 3
  172.      INTRODUCTION
  173.  
  174.      At CCS, we use the Emulator to develop things like Z80-based hard disk
  175.      controller card software, device-switching hardware, and even a few
  176.      boring old standard CP/M applications. We have also used it to regen-
  177.      erate the source code for the 32K ROM in the Radio Shack Model 100
  178.      laptop computer, to figure out how it works. 
  179.       
  180.      The Emulator consists of a high-speed 8088 assembler subroutine (which
  181.      does the actual Z80 emulation), and a 'C'-language main program which
  182.      provides the CP/M-like interface to the user, the disassembler, the
  183.      RESOURCE facility, and the rest of the advanced features. 
  184.  
  185.  
  186.      Why Did We Do It?     _________________
  187.  
  188.      At CCS, we have quite an investment in CP/M software. Most of that
  189.      software consists of fairly esoteric software development tools, things
  190.      that are hard to find in the IBM PC world. Furthermore, we continue to
  191.      develop software for the Z80. The old chip just won't die, although
  192.      nowadays it is used more in controller boards than as a primary system
  193.      processor.
  194.  
  195.      We wanted to keep these Z80 tools, yet apply our numerous IBM PC tools
  196.      (especially some fantastic IBM PC editors like SPF/PC) to our Z80
  197.      development process.
  198.  
  199.      We were also keenly interested in creating source code for some object-
  200.      only Z80 applications, with a view to converting them to 8088 assembler
  201.      source code for re-assembly as native IBM PC programs.
  202.  
  203.      We scouted around and discovered several software packages which sup-
  204.      posedly allowed us to run CP/M on the IBM PC. Needless to say, they
  205.      just couldn't cut it. The Heath User's Group (HUG) emulator, 80Mate by
  206.      Vertex, and a few similar packages were considered. We weren't impressed
  207.      by the speed of emulation, or by the accuracy of the emulation, or by
  208.      the user interface. What's more, we kept bumping into more and more
  209.      people who were in the business of Z80 development, and who kept
  210.      badgering us to solve this problem "the right way" (whatever that
  211.      means).
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  225.  
  226.  
  227.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 4
  228.      INTRODUCTION
  229.  
  230.  
  231.      How Does It Work?     _________________
  232.       
  233.      When it runs under PCDOS, the Emulator looks like this: 
  234.       
  235.           +------------------------------------+ 
  236.           | Z80MU 'C' main program             |             Z80MU 'C' main program
  237.           |                                    | 
  238.           | This is what you talk to, the guy  | 
  239.           | that emulates CP/M Console Command | 
  240.           | Processor.                         | 
  241.           |                                    | 
  242.           +------------------------------------+ 
  243.           | Z80 Emulation 8088 Assembler Code  |             Z80 Emulation 8088 Assembler Code
  244.           |                                    | 
  245.           | Which actually emulates the Z80 as | 
  246.           | it "executes" in the CP/M Segment. | 
  247.           |                                    | 
  248.           +------------------------------------+ 
  249.           | 64K CP/M Segment                   |             64K CP/M Segment
  250.           |                                    | 
  251.           | In which the Z80 code is held as   | 
  252.           | it executes. The size of the       | 
  253.           | Transient Program Area is 65022    | 
  254.           | bytes.                             | 
  255.           |                                    | 
  256.           |                                    | 
  257.           |                                    | 
  258.           |                                    | 
  259.           |                                    | 
  260.           |                                    | 
  261.           |                                    | 
  262.           | - - - - - - - - - - - - - - - - - -| 
  263.           | BDOS and BIOS hooks                |             BDOS and BIOS hooks
  264.           |                                    |
  265.           | Which trap CP/M BIOS and BDOS      | 
  266.           | calls, so that they can be         |
  267.           | emulated.                          |
  268.           |                                    |
  269.           +------------------------------------+ 
  270.       
  271.  
  272.      The main program accepts the user's commands, and processes them. When
  273.      and if it comes time to run a Z80 program, the Z80 code is loaded into
  274.      the CP/M Segment, and the 8088 assembler code which actually emulates
  275.      the Z80 is called to run the program there.
  276.  
  277.      As the Z80 program executes, it accesses the outside world via calls to
  278.      the BDOS and BIOS hooks. The code that is executed for a given BDOS or
  279.  
  280.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  281.  
  282.  
  283.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 5
  284.      INTRODUCTION
  285.  
  286.      BIOS function actually resides within the 8088 assembler code that
  287.      emulates the Z80.
  288.       
  289.       
  290.      What Does It Require To Run?      ____________________________
  291.       
  292.      The Emulator runs on the IBM PC under PCDOS 2.x or above. The Emulator
  293.      itself is about 93K in size. The first thing that it does when it runs
  294.      is allocate 64K to be used as CP/M memory (the "CP/M Segment"). 
  295.       
  296.      So you had better have 93K + 64K = 157K available when you run the                            93K + 64K = 157K
  297.      Emulator. Note that the amount of memory required may vary as improved
  298.      versions of the Emulator are released. 
  299.       
  300.      Some CP/M applications expect to control the screen cursor by sending
  301.      control characters through the BDOS. For these programs, you may want
  302.      to have the PCDOS ANSI.SYS device driver loaded via your CONFIG.SYS                       ANSI.SYS
  303.      file.
  304.       
  305.       
  306.      How Accurate an Emulation Is It?      ________________________________
  307.       
  308.      There are two aspects to the accuracy of the Emulator: 
  309.       
  310.           1) How accurately it emulates the Z80 
  311.           2) How accurately it emulates CP/M 
  312.       
  313.      The Emulator emulates the Z80 almost perfectly, even down to an exact
  314.      emulation of all six flag bits in the Flags Register. Even the untest-
  315.      able Half-carry and Add/Subtract flag bits are emulated. For faster
  316.      execution, the Emulator ignores the two unused bits in the Flags
  317.      Register, so these will not act exactly as they would on a real Z80.
  318.  
  319.      Input/Output instructions (the IN's and OUT's) perform everything except
  320.      the actual strobe of the I/O data lines. You can't very well have Z80
  321.      code accessing I/O addresses that mean something entirely different on
  322.      the IBM PC. So the actual data transfer has been disabled. But any
  323.      setup, auto-increment of registers, and flag effects have been emulated
  324.      even for the IN's and OUT's. 
  325.       
  326.      The Z80 HALT instruction is used as a hook to return control to the main
  327.      'C' program, and as a call to the emulated CP/M BIOS and BDOS. 
  328.  
  329.      When it came to emulating CP/M 2.2, we took a less precise approach. We
  330.      weren't interested in emulating the limitations of CP/M. We wanted to
  331.      include many of the benefits of PCDOS. And we wanted to add many more
  332.      "builtin" commands than were available with CP/M. We also demanded the
  333.      largest possible TPA (Transient Program Area - the amount of memory
  334.  
  335.  
  336.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  337.  
  338.  
  339.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 6
  340.      INTRODUCTION
  341.  
  342.      available to be used by a Z80 program). Yet we wanted to keep the
  343.      interface very close to CP/M's.
  344.       
  345.      So we decided to support "standard" CP/M applications, ones that stood a
  346.      good chance of executing on a wide variety of CP/M systems and thus were
  347.      hardware independent. 
  348.       
  349.      This we have succeeded in doing. 
  350.       
  351.      The user interface is just like CP/M's, so that someone used to CP/M
  352.      will feel right at home. 
  353.       
  354.      The program interface (via the BIOS and BDOS) is exactly the same as
  355.      CP/M's. There are some BIOS and BDOS functions that are hardware-
  356.      specific. These are in general not supported. The differences are
  357.      explained in a later section. 
  358.       
  359.      The handling of commands and command arguments (the command "tail")
  360.      appears to the Z80 application exactly as it would on a real CP/M
  361.      system. The default FCB at 5Ch is formatted with the filename implied by
  362.      the first command-line argument, and the FCB at 6Ch with the second
  363.      argument. The byte at 80h is set to the number of characters in the
  364.      command tail, and is followed by an uppercase version of the command
  365.      tail as typed by the user.
  366.       
  367.      We have achieved a TPA size of 65022 bytes. This is more than is
  368.      available on almost all "real" CP/M systems, including the Baby Blue Z80
  369.      add-on board (for the IBM PC) from MicroLog. 
  370.       
  371.      We have also built a terminal emulator into the Emulator, since many
  372.      CP/M applications (especially those doing full-screen editing) assume
  373.      that they are being run from an ASCII terminal.
  374.       
  375.      All in all, the compatability of the Emulator is so good that we have
  376.      been able to move almost all of our CP/M applications to the Emulator,
  377.      and to have them run perfectly (although a tad slow). 
  378.       
  379.      Here is a partial list of CP/M applications that we have tested with the
  380.      Emulator and found to run as they do on a "real" CP/M system: 
  381.       
  382.           ASM 
  383.           LOAD 
  384.           ED
  385.           DDT
  386.           DUMP
  387.           PIP
  388.           M80 
  389.           L80
  390.           LIB
  391.  
  392.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  393.  
  394.  
  395.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 7
  396.      INTRODUCTION
  397.  
  398.           MBASIC 
  399.           LASM 
  400.           MAC 
  401.           dBase II 
  402.           WORDSTAR 3.0 & 3.3 with MAILMERGE (but not SPELSTAR!) 
  403.           PMATE-80 rev. 3.02 
  404.           Software Toolworks 'C' compiler
  405.           Telecon 'C' compiler
  406.           Chang Labs' MemoPlan 
  407.  
  408.  
  409.      This is more a list of the software that we happened to have on hand
  410.      than an exhaustive list of software that will run under the Emulator.
  411.  
  412.  
  413.      What WON'T Run Under the Emulator?     __________________________________
  414.  
  415.      There are some CP/M programs (like STAT.COM provided by Digital Re-
  416.      search) which are hardware-specific. These cannot be run under the
  417.      Emulator, or must be run "carefully" to avoid functions that look to the
  418.      hardware. STAT, for instance, starts out by interrogating the physical
  419.      layout of the diskette. Since this is unsupported under the Emulator,
  420.      STAT is immediately aborted by the Emulator. 
  421.  
  422.      WORDSTAR's SPELSTAR won't work, either. It tries to call CP/M's CCP
  423.      directly. It's really quite sad. It goes to a lot of work to calculate
  424.      just where in Z80 memory the CCP is, relative to the BDOS address held
  425.      in location 0005h. Then it calls that address. Unfortunately, there's
  426.      nothing there...
  427.  
  428.       
  429.       
  430.      How Fast Is It?      _______________
  431.       
  432.      Aye, there's the rub. 
  433.       
  434.      Because the Z80 used by the Emulator is an imaginary one whose instruc-
  435.      tions must be emulated in software, the effective speed of a Z80 program
  436.      is considerably less than the speed of the IBM PC. One 12-cycle Z80
  437.      instruction, for example, may take from 47 to over 100 IBM PC cycles
  438.      (depending on the instruction, its addressing mode, etc). 
  439.       
  440.      For detail on the effective speed of the emulated Z80 and what it means,
  441.      see the description of the "speed?" and "howfast?" Builtin Commands                                 speed?       howfast?
  442.      later in this Guide. 
  443.       
  444.      We have not found the speed of the emulated Z80 to be entirely accept-
  445.      able. Z80MU is the fastest software-based true Z80 emulator available
  446.      today for the IBM PC. Yet we would like to have something that would run
  447.  
  448.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  449.  
  450.  
  451.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 8
  452.      INTRODUCTION
  453.  
  454.      the standard CP/M utilities on an IBM PC at an effective cpu speed of at
  455.      least 1 MegaHertz, and still have all of the subtleties (like flag
  456.      updating) performed with 100% accuracy. 
  457.       
  458.      One solution is to run the Emulator on an IBM PC/AT with a hard disk.
  459.      This is perhaps the best solution, but doesn't help those who don't have
  460.      access to an AT. 
  461.       
  462.      An alternative solution is to use the NEC V20 processor chip in the IBM
  463.      PC, and get rid of the Intel 8088. The NEC V20 is a tad faster than the
  464.      8088. More importantly, it performs full-speed hardware emulation of the
  465.      Intel 8080 chip. Many CP/M utilities do not use the extended instruc-
  466.      tions offered by the Z80, and will run just fine on an 8080 chip. Such a
  467.      hardware-based emulator would offer superior speed. It would, however,
  468.      be limited to 8080 operation. 
  469.       
  470.      We are developing such an emulator. There is no firm release date.
  471.       
  472.      In the meantime, you should equip your IBM PC with a NEC V20 chip to
  473.      speed things up. We paid $16 apiece for ours, and there is no more cost-
  474.      effective hardware upgrade for the IBM PC! See the ads in back of BYTE
  475.      magazine for sources and prices. 
  476.  
  477.       
  478.       
  479.      How Do I Get My CP/M Programs Into The IBM PC?      ______________________________________________
  480.       
  481.      Assuming that you want to emulate some CP/M applications on the IBM PC,
  482.      the first realization is that these CP/M files don't already reside on
  483.      the PC. What's more, they currently exist (by definition) on disks
  484.      formatted for CP/M, not for the IBM PC. So they can't be read by a
  485.      vanilla IBM PC using PCDOS. They must be copied to standard PCDOS disk
  486.      files. 
  487.       
  488.      We have used several approaches, all with excellent results. 
  489.       
  490.      The first approach is to transfer the CP/M files straight from the CP/M
  491.      disks to PCDOS disks using a utility that runs on the IBM PC and is
  492.      capable of reading the foreign CP/M format. Such utilities include:
  493.       
  494.           CONVERT  (from Selfware, Inc.  Fairfax, VA)           CONVERT
  495.           XENOCOPY (from Vertex Systems, Inc.  L.A., Calif)           XENOCOPY
  496.       
  497.  
  498.      This approach is nice, when it works. The major disadvantages are:
  499.  
  500.           Only certain CP/M formats are recognized by each of these
  501.                utilities. Apple ][ and NorthStar Horizon CP/M disks, for
  502.  
  503.  
  504.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  505.  
  506.  
  507.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 9
  508.      INTRODUCTION
  509.  
  510.                example, cannot be read on the IBM PC without special
  511.                hardware.
  512.  
  513.           You must have the CP/M disks at hand. 
  514.       
  515.      Another approach is to transfer the CP/M files to the IBM PC via a
  516.      communications line. This is Joan Riff's personal favorite. If the
  517.      CP/M system is at hand, then the two machines are direct-connected and
  518.      cranked up to 9600 baud. If the CP/M system is not handy, then the
  519.      transfer is made over the phone at whatever speeds the respective modems
  520.      can handle. In either case, the CP/M system running BYE and XMODEM is
  521.      controlled by the IBM PC running Crosstalk VI version 3.5 (from Micro-
  522.      Stuf) and Joan Riff's excellent XMODEM (with CRC) Crosstalk RUN command.
  523.  
  524.       
  525.      When direct connected, files really fly across at 9600 baud. 
  526.       
  527.      The major advantages of this approach are: 
  528.       
  529.           Who cares what the CP/M disk format is? If the CP/M system can
  530.                read its own files, then we can get them. This works very
  531.                well when transferring Apple ][ and NorthStar Horizon
  532.                CP/M files. 
  533.  
  534.           Public Domain CP/M software can be gathered just by dialing
  535.                into a CP/M Bulletin Board or RCPM system. You need never
  536.                know what hardware system is on the other end. 
  537.       
  538.       
  539.      CP/M and PCDOS files are similar enough that we have never had to alter
  540.      a file that was transferred using either of the above two approaches.
  541.      We just download the files to the IBM PC and run 'em under the Emulator.
  542.       
  543.      The biggest problem is remembering which files are PCDOS files and
  544.      which are CP/M files. If you transfer a CP/M file called DUMP.COM, for
  545.      example, from a CP/M system to the IBM PC's disk, you really do want to
  546.      remember that it is a CP/M file (to be run with the Emulator) and not an
  547.      IBM PC .COM file. If you accidentally invoke DUMP.COM from PCDOS, you
  548.      will be unpleasantly surprised. The CP/M DUMP.COM file contains Z80
  549.      opcodes, which will be executed by the IBM PC as 8088 opcodes. Time to
  550.      reach for the Big Red Switch... 
  551.       
  552.      You must run such CP/M command (.COM) files under the Emulator!          must
  553.       
  554.      At CCS, we keep things straight by storing CP/M files under separate
  555.      PCDOS directories. The "Z80PATH" environment string (explained else-
  556.      where) makes this particularly convenient. 
  557.       
  558.  
  559.  
  560. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  561.  
  562.  
  563.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 10
  564.      INTRODUCTION
  565.  
  566.      The saving grace to this CP/M-to-PCDOS conversion is that it needs to be
  567.      done only once for a given file. We spent quite a while transferring 10
  568.      megabytes of CP/M files to the IBM PC. But we need never do it again.
  569.      Now we just run everything on the IBM PC. 
  570.  
  571.  
  572.  
  573.      How Do I Run It?      _________________
  574.       
  575.      The Emulator is just another PCDOS program. There are no arguments to
  576.      give it. There is no syntax. Just type 
  577.       
  578.           Z80MU           Z80MU
  579.       
  580.      and bingo! - you're in CP/M.          bingo!
  581.       
  582.      To make things easier, you may want to copy Z80MU.EXE to one of your
  583.      PCDOS "PATH" directories (if you have any). If you don't have any PATH
  584.      directories set up, then just insert the floppy that holds Z80MU, start
  585.      the program, and then remove the floppy. You don't need it until you
  586.      want to run the Emulator again. 
  587.       
  588.      The next section ("The PCDOS Environment") describes the PCDOS environ-
  589.      ment that applies to the Emulator. You may want to study it before you
  590.      run the thing. 
  591.  
  592.       
  593.       
  594.      What Can Go Wrong?     __________________
  595.  
  596.      The Emulator is as safe a program as ever you'll find on the IBM PC.
  597.      You will probably never experience any problem with it.
  598.  
  599.      There is one important thing to watch out for, however:
  600.  
  601.           If the Emulator itself is ever aborted, then you should          If the Emulator itself is ever aborted, then you should
  602.           immediately reboot your IBM PC.          immediately reboot your IBM PC.
  603.  
  604.      Why? Because the Emulator must trap the IBM PC's BREAK interrupt. When
  605.      the Emulator returns to PCDOS (via the "exit" command), it restores this                                             exit
  606.      interrupt the way it was before. If the Emulator never gets a chance to
  607.      exit gracefully, then it never gets a chance to restore this interrupt.
  608.      The thing is left pointing to now-dead code somewhere in the IBM PC's
  609.      memory. This is bad news for you, and good news for that big red switch
  610.      on the side of your PC...
  611.  
  612.  
  613.  
  614.  
  615.  
  616.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  617.  
  618.  
  619.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 11
  620.      INTRODUCTION
  621.  
  622.      Why might the Emulator abort? Well, there is always the possibility of                                               is
  623.      an Emulator bug that we haven't found. But the most likely reason is a
  624.      disk error that results in the familiar message:
  625.  
  626.                               Abort, Retry, Ignore?                              Abort, Retry, Ignore?
  627.  
  628.      If you select Abort, then you've just aborted the Emulator and left the                   Abort
  629.      BREAK interrupt in limbo. So reboot to be safe.
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  673.  
  674.  
  675.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 12
  676.      THE PCDOS ENVIRONMENT
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.                              THE PCDOS ENVIRONMENT                              THE PCDOS ENVIRONMENT                                                    
  691.  
  692.      The Z80 Emulator runs as a normal application program under PCDOS
  693.      (version 2.0 and above). There are a few things that you should keep in
  694.      mind, in order to get the most out of the Emulator. 
  695.  
  696.       
  697.      PCDOS's use of COMMAND.COM      __________________________
  698.  
  699.      Certain Emulator commands ("dir", "!xxxxxx", etc) are handled by calling                                 dir    !xxxxxx
  700.      PCDOS to perform the associated operation. The first thing that PCDOS
  701.      does when called in this way is reload its COMMAND.COM file from disk.
  702.      To speed things up, you should make sure that PCDOS's COMMAND.COM file
  703.      is in a RAMdisk, or on a hard disk. You can tell PCDOS where to find
  704.      COMMAND.COM by using the "SET COMSPEC=" command in your AUTOEXEC.BAT
  705.      file. 
  706.       
  707.      Certain versions of PCDOS (2.0 and 2.1, and maybe others) have trouble
  708.      obeying the "COMSPEC=" command. They try to reload COMMAND.COM from the
  709.      boot disk, regardless of the current "COMSPEC=" parameter. If you use
  710.      one of these versions of PCDOS, then you may avoid problems by keeping
  711.      COMMAND.COM always available on the boot drive. Alternatively, you may
  712.      apply one of the public domain COMZAP patches to fix your copy of PCDOS.
  713.  
  714.       
  715.      The "Z80PATH=" Environment String     _________________________________
  716.  
  717.      The Emulator has a facility which is equivalent to the PCDOS "PATH"
  718.      command. It allows you to tell the Emulator where to look for Z80
  719.      command (.COM) files. 
  720.       
  721.      This facility is implemented by a new PCDOS environment string, called
  722.      "Z80PATH". This string is a list of fully-qualified names of directories
  723.      which are to be searched when the Emulator is looking for a .COM file to
  724.      load and run. The various directory names must be separated with
  725.      semicolon (";") characters, as follows: 
  726.       
  727.  
  728. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  729.  
  730.  
  731.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 13
  732.      THE PCDOS ENVIRONMENT
  733.  
  734.  
  735.           SET Z80PATH=c:\cpm;c:\z80\mystuff;c:\           SET Z80PATH=c:\cpm;c:\z80\mystuff;c:\
  736.  
  737.      This example tells the Emulator to search for Z80 programs first in the
  738.      directory "CPM" on drive C:, and then (if not found there) in the
  739.      directory "Z80\MYSTUFF" on drive C:, and finally (if still not found) in
  740.      the root directory of drive C:. 
  741.       
  742.      A Z80PATH string should be defined in your AUTOEXEC.BAT file, so that
  743.      it is always present when you run the Emulator.
  744.  
  745.      The trailing "\" character of each directory name is optional. If it is
  746.      absent, a "\" character is automatically applied to the directory name
  747.      before the name is used in the search.
  748.       
  749.      The Z80PATH search order is used whenever an "unqualified" program name
  750.      is used as a command to the Emulator. An "unqualified" program name is a
  751.      legal filename (up to 8 characters) which: 
  752.       
  753.           1) has no drive ID on the front of it (no ":" character), and
  754.           2) has no directory names imbedded in it (no "\" characters), and 
  755.           3) is not the name of an Emulator Builtin Command.
  756.  
  757.      For example, let's say that you give the following command to the
  758.      Emulator: 
  759.       
  760.           Z80 A>asm dump.aaz                 asm dump.aaz
  761.  
  762.      The Emulator first checks to see if the command ("ASM") is one that it
  763.      recognizes - a so-called Builtin Command (see the "Builtin Commands"
  764.      section). If it is not, then the Emulator acts just like CP/M and
  765.      attaches a .COM extension to the command, yielding "ASM.COM". It then
  766.      looks in the current PCDOS directory on the current disk (in this case,
  767.      drive A:) for a file by the name of ASM.COM. If it finds such a file,
  768.      then it loads it into the CP/M Segment and runs it. 
  769.       
  770.      If the file is not found on the current drive, then the Emulator
  771.      searches the various Z80PATH directories, looking for a file with the
  772.      right name (ASM.COM). The directories are searched in the order that
  773.      they appear in the Z80PATH string. The first ASM.COM file that is found
  774.      is the one loaded and run. 
  775.       
  776.      If there is no Z80PATH string defined in the PCDOS environment, then the
  777.      search stops with the current disk drive's current PCDOS directory. 
  778.       
  779.      If no matching filename is found after all of this, then the Emulator
  780.      echos the command line
  781.  
  782.           asm? 
  783.  
  784.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  785.  
  786.  
  787.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 14
  788.      THE PCDOS ENVIRONMENT
  789.  
  790.  
  791.  
  792.      indicating that it doesn't know what you mean. 
  793.  
  794.      Note that no search takes place if the command is "qualified". A
  795.      "qualified" command includes a drive ID or a pathname, such as:
  796.  
  797.           Z80 A>b:asm dump.aaz                b:asm dump.aaz
  798.           Z80 A>\bin\asm dump.aaz                \bin\asm dump.aaz
  799.  
  800.      In such a case, the Emulator tries only once to open the Z80 .COM file,
  801.      using the exact name given. If such a file cannot be found, then the
  802.      command fails as mentioned above.
  803.  
  804.  
  805.  
  806.      The AUTOEXEC.Z80 File     _____________________
  807.  
  808.      When the Emulator first starts up, it automatically executes the
  809.      following command:
  810.  
  811.           Z80 A>SUBMIT AUTOEXEC.Z80                SUBMIT AUTOEXEC.Z80
  812.  
  813.      If there is no file by the name of AUTOEXEC.Z80 in the current directory
  814.      when the Emulator is run, then an error message is displayed and the
  815.      Emulator just waits for you to enter commands from the keyboard.
  816.  
  817.      If there is such a file, however, then the Emulator reads its commands              is
  818.      from that file, until EOF. See the "submit" builtin command for more                                         submit
  819.      details about submit files.
  820.  
  821.      This is an easy way to automate the Emulator. At CCS, we use a different
  822.      AUTOEXEC.Z80 file in each work directory in order to set up the parti-
  823.      cular environment that we want to work with. The AUTOEXEC.Z80 file
  824.      within the Radio Shack Model 100 directory, for example, automatically
  825.      reads in the 64K Model 100 image from disk ("read 0 model100.mem"), and                                                  read 0 model100.mem
  826.      the disassembler control file ("control read model100.ctl"). It also                                     control read model100.ctl
  827.      sets up the disassembler format that we want ("list include A O"). So                                                    list include A O
  828.      when we start up the Emulator while within that directory, the thing
  829.      comes up ready to do real work.
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  841.  
  842.  
  843.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 15
  844.      THE PCDOS ENVIRONMENT
  845.  
  846.  
  847.      I/O Redirection With The Emulator      __________________________________
  848.       
  849.      The Emulator reads its commands from the standard input as defined by
  850.      PCDOS. It writes its output to the standard output that is defined by
  851.      PCDOS. So regular old PCDOS I/O redirection can be used when you start
  852.      the Emulator. 
  853.       
  854.      For example, the following PCDOS command can be used to run the Emulator
  855.      and capture all Emulator output to file OUTPUT.DOC: 
  856.  
  857.           Z80MU >OUTPUT.DOC           Z80MU >OUTPUT.DOC
  858.  
  859.      You may also append output to an existing file with:
  860.  
  861.           Z80MU >>OUTPUT.DOC           Z80MU >>OUTPUT.DOC
  862.  
  863.      And the following can be used to have the Emulator read all of its
  864.      commands from the file INPUT.BAT: 
  865.       
  866.           Z80MU <INPUT.BAT           Z80MU <INPUT.BAT
  867.       
  868.      You may combine input and output redirection, as follows: 
  869.       
  870.           Z80MU <INPUT.BAT >OUTPUT.DOC           Z80MU <INPUT.BAT >OUTPUT.DOC
  871.       
  872.      This is perfect for automating the Emulator. Some of the samples
  873.      displayed later in this document were captured by redirecting the
  874.      Emulator's output to a file, and then editing that file into this
  875.      document. 
  876.       
  877.      There are a few things to bear in mind, however. 
  878.       
  879.      First of all, remember that there are several parts of the Emulator:
  880.  
  881.       
  882.           The main program, which reads your commands and in general          The main program
  883.           acts like the CP/M CCP. It does all I/O via PCDOS, so it is
  884.           subject to I/O redirection. 
  885.        
  886.           The actual Z80 emulator, which does no I/O at all.          The actual Z80 emulator
  887.        
  888.           The CP/M BIOS emulator. It does I/O at the IBM PC ROM BIOS          The CP/M BIOS emulator
  889.           level, so PCDOS never sees what's going on. CP/M BIOS terminal
  890.           I/O goes through the emulated "terminal" inside the Emulator,
  891.           and then straight to the IBM PC screen. So I/O redirection
  892.           does not apply there. 
  893.       
  894.  
  895.  
  896. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  897.  
  898.  
  899.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 16
  900.      THE PCDOS ENVIRONMENT
  901.  
  902.  
  903.           The CP/M BDOS emulator. The BDOS emulator does its I/O via PCDOS,          The CP/M BDOS emulator
  904.           so I/O redirection does apply to it, and to any Z80 programs that
  905.           use BDOS functions for I/O. 
  906.  
  907.  
  908.      Now the question arises: Will my CP/M application obey any I/O redirec-
  909.      tion that I specify when I run the Emulator? 
  910.       
  911.      The answer, of course, depends on your application. 
  912.       
  913.      Most "standard" CP/M applications do their I/O via BDOS functions. So
  914.      these will obey your I/O redirection. 
  915.       
  916.      Full-screen editors, in general, use the BIOS instead of the BDOS, for a
  917.      lot of very good reasons. So these will automatically be exempt from
  918.      your I/O redirection. 
  919.  
  920.      When constructing a file to be read via input redirection, remember to
  921.      include all characters that are to be read either by the Emulator itself
  922.      or by the CP/M application. This usually means that your input file will
  923.      be a jumbled mix of Emulator and application input. 
  924.       
  925.      Let's say, for example, that you have a CP/M application named TEST.COM
  926.      that asks for your name, prints some silly message based upon your name,
  927.      and then exits back to CP/M. A complete input file to execute that
  928.      program would look like this: 
  929.       
  930.           test          test           (Emulator command to run TEST.COM) 
  931.           Joan Riff          Joan Riff      (Input to CP/M application program) 
  932.           exit          exit           (Emulator command to exit back to PCDOS) 
  933.       
  934.       
  935.      If this text is saved on a file called AUTONAME, we can run the Emula-
  936.      tor, tell it to run TEST.COM, answer TEST's question, and then exit the
  937.      Emulator back to PCDOS by entering the following PCDOS command: 
  938.       
  939.           Z80MU <AUTONAME           Z80MU <AUTONAME
  940.       
  941.       
  942.      Please remember that all Emulator input and/or all Emulator output is                          all                       all
  943.      redirected at once. If you redirect the output only, meaning to enter
  944.      commands from the keyboard, don't be real surprised if you can't see any
  945.      of the Emulator's prompts. They are being written to the redirected
  946.      output file, and not to the screen. 
  947.  
  948.           NOTE: When you redirect output to a disk file, your input
  949.           keypresses are supposed to be sent to the output file (not to
  950.           the screen). Some versions of PCDOS, however, contain a bug
  951.  
  952.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  953.  
  954.  
  955.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 17
  956.      THE PCDOS ENVIRONMENT
  957.  
  958.  
  959.           that causes your keypresses to appear on the screen instead.
  960.           We have seen public domain patches to fix this bug floating
  961.           around the Bulletin Boards, but can't vouch for any of them. 
  962.  
  963.           ALSO: Input that comes from Input I/O Redirection is not
  964.           echoed, so you won't see it anywhere. Input from submit                                                           submit
  965.           files, however, IS echoed.
  966.  
  967.       
  968.      Using The Keyboard      __________________
  969.       
  970.      As mentioned previously, the Emulator reads its input from the standard
  971.      input as defined by PCDOS. So if you don't redirect the input to the
  972.      Emulator, then input comes from the keyboard. 
  973.       
  974.      The Emulator could have done its own direct keyboard and screen I/O.
  975.      This would speed things up considerably. PCDOS is notoriously slow when
  976.      it comes to writing to the screen. 
  977.       
  978.      We decided, however, not to circumvent PCDOS when writing to the screen
  979.      and reading from the keyboard. The Emulator is slower as a result. But
  980.      we gain a few conveniences as a result: 
  981.       
  982.           We achieve something closer to true CP/M emulation, 'cause
  983.           PCDOS automatically handles ^P and ^S/^Q in a manner close to
  984.           CP/M's handling of them. 
  985.       
  986.           We get automatic I/O redirection. 
  987.       
  988.           We get PCDOS expanding macro keys and interpreting function
  989.           keys. 
  990.       
  991.       
  992.      The F3 key, for instance, can still be used to repeat the last command
  993.      entered to the Emulator. The ESC key cancels the current input line. And
  994.      F1 recreates the last command one character at a time. Other PCDOS
  995.      keyboard conventions (like Ctrl-NumLock, Ctrl-PrtSc, and so on) are also
  996.      handled by PCDOS in a way that we're all used to. 
  997.       
  998.      The addition of keyboard enhancers like CED and Sidekick can confuse
  999.      things, so that the function keys don't act quite right. You'll just
  1000.      have to experiment with it.
  1001.  
  1002.      If you want to copy screen output to the printer, then press ^P or
  1003.      Ctrl-PrtSc. A second press will turn printer echo off. Remember that
  1004.      such PCDOS redirection applies to Emulator output (like dumps, disassem-
  1005.      blies, etc) as well as to the output of any CP/M applications being run
  1006.      under the Emulator that use BDOS functions for output.
  1007.  
  1008.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1009.  
  1010.  
  1011.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 18
  1012.      THE PCDOS ENVIRONMENT
  1013.  
  1014.  
  1015.       
  1016.      If text is scrolling off of the screen too fast to read (not real
  1017.      likely, with PCDOS being as slow as it is), you can pause and restart it
  1018.      with ^S/^Q, or Ctrl-NumLock. 
  1019.  
  1020.      The actions of ^S/^Q, ^P and Ctrl-PrtSc may vary, depending on the
  1021.      particular CP/M application being run. CP/M's BDOS function number 6
  1022.      (Direct Console I/O), for example, is handled by CP/M without it
  1023.      checking for ^S or ^P. The Emulator mimics this action.
  1024.  
  1025.  
  1026.      Filenames!     __________
  1027.  
  1028.      CP/M filenames may contain certain characters that PCDOS objects to. In
  1029.      general, don't use the "\" or "/" characters in filenames, or the I/O
  1030.      redirection characters ">" and "<", and so on.
  1031.  
  1032.      And watch out for PCDOS device names that are perfectly innocent
  1033.      filenames under CP/M. Things like "CON.ASM" will fool you.
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1065.  
  1066.  
  1067.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 19
  1068.      THE CP/M ENVIRONMENT
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.                               THE CP/M ENVIRONMENT                              THE CP/M ENVIRONMENT
  1084.  
  1085.  
  1086.      This section describes the environment set up by the Emulator, under
  1087.      which your Z80 programs will run.
  1088.  
  1089.  
  1090.  
  1091.      Emulated Terminal      __________________
  1092.       
  1093.      If a Z80 program does character I/O by invoking CP/M BDOS functions (not
  1094.      BIOS calls), then its input and output come from PCDOS, and this section
  1095.      does not apply. 
  1096.       
  1097.      When a Z80 program does character I/O by calling the emulated CP/M BIOS
  1098.      (not using BDOS functions, but BIOS calls), then it is communicating
  1099.      with an imaginary, emulated ASCII terminal which is maintained by the
  1100.      Emulator. The Emulator interprets ASCII codes that are sent to this
  1101.      "terminal", and translates them into appropriate calls to the IBM ROM to
  1102.      control the IBM's display. 
  1103.       
  1104.      Most ASCII characters that are sent to the emulated "terminal" are
  1105.      displayable characters - letters, numbers, and so on. They appear on the
  1106.      screen for the user to read. Other ASCII characters - called "control
  1107.      sequences" - are used not to display anything, but to cause the "ter-
  1108.      minal" to perform special functions like clearing the screen, switching
  1109.      between high- and low-intensity, and so on. 
  1110.  
  1111.      The builtin "terminal" obeys VT52 control sequences, which are the                                  VT52 control sequences
  1112.      same ones used by the Heath/Zenith H19 and H89 machines when in ZDS                           Heath/Zenith H19     H89
  1113.      mode. They are as follows:
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1121.  
  1122.  
  1123.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 20
  1124.      THE CP/M ENVIRONMENT
  1125.  
  1126.  
  1127.  
  1128.           ESC H Homes cursor           ESC H
  1129.  
  1130.           ESC C Advances cursor 1 char to right. Stays on same line.           ESC C
  1131.       
  1132.           ESC D Backspaces cursor one char to left. Stays on same line.           ESC D
  1133.  
  1134.           ESC B Moves cursor down 1 line, staying in same column. Screen          ESC B
  1135.                is scrolled if necessary.
  1136.       
  1137.           ESC A Moves cursor up 1 line, staying in same column. No          ESC A
  1138.                scrolling occurs. 
  1139.       
  1140.           ESC I (uppercase letter "I", HEX 049h) Moves cursor up 1 line,          ESC I
  1141.                staying in same column. Scrolling occurs if cursor was on
  1142.                top line. 
  1143.       
  1144.           ESC n Causes current cursor position to be returned via          ESC n
  1145.                emulated "keyboard" as ESC Y line# column#. This control                                                           ____________
  1146.                sequence is ignored (not supported) by the Emulator.               ____________________________________________________
  1147.       
  1148.           ESC j Saves cursor position for later restore via ESC k.           ESC j
  1149.       
  1150.           ESC k Returns cursor to position that was saved via ESC j.           ESC k
  1151.  
  1152.           ESC Y line# column# Direct cursor addressing sequence. Screen          ESC Y line# column#
  1153.                lines are numbered 1 to 25. Screen columns are numbered 1
  1154.                to 80. Line# and column# args are obtained by adding 31
  1155.                (01Fh) to the desired line or column number. Alternative-
  1156.                ly, you may think of lines as being numbered from 0 to
  1157.                24, columns from 0 to 79, and the offset to add to each
  1158.                being 32 (020h).
  1159.  
  1160.                To position to line 5, column 10, for example, the
  1161.                following is sent: 
  1162.       
  1163.                ESC Y $ )                ESC Y $ )
  1164.       
  1165.                which is represented in HEX as 01Bh 059h 024h 029H and in                                              01Bh 059h 024h 029H
  1166.                decimal as 27 89 36 41. Note that the line# arg is                          27 89 36 41
  1167.                obtained by 5 + 31 = 36 (024h), and the column# arg by 10                                    36
  1168.                + 31 = 41 (029h).                       41
  1169.       
  1170.                Line# or column# args less than 32 default to 32 (i.e. -
  1171.                to line or column 1). An arg value that is too large
  1172.                defaults to the max legal value (25 for line, 80 for
  1173.                column). 
  1174.  
  1175.  
  1176.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1177.  
  1178.  
  1179.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 21
  1180.      THE CP/M ENVIRONMENT
  1181.  
  1182.  
  1183.           ESC F Erases the entire screen and homes the cursor.           ESC F
  1184.       
  1185.           ESC b Erases from the start of the screen to the cursor,          ESC b
  1186.                including the cursor position. 
  1187.       
  1188.           ESC J Erases from the cursor to the end of the screen (inclu-          ESC J
  1189.                ding the cursor position). 
  1190.       
  1191.           ESC l (lowercase letter "L", HEX 06Ch) Erases the entire line          ESC l
  1192.                that the cursor is on, positions the cursor to the left
  1193.                edge of that line. 
  1194.  
  1195.           ESC o (lowercase letter "O", HEX 06Fh) Erases from the          ESC o
  1196.                beginning of the line to the cursor (including the cursor
  1197.                position). 
  1198.       
  1199.           ESC K Erases from the cursor to the end of the line (including          ESC K
  1200.                the cursor position). 
  1201.       
  1202.           ESC L Inserts a blank line before the line that the cursor is          ESC L
  1203.                on, shifts following lines (including the cursor line)
  1204.                down to make room. Cursor is moved to start of new blank
  1205.                line. 
  1206.       
  1207.           ESC M Deletes the line that the cursor is on, scrolls follow-          ESC M
  1208.                ing lines up to fill its place. Cursor moves to left edge
  1209.                of its line. 
  1210.       
  1211.           ESC N Deletes the character under the cursor, shifts remaining          ESC N
  1212.                text to left to cover it up. 
  1213.       
  1214.           ESC @ (At-sign character, HEX 040h) Enters Insert Mode.          ESC @
  1215.                Displayed characters cause others on the same line to be
  1216.                moved right to make room. This can be pretty pokey,
  1217.                thanks to the IBM ROM BIOS!
  1218.  
  1219.           ESC O (uppercase letter "O", HEX 04Fh) Exits Insert Mode.           ESC O
  1220.  
  1221.           ESC p Enters Reverse Video or Highlight mode.          ESC p
  1222.  
  1223.           ESC q Exits Reverse Video or Highlight mode.          ESC q
  1224.  
  1225.           BEL (decimal 7) Beeps bell.           BEL
  1226.       
  1227.           BS (decimal 8) Backspaces cursor one character position.           BS
  1228.  
  1229.           HT (decimal 9) Tabs cursor to next mod-8 column boundary          HT
  1230.  
  1231.  
  1232.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1233.  
  1234.  
  1235.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 22
  1236.      THE CP/M ENVIRONMENT
  1237.  
  1238.  
  1239.           LF (decimal 10, HEX 0Ah) Advances cursor to next line, same          LF
  1240.                column. 
  1241.  
  1242.           FF (decimal 12, HEX 0Ch) Clears screen and homes cursor.           FF
  1243.  
  1244.           CR (decimal 13, HEX 0Dh) Returns cursor to start of current          CR
  1245.                line. 
  1246.  
  1247.  
  1248.       
  1249.      The other standard ASCII control characters (below 032 or 20h) and those
  1250.      from 128 (80h) through 255 (FFh) display various graphic symbols. See
  1251.      the IBM Tech Ref Manual for details. 
  1252.       
  1253.      The emulated VT52 "terminal" also translates input from the IBM key-
  1254.      board. Most keypresses are returned to the Z80 program as single ASCII
  1255.      characters. The "extended" codes that are generated by IBM function
  1256.      keys, arrow keys, ALT keys, and so on, are translated into 2-byte
  1257.      keyboard sequences as follows: 
  1258.  
  1259.           The first byte is an ESCAPE character (Decimal 027, HEX 1Bh).                               ESCAPE
  1260.  
  1261.           The second byte is the keyboard scan code, as defined in the                                 keyboard scan code
  1262.           IBM Tech Ref Manual. 
  1263.       
  1264.      Additionally, the NUL extended code (CTRL-@) is translated into a                       NUL
  1265.      single ASCII character (Decimal 000). 
  1266.       
  1267.      For example, assume that the user presses the PgUp key on the IBM
  1268.      keyboard. The next time that the Z80 program calls the CP/M BIOS to read
  1269.      a keypress from the "terminal", an ESCAPE character will be returned.
  1270.      The time after that, a Decimal 073 (HEX 49h) will be returned. This is
  1271.      the scan code for the PgUp key. 
  1272.       
  1273.       
  1274.      The above information may be used to configure particular Z80 applica-
  1275.      tions for use with the Emulator's "terminal".  Remember that this
  1276.      emulated "terminal" only appears at the CP/M BIOS interface. Applica-
  1277.      tions that do I/O via BDOS functions (which includes most of the
  1278.      standard CP/M utilities) do not see this behavior. 
  1279.       
  1280.      WORDSTAR, dBase II, Target Plannercalc  and PMATE, for example, do at
  1281.      least some of their terminal I/O via the CP/M BIOS, so they must be
  1282.      configured for the particular terminal being used. Refer to the above
  1283.      information when installing such applications for use under the Emula-
  1284.      tor, using this emulated VT52 "terminal". Please bear in mind, however,
  1285.      that things can get very confusing when one application (like dBase II)
  1286.  
  1287.  
  1288.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1289.  
  1290.  
  1291.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 23
  1292.      THE CP/M ENVIRONMENT
  1293.  
  1294.  
  1295.      does terminal I/O via both the BIOS and the BDOS. Just experiment until
  1296.      you get something useful.
  1297.  
  1298.           NOTE: This emulated terminal facility may be enabled and
  1299.           disabled via the "terminal" builtin command, which is des-                            terminal
  1300.           cribed in the "Builtin Commands" section.
  1301.  
  1302.       
  1303.      ^C and BREAK Handling      _____________________
  1304.       
  1305.      The ^C (Ctrl-C) and BREAK (Ctrl-Scroll Lock) keys are handled in a
  1306.      special way on the IBM PC. Under normal circumstances, these keypresses
  1307.      are trapped by PCDOS and cause the executing PCDOS program (in this
  1308.      case, the Emulator) to be aborted. 
  1309.       
  1310.      This is undesirable. 
  1311.       
  1312.      Additionally, CP/M includes an important assumption, to wit: ^C is a
  1313.      keypress like any other, and must be passed through all the way to the
  1314.      Z80 program for processing. Several standard CP/M programs (PIP.COM,
  1315.      M80.COM, WORDSTAR, etc) use ^C as a command, and must not be aborted                                                      must not
  1316.      when it is typed. 
  1317.  
  1318.      For this reason, the Emulator traps ^C and BREAK keypresses. It decides
  1319.      what to do with them as follows: 
  1320.       
  1321.           When not running a Z80 program (i.e. - when the Emulator is
  1322.                accepting commands), the BREAK key does nothing and the ^C
  1323.                keypress does various things depending on the mood of PCDOS. 
  1324.       
  1325.           When executing a Z80 program, pressing ^C causes a ^C character
  1326.                (Decimal 003) to be queued as keyboard input. Pressing BREAK
  1327.                causes the Z80 to be stopped (with an appropriate message),
  1328.                and a return to the Emulator awaiting your command.
  1329.  
  1330.                NOTE: If the Z80 program is in the process of reading a
  1331.                line of keyboard input when you press BREAK, then you
  1332.                may have to press RETURN (to terminate that read) before
  1333.                the BREAK will be recognized.
  1334.  
  1335.  
  1336.      When the Emulator stops ("aborts") a Z80 program due to a BREAK key-
  1337.      press, it displays a message to that effect. It suspends the Z80 in
  1338.      perfect order, maintaining all registers, flags, etc. It then accepts
  1339.      Emulator commands. 
  1340.       
  1341.      At this point you may inspect registers, run another Z80 program, or
  1342.  
  1343.  
  1344.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1345.  
  1346.  
  1347.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 24
  1348.      THE CP/M ENVIRONMENT
  1349.  
  1350.  
  1351.      whatever. You may also continue execution of the aborted program with
  1352.      the "go" command.           go
  1353.       
  1354.      This is a very powerful tool for debugging, which is not available with
  1355.      true (hardware) Z80 systems. You may in effect interrupt the Z80 at any                                                                         any
  1356.      point, actually pausing it between Z80 instructions. 
  1357.       
  1358.      This also maintains compatability with existing CP/M programs that want
  1359.      to read the ^C character. To exit PIP, for example, you need only press
  1360.      ^C and then RETURN. This ^C is passed to PIP, who interprets it as a
  1361.      request to exit the program. 
  1362.       
  1363.      Note that RETURN must be pressed after the ^C in some cases (like when
  1364.      entering a command line into PIP). This is one area of PCDOS-CP/M
  1365.      incompatability, for which Joan Riff offers her apologies. A Z80
  1366.      program (like PIP) that requests a line of input from CP/M won't see the
  1367.      ^C until the entire line is terminated with RETURN. A Z80 program that
  1368.      asks for one character at a time, however, will see the ^C immediately. 
  1369.  
  1370.           NOTE: When running PCDOS commands like type, dir, and so on,                                                 type  dir
  1371.           the BREAK key is unavailable to you. If you want to interrupt
  1372.           the output from such programs that are run "underneath" the
  1373.           Emulator, you will have to use the ^C key.
  1374.       
  1375.       
  1376.           
  1377.      Common PCDOS and CP/M File System      _________________________________
  1378.       
  1379.      The Emulator goes to great lengths to allow CP/M programs to read and
  1380.      write PCDOS files. Thus the PCDOS file system serves as a common
  1381.      environment for both PCDOS and CP/M files. This allows you to use your
  1382.      favorite IBM PC editor, for example, to edit source files that are then
  1383.      compiled within CP/M (using the Emulator) with ASM.COM, M80.COM,
  1384.      F80.COM, or whatever. 
  1385.       
  1386.      CP/M's "User Number" concept, however, is primitive compared to the
  1387.      directory structure available with PCDOS. So although the emulated BDOS
  1388.      supports the setting of a user number, the user number is ignored by the
  1389.      Emulator when it comes time to actually access files. 
  1390.       
  1391.      Likewise, the concept of a Read-Only disk drive is not necessary under
  1392.      the Emulator. And the fatal CP/M flaw that crops up when you change
  1393.      disks and forget to type ^C to Warm Boot the system has been virtually
  1394.      eliminated by PCDOS. 
  1395.  
  1396.  
  1397.      CP/M and its CCP (or lack of them)      __________________________________
  1398.       
  1399.  
  1400. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1401.  
  1402.  
  1403.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 25
  1404.      THE CP/M ENVIRONMENT
  1405.  
  1406.  
  1407.      One thing that we did in order to achieve such a large TPA size (65022
  1408.      bytes) and such fast emulation was remove the console command part of
  1409.      CP/M (the Console Command Processor, or CCP) from the CP/M Segment. In
  1410.      fact, we did away with CP/M entirely. 
  1411.       
  1412.      The CCP is the part of a normal CP/M system which accepts commands from
  1413.      the user and processes them. The Digital Research CCP that comes with
  1414.      CP/M 2.2 is fairly limited in its power. 
  1415.       
  1416.      In the Emulator, it is the main Z80MU 'C'-language program which
  1417.      contains all of the functions of CP/M's CCP, and does a whole lot more.
  1418.      In fact, it is this program which emulates all of CP/M (with a lot of
  1419.      help from PCDOS). 
  1420.  
  1421.      For this reason, there are certain CP/M enhancements (like ZCPR) which
  1422.      will have a whole lot of trouble working under the Emulator. The good
  1423.      news is that they are largely irrelevant under the Emulator, as the
  1424.      Emulator itself provides a powerful increase in console power even
  1425.      without ZCPR. 
  1426.       
  1427.      So if you have dreams of running ZCPR (or any CP/M enhancement which
  1428.      counts on patching CP/M), you ought to forget about it. When using the
  1429.      Emulator, there's no CP/M for such programs to patch. It's all fakeware,
  1430.      invisible to Z80 programs. 
  1431.       
  1432.      Stick with CP/M programs which interact with the outside world via the
  1433.      standard, unmodified BIOS and BDOS interfaces. 
  1434.       
  1435.       
  1436.  
  1437.      CP/M 2.2 BIOS and BDOS Emulation      ________________________________
  1438.       
  1439.      The Emulator tries very hard to look to Z80 programs like CP/M version
  1440.      2.2, at least in terms of its BIOS calls and BDOS support functions.
  1441.      Most Z80 programs that are run under the Emulator will have no idea that
  1442.      they aren't being run on a Z80 machine running Digital Research's CP/M.
  1443.       
  1444.      There are some hardware-specific aspects of CP/M, however, that make no
  1445.      sense on a PCDOS system. 
  1446.       
  1447.      Many CP/M BIOS calls, for example, deal with the physical layout and
  1448.      operation of the floppy disk. Some of these are ignored. Others cause a
  1449.      fault of the Z80 program, with the display of a message to the effect
  1450.      that the program invoked an unsupported BIOS call. 
  1451.       
  1452.      There are a few BDOS functions which likewise are irrelevant, and which
  1453.      cause the Z80 program to be aborted. 
  1454.       
  1455.  
  1456. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1457.  
  1458.  
  1459.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 26
  1460.      THE CP/M ENVIRONMENT
  1461.  
  1462.  
  1463.      The following is a list of the various BIOS calls that are supported by
  1464.      CP/M 2.2, and their effects under the Emulator. Calls that are marked
  1465.      "unsupported" cause the Z80 program to be aborted.
  1466.  
  1467.      The addresses listed are absolute addresses within the CP/M Segment.
  1468.      Note that when the CP/M segment is Cold Booted, CP/M's location zero is
  1469.      set to JMP BIOS+3 (FF03h - the Warm Boot vector). The only safe way for                                                                safe
  1470.      a Z80 program to locate this BIOS jump table in any CP/M system (not
  1471.      just the Emulator) is to look at address 0001 within CP/M's memory.
  1472.  
  1473.           BIOS          BIOS
  1474.           Address          Address   Function                     Function
  1475.  
  1476.           FF00h     Cold Start CP/M segment
  1477.           FF03h     Warm Start CP/M segment 
  1478.           FF06h     Set A-reg to FFh if Emulated VT52 Terminal has keypress
  1479.                          to be read, 00h if not
  1480.           FF09h     Get keypress from Emulated VT52 Terminal to A-reg, via
  1481.                          IBM's ROM BIOS 
  1482.           FF0Ch     Output C-reg to Emulated VT52 Terminal via IBM's ROM BIOS
  1483.           FF0Fh     Output C-reg to LPT1: via IBM's ROM BIOS
  1484.           FF12h     Output C-reg to COM1: via IBM's ROM BIOS 
  1485.           FF15h     Get char from COM1: to A-reg via IBM's ROM BIOS 
  1486.           FF18h     Home Disk (unsupported) 
  1487.           FF1Bh     Select Disk (unsupported) 
  1488.           FF1Eh     Set Track (unsupported) 
  1489.           FF21h     Set Sector (unsupported) 
  1490.           FF24h     Set DMA address (unsupported) 
  1491.           FF27h     Read Sector (unsupported) 
  1492.           FF2Ah     Write Sector (unsupported) 
  1493.           FF2Dh     Set A-reg to FFh if LPT1: ready for output, 00h if not,
  1494.                          as reported by IBM's ROM BIOS
  1495.           FF30h     Sector Translate (unsupported) 
  1496.        
  1497.       
  1498.      Similarly, here is a table of the various BDOS functions (in Decimal/-
  1499.      HEX), and their actions under the Emulator. Note that a CP/M BDOS
  1500.      function is invoked by loading the function number into C-reg, and
  1501.      doing a CALL 0005h. See standard CP/M documentation for detailed
  1502.      calling conventions.
  1503.  
  1504.           BDOS          BDOS
  1505.           Function          Function  Action                    Action
  1506.       
  1507.           00/00h    Warm Boot. Returns to accept more Emulator commands. Does
  1508.                          not alter memory in the CP/M Segment.                          not
  1509.           01/01h    Read char from PCDOS standard input to A-reg. 
  1510.           02/02h    Send E-reg to PCDOS standard output. 
  1511.  
  1512.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1513.  
  1514.  
  1515.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 27
  1516.      THE CP/M ENVIRONMENT
  1517.  
  1518.  
  1519.           03/03h    Read char from PCDOS AUX: device into A-reg. 
  1520.           04/04h    Send E-reg to PCDOS AUX: device 
  1521.           05/05h    Send E-reg to PCDOS PRN device 
  1522.           06/06h    If E-reg on entry = FFh, then return in A-reg next char
  1523.                          from PCDOS standard input, or 00h if none available
  1524.                          at this instant. 
  1525.                     If E-reg on entry <> FFh, then send E-reg to PCDOS
  1526.                          standard output. 
  1527.           07/07h    Get IOBYTE to A-reg. 
  1528.           08/08h    Store E-reg into IOBYTE. 
  1529.           09/09h    Output string at (DE) to PCDOS standard output. 
  1530.           10/0Ah    Input line from PCDOS standard input to (DE). 
  1531.           11/0Bh    Set A-reg to FFh if char from PCDOS standard input is
  1532.                          ready to be read, or 00h if not. 
  1533.           12/0Ch    Return CP/M version to HL. Sets reg L to 22h (for CP/M
  1534.                          version 2.2), and reg H to 00h.
  1535.           13/0Dh    Reset disk system. Sets DMA to 80h. Does not change                                                             not
  1536.                          selected drive to A: (like CP/M does), as this is
  1537.                          not necessary with PCDOS. 
  1538.           14/0Eh    Set default drive to E-reg. 
  1539.           15/0Fh    Open file whose FCB is at (DE). Sets A-reg to 00h if
  1540.                          successful, else to FFh. 
  1541.           16/10h    Close file whose FCB is at (DE).  Sets A-reg to 00h if
  1542.                          successful, else to FFh. 
  1543.           17/11h    Search for first file that matches pattern in FCB at
  1544.                          (DE).  Sets A-reg to 00h if successful, else to FFh.
  1545.           18/12h    Search for next file that matches last pattern used. 
  1546.                          Sets A-reg to 00h if successful, else to FFh. 
  1547.           19/13h    Delete file(s) represented by FCB is at (DE).  Sets A-reg
  1548.                          to 00h if successful, else to FFh. 
  1549.  
  1550.           20/14h    Read next sequential record from file whose FCB is
  1551.                          at (DE). Sets A-reg to status as follows:
  1552.       
  1553.                          0 = successful 
  1554.                          1 = reading unwritten data (EOF) 
  1555.                          FFh = PCDOS returned error # 2: "No room in DTA for
  1556.                               record" 
  1557.  
  1558.                     Note that a short record is filled out by the Emulator
  1559.                          with ^Z (eof) characters. 
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1569.  
  1570.  
  1571.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 28
  1572.      THE CP/M ENVIRONMENT
  1573.  
  1574.  
  1575.           21/15h    Write next sequential record to file whose FCB is at
  1576.                          (DE). Returns status in A-reg as follows: 
  1577.       
  1578.                          0 = successful 
  1579.                          5 = diskette full 
  1580.                          6 = PCDOS returned error # 2: "No room in DTA for
  1581.                               record" 
  1582.       
  1583.           22/16h    Create (and open) file whose FCB is at (DE).  Sets A-reg
  1584.                          to 00h if successful, else to FFh. 
  1585.           23/17h    Rename file(s) per special FCB at (DE).  Sets A-reg to
  1586.                          00h if successful, else to FFh. 
  1587.           24/18h    Return login vector (bitmap of known disks) to HL. Calls
  1588.                          PCDOS to discover number of available drives. 
  1589.           25/19h    Return default drive number in A-reg. 
  1590.           26/1Ah    Set DMA to DE. 
  1591.           27/1Bh    Return allocation information (unsupported - aborts Z80
  1592.                          program). See note below. 
  1593.           28/1Ch    Write-protect drive (ignored). 
  1594.           29/1Dh    Return write-protect vector (bitmap of $R/O drives) to
  1595.                          HL. Sets HL to zero (nobody's write-protected).
  1596.           30/1Eh    Set file attributes (ignored, but returns A-reg of 00h to
  1597.                          indicate success). 
  1598.           31/1Fh    Return physical disk information (unsupported - aborts
  1599.                          Z80 program). See note below. 
  1600.  
  1601.           32/20h    If E-reg on entry is FFh, then current user number is
  1602.                          returned in A-reg. 
  1603.       
  1604.                     If E-reg on entry <> FFh, then current user number is set
  1605.                          to E-reg MOD 32. 
  1606.       
  1607.                     This only updates the byte at CP/M address 4. The
  1608.                          Emulator ignores this byte when accessing files. 
  1609.       
  1610.           33/21h    Read random record from file whose FCB is at (DE).
  1611.                          Returns A-reg status as follows: 
  1612.  
  1613.                          0 = successful 
  1614.                          1 = reading unwritten data 
  1615.                          3 = (CP/M "Cannot close current extent" error):
  1616.                               PCDOS returned error # 2: "No space in DTA for
  1617.                               record" 
  1618.       
  1619.                     Note that a partial record is filled out by the Emulator
  1620.                          with ^Z (eof) characters. 
  1621.       
  1622.  
  1623.  
  1624. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1625.  
  1626.  
  1627.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 29
  1628.      THE CP/M ENVIRONMENT
  1629.  
  1630.  
  1631.           34/22h    Write random record to file whose FCB is at (DE). Returns
  1632.                          A-reg status as follows: 
  1633.       
  1634.                          0 = successful 
  1635.                          3 = (CP/M "Cannot close current extent" error):
  1636.                               PCDOS returned error # 2: "No space in DTA for
  1637.                               record" 
  1638.                          5 = (CP/M "Directory Overflow" error): Diskette full
  1639.  
  1640.       
  1641.           35/23h    Compute file size for file whose FCB is at (DE). Result
  1642.                          goes into random record field of FCB. 
  1643.           36/24h    Set random record field per FCB at (DE). 
  1644.           37/25h    Reset drive (accepted but ignored) 
  1645.           38/26h    (unsupported - aborts Z80 program) 
  1646.           39/27h    (unsupported - aborts Z80 program) 
  1647.           40/28h    Write random record with zero fill. In the Emulator, this
  1648.                          is translated to a function 34/22h (above). 
  1649.  
  1650.           NOTE: If someone will kindly provide us with a coherent
  1651.           writeup of the disk parameter block and allocation information
  1652.           as returned by BDOS functions 31/1Fh and 27/1Bh above, then
  1653.           we will gladly emulate these functions in the next release.
  1654.  
  1655.       
  1656.      In CP/M the BDOS routines call the BIOS routines. This is not true in
  1657.      the Emulator. The Emulator's BDOS functions in general invoke the
  1658.      corresponding PCDOS functions, and the Emulator's BIOS routines call the
  1659.      IBM PC ROM BIOS routines.
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1681.  
  1682.  
  1683.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 30
  1684.      EMULATOR BUILTIN COMMANDS
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.                                 BUILTIN COMMANDS                                 BUILTIN COMMANDS                                                  
  1699.  
  1700.      This section describes those commands that are recognized and acted
  1701.      upon by the Emulator itself. Such commands do not involve a search of
  1702.      the disk for a corresponding .COM file, since the Emulator recognizes
  1703.      them as special commands which are to be handled within the Emulator
  1704.      itself. This process is roughly equivalent to the handling of CP/M's CCP
  1705.      commands.
  1706.  
  1707.  
  1708.      Command Name Conflicts     ______________________
  1709.  
  1710.      You may have a .COM (Z80 command) file that has the same name as one of
  1711.      these Builtin Commands. How do you tell the Emulator to run your .COM
  1712.      file, instead of doing its corresponding Builtin Command? All that you
  1713.      have to do is convince the Emulator that your command is indeed a disk
  1714.      file. This can be done by including a drive ID or pathname as part of
  1715.      your command:
  1716.  
  1717.           Z80 A>a:dump foobar.asc                a:dump foobar.asc
  1718.           Z80 A>b:\bin\dump foobar.asc                b:\bin\dump foobar.asc
  1719.           Z80 A>\mystuff\dump foobar.asc                \mystuff\dump foobar.asc
  1720.  
  1721.      Alternatively, you may want to rename your .COM file so that it no
  1722.      longer conflicts with an Emulator Builtin Command name.
  1723.  
  1724.  
  1725.  
  1726.      Numeric Arguments      _________________
  1727.       
  1728.      Some Builtin Commands accept numeric arguments. These may represent
  1729.      addresses to be dumped, the number of pages to save, or whatever.                     dump                           save
  1730.       
  1731.      A numeric argument may be entered in any of several ways: 
  1732.       
  1733.           As a HEX number. No prefix is required in this case, as this is
  1734.                the default numeric radix. 
  1735.  
  1736.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1737.  
  1738.  
  1739.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 31
  1740.      EMULATOR BUILTIN COMMANDS
  1741.  
  1742.  
  1743.       
  1744.                Examples: ffff  0  7F  -5  +3FF 
  1745.  
  1746.           As a decimal number, prefixed by a period ("."). 
  1747.  
  1748.                Examples: .10  .0  -.1  +.256  .65022 
  1749.       
  1750.           As a binary number, prefixed with the percent sign ("%"). 
  1751.  
  1752.                Examples: %0  %1010101011110000  -%1 
  1753.       
  1754.           As an ASCII character, prefixed by the apostrophe ("'"). 
  1755.  
  1756.                Examples: 'A  '"  '0  -'Z
  1757.       
  1758.           As an ASCII escape sequence, prefixed by an apostrophe and back-
  1759.                slash ("'\"). 
  1760.  
  1761.                Examples: 
  1762.  
  1763.                     '\\            (single "\" char) 
  1764.                     '\0            (NUL byte) 
  1765.                     '\b or '\B     (Backspace char) 
  1766.                     '\t or '\T     (TAB char) 
  1767.                     '\n or '\N     (LINEFEED char) 
  1768.                     '\r or '\R     (CARRIAGE RETURN char) 
  1769.                     '\'            (single apostrophe ("'") char) 
  1770.                     '\"            (single double-quote char ) 
  1771.                     '\xFF or '\XFF (byte with HEX value of FF) 
  1772.       
  1773.           As a label which has been defined with the "label" builtin command.                                                      label
  1774.  
  1775.                Examples: fcb1  program_start  BDOS  -reserved 
  1776.       
  1777.           As two or more of the above entries, connected with "+" or "-"
  1778.                operators. 
  1779.  
  1780.                Examples: 
  1781.  
  1782.                     fcb1+5 
  1783.                     program_end-table_length 
  1784.                     'A-40+'a 
  1785.                     table-5+offset 
  1786.       
  1787.       
  1788.  
  1789.  
  1790.  
  1791.  
  1792. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1793.  
  1794.  
  1795.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 32
  1796.      EMULATOR BUILTIN COMMANDS
  1797.  
  1798.  
  1799.  
  1800.      The Builtin Commands are presented by functional grouping:
  1801.  
  1802.           - The PCDOS pass-through command prefix
  1803.           - CP/M Builtins that are emulated
  1804.           - Emulator Builtins that are similar to CP/M's
  1805.           - General Emulator commands
  1806.           - Emulator DEBUG commands
  1807.           - CP/M Environment and file control commands
  1808.           - RESOURCE commands
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1849.  
  1850.  
  1851.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 33
  1852.      BUILTIN COMMANDS: PCDOS PASS-THROUGH
  1853.  
  1854.  
  1855.       
  1856.      Builtin:     ________  !xxxxxx               !xxxxxx
  1857.       
  1858.      Passes command xxxxxx to PCDOS. This gives you a way to use the usual
  1859.      PCDOS utilities from within the emulator, without having them interpret-
  1860.      ed as CP/M commands. Everything after the "!" character is passed as a
  1861.      command to PCDOS. 
  1862.       
  1863.      This command requires the reloading (by PCDOS) of the PCDOS COMMAND.COM
  1864.      file from disk. See the section on "The PCDOS Environment" for more
  1865.      detail on this subject. 
  1866.       
  1867.      Since PCDOS handles the command (and any command arguments that may be
  1868.      present), the standard PCDOS "PATH" environment string may apply. So may
  1869.      all other PCDOS conventions, like I/O redirection, wildcards, PCDOS
  1870.      device names, etc. 
  1871.       
  1872.      The given command is executed above the Emulator's memory. This implies
  1873.      that there had better be enough memory available above the Emulator to
  1874.      run the given command. 
  1875.       
  1876.      You may use this facility to "drop into" PCDOS for a while (perhaps to
  1877.      use a PCDOS screen editor on a CP/M source file), and then return to the
  1878.      Emulator. Use "!command" to drop into DOS, and "exit" to leave PCDOS and                    !command                         exit
  1879.      return to the Emulator. 
  1880.       
  1881.      This is also the primary way to take advantage of PCDOS's directory
  1882.      structure while within CP/M. You may issue "CHDIR", "MKDIR", and other
  1883.      directory-related commands directly to PCDOS. The effect of such
  1884.      commands carries over to the Emulator. 
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1905.  
  1906.  
  1907.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 34
  1908.      BUILTIN COMMANDS: PCDOS PASS-THROUGH
  1909.  
  1910.  
  1911.  
  1912.      Example (from an actual session):
  1913.       
  1914.           Z80 A>!cd \foo                 !cd \foo
  1915.           Z80 A>!cd \                 !cd \
  1916.           Z80 A>!rd \foo                !rd \foo
  1917.           Z80 A>!chkdsk b:                 !chkdsk b:
  1918.       
  1919.       
  1920.              362496 bytes total disk space 
  1921.                1024 bytes in 1 directories 
  1922.              272384 bytes in 10 user files 
  1923.               89088 bytes available on disk 
  1924.       
  1925.              423936 bytes total memory 
  1926.              152384 bytes free 
  1927.       
  1928.           Z80 A>!md foo                 !md foo
  1929.           Z80 A>!cd foo                 !cd foo
  1930.           Z80 A>stat *.*                 stat *.*
  1931.       
  1932.       
  1933.                Volume in drive A has no label 
  1934.                Directory of  A:\foo 
  1935.       
  1936.                .         <DIR>     11-19-85   1:15a 
  1937.                ..        <DIR>     11-19-85   1:15a 
  1938.                2 File(s)    144384 bytes free 
  1939.       
  1940.           Z80 A>!command                 !command
  1941.        
  1942.       
  1943.           The IBM Personal Computer DOS 
  1944.           Version 2.00 (C)Copyright IBM Corp 1981, 1982, 1983 
  1945.       
  1946.           Tue 11-19-1985 1:16:00.18 
  1947.           A:>chkdsk              chkdsk
  1948.       
  1949.       
  1950.              362496 bytes total disk space 
  1951.                1024 bytes in 1 directories 
  1952.              217088 bytes in 17 user files 
  1953.              144384 bytes available on disk 
  1954.       
  1955.              423936 bytes total memory 
  1956.              149264 bytes free 
  1957.       
  1958.       
  1959.  
  1960. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  1961.  
  1962.  
  1963.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 35
  1964.      BUILTIN COMMANDS: PCDOS PASS-THROUGH
  1965.  
  1966.  
  1967.           Tue 11-19-1985 1:16:16.17 
  1968.           A:>exit              exit
  1969.  
  1970.           Z80 A>!format a:                 !format a:
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.  
  1991.  
  1992.  
  1993.  
  1994.  
  1995.  
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.  
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2017.  
  2018.  
  2019.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 36
  2020.      BUILTIN COMMANDS: EMULATED CP/M BUILTIN'S
  2021.  
  2022.  
  2023.       
  2024.      Builtin:     ________  d:                d:
  2025.  
  2026.           Changes the default disk drive to the drive whose letter name is
  2027.      represented by the "d" character. The command prompt will change to
  2028.  
  2029.           Z80 d>
  2030.  
  2031.      to reflect the new default. Drive d's current PCDOS directory will
  2032.      then be the first directory searched for Z80 command (.COM) files,
  2033.      unless explicitly overridden by a drive prefix or pathname. Data files
  2034.      that are created will default to that drive and its current directory.
  2035.      Data files that are read will be searched for only in that drive and
  2036.      directory, unless explicitly overridden by the Z80 program. 
  2037.       
  2038.      Example (from an actual session): 
  2039.  
  2040.           Z80 A>stat b:*.*                 stat b:*.*
  2041.       
  2042.       
  2043.                 Volume in drive B has no label 
  2044.                 Directory of  B:\ 
  2045.       
  2046.                WORDSTAR     <DIR>     11-02-85   4:19a 
  2047.                     1 File(s)     89088 bytes free 
  2048.       
  2049.           Z80 A>dir b:\wordstar\ws*.*                 dir b:\wordstar\ws*.*
  2050.       
  2051.       
  2052.                 Volume in drive B has no label 
  2053.                 Directory of  B:\wordstar 
  2054.       
  2055.                WSMSGS   OVR   27904  11-06-85   6:27p 
  2056.                WSOVLY1  OVR   34048  11-06-85   6:30p 
  2057.                WSU      COM   15872  11-06-85   6:32p 
  2058.                WS       COM   15872  11-06-85   6:37p 
  2059.                     4 File(s)     89088 bytes free 
  2060.       
  2061.           Z80 A>b:                 b:
  2062.       
  2063.           Z80 B>dir                 dir
  2064.       
  2065.       
  2066.                 Volume in drive B has no label 
  2067.                 Directory of  B:\ 
  2068.       
  2069.                WORDSTAR     <DIR>     11-02-85   4:19a 
  2070.                     1 File(s)     89088 bytes free 
  2071.  
  2072.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2073.  
  2074.  
  2075.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 37
  2076.      BUILTIN COMMANDS: EMULATED CP/M BUILTIN'S
  2077.  
  2078.  
  2079.       
  2080.           Z80 B>stat a:\*.exe                 stat a:\*.exe
  2081.       
  2082.       
  2083.                 Volume in drive A has no label 
  2084.                 Directory of  A:\ 
  2085.       
  2086.                Z80MU    EXE   94976  11-18-85   3:31p 
  2087.                     1 File(s)    142336 bytes free 
  2088.       
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123.  
  2124.  
  2125.  
  2126.  
  2127.  
  2128.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2129.  
  2130.  
  2131.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 38
  2132.      BUILTIN COMMANDS: EMULATED CP/M BUILTIN'S
  2133.  
  2134.  
  2135.       
  2136.      Builtin:  del <pattern>                del <pattern>      ________
  2137.                era <pattern>                era <pattern> 
  2138.                delete <pattern>                delete <pattern> 
  2139.                erase <pattern>                erase <pattern>
  2140.  
  2141.      These are identical commands. All cause the invocation of the PCDOS
  2142.      "DEL" command to delete files that match <pattern>. 
  2143.  
  2144.      See the PCDOS manual for details of <pattern>. 
  2145.  
  2146.      We have created several synonyms for the same command in order to make
  2147.      life easier for CP/M folks who are used to saying "ERA", and PCDOS
  2148.      folks who are used to saying "DEL" or whatever. 
  2149.  
  2150.      These commands cause PCDOS to reload COMMAND.COM, so see "The PCDOS
  2151.      Environment" section for further detail on that subject. 
  2152.  
  2153.      Example:
  2154.       
  2155.           Z80 A>erase b:*.asm                 erase b:*.asm
  2156.           Z80 A>del *.*                 del *.*
  2157.                Are you sure? y                              y
  2158.           Z80 A>delete c:\backup\foo.*                 delete c:\backup\foo.*
  2159.           Z80 A>era foo.asm                era foo.asm
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2185.  
  2186.  
  2187.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 39
  2188.      BUILTIN COMMANDS: EMULATED CP/M BUILTIN'S
  2189.  
  2190.  
  2191.       
  2192.      Builtin:  dir <pattern>                dir <pattern>      ________
  2193.                stat <pattern>                stat <pattern>
  2194.       
  2195.      Shows a directory of files matching <pattern>. This invokes the PCDOS
  2196.      "DIR" command, so remember about COMMAND.COM (see "The PCDOS Environ-
  2197.      ment" section). 
  2198.  
  2199.      <pattern> is passed directly to PCDOS. So see the PCDOS manual if you
  2200.      want to know what's legal.
  2201.       
  2202.      The CP/M STAT command (STAT.COM) cannot be emulated, because the
  2203.      first thing that Digital Research's STAT.COM does is invoke a hardware-
  2204.      specific CP/M function that means nothing on the IBM PC, and is there-
  2205.      fore illegal within the Emulator. But the most common function of
  2206.      STAT.COM - displaying filenames and file sizes with "STAT *.*" or
  2207.      whatever - can be done with PCDOS's "DIR" command. So STAT and DIR have
  2208.      been made to do the same thing. If you're used to typing "STAT *.*" in
  2209.      CP/M, then you'll be able to do the same thing under the Emulator. 
  2210.  
  2211.      Example (from an actual session):
  2212.  
  2213.           Z80 A>stat b:*.*                 stat b:*.*
  2214.       
  2215.       
  2216.                 Volume in drive B has no label 
  2217.                 Directory of  B:\ 
  2218.       
  2219.                WORDSTAR     <DIR>     11-02-85   4:19a 
  2220.                     1 File(s)     89088 bytes free 
  2221.       
  2222.           Z80 A>dir b:\wordstar\ws*.*                 dir b:\wordstar\ws*.*
  2223.       
  2224.       
  2225.                 Volume in drive B has no label 
  2226.                 Directory of  B:\wordstar 
  2227.       
  2228.                WSMSGS   OVR   27904  11-06-85   6:27p 
  2229.                WSOVLY1  OVR   34048  11-06-85   6:30p 
  2230.                WSU      COM   15872  11-06-85   6:32p 
  2231.                WS       COM   15872  11-06-85   6:37p 
  2232.                     4 File(s)     89088 bytes free 
  2233.       
  2234.           Z80 A>b:                 b:
  2235.       
  2236.           Z80 B>dir                 dir
  2237.       
  2238.       
  2239.  
  2240. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2241.  
  2242.  
  2243.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 40
  2244.      BUILTIN COMMANDS: EMULATED CP/M BUILTIN'S
  2245.  
  2246.  
  2247.                 Volume in drive B has no label 
  2248.                 Directory of  B:\ 
  2249.       
  2250.                WORDSTAR     <DIR>     11-02-85   4:19a 
  2251.                     1 File(s)     89088 bytes free 
  2252.       
  2253.           Z80 B>stat a:\*.exe                 stat a:\*.exe
  2254.       
  2255.       
  2256.                 Volume in drive A has no label 
  2257.                 Directory of  A:\ 
  2258.       
  2259.                Z80MU    EXE   94976  11-18-85   3:31p 
  2260.                     1 File(s)    142336 bytes free 
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2297.  
  2298.  
  2299.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 41
  2300.      BUILTIN COMMANDS: EMULATED CP/M BUILTIN'S
  2301.  
  2302.  
  2303.  
  2304.      Builtin:  type <filename.typ>                type <filename.typ>      ________
  2305.                ty <filename.typ>                ty <filename.typ>
  2306.       
  2307.      This command is the equivalent of the CP/M "TYPE" command. The specified
  2308.      file is displayed on the standard output (normally the screen). 
  2309.       
  2310.      The display may be paused with either the CP/M convention of ^S/^Q or
  2311.      the PCDOS convention of CTRL-NUMLOCK. It may be aborted with ^C or
  2312.      CTRL-BREAK. 
  2313.  
  2314.      This command causes PCDOS to reload COMMAND.COM, so see "The PCDOS
  2315.      Environment" section for further detail on that subject. 
  2316.       
  2317.      Example: 
  2318.  
  2319.           Z80 A>ty b:foo.asm                 ty b:foo.asm
  2320.           Z80 A>type \source\backup\foo.doc                 type \source\backup\foo.doc
  2321.           Z80 A>ty ctest.err                 ty ctest.err
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2353.  
  2354.  
  2355.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 42
  2356.      BUILTIN COMMANDS: SIMILAR TO CP/M'S
  2357.  
  2358.  
  2359.  
  2360.      Builtin:  rename <oldpath> <newpath>                rename <oldpath> <newpath>      ________
  2361.                ren <oldpath> <newpath>                ren <oldpath> <newpath>
  2362.       
  2363.      Renames the file specified by <oldpath> to the name given by <newpath>.
  2364.  
  2365.           NOTE: This is not the same syntax used by the CP/M equivalent,                        not
  2366.           which is "REN <newname>=<oldname>". 
  2367.       
  2368.      This command causes PCDOS to reload COMMAND.COM, so see "The PCDOS
  2369.      Environment" section for further detail on that subject. 
  2370.       
  2371.      This command invokes the PCDOS "RENAME" command. See the PCDOS manual
  2372.      for details.
  2373.  
  2374.      Example: 
  2375.  
  2376.           Z80 A>rename dbase.exe dbase.xxx                 rename dbase.exe dbase.xxx
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2409.  
  2410.  
  2411.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 43
  2412.      BUILTIN COMMANDS: SIMILAR TO CP/M'S
  2413.  
  2414.  
  2415.  
  2416.      Builtin:  save n <filename.typ>                save n <filename.typ>      ________
  2417.                sa n <filename.typ>                sa n <filename.typ>
  2418.       
  2419.      Saves n 256-byte pages of CP/M memory (starting at address 0100h) to the
  2420.      specified file. The data written to the file is a simple memory image.
  2421.      No translation is done, even if a .HEX extension is given in the
  2422.      filename. If you want to write a true Intel HEX file, use the write                                                                   write
  2423.      Builtin. 
  2424.       
  2425.           NOTE: This is close to the CP/M equivalent, except that the
  2426.           default radix for n is HEX, not decimal as with CP/M. 
  2427.       
  2428.      Example (from an actual session):
  2429.  
  2430.           Z80 A>save 3 820init2.com                 save 3 820init2.com
  2431.       
  2432.                Writing 3 pages (768 bytes) to file '820INIT2.COM' 
  2433.       
  2434.           Z80 A>save 0 continue.com                 save 0 continue.com
  2435.       
  2436.                Writing 0 pages (0 bytes) to file 'CONTINUE.COM' 
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2465.  
  2466.  
  2467.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 44
  2468.      BUILTIN COMMANDS: SIMILAR TO CP/M'S
  2469.  
  2470.  
  2471.  
  2472.      Builtin:  copy <from_pattern> <to_path>                copy <from_pattern> <to_path>      ________
  2473.                co <from_pattern> <to_path>                co <from_pattern> <to_path>
  2474.       
  2475.      Copies the file(s) specified by <from_pattern> to the file or directory
  2476.      specified by <to_path>. 
  2477.       
  2478.      This command invokes the PCDOS "COPY" command, so see the PCDOS manual
  2479.      for details as to what's legal. 
  2480.       
  2481.      It also causes PCDOS to reload COMMAND.COM, so see "The PCDOS Environ-
  2482.      ment" section for further detail on that subject. 
  2483.       
  2484.      This command is roughly equivalent to CP/M's "PIP <outfile>=<infile>".
  2485.      You have the additional power of PCDOS's directory and device name
  2486.      support, however. 
  2487.       
  2488.      Example:
  2489.  
  2490.           Z80 A>copy *.* B:                 copy *.* B:
  2491.           Z80 A>co b:*.asm                 co b:*.asm
  2492.           Z80 A>copy \bin\*.* c:\backup                 copy \bin\*.* c:\backup
  2493.           Z80 A>copy *.asm combined.bak                 copy *.asm combined.bak
  2494.           Z80 A>co *.asm *.bak                 co *.asm *.bak
  2495.           Z80 A>co foo.asm lpt1:                 co foo.asm lpt1:
  2496.           Z80 A>co con autoexec.bat                co con autoexec.bat
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.  
  2517.  
  2518.  
  2519.  
  2520.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2521.  
  2522.  
  2523.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 45
  2524.      BUILTIN COMMANDS: GENERAL
  2525.  
  2526.  
  2527.  
  2528.      Builtin:  help [command]                help [command]     ________
  2529.                ? [command]                ? [command]
  2530.       
  2531.      Displays a brief description of the requested Builtin Command. 
  2532.       
  2533.      If no command name follows the "help" command, then a rather lengthy                                     help
  2534.      explanation of all commands is displayed. If you press the SPACE bar,
  2535.      this long listing will be interrupted at the next logical break.
  2536.  
  2537.      The listing can be paused with ^S/^Q, or CTRL-NumLock. You can turn
  2538.      printer copying on before the listing starts (which is recommended) with
  2539.      ^P or CTRL-PrtSc.
  2540.       
  2541.      Example:
  2542.       
  2543.           Z80 A>help xreg                 help xreg
  2544.           Z80 A>? list                 ? list
  2545.           Z80 A>?                 ?
  2546.           Z80 A>help ?                help ?
  2547.           Z80 A>help b:                help b:
  2548.           Z80 A>help !                help !
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2577.  
  2578.  
  2579.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 46
  2580.      BUILTIN COMMANDS: GENERAL
  2581.  
  2582.  
  2583.       
  2584.      Builtin:  illop [fault | nop]                illop [fault | nop]      ________
  2585.                i [fault | nop]                i [fault | nop]
  2586.       
  2587.      Specifies how the Emulator is to handle illegal Z80 opcodes. 
  2588.       
  2589.      If "illop fault" is entered, then an illegal Z80 opcode will cause a Z80         illop fault
  2590.      fault, meaning that the Emulator will stop executing the Z80 program and
  2591.      will display an error message to the effect that an illegal opcode was
  2592.      encountered at such-and-such and address. 
  2593.  
  2594.      If "illop nop" is entered, then an illegal Z80 opcode will simply be         illop nop
  2595.      ignored. This is closer to true Z80 operation. Execution will continue
  2596.      with the next Z80 instruction after the illegal opcode. 
  2597.       
  2598.      If only "illop" is entered, then the Emulator simply reports how it is              illop
  2599.      currently handling illegal opcodes. 
  2600.  
  2601.      Example (from an actual session):
  2602.       
  2603.           Z80 A>i                 i
  2604.       
  2605.                Illegal opcodes will act as NOP's 
  2606.  
  2607.           Z80 A>illop fault                 illop fault
  2608.       
  2609.                Illegal opcodes will FAULT 
  2610.  
  2611.           Z80 A>illop nop                 illop nop
  2612.       
  2613.                Illegal opcodes will act as NOP's 
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2633.  
  2634.  
  2635.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 47
  2636.      BUILTIN COMMANDS: GENERAL
  2637.  
  2638.  
  2639.  
  2640.      Builtin:  exit                exit      ________
  2641.                e                e
  2642.       
  2643.      Exits the Emulator, and returns to PCDOS. 
  2644.       
  2645.      Due to certain limitations within PCDOS, you should not remove any
  2646.      floppy disks that are being used until you have exited the Emulator via
  2647.      this command, unless you know that the Z80 programs which you have run                              know
  2648.      have truly closed any files that have been written to. 
  2649.  
  2650.      We have used the Emulator extensively, and have frequently changed
  2651.      floppies while within the Emulator. We have never experienced corrupted
  2652.      floppy data. But then, we use only "safe" CP/M software like ASM.COM,
  2653.      M80.COM, L80.COM, and so on. Such programs are very good about closing
  2654.      files when they exit. 
  2655.       
  2656.      This warning is included not because it has ever happened to us, but
  2657.      because we wrote the code, and we know about certain "windows" within
  2658.      which a faulting CP/M program could conceivably confuse PCDOS into
  2659.      writing one floppy's data to another floppy, destroying the second
  2660.      floppy's file data and perhaps even its FAT (File Allocation Table). 
  2661.       
  2662.      Example: 
  2663.           Z80 A>exit                 exit
  2664.           A> 
  2665.  
  2666.  
  2667.  
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2689.  
  2690.  
  2691.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 48
  2692.      BUILTIN COMMANDS: GENERAL
  2693.  
  2694.  
  2695.  
  2696.      Builtin:  speed?                speed?      ________
  2697.                howfast?                howfast?
  2698.       
  2699.      Calculates the effective speed of the imaginary Z80 that exists within
  2700.      the Emulator. 
  2701.  
  2702.      A sample Z80 program is loaded into the CP/M segment. It is run, and its
  2703.      execution is timed. This program takes up to half a minute to run on a
  2704.      simple IBM PC with an 8088, and correspondingly less time on faster
  2705.      machines (i.e. - a PC with a NEC V20 chip, an IBM PC/AT, etc). 
  2706.       
  2707.      The effective clock speed is displayed at the end of the test. 
  2708.       
  2709.      The reported speed should be taken with a grain of salt. What it means
  2710.      is that if you had a real Z80 running the exact instruction mix found in
  2711.      the test program, then that real Z80 would have to run at the reported
  2712.      clock speed in order to perform as fast (or slow) as the Emulator's
  2713.      imaginary Z80. 
  2714.  
  2715.      For example, assume that the reported effective clock is 250,000 Hz.
  2716.      This means that the imaginary Z80 in the Emulator is running the test
  2717.      program at one fourth the speed of a 1 MegaHertz Z80 (as found on a
  2718.      Microsoft SoftCard in an Apple, for example), one eighth the speed of a
  2719.      2 MegaHertz Z80, etc. 
  2720.       
  2721.      Does this mean that your CP/M programs run under the Emulator will run
  2722.      at one fourth the speed of an Apple with a SoftCard? Not necessarily.
  2723.      The reported speed is for CPU-bound (no I/O) operation, of the exact mix
  2724.      of instructions found in the test program. Real CP/M programs tend to
  2725.      have a mix of CPU and I/O operations. I/O operations to disk are handled
  2726.      as fast as the IBM PC can do them. They aren't emulated, they are done.                                                                       done
  2727.      And CP/M programs whose CPU-bound operations involve a lot of register-
  2728.      to-register operations will be emulated faster than those requiring a
  2729.      lot of memory accesses. 
  2730.       
  2731.      It's a complicated relationship. Our experience has been that an
  2732.      assembly (using ASM.COM) runs about 1/5th the speed under the Emulator
  2733.      on a stock, floppy-based IBM PC than it does on an Apple with a SoftCard
  2734.      and 1 MegaHertz Z80. The addition of a NEC V20 processor to the IBM PC
  2735.      improves performance. So does using a hard disk instead of floppies. And
  2736.      moving the Emulator to an IBM PC/AT brings emulated performance close to
  2737.      that of a 1 MegaHertz Z80. 
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2745.  
  2746.  
  2747.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 49
  2748.      BUILTIN COMMANDS: GENERAL
  2749.  
  2750.  
  2751.           NOTE: This command causes a Cold Boot of the CP/M segment.
  2752.           This destroys any CP/M program that you may have had in
  2753.           memory. 
  2754.       
  2755.      Example (from an actual session):
  2756.       
  2757.           Z80 A>speed?                 speed?
  2758.       
  2759.                *** CP/M Segment COLDBOOTED *** 
  2760.       
  2761.                Beginning Z80 timing test. Please wait... 
  2762.       
  2763.                Effective Z80 clock speed is 248101 Hz 
  2764.       
  2765.                *** CP/M Segment COLDBOOTED *** 
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.  
  2784.  
  2785.  
  2786.  
  2787.  
  2788.  
  2789.  
  2790.  
  2791.  
  2792.  
  2793.  
  2794.  
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2801.  
  2802.  
  2803.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 50
  2804.      BUILTIN COMMANDS: DEBUG SUPPORT
  2805.  
  2806.  
  2807.       
  2808.      Builtin:  btrace [ SOME | ALL ]                btrace [ SOME | ALL ]      ________
  2809.                bt [ SOME | ALL ]                bt [ SOME | ALL ]
  2810.       
  2811.      Displays the current BDOS Trace Table (if no arguments are present), or
  2812.      controls the BDOS functions that will be traced. 
  2813.  
  2814.      As a CP/M program is run, the various BDOS calls that it makes are
  2815.      traced. This command displays the trace table as it has been left by the
  2816.      last CP/M program run. 
  2817.       
  2818.      Items reported include: 
  2819.       
  2820.           1) The trace table sequence number. 
  2821.           2) The Program Counter of the CALL to the BDOS. 
  2822.           3) The contents of the Z80 DE register at the entry to the BDOS
  2823.                handler. 
  2824.           4) The DMA address in effect at the instant of this BDOS call. 
  2825.           5) The BDOS function # (as passed in the Z80 C-reg) and a text
  2826.                description of the function being performed.
  2827.       
  2828.      The BDOS Trace Table is cleared by a COLD BOOT, by the load of a new
  2829.      CP/M program, and at various other times when it seems logical to clear
  2830.      it out. 
  2831.  
  2832.      If an argument (either "SOME" or "ALL") is present, then the trace                             SOME      ALL
  2833.      table is not displayed. Instead, the Emulator adjusts (according to the
  2834.      argument) the way that future traces will be made:
  2835.  
  2836.           If "SOME" is specified, then the Console Status, Console              SOME
  2837.           Output, Direct Console I/O, and List Output BDOS functions
  2838.           will not be traced. This can help to keep the BDOS Trace Table
  2839.           from filling up with unimportant entries.
  2840.  
  2841.           If "ALL" is specified, then even these console character BDOS              ALL
  2842.           functions will be traced.
  2843.  
  2844.  
  2845.  
  2846.  
  2847.  
  2848.  
  2849.  
  2850.  
  2851.  
  2852.  
  2853.  
  2854.  
  2855.  
  2856.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2857.  
  2858.  
  2859.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 51
  2860.      BUILTIN COMMANDS: DEBUG SUPPORT
  2861.  
  2862.  
  2863.      Example (from an actual run of DUMP.COM): 
  2864.  
  2865.           Z80 A>btrace all                 btrace all
  2866.       
  2867.           Future BDOS traces will include console character functions
  2868.  
  2869.           Z80 A>a:dump dump.com                a:dump dump.com
  2870.  
  2871.           0000 21 00 00 39 22 15 02 31 57 02 CD C1 01 FE FF C2 
  2872.           0010 1B 01 11 F3 01 CD 9C 01 C3 51 01 3E 80 32 13 02 
  2873.           0020 21 00 00 E5 CD A2 01 E1 DA 51 01 47 7D E6 0F C2 
  2874.           ...
  2875.           ...  (Much of DUMP.COM output deleted for brevity)
  2876.           ...
  2877.           0150 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
  2878.           0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
  2879.           0170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
  2880.       
  2881.           Z80 A>bt                 bt
  2882.       
  2883.           BDOS TRACE TABLE: 
  2884.           SEQ#  Z80PC  Z80DE Z80DMA FUNCTION 
  2885.           ----- -----  ----- ------ ---------------- 
  2886.             006 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2887.             007 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2888.             008 016BH  0020H  0080H 02H Console Output from E-reg = 
  2889.  
  2890.           ...
  2891.           ...  (Many entries deleted for brevity)
  2892.           ...
  2893.  
  2894.            049 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2895.            050 01D6H  005CH  0080H 14H Read File (Sequential), FCB at (DE)
  2896.            051 016BH  000DH  0080H 02H Console Output from E-reg = ^M
  2897.            052 016BH  000AH  0080H 02H Console Output from E-reg = ^J
  2898.            244 016BH  0020H  0080H 02H Console Output from E-reg = 
  2899.            245 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2900.            246 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2901.            247 016BH  0020H  0080H 02H Console Output from E-reg = 
  2902.            248 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2903.            249 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2904.            250 016BH  000DH  0080H 02H Console Output from E-reg = ^M
  2905.            251 016BH  000AH  0080H 02H Console Output from E-reg = ^J
  2906.            252 015EH  0070H  0080H 0BH Get Console Status to A-reg 
  2907.            253 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2908.            254 016BH  0031H  0080H 02H Console Output from E-reg = 1 
  2909.            255 016BH  0037H  0080H 02H Console Output from E-reg = 7 
  2910.            001 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2911.  
  2912.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2913.  
  2914.  
  2915.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 52
  2916.      BUILTIN COMMANDS: DEBUG SUPPORT
  2917.  
  2918.  
  2919.            002 016BH  0020H  0080H 02H Console Output from E-reg = 
  2920.            003 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2921.            004 016BH  0030H  0080H 02H Console Output from E-reg = 0 
  2922.            005 016BH  0020H  0080H 02H Console Output from E-reg = 
  2923.           -- END OF BDOS TRACE TABLE -- 
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  2969.  
  2970.  
  2971.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 53
  2972.      BUILTIN COMMANDS: DEBUG SUPPORT
  2973.  
  2974.  
  2975.  
  2976.      Builtin:  break                break      ________
  2977.                break clear [n [n...]]                break clear [n [n...]] 
  2978.                break set n [n...]                break set n [n...] 
  2979.                b                b 
  2980.                b clear [n [n...]]                b clear [n [n...]] 
  2981.                b set n [n...]                b set n [n...]
  2982.       
  2983.      Manipulates the Breakpoint Table, which contains up to 50 Z80 addresses
  2984.      at which execution of the Z80 is to be halted, and control returned to
  2985.      the Emulator's command prompt. 
  2986.       
  2987.      Breakpoints are typically used in conjunction with the "read" and "go"                                                             read       go
  2988.      commands, and various other debug commands. 
  2989.       
  2990.      The Breakpoint Table is cleared when a new CP/M program is loaded, when
  2991.      the CP/M Segment is Cold Booted, and at various other times when it
  2992.      seems logical to clear it. 
  2993.       
  2994.      If only "break" is entered, then the current Breakpoint Table addresses              break
  2995.      are displayed. 
  2996.       
  2997.      If "break set" is entered followed by one or more Z80 addresses, then         break set
  2998.      the addresses following the command are added to the Table. 
  2999.       
  3000.      If only "break clear" is entered, then all active breakpoint addresses              break clear
  3001.      are removed. No execution breakpoints will occur. 
  3002.       
  3003.      If "break clear" is entered followed by one or more Z80 addresses, then         break clear
  3004.      only the specified addresses are removed from the Breakpoint Table. 
  3005.       
  3006.           NOTE: When a breakpoint is encountered during execution of the
  3007.           Z80 code, that breakpoint's address is automatically cleared
  3008.           from the table.
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3025.  
  3026.  
  3027.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 54
  3028.      BUILTIN COMMANDS: DEBUG SUPPORT
  3029.  
  3030.  
  3031.      Example:
  3032.  
  3033.           Z80 A>break clear                 break clear
  3034.       
  3035.                0 Breakpoints cleared 
  3036.  
  3037.           Z80 A>b set startup startup+3 14f 210 221                 b set startup startup+3 14f 210 221
  3038.       
  3039.                5 Breakpoints set - 5 now in table 
  3040.  
  3041.           Z80 A>b clear 221                 b clear 221
  3042.       
  3043.                1 Breakpoints cleared, 4 left 
  3044.  
  3045.           Z80 A>b                 b
  3046.       
  3047.                Current Breakpoints: 
  3048.                0100H  0103H  014FH  0210H 
  3049.                4 Breakpoints currently set 
  3050.  
  3051.           Z80 A>b clear 210 startup                 b clear 210 startup
  3052.       
  3053.                2 Breakpoints cleared, 2 left 
  3054.  
  3055.           Z80 A>b                 b
  3056.       
  3057.                Current Breakpoints: 
  3058.                0103H  014FH 
  3059.                2 Breakpoints currently set 
  3060.  
  3061.           Z80 A>b clear                 b clear
  3062.       
  3063.                2 Breakpoints cleared 
  3064.  
  3065.           Z80 A>b                 b
  3066.       
  3067.                Current Breakpoints: 
  3068.                0 Breakpoints currently set 
  3069.       
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3081.  
  3082.  
  3083.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 55
  3084.      BUILTIN COMMANDS: DEBUG SUPPORT
  3085.  
  3086.  
  3087.       
  3088.      Builtin:  dump [n1 [n2]]                dump [n1 [n2]]      ________
  3089.                d [n1 [n2]]                d [n1 [n2]]
  3090.       
  3091.      Dumps Z80 (CP/M) memory in HEX and ASCII.
  3092.       
  3093.      If n1 is given, then the first address dumped is n1. If no arguments are
  3094.      present, then the first address is the one following the last one
  3095.      done by a previous dump command.                         dump
  3096.  
  3097.      If n2 is given, then the dump continues through Z80 (CP/M) address n2.
  3098.      If n2 is not given, then n2 is assumed to be 255 bytes beyond the
  3099.      starting address. 
  3100.       
  3101.      A lengthy dump may be interrupted by pressing the SPACE bar. 
  3102.       
  3103.      Example (from an actual session):
  3104.       
  3105.           Z80 A>dump 100                 dump 100
  3106.       
  3107.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3108.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3109.      0100: 21 00 00 39 22 15 02 31  57 02 CD C1 01 FE FF C2 !..9"..1 W.MA.~.B
  3110.      0110: 1B 01 11 F3 01 CD 9C 01  C3 51 01 3E 80 32 13 02 ...s.M.. CQ.>.2..
  3111.      0120: 21 00 00 E5 CD A2 01 E1  DA 51 01 47 7D E6 0F C2 !..eM".a ZQ.G}f.B
  3112.      0130: 44 01 CD 72 01 CD 59 01  0F DA 51 01 7C CD 8F 01 D.Mr.MY. .ZQ.|M..
  3113.      0140: 7D CD 8F 01 23 3E 20 CD  65 01 78 CD 8F 01 C3 23 }M..#> M e.xM..C#
  3114.      0150: 01 CD 72 01 2A 15 02 F9  C9 E5 D5 C5 0E 0B CD 05 .Mr.*..y IeUE..M.
  3115.      0160: 00 C1 D1 E1 C9 E5 D5 C5  0E 02 5F CD 05 00 C1 D1 .AQaIeUE .._M..AQ
  3116.      0170: E1 C9 3E 0D CD 65 01 3E  0A CD 65 01 C9 E6 0F FE aI>.Me.> .Me.If.~
  3117.      0180: 0A D2 89 01 C6 30 C3 8B  01 C6 37 CD 65 01 C9 F5 .R..F0C. .F7Me.Iu
  3118.      0190: 0F 0F 0F 0F CD 7D 01 F1  CD 7D 01 C9 0E 09 CD 05 ....M}.q M}.I..M.
  3119.      01A0: 00 C9 3A 13 02 FE 80 C2  B3 01 CD CE 01 B7 CA B3 .I:..~.B 3.MN.7J3
  3120.      01B0: 01 37 C9 5F 16 00 3C 32  13 02 21 80 00 19 7E B7 .7I_..<2 ..!...~7
  3121.      01C0: C9 AF 32 7C 00 11 5C 00  0E 0F CD 05 00 C9 E5 D5 I/2|..\. ..M..IeU
  3122.      01D0: C5 11 5C 00 0E 14 CD 05  00 C1 D1 E1 C9 46 49 4C E.\...M. .AQaIFIL
  3123.      01E0: 45 20 44 55 4D 50 20 56  45 52 53 49 4F 4E 20 31 E DUMP V ERSION 1
  3124.      01F0: 2E 34 24 0D 0A 4E 4F 20  49 4E 50 55 54 20 46 49 .4$..NO  INPUT FI
  3125.  
  3126.           Z80 A>d primary_fcb secondary_fcb+.15                 d primary_fcb secondary_fcb+.15
  3127.       
  3128.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3129.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3130.      0050:                                      01 44 55 4D              .DUM
  3131.      0060: 50 20 20 20 20 43 4F 4D  00 00 80 00 80 01 00 00 P    COM ........
  3132.      0070: 6D 0B 1B BF 40 F3 00 00  00 F3 00 00             m..?@s.. .s.. 
  3133.  
  3134.  
  3135.  
  3136.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3137.  
  3138.  
  3139.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 56
  3140.      BUILTIN COMMANDS: DEBUG SUPPORT
  3141.  
  3142.  
  3143.  
  3144.      Builtin:  go [n]                go [n]      ________
  3145.                g [n]                g [n]
  3146.       
  3147.       
  3148.      Begins execution of Z80 code at address n. If n is not specified, then
  3149.      the starting address defaults to the current Z80 Program Counter (PC).
  3150.       
  3151.      This is the usual way to run a program that has been read from disk. It                                                          read
  3152.      is also used to continue execution when the Z80 has been stopped via a
  3153.      breakpoint, or by the user pressing the BREAK key. 
  3154.       
  3155.           NOTE: A Z80 command (.COM) file that is invoked by typing
  3156.           its name is automatically run. It does not require this
  3157.           command in order to be executed. 
  3158.       
  3159.      Example: 
  3160.           Z80 A>go                 go
  3161.           Z80 A>g 100                 g 100
  3162.           Z80 A>g -.768                 g -.768
  3163.           Z80 A>go fixit5-3                 go fixit5-3
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3193.  
  3194.  
  3195.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 57
  3196.      BUILTIN COMMANDS: DEBUG SUPPORT
  3197.  
  3198.  
  3199.  
  3200.      Builtin:  find n "text"               find n "text"     ________
  3201.                f n "text"                f n "text"
  3202.       
  3203.       
  3204.      Searches the CP/M Segment for the binary pattern represented by string
  3205.      "text". The search begins at Z80 address n, which is a numeric value as      text
  3206.      described at the start of this section. 
  3207.  
  3208.      The "text" string may (and usually does) include imbedded escape          text
  3209.      sequences, as follows:
  3210.  
  3211.  
  3212.                \\             (single "\" char) 
  3213.                \0             (NUL byte) 
  3214.                \b or \B       (Backspace char) 
  3215.                \t or \T       (TAB char) 
  3216.                \n or \N       (LINEFEED char) 
  3217.                \r or \R       (CARRIAGE RETURN char) 
  3218.                \'             (single apostrophe ("'") char) 
  3219.                \"             (single double-quote char ) 
  3220.                \xFF or \XFF   (byte with HEX value of FF) 
  3221.       
  3222.  
  3223.      The CP/M Segment address of each match is displayed as a four-digit HEX
  3224.      value. The search ends with CP/M Segment address 0FFFFh.
  3225.  
  3226.      Example (from an actual session): 
  3227.  
  3228.           Z80 A>patch 8000 "Joan Riff"                 patch 8000 "Joan Riff"
  3229.       
  3230.           Z80 A>find 100 "Joan"                 find 100 "Joan"
  3231.                8000H 
  3232.  
  3233.           Z80 A>f .256 "\xcd\x05\x00"                 f .256 "\xcd\x05\x00"
  3234.                015EH 016BH 019EH 01CAH 01D6H 
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.  
  3242.  
  3243.  
  3244.  
  3245.  
  3246.  
  3247.  
  3248.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3249.  
  3250.  
  3251.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 58
  3252.      BUILTIN COMMANDS: DEBUG SUPPORT
  3253.  
  3254.  
  3255.       
  3256.      Builtin:  patch [n]               patch [n]     ________
  3257.                patch n "xxxx"                patch n "xxxx" 
  3258.                p [n]               p [n]
  3259.                p n "xxxx"                p n "xxxx"
  3260.       
  3261.      Either enters an interactive patch dialog which allows you to change
  3262.      CP/M memory a byte at a time, or else applies string patch "xxxx" to the                                                                 xxxx
  3263.      CP/M Segment and does not enter interactive patch mode. 
  3264.       
  3265.      If n (which is a numeric value as defined at the start of this section)
  3266.      is specified, then patching starts at address n. If n is not specified,
  3267.      then patching begins with next patch location (the one above the last
  3268.      location patched). Note that in the patch n "xxxx" format, numeric                                         patch n "xxxx"
  3269.      value n is required. 
  3270.       
  3271.      The interactive patch dialog consists of: 
  3272.       
  3273.           1) a prompt which shows the next address to be patched and its
  3274.           current contents.
  3275.  
  3276.           2) user responses. 
  3277.       
  3278.      User responses to the interactive patch prompt are as follows: 
  3279.       
  3280.           ?<return>  A question mark (followed by RETURN) to request a short          ?<return>
  3281.                help message showing available responses. 
  3282.       
  3283.           n<return> A standard numeric argument as described at the start          n<return>
  3284.                of this section. This is the byte value to be patched into the
  3285.                specified CP/M address. 
  3286.       
  3287.                NOTE: This may also be a 16-bit value. If the high-order
  3288.                byte of the resultant n is non-zero, then this is taken
  3289.                to be a 16-bit value, and fills 2 bytes.
  3290.  
  3291.           "xxx" A string of ASCII text, delimited by double-quote characters.          "xxx"
  3292.                The bytes of the string are patched into successive CP/M
  3293.                memory locations. The string may include ASCII escape se-
  3294.                quences as follows: 
  3295.       
  3296.                \\             (single "\" char) 
  3297.                \0             (NUL byte) 
  3298.                \b or \B       (Backspace char) 
  3299.                \t or \T       (TAB char) 
  3300.                \n or \N       (LINEFEED char) 
  3301.                \r or \R       (CARRIAGE RETURN char) 
  3302.                \'             (single apostrophe ("'") char) 
  3303.  
  3304.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3305.  
  3306.  
  3307.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 59
  3308.      BUILTIN COMMANDS: DEBUG SUPPORT
  3309.  
  3310.  
  3311.                \"             (single double-quote char ) 
  3312.                \xFF or \XFF   (byte with HEX value of FF) 
  3313.       
  3314.       
  3315.           <space><return> to leave the addressed byte unchanged, and move to          <space><return>
  3316.                next one. 
  3317.       
  3318.           <return> to exit the interactive patch mode.           <return>
  3319.       
  3320.           ;xxx A comment (everything following the semicolon is ignored).          ;xxx
  3321.  
  3322.       
  3323.       
  3324.      Example (from an actual session):
  3325.  
  3326.           Z80 A>patch 400                 patch 400
  3327.       
  3328.       
  3329.           Enter '?' for help with PATCH entries 
  3330.       
  3331.       
  3332.           0400H (00H) = 'R                         'R
  3333.           0401H (00H) = 'I+20                         'I+20
  3334.           0402H (00H) = "ff\0"                         "ff\0"
  3335.           0405H (00H) = 
  3336.       
  3337.           Z80 A>d 400 40f                 d 400 40f
  3338.       
  3339.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3340.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3341.      0400: 52 69 66 66 00 00 00 00  00 00 00 00 00 00 00 00 Riff.... ........
  3342.  
  3343.           Z80 A>p primary_fcb "JoanRiff   "                 p primary_fcb "JoanRiff   "
  3344.       
  3345.           Z80 A>d primary_fcb secondary_fcb+.15                 d primary_fcb secondary_fcb+.15
  3346.       
  3347.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3348.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3349.      0050:                                      4A 6F 61 6E              Joan
  3350.      0060: 52 69 66 66 20 20 20 4D  00 00 80 00 80 01 00 00 Riff   M ........
  3351.      0070: 6D 0B 1B BF 40 F3 00 00  00 F3 00 00             m..?@s.. .s..  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3361.  
  3362.  
  3363.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 60
  3364.      BUILTIN COMMANDS: DEBUG SUPPORT
  3365.  
  3366.  
  3367.  
  3368.      Builtin:  xreg [rr n]                xreg [rr n]      ________
  3369.                x [rr n]                x [rr n]
  3370.       
  3371.      Sets Z80 register or flag rr to value n. 
  3372.       
  3373.      If no args are present, then the current Z80 register values and flags
  3374.      are displayed. 
  3375.       
  3376.      If args are present, then the register or flag represented by rr is set
  3377.      to the numeric value n (whose format is described at the beginning of
  3378.      this section). 
  3379.       
  3380.           NOTE: The Z80 has a primary and an alternate set of registers
  3381.           and flags. The alternate set is indicated by appending an
  3382.           apostrophe ("'") to the register or flag name. 
  3383.       
  3384.      The register or flag to be set (the rr argument) must be one of the
  3385.      following (in either upper or lowercase): 
  3386.       
  3387.           regs:     A    F    B    C    D    E    H    L 
  3388.                     A'   F'   B'   C'   D'   E'   H'   L' 
  3389.                     AF   BC   DE   HL 
  3390.                     AF'  BC'  DE'  HL' 
  3391.                     IX   IY   SP   PC 
  3392.                     IFF1 IFF2 IMF  I    R 
  3393.       
  3394.           flags:    SF   ZF   HF   P/V  NF   CF 
  3395.                     SF'  ZF'  HF'  P/V' NF'  CF' 
  3396.       
  3397.      Example (from an actual session):
  3398.  
  3399.           Z80 A>xreg pc 0                 xreg pc 0
  3400.       
  3401.           Z80 A>x                 x
  3402.       
  3403.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3404.           0A01 000F 007F FEFC 0000 0000 00 00 FEFE 0000   0    0   0
  3405.           0000'0000'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3406.           L0000:    C3 03 FF       JP   LFF03 
  3407.       
  3408.           Z80 A>xreg bc ffff                 xreg bc ffff
  3409.       
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3417.  
  3418.  
  3419.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 61
  3420.      BUILTIN COMMANDS: DEBUG SUPPORT
  3421.  
  3422.  
  3423.           Z80 A>x                 x
  3424.       
  3425.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3426.           0A01 FFFF 007F FEFC 0000 0000 00 00 FEFE 0000   0    0   0
  3427.           0000'0000'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3428.           L0000:    C3 03 FF       JP   LFF03
  3429.       
  3430.           Z80 A>x c' 'A                 x c' 'A
  3431.       
  3432.           Z80 A>xreg de .256                 xreg de .256
  3433.       
  3434.           Z80 A>xreg AF' 55                 xreg AF' 55
  3435.       
  3436.           Z80 A>xreg                 xreg
  3437.       
  3438.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3439.           0A01 FFFF 0100 FEFC 0000 0000 00 00 FEFE 0000   0    0   0 
  3440.           0055'0041'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3441.           L0000:    C3 03 FF       JP   LFF03 
  3442.       
  3443.  
  3444.  
  3445.  
  3446.  
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3473.  
  3474.  
  3475.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 62
  3476.      BUILTIN COMMANDS: DEBUG SUPPORT
  3477.  
  3478.  
  3479.  
  3480.      Builtin:  trace [n]                trace [n]      ________
  3481.                t [n]                t [n]
  3482.       
  3483.      Traces a certain number (specified by the n argument) of Z80 instruction
  3484.      executions, displaying Z80 regs and flags after each instruction's
  3485.      execution. 
  3486.       
  3487.      Execution begins at the current Z80 Program Counter (PC). 
  3488.       
  3489.      If no argument is given, then n defaults to 1. 
  3490.       
  3491.      The n argument is a numeric value as described at the beginning of this
  3492.      section. 
  3493.  
  3494.           NOTE: The PC of each executed instruction is saved in a
  3495.           circular buffer for later interpretation by the "pc?" builtin                                                           pc?
  3496.           command(q.v.).
  3497.  
  3498.      Example (from an actual trace of DDT.COM's opening lines): 
  3499.  
  3500.           Z80 A>read ddt.com                 read ddt.com
  3501.       
  3502.           *** Low = 0100H  Next = 1400H 
  3503.           *** Z80 DMA, PC and Stack automatically set for .COM file 
  3504.  
  3505.           Z80 A>t 4                 t 4
  3506.       
  3507.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3508.           0A01 0FBC 0100 FEFC 0000 0000 00 00 FEFC 0103   0    0   0 
  3509.           0055'0041'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3510.           L0103:    C3 3D 01       JP   L013D 
  3511.       
  3512.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3513.           0A01 0FBC 0100 FEFC 0000 0000 00 00 FEFC 013D   0    0   0 
  3514.           0055'0041'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3515.           L013D:    31 00 02       LD   SP,L0200 
  3516.       
  3517.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3518.           0A01 0FBC 0100 FEFC 0000 0000 00 00 0200 0140   0    0   0 
  3519.           0055'0041'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3520.           L0140:    C5             PUSH BC 
  3521.       
  3522.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3523.           0A01 0FBC 0100 FEFC 0000 0000 00 00 01FE 0141   0    0   0 
  3524.           0055'0041'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3525.           L0141:    C5             PUSH BC 
  3526.  
  3527.  
  3528.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3529.  
  3530.  
  3531.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 63
  3532.      BUILTIN COMMANDS: DEBUG SUPPORT
  3533.  
  3534.  
  3535.       
  3536.      Builtin:  notrace [n]                notrace [n]      ________
  3537.                n [n]                n [n]
  3538.       
  3539.      Executes a certain number (specified by the n argument) of Z80 instruc-
  3540.      tions, beginning at the current Z80 Program Counter (PC). The Z80
  3541.      registers are not displayed after every instruction, but are displayed                   not                                        are
  3542.      after the last instruction. 
  3543.  
  3544.      If no argument is given, then n defaults to 1. 
  3545.       
  3546.      The n argument is a numeric value as described at the beginning of this
  3547.      section. 
  3548.  
  3549.           NOTE: The PC of each executed instruction is saved in a
  3550.           circular buffer for later interpretation by the "pc?" builtin                                                           pc?
  3551.           command(q.v.).
  3552.       
  3553.      Example: 
  3554.  
  3555.           Z80 A>n 3                 n 3
  3556.       
  3557.           A F  B C  D E  H L  IX   IY   I  R  SP   PC   IFF1 IFF2 IMF
  3558.           0A01 0F09 0130 FEFC 0000 0000 00 00 01FA FEFE   0    0   0 
  3559.           0055'0041'0000'0000'SF=0 ZF=0 HF=0 P/V=0 NF=0 CF=1 
  3560.           LFEFE:    76             HALT 
  3561.       
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3585.  
  3586.  
  3587.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 64
  3588.      BUILTIN COMMANDS: DEBUG SUPPORT
  3589.  
  3590.  
  3591.       
  3592.      Builtin:  pctrace? [FIRST/LAST n [FULL/BRIEF] ]                pctrace? [FIRST/LAST n [FULL/BRIEF] ]      ________
  3593.                pc? [FIRST/LAST n [FULL/BRIEF] ]                pc? [FIRST/LAST n [FULL/BRIEF] ]
  3594.       
  3595.  
  3596.      Displays the Z80 PC's which were saved during the last "trace" or                                                             trace
  3597.      "notrace" execution. This is very useful for finding out how the Z80      notrace
  3598.      wound up at a particular address, or where it went from there.
  3599.  
  3600.      The display may proceed from the oldest PC toward the newest (FIRST n),                                                                   FIRST n
  3601.      or in the reverse direction (LAST n).                                  LAST n
  3602.  
  3603.      The display may include only the PC itself (BRIEF) or the complete                                                 BRIEF
  3604.      disassembled instruction at each PC (FULL).                                          FULL
  3605.  
  3606.      Note that a FULL display assumes that instructions haven't been modified                 FULL
  3607.      since they executed. All that is saved in the circular PC queue is the
  3608.      PC itself. For a FULL display, the current contents of whatever is at                      FULL                                        _______
  3609.      that address is disassembled.
  3610.       
  3611.      The n argument is a numeric value as described at the beginning of this
  3612.      section. 
  3613.  
  3614.      The default is LAST 512 FULL.                    LAST 512 FULL
  3615.  
  3616.      Example: 
  3617.  
  3618.           Z80 A>pc?                 pc?
  3619.           Z80 A>pctrace? first 20 full                pctrace? first 20 full
  3620.           Z80 A>pc? last 20 brief                pc? last 20 brief                                 
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3641.  
  3642.  
  3643.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 65
  3644.      BUILTIN COMMANDS: DEBUG SUPPORT
  3645.  
  3646.  
  3647.       
  3648.      Builtin:  move nlow nhigh ndest                move nlow nhigh ndest      ________
  3649.                m nlow nhigh ndest                m nlow nhigh ndest
  3650.       
  3651.      Moves CP/M memory from one location within the CP/M Segment to another
  3652.      location within the CP/M Segment. 
  3653.       
  3654.      The block of memory to be moved is defined by nlow through nhigh.
  3655.  
  3656.      The new location for the block is defined by ndest. 
  3657.       
  3658.      All three arguments are numeric values as described at the start of this
  3659.      section. 
  3660.       
  3661.           NOTE: The move is done either left-to-right or right-to-left,
  3662.           as needed. So no smearing is possible. 
  3663.       
  3664.      Example (from an actual session): 
  3665.  
  3666.           Z80 A>p primary_fcb "JoanRiff   "                 p primary_fcb "JoanRiff   "
  3667.       
  3668.           Z80 A>d primary_fcb secondary_fcb+.15                 d primary_fcb secondary_fcb+.15
  3669.       
  3670.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3671.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3672.      0050:                                      4A 6F 61 6E              Joan
  3673.      0060: 52 69 66 66 20 20 20 4D  00 00 80 00 80 01 00 00 Riff   M ........
  3674.      0070: 6D 0B 1B BF 40 F3 00 00  00 F3 00 00             m..?@s.. .s.. 
  3675.  
  3676.           Z80 A>move primary_fcb secondary_fcb secondary_fcb                 move primary_fcb secondary_fcb secondary_fcb
  3677.       
  3678.           Z80 A>d primary_fcb secondary_fcb+.15                 d primary_fcb secondary_fcb+.15
  3679.       
  3680.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3681.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3682.      0050:                                      4A 6F 61 6E              Joan
  3683.      0060: 52 69 66 66 20 20 20 4D  00 00 80 00 4A 6F 61 6E Riff   M ....Joan
  3684.      0070: 52 69 66 66 20 20 20 4D  00 00 80 00             Riff   M .... 
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3697.  
  3698.  
  3699.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 66
  3700.      BUILTIN COMMANDS: DEBUG SUPPORT
  3701.  
  3702.  
  3703.       
  3704.      Builtin:  math <expression>               math <expression>     ________
  3705.                ma <expression>               ma <expression>
  3706.       
  3707.      Prints 16-bit evaluated result of expression, which is composed of
  3708.      numeric values (as described at the start of this section) connected
  3709.      with '+' or '-' operators. 
  3710.       
  3711.      The evaluated result is printed in HEX and decimal, as both positive
  3712.      and negative numbers.
  3713.  
  3714.      Example (from an actual session): 
  3715.  
  3716.           Z80 A>math 0-7ff                 math 0-7ff
  3717.       
  3718.                HEX: F801H  -07FFH     Dec: 63489  -02047 
  3719.  
  3720.           Z80 A>ma secondary_fcb-primary_fcb                 ma secondary_fcb-primary_fcb
  3721.       
  3722.                HEX: 0010H  -FFF0H     Dec: 00016  -65520 
  3723.  
  3724.           Z80 A>ma 'A-40+'a                 ma 'A-40+'a
  3725.       
  3726.                HEX: 0062H  -FF9EH     Dec: 00098  -65438 
  3727.  
  3728.  
  3729.  
  3730.  
  3731.  
  3732.  
  3733.  
  3734.  
  3735.  
  3736.  
  3737.  
  3738.  
  3739.  
  3740.  
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3753.  
  3754.  
  3755.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 67
  3756.      BUILTIN COMMANDS: CP/M ENVIRONMENT CONTROL
  3757.  
  3758.  
  3759.  
  3760.      Builtin:  args <tail>                args <tail>      ________
  3761.                ar <tail>                ar <tail>
  3762.       
  3763.      Formats default FCB's at 5Ch and 6Ch as well as default DMA at 80h per
  3764.      command tail, exactly as if <tail> had followed a Z80 command (.COM)
  3765.      filename. 
  3766.       
  3767.      This command is most useful for "filling in" a command tail for Z80 code
  3768.      that has been "read" into CP/M memory and which will look for command-                    read
  3769.      line arguments. 
  3770.       
  3771.      For instance, you may want to debug Digital Research's DDT.COM program,
  3772.      while telling DDT to load file FOO.COM. You would first load DDT via
  3773.       
  3774.           read 100 ddt.com           read 100 ddt.com
  3775.       
  3776.      You would then fill in DDT's command-line arguments with 
  3777.       
  3778.           args foo.com           args foo.com
  3779.       
  3780.      When executed, DDT would then see "FOO.COM" in both the first FCB at 5Ch
  3781.      and as a raw command tail at 80h. 
  3782.       
  3783.      Example (from an actual session): 
  3784.  
  3785.           Z80 A>args testfile001 file0002                 args testfile001 file0002
  3786.       
  3787.           Z80 A>d primary_fcb secondary_fcb+.15                 d primary_fcb secondary_fcb+.15
  3788.       
  3789.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3790.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3791.      0050:                                      00 54 45 53              .TES
  3792.      0060: 54 46 49 4C 45 30 30 31  00 00 00 00 00 46 49 4C TFILE001 .....FIL
  3793.      0070: 45 30 30 30 32 20 20 20  00 00 00 00             E0002    ....
  3794.  
  3795.           Z80 A>d 80 9f                 d 80 9f
  3796.       
  3797.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3798.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3799.      0080: 15 20 54 45 53 54 46 49  4C 45 30 30 31 20 46 49 . TESTFI LE001 FI
  3800.      0090: 4C 45 30 30 30 32 0D 00  00 00 00 00 00 00 00 00 LE0002.. ........
  3801.  
  3802.           Z80 A>args foo.c -n -b -v                 args foo.c -n -b -v
  3803.       
  3804.  
  3805.  
  3806.  
  3807.  
  3808. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3809.  
  3810.  
  3811.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 68
  3812.      BUILTIN COMMANDS: CP/M ENVIRONMENT CONTROL
  3813.  
  3814.  
  3815.           Z80 A>d primary_fcb secondary_fcb+.15                 d primary_fcb secondary_fcb+.15
  3816.       
  3817.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3818.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3819.      0050:                                      00 46 4F 4F              .FOO
  3820.      0060: 20 20 20 20 20 43 20 20  00 00 00 00 00 2D 4E 20      C   .....-N 
  3821.      0070: 20 20 20 20 20 20 20 20  00 00 00 00                      .... 
  3822.  
  3823.           Z80 A>d 80 9f                 d 80 9f
  3824.       
  3825.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  3826.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  3827.      0080: 0F 20 46 4F 4F 2E 43 20  2D 4E 20 2D 42 20 2D 56 . FOO.C  -N -B -V
  3828.      0090: 0D 45 30 30 30 32 0D 00  00 00 00 00 00 00 00 00 .E0002.. ........
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.  
  3840.  
  3841.  
  3842.  
  3843.  
  3844.  
  3845.  
  3846.  
  3847.  
  3848.  
  3849.  
  3850.  
  3851.  
  3852.  
  3853.  
  3854.  
  3855.  
  3856.  
  3857.  
  3858.  
  3859.  
  3860.  
  3861.  
  3862.  
  3863.  
  3864.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3865.  
  3866.  
  3867.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 69
  3868.      BUILTIN COMMANDS: CP/M ENVIRONMENT CONTROL
  3869.  
  3870.  
  3871.  
  3872.      Builtin:  coldboot!                coldboot!      ________
  3873.                cold!                cold!
  3874.       
  3875.      Cold Boots CP/M memory by zeroing the 64K CP/M Segment, installing the
  3876.      BIOS and BDOS hooks, formatting the first page of memory just as CP/M
  3877.      would, etc. 
  3878.       
  3879.      When you first start up the Emulator, the CP/M Segment has already been
  3880.      Cold Booted. 
  3881.       
  3882.      You may use this command to clean things up when you suspect that Z80
  3883.      software may have corrupted the BIOS or BDOS hooks, garbaged page zero,
  3884.      or whatever. 
  3885.       
  3886.      If a Z80 program exits with an Emulator message to the effect that the
  3887.      program requests termination via Cold Boot, then you should use this
  3888.      command to do it. The Z80 program probably had a good reason for asking
  3889.      for a Cold Boot.
  3890.       
  3891.      Example: 
  3892.  
  3893.           Z80 A>coldboot!                 coldboot!
  3894.       
  3895.                *** CP/M Segment COLDBOOTED *** 
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.  
  3902.  
  3903.  
  3904.  
  3905.  
  3906.  
  3907.  
  3908.  
  3909.  
  3910.  
  3911.  
  3912.  
  3913.  
  3914.  
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3921.  
  3922.  
  3923.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 70
  3924.      BUILTIN COMMANDS: CP/M ENVIRONMENT CONTROL
  3925.  
  3926.  
  3927.  
  3928.      Builtin:  terminal [ ON | OFF ]                terminal [ ON | OFF ]      ________
  3929.                term [ ON | OFF ]                term [ ON | OFF ]
  3930.  
  3931.      Enables or disables the builtin VT52 "emulated terminal".
  3932.  
  3933.      If ON is specified, then the emulated CP/M BIOS routines that deal with        ON
  3934.      the console will perform terminal emulation as described previously.
  3935.      Such I/O goes straight to the IBM PC screen (via the IBM PC ROM BIOS
  3936.      routines), and is therefore never seen by PCDOS.
  3937.  
  3938.      If OFF is specified, then the emulated CP/M BIOS routines that deal        OFF
  3939.      with the console will not emulate anything. They will simply act                           not
  3940.      as if the equivalent CP/M BDOS function had been called. This means that
  3941.      CP/M BIOS terminal I/O will go to PCDOS for handling. This makes it
  3942.      available for PCDOS I/O redirection. It also allows a PCDOS emulator
  3943.      (like ANSI.SYS) to become the CP/M terminal emulator.
  3944.  
  3945.      If no argument is specified, then the current state of emulation is
  3946.      simply reported.
  3947.       
  3948.      Example: 
  3949.  
  3950.           Z80 A>term                 term
  3951.       
  3952.           Terminal Emulation is OFF (CP/M BIOS console goes to PCDOS)
  3953.  
  3954.           Z80 A>terminal on                 terminal on
  3955.       
  3956.           Terminal Emulation is ON (via CP/M BIOS) 
  3957.  
  3958.           Z80 A>terminal off                 terminal off
  3959.       
  3960.           Terminal Emulation is OFF (CP/M BIOS console goes to PCDOS)
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.  
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.  
  3975.  
  3976.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  3977.  
  3978.  
  3979.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 71
  3980.      BUILTIN COMMANDS: CP/M ENVIRONMENT CONTROL
  3981.  
  3982.  
  3983.       
  3984.      Builtin:  read [n] <filename.typ>                read [n] <filename.typ>      ________
  3985.                r [n] <filename.typ>                r [n] <filename.typ>
  3986.       
  3987.      Reads data from specified file into the CP/M Segment, at address n.
  3988.       
  3989.      If n is absent, then it defaults to 0100. 
  3990.       
  3991.      This is the primary method used to load Z80 software for debugging. It
  3992.      is normally used to read Z80 command (.COM) files into memory, but this
  3993.      command will also read raw data files with no problem. 
  3994.       
  3995.      If <filename.typ> has a filetype of .HEX, then the file is assumed to be
  3996.      in standard Intel HEX format, and is loaded into memory at addresses
  3997.      specified by the HEX records. In such a case, the n argument may have no
  3998.      meaning.
  3999.       
  4000.      The n argument is a numeric value of the sort described at the beginning
  4001.      of this section. 
  4002.  
  4003.           NOTE: If a read of a file causes data to be read below 0100h                     read
  4004.           or above FD00h, then the CP/M environment will be clobbered.
  4005.           If you're developing non-CP/M Z80 code, then who cares. If
  4006.           you're reading in a file that expects to call CP/M, however,
  4007.           then running the thing with a clobbered CP/M environment just
  4008.           might scramble the brains of the imaginary Z80.
  4009.       
  4010.      This command is used by us at CCS to load test versions of our Z80
  4011.      software, which we leave in .HEX format when we run L80. 
  4012.       
  4013.      Example: 
  4014.  
  4015.           Z80 A>read 100 820init.com                 read 100 820init.com
  4016.       
  4017.                *** Low = 0100H  Next = 0380H 
  4018.                *** Z80 DMA, PC and Stack automatically set for .COM file 
  4019.  
  4020.           Z80 A>write 100 360 820init.hex                 write 100 360 820init.hex
  4021.       
  4022.                Writing HEX records for 0100H thru 0360H (609 bytes) to file
  4023.                '820INIT.HEX' 
  4024.  
  4025.           Z80 A>read 820init.hex                 read 820init.hex
  4026.       
  4027.                *** .HEX file Starting Address = 0100H 
  4028.                *** Low = 0100H  Next = 0360H 
  4029.  
  4030.  
  4031.  
  4032.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4033.  
  4034.  
  4035.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 72
  4036.      BUILTIN COMMANDS: CP/M ENVIRONMENT CONTROL
  4037.  
  4038.  
  4039.       
  4040.      Builtin:  write nlow nhigh <filename.typ>                write nlow nhigh <filename.typ>      ________
  4041.                w nlow nhigh <filename.typ>                w nlow nhigh <filename.typ>
  4042.       
  4043.      Write a block of CP/M memory to a disk file. 
  4044.       
  4045.      The bounds of the block to be written are specified by nlow and nhigh,
  4046.      which are numeric values as described at the start of this section.
  4047.       
  4048.      The specified block of memory is written from the CP/M Segment to the
  4049.      specified file. It is written as a pure memory image, unless a .HEX
  4050.      extension is supplied.
  4051.       
  4052.      Specifying a filename of type .HEX will cause an Intel HEX file to be                                        will
  4053.      written. The final record of the generated HEX file is the special
  4054.      HEX record which specifies the starting execution address of the
  4055.      program. This address is assumed to be nlow.
  4056.  
  4057.      Example: 
  4058.  
  4059.           Z80 A>read 100 820init.com                 read 100 820init.com
  4060.       
  4061.                *** Low = 0100H  Next = 0380H 
  4062.                *** Z80 DMA, PC and Stack automatically set for .COM file 
  4063.  
  4064.           Z80 A>write 100 360 820init.hex                 write 100 360 820init.hex
  4065.       
  4066.                Writing HEX records for 0100H thru 0360H (609 bytes) to file
  4067.                '820INIT.HEX' 
  4068.  
  4069.           Z80 A>read 820init.hex                 read 820init.hex
  4070.       
  4071.                *** .HEX file Starting Address = 0100H 
  4072.                *** Low = 0100H  Next = 0360H 
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4089.  
  4090.  
  4091.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 73
  4092.      BUILTIN COMMANDS: CP/M ENVIRONMENT CONTROL
  4093.  
  4094.  
  4095.       
  4096.      Builtin:  submit <filename.typ>                submit <filename.typ>      ________
  4097.                sub <filename.typ>                sub <filename.typ>
  4098.       
  4099.      Switches input (for Emulator commands only) to the specified file.
  4100.  
  4101.      This is roughly equivalent to the CP/M SUBMIT.COM program, except that
  4102.      it is built into the Emulator. 
  4103.       
  4104.      Z80 application input via BDOS and BIOS does not get switched. Only
  4105.      Emulator input is switched. Submit files cannot be nested.                                 Submit
  4106.       
  4107.      Input reverts to the standard input (as defined by PCDOS) when EOF is
  4108.      detected on the specified file. 
  4109.  
  4110.           NOTE: If a keypress is detected during submit file processing                                                 submit
  4111.           but outside of Z80 operation (i.e. - when the Emulator is
  4112.           expecting a command), then the submit file is aborted. This                                         submit
  4113.           is how you cancel a submit file - just press SPACE while it
  4114.           is running.
  4115.       
  4116.      Example: 
  4117.           Z80 A>submit script                 submit script
  4118.           Z80 A>sub c:\cpm\autoexec.z80                sub c:\cpm\autoexec.z80
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4145.  
  4146.  
  4147.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 74
  4148.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4149.  
  4150.  
  4151.       
  4152.      Builtin:  list [n1 [n2]] [>outfile | >>outfile]                list [n1 [n2]] [>outfile | >>outfile]      ________
  4153.                list prologue n1 n2 [>outfile | >>outfile]                list prologue n1 n2 [>outfile | >>outfile] 
  4154.                list include [A][O][F]                list include [A][O][F] 
  4155.                l [n1 [n2]] [>outfile | >>outfile]                l [n1 [n2]] [>outfile | >>outfile] 
  4156.                l prologue n1 n2 [>outfile | >>outfile]                l prologue n1 n2 [>outfile | >>outfile] 
  4157.                l include [A][O][F]                l include [A][O][F] 
  4158.       
  4159.      This is a multi-purpose disassembly command, which does one of three
  4160.      things (depending upon the arguments that are present):
  4161.       
  4162.           Lists disassembled Z80 object code (first form). 
  4163.       
  4164.           Generates an assembler prologue for the given range of Z80
  4165.           object code (second form). 
  4166.       
  4167.           Specifies fields to be included in disassembly lines (third
  4168.           form). 
  4169.       
  4170.  
  4171.  
  4172.      Format:  list [n1 [n2]] [>outfile | >>outfile]               list [n1 [n2]] [>outfile | >>outfile] 
  4173.               l [n1 [n2]] [>outfile | >>outfile]               l [n1 [n2]] [>outfile | >>outfile] 
  4174.       
  4175.      This form causes the disassembly of Z80 object code from CP/M address n1
  4176.      through CP/M address n2 (both of which are numeric values as defined at
  4177.      the start of this section). If n2 is absent, then n2 is assumed to be
  4178.      n1+22. If n1 is absent, then it defaults to the next address to be
  4179.      disassembled (as left by last list command).                                    list
  4180.       
  4181.      The generated disassembly is sent to (">outfile") or appended to                                            >outfile
  4182.      (">>outfile") the specified output file. If an output file is not       >>outfile
  4183.      specified (no ">" character present), then the generated disassembly
  4184.      goes to the standard output as defined by PCDOS (normally the screen). 
  4185.  
  4186.           NOTE: Disassembly speed decreases as the size of the control
  4187.           table increases. It may also be slowed by PCDOS being so
  4188.           lethargic with screen output. When disassembling the Radio
  4189.           Shack Model 100's memory (which required a control table of
  4190.           about 42K), for instance, we were only getting about 2 lines
  4191.           of disassembled code per second. 
  4192.  
  4193.      Generated source code is suitable for input to M80.COM in .Z80 mode.
  4194.      Note, however, that any RST instructions use as their argument the
  4195.      final address being jumped to, not the RST number (as is customary).
  4196.      Also, there is no END statement supplied.
  4197.  
  4198.  
  4199.  
  4200.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4201.  
  4202.  
  4203.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 75
  4204.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4205.  
  4206.  
  4207.       
  4208.      Format:  list prologue n1 n2 [>outfile | >>outfile]               list prologue n1 n2 [>outfile | >>outfile] 
  4209.               l prologue n1 n2 [>outfile | >>outfile]               l prologue n1 n2 [>outfile | >>outfile] 
  4210.       
  4211.      This form generates assembler source code suitable for inclusion at the
  4212.      front of a Z80 source file. The generated source code is the prologue
  4213.      for a given block of Z80 object code, defined by CP/M addresses n1 and
  4214.      n2. Both n1 and n2 are numeric values as defined at the start of this
  4215.      section. 
  4216.       
  4217.      The generated prologue contains equates for the various ASCII control
  4218.      characters. Additionally, it contains equated labels for any CP/M
  4219.      addresses that are referenced by the specified block of Z80 code (from
  4220.      n1 to n2), but not contained within it. 
  4221.       
  4222.      Such a prologue is generally needed at the front of any sizeable Z80
  4223.      disassembly. 
  4224.       
  4225.      The generated prologue is sent to (">outfile") or appended to (">>out-                                         >outfile                    >>out-
  4226.      file") the specified output file. If an output file is not specified,     file
  4227.      (no ">" character present), then the generated prologue goes to the
  4228.      standard output as defined by PCDOS (normally the screen). 
  4229.  
  4230.  
  4231.       
  4232.      Format:  list include [A][O][F]               list include [A][O][F] 
  4233.               l include [A][O][F]               l include [A][O][F] 
  4234.       
  4235.      Specifies the fields to be included in disassembled Z80 instructions.
  4236.       
  4237.      If the "A" arg is present, then CP/M addresses will be included at the             A                            addresses
  4238.      left of disassembled instructions. 
  4239.       
  4240.      If the "O" argument is present, then raw opcodes will be included after             O                                opcodes
  4241.      the address (if present) but before the Z80 mnemonic. 
  4242.       
  4243.      If the "F" argument is present, then the disassembled Z80 instruction             F
  4244.      will include a comment explaining the instruction's possible effect(s)
  4245.      on the Z80 flags.                 flags
  4246.       
  4247.      Arguments after "include" may be whole words. Only the first character                      include
  4248.      is checked. 
  4249.       
  4250.      If no arguments appear after "include", then the disassembled Z80                                   include
  4251.      instruction will consist only of the mnemonic field. 
  4252.  
  4253.  
  4254.  
  4255.  
  4256.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4257.  
  4258.  
  4259.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 76
  4260.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4261.  
  4262.  
  4263.       
  4264.      Example: 
  4265.           Z80 A>list include addresses                 list include addresses
  4266.           Z80 A>list include                 list include
  4267.           Z80 A>l prologue 100 7ff                 l prologue 100 7ff
  4268.           Z80 A>list prologue 0 ffff >model100.rom                 list prologue 0 ffff >model100.rom
  4269.           Z80 A>list 0 ffff >>model100.rom                list 0 ffff >>model100.rom
  4270.           Z80 A>list                list
  4271.  
  4272.  
  4273.           NOTE: The next section contains a sample Emulator session
  4274.           which generates source code from object code. Refer to it for
  4275.           more detail about this and related Resource commands.
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.  
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.  
  4296.  
  4297.  
  4298.  
  4299.  
  4300.  
  4301.  
  4302.  
  4303.  
  4304.  
  4305.  
  4306.  
  4307.  
  4308.  
  4309.  
  4310.  
  4311.  
  4312.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4313.  
  4314.  
  4315.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 77
  4316.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4317.  
  4318.  
  4319.  
  4320.      Builtin:  control list [n]                control list [n]      ________
  4321.                control clear                control clear 
  4322.                control read <filepath>                control read <filepath> 
  4323.                control write <filepath>                control write <filepath> 
  4324.                control n     i | b | w | t | s | c                control n     i | b | w | t | s | c 
  4325.                c list [n]                c list [n] 
  4326.                c clear                c clear 
  4327.                c read <filepath>                c read <filepath> 
  4328.                c write <filepath>                c write <filepath> 
  4329.                c n     i | b | w | t | s | c                c n     i | b | w | t | s | c 
  4330.       
  4331.      This is a multi-purpose command which manipulates the disassembly
  4332.      control table. 
  4333.       
  4334.      The disassembly control table holds CP/M addresses and any or all of the
  4335.      following which are associated with each address: 
  4336.       
  4337.           The data type of the Z80 object code at this address. This is
  4338.                called a "control break". 
  4339.       
  4340.           A symbolic label to be associated with the address. 
  4341.       
  4342.           A comment to be associated with the address. 
  4343.       
  4344.       
  4345.      This control table is used by the disassembler (the list command), and                                                         list
  4346.      tells it how to format the source code while disassembling. 
  4347.       
  4348.      The various data type control breaks that may be associated with a CP/M
  4349.      address are as follows: 
  4350.       
  4351.           Instructions (executable Z80 code, disassembled as mnemonics)
  4352.       
  4353.           Bytes (disassembled as DB pseudo-ops) 
  4354.       
  4355.           Words (disassembled as DW pseudo-ops, multiple entries per
  4356.                line) 
  4357.       
  4358.           Table of Words (disassembled as DW pseudo-ops, one per line)
  4359.       
  4360.           Storage (disassembled as DS with argument large enough to
  4361.                bring it up to next control entry) 
  4362.       
  4363.       
  4364.      This is how the disassembler knows which parts of your Z80 object code
  4365.      are instructions, which are data, and which are irrelevant buffers etc. 
  4366.  
  4367.  
  4368.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4369.  
  4370.  
  4371.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 78
  4372.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4373.  
  4374.  
  4375.      The specific formats are described below.
  4376.  
  4377.  
  4378.      Format:  control list [n]               control list [n]
  4379.               c list [n]               c list [n]
  4380.       
  4381.      This format of the command causes the Emulator to display all control
  4382.      table information that is currently known to it. If numeric value n (see
  4383.      definition of legal numeric values at start of this section) is present,
  4384.      then only control information associated with CP/M addresses greater
  4385.      than or equal to n are listed. 
  4386.       
  4387.      The list includes any control breaks, labels, and comments associated
  4388.      with the various CP/M addresses. 
  4389.       
  4390.  
  4391.  
  4392.      Format:  control clear               control clear
  4393.               c clear               c clear
  4394.       
  4395.      This format of the command clears out the control table, so that nothing
  4396.      is known about the Z80 object code. No CP/M addresses, control breaks,
  4397.      labels or comments are defined after this command is given. 
  4398.       
  4399.       
  4400.  
  4401.      Format:  control read <filepath>               control read <filepath>
  4402.               c read <filepath>               c read <filepath>
  4403.       
  4404.      This format of the command causes the Emulator to read a control table
  4405.      from the specified filename. The file must have been created by a                                           must
  4406.      "control write <filepath>" command.       control write <filepath>
  4407.       
  4408.      A currently-defined control table is cleared before the new one is read
  4409.      from disk. It is not possible to merge control tables using this
  4410.      command. 
  4411.       
  4412.       
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4425.  
  4426.  
  4427.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 79
  4428.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4429.  
  4430.  
  4431.      Format:  control write <filepath>               control write <filepath>
  4432.               c write <filepath>               c write <filepath>
  4433.       
  4434.      This command writes the current control table to the specified file, for
  4435.      later input via the "control read <filepath>" command. All known data is                          control read <filepath>
  4436.      written - CP/M addresses, control breaks, labels and comments. 
  4437.       
  4438.       
  4439.  
  4440.      Format:  control n     i | b | w | t | s | c               control n     i | b | w | t | s | c
  4441.               c n     i | b | w | t | s | c               c n     i | b | w | t | s | c
  4442.       
  4443.      This format of the command is the real workhorse of control table
  4444.      maintenance. It associates a Z80 data type with CP/M address n, which is
  4445.      a numeric value as defined at the start of this section. 
  4446.       
  4447.      The argument following CP/M address n is a directive to the disassembler
  4448.      (the list command), and may be any one of the following (note that only          list                          one
  4449.      the first character is required): 
  4450.       
  4451.           Instructions: switch to Z80 mnemonics when you get to this          I
  4452.                address. 
  4453.       
  4454.           Bytes: switch to DB pseudo-ops when you get to this address.          B
  4455.       
  4456.           Words: switch to DW pseudo-ops (multiple per line) when you          W
  4457.                get to this address. 
  4458.       
  4459.           Table of words: switch to DW pseudo-ops (one per line) when          T
  4460.                you get to this address. This is useful for jump tables,
  4461.                etc, where you want the source code to be neatly ar-
  4462.                ranged. 
  4463.       
  4464.           Storage: do a single DS (define storage) pseudo-op when you          S
  4465.                get to this address, and make the size field big enough
  4466.                to take you up to the next control break address (or the
  4467.                end of the disassembly, whichever is lower). 
  4468.  
  4469.       
  4470.      You may also specify a special argument, which is handled immediately
  4471.      and never gets to the disassembler: 
  4472.       
  4473.           Clear: Clear this address's control break data type. This does          C
  4474.                not remove an associated label or comment. It just undoes               not
  4475.                any control break (of one of the above types) associated
  4476.                with this CP/M address. 
  4477.       
  4478.       
  4479.  
  4480. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4481.  
  4482.  
  4483.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 80
  4484.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4485.  
  4486.  
  4487.  
  4488.      Example: 
  4489.           Z80 A>control list                 control list
  4490.           Z80 A>c clear                 c clear
  4491.           Z80 A>c read b:\model100\model100.ctl                 c read b:\model100\model100.ctl
  4492.           Z80 A>control write foo.ctl                 control write foo.ctl
  4493.           Z80 A>c read xyz                 c read xyz
  4494.           Z80 A>control 100 Instructions                 control 100 Instructions
  4495.           Z80 A>c 103 b                 c 103 b
  4496.           Z80 A>c table_start+1 S                 c table_start+1 S
  4497.           Z80 A>CONTROL bios_address W                 CONTROL bios_address W
  4498.           Z80 A>c FF00 Table                 c FF00 Table
  4499.           Z80 A>c 103 clear                c 103 clear
  4500.  
  4501.  
  4502.  
  4503.  
  4504.           NOTE: The next section contains a sample Emulator session
  4505.           which generates source code from object code. Refer to it for
  4506.           more detail about this and related Resource commands.
  4507.       
  4508.  
  4509.  
  4510.  
  4511.  
  4512.  
  4513.  
  4514.  
  4515.  
  4516.  
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.  
  4536. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4537.  
  4538.  
  4539.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 81
  4540.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4541.  
  4542.  
  4543.       
  4544.      Builtin:  label n [label_name]                label n [label_name]      ________
  4545.                label autogen n1 n2                label autogen n1 n2 
  4546.                = n [label_name]                = n [label_name] 
  4547.                = autogen n1 n2                = autogen n1 n2 
  4548.       
  4549.      This command controls the assignment of symbolic label names to various
  4550.      CP/M addresses. Symbolic labels may be used as numeric values in many
  4551.      Emulator commands. They are also used by the disassembler when creating
  4552.      source code from Z80 object code. 
  4553.  
  4554.  
  4555.       
  4556.       
  4557.      Format:  label n [label_name]               label n [label_name]
  4558.               = n [label_name]               = n [label_name]
  4559.       
  4560.      This format associates label_name with CP/M address n, which is a
  4561.      numeric value as described at the start of this section. 
  4562.       
  4563.      Label names may be up to 32 characters in length. They must contain only
  4564.      alphanumeric characters and the underscore character "_". 
  4565.       
  4566.      If label_name is absent in this command, then any existing label name
  4567.      associated with the specified CP/M address is simply deleted. 
  4568.       
  4569.       
  4570.       
  4571.       
  4572.      Format:  label autogen n1 n2               label autogen n1 n2
  4573.               = autogen n1 n2               = autogen n1 n2
  4574.       
  4575.      This format causes the Emulator to automatically generate labels (of
  4576.      format AUTOxxxx) for all unlabeled CP/M addresses that are referenced by
  4577.      the block of Z80 code that starts at n1 and ends at n2 (both of which
  4578.      are numeric values as defined at the start of this section). 
  4579.       
  4580.      Labels that are generated are automatically entered into the current
  4581.      control table. Existing labels will not be altered. 
  4582.       
  4583.      This is a quick way to create labels. It can be useful for rapid
  4584.      generation of readable source code from Z80 object code. You should,
  4585.      however, define any recognizable labels before using this command. You
  4586.      should also make sure that you have pretty accurately defined all
  4587.      control breaks that apply to the specified block of Z80 code. There's
  4588.      nothing worse than getting a block of data confused with instructions,
  4589.      and having this command generate a few hundred bogus labels by misinter-
  4590.      preting the Z80 code. 
  4591.  
  4592.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4593.  
  4594.  
  4595.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 82
  4596.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4597.  
  4598.  
  4599.       
  4600.      So this is generally the last thing that you do before deciding that
  4601.      you have finished disassembling a complete Z80 program. 
  4602.       
  4603.  
  4604.  
  4605.           NOTE: 16-bit literals will be ignored. There's no way - short
  4606.           of human inspection - to tell if the 16-bit value is meant to
  4607.           be a Z80 address or just a binary value (like a loop counter).
  4608.           In previous versions of the Emulator, there were too many
  4609.           bogus labels being autogen'd from 16-bit literals. Now it is                             autogen
  4610.           up to you to decide whether a particular 16-bit literal
  4611.           should have a label associated with it. Specifically, the
  4612.           following instructions' 16-bit literals are ignored:
  4613.  
  4614.                     LD   IX,nn
  4615.                     LD   IY,nn
  4616.                     LD   BC,nn
  4617.                     LD   DE,nn
  4618.                     LD   HL,nn
  4619.                     LD   SP,nn
  4620.  
  4621.  
  4622.      Example: 
  4623.           Z80 A>= 100 program_entry                 = 100 program_entry
  4624.           Z80 A>label 7ff program_end                 label 7ff program_end
  4625.           Z80 A>= 0 warm_boot_jump                 = 0 warm_boot_jump
  4626.           Z80 A>= 5C FCB1                 = 5C FCB1
  4627.           Z80 A>= 5 BDOS                 = 5 BDOS
  4628.           Z80 A>label autogen 100 7ff                label autogen 100 7ff
  4629.  
  4630.  
  4631.  
  4632.  
  4633.           NOTE: The next section contains a sample Emulator session
  4634.           which generates source code from object code. Refer to it for
  4635.           more detail about this and related Resource commands.
  4636.  
  4637.  
  4638.  
  4639.  
  4640.  
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.  
  4647.  
  4648.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4649.  
  4650.  
  4651.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 83
  4652.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4653.  
  4654.  
  4655.  
  4656.      Builtin:  comment n ["text"]                comment n ["text"]      ________
  4657.                ; n ["text"]                ; n ["text"] 
  4658.       
  4659.      Associates source-code comment "text" with CP/M address n, which is a                                     text
  4660.      numeric value as defined at the start of this section. "text" may be up                                                             text
  4661.      to 254 characters long. 
  4662.       
  4663.      If "text" is absent, then any existing comment associated with address n         text
  4664.      is simply deleted. 
  4665.       
  4666.      Note that "text" must be enclosed in double quotes. It may include                text
  4667.      escape sequences as follows: 
  4668.       
  4669.           \\             Single "\" char 
  4670.           \0             NUL byte 
  4671.           \b or \B       Backspace char 
  4672.           \t or \T       Tab char 
  4673.           \n or \N       Linefeed char 
  4674.           \r or \R       Return char 
  4675.           \'             Single quote char 
  4676.           \"             Double quote char 
  4677.           \xFF or \XFF   Byte with HEX value FF 
  4678.       
  4679.      These escape codes made be used to make the comment more readable.
  4680.  
  4681.       
  4682.      When a comment is detected by the disassembler, it will be printed in
  4683.      one of two places: 
  4684.       
  4685.           As a line comment, after the mnemonic. Such a comment replaces
  4686.                the flags comment field (if present). If "text" starts                                                         text
  4687.                with other than a "\n" escape, then the comment is
  4688.                printed in this manner. 
  4689.       
  4690.           As a multi-line comment, on lines before the instruction. If
  4691.                "text" starts with a "\n" escape, then the comment will                text
  4692.                be printed in this manner. Blank comment lines (starting
  4693.                with ";") are automatically provided before and after the
  4694.                comment, and ";" characters are inserted after every "\n"
  4695.                or "\r" found in the "text" string.                                      text
  4696.       
  4697.       
  4698.      If you want to create a nice-looking multi-line comment, then imbed "\n"
  4699.      escapes as line delimiters, and "\t" escapes to line things up on
  4700.      succeeding lines. 
  4701.       
  4702.  
  4703.  
  4704. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4705.  
  4706.  
  4707.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 84
  4708.      BUILTIN COMMANDS: RESOURCE FACILITY COMMANDS
  4709.  
  4710.  
  4711.      If your comment is intended to be a single-line comment appended to the
  4712.      disassembled instruction's mnemonic, then avoid imbedded "\n" and "\r"
  4713.      escapes. 
  4714.  
  4715.       
  4716.      Example: 
  4717.           Z80 A>comment 100 "\nStart of main program"                 comment 100 "\nStart of main program"
  4718.           Z80 A>; 0 "Jump to BIOS Warm, Start"                 ; 0 "Jump to BIOS Warm, Start"
  4719.           Z80 A>; 100                 ; 100
  4720.           Z80 A>comment ff00 "\nBIOS Jump Table\n\n\t3 bytes per JMP"                comment ff00 "\nBIOS Jump Table\n\n\t3 bytes per JMP"
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.           NOTE: The next section contains a sample Emulator session
  4727.           which generates source code from object code. Refer to it for
  4728.           more detail about this and related Resource commands.
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.  
  4748.  
  4749.  
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.  
  4758.  
  4759.  
  4760.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4761.  
  4762.  
  4763.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 85
  4764.      USING THE RESOURCE BUILTIN COMMANDS
  4765.  
  4766.  
  4767.       
  4768.  
  4769.  
  4770.  
  4771.  
  4772.  
  4773.  
  4774.  
  4775.  
  4776.  
  4777.                       USING THE RESOURCE BUILTIN COMMANDS                       USING THE RESOURCE BUILTIN COMMANDS
  4778.  
  4779.  
  4780.      This section presents an example of re-sourcing a piece of Z80 object
  4781.      code. It demonstrates the use of the various Emulator builtin commands
  4782.      that deal with regenerating source code from object code.
  4783.  
  4784.      We were recently presented with a piece of software which (wouldn't you
  4785.      know it) existed only in object form on a Xerox 820 CP/M system. The
  4786.      owner of this little utility really wanted to move it to a 16-bit
  4787.      Hyperion system, cause the utility sets up a Z80 SIO and that's what the
  4788.      Hyperion has - an SIO.
  4789.  
  4790.      So he was wondering - could we regenerate the source code for this
  4791.      little utility?
  4792.  
  4793.  
  4794.  
  4795.           NOTE: The first step is to read the thing into Z80 memory
  4796.           with the Emulator, and clear any previous resource control
  4797.           breaks.
  4798.       
  4799.      Z80 C>read 100 820init.com            read 100 820init.com
  4800.       
  4801.      *** Low = 0100H  Next = 0380H 
  4802.      *** Z80 DMA, PC and Stack automatically set for .COM file 
  4803.      Z80 C>control clear            control clear
  4804.       
  4805.      Z80 C>list include addresses opcodes            list include addresses opcodes
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4817.  
  4818.  
  4819.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 86
  4820.      USING THE RESOURCE BUILTIN COMMANDS
  4821.  
  4822.  
  4823.           NOTE: The next thing to do is take a quick look at the
  4824.           program, and get a general feel for what it does.
  4825.       
  4826.      Z80 C>list            list
  4827.       
  4828.      L0100:     11 45 02              LD     DE,L0245 
  4829.      L0103:     CD 40 02              CALL   L0240 
  4830.      L0106:     11 C8 02              LD     DE,L02C8 
  4831.      L0109:     CD 40 02              CALL   L0240 
  4832.      L010C:     CD 35 02              CALL   L0235 
  4833.      L010F:     FE 0D                 CP     CR 
  4834.      L0111:     C2 16 01              JP     NZ,L0116 
  4835.      L0114:     3E 36                 LD     A,'6' 
  4836.      L0116:     D6 30                 SUB    '0' 
  4837.  
  4838.  
  4839.  
  4840.           NOTE: This isn't real promising. Let's dump the thing and
  4841.           look for obvious ASCII strings.
  4842.  
  4843.      Z80 C>d 100 37f            d 100 37f
  4844.       
  4845.      ADDR  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F 01234567 89ABCDEF
  4846.      ----  -- -- -- -- -- -- -- --  -- -- -- -- -- -- -- -- -------- --------
  4847.      0100: 11 45 02 CD 40 02 11 C8  02 CD 40 02 CD 35 02 FE .E.M@..H .M@.M5.~
  4848.      0110: 0D C2 16 01 3E 36 D6 30  FE 00 DA 06 01 FE 0A D2 .B..>6V0 ~.Z..~.R
  4849.      0120: 06 01 32 58 03 11 EF 02  CD 40 02 CD 35 02 FE 0D ..2X..o. M@.M5.~.
  4850.      0130: C2 35 01 3E 4E FE 45 CA  47 01 FE 4F CA 47 01 FE B5.>N~EJ G.~OJG.~
  4851.      0140: 4E CA 47 01 C3 25 01 32  5A 03 11 16 03 CD 40 02 NJG.C%.2 Z....M@.
  4852.      0150: CD 35 02 FE 0D C2 5A 01  3E 38 D6 30 FE 07 CA 69 M5.~.BZ. >8V0~.Ji
  4853.      0160: 01 FE 08 CA 69 01 C3 4A  01 32 59 03 3A 58 03 FE .~.Ji.CJ .2Y.:X.~
  4854.      0170: 00 C2 79 01 3E 0F C3 B7  01 FE 01 C2 83 01 3E 0E .By.>.C7 .~.B..>.
  4855.      0180: C3 B7 01 FE 02 C2 8D 01  3E 0C C3 B7 01 FE 03 C2 C7.~.B.. >.C7.~.B
  4856.      0190: 97 01 3E 0A C3 B7 01 FE  04 C2 A1 01 3E 07 C3 B7 ..>.C7.~ .B!.>.C7
  4857.      01A0: 01 FE 05 C2 AB 01 3E 06  C3 B7 01 FE 06 C2 B5 01 .~.B+.>. C7.~.B5.
  4858.      01B0: 3E 05 C3 B7 01 3E 02 32  58 03 3A 5A 03 FE 45 C2 >.C7.>.2 X.:Z.~EB
  4859.      01C0: C7 01 3E 03 C3 D3 01 FE  4F C2 D1 01 3E 01 C3 D3 G.>.CS.~ OBQ.>.CS
  4860.      01D0: 01 3E 00 32 5A 03 3A 59  03 FE 07 CA EB 01 3E 60 .>.2Z.:Y .~.Jk.>`
  4861.      01E0: 32 5B 03 3E C0 32 5C 03  C3 F5 01 3E 20 32 5B 03 2[.>@2\.  Cu.>2[.
  4862.      01F0: 3E 40 32 5C 03 F3 3E 18  D3 06 D3 06 3E 01 D3 06 >@2\.s>. S.S.>.S.
  4863.      0200: AF D3 06 3E 04 D3 06 3A  5A 03 C6 44 D3 06 3E 03 /S.>.S.: Z.FDS.>.
  4864.      0210: D3 06 3A 5C 03 C6 01 D3  06 3E 05 D3 06 3A 5B 03 S.:\.F.S .>.S.:[.
  4865.      0220: C6 8A D3 06 3E 47 D3 00  3A 58 03 D3 00 FB 11 3D F.S.>GS. :X.S.{.=
  4866.      0230: 03 CD 40 02 C9 0E 01 CD  05 00 FE 60 D8 D6 20 C9 .M@.I..M  ..~`XVI
  4867.      0240: 0E 09 C3 05 00 1A 49 4E  49 54 20 31 2E 30 20 66 ..C...IN  IT 1.0f
  4868.      0250: 6F 72 20 58 65 72 6F 78  20 38 32 30 0D 0A 0A 0A or Xerox  820....
  4869.      0260: 0D 0A 42 61 75 64 20 52  61 74 65 73 3A 0D 0A 31 ..Baud R ates:..1
  4870.      0270: 39 32 30 30 20 3D 20 30  0D 0A 39 36 30 30 20 20 9200 = 0 ..9600 
  4871.  
  4872.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4873.  
  4874.  
  4875.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 87
  4876.      USING THE RESOURCE BUILTIN COMMANDS
  4877.  
  4878.  
  4879.      0280: 3D 20 31 0D 0A 34 38 30  30 20 20 3D 20 32 0D 0A = 1..480 0  = 2..
  4880.      0290: 32 34 30 30 20 20 3D 20  33 0D 0A 31 32 30 30 20 2400  =  3..1200
  4881.      02A0: 20 3D 20 34 0D 0A 20 36  30 30 20 20 3D 20 35 0D  = 4.. 6 00  = 5.
  4882.      02B0: 0A 20 33 30 30 20 20 3D  20 36 0D 0A 20 31 31 30 . 300  =  6.. 110
  4883.      02C0: 20 20 3D 20 37 0D 0A 24  0D 0A 53 65 6C 65 63 74   = 7..$ ..Select
  4884.      02D0: 20 62 61 75 64 20 72 61  74 65 20 20 20 20 20 20  baud ra te     
  4885.      02E0: 20 20 20 20 20 28 31 2D  39 29 3A 20 36 08 24 0D      (1- 9): 6.$.
  4886.      02F0: 0A 53 65 6C 65 63 74 20  70 61 72 69 74 79 20 20 .Select  parity 
  4887.      0300: 28 4F 64 64 2C 20 45 76  65 6E 2C 20 4E 6F 6E 65 (Odd, Ev en, None
  4888.      0310: 29 3A 20 4E 08 24 0D 0A  53 65 6C 65 63 74 20 77 ): N.$.. Select w
  4889.      0320: 6F 72 64 20 6C 65 6E 67  74 68 20 20 20 20 20 20 ord leng th     
  4890.      0330: 28 37 20 6F 72 20 38 29  3A 20 38 08 24 0D 0A 43 (7 or 8) : 8.$..C
  4891.      0340: 6F 6D 6D 75 6E 69 63 61  74 69 6F 6E 73 20 70 6F ommunica tions po
  4892.      0350: 72 74 20 73 65 74 2E 24  00 00 00 00 00 00 00 00 rt set.$ ........
  4893.      0360: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ........ ........
  4894.      0370: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ........ ........
  4895.  
  4896.  
  4897.  
  4898.  
  4899.  
  4900.           NOTE: Well, there are some strings that are terminated with
  4901.           dollar signs. This is a heavy hint that these strings are to
  4902.           be displayed by BDOS function 9. Let's start our control
  4903.           table by filling in what we know so far...
  4904.  
  4905.  
  4906.      Z80 C>c 100 instructions           c 100 instructions      (0100h, of course, starts code)
  4907.       
  4908.      Z80 C>= 100 startup           = 100 startup           (Give it a sensible name) 
  4909.       
  4910.      Z80 C>c 245 b            c 245 b                 (Start bytes at first ASCII string)
  4911.       
  4912.      Z80 C>= 245 init_msg           = 245 init_msg          (Give them sensible names) 
  4913.       
  4914.      Z80 C>= 2c8 baud_prompt            = 2c8 baud_prompt
  4915.       
  4916.      Z80 C>= 2ef parity_prompt            = 2ef parity_prompt
  4917.       
  4918.      Z80 C>= 316 databits_prompt            = 316 databits_prompt
  4919.       
  4920.      Z80 C>= 33d wrapup_msg            = 33d wrapup_msg
  4921.       
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4929.  
  4930.  
  4931.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 88
  4932.      USING THE RESOURCE BUILTIN COMMANDS
  4933.  
  4934.  
  4935.  
  4936.           NOTE: Now let's look at the first code bytes again, and see
  4937.           if they make any more sense.
  4938.  
  4939.      Z80 C>l 100            l 100
  4940.       
  4941.       
  4942.                     STARTUP: 
  4943.      L0100:     11 45 02              LD     DE,INIT_MSG 
  4944.      L0103:     CD 40 02              CALL   L0240 
  4945.      L0106:     11 C8 02              LD     DE,BAUD_PROMPT 
  4946.      L0109:     CD 40 02              CALL   L0240 
  4947.      L010C:     CD 35 02              CALL   L0235 
  4948.      L010F:     FE 0D                 CP     CR 
  4949.      L0111:     C2 16 01              JP     NZ,L0116 
  4950.      L0114:     3E 36                 LD     A,'6' 
  4951.      L0116:     D6 30                 SUB    '0' 
  4952.  
  4953.  
  4954.  
  4955.  
  4956.           NOTE: So the routine at 0240h does something with a "$"-
  4957.           terminated string. Need we guess?
  4958.  
  4959.      Z80 C>l 240            l 240
  4960.       
  4961.      L0240:     0E 09                 LD     C,TAB 
  4962.      L0242:     C3 05 00              JP     L0005 
  4963.       
  4964.                     INIT_MSG: 
  4965.                          DB     SUB,"INIT 1.0 for Xero" 
  4966.      L0245:     1A 49 4E 49  
  4967.      L0249:     54 20 31 2E  
  4968.      L024D:     30 20 66 6F  
  4969.      L0251:     72 20 58 65  
  4970.      L0255:     72 6F             
  4971.  
  4972.  
  4973.           NOTE: First of all, note how the above disassembly changed
  4974.           from instructions to data, just as we told it to. Note also
  4975.           that this routine at 0240h is simple enough to document...
  4976.  
  4977.      Z80 C>= 5 bdos            = 5 bdos
  4978.       
  4979.      Z80 C>; 240 "\nPrint $-terminated string at (DE)"            ; 240 "\nPrint $-terminated string at (DE)"
  4980.       
  4981.      Z80 C>c 240 i            c 240 i
  4982.       
  4983.  
  4984. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  4985.  
  4986.  
  4987.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 89
  4988.      USING THE RESOURCE BUILTIN COMMANDS
  4989.  
  4990.  
  4991.      Z80 C>= 240 print_string            = 240 print_string
  4992.       
  4993.      Z80 C>l 240            l 240
  4994.       
  4995.       
  4996.                     PRINT_STRING: 
  4997.       
  4998.                     ;  
  4999.                     ; Print $-terminated string at (DE) 
  5000.                     ;  
  5001.      L0240:     0E 09                 LD     C,TAB 
  5002.      L0242:     C3 05 00              JP     BDOS 
  5003.       
  5004.                     INIT_MSG: 
  5005.                          DB     SUB,"INIT 1.0 for Xero" 
  5006.      L0245:     1A 49 4E 49  
  5007.      L0249:     54 20 31 2E  
  5008.      L024D:     30 20 66 6F  
  5009.      L0251:     72 20 58 65  
  5010.      L0255:     72 6F             
  5011.  
  5012.  
  5013.  
  5014.  
  5015.           NOTE: OK, one routine down. Referring back to our disassembly
  5016.           of the startup code, let's see what else we can figure out.
  5017.  
  5018.      Z80 C>= 106 get_baud_rate            = 106 get_baud_rate
  5019.       
  5020.      Z80 C>l startup            l startup
  5021.       
  5022.       
  5023.                     STARTUP: 
  5024.      L0100:     11 45 02              LD     DE,INIT_MSG 
  5025.      L0103:     CD 40 02              CALL   PRINT_STRING 
  5026.       
  5027.                     GET_BAUD_RATE: 
  5028.      L0106:     11 C8 02              LD     DE,BAUD_PROMPT 
  5029.      L0109:     CD 40 02              CALL   PRINT_STRING 
  5030.      L010C:     CD 35 02              CALL   L0235 
  5031.      L010F:     FE 0D                 CP     CR 
  5032.      L0111:     C2 16 01              JP     NZ,L0116 
  5033.      L0114:     3E 36                 LD     A,'6' 
  5034.      L0116:     D6 30                 SUB    '0' 
  5035.  
  5036.  
  5037.  
  5038.  
  5039.  
  5040.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5041.  
  5042.  
  5043.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 90
  5044.      USING THE RESOURCE BUILTIN COMMANDS
  5045.  
  5046.  
  5047.           NOTE: We have another routine to decipher - at 0235h.
  5048.  
  5049.      Z80 C>l 235            l 235
  5050.       
  5051.      L0235:     0E 01                 LD     C,SOH 
  5052.      L0237:     CD 05 00              CALL   BDOS 
  5053.      L023A:     FE 60                 CP     '`' 
  5054.      L023C:     D8                    RET    C 
  5055.      L023D:     D6 20                 SUB    ' ' 
  5056.      L023F:     C9                    RET 
  5057.       
  5058.                     PRINT_STRING: 
  5059.       
  5060.                     ;  
  5061.                     ; Print $-terminated string at (DE) 
  5062.                     ;  
  5063.      L0240:     0E 09                 LD     C,TAB 
  5064.      L0242:     C3 05 00              JP     BDOS 
  5065.       
  5066.                     INIT_MSG: 
  5067.                          DB     SUB,"INIT 1" 
  5068.      L0245:     1A 49 4E 49  
  5069.      L0249:     54 20 31          
  5070.  
  5071.  
  5072.  
  5073.  
  5074.           NOTE: Notice how the disassembly continued way past the end
  5075.           of our routine. That's because we didn't give an ending
  5076.           address. At any rate, the routine at 0235h appears to call
  5077.           BDOS to get a keypress, then force it to uppercase. It
  5078.           contains a slight bug, but our job right now is to re-source
  5079.           it, not fix it.
  5080.  
  5081.      Z80 C>= 235 get_bdos_keypress            = 235 get_bdos_keypress
  5082.       
  5083.      Z80 C>c 235 i            c 235 i
  5084.       
  5085.      Z80 C>; 235 "\nReturn next keypress as Uppercase char in A-reg"            ; 235 "\nReturn next keypress as Uppercase char in A-reg"
  5086.       
  5087.      Z80 C>; 237 "Use BDOS to get next keypress"            ; 237 "Use BDOS to get next keypress"
  5088.       
  5089.      Z80 C>; 23a "Is it lowercase char?"            ; 23a "Is it lowercase char?"
  5090.       
  5091.      Z80 C>; 23c "No, return it as-is"            ; 23c "No, return it as-is"
  5092.       
  5093.      Z80 C>; 23d "Yes, convert to uppercase"            ; 23d "Yes, convert to uppercase"
  5094.       
  5095.  
  5096. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5097.  
  5098.  
  5099.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 91
  5100.      USING THE RESOURCE BUILTIN COMMANDS
  5101.  
  5102.  
  5103.      Z80 C>l 235            l 235
  5104.       
  5105.       
  5106.                     GET_BDOS_KEYPRESS: 
  5107.       
  5108.                     ;  
  5109.                     ; Return next keypress as Uppercase char in A-reg
  5110.                     ;  
  5111.      L0235:    0E 01                LD    C,SOH 
  5112.      L0237:    CD 05 00             CALL  BDOS    ;Use BDOS to get next
  5113.                                                             keypress
  5114.      L023A:    FE 60                CP    '`'     ;Is it lowercase char?
  5115.      L023C:    D8                   RET   C       ;No, return it as-is
  5116.      L023D:    D6 20                SUB   ' '     ;Yes, convert to uppercase
  5117.      L023F:    C9                   RET 
  5118.       
  5119.                     PRINT_STRING: 
  5120.       
  5121.                     ;  
  5122.                     ; Print $-terminated string at (DE) 
  5123.                     ;  
  5124.      L0240:     0E 09                 LD     C,TAB 
  5125.      L0242:     C3 05 00              JP     BDOS 
  5126.       
  5127.                     INIT_MSG: 
  5128.                          DB     SUB,"INIT 1" 
  5129.      L0245:     1A 49 4E 49  
  5130.      L0249:     54 20 31          
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.           NOTE: OK, our little routines are understood and documented.
  5137.           Back to the main code, and add comments that clarify things.
  5138.  
  5139.      Z80 C>; 100 "Give intro screen"            ; 100 "Give intro screen"
  5140.       
  5141.      Z80 C>; 106 "Ask for baudrate value"            ; 106 "Ask for baudrate value"
  5142.       
  5143.      Z80 C>; 10f "RETURN only?"            ; 10f "RETURN only?"
  5144.       
  5145.      Z80 C>; 111 "No, look at keypress"            ; 111 "No, look at keypress"
  5146.       
  5147.      Z80 C>; 114 "Yes, use default value"            ; 114 "Yes, use default value"
  5148.       
  5149.      Z80 C>= 116 edit_baud_rate            = 116 edit_baud_rate
  5150.       
  5151.  
  5152. COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5153.  
  5154.  
  5155.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 92
  5156.      USING THE RESOURCE BUILTIN COMMANDS
  5157.  
  5158.  
  5159.      Z80 C>l get_baud_rate 12b            l get_baud_rate 12b
  5160.       
  5161.       
  5162.                     GET_BAUD_RATE: 
  5163.      L0106:   11 C8 02           LD     DE,BAUD_PROMPT ;Ask for baudrate
  5164.                                                                  value 
  5165.      L0109:   CD 40 02           CALL   PRINT_STRING 
  5166.      L010C:   CD 35 02           CALL   GET_BDOS_KEYPRESS 
  5167.      L010F:   FE 0D              CP     CR          ;RETURN only? 
  5168.      L0111:   C2 16 01           JP     NZ,EDIT_BAUD_RATE ;No, look at
  5169.                                                                  keypress 
  5170.      L0114:   3E 36              LD     A,'6'       ;Yes, use default
  5171.                                                                  value 
  5172.       
  5173.                     EDIT_BAUD_RATE: 
  5174.      L0116:   D6 30              SUB    '0' 
  5175.      L0118:   FE 00              CP     NUL 
  5176.      L011A:   DA 06 01           JP     C,GET_BAUD_RATE 
  5177.      L011D:   FE 0A              CP     LF 
  5178.      L011F:   D2 06 01           JP     NC,GET_BAUD_RATE 
  5179.      L0122:   32 58 03           LD     (L0358),A 
  5180.      L0125:   11 EF 02           LD     DE,PARITY_PROMPT 
  5181.      L0128:   CD 40 02           CALL   PRINT_STRING 
  5182.      L012B:   CD 35 02           CALL   GET_BDOS_KEYPRESS 
  5183.  
  5184.  
  5185.  
  5186.  
  5187.           NOTE: And so on, and so on, and so on....
  5188.  
  5189.  
  5190.  
  5191.      We'll not present all of the output here. Although the session actually
  5192.      lasted less than half an hour, the output is huge. Instead, let us skip
  5193.      ahead to the point where we've finished defining our control table.
  5194.  
  5195.  
  5196.  
  5197.  
  5198.           NOTE: At this point - having done all of this work to con-
  5199.           struct documentation of the object code - we should save the                                                              ________
  5200.           control table to disk!          ______________________
  5201.  
  5202.      Z80 C>control write 820init.ctl           control write 820init.ctl
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5209.  
  5210.  
  5211.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 93
  5212.      USING THE RESOURCE BUILTIN COMMANDS
  5213.  
  5214.  
  5215.           NOTE: Having done that, we must prepare things for the actual
  5216.           generation of the .ASM file. Specifically, we should exclude
  5217.           addresses, opcodes, and flags from disassembly source lines.
  5218.       
  5219.      Z80 C>list include            list include
  5220.  
  5221.  
  5222.  
  5223.           NOTE: Now we can disassemble the object code to disk as source
  5224.           code. First we write the prologue, and then the program
  5225.           itself:
  5226.       
  5227.      Z80 C>list prologue 100 360 >820init.asm            list prologue 100 360 >820init.asm
  5228.       
  5229.      Z80 C>list 100 360 >>820init.asm            list 100 360 >>820init.asm
  5230.  
  5231.  
  5232.           NOTE: Having done that, let's test things by running the .ASM
  5233.           file through M80.COM...
  5234.       
  5235.      Z80 C>m80 820init.rel,820init.prn=820init.asm            m80 820init.rel,820init.prn=820init.asm
  5236.      %No END statement 
  5237.      %No END statement 
  5238.       
  5239.      No Fatal error(s) 
  5240.       
  5241.  
  5242.  
  5243.  
  5244.  
  5245.      That's it. We're done. The assembler version of 820INIT.COM has been
  5246.      written and verified.
  5247.  
  5248.      For your enjoyment, we have included with Z80MU the various 820INIT
  5249.      files that were used or created by the above session. Feel free to
  5250.      examine all of these files, especially 820INIT.ASM and 820INIT.PRN. They
  5251.      give you a good idea of the quality of source code that can be recreated
  5252.      from a given object program.
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5265.  
  5266.  
  5267.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 94
  5268.      Appendix A: Layout of CP/M Segment
  5269.  
  5270.  
  5271.       
  5272.      Appendix A: Layout of Simulated CP/M Segment (as set by Cold Boot)      __________________________________________________________________
  5273.       
  5274.      0000:     JMP  0FF03H         ;to our fake BIOS 
  5275.      0003:     DB   ?              ;IOBYTE 
  5276.      0004:     DB   ?              ;Login Byte (drive, User Number) 
  5277.      0005:     JMP  0FEFEH         ;to our fake BDOS 
  5278.      005C:     DB   ?              ;Default FCB 
  5279.      0080:     DB   ?              ;Default DMA and Command Tail 
  5280.      0100:     DB   ?              ;start of TPA 
  5281.      FEFD:     DB   ?              ;last byte of TPA 
  5282.      FEFE:     HALT                ;our BDOS hook 
  5283.      FEFF:     RET                 ;return from BDOS 
  5284.      FF00:     JMP  0FF80H         ;BIOS COLD BOOT vector 
  5285.      FF03:     JMP  0FF82H         ;BIOS WARM BOOT vector 
  5286.      FF06:     JMP  0FF84H         ;BIOS console status 
  5287.      FF09:     JMP  0FF86H         ;BIOS console input 
  5288.      FF0C:     JMP  0FF88H         ;BIOS console output 
  5289.      FF0F:     JMP  0FF8AH         ;BIOS list output 
  5290.      FF12:     JMP  0FF8CH         ;BIOS punch output 
  5291.      FF15:     JMP  0FF8EH         ;BIOS reader input 
  5292.      FF18:     JMP  0FF90H         ;BIOS home disk 
  5293.      FF1B:     JMP  0FF92H         ;BIOS select disk 
  5294.      FF1E:     JMP  0FF94H         ;BIOS set track 
  5295.      FF21:     JMP  0FF96H         ;BIOS set sector 
  5296.      FF24:     JMP  0FF98H         ;BIOS set DMA address 
  5297.      FF27:     JMP  0FF9AH         ;BIOS read sector 
  5298.      FF2A:     JMP  0FF9CH         ;BIOS write sector 
  5299.      FF2D:     JMP  0FF9EH         ;BIOS list status 
  5300.      FF30:     JMP  0FFA0H         ;BIOS (unimplemented) 
  5301.      FF33:     JMP  0FFA2H         ;BIOS (unimplemented) 
  5302.      FF36:     JMP  0FFA4H         ;BIOS (unimplemented) 
  5303.      FF39:     JMP  0FFA6H         ;BIOS (unimplemented) 
  5304.      FF3C:     JMP  0FFA8H         ;BIOS (unimplemented) 
  5305.      FF3F:     JMP  0FFAAH         ;BIOS (unimplemented) 
  5306.      FF42:     JMP  0FFACH         ;BIOS (unimplemented) 
  5307.      FF45:     JMP  0FFAEH         ;BIOS (unimplemented) 
  5308.      FF48:     JMP  0FFB0H         ;BIOS (unimplemented) 
  5309.      FF4B:     JMP  0FFB2H         ;BIOS (unimplemented) 
  5310.      FF4E:     JMP  0FFB4H         ;BIOS (unimplemented) 
  5311.      FF51:     JMP  0FFB6H         ;BIOS (unimplemented) 
  5312.      FF54:     JMP  0FFB8H         ;BIOS (unimplemented) 
  5313.      FF57:     JMP  0FFBAH         ;BIOS (unimplemented) 
  5314.      FF5A:     JMP  0FFBCH         ;BIOS (unimplemented) 
  5315.      FF5D:     JMP  0FFBEH         ;BIOS (unimplemented) 
  5316.      FF60:     JMP  0FFC0H         ;BIOS (unimplemented) 
  5317.      FF63:     JMP  0FFC2H         ;BIOS (unimplemented) 
  5318.      FF66:     JMP  0FFC4H         ;BIOS (unimplemented) 
  5319.  
  5320.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5321.  
  5322.  
  5323.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 95
  5324.      Appendix A: Layout of CP/M Segment
  5325.  
  5326.  
  5327.      FF69:     JMP  0FFC6H         ;BIOS (unimplemented) 
  5328.      FF6C:     JMP  0FFC8H         ;BIOS (unimplemented) 
  5329.      FF6F:     JMP  0FFCAH         ;BIOS (unimplemented) 
  5330.      FF72:     JMP  0FFCCH         ;BIOS (unimplemented) 
  5331.      FF75:     JMP  0FFCEH         ;BIOS (unimplemented) 
  5332.      FF78:     JMP  0FFD0H         ;BIOS (unimplemented) 
  5333.      FF7B:     JMP  0FFD2H         ;BIOS (unimplemented) 
  5334.       
  5335.      FF80:     HALT                ;BIOS COLD BOOT hook 
  5336.      FF81:     RET 
  5337.      FF82:     HALT                ;BIOS WARM BOOT hook 
  5338.      FF83:     RET 
  5339.      FF84:     HALT                ;BIOS console status 
  5340.      FF85:     RET 
  5341.      FF86:     HALT                ;BIOS console input 
  5342.      FF87:     RET 
  5343.      FF88:     HALT                ;BIOS console output 
  5344.      FF89:     RET 
  5345.      FF8A:     HALT                ;BIOS list output 
  5346.      FF8B:     RET 
  5347.      FF8C:     HALT                ;BIOS punch output 
  5348.      FF8D:     RET 
  5349.      FF8E:     HALT                ;BIOS reader input 
  5350.      FF8F:     RET 
  5351.      FF90:     HALT                ;BIOS home disk 
  5352.      FF91:     RET 
  5353.      FF92:     HALT                ;BIOS select disk 
  5354.      FF93:     RET 
  5355.      FF94:     HALT                ;BIOS set track 
  5356.      FF95:     RET 
  5357.      FF96:     HALT                ;BIOS set sector 
  5358.      FF97:     RET 
  5359.      FF98:     HALT                ;BIOS set DMA address 
  5360.      FF99:     RET 
  5361.      FF9A:     HALT                ;BIOS read sector 
  5362.      FF9B:     RET 
  5363.      FF9C:     HALT                ;BIOS write sector 
  5364.      FF9D:     RET 
  5365.      FF9E:     HALT                ;BIOS list status 
  5366.      FF9F:     RET 
  5367.      FFA0:     HALT                ;BIOS (unimplemented) 
  5368.      FFA1:     RET 
  5369.      FFA2:     HALT                ;BIOS (unimplemented) 
  5370.      FFA3:     RET 
  5371.      FFA4:     HALT                ;BIOS (unimplemented) 
  5372.      FFA5:     RET 
  5373.      FFA6:     HALT                ;BIOS (unimplemented) 
  5374.      FFA7:     RET 
  5375.  
  5376.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5377.  
  5378.  
  5379.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 96
  5380.      Appendix A: Layout of CP/M Segment
  5381.  
  5382.  
  5383.      FFA8:     HALT                ;BIOS (unimplemented) 
  5384.      FFA9:     RET 
  5385.      FFAA:     HALT                ;BIOS (unimplemented) 
  5386.      FFAB:     RET 
  5387.      FFAC:     HALT                ;BIOS (unimplemented) 
  5388.      FFAD:     RET 
  5389.      FFAE:     HALT                ;BIOS (unimplemented) 
  5390.      FFAF:     RET 
  5391.      FFB0:     HALT                ;BIOS (unimplemented) 
  5392.      FFB1:     RET 
  5393.      FFB2:     HALT                ;BIOS (unimplemented) 
  5394.      FFB3:     RET 
  5395.      FFB4:     HALT                ;BIOS (unimplemented) 
  5396.      FFB5:     RET 
  5397.      FFB6:     HALT                ;BIOS (unimplemented) 
  5398.      FFB7:     RET 
  5399.      FFB8:     HALT                ;BIOS (unimplemented) 
  5400.      FFB9:     RET 
  5401.      FFBA:     HALT                ;BIOS (unimplemented) 
  5402.      FFBB:     RET 
  5403.      FFBC:     HALT                ;BIOS (unimplemented) 
  5404.      FFBD:     RET 
  5405.      FFBE:     HALT                ;BIOS (unimplemented) 
  5406.      FFBF:     RET 
  5407.      FFC0:     HALT                ;BIOS (unimplemented) 
  5408.      FFC1:     RET 
  5409.      FFC2:     HALT                ;BIOS (unimplemented) 
  5410.      FFC3:     RET 
  5411.      FFC4:     HALT                ;BIOS (unimplemented) 
  5412.      FFC5:     RET 
  5413.      FFC6:     HALT                ;BIOS (unimplemented) 
  5414.      FFC7:     RET 
  5415.      FFC8:     HALT                ;BIOS (unimplemented) 
  5416.      FFC9:     RET 
  5417.      FFCA:     HALT                ;BIOS (unimplemented) 
  5418.      FFCB:     RET 
  5419.      FFCC:     HALT                ;BIOS (unimplemented) 
  5420.      FFCD:     RET 
  5421.      FFCE:     HALT                ;BIOS (unimplemented) 
  5422.      FFCF:     RET 
  5423.      FFD0:     HALT                ;BIOS (unimplemented) 
  5424.      FFD1:     RET 
  5425.      FFD2:     HALT                ;BIOS (unimplemented) 
  5426.      FFD3:     RET 
  5427.      FFD4:                         ;rest reserved for scratch use
  5428.  
  5429.  
  5430.  
  5431.  
  5432.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5433.  
  5434.  
  5435.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 97
  5436.      Appendix B: Bugs and Future Plans
  5437.  
  5438.  
  5439.  
  5440.       
  5441.                         Appendix B: Bugs and Future Plans                        _________________________________
  5442.  
  5443.       
  5444.      This section describes known bugs and otherwise strange Emulator
  5445.      activity. Please help us to improve the product by sending us your own
  5446.      bug reports, with as much detail as possible (including programs
  5447.      which demonstrate the bug). 
  5448.       
  5449.      These bugs will be fixed as time allows and user interest demands.
  5450.  
  5451.       
  5452.           Issue: The disassembly (list) command can become quite pokey.                                  list          ______
  5453.                As the control table grows, disassembly speed decreases.
  5454.                When disassembling the Model 100's ROM, for instance, the
  5455.                poor disassembler is faced with a control table that is
  5456.                something bigger than 42K in size. It may have to
  5457.                search most of the table for each memory reference. This
  5458.                yields a disassembly speed of a line or two a second.
  5459.                Boo! The control table search routines should be changed
  5460.                from a sequential to an indexed method.
  5461.  
  5462.           Author's Response: Agreed. Will rewrite these for next          __________________
  5463.                release. 
  5464.       
  5465.  
  5466.           Issue: Some commands (notably those that accept a range of          ______
  5467.                CP/M addresses) get confused if they are asked to wrap
  5468.                around the high end of the 64K CP/M segment.
  5469.  
  5470.           Author's Response: Have applied fixes for most glaring          __________________
  5471.                problems. Would appreciate specifics (i.e. - what
  5472.                commands fail and how) to help track down the rest. 
  5473.       
  5474.  
  5475.           Issue: Internal I/O redirection (effected by the Emulator, not          ______
  5476.                PCDOS) should be available for any Emulator command, not
  5477.                just the list command.                         list
  5478.       
  5479.           Author's Response: Agreed. Will look into it.          __________________
  5480.  
  5481.  
  5482.  
  5483.  
  5484.  
  5485.  
  5486.  
  5487.  
  5488.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5489.  
  5490.  
  5491.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 98
  5492.      Appendix B: Bugs and Future Plans
  5493.  
  5494.  
  5495.  
  5496.           Issue: The patch command ought to allow multiple entries per                     patch          ______
  5497.                line, and ought to accept arguments on the patch command                                                          patch
  5498.                line without dropping into interactive patch mode. 
  5499.       
  5500.           Author's Response: Have provided left-handed solution by          __________________
  5501.                allowing a patch string on same line as patch command.                                                       patch
  5502.                True fix (with multiple byte values as independent args
  5503.                on command line) will take a while to implement.
  5504.  
  5505.  
  5506.           Issue: The Emulator lacks a mini assembler. It needs one.           ______
  5507.       
  5508.           Author's Response: Agreed. We just don't have the memory left          __________________
  5509.                in the 64K Lattice code segment to do it right. Maybe
  5510.                after some major rework...
  5511.  
  5512.  
  5513.           Issue: The Emulator's main program ought to be rewritten in          ______
  5514.                Microsoft C version 3.0. This will speed it up consider-
  5515.                ably, and will make it a lot smaller. 
  5516.       
  5517.           Author's Response: Agreed. The major effort is in reworking          __________________
  5518.                the assembler subroutines. There are a lot of places                                                      lot
  5519.                where Lattice's calling convention and register usage is
  5520.                assumed.
  5521.  
  5522.  
  5523.           Issue: It would be nice to somehow state to the Emulator that          ______
  5524.                what is in CP/M memory is actually an 8080 or 8085
  5525.                program. This would allow the 8085's RIM and SIM instruc-
  5526.                tions, for example, to be properly disassembled (instead
  5527.                of being misinterpreted as Z80 relative jumps). 
  5528.       
  5529.           Author's Response: Agreed. The biggest obstacle to doing this          __________________
  5530.                is the same old bugaboo - no memory left in 64K code
  5531.                segment. Will put this off until we free up a couple of
  5532.                K in the code segment.
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5545.  
  5546.  
  5547.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 99
  5548.      Appendix B: Bugs and Future Plans
  5549.  
  5550.  
  5551.  
  5552.  
  5553.           Issue: The loading of Z80 .COM files to be executed - in fact,          ______
  5554.                any file load that is done directly or indirectly by the
  5555.                "read" command - is just too slow.                read
  5556.  
  5557.           Author's Response: Agreed! This should be redone to bypass          __________________
  5558.                Lattice C's slow I/O routines. This problem may go away
  5559.                if and when the Emulator is rewritten in Microsoft 'C'
  5560.                version 3.0.
  5561.       
  5562.  
  5563.           Issue: The disassembler can get confused when a multi-byte          ______
  5564.                opcode crosses a control break. In general, it reverts
  5565.                to DB pseudo ops up to the control break when this
  5566.                happens. Also, it's not too smart when disassembling
  5567.                code with addresses up around the 64K segment boundary.
  5568.       
  5569.           Author's Response: I have tried to locate and eliminate          __________________
  5570.                peephole problems. The nature of the problem, however,
  5571.                goes to the very core of the disassembler as designed.
  5572.                This is not quickly (or cheaply) fixable.
  5573.  
  5574.  
  5575.           Issue: There are too many CP/M applications which abort          ______
  5576.                because they use BDOS functions 27/1Bh and 31/1Fh. These
  5577.                BDOS functions should be supported, even if they mean
  5578.                little on a PCDOS system.
  5579.  
  5580.           Author's Response: Agreed. The only reason that they haven't          __________________
  5581.                been emulated is that I have yet to find a sensible
  5582.                writeup of just exactly what the various data formats
  5583.                are. DRI's writeup stinks. If someone can provide a
  5584.                clear explanation of just what they truly mean, then
  5585.                I'll emulate them.
  5586.  
  5587.  
  5588.           Issue: There are more than 600 distinct instructions in the          ______
  5589.                Z80. Have they all been validated as to the accuracy of
  5590.                the emulation?
  5591.  
  5592.           Author's Response: So far, all we've done is run Z80 stuff and          __________________
  5593.                try to guess that it has run fine. All opcodes have been
  5594.                desk-checked. Not all opcodes have been tested. Most, in
  5595.                fact, have not even been executed. Would somebody please                                                                 please
  5596.                create a definitive test program? The diagnostics that
  5597.                we've tried (like Supersoft's) have proven to be inac-
  5598.                curate.
  5599.  
  5600.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5601.  
  5602.  
  5603.      "Z80MU" Z80 and CP/M 2.2 Emulator User's Guide            Page 100
  5604.      Appendix B: Bugs and Future Plans
  5605.  
  5606.  
  5607.  
  5608.  
  5609.           Issue: There should be an option to allow pagination of          ______
  5610.                disassembled object code.
  5611.  
  5612.           Author's Response: Agreed. Will look into another list include                                                            list include          __________________
  5613.                option to specify pagination.
  5614.  
  5615.  
  5616.           Issue: Expressions are currently limited to "+" and "-"          ______
  5617.                operators. They should allow "*" and "/" also, and maybe
  5618.                even AND, OR, XOR, shifts, etc.
  5619.  
  5620.           Author's Response: I disagree. The amount of work involved          __________________
  5621.                isn't justified by the benefit.
  5622.  
  5623.  
  5624.           Issue: The Z80 IN and OUT instructions should have access to          ______
  5625.                real 8088 I/O ports on the IBM PC.
  5626.  
  5627.           Author's Response: Over my dead body.          __________________
  5628.  
  5629.  
  5630.  
  5631.  
  5632.  
  5633.  
  5634.  
  5635.  
  5636.  
  5637.  
  5638.  
  5639.  
  5640.  
  5641.  
  5642.  
  5643.  
  5644.  
  5645.  
  5646.  
  5647.  
  5648.  
  5649.  
  5650.  
  5651.  
  5652.  
  5653.  
  5654.  
  5655.  
  5656.      COMPUTERWISE CONSULTING SERVICES, P.O. BOX 813, MCLEAN, VA 22101
  5657.