****************************************************************************
*                                                                          *
*                       *-*-*   READ.ME   *-*-*                            *
*                                                                          *
****************************************************************************
*                                                                          *
*                           DOS/RMX R1.0                                   *
*                                                                          *
*                            7 Feb 1991                                    *
*                                                                          *
*   This READ.ME file describes problems found in the DOS/RMX Operating    *
*   System, and workarounds for these problems.                            *
*                                                                          *
*   The items in this READ.ME file are organized by layer of the DOS/RMX   *
*   Operating System.  The catagories are as follows:                      *
*                                                                          *
*   Device Drivers (DD)       BIOS (IOS)                      EIOS (EIO)   *
*   Application Loader (AL)   Human Interface (HI)            UDI (UDI)    *
*   SDM III (SDM)             Human Interface Commands (HIC)  SDB (SDB)    *
*   Terminal Support (TSC)    Demonstration Software (DS)     Other (OTH)  *
*   Networking (NET)          DOS Utilities (DUT)             RHDFS (RHD)  *
*   EDOS File Driver (EDOS)   VM86 Dispatcher (V86)           MBII  (MB2)  *  
*   Languages (LAN)           Console Sharing (CON)                        *  
*   DOS Applications (DAP)    Loadable Device Drivers (LDD)                *  
*                                                                          *
****************************************************************************

                              EIOS
      
EIO-1. Passing a NIL Pointer results in a General Protection error.

      The following system calls result in a General Protection error
      if a NIL Pointer is passed as a parameter:

      1) GET$LOGICAL$DEVICE$STATUS
      2) GET$USER$IDS
      3) LOGICAL$ATTACH$DEVICE
      4) ATTACH$FILE
      5) CATALOG$CONNECTION
      6) CHANGE$ACCESS
      7) GET$DIRECTORY$ENTRY
      8) LOOKUP$CONNECTION
      9) UNCATALOG$CONNECTION
     10) VERIFY$USER
     11) GET$FILE$STATUS
     12) RENAME$FILE
     13) GET$CONNECTION$STATUS

EIO-2. An E$SPACE exception is not reported when EIOS buffers are flushed.

       If you open a file with one or more EIOS buffers and write to it,
       data is buffered in the EIOS buffers, and is subsequently flushed 
       to the disk when the file is closed. If the EIOS detects an E$SPACE
       exception on a full disk at this point, the data is not written to
       the disk, but the S$CLOSE system call returns to the application
       with an E$OK status.

****************************************************************************

                              SDM III

SDM-1. SDM III occassionally executes the last command from the
       previous SDM session.

       When debugging with SDM III using brackets and commas (such as
       "10<nrp;vs>,"), it is possible to step past the end of the Human
       Interface command being debugged and return to the CLI prompt.
       In this case, SDM III is left with a pending command.  If
       SDM III is now re-entered due to a hardware trap such as a
       General Protection error, the standard trap/fault message and
       address will be displayed, and the uncompleted SDM command
       from the previous session will be executed.

****************************************************************************

                                  SDB  

SDB-1. "E" is not displayed with VS of certain 32-bit RQE$ calls.

       The iRMX III SDB makes no distinction between the 
       RQ and RQE versions of certain system calls.  Thus, the
       'E' is not displayed with VS on the following calls:
   
       1) rqe$get$pool$attributes
       2) rqe$create$job
   
       A display of

         get pool attributes
         create job
 
       is seen instead of
    
         E get pool attributes
         E create job.

SDB-2. The iRMX III SDB doesn't clear the unused portion of each stack
       entry before displaying the entry.

       The VS command displays the stack at a system call and shows
       the call's parameter structure.  These stack entries are
       displayed based on the type of code being executed, i.e.,
       16 bit code will have its stack displayed as 16 bit values,
       and 32 bit code will have its stack displayed as 32 bit
       values.  In either case, the unused portion of the stack is
       displayed as well as the used portion.  In other words, a
       BYTE parameter will have 8 valid bits of data displayed as
       well as 8 bits of unused data on a 16 bit stack; it will
       have 8 valid bits of data displayed as well as 24 bits of
       unused data on a 32 bit stack.  The full stack is displayed
       so an actual stack problem can be detected.
       
SDB-3. VMI and VMO commands do not recognize the limits of
       the MBII messages in the trace buffers.

       The VMI and VMO commands are used to display input and output
       messages in a set of user-configured trace buffers.  These
       trace buffers are circular in nature and contain the last 'x'
       number of messages sent/received, where 'x' varies based on the
       configured size of the trace buffers.  If the user chooses to
       display a number of messages which is larger than the number
       currently contained in these buffers, the SDB uses the circular
       nature of the buffers to try to display the messages within the
       range you specified.  For example, if the input trace buffer
       only holds 100 messages, and 8000 messages have been received,
       using the VMI command to display messages 6000 to 6100 will
       result in the display of messages 7900 to 8000.  It is up to
       the user of these commands to know the size of the trace buffers
       configured into the system via the Nucleus Communications Service
       screen in the ICU (NTM parameter) and use this knowledge when
       querying the trace buffers.

       NOTE: For Pre-configured DOS/RMX for iSBC 386PC16, the trace buffer 
             size is 255 messages.

SDB-4. VT display of priority-based signal service port is incorrect.
   
       The display of a priority signal service port using the SDB VT
       command shows FIFO queuing.  This is ONLY a display error; the
       Nucleus treats the same signal service port correctly as a
       priority-based port.

****************************************************************************
   
                            TERMINAL SUPPORT CODE

TSC-1. Terminal Attributes need to be restored after LOCK/CONNECT.

       When a Human Interface-configured terminal is taken off line for
       use with a modem via the LOCK and CONNECT commands, the user should
       be careful to note the terminal's current attributes before changing
       them to meet his or her needs.  If the user changes these attributes,
       he or she must restore them before returning the terminal to the Human
       Interface via the DISCONNECT and UNLOCK commands.  Otherwise, the
       terminal will be unusable by the Human Interface.

****************************************************************************

                      LANGUAGES AND UTILITIES

LAN-1. Aliases for 386 languages assume DOS-hosted tools.

       The lang386.als that is invoked from :CONFIG:ALIAS.CSD contains
       two sets of alias statements for PLM386, BND386 etc. One set
       assumes that the DOS-hosted tools are installed in standard
       DOS directories. The other set assumes that the tools are
       installed under /lang286. The second set is commented out,
       i.e. the tools are assumed to have been installed from DOS.
       Inspect the :CONFIG:LANG386.ALS and make the necessary
       modifications to match the way you have installed the Intel
       386 tools.
       
LAN-2. ASM386 V4.0 does not work from the iRMX side of DOS/RMX.

       ASM386 V4.0 causes a General Protection error when invoked from iRMX
       (using RUN86). Make sure you use ASM386 V3.0 from iRMX.
       Version V4.0 runs properly from DOS however.

LAN-3. The Pre-configured DOS/RMX Operating System has 20 OS extension
       gates (440 thru 459) available for use by applications. 

       They can be bound to an application via the RQE$Set$OS$Extension
       system call. Other applications can access the OS extensions
       via assembly language interface procedures described below:

           This ASM module is a sample interface to Call Gate 441
           which is one of the user-accessable gates.  The OS
           Extension procedure tied to the gate has the following
           FAR external interface:

           out$char: PROCEDURE(value, status$p) EXTERNAL;

                               ASM386 MODULE

           GATE_441     equ     441

           $GENONLY
           %*DEFINE(CALL_G(ARG))
           (DB    9AH
            DD    0, %ARG*8)

           Name    Interface

           Code    Segment   ER    PUBLIC

               Public Outchar
                
           Outchar Proc    Near

           ;
           ;      PLM CALL -  CALL  OUT$CHAR  (VALUE, @STATUS);
           ;
           ;              STACK  FRAME AFTER PUSHING EBP
           ;
           ;                ,__________________________,
           ;        ESP ->  |        OLD EBP           |  [EBP]
           ;                |__________________________|
           ;                |  OFFSET OF RET. ADD.     |  [EBP + 4]
           ;                |__________________________|  
           ;                |  OFFSET OF STATUS        |  [EBP + 8]
           ;                |__________________________|
           ;                |  SEGMENT OF STATUS       |  [EBP + 12]
           ;                |__________________________|
           ;                |     VALUE (PARAMETER)    |  [EBP + 16]
           ;                '__________________________'
           ;

               push    ebp
               mov     ebp, esp
               push    dword ptr ss:[ebp + 16]        ; value
               push    dword ptr ss:[ebp + 12]        ; selector of status$p
               push    dword ptr ss:[ebp + 8]         ; offset of status$p

               %call_g(GATE_441)

               ;CALL gate_441 - Invoke entry procedure through the call gate
               les     edi, pword ptr ss:[ebp + 8]    ; Load status$p in es:edi
               mov     cx,es:[edi]                    ; Load condition code
                                                      ; in cx
               jcxz    done                           ; If CX=0, then no error
               ;
               ; Error processing code IF CX <> 0
               ;
           done:
               ;
               pop     ebp
               ret     12
               Outchar Endp

           Code    Ends
           End

          As can be seen from the code, the Outchar procedure is a near
          procedure which can be called from PL/M.  This same approach can
          be used for any OS Extension.

****************************************************************************

                          EDOS FILE DRIVER

EDOS-1. The default CONFIG.SYS provided with the DOS/RMX system has
        FILES=64. This also limits the number of files that may be
        accessed simultaneously via the EDOS File Driver. If you get
        an E$LIMIT exception as a result of this, you may increase this
        parameter in CONFIG.SYS.

EDOS-2. Seek backwards from EOF (mode 4) is not supported for directory files.

        A$SEEK or S$SEEK with mode 4 (backwards from EOF) is not supported
        for directory files. This is because of an inherent limitation
        in DOS. (Note that this mode IS supported for data files; the
        limitation is only with directory files - an E$SUPPORT exception 
        is returned if you try to seek with mode 4 on a directory file
        via the EDOS file driver).

****************************************************************************
       
                            CONSOLE SHARING

CON-1. DOS/RMX does not support an MDA-monochrome display card.

       The DOS prompt will come back after loading the DOS/RMX bootfile.  
       However, ALT-SYS REQ will switch to a blank screen.  
       iRMX is alive, but its screen output is invisible.

CON-2. Console ownership can be switched programmatically between DOS and iRMX.

       Refer to the /RMX386/DEMO/ALTSYS/README file - it describes this
       feature. It has not been formally evaluated.

****************************************************************************

                          OTHER INFORMATION

OTH-1. Additional Porting Guidelines - LARGE to COMPACT models of compilation

      The iRMX III.1 Operating System only provides COMPACT interface
      libraries.  This requires 32 bit application code to reside in the
      same code segment as these system interface procedures.  The simplest
      way to accomplish this is to structure your application as one or
      more COMPACT subsystems.  When porting an existing 16 bit LARGE model
      application to a 32 bit COMPACT model application, consider the
      following:

      1) COMPACT model code runs faster than LARGE model code.  It takes
         26 clocks for each segment register load.  NEAR (COMPACT) calls
         require no segment register loads where as FAR (LARGE) calls
         require at least 4 register loads (CS and DS going and returning)
         per call.  This register loading time adds up quickly, especially
         if nested calls are made.  A simple LARGE model 16 bit test program
         which made recursive calls to just four system calls experienced a 6%
         performance boost when changed to COMPACT.

      2) When moving from LARGE to COMPACT, take steps to insure that a
         valid DS value is available to jobs and tasks created by the
         RQ$CREATE$JOB, RQE$CREATE$JOB, RQ$CREATE$IO$JOB, RQE$CREATE$IO$JOB,
         RQ$LOAD$IO$JOB, RQE$LOAD$IO$JOB, and RQ$CREATE$TASK system calls.
         In LARGE model code which made one of these system calls, one
         typically specified a NULL data segment value along with a pointer
         to a publically declared procedure.  This worked fine since LARGE
         model procedures always load DS upon entry.  This is not the case,
         however, in COMPACT model code.  DS is assumed to have been set up
         previously.  To avoid getting a General Protection error due to a
         NULL DS, the programmer has two choices; 1) change the code to pass
         a valid selector for the data segment of created jobs and tasks, or
         2) use the EXPORT compiler directive to produce public procedures
         which continue to load DS upon entry.  An example of the second
         option is as follows:

            $COMPACT(my_code -CONST IN CODE- HAS my_proc;
            $EXPORTS task$1)
               .
               .
            my_proc:
            DO;
                 .
                 .
                 task$1: PROCEDURE PUBLIC;
                    .
                    .
                 END task$1;
            END my_proc;

         The EXPORTS directive causes the compiler to provide a FAR interface
         for the procedure task$1.  This interface includes setting up DS
         upon procedure entry.

****************************************************************************

                             DOS APPLICATIONS

DAP-1. Various DOS Application software packages have been tested with the
       DOS/RMX Operating System.  Some have been found to have the following
       limitations:

       PC Paintbrush IV Plus V1.0: Not supported due to TSR incompatibilities.

       Norton Utilities: the SysInfo (SI) program alternates between detecting
       clock speeds of 8 and 16 MHz.  This is due to the inaccuracy of the
       emulation of DOS clock frequency manipulation and query commands by
       the VM86 Dispatcher.  The DOS/RMX Operating System prevents DOS
       manipulation of the system clock in order to insure Real-Time integrity.

       Harvard Graphics V2.3:  Problems were seen when installing this program
       under DOS/RMX.  To prevent such problems, install the HG package under
       DOS before loading the DOS/RMX system.
   
       DESQview 2.31:  Numerous problems were seen with this software package.
       Based on our tests, DESQview 2.31 is not supported by DOS/RMX.

       Lotus 1-2-3 V3.1: This package runs in protected mode via DPMI
       interfaces and thus is not supported.  Non-protected mode versions
       of Lotus work fine except for its reinitialization of the graphics
       card to clear the screen.  This blanks the iRMX screen also.

       AutoCAD:  Text screens such as the main menu and help screen utilize
       both the DOS and iRMX video pages on the EGA/VGA controller.  This
       causes the iRMX screen to contain garbage characters when hot-keyed
       to from within AutoCAD.  This screen clutter, however, can be
       cleared by scrolling it up with carriage returns.

       SYTOS backup utility: In order to successfully use this utility
       to back up an iRMX partition (via the RHDFS), you must first
       configure SYTOS to be network-capable and must load the DOS
       MS-NET software and use it with the DOS/RMX network redirector.

       The Archive VP60e tape backup utility: This package has problems
       under DOS/RMX and is not supported.

       Ventura Publisher 3.0: This memory-intensive software package
       works fine provided the DOS/RMX system includes 2 megabytes of
       Expanded Memory (via an Intel AboveBoard) and optimize TPA memory
       (lowered values for FILES and BUFFERS in CONFIG.SYS).

       General:  DOS applications which are sensitive to timing will fail
       when competing with RMX for the CPU.  Observed failures include
       XMODEM data transfers and the Norton Disk Test.

DAP-2. Intel Virtual Terminal TSR works with the following limitation:

       You may experience problems attaching to your iRMX partitions on your
       hard disk after you have loaded the Intel VT TSR. To work around this
       problem, please follow this sequence:

        a. Attach any iRMX partitions you forsee using.
           (such as c_rmx, d_rmx, etc.)

        b. And then load the Intel VT TSR.

       If you wish to attach any iRMX partitions later, please unload the
       VT TSR, and follow the above sequence.

****************************************************************************

                      DEMONSTRATION SOFTWARE 

DS-1. Interface Library for DOS Real-Time-Extensions is provided.

      The /rmx386/demo/rte/lib directory contains sample interface 
      libraries for DOS Real-Time-Extensions. DOS programs that use 
      Real-Time-Extensions may link to this library. Please refer to
      the READ.ME file in this directory before using the interface library.

      The /rmx386/demo/rte/inc directory also contains a 'C' header
      file for DOS Real-Time-Extensions. DOS programs that use 
      Real-Time-Extensions may include this header file. Please refer to
      the READ.ME file in this directory also.

****************************************************************************

                        NETWORKING

NET-1. A separate READ.ME for Network Redirector provided.

       The file /DOSRMX/README.RDR documents limitations of the PCNET.EXE
       program. This is the program that causes redirection of NETBIOS
       requests from DOS applications to iRMX-NET and allows concurrent
       access to the Network from both iRMX and DOS.

NET-2. iRMX-NET cannot consume from a DOS server. If you directly try to 
       attachdevice to a DOS server from iRMX, you may take a GP fault.

       If you need to consume from a DOS server, you may do so from the 
       DOS side of DOS/RMX. You may then indirectly consume from the iRMX 
       side via the EDOS File Driver.

       e.g.
          From the DOS side of DOS/RMX, do the following:

             net use r: \\<dos-server>
             dir r:
             ... 
             etc
             ...

          Then, from the iRMX side of DOS/RMX, do the following:
             ad r_dos as :r: e
             dir :r: 
             ... 
             etc
             ...

NET-3. iSBX 586 is not reset by CTL-ALT-DEL;  needs a power-down/up cycle.

       If you are using an iSBC386SX with an iSBX 586 for Networking,
       on resetting the system (with a CTL-ALT-DEL), the iRMX-NET 
       software will fail the next time iRMX is loaded. This is
       because the iSBX 586 did not get reset when the iSBC386SX was
       reset. Therefore you need to power down and then power back up
       the system before you re-boot DOS.


NET-4. iRMX-NET takes time to initialize on PC systems with sPCLINK2NIA.

       If you load the \dosrmx\dosrnet boot image which includes iRMX-NET for
       the sPCLINK2NIA controller, you will see a long delay (approx 30 seconds)
       between the time the DOS prompt appears and the time iRMX Human Interface
       is initialized. During this pause, the Alt-SysReq keyboard sequence
       to switch the console to iRMX will not be effective.

NET-5. Older versions of 300SX systems are jumpered incorrectly for Networking.

       If you have an older version of a SYP300SX system in which the Slave
       Interrupt Level 21H is hard-wired to a mouse port, you will not be
       able to use iRMX-NET. This is because the Preconfigured boot image
       \dosrmx\dosrnet assumes that the interrupt level for the sPCLINK2NIA
       controller is 21H.

       If you have such a system, you must load the non-networked boot file
       \dosrmx\dosrmx.

NET-6. 386/258 needs iRMX III.1.3 to interoperate via 186/530 with PC16.

       If you are using an iSBC 386PC16 with an iSBC 186/530, and expect to
       interoperate with an iSBC 386/258 using Networking via the iSBC 186/530,
       then you need to upgrade the iSBC 386/258 with iRMX III.1.3.
       This is because the iNA loadfile that is provided with DOS/RMX
       is incompatible with iRMX III prior to iRMX III.1.3. Also, the iNA 
       loadfile provided by iRMX III prior to iRMX III.1.3 is incompatible
       with DOS/RMX. The version of iNA that iRMX III.1.3 provides is
       compatible with DOS/RMX. Hence the need to upgrade the iSBC 386/258
       to iRMX III.1.3.

       NOTE: This also applies to other iSBC 386/xxx and iSBC 486/xxx
             boards which reside on the same MBII backplane and share
             the same iSBC 186/530 with the iSBC 386PC16.

****************************************************************************
       
                         DEVICE DRIVERS

DD-1. Formatting a zero-length partition from iRMX causes a Divide-by-0.

      If you attach a zero-length partition on your hard-disk from iRMX,  
      and then try to format it using the physical file driver, the
      device driver takes a Divide-by-Zero fault. This may also happen
      if you attempt to format an undefined partition from iRMX. Please
      verify your partition table (using RDISK) before you attempt to
      format an iRMX partition from iRMX.


DD-2. iRMX J-media floppies require a special loadable device-driver:

      The iRMX floppy driver included in the Pre-Configured Operating System
      images support only uniform format diskettes. They do not support
      iRMX "Standard" J-media diskettes which are formatted with
      128-byte sectors on the first track. However, if you wish to install
      iRMX software packages which you have on J-media, please use the
      iRMX floppy driver provided as a loadable device-driver as follows:
 
       a. Load the loadable floppy driver by typing:
 
              "sysload :rmx:drivers/flpydrv(100400)"

       b. Insert the J-media diskette into your floppy drive.
 
       c. Attach it from iRMX using the DUIB name "AS" (Drive 1 - 
          high density) or "BS" (Drive 2 - low density).

       d. Copy the files from the J-media diskette.

       e. Detach the diskette.

       f. To re-initialize the floppy controller for normal operations,
          insert a uniform-format diskette into the drive, attach it from
          iRMX (using the appropriate DUIB name A or B), and then detach it.

                           *** CAUTION ***

          The DUIB names AS and BS must be used only in the limited fashion
          described above.


****************************************************************************
