Category : Alternate Operating Systems - Quarterdeck DesqView, CP/M, etc
Archive   : MULTIDOS.ZIP
Filename : MULTIDOS.PRN

 
Output of file : MULTIDOS.PRN contained in archive : MULTIDOS.ZIP


















__________________________________________
| |
| |
| MultiDos Plus (tm) 4.01 |
| |
| "Multitasking for DOS" |
| |
| Shareware Version |
| |
| |
| Copyright (c) 1991 |
| |
| by |
| |
| Nanosoft Inc. |
| 13 Westfield Road |
| Natick, MA 017 |
| |
| Voice (508) 651-0091 |
| FAX (508) 655-8860 |
| BBS (508) 650-9552 |
| |
|________________________________________|



























Table of Contents
-----------------



Introduction 1

System Overview 2

Getting Started 4

Command Line Options 5

Operator Commands 9

Foreground/Background Program Selection 20

Executing DOS Commands 21

Automatic Startup 22

Using MDDEBUG 23

The Application Program Interface (API) 29

Execution Control Functions 31

Resource Control Functions 40

Inter-Task Messaging Functions 45

Event Trigger Functions 49

Inside MultiDos Plus 51

Running with a LIM 4.0 EMS Driver 59

Using the Math Coprocessor 60

Useful System Data Structures 61

Software Interface for Terminal Communication 64

ISR Execution in LIM EMS 70

Enhancing the Task Context Switch 72

Performance Improvement Tips 74
















*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

INTRODUCTION
------------

MultiDos Plus is a multitasking extension to MS/PC-DOS which
enables you to run multiple DOS programs simultaneously. In order
to use MultiDos Plus you will need an IBM PC/XT/AT or true clone
running under DOS 3.0 or later operating system. You will also
need enough memory to contain the operating system, MultiDos Plus
(about 64K), and your application programs.

MultiDos Plus enables you to load multiple programs in your
system at the same time and have them all run concurrently using
a preemptive multitasking scheduler. The scheduler provides for
two different types of prioritized scheduling.

Programs running under MultiDos Plus have full access to DOS
services by means of standard DOS function calls. Users may use
the full range of DOS commands by running COMMAND.COM under
MultiDos Plus. In addition MultiDos Plus is compatible with most
"well behaved" off-the-shelf software available for the IBM-PC. A
set of commands are available to load and execute programs, set
program priorities, suspend/resume/abort programs and more. An
Application Program Interface (API) enables user written programs
to do the following:

o Change program priority
o Change time slice interval
o Run subroutines or functions as separate tasks
o Execute MultiDos Plus commands from within a task
o Communicate with other programs
o Suspend for a timed interval
o Synchronize resource usage using semaphores
o Wait on and signal events

MultiDos Plus supports the execution of programs in expanded
memory using the LIM 4.0 Expanded Memory standard. In most cases
the program need not be aware that it is running in expanded
memory.

MultiDos Plus can be run as a DOS SHELL program or as a
conventional EXE DOS program. MultiDos Plus and all programs
running under it may be started up automatically by means of a
startup file. With this feature the system can be started with no
operator intervention providing a platform for turnkey systems.

Programs running under MultiDos Plus can access the display and
keyboard by means of standard DOS or BIOS calls. Each program is
assigned a distinct virtual display, with only the "foreground"
program allowed to write to the real display. The user may bring
any program to the foreground by means of a hot key.

Usually a program and task are synonymous under MultiDos Plus.
However, it is possible for a task to create another task to run
in parallel and share the same code and data space. These are
referred to as internal tasks or threads and are described later
in more detail.





(1)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

SYSTEM OVERVIEW
---------------

MultiDos Plus is an EXE program and may be run from the DOS
command line like any other EXE program. You can exit MultiDos
Plus, and the system will revert back to its normal state.

On startup, MultiDos Plus takes control of the system by altering
various interrupt vectors to point to itself and also by
obtaining all the system memory. From this point on MultiDos Plus
controls the loading and execution of application programs.
MultiDos Plus can load programs in accordance with commands typed
at the keyboard, by other programs already loaded and running
under MultiDos Plus, or by commands in a special startup file.

MultiDos Plus provides true preemptive multitasking scheduling
with a choice of two different priority schemes. Under the
default scheduling scheme, CPU time slices are assigned to the
various programs in a round robin manner. Programs with higher
priority (lower priority number) receive more time slices than
programs with lower priority. The time-slice interval is based on
the timer interrupt in the PC and is approximately 55 msecs. You
can change the time-slice interval by making the appropriate
MultiDos Plus Application Program Interface (API) call or by a
command line parameter when MultiDos Plus is started.

MultiDos Plus provides an alternative scheduling scheme under
which the highest priority program in the system continues to run
until it is suspended waiting for some system resource to become
available. This scheduling scheme requires that programs be aware
that they are running in a prioritized multitasking environment.
It would be necessary for high priority programs to suspend
voluntarily, in order to permit other lower priority programs to
run. This scheduling scheme is necessary for many applications in
order to guarantee that certain high priority tasks get scheduled
in a predictable manner to handle real time events. Using the
alternative scheduling scheme requires careful design of the
overall system. For most normal situations the default scheduling
scheme should be adequate.

Since DOS is not reentrant, MultiDos Plus controls all access to
DOS system services on a first come first served basis. Tasks
need not concern themselves with the details of accessing DOS in
concert with other tasks and can make calls to DOS at any time.

Programs which cannot execute for any reason (waiting for
keyboard input, waiting for DOS or MultiDos Plus services,
operator suspended, etc.) are not assigned time slices.

MultiDos Plus also controls access to the visible display and the
keyboard. All programs under MultiDos Plus including MultiDos
Plus itself can be in one of two states -- foreground or
background. Only the foreground program can display on the
monitor or read from the keyboard. At any given time only one
program can be in the foreground state. If any of the background
programs writes to the screen using DOS or BIOS calls, the output
is actually written to an "invisible" screen associated with that
program. This screen becomes visible if the program is brought to



(2)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

the foreground. You can swap programs between foreground and
background by means of commands entered at the keyboard or by
means of MultiDos Plus API calls. It is important to note that
background programs do continue to run, even if you do not see
them do anything.

MultiDos Plus software consists of the following components:

MULTIDOS.EXE - the multitasking kernel.
MDBIO10.EXE - a display driver TSR which is automatically

loaded by MultiDos Plus on startup. This driver redirects
interrupt 10H display calls issued by background programs to the
appropriate virtual screens.

MDHLP - an ASCII text file containing online help information.
MDDEBUG.EXE - a monitor/debugger program useful for debugging
application programs running under MultiDos Plus.











































(3)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

GETTING STARTED
---------------

Install MultiDos Plus in your system by copying the distribution
diskette to any directory in your system. We recommend that this
directory be specified in your DOS PATH environment variable.

The distribution diskette includes a number of sample programs.
This section describes how to bring up MultiDos Plus and run two
of the sample programs.

Change your current disk and directory to the directory
containing the MultiDos Plus files. From the DOS prompt, perform
the following steps:

1) Type MULTIDOS
MultiDos Plus is started, and you should see the MultiDos
Plus prompt.
2) Type RM 128
This command assigns 128K of memory to the next task.
3) Type RU DEMO1
The DEMO1 program is loaded into a 128K memory block.
4) Type RM 64
Assign 64K of memory to the next task.
5) Type RU DEMO2
The DEMO2 program is loaded into a 64K memory block.

The ALTZ hot key (ALT and Z simultaneously pressed) may be used
to bring any program to the foreground. The ALTZ hot key also
switches you from an application program to the MultiDos Plus
command interpreter.

Typing a ? gives you a list of valid MultiDos Plus commands.




























(4)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

COMMAND LINE OPTIONS
--------------------

MultiDos Plus may be started by simply typing MULTIDOS when you
have a DOS prompt on your screen, or it may be automatically
started from the autoexec.bat file, or you may specify MultiDos
Plus to be the startup DOS SHELL. If MultiDos Plus is started
with no command line arguments, certain default parameters are
assumed for the system. These parameters may be modified by means
of optional command line arguments. Certain arguments require an
additional parameter. For example:

MULTIDOS /NALTZ /NUMTCB 5

This will start MultiDos Plus with the hot key disabled and the
number of programs in the system limited to 5.

The remainder of this section lists the command line options and
a detailed description of each. NOTE: All options begin with a
slash (/). Command line options or arguments may be entered in
upper or lower case.

/AUTO [startup file name]

The /AUTO option allows you to specify the path name of a file
which contains MultiDos Plus commands. If this option is not
specified, a file called AUTO.MTX is assumed to be the startup
batch file. If the startup batch file is not present, the system
comes up in the interactive mode permitting the user to enter
MultiDos Plus commands manually. See the Automatic Startup
section in this chapter for more information.






























(5)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

/EMMPGS [# of 16K EMM pages]

This option should only be used in a system with LIM 4.0 expanded
memory. Use the /EMMPGS option to limit the size of the LIM 4.0
expanded memory page frame created by MultiDos Plus for expanded
memory program loading. The value specified is the number of 16K
pages to allocate to the frame. If this option is not specified,
MultiDos Plus will create the biggest possible page frame for
program loading.


/MAPALL

This option should only be used in a system with LIM 4.0 expanded
memory. The /MAPALL option will cause MultiDos Plus to
permanently map the LIM page frame (usually at segment C000H) and
make this part of the conventional memory in the system. NOTE: Do
not use this option if you plan on running applications which use
LIM driver calls and explicitly map LIM memory. By default,
MultiDos Plus will map all other "holes" in the first megabyte as
conventional memory permitting access to a substantially larger
amount of conventional memory. This option has no impact on the
size and function of the MultiDos Plus Page Frame where
applications are loaded and executed.

/NALTZ

Use the /NALTZ option to disable the ALTZ hot key feature. This
option is most useful in turnkey systems where it may not be
desirable to allow the user access to the MultiDos Plus commands.
A turnkey system would use the FG command in the AUTO.MTX or
user-specified startup file to establish a foreground program at
system startup, preventing the system operator from using any
MultiDos Plus commands.

/NO10

The /NO10 command line option tells MultiDos Plus not to load the
MDBIO10.EXE display BIOS.

This option is useful for applications which only have one task
which will ever write to the display. It may also be useful if
your tasks cooperate with each other in their use of the display
by using a resource semaphore to control display usage.

Please note that RS-232 output redirection is performed by the
MDBIO10 module. If your application uses the COMM command to
specify I/O redirection, the /NO10 option will disable the
redirection of the display output.












(6)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

/NOCB

The /NOCB option will disable the checking for CTRL-C and CTRL-
BREAK during DOS writes. Use /NOCB to completely disable the
checking for these two key combinations. If this option is not
used and a CTRL-C is pressed during a DOS write to the CRT
display, the application may be aborted, or if if has an INT 23H
handler that ignores CTRL-C or CTRL-BREAK, an ugly unexpected ^C
may be displayed.

Using /NOCB makes it possible to use the ANSI.SYS functions to
format and control a display without risking that the operator
may enter a CTRL-C during a DOS display write.

/NOECHO

The /NOECHO option will inhibit the echoing of the commands in
the startup file.

/NOMAP

The /NOMAP option is available to disable the mapping of LIM
memory into empty spaces above the C000 segment. Use /NOMAP to
disable the mapping.

/NOPROMPT

The /NOPROMPT option will inhibit the display of the MultiDos
Plus command prompt when MultiDos Plus is in the foreground.

/NOREDIRECT

Use this option to prevent redirection of standard output and
input to and from the communication ports for tasks started with
the COMM command. This option is useful only for certain
specialized communication programs.

/NUMTCB [# of TCBs to allocate]

MultiDos Plus allocates a structure called a TCB for each task.
All the TCBs are initially allocated when MultiDos Plus first
starts. The default number allocated is 12 which is enough for 10
tasks. MultiDos Plus itself requires two TCBs for its own
internal use. The rest are available for user programs. Each TCB
occupies 224 bytes of memory. Allocating unnecessary TCBs
decreases the memory available for application programs. Also,
use of the /CTX option increases the size of each TCB by about
400 bytes. Up to 64 TCBs may be allocated.













(7)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

/PR [level]

MultiDos Plus provides two different prioritized scheduling
schemes. The /PR command is used to override the default scheme
of a simple round robin. The [level] is a value from 0 to 255
which is the priority level initially assigned to tasks when they
are loaded. The scheduling scheme invoked by the /PR option

allows the task with the highest priority to execute until a task
of greater priority is scheduled or the running task suspends
itself. Tasks of equal priority are still scheduled in a round
robin manner within their own priority level. NOTE: Both
scheduling schemes permit the use of 256 priority levels.

See the section on Inside MultiDos Plus in Chapter V for more
details on the two scheduling schemes.

/TSL [interval designator]

The /TSL option will tell MultiDos Plus to preset the time-slice
interval at startup. If this option is not specified, the default
interval will be set to 55 milliseconds. The [interval
designator] is a single character and must be one of 2, 4, 8, A
or B. See the API function code 10 for more details on the
effects of changing the time-slice interval. The following table
shows the relationship between the /TSL parameters and the length
of the time slice.

Parameter Interval Length (milliseconds)
2 27.5
4 13.75
8 6.88
A 3.44
B 1.72

Any other values will result in an error message, and MultiDos
Plus will terminate.

























(8)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

OPERATOR COMMANDS
-----------------

A set of commands called Operator Commands control the loading
and execution of application programs under MultiDos Plus. These
commands are used to load, execute, abort, suspend, and restrict
the memory usage of the programs. A special startup file may also
contain these commands to automatically load and execute programs
when MultiDos Plus is started.

Commands may be entered in upper or lower case, and you must
terminate each command with a carriage return.

It is possible for a running task to issue operator commands by
using the Application Program Interface. See the section on
Execution Control Functions in Chapter IV for details.The
commands are grouped into four sections. The commands in the
first section are those you may need to specify before loading
and executing a program. All commands in this section are
optional since they all have default values associated with them.
The second section consists of a single command (RU) which is
actually used to load the program. The third section deals with
commands to control the execution of programs, and the fourth
section contains miscellaneous commands.

Preload Commands
----------------

As noted earlier, all commands in this section are optional and
are used to override defaults used in loading a program under
MultiDos Plus. All parameters revert back to the default state as
soon as a program is loaded. Some commands in this section are
provided only to undo the effects of a previous command and are
infrequently used.

AM - Additional Memory

When MultiDos Plus loads a program, the minimum amount of memory
required to load the program is computed. If the AM command is
used, the value specifed is added to the minimum amount of memory
required to load the program. Enter the command using the
following syntax:

AM

The parameter is a decimal
value in units of 1,024 bytes.

CD - Change the Current Directory

The CD command is provided so that the user can change the
current working directory for MultiDos Plus. Other DOS internal
commands are available only if COMMAND.COM is loaded under
MultiDos Plus.







(9)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

CMP - Program Uses Conventional Memory Only

Use the CMP command to undo the effects of a previous XMP
command. The CMP command indicates that the next loaded program
will not make any calls to a LIM 4.0 expanded memory manager. CMP
is the default unless an XMP command has been executed. NOTE:
This command has no bearing on whether the program runs in
expanded memory or not but only instructs MultiDos Plus that the
program will not use expanded memory on its own.


COMM - Specify the CRT Port for the Program

Use the COMM command to specify a CRT communication port for the
program's standard input and output. This will cause MultiDos
Plus to redirect the program's standard keyboard and display data
to and from the communications port. The command syntax is:

COMM

The parameter specifies the communication port where the
CRT is connected. A value of 1 designates COM1, value of 2 COM2,
etc. The number of COM ports supported depends on the
communications driver in your system. The is a
hexadecimal value used to initialize the port when the task is
loaded and is used to set the baud rate, parity, etc. See the
Initialize Port function under the Software Interface for
Terminal Communication section in Chapter V for more information.
The value corresponds to the contents of register AL
documented in that section.

It is IMPORTANT that the NANSI command be executed for the task
after the task is loaded. The built-in ANSI.SYS functions in
MultiDos Plus do not support programs running on CRTs connected
to your PC. Therefore, it is necessary to disable this function
for programs running on CRTs.

DI - Allocate Background Display Memory

When the next task is loaded by the RU command, the task will be
given a display memory for background display output. This
command is rarely needed since this is the default mode. This
command is provided so that you can undo an ND command typed by
mistake.

















(10)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

IRQ - Associate the LIM Map of a task with an External Interrupt

The IRQ command tells MultiDos Plus that when an external
interrupt occurs the LIM map associated with the program should
be mapped before the ISR associated with the interrupt is
invoked. When the ISR returns, the original map is automatically
restored. This command is required only for expanded memory
programs performing asynchronous I/O with external devices.

The syntax for the IRQ command is:

IRQ

is a number from 1 to 15 and indicates the hardware
interrupt to be mapped. A value of 1 will map interrupt vector 9
which is normally the keyboard hardware interrupt. Values 1 thru
7 map to vector numbers + 8, and values 8 thru 15 map to
vector numbers + 68H.

Note: See the appendix describing the IRQ command line option
for more MultiDos Plus features for running ISRs in LIM memory.

LC - Load in Conventional Memory

The LC command tells MultiDos Plus to load the next program into
conventional memory. On systems with no expanded memory this is
the default. If a LIM 4.0 board and driver are present in your
system, programs are loaded in expanded memory by default. Use
this command only if you have LIM 4.0 in your system and you wish
to load your program in conventional memory.


LO - Program Execution Starts Only After Foreground Selection

By default, programs loaded under MultiDos Plus are not started
until the program is brought to the foreground the very first
time. The XQ command, described later, permits a program to start
running as soon as it is loaded. The LO command is provided to
undo a previous XQ command.

LX - Load Program in Expanded Memory

Use the LX command to reverse the effect of an LC command. The LX
command tells MultiDos Plus to load the next program into
expanded memory. This command is only meaningful if your system
has expanded memory and a LIM 4.0 driver. If LIM 4.0 is present,
the default is to load programs into LIM memory unless an LC
command is entered.













(11)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

ND - No Display Memory

If the next task to be loaded will not perform any output to the
screen, the ND command can be entered to inhibit the allocation
of a background display memory buffer for the task. This will
save either 4K or 16K depending on the display adapter. If the ND
command is used, the XQ command must also be used in order to
start running the program. This is necessary because programs
with no display memory cannot be brought to the foreground.
Programs with no display memory will not show up when the ALTZ
hot key is used.

RM - Reserve Memory

When MultiDos Plus loads a program, it automatically determines
the amount of memory to assign to the program. This is done by
examining the size of the program file and, in the case of EXE
programs, the information in the EXE header. However, many
programs request additional memory by making the DOS memory
allocation calls. Programs written in high level languages may do
so for stack and heap space even if you find no explicit memory
calls in your program. It is important to note that this memory
is allocated only from the initial memory reserved for the
program. Therefore, many programs may not operate correctly
unless sufficient memory is reserved for the program. The amount
of memory needed by a program may be determined by reserving a
large amount of memory and checking the memory usage of the
program by using MDDEBUG.

The syntax for the RM command is:

RM

For example:

RM 128

Use RM 128 to create a 128K memory partition for the next loaded
program. The memory is not reserved until the program is loaded.
If there is not enough memory to create the partition when the RM
command is issued, no error message will be issued. The error
message will be issued when the command to load the program is
executed.

NOTE: RM and AM commands perform similar functions. RM lets you
specify total size needed. AM specifies additional memory.















(12)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

SBK - Suspend Task in the Background

The program will run only when it is in the foreground state. A
typical use for this command is to prevent programs which write
directly to the display memory from interfering with the
foreground display. The foreground display is preserved between
foreground to background and back to foreground switches.

XMP - Program Uses Expanded Memory

Use the XMP command to indicate that the program about to be
loaded will use expanded memory. With this option, MultiDos Plus
will save the LIM map context at the end of every time slice for
the program and restore it when the program is ready to run. Use
of this option has no bearing on whether the program is loaded in
expanded or conventional memory. It only instructs MultiDos Plus
that the program will make LIM EMM calls on its own.

XQ - Start Execution of Next Program Immediately After Loading

The XQ command will cause the next program loaded to start
running immediately after it is loaded. If this command is not
used, a program will start running only when it is brought to the
foreground for the first time. If you use the ND command, you
must use the XQ command before loading the program.

Load Program
------------

RU - Load the Specified Program into Memory

The RU command is used to actually load a program into memory and
ready it for execution. The program is loaded using the
parameters established by previously entered commands like RM,
XQ, ND and DI. After the program is loaded, the parameters are
reset to their initial default values. A loaded program becomes a
task under MultiDos Plus.

The following is the basic syntax of the RU command:

RU

The are the command line arguments that
would normally be supplied to a program if it were executed
directly from DOS.
















(13)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

MultiDos Plus does not require you to type RU. You may load a
program simply by typing the name of the program as long as the
program name does not conflict with any MultiDos Plus command.

eg. RU PROG ARG1 ( or PROG ARG1 )

If the name of a program conflicts with a MultiDos Plus command
and the RU is not specified, the MultiDos Plus command definition
takes precedence.

The program name may be any valid DOS path name of a COM or an
EXE file. If a simple file name is specified, the DOS environment
PATH variable is used to locate the program.

Once loaded, the program name is also used for the task name. The
first seven (7) characters up to the period (.) of the simple
file name are used for the task name. If a file with a path name
of \ABC\DEFGHIJK.EXE were loaded, the task name would be DEFGHIJ.
The directory specification of \ABC\ is dropped and so is the K.
The .EXE or .COM extension is never included. If the RU is not
specified, the name is also converted to upper case.

The standard input/output redirection and pipes normally
supported by the DOS COMMAND.COM program are not available when
running under MultiDos Plus.




































(14)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Execution Control Commands
--------------------------

AB - Abort Task

Abort the named task. The task is actually aborted the next time
it gets scheduled for execution. If the task is suspended for any
reason (waiting for keyboard, waiting for a semaphore, etc.), it
will be aborted only when it gets out of the suspended state.

The syntax for the AB command is:

AB

When MultiDos Plus aborts the task, the memory reserved for the
program is returned to the free memory pool.

CAUTION: If the task has "hooked" into any interrupt vectors, the
consequences of leaving interrupt vectors pointing to unused
memory may cause unexpected results.

FG - Move Background Task to Foreground

Use the FG command to bring the named task into the foreground.
The syntax for the FG command is:

FG

If the task has just been loaded and is waiting to begin
execution, it will begin execution as soon as it has control of
the foreground display.

Information on possible uses of the FG command is given in the
sections on Foreground/Background Program Selection and Automatic
Startup in this chapter.

An additional feature of the FG command is the ability to bring
the previous foreground task back into the foreground without
having to know the task's name. If an astrisk is used in place
of the task name, the previous foreground task is brought back to
the foreground. This function is most useful when a task is done
with the foreground and wants to switch itself to the background,
restoring the task that was previously in the foreground. The
task can submit an FG command, using INT 15H function code 15, to
MultiDos Plus.


GO - Resume Execution of a Task

A task which was previously suspended using the SS command can be
restarted at the point where it was suspended. The syntax for the
GO command is:

GO

The task is removed from the Suspend queue and placed on the
Ready queue.




(15)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

PR - Set or Display Task Priority

Each task in the system is assigned an execution priority. The
priority determines how often the task is given a slice of time
by the task scheduler. The lower the priority number, the more
frequently the task will be scheduled.

The PR command allows a task priority to be set to a value from 0
to 255. If no value is specified in the command, the current
priority of the task is displayed. If you do not set any
priority, loaded tasks will default to priority 0 or the level
specified by the /PR command line option.

The following is the syntax of the PR command:

PR

SS - Suspend Task

The execution of the specified task is suspended until a GO
command is issued to reactivate the task. The syntax for the SS
command is:

SS

It is important to note that even though a task is marked for
suspension, it may not be suspended immediately. Tasks waiting
for keyboard input, semaphores, events and messages are not
suspended until their current requests are satisfied. A task
performing a DOS function call is not suspended until the DOS
call is complete.






























(16)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Miscellaneous Commands
----------------------

ANSI - Activate ANSI.SYS for Task

The ANSI command activates the ANSI.SYS driver functionality
built into MultiDos Plus for the specified task. ANSI.SYS can be
enabled or disabled on a per task basis. The syntax for the ANSI
command is:

ANSI

The is the name of the task to be activated. The
default when a task is loaded is to have ANSI.SYS enabled. If a
task should not have the ANSI.SYS functionality activated for it
(for example, a task loaded with the COMM option), the NANSI
command can be used to disable this functionality.


ASG - Define Foreground Switch

The ASG command tells MultiDos Plus to enable certain keys to
bring a task to the foreground immediately without using the ALT
Z sequence. The PC keyboard function keys and ALT keys may be
used for this purpose. For example, the F1 function key may be
set to always bring the COMMAND task to the foreground. Once a
key assignment has been made, the task may be brought to the
foreground any time the key is pressed. The way to make this
assignment is to use the ASG command.

The ASG command allows the assignment of up to 10 keys to 10
tasks. The syntax for the ASG command is:

ASG [ ]

If the ASG command is entered without any arguments, a list of
current key assignments will be displayed. Each of the 10
entries in the assignment table is listed in the order: index,
scan code, task name.

The arguments specify a mapping between a specified scan code and
a task name. The scan code must be specified as a decimal
number. The ASG command to map the COMMAND task to the F1
function key would be:

ASG COMMAND 0 59

This command would set the first entry in the assignment table to
map the task COMMAND to scan code 59 which is the F1 function
key.











(17)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

The decimal values for the function key scan codes are:

Key Normal Shifted Ctrl Alt

F1 59 84 94 104
F2 60 85 95 105
F3 61 86 96 106
F4 62 87 97 107
F5 63 88 98 108
F6 64 89 99 109
F7 65 90 100 110
F8 66 91 101 111
F9 67 92 102 112
F10 68 93 103 113

The scan codes for other function keys and the Alt keys may also
be used.

If an astrisk is used in the place of a task name, the key
assignment has a different meaning. Whenever that key is
pressed, the previous foreground task is brought back to the
foreground. For example:

ASG * 0 61

Whenever the F3 function key is pressed, the previous foreground
task will be brought back to the foreground.

The value after the task name is the assignment table index and
can range from 0 to 9. Entries may be placed in any order in the
table. When a key is pressed, the entry with a matching scan code
closest to the begining of the table is used.

The /NALTZ command line option will not disable the single key
task selection feature.


BAT - Batch Command Execution

The BAT command will tell MultiDos Plus to execute commands from
an ASCII text file as if they were entered from the keyboard.
The format is:

BAT filename

where filename is any DOS pathname. All commands in the file are
executed by MultiDos Plus before any other commands (i.e. INT
15H, function 15) are executed. No other task's child process
requests are processed until the BAT command is finished.

A BAT batch file can also contain embeded batch commands.










(18)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

ECHO - Echo Text

Any text following the ECHO keyword is echoed to the display.
This command may be useful in AUTO.MTX files to display messages
during a turnkey system startup. The following line:

ECHO This is a test

will display "This is a test" on the CRT display.

The command "ECHO *" will clear the display.


EXIT - Terminate MultiDos Plus

This command terminates MultiDos Plus and restores the system to
its original state. All running tasks are immediately terminated.
Caution should be used when using this command as some tasks may
have taken certain interrupts during execution, and the EXIT
command will not restore the interrupt vector to its original
state.

The EXIT command has no effect if MultiDos Plus is running as a
DOS SHELL.

NANSI - Disable ANSI.SYS

Use the NANSI command to disable ANSI.SYS for a task. When a task
is loaded, the default is to have ANSI.SYS in effect for a task.
The ANSI.SYS functions can be reactivated using the ANSI command.
The syntax for the NANSI command is:

NANSI

is the task name of the task for which ANSI.SYS is to
be disabled.


REM - Remark Command

The REM command will allow the addition of remark statements to
automatic startup files to document the content of the file. Any
characters after the REM are completly ignored. The following
are examples of some REM statements:

REM This is a test
REMthisisatest
REMARKABLE application written by Jack Spratt













(19)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

FOREGROUND/BACKGROUND PROGRAM SELECTION

As described earlier, there is always only one foreground
program; and the rest of the programs are in the background. You
can swap programs between foreground and background by doing ALTZ
(pressing ALT key and Z key at the same time). If you do ALTZ
when you have an application program in the foreground, your
foreground program will go to the background; and MultiDos Plus
will come to the foreground.

If you do ALTZ with MultiDos Plus in the foreground, you will see
the name of one of your background programs. At this point you
will be invited to either hit a return or do another ALTZ.
Hitting the return will banish MultiDos Plus to the background
and bring the named program to the foreground. Doing another ALTZ
instead of hitting the return will list the next program (if any)
in the background.

Another method of switching programs between the foreground and
the background is to assign hot keys using the ASG MultiDos Plus
operator command. Read the ASG description in the Operator
Commands section for more information on this feature.

A program loaded without a background display memory may never be
brought to the foreground. For this reason, programs without
display memory will not have their name shown when the ALTZ task
list is being displayed.

Another method of establishing the foreground program is to use
the MultiDos Plus FG command. This command can be invoked
directly from the MultiDos Plus command line or another program
can issue the command using the API function to invoke MultiDos
Plus commands from a program.




























(20)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

EXECUTING DOS COMMANDS

A set of DOS commands, known as DOS internal commands, are built
into the DOS command processor, COMMAND.COM. This includes
commands to list a directory, copy files, delete files, etc.
Also, the ability to execute batch files requires COMMAND.COM.

MultiDos Plus users who require these features should, therefore,
first load and execute COMMAND.COM. The amount of memory to
reserve for the COMMAND task depends on what you intend to do
with the command processor. Reserving 64K is adequate for
executing internal commands. Running batch files which invoke
other programs may require you to reserve sufficient memory for
their execution as well as the memory needed to execute
COMMAND.COM.














































(21)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

AUTOMATIC STARTUP
-----------------

Many applications require startup with little or no human
intervention (a turnkey system). MultiDos Plus has all the
features neccessary to be used in a turnkey system.

To start MultiDos Plus automatically, modify the AUTOEXEC.BAT
file to invoke MULTIDOS.EXE. NOTE: The command to start MultiDos
Plus should be the very last command in the batch file.

Now create a standard ASCII text file with the MultiDos Plus
commands needed to load and begin execution of your application
programs. Although the name of the file is not important, if you
name it AUTO.MTX and place it in the current directory, MultiDos
Plus will automatically look for it and execute the commands
placed therein. If you choose a different file name or place the
file in a different directory, use the /AUTO command line option
to tell MultiDos Plus where the file is located.

Normally, MultiDos Plus will echo each command it reads from the
AUTO.MTX file just before it executes the command. You may use
the command line option /NOECHO to suppress the echoing of those
commands. You may also want to use the /NOPROMPT option to
inhibit the display of the MultiDos Plus command prompt.

In a turnkey system you may want to disable the ALTZ hot key
facility. If your system operators do not have access to the
MultiDos Plus command level, they will not be able to abort
tasks, load other programs, or any other nasty things you may not
want them to do. Use the /NALTZ command line option to disable
the ALTZ facility. The /NALTZ option will disable the ALTZ before
any other operation occurs.

Since you will probably want to disable the ALTZ facility, you
will need an alternative method of starting your programs. Also,
you will probably want one specific task to become the first
foreground task. The XQ command will force programs to begin
execution without being brought to the foreground. The FG command
should be the last command in the file and will establish the
desired foreground program. Read the description of the ASG
Operator Command for additional task foreground selection
methods.

Before each program is loaded, be sure to specify the XQ command
so that the program will begin execution immediately after
loading. This way the program need not be brought to the
foreground to initiate its execution. This command would also be
needed to start any programs which have no display.

The very last command in the AUTO.MTX file should be the FG
command to start the foreground task. The foreground task need
not be loaded with the XQ command option. The FG command will
cause the task to begin execution.







(22)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

USING MDDEBUG
-------------

Included with the MultiDos Plus software is a program named
MDDEBUG which may be used to observe the state of the system
during execution. For example, the execution context of a
program, its PSP, environment and other parameters can be
examined. MDDEBUG will also allow you to display memory, system
variable contents, check resource ownership, and list the tasks
in the system. The following describes how to execute MDDEBUG and
its various commands. Used in conjunction with an hardware
emulation debug facility, MDDEBUG is invaluable for debuging a
multitasking application. If you are using a system with a "dumb"
terminal connected, you can use the COMM command to run MDDEBUG
from the terminal if you have a communication driver installed as
described in the Software Interface for Terminal Communication
section in Chapter V.

Note that MDDEBUG makes reference to tasks and not programs.
Although a program loaded under MultiDos Plus becomes a task, it
is possible for a program to contain more than one task. MDDEBUG
will show all the tasks runing under MultiDos Plus. See the API
functions in Chapter IV for more information on creating
"internal" tasks or "threads".

To run MDDEBUG, just type:

MDDEBUG

at the MultiDos Plus command prompt. If your system is configured
with LIM 4.0 expanded memory, use the LC command to ensure that
it is loaded into conventional memory. It must run in
conventional memory in order to access data in programs loaded in
LIM memory.

Use ALTZ to select and run MDDEBUG.

























(23)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

You will be presented with a signon message and the MDDEBUG
prompt which looks like:

MDDEBUG>

You may now enter one of the following single character commands.
Enter a ? to get on-line help.

(C)heck Message Queue
(D)ump Memory
(E)nvironment of a Task
(F)ree Memory for Task
(H)andles and File Names for a Task
(I)ssue a Message to a Message Queue
(L)ist Task Names and Numbers
(M)ultiDos Command
(P)SP Information of a Task
(Q)uit
(R)esource Semaphore Owners and Requestors
(S)ystem Block
(T)ask Status
(X)panded Memory Information

When a command is entered, the operator is prompted for any
additional parameters required to process the command. The
command is executed, and the MDDEBUG prompt is again displayed.

The remainder of this chapter describes the commands in detail.

































(24)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

(C)heck Message Queue

The "C" command is used to check the contents of a message queue.
When you press the "C" key, you will be asked to enter a queue
number. The number must be a decimal value between 0 and 63. The
status of the message queue is then displayed. Tasks waiting on
the queue, if any, are listed. If any messages are on the queue,
the contents of the messages are displayed. All messages are
displayed in both hexadecimal and ASCII.


(D)ump Memory

The "D" command is used to display the contents of memory in the
system. When you press the "D" key, MDDEBUG will ask for a memory
address to display. If the address falls in the LIM expanded
memory page frame, the number of the task whose memory is of
interest is requested. Use the "L" command to obtain a list of
tasks and their numbers. MDDEBUG will make sure the task is
mapped in during the display process.

When the address of the memory to be displayed is requested, it
must be entered in the form SEGMENT:OFFSET and the values entered
must be hexadecimal.

Memory is displayed in 32-byte chunks. Each line displayed shows
16 bytes: first in hexadecimal format and then in printable
ASCII. If a byte is not a printable ASCII character, it is
displayed as a period (.). After the 32 bytes are displayed, a
prompt is issued for another memory address. If a blank line is
entered, the next 32 bytes are displayed. If an address is
entered, 32 bytes are displayed starting with the new address.


(E)nvironment of a Task

The "E" command is used when you need to display the environment
of a task. When you press the "E" key, the task number will be
requested. Use the "L" command to obtain a list of tasks and
their numbers. Enter the number of the task in which you are
interested. The individual environment strings for the task will
then be displayed. The path name of the task's program file will
be displayed last.

(F)ree Memory for Task

The "F" command is used to display the memory allocation
information of a task. When you press the "F" key, the task
number will be requested. Use the "L" command to obtain a list of
tasks and their numbers. Both the task's available and in-use
memory is displayed. The starting paragraph of each memory block
and the size of the block are shown. The starting paragraph is
displayed in hexadecimal, and the block size is displayed in
decimal. The size is the number of bytes (not paragraphs).







(25)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

(H)andles and File Names for a Task

The "H" command is used to display the file handles in use by a
task and the name of the file associated with the handle. When
you press the "F" key, you will be asked to provide the number of
the task. Use the "L" command to obtain a list of tasks and their
numbers. The task name and the maximum number of files the task
may have open is displayed. The file handle numbers are displayed
next, one handle to a line. Following each handle number is the
DOS file name associated with the handle. Only the name of the
file is displayed. The directory and disk of the file are not
provided.


(I)ssue a Message to a Message Queue

The "I" command is used to place a text message on a selected
message queue. When you press the "I" key, you will be prompted
for the queue number and then for the text of the message. The
message will be placed on the specified queue. The message is
limited to text characters entered from the keyboard.


(L)ist Task Names and Numbers

The "L" command is used to request a list of the names and
numbers of all the tasks in the system. When you press the "L"
key, all the tasks (and their associated numbers) in the system
are listed, one per line. Each task name is preceeded by a number
which is its task number. The task number is used to reference a
specific task in many of the other MDDEBUG commands. Following
each task name is a number which is the priority of the task.


(M)ultiDos Command

The "M" command is used to send MultiDos Plus an Operator Command
from MDDEBUG. When you press the "M" key, you will be asked to
enter a command string. Up to 80 characters may be entered,
terminated by a carriage return. The command string is sent to
the MultiDos Plus command interpreter, and the string "Command
sent" is displayed acknowledging that the command was sent. The
command may be any valid MultiDos Plus command. Any error
messages are displayed on the foreground display. See the API
function code 15 (Execute a MultiDos Plus Command) in Chapter IV
for more information on the effects of sending MultiDos Plus
commands from a task.














(26)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

(P)SP Information of a Task

The "P" command is used to display information from a task's
Program Segment Prefix (PSP). When you press the "P" key, you are
asked for a task number. Use the "L" command to obtain a list of
tasks and their numbers. Information contained in the selected
task's PSP is displayed. For more information on the contents of
the displayed fields refer to your DOS Technical Referance
manual.


(Q)uit

The "Q" command is used to terminate execution of MDDEBUG. When
you press the "Q" key, execution is terminated immediately.


(R)esource Semaphore Owners and Requestors

The "R" command is used to display a snapshot of the MultiDos
Plus Resource Semaphores. When you press the "R" key, the
Resource Semaphore number, current owner task name and any
requesting task's names are displayed for all the Resource
Semaphores having any activity.


(S)ystem Block

The "S" command is used to display the contents of the MultiDos
Plus System Block data structure. When you press the "S" key, the
contents of the System Block will be displayed. See the section
on Useful System Data Structures in Chapter IV for a description
of the fields in the System Block.


(T)ask Status

The "T" command is useful for obtaining information about a
running task. When you press the "T" key, you will be asked for a
task number. Use the "L" command to obtain a list of task
numbers. Once you enter the task number, the information about
the task will be displayed. The following describes the meaning
of the displayed information:

The Task Name is the seven (7) character name of the selected
task. Following the name is the priority of the task and the
ANSI.SYS emulation state. If ANSI.SYS emulation is turned off for
the task, the state will be 0. Otherwise it will be non-zero.

The next line displays the SS and SP registers for the task
followed on the next line by the remainder of the task's
registers.

The environment segment from the task's PSP is displayed in
hexadecimal followed by the communications port number of the
task. If the task is not communicating with an RS-232 terminal,
the port number will be zero.




(27)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Twelve fields from the task's TCB are displayed, four to a line.
They are CURIRQ, DISMEM, TOPMEM, TSKSEG, EMSPTR, EMMPRG, EMMHND,
ALTMAP, PARTCB, TSKPID, DISTYP, and ADDR68. All values are
displayed in hexadecimal.

Field Description

CURIRQ value set for task by the IRQ command
DISMEM display memory segment
TOPMEM tasks top of memory in K
TSKSEG PSP segment for the task
EMSPTR segment of LIM map
EMMPRG task uses LIM flag
EMMHND LIM handle for task
ALTMAP LIM alternate map set for task
PARTCB parent tasks TCB offset
TSKPID current DOS process ID
DISTYP 0 = MDA, 1 = CGA
ADDR68 base i/o address of video controller

The next line displays the current display mode for the task, the
number of display columns, and the length of the display memory.

The following line contains the current cursor positions for the
four display pages (if MDA, only the first position is valid),
and the next line displays the current active display page and
the current cursor mode. The MDBIO10 driver only updates this
information for background tasks. The foreground task information
is kept in the low memory BIOS data area.


(X)panded Memory Information

The "X" command is used to display information about your
system's expanded memory. When you press the "X" key, the raw
page size, number of alternate register sets, the context save
area size, and the number of available 16K EMS pages are
displayed. Refer to your LIM 4.0 driver specification for a
complete description of these values. If no expanded memory is
configured in your system, the message "No expanded memory
present" will be displayed.




















(28)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

THE APPLICATION PROGRAM INTERFACE (API)
---------------------------------------

Programs can interact with each other or control their own
execution by means of calls to the Application Program Interface
(API). This is done through the software interrupt 15 (INT 15H).
A program must load the function code of the function to be
performed into the AH register and any required parameters in the
proper registers and execute an INT 15H instruction. If a
function code not recognized by MultiDos Plus is used in register
AH, control is passed to the interrupt handler present before
MultiDos Plus was loaded.

NOTE: No registers are destroyed unless specifically noted.

This chapter has been divided into four sections: Execution
Control Functions, Resource Control Functions, Inter-Task
Messaging Functions, and Event Trigger Functions. The function
descriptions in each section are organized in function code
order. The following tables lists the function codes for each
section.

Execution Control Functions

Function Code Definition
0 give up time slice
3 suspend task for interval
7 spawn internal task
8 terminate internal task
9 change priority
10 change time slice interval
11 force display output to real video memory
12 restore old video memory
13 turn off time slicing
14 turn on time slicing
15 execute a MultiDos Plus command
17 turn off ALTZ
18 turn on ALTZ
19 return TCB address
20 return foreground/background flag
21 return pointer to System Block
22 initialize ADOS
23 map interrupt request
24 unmap interrupt request
25 unmap all interrupt requests
















(29)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Resource Control Functions

Function Code Definition
1 get resource semaphore
2 release resource semaphore
16 test a resource semaphore
26 map semaphore name to number
27 get resource semaphore by name
28 release resource semaphore by name
29 check if resource semaphore available by name

Inter-Task Messaging Functions

Function Code Definition

4 send message
5 check queue for a message
6 get message

Event Trigger Functions

Function Code Definition

30 event semaphore functions
30-0 clear event counter
30-1 signal event
30-2 wait for event

NOTE: Most compiler systems available for DOS have a facility for
invoking software interrupts. See the technical reference manual
of your particular compiler for details.






























(30)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

EXECUTION CONTROL FUNCTIONS
---------------------------

The Execution Control Functions are provided to give tasks a
means of controlling various aspects of execution. Functions are
provided for a task to control its own execution, to examine and
alter system wide parameters, and to control the execution of
other tasks. Several of the functions defined here must only be
used by MultiDos Plus. They are only listed for completeness.



Give Up Time Slice

Function Code = 0

Entry:
AH = function code

The task making this call wishes to give up its time slice. The
next ready task is given the remainder of the time slice.

Tasks which are performing certain types of timing loops should
use this function to yield processor time to other tasks in the
system.

If the /PR command line option was specified when MultiDos Plus
was started, and the highest priority task in the system issues
this function, and there are no other tasks of equal or greater
priority, control will return immediately to this task.


Suspend Task for Interval

Function Code = 3

Entry:
AH = function code
DX = number of time ticks to suspend

The task making this call is suspended for the specified number
of time ticks. A time tick is the basic time-slice interval. Be
aware that this value can be changed by using function code 10
(Change Time Slice Interval).

This function should be used by tasks which want to delay
execution for a specific period of time. The normal practice of
executing a loop to maintain timing is not recommended in a
multitasking environment. This technique will waste processor
time which can be productively used by other tasks.

If the /PR option was invoked, this function can provide very
accurate execution timing for high priority tasks. High priority
tasks should use this function to yield processor time to lower
priority tasks when they no longer need it.






(31)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Spawn Internal Task

Function Code = 7

Entry:
AH = function code
BX = CS register of new task
CX = IP register of new task
DX = stack size for new task in paragraphs

Exit:
AH = 0 if no error
1 if no free task control blocks
2 if no free memory for the new task's stack

A new task, called an internal task, is created and will start
executing at the specified CS:IP. Control is returned immediately
to the calling (parent) task which continues execution. The
memory for the stack, specified in DX, is obtained from the
parent task. The parent task must, therefore, have sufficient
free memory to start an internal task.

See the section on Inside MultiDos Plus in Chapter V for more
details on the operation of internal tasks.


Terminate Execution of an Internal Task
Function Code = 8

Entry:
AH = function code

An internal task terminates itself by invoking this function
call. Its stack space (originally obtained from its parent task)
is returned to the free memory pool of the parent task.

It is important that an internal task terminate itself using this
function and not one of the DOS termination functions.


Change Priority
Function Code = 9

Entry:
AH = function code
AL = new priority

Change the task priority. Any value between 0 and 255 is allowed.

The meaning of the priority depends on whether or not the /PR
command line option was specified when MultiDos Plus was started.
See the /PR command line option in Chapter II for more
information. The Inside MultiDos Plus section in Chapter V also
has more information on task priority.







(32)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Change Time Slice Interval
Function Code = 10

Entry:
AH = function code
AL = 00H = 55 milliseconds (default)
80H = 27.5 milliseconds
40H = 13.75 milliseconds
20H = 6.88 milliseconds
10H = 3.44 milliseconds
08H = 1.22 milliseconds

This function changes the length of the basic time-slice
interval. Unless specifically stated, MultiDos Plus begins
execution with a default time-slice interval of 55 milliseconds.
This is the normal interval programmed into the timer for
interrupt 8. MultiDos Plus uses interrupt 8 to preempt running
tasks.

Although MultiDos Plus will change the interrupt interval for
interrupt 8, a count of the number of times the interrupt has
occured is maintained and after 55 milliseconds has elapsed, the
interrupt 8 handler, which was present before MultiDos Plus, is
executed. This preserves the BIOS time-of-day and any other
timing required by your PC BIOS and TSR's.

When MultiDos Plus terminates execution, the timer is reset to
its original 55 millisecond interval.

Force Display Output to Real Video Memory
Function Code = 11

Entry:
AH = function code

The pointer to the task display memory is forced to point to the
real hardware display memory. The old pointer is saved for the
task and may be restored using function code 12 (Restore Old
Video Display Memory).

This function is useful if a task wants to force a message to the
CRT display regardless of its foreground/background state.

In order for this function to work properly, the invoking task's
display mode must be the same as the foreground task's mode.
Also, the text is displayed at the current cursor position
defined for the issuing task which may not be the same as the
cursor position of the foreground task.

If a task issues this function and writes to the display when it
is a background task, the displayed data will be saved to the
foreground task's background virtual display if it is switched to
the background.








(33)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Restore Old Video Display Memory

Function Code = 12

Entry:
AH = function code

The old video display memory pointer saved by function code 11
(Force Display Output to Real Video Memory) is restored.

NOTE: Function codes 11 and 12 are useful if a background task
wants to display a message in the foreground display.

This function must not be called unless a function code 11 has
been executed by the task.

The execution of function codes 11 and 12 does not affect the
display of a foreground task.


Disable Multitasking

Function Code = 13

Entry:
AH = function code

When the timer interrupt signals the end of the time slice for
this task, MultiDos Plus gives the next time slice to the same
task. This effectively turns off the time slicing. The task will
continue to receive all the CPU time until a function code 14
(Enable Multitasking) is executed.

This function, which disables multitasking, is useful for
processing time-critical events. It may also be useful while
executing regions of nonreentrant code shared by multiple tasks.
A critical region of code would be bracketed by a function code
13 and a function code 14 which enables multitasking.

Hardware interrupts remain enabled even when multitasking is
turned off.


Enable Multitasking

Function Code = 14

Entry:
AH = function code

This function reverses the effect of function code 13 (Disable
Multitasking). If function code 13 is issued and is not followed
by function code 14, no other task would receive time slices.

See function code 13 for more information on disabling and
enabling multitasking.





(34)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Execute a MultiDos Plus Command

Function Code = 15

Entry:
AH = function code
DS:BX = pointer to null terminated command string

The string pointed to by DS:BX is executed as a MultiDos Plus
command as if the command had been typed in at the MultiDos Plus
prompt. The string must be terminated with an ASCII null
character and must not include a carriage return or line feed at
the end. Any lower case characters in the command are converted
to upper case, up to the first space, before the command is
executed. The converted characters are placed back into the
command buffer. You can use this call to start other programs,
suspend programs, etc.

When a task invokes this function, the task is suspended and
placed in a First-In-First-Out (FIFO) queue. The queue is
serviced by MultiDos Plus periodically. When MultiDos Plus finds
a request to execute a command, the command is executed before
the task is allowed to resume execution. If several tasks issue
requests at the same time, the requests are serviced in a FIFO
order.



Turn Off ALTZ Toggle

Function Code = 17

Entry:
AH = function code

This function disables the ALTZ foreground/background selection
key. Once this function has been issued, pressing the ALT and the
Z key together will have no affect on MultiDos Plus. The only way
to switch between foreground and background would be to issue an
FG command to MultiDos Plus using INT 15H function code 15
(Execute a MultiDos Plus Command).


Turn On ALTZ Toggle (default)

Function Code = 18

Entry:
AH = function code

This function enables the ALTZ foreground/background selection
key. This is the default mode when MultiDos Plus first begins
execution unless the command line option /NALTZ was specified. If
the ALTZ hot key was disabled, this function will reenable it.







(35)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Get Task Control Block Address
Function Code = 19

Entry:
AH = function code

Exit:
AX = offset of the task control block
BX = segment of the task control block

The segment and offset of the Task Control Block (TCB) of the
calling task is returned. A TCB is a structure created by
MultiDos Plus for each task in the system. See the section on
Useful System Data Structures in Chapter V for more information
on the contents of the TCB.

All TCBs reside in the same data segment which can be found in
the first field of the System Block and is labeled as the segment
of the System Control Block.


MultiDos Plus Foreground/Background Flag
Function Code = 20

Entry:
AH = function code

Exit:
AX = 0 if MultiDos Plus is the background task
1 if MultiDos Plus is the foreground task

Using this function, a task can check to see if the MultiDos Plus
command task is in the foreground or background.

A task can check if it is the foreground task by testing the flag
at offset 72 in its TCB. If the word at that location is binary
zero, the task is in the background. The TCB of the current
foreground task can be located using the pointer at offset 22 in
the System Block.


Get System Block Pointer
Function Code = 21

Entry:
AH = function code

Exit:
AX = offset of the System Block
BX = segment of the System Block

This function returns a pointer to the System Block structure.
See the section on Useful System Data Structures in Chapter V for
more details on the position of data in the System Block. This
structure contains information which may be useful to an
application.





(36)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

MultiDos Plus Initialization
Function Code = 22

Entry:
AH = function code

This function is used by MultiDos Plus during initialization and
should not be invoked by any other task. It is documented here
for the sake of completeness. Any attempt to use it by an
application program will cause unpredictable, erratic results.



Map IRQ
Function Code = 23

Entry:
AH = function code
AL = interrupt request number to map (1 - 15)
BX = offset of Task Control Block (TCB) to associate
to interrupt

Exit:
AX = 0 if successful, not 0 if invalid value in AL

The LIM map of the task identified by the TCB is associated with
the hardware Interrupt ReQuest level specified in the AL
register. The value of the AL register is determined by
subtracting 8 from the interrupt number. For example, a value of
1 corresponds to interrupt 9 which is normally the keyboard
hardware interrupt. Mapping interrupt 8 (IRQ 0) is not allowed
and returns a nonzero value in AX. Values in register AL which
are greater than 7 are determined by subtracting 68H from the
interrupt number. For example, a value of 8 corresponds to
interrupt 70H which is IRQ 8 on the second PIC of an AT.

A task may only be associated with one IRQ at a time. If the IRQ
is changed for a task, be sure to use function code 24 (Unmap
IRQ) to disassociate an existing IRQ relationship.

This function is normally issued by the MultiDos Plus command
task when a program is loaded with an IRQ command in effect.



















(37)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Unmap IRQ
Function Code = 24

Entry:
AH = function code
AL = interrupt request number to unmap (1 - 15)

Exit:
AX = 0 if successful, not 0 if invalid value in AL

The Task Control Block (TCB) is disassociated from the specified
interrupt request level. The association must have been
previously established using function code 23 (Map IRQ).

Unpredictable results may occur if no relationship exists for the
interrupt specified in the AL register when function code 24 is
invoked.



Unmap all IRQ'S
Function Code = 25

Entry:
AH = function code

Exit:
AX = destroyed

This function is used by MultiDos Plus to restore all the
hardware interrupt vectors to the values present when MultiDos
Plus first began execution.

WARNING: This function is for MultiDos Plus internal use only.



Return Memory Parameters
Function code = 31

Entry:
AH = 31

Exit:
BX = First memory segment of conventional memory
DX = First memory segment of the LIM swap frame
created by MultiDos Plus to load programs

This function will return the memory segment values for the start
of conventional memory and the base of the LIM swap area.











(38)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Test if Multitasking is Disabled
Function code = 32

Entry:
AH = 32

Exit:
AX = 0 if multitasking is enabled
or
AX = TCB of task that disabled multitasking

This function may be useful by interrupt handlers which may need
to know if multitasking is disabled or not.
















































(39)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

RESOURCE CONTROL FUNCTIONS
--------------------------

Tasks running under MultiDos Plus can synchronize their execution
and also share common resources by using "semaphores". Semaphores
are also referred to in this document as "resource semaphores".

Thirty-one semaphores numbered 1 through 31 are available for
MultiDos Plus applications. These semaphores are created when

MultiDos Plus starts, and programs may use them at any time.

WARNING: Semaphore 0 is present but is used internally by
MultiDos Plus to control access to DOS services. Programs which
get or attempt to release semaphore 0 may interfere with DOS
access.

An additional set of 32 semaphores are also available but are
referenced by name rather than a number. Names may be anything
that programs choose to use but are limited to a maximum of 8
characters in length. Once used, names are remembered by MultiDos
Plus and do not disappear until MultiDos Plus is terminated or
the system is rebooted. Named semaphores are used internally by
MultiDos Plus when applications post read/write calls to DOS
drivers which support IOCTL calls. Consequently, the number of
named semaphores available for application use may be less than
32.

Semaphore operations include the ability to get (function codes 1
and 27), release (function codes 2 and 28), or check the status
(function codes 16 and 29) of a given semaphore. A program
issuing a call to get a semaphore will return immediately if the
semaphore is free or available. The semaphore is then considered
to be owned by the program until the program releases it at a
later point. A program attempting to get a semaphore will be
suspended if the specified semaphore is owned by another program.

Semaphores may be used to handle a variety of synchronization
problems but are generally used in the following two situations:

1) Two cooperating tasks may wish to synchronize their
execution and attempt to get a semaphore in a prearranged
sequence. The second task attempting to get the semaphore will be
suspended. The first task may schedule the execution of the
second by releasing the semaphore at the appropriate time.

2) The most common use of semaphores is to control the access to
certain system resources. These resources may be hardware or
software resources. An example of a hardware resource may be a
device such as a communications port which may be used by any
program but must be accessed in an exclusive manner. A software
resource could be a function or a driver which is not reentrant.
Programs accessing such resources should control their access by
getting a semaphore prior to accessing the resource and releasing
it, after the use of the resource. This technique will guarantee
exclusive use of the resource when it is in use.






(40)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Get Ownership of a Resource Semaphore

Function Code = 1

Entry:
AH = function code
AL = resource semaphore number (0 - 63)

Exit:
AH = 0 if no error
2 if resource semaphore number is invalid

The ownership of the resource semaphore is tested and if not
owned by another task, ownership is given to the calling task and
control returns immediately. If the resource semaphore is owned
by another task, the calling task is suspended until the owner
gives up control. If several tasks request the same resource
semaphore, the tasks are suspended and placed in a FIFO queue to
wait for the resource semaphore to become available.


Release Ownership of a Resource Semaphore
Function Code = 2

Entry:
AH = function code
AL = resource semaphore number (0 - 63)

Exit:
AH = 0 if no error
1 if the task does not own the resource semaphore
2 if the resource semaphore number is invalid

This function releases ownership of the specified resource
semaphore. If a task is waiting for the resource, the waiting
task will become the new owner and will be scheduled for
execution. If several tasks are waiting for the resource
semaphore, the first task that requested it will be given
ownership. The other waiting tasks will remain on the queue and
wait for their turn at ownership.

WARNING: Do not use this function in an interrupt service
routine. The task which was interrupted may not be the owner of
the resource semaphore.

















(41)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Test Ownership of a Resource Semaphore
Function Code = 16

Entry:
AH = function code
AL = resource semaphore number (0 - 63)

Exit:
AH = 0 if resource is not reserved
1 if resource is reserved
2 if the resource semaphore does not exist
3 if the task already owns the resource semaphore

This function tests if the specified resource semaphore is
already owned. You will probably want to use this function in
conjunction with function codes 13 (Disable Multitasking) and 14
(Enable Multitasking) to disable the time slice scheduling while
your task is checking the resource semaphore. If the resource is
available, then the task can issue the function to get the
resource before some other task can get the resource. This may be
important if a task wants to get ownership of a resource without
getting suspended.



Map Name to Number
Function Code = 26

Entry:
AH = function code
DS:SI = pointer to name string

Exit:
AL = 0H no error
4H out of string space
AH = resource semaphore number if no error

This function is used internally by function codes 27, 28 and 29
to equate a string with a resource semaphore number. The name
string pointed to by DS:SI consists of 8 bytes all of which are
significant, and it is not null terminated. If the name already
exists, the number associated with that name is returned in
register AH. If the name does not yet exist, it is entered into
the name table; and a free number is assigned to the name. Up to
32 names may be created, and the numbers assigned to them will
start with 32 and range up to 63. Once a name is created, it
cannot be destroyed.

Function codes 27, 28, and 29 are the equivalent of invoking
function code 26 followed by function code 1, 2, and 16
respectively.










(42)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Get Resource Semaphore by Name
Function Code = 27

Entry:
AH = function code
DS:SI = pointer to name string

Exit:
AH = 0H resource semaphore is now reserved
2H illegal resource semaphore number
3H invoking task already owns semaphore
4H out of string space

The ownership of the resource semaphore is tested; and if
unowned, ownership is given to the calling task and control
returns immediately. If the resource is owned by another task,
the calling task is suspended until the owner gives up control.
If several tasks request the same resource semaphore, the tasks
are suspended and are placed in a FIFO queue to wait for the
resource to become available. See function code 1 (Get Ownership
of a Resource Semaphore) for more details on getting resource
semaphore ownership.



Release Resource Semaphore by Name
Function Code = 28

Entry:
AH = function code
DS:SI = pointer to name string

Exit:
AH = 0H resource semaphore is available
1H resource semaphore is not available
2H illegal resource number
3H invoking task already owns semaphore
4H out of string space

This function releases ownership of the named resource semaphore.
See function code 2 (Release Ownership of a Resource Semaphore)
for more details about releasing ownership of a resource
semaphore.


















(43)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Test Resource Semaphore by Name
Function Code = 29

Entry:
AH = function code
DS:SI = pointer to name string

Exit:
AH = 0H resource semaphore is available
1H resource semaphore is not available
2H illegal resource number
3H invoking task already owns semaphore
4H out of string space

The ownership of the resource semaphore named in the string
pointed to by DS:SI is tested, and the results of the test are
placed in the AH register on return. See function code 16 (Test
Ownership of a Resource Semaphore) for more information on
testing resource semaphores.










































(44)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

INTERTASK MESSAGING FUNCTIONS
-----------------------------

The Intertask Message Facility is a convenient mechanism for
programs running under MultiDos Plus to rapidly exchange data.
API calls are available for tasks or programs to send (function
code 4), receive (function code 6) and check (function code 5)
for the presence of messages.

MultiDos Plus provides 64 message queues (or mail boxes) numbered
0 through 63. These queues are created when MultiDos Plus is
started and are available at any time for programs to send or
receive data. Unlike other multitasking environments, there is no
need to create, use and subsequently destroy message queues.

When a task sends a message to a message queue, the contents of
the message buffer are copied to a buffer in a message buffer
pool. This buffer is queued on a data structure associated with
the message queue. The task sending the message is free to
continue its execution and also to reuse its message buffer.

The buffer pool, where copies of the messages are maintained by
MultiDos Plus, is the unused conventional memory pool in the
system. Therefore, if all the memory is assigned to various
application programs (by means of RM commands and/or loading
programs until memory runs out), there will be no memory
available for the message buffer pool and intertask communication
will not be possible.

The size of an individual message is limited to the smaller of
64K or the size of the largest free memory block.

Tasks which attempt to read a message from a queue are suspended
if there is no message pending on the queue. If a message is
pending, its contents are immediately copied to the receive
buffer and execution continues. Multiple tasks may post reads on
a single message queue. These tasks are queued up in a FIFO
manner and receive the messages in the order in which they are
received on the queue.

If any task is waiting to receive a message on the specified
queue, the message buffer contents are copied to the receiving
task's buffer area, after which the task that was waiting for the
message is scheduled.

Tasks which read a message queue must specify the length of the
receive buffer so that MultiDos Plus can ensure that the receive
buffer is not overrun. MultiDos Plus will always transfer as many
bytes as it can without overrunning the receive buffer.












(45)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

As noted earlier, applications do not create queues; and
therefore, there is no notion of "ownership" of the queues.
Programs are free to write to and read from message queues as
they please. It is, therefore, necessary for the system designer
of the various applications to coordinate the use of the various
message queues.

Cooperating programs may set up shared memory areas by sending
the address and the size of the area to another program via a
message queue. Since Multidos Plus runs under the real mode,
there is no memory protection; and any program may access any
part of the first megabyte. NOTE: This technique may not be
possible for programs running in LIM memory.
















































(46)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Send a Message to Another Task
Function Code = 4

Entry:
AH = function code
AL = message queue number (0 - 63)
DS:SI = message buffer pointer
CX = length of message

Exit:
AH = 0 if okay
1 no system memory for message
2 if illegal message queue number

Send a message to another task via a message queue. The contents
of the buffer pointed to by DS:SI are copied to a system buffer
allocated from the MultiDos Plus available memory pool, and the
system buffer is added to the end of the specified message queue.
As soon as this function returns to the invoking task, the task's
message buffer may be used for another message without disturbing
the previous message.


Check Message Queue for a Message
Function Code = 5

Entry:
AH = function code
AL = message queue number (0 - 63)

Exit:
AH= 0 if no error
2 illegal message queue number
DX= 0 if no message, else the length of
the first message in the queue

Check if the specified message queue has an available message.
Control is returned immediately. The function does not wait for a
message to be placed on the message queue. In addition to
checking for the presence of a message, this function is also
useful for determining the size of a message before actually
attempting to get the message. The task can then insure that the
buffer it passes to get the message will be large enough to hold
the entire message.

















(47)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Get a Message from a Message Queue
Function Code = 6

Entry:
AH = function code
AL = message queue number (0 - 63)
ES:DI = buffer pointer to put message in
CX = number of bytes in buffer

Exit:
AH = 0 no error
CX = number of bytes transferred
DX = actual message length
or
AH = 2 illegal message queue number

Read a message from the specified message semaphore. If no
message is present, the task is suspended until one is available.

If a task does not know the maximum size of a message, it should
issue a function code 5 (Check Message Queue for a Message) to
check a message queue for the size of a message before actually
reading the message. If the buffer is not large enough to hold
the message, the message is truncated before it is placed in the
calling task's buffer. The truncated part of the message is lost.




































(48)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

EVENT TRIGGER FUNCTIONS
-----------------------

A useful feature provided by MultiDos Plus is a mechanism for
having a task wait for a specific event to occur. While the task
is waiting, it is suspended on a queue and will not use any
processor time. When an event occurs, the process triggering the
event (such as an interrupt handler) invokes a MultiDos Plus API
call to signal that the event has occurred. If a task is waiting
for the event, it is scheduled. If no task is waiting, a counter
for the event is incremented.

There are 64 Event Triggers defined in MultiDos Plus. Each one
consists of a 16-bit counter and an associated task waiting
queue. When an Event Trigger function is invoked, a number from 0
to 63 is specified to indicate on which counter/queue to operate.

The Event Trigger functions are all available through the single
interrupt 15H function code 30. Each individual function is
specified by a subfunction code in register AL. Three
subfunctions are defined to clear the counter (subfunction code
0), wait for an event (subfunction code 2), and to trigger the
event (subfunction code 1). The following describes the interface
to these subfunctions.


Clear Event Counter
Function Code = 30 subfunction = 0

Entry:
AH = function code
AL = subfunction code
DX = event/trigger number (0 - 63)

Exit:
AH = 0 no error

This function clears the counter for the specified event/counter
number. This function can be invoked by either a task or an
interrupt service routine.

NOTE: A counter will roll over after 65,536 events have occurred
and none have been serviced.


















(49)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Signal Event
Function Code = 30 subfunction = 1

Entry:
AH = function code
AL = subfunction code
DX = event/trigger number (0 - 63)

Exit:
AH = 0 no error
1 invalid event/trigger number

This subfunction is used to signal a waiting task that an event
has occurred. This function may be invoked either by another task
or by an interrupt service routine. If a task is waiting for the
event, it is scheduled for execution.

If no task is waiting, then the counter is incremented by one to
indicate that an event occurred. If more than 65,536 event
signals are received, the counter will roll over to zero.


Wait for Event
Function Code = 30 subfunction = 2

Entry:
AH = function code
AL = subfunction code
DX = event/trigger number (0 - 63)

Exit:
AH = 0 no error
1 invalid event/trigger number

A task issues this function to wait for an event to occur. If the
value of the counter is zero, the invoking task is suspended
until another task or an interrupt service routine invokes
subfunction 1 (Signal Event). If the counter is not zero, control
is returned immediately to the calling task; and the counter is
decremented by one.

A potential use for an Event Trigger is a cooperative arrangement
between a task (or several tasks) and an interrupt service
routine. If an interrupt service routine has the job of
collecting data and placing it in a buffer, it would notify a
task waiting for the event when the buffer is full. The waiting
task would then service the full buffer (when it is its turn to
receive a time slice) and return to wait for the next event.













(50)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

INSIDE MULTIDOS PLUS
--------------------

The file MULTIDOS.EXE is the only file required to use MultiDos
Plus. It contains the multitasking kernal which provides all the
MultiDos Plus features except for those provided by the display
driver (MDBIO10.EXE). If your application will only have one task
which will ever write to the CRT, there is no need to install
MDBIO10 on startup. Therefore, the only files you may ever need
to run MultiDos Plus are MULTIDOS.EXE and perhaps MDBIO10.EXE.
This chapter will describe some of the inner workings of the
MULTIDOS.EXE program which may help you to better understand how
to use MultiDos Plus for your application.

MultiDos Plus Startup

When the MULTIDOS.EXE program begins execution, it goes through a
complex initialization process. During initialization, a number
of data structures are created and initialized followed by the
"hooking" of a number of the interrupt vectors. All the command
line parameter options are examined; and the appropriate internal
flags, etc. are set for later use.

During intialization, the memory for the Task Control Blocks
(TCB) is allocated. The value specified with the /NUMTCB option
is used as the number of TCBs to create. If no /NUMTCB option is
specified, a default value of 12 is used. When specifying the
number of TCBs, keep in mind that two additional TCBs are
required by MultiDos Plus for internal use. Also, when a task
executes a DOS child process function, each active child process
requires an additional TCB.

The size of the TCB is determined by the /CTX option. If /CTX is
not specified, the TCB will only be about 224 bytes. If /CTX is
specified, the TCB will be about 624 bytes. The actual size may
vary slightly depending on the version of MultiDos Plus you are
using.

Once the TCBs have been allocated, the first two are used for two
internal tasks, the MULTIDO and the IDLE tasks. If you use the
"L" command in MDDEBUG, the first TCB is MULTIDO and the second
is IDLE. These two tasks are created during initialization.

The interrupt vectors "hooked" into by MultiDos Plus are 8, 9,
12H, 15H, 16H, 20H, 21H, 22H, 23H, 24H, 25H, 26H, 27H. If MDBIO10
is loaded, interrupt 10H is also "hooked". If your application
needs to make use of any of these interrupts, you must take care
to pass control to the MultiDos Plus interrupt handler if the
interrupt is not applicable to your application. For the most
part MultiDos Plus tries to preserve the DOS or BIOS meaning of
the interrupt with multitasking in mind.

Once the INT 8 interrupt vector is "hooked", the multitasking is
initiated. The initialization routine becomes the MULTIDO task
which is described below.
The Command Task

The Command Task is the main MultiDos Plus task and performs



(51)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

several different functions. The task name in the TCB is MULTIDO
which can be examined with various MDDEBUG commands. As mentioned
above, the Command Task is a continuation of the initialization
process and comes into being as soon as the multitasking is
turned on by "hooking" interrupt 8.

The first function performed is the loading of the MDBIO10
driver, if required. Once MDBIO10 is loaded, a delay of 18 ticks
is executed to give MDBIO10 plenty of time to perform its
initialization. To make the new interrupt vector a part of the
Command Task display context, the content of the System Block's
"pointer to new interrupt 10H" is placed into the actual
interrupt 10H vector.

Next is the processing of the AUTO.MTX startup file, if one is
present. During the execution of the AUTO.MTX, only command
processing takes place. If a started task attempts to use any of
the other services provided by the Command Task, they will not be
performed until the AUTO.MTX processing is finished.

The Command Task will now enter its main function loop which
continually checks several queues for requests and then reads a
character from the keyboard. If there is no character to read,
the Command Task suspends itself for at least one timer tick.
When the MULTIDO task is in the background, it suspends itself
for 4 ticks before scanning the queues and looking for an ALTZ
key.

Besides interpreting MultiDos Plus commands, the Command Task
also provides services for inter-task communication, program
loading, program termination, foreground/background switching and
task command execution. All these functions are initiated when
the Command Task finds a request for these services on one of the
request queues. These queues are checked each time the Command
Task wakes up.

The "IDLE" Task

The "IDLE" Task is a very simple task which exists solely for the
purpose of giving the system something to do when there is
nothing else that needs to be done. The "IDLE" Task is always in
a loop which continually gives up its time slice by issuing an
API function code 0 (Give Up Time Slice) call.

The General Application Environment

When a COM or EXE program begins execution as a loaded program
under MultiDos Plus, it can usually execute as if MultiDos Plus
was not in the system and the program was started by DOS.

Each program has a PSP block built for it just as if the program
had been loaded by DOS. This gives each task its own environment
string (which is a copy of the environment present when the
MULTIDOS.EXE first began execution) and separate file handle
table. The PSP will also have the command line string which is
taken from the command line that loaded the program. As mentioned
in earlier chapters, no standard input/output redirection is
provided by MultiDos Plus. The first five file handles of a task



(52)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

are inherited from the MultiDos Plus PSP. The DOS CLOSE HANDLE
function will not close a handle less than 5. If attempted, the
function returns a normal completion code with no error to the
calling task.


DOS Services

Tasks are normally free to make use of DOS interrupt 21H services
as if they are the only program in the system. MultiDos Plus uses
Resource Semaphore 0 to control access to DOS without the tasks
being aware of the process. In addition, a number of DOS services
are provided directly by MultiDos Plus so as not to tie up DOS.
These are normally functions which read from the keyboard and
write to the CRT display.

When a task issues an INT 21H for a DOS function, several
functions are performed just before entry to the old DOS
interrupt vector. MultiDos Plus sets the DTA and the Process ID
for the task. The Process ID is the task's PSP segment and is set
using DOS function code 50H. Also, if the /CTX option was
specified when MultiDos Plus was invoked, the directory context
of the task is restored. When the task returns from DOS, the
directory context will be saved in the task's TCB.

Task Scheduling

MultiDos Plus provides a preemptive multitasking system which
offers a choice of two different scheduling schemes. The
interrupt 8 timer is used to preempt executing tasks. Tasks
waiting for execution are held in a Ready Queue and receive
slices of processor time. When the interrupt 8 timer expires, the
currently executing task is suspended and placed at the end of
the Ready Queue. The next task on the queue is then allowed to
execute until the timer expires again.

The default scheme of selecting the next task to execute from the
Ready Queue removes the task at the head of the queue, checks its
scheduling counter and if zero, the task is executed. If the
scheduling counter is not zero, it is decremented by one and
placed at the end of the Ready Queue. If the scheduling counter
is decremented to zero, the counter is reset to the task's
priority level; and the task is allowed to execute. Using this
type of scheduling scheme, all tasks will eventually receive a
time slice. When a task is loaded, its priority level is set to
zero.

A second type of scheduling scheme may be selected by using the
/PR command line option when MultiDos Plus is started. The /PR
option changes the way MultiDos Plus selects tasks from the Ready
Queue for execution. A task is selected by scanning all the tasks
on the Ready Queue. The task with the highest priority level
(lowest value) is selected for execution. If several tasks have
the same priority level and they have the highest priority, the
task closest to the head of the queue is selected. Thus, tasks
with equal priority will execute in a round robin manner. The use
of this scheme can provide high priority tasks with highly
reliable scheduling for critical real time events. NOTE: High



(53)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

priority tasks should make use of API function code 3 (Suspend
Task for Interval) to avoid monopolizing all of the system's
processing time. The API Event Triggers are also good for
controlling high priority tasks.

The scheme for selecting the next task for execution also applies
when an executing task gives up its processing time by giving up
its time slice, suspending itself, requesting a resource
semaphore, getting a message from a message queue, or waiting for
an event.

Task Context Switch

There are a number of instances where MultiDos Plus will save a
running task's context, place the task's TCB on a queue, find the
next task ready to run, switch in the new task's context and
resume execution with the new task. A context switch occurs when
a task executes an interrupt 15H API function which causes the
task to be blocked from execution or when the interrupt 8 timer
interrupt occurs. It is the interrupt 8 timer interrupt which
preempts the running task and the context switch is performed
before the old timer interrupt handler code is executed.

A task's context information consists of registers AX, BX, CX,
DX, BP, DI, SI, DS, ES, CS, IP, FLAGS, SS, and SP. All the
register context is saved on the task's stack with the exception
of the SS and SP registers which are saved in the task's TCB. The
interrupt 10H interrupt vector is also saved in the TCB; and if
the task uses LIM memory, the LIM context is also saved in a
block of memory attached to the task's TCB.

Internal Tasks (Threads)

MultiDos Plus supports the concept of internal tasks or threads
within the same program. A program may start subroutines or
functions as separate processes called internal tasks.

The concept of internal tasks offer several obvious advantages.
The various tasks can easily share data without resorting to
intertask communication or other means. The other major advantage
is that reentrant code can be shared between the tasks, resulting
in significantly smaller memory requirements.

Greater care is needed in implementing a system based on internal
tasks. The major consideration is to examine the code that will
be shared by the various tasks and determine whether it is
reentrant. Though this is fairly easy to determine in the case of
assembler code, determining the reentrancy of higher level
language code may be difficult. Even if the code written by the
MultiDos Plus user is reentrant, it should be noted that the
various tasks may reference library run-time functions which may
or may not be reentrant.

Internal tasks share the same Program Segment Prefix with the
parent, with the result that files opened by one task are
available to the parent as well as other children. The child
internal tasks inherit other properties of the parent including
the memory control blocks. Memory allocation done by a child



(54)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

internal task results in memory being allocated from the parent.

MultiDos Plus automatically assigns names for internal tasks.
Unique names are assigned to internal tasks by incrementing the
last character of the parent task's name. Internal tasks are not
shown when ALTZ is done and cannot be brought to the foreground.

It is very important that an internal task terminate its
execution by using the API function code 8 (Terminate Internal
Task). Using a DOS termination function will result in
unpredictable results.


















































(55)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

RUNNING WITH A LIM 4.0 EMM DRIVER

MultiDos Plus fully supports any LIM EMS memory you may have in
your system. A LIM driver version 4.0 or greater must be present
in your system in order for MultiDos Plus to take advantage of
the LIM memory.

On 386 PCs no hardware LIM boards need to be present as long as
you have a suitable software emulator which conforms to LIM 4.0.
For 286 as well as 8088 based systems you must have a LIM board
with the appropriate LIM 4.0 driver. NOTE: Certain 286 PCs have
LIM 4.0 emulators which enable you to use extended memory as LIM
4.0 memory. However, this technique will not be suitable for use
under MultiDos Plus as the map switching will not be fast enough.

Certain older LIM boards such as the Intel Above Board may be
controlled by a LIM 4.0 driver but provide mappable memory of
only 64K. These boards will severely restrict the size of the
programs you can run in LIM memory.

Newer LIM boards which provide hardware support for the LIM 4.0
specification such as the Intel Above Board PLUS or the AST
Rampage Plus are highly desirable for use under MultiDos Plus.
However, even with these boards, your hardware configuration may
limit the amount of mappable EMS memory. The ideal configuration
for MultiDos Plus is a 386 PC with a LIM 4.0 memory manager or a
PC/AT with conventional memory limited to 256K with the rest
supplied by a LIM 4.0 board with the ability to backfill
conventional memory to 640K. For faster context switches, boards
supporting alternate map sets are desirable.

Nanosoft Inc. has tested various configurations but does not
explicitly endorse any single product due to the large number of
boards and emulators available in the market. It is up to the
user to determine the best configuration to suit your needs.

MultiDos Plus permits your normal DOS programs to run in expanded
memory with no changes to your programs. This permits large
multitasking systems to be developed without being limited by
memory. The code size of a single program is still limited by the
size of the mappable page frame in your system (unless overlays
are used). Programs running in expanded memory may use LIM
memory by means of standard LIM driver calls to map memory in the
LIM page frame. MultiDos Plus saves and restores map contexts for
all programs with no special coding required on the part of
application programs.

Certain terms need to be fully understood in order to make
effective use of LIM memory under MultiDos Plus. The MultiDos
Plus Page Frame is defined as the area of mappable LIM memory
used to load and execute application programs. It is the largest
contiguous area of mappable LIM memory available in the system
and generally starts at the first 16K boundary after MultiDos
Plus and extends up to your display memory. The LIM page frame is
a 64K area of memory usually starting at C000 or beyond and is
used by applications to map LIM memory by normal LIM driver
calls. A normal DOS program which uses LIM memory will run
unchanged under MultiDos Plus whether it is loaded in



(56)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

conventional or LIM memory (in the MultiDos Page Frame).

In addition to the two page frames discussed, most systems have
"holes" in the first megabyte of memory where LIM memory can be
mapped. On startup, MultiDos Plus permanently maps LIM memory
into these "holes" and links them to the conventional memory in
your system. This may result in significant increase in the
amount of conventional memory in your system. By default, the
"hole" corresponding to the LIM page frame is not mapped on the
assumption that you may be running applications which explicitly
map LIM memory and need the use of the LIM page frame. If this is
not the case the startup option /MAPALL will map all available
holes including the LIM page frame. NOTE: This permanent mapping
does not preclude applications from running in LIM memory in the
MultiDos Plus Page Frame.

As noted earlier, programs may run in expanded memory without any
special consideration. There are, however, some exceptions.
Programs running in expanded memory performing data transfers
to/from external devices triggered by hardware interrupts will
not function correctly. This is due to the fact that the data
transfer may take place when the map set associated with the
program is not active. To handle this situation, the command IRQ
lets you associate an IRQ number with a specific program's map
set. Simply specify this parameter when you load the program, and
MultiDos Plus will automatically map the program when the
specified interrupt occurs. After the ISR is complete MultiDos
Plus will remap the map context in effect when the interrupt
occurred. Currently there is no provision to associate multiple
IRQs with a single program.

Programs running in LIM memory may not set up shared memory areas
with other programs running in LIM. They may do so with programs
running in conventional memory provided that the programs
explicitly handle the mapping when necessary.

MultiDos Plus uses alternate map sets (if available) to perform
rapid context switching of LIM maps. If alternate map sets are
used up (or if none are available to start with), MultiDos Plus
saves and restores map contexts in internal save areas associated
with each program.

DRIVERS UNDER MULTIDOS PLUS

The discussion in this section applies to installable DOS device
drivers as well as Interrupt Service Routines and TSRs.

In general, drivers, TSRs and ISRs written for DOS will work
under MultiDos Plus with no changes. There are, however, some
restrictions when expanded memory is used in conjunction with
MultiDos Plus. This section offers general guidelines for
implementing and using existing drivers under MultiDos Plus.
Having a clear understanding of the MultiDos Plus architecture
will permit the user to circumvent most of the limitations.

In general, all TSRs and ISRs must be loaded prior to MultiDos
Plus. DOS installable drivers are of course always loaded when
the system is booted. Though MultiDos Plus permits TSRs to be



(57)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

loaded as tasks under MultiDos Plus, in most cases this approach
is not recommended. TSRs which change interrupt vectors used by
MultiDos Plus MUST be loaded before MultiDos Plus.

Any software which gets invoked as a result of external
interrupts may not normally reside in mappable expanded memory.
The external interrupt would cause the processor to transfer
control to code which may not be currently mapped. The IRQ
command described in Chapter II may be used to handle this
situation but will result in significant performance overhead,
especially if the interrupts occur at a rapid rate.

TSRs and ISRs may be loaded in expanded memory which is
permanently mapped (the "holes" in high memory which are
permanently mapped by MultiDos Plus). Any driver, TSR or ISR
which uses expanded memory (by making explicit LIM driver calls)
must save and restore the current task's map context.

Standard DOS drivers are usually synchronous drivers (control is
transferred to the application only after the driver completes
the request). Some drivers, especially network related drivers,
are implemented as asynchronous drivers. Such drivers may need to
be redesigned if they need to service application programs
running in expanded memory. When a request is initiated by a
program, the driver must determine the TCB of the program, and
later map the LIM map associated with the program to perform data
transfers to/from driver address space to program address space.
If drivers are implemented to service multiple application
programs, the driver must be reentrant.

Drivers and ISRs which are triggered by external interrupts
should not use most of the MultiDos Plus API calls. The
exceptions are calls to determine the current TCB and certain
event trigger calls. It should be noted that ISRs may get invoked
at any arbitrary time and runs under the context of the user task
which was interrupted. Using MultiDos Plus system service calls
may, therefore, affect the execution of the task which was
interrupted with unpredictable results.

Event trigger calls have been designed for use by ISRs and
drivers and should be the primary vehicle for communication from
a driver to tasks running under MultiDos Plus.



















(58)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

THE DISPLAY AND INTERRUPT 10H
-----------------------------

Well behaved DOS programs either use DOS interrupt 21H functions
or BIOS interrupt 10H functions to place data on the visual CRT
display. Even the DOS interrupt 21H functions wind up invoking
the BIOS interrupt 10H functions for display functions. Based on
this, MultiDos Plus includes a software driver which intercepts
BIOS interrupt 10H. The driver will only allow the foreground
program to write data to the real CRT memory, while background
programs have their display data written to a different piece of
memory. This driver is the file MDBIO10.EXE which is included on
the distribution diskette.

MDBIO10 supports the standard BIOS INT 10H functions for
background tasks for the monochrome and the color graphics
displays. Other display adapter modes are not supported for
background tasks. Foreground tasks can use any display mode
supported by your adapter hardware. If the foreground task is
using an unsupported mode and the task is moved to the
background, some of the contents of the display are lost.

MDBIO10 is a Terminate Stay Resident program which performs some
initial setup and then invokes DOS INT 21H function code 31H to
terminate. The initialization sets the interrupt 10H vector to
point to the MDBIO10 interrupt handler and sets the new interrupt
10H pointer in the System Block before terminating. Subsequent
execution is initiated by MultiDos Plus tasks invoking interrupt
10H.

When the driver is entered as a result of an interrupt 10H call,
MDBIO10 first determines if the calling program is in the
foreground or in the background. Display calls issued by the
foreground program are passed through to the original BIOS
display handler.

Display output of a background task is written to its virtual
screen. The virtual screen is on a paragraph boundary, and its
segment address is in offset 18 of the TCB.

Data associated with the display for each task is maintained in
its TCB. This area is identical to that maintained by BIOS in low
memory.


















(59)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

USING THE MATH COPROCESSOR
--------------------------

In the interest of performance, MultiDos Plus does not save and
restore the context of the 8087/80287/80387 math coprocessor when
a task's context is switched at the end of a time slice. If more
than one task requires the use of the coprocessor, the context of
the coprocessor must be saved and restored during each task
context switch. This will also be necessary if your application
software uses an 8087 emulator for its floating point.

MultiDos Plus is supplied with a small TSR named APPLCTX.EXE
which should provide the context save/restore required for your
application. The source code for APPLCTX is also supplied in the
event you need additional support. Read the section on Enhancing
the Task Context Switch for more information on how APPLCTX
works.












































(60)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

USEFUL SYSTEM DATA STRUCTURES
-----------------------------

The Task Control Block

A Task Control Block (TCB) is a data structure which contains
task related information needed by MultiDos Plus to keep track of
the task. Each task running under MultiDos Plus has a TCB. A
task can obtain a pointer to its own TCB by issuing an interrupt
15H with a function code of 19 (Get Task Control Block Address).
All TCBs are allocated in the same segment, and they all start on
a paragraph boundry. The first TCB starts at byte offset 16. The
TCB size in the system block can be used to calculate the start
of any TCB in the system. The following table contains the
definitions of the fields contained in the TCB. All offsets and
sizes are in bytes.

Offset Size Definition

0 2 link to next TCB
4 8 null terminated task name (7 characters max)
14 2 task starting segment (PSP)
16 2 abort/suspend flags
18 2 current display memory segment
20 2 priority level (0 - 65,534)
22 2 time slice counter
26 2 suspend timer value
28 2 stack segment
30 2 stack pointer
32 2 display type
34 2 display memory
38 2 termination count
40 2 equipment flag for BIO10 driver
42 1 background CRT mode



























(61)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Offset Size Definition

43 2 number of CRT columns
45 2 length of CRT display memory
47 2 segment of real CRT memory
49 16 8 CRT cursor positions
65 2 current cursor mode
67 1 active CRT page
68 2 6845 address
72 2 foreground task flag
80 2 save video memory segment
82 4 INT 22H context
86 4 INT 23H context
90 4 INT 24H context
94 2 top of memory for this task
100 2 DTA segment
102 2 DTA offset
108 1 current attribute (ANSI.SYS)
109 1 current horizontal coordinate (ANSI.SYS)
110 1 current vertical coordinate (ANSI.SYS)
111 1 current display state (ANSI.SYS)
112 1 maximum columns (ANSI.SYS)
113 1 current page (ANSI.SYS)
114 2 saved cursor position (ANSI.SYS)
116 1 parameter buffer index (ANSI.SYS)
117 1 current screen mode (ANSI.SYS)
118 1 wrap flag (ANSI.SYS)
119 6 parameter buffer (ANSI.SYS)
125 1 keyboard DSR state (ANSI.SYS)
126 7 keyboard DSR buffer (ANSI.SYS)
136 16 request header for DOS driver calls
166 2 segment of LIM map if LIM task
168 2 task makes LIM calls flag
170 2 LIM handle for this task
172 2 keyboard shift status
186 2 parent TCB if child process
188 2 termination code
190 2 COM port number
196 2 current IRQ number
200 2 miscellaneous flag word
204 4 INT 10H vector context
208 2 LIM alternate map set number
210 414 DOS current disk and directory context


















(62)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

The System Block

The System Block is a data structure inside MultiDos Plus which
contains pointers to other MultiDos Plus internal data
structures. It is used by other programs to retrieve information
for debugging and setting up a display driver for BIOS interrupt
10H.

The pointer to the System Block is obtained by issuing the
MultiDos Plus service interrupt with a function code of 21 (Get
System Block Pointer). The pointer returned points to a structure
of the following format:

Offset Size Definition

0 2 segment of System Control Block
2 2 redirection flag set by /NOREDIRECT
4 2 no BIOS 10H flag set by /NO10
6 4 pointer to old interrupt 10H
10 4 pointer to new interrupt 10H
14 4 pointer to word with current TCB offset
18 4 pointer to word with Idle task TCB offset
22 4 pointer to word with foreground TCB offset
26 4 pointer to word with MultiDos Plus TCB offset
30 2 TCB size
32 2 number of TCBs
34 2 expanded memory present flag
36 2 base segment of expanded memory frame
38 2 size of expanded memory frame in 16K pages
40 2 base segment for conventional memory tasks
42 2 number of conventional memory paragraphs
44 4 pointer to list of queue pointers





























(63)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

SOFTWARE INTERFACE FOR TERMINAL COMMUNICATION
---------------------------------------------

When a program is loaded with the COMM command option, MultiDos
Plus will direct certain keyboard and display functions to/from
the serial communication ports. This section describes the
specific functions performed and the software interface to the
communication ports. By using this facility it is possible to run
many standard DOS programs from a "dumb" terminal, including
COMMAND.COM.

In order to use this feature you must install a special driver
which will handle the low level BIOS communication functions.
This driver is currently not supplied with MultiDos Plus; a
detailed description of the driver is provided here so that the
user can develop a suitable driver.

Terminal redirection is enabled by the COMM command described in
Chapter II. NOTE: The communications driver must be resident
prior to using the command. It may be loaded before MultiDos
Plus, or you can have MultiDos Plus load and execute the driver.
The driver must "hook" onto software interrupt 14H to handle
functions issued to it by MultiDos Plus. A basic requirement of
the driver is that it use the hardware interrupts to collect
input data from the communications port. If the driver is not
interrupt driven, it will most likely function improperly because
the program was not assigned a time slice when the port needed
servicing.

MultiDos Plus interfaces to the driver by means of software
interrupt 14H. The function codes used by the driver are distinct
from the BIOS RS-232 services.

Basically, MultiDos Plus invokes INT 14H in three places. When a
task is loaded, INT 14H function codes 20H, 24H and 25H are
issued to initialize the specified communications port. When a
task reads from the keyboard, INT 14H function codes 22H and 23H
are issued and if there is a buffer overflow, function code 25H
is issued to clear the error. Function code 27H is issued if INT
16H is issued to check for a key press. When a task issues an INT
10H function code 0EH to display a character, the MDBIO10 driver
will invoke INT 14H function code 21H to send the character to
the task's communication port.

When the task is loaded, the communications port number is placed
in the task's TCB at offset 190. Later read and write functions
check the TCB field to determine which communication port to use
for the operation. The port number placed in the TCB is zero if
no communication redirection should be done for the task. If the
port is a one (1), then COM1 is assumed. The highest port number
allowed depends on what is supported by the port driver.










(64)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

When the task is loaded and the port is initialized, the INT 14H
functions are issued in the order 25H, 20H, and then 24H to
initialize the port.


Initialize Port
---------------

Function Code = 20H

Entry:
AH = function code (20H)
AL = initialization parameters
DX = port number 0 based (COM1 = 0)
Exit:
AH = 0H command successful
41H no port address
64H monitor mode active

The RS-232 port specified in the DX register is initialized for
the parameters specified in the AL register. The bit settings in
AL have the following meaning:

Bits Definition

5 - 7 baud rate

000 110
001 150
010 300
011 600
100 1200
101 2400
110 4800
111 9600

3 - 4 parity

00 none
01 odd
11 even

2 stop bits

0 one stop bit
1 two stop bits

0 - 1 word length

10 7 bits
11 8 bits










(65)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Transmit Character
------------------

Function Code = 21H

Entry:
AH = function code
AL = character to send
DX = port number

Exit:
AH = 0H command successful
39H no DSR or CTS
3CH no DSR
3BH no CTS
42H monitor mode inactive
41H invalid port address
97H time-out

In order to use this function, the monitor mode must have been
activated by issuing an INT 14H function code 24H.

The character in the AL register is sent to the communications
port as soon as the port is able to receive data for
transmission.



Receive Character
-----------------

Function Code = 22H

Entry:
AH = function code
DX = port number

Exit:
AH = 0H command successful
3DH framing and parity error
3EH overrun error
3FH framing error
40H parity error
41H invalid port number
42H monitor mode not active
96H ring buffer overflow
97H time-out
AL = character received

The receive ring buffer is examined to determine if any
characters have been received from the specified communication
port. If a character is present, it is returned in the AL
register. If no characters have been received, the function waits
for a character until a time-out occurs. The time-out duration is
implementation specific.






(66)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Return Port Status
------------------

Function Code = 23H

Entry:
AH = function code
DX = port number

Exit:
AH = line status
AL = modem status

The line and modem status registers are read, and control is
returned to the caller. The following describes the meaning of
the bit settings in the AH and AL registers. The definition is
true if the bit is set to one.

LINE STATUS

Bits Definition
7 time-out error
6 transfer shift register
5 transfer holding register
4 break-detect error
3 framing error
2 parity error
1 overrun error
0 data ready

MODEM STATUS

Bits Definition
7 received line signal detect
6 ring indicator
5 data set ready
4 clear to send
3 delta receive line signal detect
2 trailing edge ring detect
1 delta data set ready
0 delta clear to send




















(67)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Set Monitor Mode
----------------

Function Code = 24H

Entry:
AH = function code
AL = 0 no individual status
1 individual status
DX = port number

Exit:
AH = status
0H successful
3AH illegal value in AL
41H invalid port address
64H monitor mode already on

This function sets up the specified serial port to start
accepting interrupts. Any input or output buffers are cleared.
The setting in register AL indicates how the port status is to be
maintained. A value of 0 causes the status to be maintained as a
single value. A value of 1 will maintain status for every byte in
the receive buffer.



Clear Buffers
-------------

Function Code = 25H

Entry:
AH = function code
AL = 0 clear buffers only
1 clear buffers and deactivate
DX = port number

Exit:
AH = status
0H successful
3AH illegal value in AL
41H invalid port number
42H monitor mode off

Any buffers associated with the port are cleared. If the AL
register value is one, the interrupts for the port are turned off
by resetting the PIC.













(68)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***


Return Buffer Character Count
-----------------------------

Function Code = 27H

Entry:
AH = function code
DX = port number

Exit:
AH = status
0H successful
41H invalid port number
42H monitor mode not active
AL = number of elements in input buffer

The number of characters in the input buffer are returned in the
AL register. No other action is taken on the port.










































(69)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

ISR Execution in LIM EMS
------------------------

The IRQ command also supports programs with Interrupt Service
Routines in swappable LIM memory. This includes many of the off-
the-shelf communication programs as well as many other types of
programs. This feature requires a /IRQ command line option and
two other MultiDos Plus commands.

The /IRQ command line option is used to enable this capability.
If MultiDos Plus is invoked without this option, the IRQ command
functions as documented earlier in this manual. The /IRQ option
must be followed by a hexadecimal value between 78 hex and F0
hex. This option can only be used on AT type computers. The
/IRQ tells MultiDos Plus to re-program the 8259 interrupt
controller to use the specified vectors rather than the standard
vectors at INT 8. MultiDos Plus will then intercept all the
hardware interrupts and re-vector them thru the original vectors.
This allows MultiDos Plus to check if the interrupt has been
associated with a task executing in swappable LIM memory and if
so, map the task in before vectoring to the old vector. When the
old vector ISR has finished processing, it returns to MultiDos
Plus to restore the interrupted task's memory context.

If the /IRQ option is used, the MultiDos Plus IRQ command is used
to associate a hardware interrupt to the next loaded task.

For example, suppose you want to run the popular PROCOMM terminal
emulation program in LIM memory using a modem connected to COM1.
You also determine that nothing in your system uses the interrupt
vectors 80H thru 8FH. MultiDos Plus is invoked by entering:

MULTIDOS /IRQ 80

At the $ prompt enter the following commands:

RM 300 (assuming your version of PROCOMM needs 300K)
IRQ 4 (COM 1 is IRQ 4, COM 2 is IRQ 3, etc.)
PROCOMM (assume in your current directory or PATH)

PROCOMM will be loaded in a 300K block of memory and will be
associated with IRQ 4 (INT 0CH).

Two additional commands have been defined to associate or
disassociate IRQs with tasks that have already been loaded.
These commands are SIRQ to associate and CIRQ to clear an
association. The SIRQ command will allow the association of more
than one IRQ to a task. The format for the SIRQ command is:

SIRQ task irq#

and the CIRQ command is:

CIRQ irq#

If an IRQ is already associated with a different task, SIRQ will
issue an error message.




(70)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

The assignment of IRQ 0 is not permitted.

When a task terminates, all IRQs associated with the task are
cleared.

























































(71)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Enhancing the Task Context Switch
---------------------------------

In order to provided our customers with high performance
multitasking, the task context save and restore procedures save
only the most necessary context required by most tasks. Some
applications may require that certain other context be preserved
at every task switch. An example might be several tasks which
make use of the 8087 coprocessor. Although the coprocessor can
be treated as a resource and controlled with a semaphore, this
may not be feasable (lack of source code) or practical (complex
calculations in pre-existing software). Another example might be
the saving and restoring of a software interrupt needed by
several tasks running in LIM memory.

An interface has been developed which allows applications to get
involved in the task context switch process. It is possible to
set the entry point for two routines, one to save context and the
other to restore context. The routine to restore context will be
executed just before a task is allowed to run and the routine to
save context will be executed when a task's execution is
suspended (end of timeslice, give up timeslice, read keyboard,
suspend for interval, etc.).

The two routines are global. e.g. All tasks must use the same
routines.

Since some tasks require certain context be preserved and others
do not, a flag mechanism exists to inform the context save and
restore routines if and what context, if any, should be
saved/restored. A new command, MISCFLAG, has been added which is
used to set bits in the MISCFLAG word (byte offset 200) in the
TCB. The format of the command is:

MISCFLAG

The is masked with hex 7F to keep only the lower 7
bits and is placed in the upper byte of the miscellaneous flag
word when a task is first loaded. In other words, this command
must be issued just prior to loading a task.

When MultiDos Plus saves or restores a task's context, the value
specified by the MISCFLAG command is checked for non-zero. If no
MISCFLAG command is issued prior to a task load, the default
value is zero. If a non-zero value is found, the application
supplied context routines are executed.















(72)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

As stated earlier, the context save and restore routines are
global and should probably be written as a TSR which must be
executed under MultiDos Plus and must be installed in
conventional memory. A sample TSR is supplied named APPLCTX.ASM
to save and restore floating point context for a real 8087 and/or
Microsoft floating point emulation. The TSR initialization code
informs MultiDos Plus of the two routine's entry points by
issuing a special INT 15H API call. The following code fragment
can be used to set up the entry points. It assumes that the
context save/restore routines are in the same code segment as the
code fragment.

MOV AX,1E08H ; FUNCTION AND SUBFUNCTION CODES
PUSH CS
POP DX ; SEGMENT OF ROUTINE CODE
MOV BX,OFFSET CTXSAVE ; OFFSET OF CONTEXT SAVE ROUTINE
MOV CX,OFFSET CTXRSTR ; OFFSET OF CONTEXT RESTORE ROUTINE
INT 15H

When either the save or restore routine is entered, ES:BX will be
pointing to the task in question's TCB. Care must be exercised
not to destroy any registers. When the routine is finished it
must use a far return to return control to MultiDos Plus.

The save and restore routines can be removed from execution by
executing INT 15H function 1E08H and setting the save and restore
routine entry points to null (0000:0000) pointers.

A field exists in the TCB to aid the context save/restore
routines in indexing into their context tables. The word at byte
offset 220 in the TCB has the TCB index which is a value from 0
to the number of TCBs - 1. If the default number of TCBs (12) is
configured, the largest TCB index will be 11.

If you are trying to execute several BASIC programs, you may wish
to use the APPLCTX TSR as most BASIC's use floating point.

Other possible context save/restore needs might be the 32-bit
registers in a 386 or the GDTR, LDTR, IDTR, etc. This would
allow the execution of multiple DOS extenders or 32-bit software.





















(73)


*** MultiDos Plus 4.01 Copyright (c) 1991 Nanosoft Inc. ***

Performance Improvement Tips
----------------------------

If MultiDos Plus is used in an application where you have
complete control of the source code, here are several tips which
can be used to help you gain the maximum possible performance
from the hardware which will be running your software.

Keep in mind that if a task waits for a key from the keyboard,
waits for a message from a message queue, waits for an event, or
waits for control of a resource semaphore, the task will not
receive any time until a character, message, event or control is
received. This gives more time to other running tasks doing
useful work.

Use the API function to give up your timeslice (AH = 0) where
ever possible. This function will allow another task to have a
chance to run if the current task has no useful work to perform
for the rest of a timeslice. For example, if a task was
displaying the current time on the display and checking for a
keyboard input, it should give up its timeslice at the end of the
loop if no keyboard input was received. In addition, only get
and check the time as often as realistically required. There is
no need to update the time display 18 times a second if the
resolution is in minutes!

If you are using the /PR scheduling option be sure to use the API
function to suspend a task (AH = 3) in order to give up a
timeslice. Use of the API function (AH = 0) to give up a
timeslice under this scheduling option may prohibit tasks of a
lesser priority from executing because execution is given to the
highest priority task in the READY queue.

If the default scheduling is used and you are setting different
task priorities, be sure at least one task has a priority of
zero. This will insure the maximum possible performance from the
scheduling mechanism.

If you don't need the ANSI.SYS emulation for a task, turn it off
using the NANSI MultiDos Plus command. This will eliminate the
overhead associated with this feature.

If a task will never use the display, use the ND command prior to
loading the task .EXE or .COM. Be sure to use the XQ command to
start execution immediately after the task is loaded.

If your application only requires a single task to write to the
display, use the /NO10 option to inhibit the loading of the
MultiDos Plus BIOS INT 10H replacement (MDBIO10.EXE) which would
not be necessary. This would eliminate additional overhead when
writing to the display.










(74)




  3 Responses to “Category : Alternate Operating Systems - Quarterdeck DesqView, CP/M, etc
Archive   : MULTIDOS.ZIP
Filename : MULTIDOS.PRN

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/