home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / emulatrs / ame86.arc / AME86.DOC next >
Text File  |  1985-07-30  |  39KB  |  1,097 lines
  1.  
  2.         AME86 - (pre)release notes
  3.         ==========================
  4.  
  5.             Version 0.7-x
  6.  
  7.  
  8.     Copyright (c) Jean-Marc Lugrin
  9.               Digital Equipment Corp.  1983, 1984
  10.  
  11.     Look at the end for distribution policy.
  12.  
  13.  
  14.  
  15.    Change for version 0.3
  16.    ----------------------
  17.  
  18.     Goal:  Bug correction,  clean-up of register handling.
  19.  
  20. The following changes were implemented:
  21.  
  22.     1) Ensure interupt enabled at emulator boot and emulated
  23.         program start
  24.  
  25.     2) Ensure direction flag cleared at emulator boot, emulated
  26.        program start, and when in MSDOS mode (that is in emulator's
  27.        code).
  28.  
  29.    The change have corrected the following bugs:
  30.  
  31.     System crash in some COMPAS programs.
  32.  
  33.     Some I/O errors in COMPAS programs.
  34.  
  35.    Changes for version 0.4
  36.    -----------------------
  37.  
  38.  
  39.     Generally increase robustness and better emulation of file
  40.     directives.  Better documentation.
  41.  
  42.   0.4-1
  43.  
  44.     1) Use two stacks, switch stack and check for stack overflow.
  45.        This corrected many random crashes.
  46.  
  47.     2) setup DRIVE code im base page like CCPM
  48.  
  49.   0.4-2
  50.  
  51.     1) Convert "?" in extent number (from MSDOS to CPM) in open and
  52.        search to 0.
  53.  
  54.     2) Allow non-zero extent in OPEN/SEARCH - position block number
  55.        accordingly.
  56.        This allowed RED to work with large files.
  57.  
  58.   0.4-3
  59.  
  60.     1) Reject "STAY RESIDENT" Abort Code of SYSTEM RESET.
  61.  
  62.     2) Better handling of S1, S2, CR and RC fields of FCB.  See
  63.        notes on FCB handling.
  64.  
  65.   0.4-4
  66.  
  67.     1) Correct bug in initialisation of non-initialised memory
  68.        (if I can say).
  69.  
  70.        Correct a bug causing some data in DS segment to be zeroed
  71.        at end of load (in MP.CMD).
  72.  
  73.     --- Switch editing to MSDOS under AME86 + RED
  74.  
  75.   0.4-5
  76.  
  77.     1) preparation of implementation of some memory allocation functions
  78.  
  79.     2) Do not attempt to load a section defined in CMD file,
  80.        with the size MIN/MAX/LENGTH of 0.  Do not attempt to load
  81.        section of LENGTH 0 (but extension still done!).
  82.  
  83.        This corrected a bug with the load of some program not
  84.        generated by GENCMD,  like MAINT (a PASCAL program).
  85.  
  86.     3) Do not clear extended area of section.
  87.  
  88.     4) Better initialisation of base page, more exactly like CPM-86
  89.        load function.
  90.  
  91.        This corrected a bug of RED hanging if there was no file
  92.        specification in command line.
  93.  
  94.  
  95.    Change for version 0.5
  96.    ----------------------
  97.  
  98.     Goal:  Implement memory management directives, for emulation
  99.            of Multi-Plan.
  100.            Allow full use of CPM-86 development tools.
  101.            Implement console i/o subset of BIOS functions.
  102.  
  103.  
  104.   0.5-0    Implement some memory allocation functions for MultiPlan:
  105.     essentially allocation at end and free all memory.
  106.     Use this functions internally for program load.
  107.  
  108.     MultiPlan, ASM86 and GENCMD are all working with this version.
  109.  
  110.  
  111.   0.5-1 Implement subset bios: console i/o, set dma,  dummy iobyte.
  112.     Implement Set Random Record function.
  113.  
  114.     PIP is working with this version.
  115.  
  116.   0.5-2 Correct error in OPEN and SEARCH NEXT, which cleared some
  117.     memory at random.
  118.  
  119.     Suppressed some "INTERUPT-OFF".
  120.  
  121.   0.5-3 Implementation of FREE at end of region and FREE of region,
  122.     stack like allocation only.
  123.  
  124.     Allow MWC-86 to work.
  125.  
  126.   0.5-4 Cleanup of command line processing (bug introduced with
  127.         version 0.4-5).
  128.  
  129.     Allow CGROMCRC to work again.
  130.  
  131.   0.5-5 Correct status return of close.
  132.     Add option handling and alternate drive on open.
  133.     Add better handling of logged-in drive functions.
  134.  
  135.     This allow to have programs like RED, COMPAS, MP residing
  136.     in another drive and being usable without changing current
  137.     drive.  This go beyond normal CP/M-86 functionallity and 
  138.     MSDOS functionallity,  but was found very practical.
  139.  
  140.     BUG: - RED do not rename small files anymore.
  141.            A LISP processor do not load files whith partial record.
  142.  
  143.   0.5-6 Correct previous bugs (RED rename and partial record)
  144.     Correct IOBYTE emulation (limit SET IOBYTE)
  145.     Implement LOAD PROGRAM function.
  146.  
  147.     RENAME function working again (RED).
  148.     FABS-86 works.
  149.     LISP works.
  150.  
  151.   0.5-7 Finish and correct memory management directives.
  152.     More "real" emulation of disk DPB and ALV.
  153.     Better emulation of logged in disk.
  154.     Preparation for program load function
  155.     Translate commande in upper case.
  156.     Reset original default drive at exit
  157.  
  158.     Allow RED/ SELECT/ STAT to display good aproximation
  159.     of disk free space for floppy, winchester and Mdrive.
  160.     Winchester and Mdrive are normally logged-in. A: is NOT
  161.     normally loged in.
  162.  
  163.     The translation of the command line to upper case avoid
  164.     various errors.
  165.  
  166.  
  167.  
  168.    Change for version 0.6
  169.    ----------------------
  170.  
  171.     GOAL: Implement remaining possible system calls
  172.     (program load,  write with zero-fill).
  173.     Systematic test of major applications,  systematic
  174.     debugging.
  175.  
  176.   0.6-1    Implement chain to program call (can chain to CMD file only),
  177.     Implement exit status (0 on success, 1 on error)
  178.         Correct bug reseting the wrong drive at exit
  179.     Implement write with zero fill
  180.     Implement option /I (for illegal BDOS and special SEARCH)
  181.     Implement Fake Allocation
  182.     Hook for Extended console BIOS call (not yet usable)
  183.     Correct bug in initialisation of load FCB
  184.     Better emulation of returned status (0 in AX/BX for most functions)
  185.     Better IOBYTE (values 15h HEX)
  186.     Error code 6 returned for file too large in random access
  187.  
  188.     Printer interface vector is destroyed.
  189.  
  190.  
  191.   0.6-2 Implement high speed video using BIOS (this is different from
  192.     extended console BIOS).
  193.     Extended console BIOS now works.
  194.     Get boot drive (extended BIOS) return load drive
  195.     Corrected a bug of 0.6-1 corupting the stack. 
  196.     Better emulation of READ CONSOLE BUFFER.
  197.     Correct bug in LOAD PROGRAM (initial and request).
  198.     Allow to load program with EOF in last group.
  199.  
  200.     CP/M-86/80 HELP works (but require option /S)
  201.     Background printing work
  202.     INFOCOM games can be loaded (SORCERER works).
  203.     WordStar (16 bits versions) and FORTH load correctly.
  204.  
  205.     BUG: Do not work on Rainbow-100/A  (only on B/+), probably
  206.     due to different clock handling routine.
  207.  
  208.  
  209.   0.6-3    Correct a bug when saving/ retoring clock interupts,
  210.     which caused INTERUPT OFF on 100A.
  211.     Better emulation/ documentation of clock routine.
  212.     Correct boot drive # which required option /S on HELP.
  213.     Implement ^C trapping: ^C abort the program restoring
  214.      MSDOS environment (and with an error message).
  215.     Implement option /C to select ^C handling mode.
  216.  
  217.   Changes for version 0.7
  218.   ------------------------
  219.  
  220.     Goal: Implement some changes requested by users (use path names,
  221.               command mode).
  222.           More robust interupt control for work with programs
  223.           modifying CPM interupts.
  224.  
  225.   0.7-1 Introduce option /F,  correct a bug in option /S implying /I.
  226.     Allow /S and /F to work correctly with CHAIN (/F being same as /S).
  227.         Work (almost) correctly with SWITCHAR.
  228.     Never require \dev for emulated programs.
  229.     Allow PATH name to load program.
  230.     Use PATH name in /S and /F options.
  231.     REJECT /F/S if PATHNAME, because of bug.
  232.  
  233.  
  234.  
  235.    Functionality
  236.    -------------
  237.  
  238. This emulator allow you to run CPM-86 programs (like RED) under MSDOS.
  239. The goal is to ease transfer of already developed applications,  and
  240. to allow co-existance of CPM-86 and MSDOS applications.  The goal is to
  241. emulate CPM-86 as commonly used on the Rainbow-100 computer.
  242.  
  243. Program which depend too heavily on internal structure of
  244. CPM-86 are not likely to work correctly.  This include
  245. communication programs (Polygon), debuggers (DDT86), device maintenance 
  246. programs (STAT, MAINT, FORMAT).  The same class of program that is easy
  247. to transfer to CCPM should run on AME86. For other limitations see below.
  248.  
  249. It is possible to develop CPM-86 program (using ASM86,
  250. GENCMD or MWC or other CPM-86 compilers) under MSDOS+AME86.
  251.  
  252. NOTE: A CPM-86 license is necessary to use Digital Research products
  253.       with AME86.
  254.  
  255.    Installation
  256.    ------------
  257.  
  258. Just copy AME86.EXE on a convenient directory of your disquette.
  259. Most sources are in AME86.ASM (a very big file),  EXCON.ASM (for
  260. extended console) and AMEND.ASM (just to mark the end of the code).
  261. They have to be linked in the order AME86+EXCON+AMEND, producing
  262. an EXE file.
  263.  
  264.  
  265.    Usage
  266.    -----
  267.  
  268. You have to copy the CPM-86 programs you want to use under
  269. MSDOS, do not forget the overlays, help files and error message files
  270. which may be needed.  To copy the file you can use RDCPM (provided with
  271. MSDOS V2.05) or other file exchange program (like the excellent
  272. DOSFLX running under CPM-86),  or transfer files in image
  273. mode using two computers and Polygon software.
  274.  
  275. IMPORTANT: CMD files are binary files,  depending on the program you
  276.        use for the transfer, you must specify an option, to avoid
  277.        cutting the file at the first ^Z.  For exemple, file transmitted
  278.        by Polygon XFR must include the IMAGE option,  KERMIT must
  279.        be in BINARY mode.
  280.  
  281.  
  282.  
  283. To run a CPM-86 program use the command:
  284.  
  285.     AME86 [drive:][path]program-name/options parameters....
  286.  
  287. AME86 will be searched using PATH (see MSDOS documentation) - but actually
  288. the CPM-86 program must reside under the current directory or in a directory
  289. specified on the command line. It is possible to specify a drive name too.
  290. Options must directly follow the name of the
  291. program to be loaded (NO space allowed). If SWITCHAR
  292. is "-", the replace "-" for "/" in the examples.
  293. The following options are implemented:
  294.  
  295.  
  296.     /C - ^C do NOT abort your program.  Under MSDOS ^C may abort
  297.         your program at any console i/o operation (except
  298.         some direct console i/o), or even at any system request
  299.         (disk i/o or other request) if the option BREAK=ON has
  300.         been used in CONFIG.SYS.  This feature is very useful
  301.         to stop erroneous program,  but may be conflicting with
  302.         the way ^C is handled by the emulated program.  If you
  303.         do NOT want ^C trapping by MSDOS during execution of
  304.         the program, use option /C.  This should be used
  305.         with program known to work well (like RED).
  306.  
  307.         NOTE: If a program had any file opened for writing when
  308.             ^C is issued, the disks may be corrupted.  You
  309.             should run CHKDSK to check disk structure.
  310.  
  311.      /S and /F:
  312.         Both option are for similar use, they are mutually exclusive.
  313.         Under CP/M-86 (and MSDOS) a program cannot now from where
  314.         it was loaded (which drive).  Under AME86 it cannot even
  315.         known from which directory.  This is a problem with program
  316.         using HELP files or OVERLAYS (like RED, TURBO, WS, etc),
  317.         as they do not known where to look at them.  Normally
  318.         they look at the default drive established at load,
  319.         or at the boot drive.
  320.         AME86 return the drive used to load the program as the
  321.         boot drive.  Still the program may look in the wrong drive
  322.         or the wrong directory.
  323.         To allow program a way to find their overlay or help file,
  324.         AME86 can give them a second chance on OPEN or CHAIN (but
  325.         NOT on MAKE, SEARCH_FIRST or SEARCH_NEXT).  The second chance
  326.         is given ONLY if the file is looked in the drive which was
  327.         the CURRENT DRIVE when the program was loaded or if a PATH
  328.         was specified on the command line,  and if option /S or /F
  329.         was specified too.
  330.         AME86 uses an heuristic to avoid re-trying twice to open
  331.         using the same file name twice.  Inpact on speed is minimal
  332.         for option /S with floppy drive,  with option /F with MDRIVE.
  333.         Using option /S or F together with PATH NAME may slow
  334.         down file opening significantly on floppy disks.
  335.  
  336.     NOTE: On 0.7-1 a bug preclude the use of /S and /F with path name.
  337.  
  338.  
  339.     /S - Search: Allow for a second chance AFTER the file was looked
  340.         in the current directory of the specified drive.
  341.  
  342.         Possible problem: if the user open a data file which do not
  343.         exist on the specified drive,  and one exist on the load drive,
  344.         the one on the load drive will be used without warning.
  345.  
  346.  
  347.     /F - First Search:  FIRST try to open on the load device and
  348.         pathname if the drive qualify (is either the default drive
  349.         at load or the effective load drive and a pathname is
  350.         specified).
  351.  
  352.         Possible problem: if the user try to open a data file
  353.         on a specific disk,  and a file with the same name exists
  354.         on the load drive, the file on the load drive will be
  355.         used without warning.
  356.  
  357.  
  358.     /I - Ignore: This option give a better (but less secure)
  359.          emulation of CPM-86.  The following functionality
  360.         is modified:
  361.  
  362.         1) If the program call CPM-86 for an illegal request,
  363.            AME86 returns with AX=BX=0.
  364.  
  365.         2) If the program ask for a SEARCH in special mode,
  366.            AME86 will attempt to emulate it (for STAT and
  367.            MAINT). This do not run very well now...
  368.  
  369.         The option should be used carefully.
  370.  
  371.  
  372. To simplify usage, you can create a BAT file containing the
  373. command:
  374.  
  375.     AME86 program/option %1 %2 %3 %4 %5 %6 %7 %8 %9
  376.  
  377. The program may include a drive and/or path name.
  378.  
  379. CPM file name (in parameters or in prompts) do not support directory
  380. path.
  381.  
  382. Exemple of command to execute DBASE:
  383.  
  384.     A>AME86 B:DBASE/S 
  385.  
  386. Exemple of RED.BAT file:
  387.  
  388.     B>A:AME86 A:RED/S/C %1
  389.  
  390. Exemple of a TURBO from a winchester disk
  391.  
  392.     E>E:AME86 E:\usr\bin\turbo/S
  393.  
  394.  
  395.  
  396. It is not possible to setup a BAT file if an EXE of the same name is used
  397. by the application (like MultiPlan).
  398.  
  399.  
  400. If you put AME86 and the commonly used batch file in MDRIVE, you will
  401. considerably increase load time performances.  In this case use option
  402. /F instead of /S:
  403.     E:AME86 E:RED/F/C %1
  404.  
  405.  
  406. Do not terminate single line BAT file with CR (carriage return),  but 
  407. directly with ^Z.  This may be done with RED if you delete the "<" which
  408. indicate the CR.  Terminating the line with ^Z (end-of-file) tell MSDOS
  409. not to read next line when program exit, saving 1/2 seconds on a floppy
  410. disk system...
  411.  
  412. AME86 exit with a status of 0 in case of success or 1 in case of error.
  413. (including ^C abort).
  414.  
  415.  
  416. If you use BREAK=ON in your CONFIG.SYS,  MSDOS will check for ^C at
  417. any system call.  Your program has no possibility to intercept this 
  418. Control/C:  it is aborted.  If you use BREAK=ON,  and your program 
  419. normally handle ^C itself,  you have to be carrefull to type ^C
  420. ONLY when your program ask for some input.  These is not always
  421. convenient,  you may desire to supress BREAK=ON or use
  422. option /C.
  423.  
  424.   Limitations
  425.   -----------
  426.  
  427.    Some limitations are just temporary,  other are due to
  428. the inherent differences between MSDOS and CPM.  Any idea
  429. how to implement these limitations are welcomes.
  430.  
  431.     *.COM (CPM-80) files will NOT run, as MSDOS overlap
  432.        the space used by Z80 to run programs.  Implementation
  433.        ideas welcomes.
  434.  
  435.     All Rainbow specific functions ARE implemented (direct
  436.     screen addressing, Firmware call) in a way compatible
  437.     with CPM-86.
  438.  
  439.     The following functions are fake'd (i.e. dummy) or have
  440.     some restrictions:
  441.  
  442.         set i/o byte (1)
  443.         get i/o byte (1)
  444.         return login vector (4)
  445.         get allocation vector (2)
  446.         set file attribute
  447.         set read-only vector
  448.         get address disk parameters (2)
  449.         get/set user code (3)
  450.         reset drive (4)
  451.         chain to program (5)
  452.  
  453.     1)   - May be fully implemented at a later stage
  454.           Actually SET I/O BYTE is only accepted if new BYTE is same
  455.           as old one.  GET I/O BYTE return the default I/O BYTE (15).
  456.     2)  - A dummy DPB is returned.  It is based on the floppy DPB
  457.           but size is changed to reflect current drive (winchester
  458.           and MDRIVE).  It works reasonably well if the DPB is used
  459.           to compute free space (like in STAT, RED,  SELECT).
  460.     3) -  User code may be equivalenced to MSDOS directory
  461.           at a later stage (using MSDOS SET command and environment
  462.           informations).
  463.     4) -  At start login vector contains only load drive.  Each file
  464.           operation (and select drive) add the corresponding drive.
  465.           Reset disk and reset drive both call the MSDOS disk reset
  466.           function.  The drive from which AME86 was loaded is
  467.           NOT automatically logged in.
  468.     5)    Chain to program try to load a CPM-86 program!  It does
  469.           not give the command to the MSDOS command processor.
  470.           Internal commands (DIR, USER, ...) cannot be processed.
  471.           SUBMIT is not implemented.  The user could write a
  472.           CMD program with equivallent functionality.
  473.  
  474.   File attributes are NOT implemented - the eight's
  475. bit in file name is always 0,  and file name are always
  476. uppercased, null in file names are replaced by spaces.
  477.  
  478.   The following functions are not implemented at all - the
  479. program which try to use them is terminated with an error message
  480. giving the (hexadecimal) code of the function:
  481.  
  482.     A star * means that the function could be fully
  483.     implemented in a future version.
  484.  
  485.       Return SYSDAT address (sorry for DDT86)
  486.       Direct bios call except console i/o, dma, partial iobyte
  487.       and BIOS call write to screen.
  488.       Extended BIOS calls are not implemented except extended
  489.       console i/o, set/clear user tick routine and return boot drive.
  490.     * Get Maximum Free Memory at Absolute address
  491.  
  492.  
  493.     Allocate at absolute address is only supported if that
  494.     address is the same as the start of a free region, like the
  495.     one returned by Get Max Memory.
  496.  
  497.  
  498. GSX-86 is not supported.
  499.  
  500.  
  501. Other differences:
  502.            The CPM reserved area of FCBs are used by the
  503.            emulator, and do NOT contains allocation informations.
  504.            Fields CR, RC, EX, S1 and S2 are almost identical.
  505.  
  506.            Some registers listed as destroyed may be effectively
  507.            destroyed by AME86 but not by CPM-86. Returned condition
  508.            codes may be different between AME86 and CPM-86.  Any
  509.            information on behavior of CPM-86 in this area welcome.
  510.  
  511.            ^C handling and disk i/o error handling may differ
  512.            quite a bit:
  513.             ^C print an error message and abort the
  514.             program, returning an error status.  Files
  515.             are NOT closed,  CHKDSK should be run on
  516.             the used disks to ensure consistency.
  517.  
  518.             I/O error is handled as usual by MSDOS, on
  519.             selection of ABORT,  an error message is
  520.             printed by AME86, to signal that it was
  521.             able to restore the MSDOS environment.
  522.  
  523.  
  524.         AME86 is normally more restrictive in error handling.
  525.         Some error which may have been un-noticced under
  526.         CPM-86 may be show by AME86.
  527.  
  528.  
  529.             Read console buffer use the MSDOS read line function,
  530.         and the MSDOS line editing facility: this is different of
  531.         the CP/M-86 line editing.
  532.  
  533.  
  534.    Program checked under AME86
  535.    ---------------------------
  536.  
  537.    The following programs have been extensively tested:
  538.     (that is used for real work,  or systematically checked
  539.     with all functions):
  540.  
  541.     ASM86 *
  542.     GENCMD *
  543.     RED
  544.     PACMAN (a MWC-86 program)
  545.     COMPAS-86
  546.     MBASIC-86
  547.     FABS-86
  548.     HELP
  549.     WordStar version 3
  550.     ZORK
  551.     DBASE
  552.  
  553.    * Require a CPM-86/80 license to run on a computer with MSDOS/AME86.
  554.  
  555.    The following programs have been partially tested:
  556.     (that is tested for correct load and work with some exemples
  557.     given in the user's manual).
  558.  
  559.     MP (MultiPlan)
  560.     MWC-86
  561.     PIP (note:  PRN: and LST: have the CPM meaning)
  562.     SELECT-86  (Background printing do not work)
  563.  
  564.  
  565.  
  566.     The following programs do NOT work:
  567.  
  568.     MAINT
  569.     STAT    (except for STAT and STAT X:)
  570.     MSKERMIT    (modify driver)
  571.  
  572.  
  573.     The following common package will not work because they use
  574.     CPM-80,  not CPM-86:
  575.  
  576.     CONDOR-3 (v2.1)
  577.     All package buyed for VT-180.
  578.     WordStar before version 3.
  579.  
  580.    Error Messages
  581.    --------------
  582.  
  583. All AME86 error messages are in the format
  584.         "AME86 - text"
  585. the AME86 exit to MSDOS after printing this message.  Depending of
  586. the file activity,  there could be hidden files on the disk.  If
  587. AME86 crash when there was file activity, it is a good practice to
  588. use CHKDSK to recover lost space.
  589.  
  590. All other error message are coming from MSDOS (disk error) or the
  591. application program.  You may receive an error message from the application
  592. that you have never seen on CPM-86 if, for exemple, one of the file
  593. is missing.
  594.  
  595.  
  596. AME86 - error messages:
  597.  
  598. program no found
  599.     The program to emulated was not found in the current directory
  600.     of the specified (or default) disk,  or AME86 was not followed
  601.     by a file name,  or that file name had a bad syntax.
  602.  
  603.     Check for the program IN THE CURRENT DIRECTORY of the SPECIFIED
  604.     DRIVE.  AME86 cannot handle directory name or PATH.
  605.  
  606. Cannot chain to program:
  607.     The program did exit with a CHAIN statement,  the statement
  608.     was not processed for one of the following reason:
  609.         - There was an option present.
  610.         - There was no CMD file on the specified OR
  611.           default drive.
  612.     There may be the same errors than on initial program load.
  613.  
  614.     The line received is printed after the error message,  check it
  615.     and create or copy the necessary files.  Commands like
  616.     DIR and ERA are not supported.  AME86 attempt to directly
  617.     load the specified program,  not to give the command to
  618.     process to MSDOS.
  619.  
  620. file not a proper CP/M-86 program
  621.     The file was not in a CMD format (it was not produced by the
  622.     GENCMD utility).
  623.  
  624.     Check if you have a CP/M-86 file - there may have been an error
  625.     if file copy or file transmission.  If the file works under
  626.     CP/M-86 and you retried the copy/ transmission,  there may be
  627.     an error in AME86.  AME86 do not reconise all possible CMD file
  628.     headers, only the format created by GENCMD.
  629.  
  630. call 99h not emulated or out of range.
  631.  
  632.     The emulated program use a system call which is not emulated
  633.     and which is important for program continuation.  99 represents
  634.     the (hexadecimal) system call number - see CP/M-86 documentation
  635.     for more informations on the system call, and see restriction
  636.     on AME86. 73h may be GSX-86 (which is not emulated).
  637.  
  638.     If you believe that this call should be emulated, send the
  639.     program with necessary informations to reproduce the error
  640.     to the AME86 developer.
  641.  
  642.     You may try to run the program with option /I.
  643.  
  644. BIOS call 99h not emulated or out of range.
  645.  
  646.     The BIOS call used is not emulated.  If it is 80h, it is
  647.     an extended console BIOS call.
  648.  
  649. not enough memory to load program.
  650.  
  651.     Self explanatory.  MSDOS is large than CP/M-86,  and you have to
  652.     add AME86,  may be the PRINT and COMMAND resident parts...
  653.  
  654.     DEC will be pleased to sell you expansion memory of high
  655.     quality...
  656.  
  657. EOF encountered when loading program
  658.  
  659.     EOF was encountered when loading a section.  The file may
  660.     have been destroyed (for exemple, transmitted WITHOUT the
  661.     "image" switch and truncated at ^Z).  The file header may be
  662.     corrupted.
  663.  
  664.     If you are sure that your file was copied/ transmitted 
  665.     correctly from CP/M-86, and that it works under CP/M-86,
  666.     send the file to the AME86 developers: its a bug.
  667.     NOTE: EOF encountered when loading the LAST group of an image
  668.     has no effect, except loading garbage in the allocated area.
  669.     This is for compatibility with CP/M-86/80.
  670.  
  671. Cannot load at absolute address
  672.  
  673.     Your program contain a section which should be loaded at
  674.     absolute address.  This is not supported by AME86.
  675.  
  676. group larger than 64k
  677.  
  678.     When loading a program, a group (data, program or stack)
  679.     was larger than 64kb. This is not actually supported by
  680.     AME86.
  681.  
  682.     Send the program to the AME86 developer.
  683.  
  684. file too large for CP/M-86 handling.
  685.  
  686.     CP/M-86 cannot handle files larger than 31 extends of ? bytes.
  687.     This is quite big.  If you have created a file larger than this
  688.     maximum size using MSDOS,  and want to read it under AME86,
  689.     you receive this error.  Sorry.
  690.  
  691. ? in drive not supported for search
  692.  
  693.     Your program use the search function with a "?" in the
  694.     field DRIVE NUMBER of the FCB.  This is not supported.
  695.     This program is probably to dependent on CP/M-86 directory
  696.     organisation to be of any use under MSDOS/AME86.
  697.  
  698.     You may try to run the program with option /I.
  699.  
  700. Make only supported for extent 0.
  701.  
  702.     A MAKE function was attempted with a non zero
  703.     extent number.  This is not supported by AME86, as being
  704.     to dependend of BDOS handling of FCBs.
  705.  
  706. internal stack overflow.
  707.  
  708.     Send the program and the informations to reproduce the error
  709.     to the AME86 developers.  This is an internal error.
  710.  
  711. application stack overflow.
  712.  
  713.     Your application use the (96 bytes) default stack, and overflows;
  714.     or your application destroy some part of AME86 (the guard word is
  715.     the last word of the code).
  716.  
  717.     Your application must be changed.
  718.  
  719. Emulated program cannot stay resident
  720.  
  721.     Your application attempted a SYSTEM RESET (i.e. program exit)
  722.     with a non-zero Abort Code - this is not allowed.
  723.  
  724.     It is not possible to run an application which should stay
  725.     resident when other application are running. It is possible that
  726.     the abort code was neither 0 nor 1 - this is undefined by CPM-86.
  727.  
  728.  
  729. Internal memory initialisation failure
  730.  
  731.     Internal MSDOS database may have been corrupted by a previous
  732.     program.  Or there may be a bug in AME86.
  733.  
  734.     Reboot MSDOS and run the program again.  Check memory.
  735.  
  736.  
  737. Illegal option
  738.  
  739.     The option specified in the command file (with the program
  740.     to load) was not a legal one.  Or the file name contained a "/".
  741.  
  742.     Retype the command correctly (options must be one letter long,
  743.     either upper or lower case).  The option character is always "/",
  744.     independently of MSDOS setup.
  745.  
  746.  
  747. Options F and S are mutually exclusive
  748.  
  749.     You specified both /S and /F.
  750.  
  751.     Read again description of /S and /F:  both acheive basically
  752.     the same result in different ways.  Rule of thumb: if the
  753.     program reside in MDRIVE, use /F, otherwise use /S.  Use none
  754.     if your program do not have overlays!
  755.  
  756.  
  757. Pathname cannot be used with /S and /F
  758.  
  759.     Put the program on an alternate's drive CURRENT directory.
  760.  
  761.  
  762. Illegal IOBYTE value
  763.  
  764.     A SET IOBYTE function (BDOS or BIOS) attempted to change the
  765.     IOBYTE value.
  766.  
  767.     IOBYTE functionality is not supported for this release of
  768.     AME86.  Communication programs normally do NOT run under AME86,
  769.     as they are too operating system dependant.  If you need to
  770.     redirect standard input/output of other programs,  you may
  771.     use MSDOS ">" and "<" redirection facilities.
  772.  
  773.  
  774. illegal path name
  775.  
  776.     Either the path name was too long or misformed.
  777.  
  778.     Check for correct path name (for exemple using DIR).
  779.  
  780.  
  781. path not found
  782.  
  783.     One of the directory specified on the path name do not exist.
  784.     If it hapens after the initialisation pahse of the program,
  785.     it is an internal error (or your disk is corrupted).
  786.  
  787.     Look for the correct path name,  for exemple using DIR.
  788.  
  789.  
  790. illegal wild card character
  791.  
  792.     There is * or ? in the name of the file to load.
  793.  
  794.     This characters are not allowed,  as they have special
  795.     meaning which do not apply in this situation.
  796.  
  797.  
  798. program aborted by ^C
  799.  
  800.     The user typed a ^C which was not trapped by a program input
  801.     routine.  The program is aborted.
  802.  
  803.     This is the same as a ^C on CP/M. If the program directly
  804.     changed vectors or other important locations,  they are
  805.     not restored.  If there was any file opened in WRITE mode,
  806.     CHKDSK should be run to restore disk consistency).
  807.  
  808.  
  809. program aborted due to fatal i/o error
  810.  
  811.     Either a fatal i/o error was detected,  or the user
  812.     answered A to a non-fatal error.
  813.  
  814.     AME86 was able to restore MSDOS environment.
  815.  
  816.     Exit condition is the same as done by ^C exit. (use CHKDSK to
  817.     restore disk consistency).
  818.  
  819.  
  820.  
  821.  
  822.  
  823.    CCPM-86 (concurent CPM) and AME86
  824.    ---------------------------------
  825.  
  826. No special effort have been done to cover CCPM migration to AME86.
  827. But to ease portables programs (as CCPM is supposed to have MSDOS
  828. emulation some day), the following effort was done:
  829.  
  830.      1) C_raw_io function (CPM function 6) implement the code 0FDh,
  831.     which read with wait.  This ease efficient portable programs.
  832.  
  833.      2) Success status return is the same as CCPM (which is a superset of
  834.     the documented CPM-86).  Practically, the status returned may be
  835.     found in BX and AX.
  836.  
  837.      3) When identical functionality cannot be provided (like direct
  838.     BIOS access) I plan to implement CCPM subset.
  839.  
  840.      4) In the base page, the field DRIVE (offset 50h) contains the
  841.     drive number used to load the program (initial load only,
  842.     not if the PROGRAM LOAD function was used).
  843.  
  844.      5) The MP/M emulation of memory allocation routines may be
  845.     implemented.
  846.  
  847.  
  848.  
  849.  
  850.    Implementation notes
  851.    --------------------
  852.  
  853. Basically AME86 emulates the interupt 224 and other environement
  854. elements of CPM-86, in two ways:
  855.  
  856.     1) By mapping (after necesseray transformations of parameters)
  857.        CPM-86 functions to MSDOS functions.
  858.  
  859.     2) By maintenaing an alternate environment (the CPM-86 or emulated
  860.        program environment).  The normal environment is called MSDOS
  861.        environment.  Emulator's environment refer to MSDOS environment
  862.        with some part of of CPM-86 environment active for quick
  863.        environment switch.
  864.  
  865. AME86 do NOT implement command language equivallence.  Its much more like
  866. calling a compatibility mode program from DCL on a VAX.  Once AME86 is loaded,
  867. it use its first parameter as the (CPM-86) program to load, and the
  868. remaining parameters are passed to the emulated programs (the first two
  869. parameters results in usual FCB in base page).
  870.  
  871. As the format of the executable files differ, AME86 has to completly
  872. implement the program load function (including memory allocation and
  873. file name parsing).  Most other functions are simply remaped to the
  874. the MSDOS equivallent (this is not too difficult, as both operating
  875. system were designed with ease of conversion of CPM programs in mind).
  876. One exception are the console i/o routines: they are directly mapped
  877. to firmware functions.  This allow screen handling programs to run
  878. as quickly on AME86 as on CPM-86.  This defeat the UNIX like i/o redirection
  879. on emulated programs using this feature.
  880.  
  881. Hardware functions work the same on CPM-86 and MSDOS (that is direct
  882. screen addressing and firmware access).  Firmware access is via different
  883. vectors on MSDOS and CPM-86, but the vector is part of the context
  884. switch process.  This is the main reason of the difficulty of using DEBUG
  885. on an emulated program (context switch is not done at interupt 3).
  886.  
  887. But hardware may not be shared between MSDOS and the emulated program:
  888. unfortunately, there is common hardware between the printer port and
  889. the communication port.  This is why communication programs which
  890. patch CPM-86 to access the communication port cannot work on AME86.
  891. Using the extended communication board is possible.  If usefull communication
  892. programs use the CPM-86 V2.0 AUX: driver exclusively, it could be possible
  893. to implement this driver in MSDOS (within or separately of AME86).
  894.  
  895. The most delicate part is FILE SYSTEM.  One reason is that the file
  896. system is badly documented in both operating systems (CPM-86 and MSDOS).
  897. An other reason is that most programs use the file system in quite tricky
  898. ways (files are never closed, or closed more than once, or program 
  899. directly access FCB fields supposed to be reserved to operating system).
  900. The misuse of the file system go from unexpected but harmless usages,
  901. like MBASIC using random i/o for all file access (even file load), to
  902. very unexpected usage, like COMPAS pascal using partially sequential and
  903. partially random access (by modifying pointers within FCB) on the same file.
  904. The third reason is that MSDOS usage of FCB is quite different than CPM-86:
  905. block number and random record numbers are largers, the size of the file
  906. is maintened up to the byte, etc...
  907.  
  908. The files themself should not be a major problem.  ASCII files are compatible,
  909. except that the data after end-of-file character may not be the same (I still
  910. hope that no program use that!).  Other file structures depend on the 
  911. application, not from the operating system.  File size is limited to the
  912. maximum size which may be handled by CPM (~500kb).
  913.  
  914. Directory structure is quite different, but the differences are not important
  915. for normal programs.  All file names will be forced to uppercase, all
  916. attribute bits cleared and null changed to space (in the emulated program's
  917. FCB too, not only in the emulator data structure).  This may be a problem
  918. if a program insists that the file names it uses are not modified (i.e.
  919. compared with another file name).  The search function returns different
  920. values too (an FCB on MSDOS,  a directory entry on CPM).  That is almost
  921. the same, except if somebody access allocation data in this way. AME86
  922. try to create a faked directory entry from the MSDOS FCB.  There is no
  923. problem if only the file name (and extension) is accessed.
  924.  
  925. FCB are converted back and forth between CPM-86 and MSDOS format on the
  926. fly, before and after most i/o operations.  Here are the equivallences:
  927.  
  928.     Drive, file name and extension are always the same,
  929.     except for uppercasing, attribute bit deletion and change
  930.     of nulls to spaces.
  931.  
  932.     MSDOS current block is converted to CPM-86 extent number.
  933.     This limit the number of blocks to 31 (of 128 bytes).
  934.     if EXTENT contains a "?", it is converted to zero.
  935.  
  936.     MSDOS record size is forced to 128 (80h).
  937.  
  938.     Current records (CURRENT and CR) are almost the same. When
  939.     writing sequentially a file under CPM-86, the EX:CR fields
  940.     go up to 0:80h, the next write set them a 1:1.  Under AME86,
  941.     the EX:CR fields growth up to 0:7fh (like under CPM-86), then
  942.     is set to 1:0 (instead of 0:80h),  then to 1:1 (like CPM-86).
  943.  
  944.     AME86 RC (Record count in current extent) is computed from
  945.     the MSDOS file size and the current record.  The result is same
  946.     RC as under CPM-86.
  947.  
  948.     MSDOS file size, date/time and system area are saved to
  949.     CPM-86 system save area.  The CPM-86 system save area (which
  950.     normally contains allocation informations are now meaningless
  951.     to the emulated program, which should NOT modify it.
  952.  
  953.     CPM-86 S1 and S2 fields are not documented.  the OPEN/MAKE
  954.     function set S1 to zero, and put 80h to S2. S1 is not modified
  955.     by other functions, S2 is only modified by WRITE, which reset
  956.     it to 0.  Under CPM-86, S2 is set back to 80h at extent switch
  957.     (that is when it is not necessary to close the file).  This
  958.     functionality is not reflected in AME86,  as the file MUST be
  959.     closed if opened in write mode.
  960.  
  961.     Partial record in both sequential and random read are returned
  962.     as full records (success),  zero filled.
  963.  
  964.  
  965.     Actually the system assumes that the maximum size of an extent
  966.     is 128 records of 128 bytes, and that there is at most 32
  967.     extents - this limits size of any file to around 500kb.
  968.  
  969.  
  970.  
  971.    Read console buffer is not emulated, but directly use MSDOS
  972. read console buffer function,  with some "patching":  DX, AX and BX
  973. are returned as 0,  and the CR which is added by MSDOS is replaced by
  974. a 0.
  975.  
  976.  
  977.  
  978. Interupt handling
  979.  
  980.     Some interupt vectors are different.  Especially the firmware 
  981.     interrupt is different,  and must absolutely be changed
  982.     (context change) when we switch from AME86 to the emulated
  983.     program.  The whole AME86 run in MSDOS mode (included some
  984.     functions used internally,  like memory allocation and
  985.     program load).  Changing the vector is known as context
  986.     switching.  The whole context switch include some other tasks,
  987.     like stack switch,  which are not relevant here.
  988.  
  989.     There is 6 places when some context must be changed:
  990.  
  991.     1) AME86 initialisation
  992.     2) AME86 exit (including ERROR and ^C exits)
  993.     3) INT 224 call from emulated program
  994.     4) start/continue emulated program
  995.     5) MSDOS interupts which may occurs when emulated program is running
  996.     6) Interupt going to emulated program when AME86 is running
  997.        (or a request is serviced by MSDOS).
  998.  
  999.  
  1000.     The vector of concern are:
  1001.  
  1002.     CP/M-86 call (224, E0h)
  1003.     MSDOS firmware interupt call (18h)
  1004.     CP/M-86 firmware interupt call (21h) - conflict with MSDOS CALL
  1005.     MSDOS call (21h)
  1006.     User clock (64h) for both MSDOS and CP/M-86
  1007.     ERROR, ^C and TERMINATE (22h, 23h, 24h)
  1008.  
  1009.     Any vector that the CP/M-86 program is modifying...
  1010.  
  1011.  
  1012. The MSDOS idle interupt (28h) may only be given when we do a request
  1013. to MSDOS,  and as such are already in MSDOS context.  This interupt
  1014. need not be switched,  and the print spooler may run with AME86.
  1015.  
  1016. The CP/M-86 call (224) is initialised at start and restored at exit,
  1017. but stay present even if in MSDOS context,  as MSDOS do not use it.
  1018.  
  1019.  
  1020. Interupt 21h is modified to point on MSDOS handler or firmware just
  1021. before to give control to emulated program,  and at interupt 224.
  1022.  
  1023.  
  1024.  
  1025. Stack handling.
  1026.  
  1027.         MSDOS switch to an internal stack when called.
  1028.         But is requires that the application has a stack with
  1029.         at least 128 bytes free for interupt handling.  COM
  1030.         files receive a stack of 256 bytes.  EXE files (as the
  1031.         AME emulator) must setup they own stack.
  1032.  
  1033.         CPM-86 call the user's program with the BDOS stack
  1034.         (of 96 bytes) that the program may use if it do
  1035.         not exceed this requirement.  CPM-86 switch to an 
  1036.          internal stack after a function call (and most probably
  1037.         after any interupt, as there is no clear requirement
  1038.         for a minimum user stack).
  1039.  
  1040.         The firmware interupts use a local stack.  Firmware
  1041.         handling is done one the caller's stack.  Firmware +
  1042.         interupt use 62 bytes.
  1043.  
  1044.         AME86 has two stack: An application stack which have
  1045.         96 bytes + 132 bytes for MSDOS and interupts,
  1046.         and an internal stack.  AME86 switch to the internal
  1047.         stack when called.  Both stack are checked by
  1048.         guard words (words initialise set to zero, and checked
  1049.         after each call).
  1050.  
  1051.         THE RISK IS THAT THE EMULATED PROGRAM NORMALLY SWITCH
  1052.         ON A LOCAL STACK,  WHICH MAY NOT HAVE THE 132 BYTES
  1053.         AVAILLABLE FOR MSDOS.  In that case,  the emulated
  1054.         program may crash in unpredicatble way if it do not
  1055.         incorporate a stack overflow check - and most programs
  1056.         don't.
  1057.  
  1058. Distribution:
  1059. ------------
  1060.  
  1061.    The program is copyrighted,  but may be freely distributed inside
  1062. and outside of DEC, to any non-military organisation.  It is not
  1063. allowed to sell it,  but reproduction costs may be recovered.
  1064.  
  1065. The sources will be put at disposition on SEENA1::SYS$PUBLIC:,  at the
  1066. following conditions:
  1067.  
  1068.         The original copyright must not be removed or
  1069.         modified.
  1070.  
  1071.         If any modification is done (either bug correction
  1072.         or enhancement),  a copy must be send to me,
  1073.         and the enhancement may be included in any
  1074.         future release of AME86.
  1075.  
  1076.         AME86 is intended for use on DEC computers ONLY.
  1077.  
  1078.  
  1079. To assemble the sources, use:
  1080.     MASM AME86;
  1081.     MASM EXCON;
  1082.     MASM AMEND;
  1083.  
  1084.     LINK AME86+EXCON+AMEND;
  1085.  
  1086.  
  1087.  
  1088.  
  1089. Any suggestion welcome.  Let me know if you want to receive any
  1090. future version of this program.
  1091.  
  1092.  
  1093. Jean-Marc Lugrin,  SWS SEENA,  21-NOV-1984
  1094.                         SEENA1::LUGRIN (prefered)
  1095.                         DecMail @GEV
  1096. 
  1097.