Subversion Repositories SvarDOS

                    === SvarCOM implementation notes ===

=== SWAPPING =================================================================

Conventional RAM is scarce, that is why a command line interpreter must make

efforts to reduce its memory footprint when launching applications. SvarCOM

does that by installing a small executable module in memory, called RMOD (for

Resident MODule). SvarCOM pre-sets RMOD so it knows how to execute the external

program and removes itself from memory, letting RMOD do the job. RMOD executes

the application, waits for it to finish and then calls back SvarCOM. All

necessary contextual data is kept in a resident, RMOD-owned memory structure.

=== NLS STRINGS ==============================================================

SvarCOM can output information in many languages. To do so, it relies on a

precompiled resource file named SVARCOM.LNG. When SvarCOM starts, it looks

for this file in the %DOSDIR% directory and loads from it the part that

contains the %LANG% language. All this is done by nls_langreload().

The SVARCOM.LNG file is compiled by TLUMACZ (from the SvarLANG.lib suite). It

takes CATS-style language files as input and compiles them into a single

SVARCOM.LNG resource file. It also produces a DEFLANG.C file with english

strings only, this one is embedded into the SvarCOM executable to display

English text in case SVARCOM.LNG is unavailable.

=== BATCH FILES SUPPORT ======================================================

When SvarCOM executes a command, it checks first if it has a *.BAT extension.

If so, it switches into 'batch-processing' mode:

 - allocates a "batch context" structure and attach it to rmod

 - writes the batch filename into the batch context (rmod-owned) memory, along

   with a counter that holds the offset of the next line to be executed.

 - a batch context has a "parent" pointer that may point to another batch

   context (owned by a different batch instance), it is, in essence, a linked

   list that allows batch files to call one another (typicall through the CALL

   command) allowing SvarCOM to get back to the parent batch once the child

   terminates.

When the rmod batch context pointer non-NULL, SvarCOM does not ask the user for

a command. Instead, it opens the batch file, jumps to the "next line to be

executed" and loads the command from there, incrementing the line counter in

the process.

=== PIPING COMMANDS ==========================================================

Piping a command means redirecting its standard output (stdout) to the

standard input (stdin) of another command. While redirection of file handles

is a concept well supported by the DOS kernels, piping is not, in part due to

the mono-task nature of DOS. SvarCOM provides piping support through following

logic:

1. user-entered (or batch-acquired) command line is analyzed for any kind of

   redirections (incl. pipes) by redir_parsecmd(). If the command appears to

   be piped, then redir_parsecmd() enforces a stdout redirection to a

   temporary file and moves all the pipe chain to an RMOD-owned buffer named

   "awaitingcmd", appending an stdin redirection so the next command's stdin

   is fed from the temporary file. The command is then executed.

2. before further execution, SvarCOM looks into its "awaitingcmd" buffer, and

   if it is non-empty, it runs its content.

3. when loading commands from the awaitingcmd, SvarCOM sets a special

   "delete_stdin_file" flag and passes it to command-executing functions so

   these remember to delete the stdin-redirected file.

=== GLOBAL EXECUTABLE LINKS ==================================================

SvarCOM features special support for "global executable links". This allows to

run selected programs from any directory, without the need to copy these

programs to a directory in %PATH%. Executable links are flat files written in

%DOSDIR%\LINKS\. Each file there contains the directory where the matching

program should be looked for.

=== STACK-OVERFLOW PROTECTION =================================================

RMOD reserves a 64-bytes memory buffer for its private stack. This is more than

enough for RMOD itself, as well as for the DOS exec function INT 21h,AX=4B00h.

There may be, however, exotic configurations where this stack is not enough,

typically if some stack-hungry TSR kicks in while RMOD is being active, or some

large interrupt handlers are used, etc. In such situation the 64-bytes stack

could be overflowed. RMOD copes with this by placing the stack right on top of

its command history buffer, and terminates the history string with a specific

signature. This way, if a stack overflow occurs and damages the command history

buffer, SvarCOM is able to easily detect it and invalidates the history buffer,

causing no risk of system instability. The user is notified about it, and the

only inconvenience is that he cannot recall the previous command.

Below the input buffer is RMOD's own memory signature, followed by its PSP.

This means that should the stack overflow become truly severe (more than 192

bytes and less than 326 bytes), RMOD signature will be overwritten and SvarCOM

won't be able to locate it, so a new copy of RMOD will be recreated. In case of

of a stack overflow that tries to use more than 326 bytes of memory, all hope

is lost and everything becomes possible.

===================================================================== EOF ====