Index of /files/intel/dosrmx/RMX386/DEMO/ALTSYS/

/********************************************************************** * * * 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). /**********************************************************************/