/**********************************************************************
 *                                                                    *
 *       Programmatic Switching of console/keyboard                   *
 *                   between DOS and iRMX                             *
 *                                                                    *
/**********************************************************************

This README file describes the RQE$Alt$SysReq primitive used to
programmatically switch console ownership between iRMX and DOS.

The motivation for this feature, the supported functions, the usage
model, the calling syntax of the primitive, and the interface library
are described below. A sample program is also included in this directory 
to illustrate all of this.

Motivation:
-----------
    The RQE$Alt$SysReq primitive allows iRMX tasks to switch the
console/keyboard between iRMX and DOS in a deterministic fashion.
This is useful for applications which need to perform console output
urgently on one of the screens specifically (e.g. to print an alarm
message).

    A DOS program may indirectly access this primitive by requesting a
user-written iRMX task to do the switching on its behalf. (The request
may be communicated via one of the Real-Time-Extension calls or via a 
user-written VM86 extension).

    This provides a way to programmatically coordinate the
console/keyboard ownership between the DOS and iRMX counterparts of
a DOS/RMX application.

Supported functions:
--------------------
The primitive supports the following functions:

    1. Lock (disable) the Alt-SysReq hotkey, and get exclusive ownership 
       of the console-switching capability for the calling task.

    2. Switch the console/keyboard to iRMX. (If the current owner
       is already iRMX, then this is a NOP).

    3. Switch the console/keyboard to DOS. (If the current owner
       is already DOS, then this is a NOP).

    4. Query which OS currently owns the console/keyboard (DOS or RMX).

    5. Unlock (enable) the Alt-SysReq hotkey, and release the exclusive
       ownership of the console-switching capability.

Usage Model:
------------
    The recommended usage model for this primitive from an iRMX
    task is as follows:
   
        Step 1.
            Acquire lock.

        Step 2.
            Query current owner of screen (RMX or DOS).

        Step 3.
            Switch to desired screen (RMX or DOS).

        Step 4.
            Perform output etc.

        Step 5.
            Switch screen back to previous owner

        Step 6.
            Release lock

    Note: 
        A task may perform Step 2, 3, 4 or 5 without acquiring the lock
        (Step 1). No error checking will be performed to verify this.
        It is up to the application tasks to ensure deterministic
        behaviour by following the recommended usage model.


Calling convention:
-------------------

    The syntax of the RQE$Alt$SysReq primitive is as follows:

        ret$value = RQE$Alt$SysReq (cmd, status$p);

    where:

        cmd:
            is a  BYTE indicating the function to be performed. 
            Possible values are:

                1 - Acquire Lock
                2 - Release Lock
                3 - Switch to iRMX
                4 - Switch to DOS
                5 - Query current owner

                All other values for cmd are invalid.

        status$p:
            is a POINTER to a WORD containing the status of the
            operation. Possible values of status are:
                E$OK - Successful
                Else - Failure

        ret$value:
            is a BYTE containg a returned value which depends on
            the requested cmd.

            If cmd = 3 or 4,
                ret$value will contain the previous owner of the
                console (0 = DOS, 0FFH = iRMX).

            If cmd = 1 or 5,
                ret$value will contain the ccurrent owner of the
                console (0 = DOS, 0FFH = iRMX).

            If cmd = 2
                ret$value is undefined.

            In all cases, ret$value is valid only if the returned
            status is E$OK.

Interface Library:
-----------------
    An iRMX program that uses this primitive gets the symbol
"RQE$Alt$SysReq" resolved by linking to the interface library
(altsys.lib) included in this directory. The interface library
assumes a NEAR call (i.e. the program and this library must
belong to the same COMPACT subsystem).

Sample program:
--------------
    The file TEST.P38 contains a sample program that illustrates
the use of the RQE$Alt$SysReq primitive. The SUBMIT file TEST.CSD
generates this program (executable file TEST) and illustrates the
use of the interface library (ALTSYS.LIB).

/**********************************************************************/
