



















           Terminal Manager

            Multi-User DOS

           Reference Manual

             Version 3.20































Terminal Manager is an unpublished work and is the copyright of Qiiq Ltd.
The  Terminal  Manager software, and data, or documentation related thereto, and  the  information  disclosed
therein, are confidential and proprietary to Qiiq Ltd and may be used only under the terms and conditions of  a
Licence  Agreement  from Qiiq Ltd.  Neither the software, regardless of the form in which it  exists,  nor  such
data,  nor information, may be used or disclosed to others for any purpose except as specifically authorised  in
writing  by Qiiq Ltd.  The recipient, by accepting the documentation or by utilising the software, agrees to  the
terms  and conditions of the Licence Agreement and agrees that neither the software, nor the  documentation,
nor  the information disclosed therein, nor any part thereof, shall be reproduced or transferred to other  docu-
ments  nor  used  nor  disclosed to others for manufacturing or for any  other  purpose  except  as  specifically
authorised in writing by Qiiq Ltd.
(c) Copyright 1990-1995  An unpublished work by Qiiq Ltd.  All rights reserved.
Terminal Manager, TermView, TermPak and Qiiq are trademarks of Qiiq Ltd.  All other trademarks are acknow-
ledged.
Qiiq Ltd, Elm House, 17-19 Claygate Lane, Thames Ditton, Surrey, KT7 0DL, United Kingdom
Telephone +44 (0)181 339 0739 - FAX +44 (0)181 398 8443 - Email qiiq@cix.compulink.co.uk


-------------------------------------------

Contents

-------------------------------------------


1  Introduction

2  Overview of Multi-User DOS

    2.1 The RUNDOS Program and the Settings File        2-2
    2.2 The CPU Index                      2-5
    2.3 The LOCK Facility                    2-6
    2.4 The Colour Mapping Facility                2-7
    2.5 The DOS Settings Facility                 2-8

3  Installing Multi-User DOS

4  The RUNDOS Program

5  The Settings File

    5.1 The RUNDOS Section                  5-2
  The CPUINDEX Statement                 5-3
  The LOCKNAME Statement                 5-4
    5.2 The COLORMAP Section                 5-4
    5.3 The SETTINGS Section                  5-8
  The COM_DIRECT_ACCESS Statement           5-9
  The COM_HOLD Statement                 5-9
  The COM_RECEIVE_BUFFER_FLUSH Statement      5-9
  The COM_SELECT Statement                5-9
  The DOS_AUTOEXEC Statement              5-10
  The DOS_BACKGROUND_EXECUTION Statement      5-10
  The DOS_BREAK Statement                5-10
  The DOS_DEVICE Statement                5-10
  The DOS_FCBS Statement                  5-11
  The DOS_FCBS_KEEP Statement              5-11
  The DOS_FILES Statement                 5-11
  The DOS_HIGH Statement                  5-12
  The DOS_LASTDRIVE Statement              5-12
  The DOS_RMSIZE Statement                5-12
  The DOS_SHELL Statement                 5-12
  The DOS_STARTUP_DRIVE Statement           5-12

Contents


  The DOS_UMB Statement                  5-13
  The DOS_VERSION Statement                5-13
  The DPMI_DOS_API Statement               5-14
  The DPMI_MEMORY_LIMIT Statement           5-14
  The DPMI_NETWORK_BUFF_SIZE Statement        5-14
  The EMS_FRAME_LOCATION Statement          5-14
  The EMS_HIGH_OS_MAP_REGION Statement        5-15
  The EMS_LOW_OS_MAP_REGION Statement        5-15
  The EMS_MEMORY_LIMIT Statement            5-15
  The HW_NOSOUND Statement               5-16
  The HW_ROM_TO_RAM Statement             5-16
  The HW_TIMER Statement                 5-16
  The IDLE_SECONDS Statement               5-16
  The IDLE_SENSITIVITY Statement             5-16
  The INT_DURING_IO Statement              5-17
  The KBD_ALTHOME_BYPASS Statement          5-17
  The KBD_BUFFER_EXTEND Statement           5-17
  The KBD_CTRL_BYPASS Statement             5-17
  The KBD_RATE_LOCK Statement              5-18
  The MEM_EXCLUDE_REGIONS Statement         5-18
  The MEM_INCLUDE_REGIONS Statement          5-18
  The MOUSE_EXCLUSIVE_ACCESS Statement        5-19
  The PRINT_SEPARATE_OUTPUT Statement         5-19
  The PRINT_TIMEOUT Statement              5-19
  The SESSION_PRIORITY Statement             5-19
  The VGA_8514A_XGA_IOTRAP Statement          5-20
  The VIDEO_FASTPASTE Statement             5-20
  The VIDEO_MODE_RESTRICTION Statement        5-20
  The VIDEO_ONDEMAND_MEMORY Statement       5-20
  The VIDEO_RETRACE_EMULATION Statement       5-20
  The VIDEO_ROM_EMULATION Statement         5-20
  The VIDEO_SWITCH_NOTIFICATION Statement      5-20
  The VIDEO_WINDOW_REFRESH Statement         5-20
  The XMS_HANDLES Statement               5-21
  The XMS_MEMORY_LIMIT Statement            5-21
  The XMS_MINIMUM_HMA Statement            5-21

Index







                                      Contents


-------------------------------------------

Chapter 1

Introduction

-------------------------------------------

This manual is a component part of the Terminal Manager Multi-User DOS
software  package.   Multi-User  DOS is an optional add-on  facility  to  the
base  Terminal  Manager software.  This manual  describes  the  installation
and operating procedures for the Multi-User DOS software.

The Multi-User DOS package comprises the following :-

  '` The   Terminal   Manager   Multi-User   DOS   Reference
     Manual (this manual)

  '` One  3.5  inch 1.44MB diskette  containing  the  Terminal
     Manager  software,  the  Multi-User  DOS  software   and
     related files (a 5.25 inch diskette is available on request)

This  manual assumes that the reader has a working knowledge of the  OS/2
environment  and  of  personal computer operating procedures.  It  is  struc-
tured primarily as a reference manual but is also designed to take the reader
through  the process of installing and using the Multi-User  DOS  software.
It is designed to be used in conjunction with the separate Terminal Manager
- Multi-User OS/2 - Reference Manual.

Before  reading this manual, the user should have already  installed,  confi-
gured and tested the base Terminal Manager Multi-User OS/2 software.

Chapter 2 gives an overview of the Multi-User DOS software.

Chapter 3 describes the installation procedure.

Chapter  4  describes  the use of the RUNDOS command  to  execute  DOS
programs.

Chapter 5 describes the options available for configuring specific DOS set-
tings for DOS programs.




Introduction                                   1-1


We  have attempted to incorporate into this manual all the  information  re-
quired  for  successful installation and use of the Multi-User  DOS  facility,
however, should you experience any problems, please contact your supplier
who is qualified to give you full technical assistance with the product.









































1-2                                   Introduction


-------------------------------------------

Chapter 2

Overview of Multi-User DOS

-------------------------------------------

This  chapter  gives an overview of the features of  the  Terminal  Manager
Multi-User DOS facility.

Multi-User  DOS is an optional add-on facility to the base  Terminal  Man-
ager  software.  It extends the capabilities of Terminal Manager enabling  it
to run DOS software on attached terminals.

The facility is available only on computers able to run the 32-bit version  of
the OS/2 operating system i.e. version 2.0 or later.  Computers able to  run
the  required version of OS/2 include the Intel 386 and 486 family  of  pro-
cessors (including the SX versions) and the Pentium family.

Multi-User DOS uses the DOS session capability of OS/2 2.0 or later which
allows  multiple  concurrent  DOS  programs to be  run  on  a  single  OS/2
computer.

On a stand-alone OS/2 system, a DOS session may be started directly  from
an icon object in the Workplace Shell without the need to first start an OS/2
session.   Alternatively,  a  DOS  session may be  started  directly  from  an
already open parent OS/2 session.

On terminals, DOS sessions are a_l_w_a_y_s_ started from a parent OS/2  session.
When  the  program running in the DOS session terminates,  control  is  re-
turned to the OS/2 session.  The switch between DOS and OS/2 sessions  is
transparent  to the operator who need not be aware that anything  special  is
taking place.

Terminal  Manager's  ability  to  support multiple  OS/2  sessions  within  a
single  terminal  means that multiple DOS sessions may  therefore  be  con-
currently active at a terminal.







Overview Of Multi-User DOS                           2-1


-------------------------------------------
2.1  The RUNDOS Program and the Settings File

On a stand-alone OS/2 system, DOS sessions are started implicitly from  an
OS/2 session whenever the user types a DOS command.  Under Multi-User
DOS,  more control is needed over the characteristics of the DOS  program
thus necessitating a different approach.  The following considerations apply
for DOS sessions running on terminals in a multi-user environment :-

  '` Some  DOS programs may not implement file and  record  locking
     and only a single copy of these programs should be allowed to  run
     in a multi-user environment at any one time.

  '` Some  DOS programs may directly access a hardware  device,  for
     example  a  communications port, and only a single copy  of  these
     programs  should be allowed to run in a multi-user environment  at
     any one time.

  '` Because  most  DOS programs never yield  the  processor,  system
     responsiveness   may  suffer  when  multiple  DOS  programs   are
     running  on  several terminals.  In order to ensure  that  the  entire
     system  stays  responsive to all users, restrictions may  need  to  be
     placed  on the number of DOS programs that can be  run  concurr-
     ently.  Section 2.2 discusses this in more detail.

  '` Some  DOS programs are designed to run only in colour and  offer
     no  configuration option to select monochrome operation.  If  these
     programs are run on a monochrome terminal, some form of  trans-
     lation  might be necessary between the colour  attributes  displayed
     by  the  program and the monochrome attributes  expected  by  the
     terminal.  Section 2.4 discusses this in more detail.

  '` Specific  DOS  settings  may be assigned to a  DOS  program  icon
     object  in  the  Workplace Shell on the host  computer.   When  the
     user selects the icon, a DOS session is started with those character-
     istics.   Because DOS sessions started on a terminal have  no  such
     icon  object, a means of providing the DOS settings information  is
     therefore necessary.

These considerations are discussed in more detail below and in sections 2.2,
2.3, 2.4 and 2.5.

In  order to provide a mechanism to handle the above  considerations,  DOS
programs  are not executed directly from an OS/2 command  line.   Instead,

2-2                           Overview Of Multi-User DOS


the OS/2 program RUNDOS.EXE is first executed.  RUNDOS.EXE allows
the user to specify the DOS command on the RUNDOS command line,  for
example :-

  RUNDOS WP.EXE DOCS

where  WP.EXE  DOCS  is the command line that  would  normally  have  been
typed to run the DOS program.

Although  the  DOS  program must be started in this way,  it  can  be  made
transparent  to  the  user since, using the above example,  a  WP.CMD  file
could be created which would simulate the DOS command but would  ulti-
mately  call  RUNDOS with the relevant parameters.  Alternatively,  if  the
system  is  driven by menus, a menu choice could  execute  the  appropriate
RUNDOS command transparently to the operator.

The  example  above would execute the DOS program with  no  more  addi-
tional control than would have been available without the use of  RUNDOS.
The  additional power of RUNDOS is invoked by specifying a Settings  File
as the first parameter of the RUNDOS command, for example :-

  RUNDOS /S WPSETNGS WP.EXE DOCS

where /S tells RUNDOS that a Settings File with the name WPSETNGS is to be
associated  with the WP.EXE program.  Again, the actual command  would
normally  be invoked by a .CMD file or from a menu choice.  The  Settings
File  is  discussed  in  detail  in  chapter  5  while  chapter  4  discusses  the
RUNDOS command.

If no DOS command line is specified for RUNDOS, a DOS session is  star-
ted with a DOS command prompt from which other DOS programs may  be
run.

Many  DOS programs are written to run in a stand-alone  environment  and
make  the  assumption that all resources, including files,  hardware  devices
etc, are for use solely by the program itself.  These programs will tend  not
to  employ  file and record locking procedures.  When run  in  a  multi-user
environment,  whether it be on a network or under Multi-User  DOS,  these
programs  can  present  problems if two or more instances  of  the  program
attempt to access the same file or resource.

To overcome this problem, Multi-User DOS provides a locking  mechanism
which prevents DOS programs from being run while another DOS program
is  running which might also be accessing common resources.  The  locking

Overview Of Multi-User DOS                           2-3


mechanism  is  provided in the RUNDOS Settings File and  is  described  in
section 2.3.

DOS  programs running under OS/2 are treated in much the same way as  a
native  OS/2  program in terms of processor scheduling.  The  program,  or
rather  the  thread  under which the program operates, has  a  priority  level
attached  to  it.   If there are no other threads in the  system  with  a  higher
priority,  the  thread  will be allowed to run.  When the  thread  runs,  it  is
allocated  a  time slice of a fixed duration.  Most native  OS/2  threads  will
tend  to yield the processor before the end of their time slice  because  some
event  they  rely upon has not yet occurred.  However, DOS  programs  are
generally  unable  to  participate in this cooperative  multi-tasking  and  will
continue  executing  until their time slice expires,  generally  looping  while
waiting  for  an event to occur.  In general, DOS programs do  tend  to  de-
crease  overall system responsiveness and, where possible, the  fastest  pro-
cessor available should be used if DOS programs are to represent the major
workload of the system.

The  Multi-User  DOS facility attempts to mitigate against  any  undesirable
behaviour  by monitoring the program's keyboard input operations in  order
to determine whether a program has entered an idle loop waiting for  input.
In this situation, Multi-User DOS yields the processor on behalf of the DOS
program.  Multi-User DOS is only able to do this for keyboard  operations.
If  the  program  is looping while waiting for some other  event,  such  as  a
hardware  condition, Multi-User DOS is unable to detect this idle  loop  and
the  program  will  run  to the end of its time  slice  taking  up  unnecessary
processor  cycles.  Similarly, if the DOS program is in a computation  pro-
cess, it will again soak up all of its allocated time slices.

It  can be seen from the above that each DOS program will have a  different
impact  on processor usage depending on its operational characteristics  and
the task it is performing.

The Settings File used in RUNDOS allows the user to allocate a figure  that
represents an index of the processor usage for a DOS program.  This  value
is known as the CPU index and is described in section 2.2.

Each  DOS  session under OS/2 has a series of DOS Settings which  can  be
viewed  and  changed at runtime by opening the Settings  Notebook  for  the
session.   When  a DOS session is first started, initial DOS Settings  can  be
assigned  for  the  new session.  The RUNDOS Settings  File  provides  the
mechanism  to  define  the DOS Settings for the session  in  which  the  new
program will be run.  This feature is discussed in detail in section 2.5.


2-4                           Overview Of Multi-User DOS


-------------------------------------------
2.2  The CPU Index

Native OS/2 programs are written taking into account the fact that the  CPU
is  being  used to run other applications concurrently.   One  common  DOS
programming practice, outlawed in OS/2, is that of looping while  constant-
ly  testing  for an event to occur; this technique is known  as  polling.   The
OS/2  operating  system  provides mechanisms which  obviate  the  need  to
employ  polling  for native OS/2 programs.  An OS/2 program  thus  never
actively  waits for an event, instead, it is suspended until the  event  occurs,
thus taking up no CPU time during the waiting period.

DOS programs, on the other hand, are generally written to assume that they
are  the only program running in the CPU and most employ polling  techni-
ques.   On  a single-tasking DOS machine, this does not present  a  problem
since  the  CPU has nothing else to do during the waiting time in  any  case.
However,  when  these programs are run in DOS sessions under  OS/2,  the
polling takes its toll and, on all but the fastest machines, CPU  performance
can appear sluggish when multiple DOS programs are being run.  This ap-
plies  to  DOS  programs  whether  running  on  terminals  under  Terminal
Manager or directly on the host machine console.

On a single-user OS/2 system, the operator is in complete control of  which
programs are being run and can decide not to run any more DOS  programs
if  responsiveness suffers.  On a multi-user system however, no one user  is
able  to  know which other DOS programs are running.  If too  many  users
decide  to  run DOS programs, performance can decrease  for  other  users,
even those running native OS/2 programs.

To  overcome  this  problem, each DOS program may be  assigned  a  CPU
index  value  indicating  its  level of CPU usage.  This  value  is  set  in  the
RUNDOS  Settings  File.  The CPUINDEX statement in  the  Settings  File
specifies the CPU index for the DOS program.

Terminal  Manager maintains a count of the total CPU index values  for  all
DOS programs running at any one time.  Whenever a new DOS program is
started,  Terminal Manager adds the program's CPU index to the  total  and
compares  the  new total with a user-defined maximum limit.  This  limit  is
defined  in  the DOSCPULIMIT statement in the SYSTEM  section  of  the
TRMMAN.INI  file.   The  TRMMAN.INI  file  and  the  DOSCPULIMIT
statement  are described in the separate manual Terminal Manager  -  Multi-
User  OS/2 - Reference Manual.  If the DOSCPULIMIT value is  exceeded,
a  message is displayed to the terminal operator and the running of the  new
DOS  program is suspended until either the operator elects to end the  pro-

Overview Of Multi-User DOS                           2-5


gram, or until another DOS program exits and reduces the total CPU  index
to a value which does not exceed the DOSCPULIMIT value.

-------------------------------------------
2.3  The LOCK Facility

Many  DOS  programs access files without using the DOS  file  and  record
locking  facilities.   Similarly,  some  programs  directly  access   hardware
devices such as the communication ports.

These  programs work fine in a single-user, stand-alone environment,  since
no  other  program  is  able to access the  resources  while  the  program  is
running.

Problems  may  occur  whenever these programs are used in  a  network  or
multi-user environment since two or more copies of the program might  run
at  the  same  time and attempt to access the  same  resource.   In  addition,
other programs, possibly from the same suite or application package, might
also attempt to access the resource concurrently.

One  solution  to  this problem is to rewrite the programs  to  use  the  DOS
locking  mechanisms.   Under  OS/2 these mechanisms  are  translated  into
OS/2's  own  locking mechanism making it safe to mix  the  programs  with
any other programs, even native OS/2 programs.

However, it is not always possible to rewrite the offending program.   Very
often,  the  program may be an off-the-shelf package for  which  the  source
code  is not provided.  In any case, even if the source code were  available,
the relevant technical expertise might not be available to make the changes.

Some  DOS programs allow the user to configure the program for  network
use.   If  this  option  is available, it will generally  solve  the  problem  and
allow  the  program  to  be  used in  a  multi-user  environment.   The  user
should, however, perform tests to ensure that multi-user operation is secure
for these programs.

If  other  options fail, Multi-User DOS offers a facility to  ensure  that  data
cannot  be  corrupted or hardware resources cannot be accessed  by  two  or
more programs running concurrently.

Multi-User  DOS allows the user to specify a Lock Name in  the  RUNDOS
Settings  File.   Several RUNDOS files for separate  DOS  programs  might
specify the same Lock Name if they are likely to access the vulnerable  files
or resources.

2-6                           Overview Of Multi-User DOS


When  a  DOS program is run using RUNDOS,  Multi-User  DOS  ensures
that no other program is currently running where the same Lock Name  was
specified  in its RUNDOS Settings File.  In other words,  Multi-User  DOS
allows only one program at a time to own the lock called Lock Name.

If  the  lock  is  already owned by another  program,  RUNDOS  displays  a
message and suspends execution of the new program until either the  opera-
tor  elects  to  cancel  the program or until  the  program  owning  the  lock
terminates.

This  mechanism  allows for serial access to vulnerable  resources  by  pro-
grams  which  implement  no locking procedures.  Although  it  means  that
only  one  program which uses those resources can run at any  one  time,  it
does allow any terminal on the system to run those programs while  protect-
ing the integrity of the vulnerable resource.

-------------------------------------------
2.4  The Colour Mapping Facility

Some  DOS  programs  display their output in colour  when  running  under
OS/2.   When these programs are run on colour terminals, e.g. a  DOS  PC
running  the TERM.EXE program, the colour is generally faithfully  repro-
duced at the terminal.

However,  some DOS PCs used as terminals might interpret  certain  colour
attributes  differently.   For  example, some DOS PCs  might  interpret  the
flashing  attribute  as  meaning that a bright  background  colour  should  be
displayed.

For  monochrome  dumb  terminals, the attribute  values  displayed  by  the
program  will  not  necessarily  correspond to  visible  or  sensible  attribute
combinations on the terminal.

For  these  reasons, Multi-User DOS provides the capability  of  defining  a
translation  from  the  attribute  displayed by the  program  to  a  value  that
produces an acceptable display on the terminal.

The  RUNDOS  Settings File allows the user to specify  the  translation  re-
quired.   Since the Settings File may be associated with an  individual  pro-
gram,  different  colour translations may be applied to  different  programs.
The TRMATTR program, described in the Terminal Manager -  Multi-User
OS/2  -  Reference Manual, may be used as an aid to  determining  the  ap-
propriate colour translation for a specific DOS program.


Overview Of Multi-User DOS                           2-7


-------------------------------------------
2.5  The DOS Settings Facility

OS/2's  DOS  session  facility  provides an extensive  array  of  options  for
configuring the environment in which DOS programs run.  This is  because
many  DOS  programs are sensitive to certain DOS  versions,  DOS  exten-
sions  or hardware characteristics.  These all need to be emulated  by  OS/2
in order for the program to believe that it is running in the true DOS envir-
onment for which it was designed.

When  a  DOS program is set up as an icon object in the  Workplace  Shell,
the  Session  page  of  the object's settings menu has  a  DOS  settings  push
button which brings up a dialog box for viewing and modifying the  various
options that define the program's DOS environment.  When the icon  object
is used to run the program, these settings will apply for the DOS session  in
which the DOS program is run.

When a DOS program is run on a terminal under the Multi-User DOS facil-
ity, it is clearly not possible to run the DOS program from a pre-configured
icon  object.   However, DOS programs running at terminals still  have  the
need  to  have their environment tailored to their design  requirements.   To
allow  the  DOS  settings  to  be  configured  for  a  terminal  program,  the
RUNDOS Settings File is used to define the same options as would be set in
the icon object's settings dialog box.

If the RUNDOS Settings File omits any or all of the options, a default value
is used.  This default value can be ascertained from an icon object's settings
dialog box and is listed in section 5.3.

The icon object's DOS settings options are described in the OS/2  documen-
tation and in the online help for the dialog box.

Section 5.3 details each of the options and the acceptable settings for each.












2-8                           Overview Of Multi-User DOS


-------------------------------------------

Chapter 3

Installing Multi-User DOS

-------------------------------------------

Multi-User DOS is installed using the Terminal Manager TINSTALL  pro-
gram.

The  installation  procedure  installs a full copy  of  the  Terminal  Manager
software  to ensure compatibility with the Multi-User DOS  software.   The
installation  procedure will only install the Multi-User DOS software  if  the
computer is running OS/2 2.0 or later.

Before installing Multi-User DOS, you must have successfully installed  the
base Terminal Manager system.

If  you  ordered Terminal Manager together with the  Multi-User  DOS  op-
tion,  the  appropriate Multi-User DOS files will have been  installed  when
you  installed  the  base Terminal Manager system.   In  this  case,  nothing
further need be done for you to use the Multi-User DOS facilities.

If  you  ordered  Multi-User  DOS as an upgrade  to  an  existing  Terminal
Manager  system,  you will need to run the TINSTALL program  from  the
Multi-User DOS diskette.  This will install the latest version of the  Termi-
nal Manager software in addition to the Multi-User DOS software.

The  installation program, TINSTALL, must be started from the  command
prompt  in  a  full-screen session on the host computer.   You  must  ensure
that  Terminal  Manager  is  not running when  you  run  the  TINSTALL
program.

To start a full screen session :-

1) Press  Ctrl+ESC  to display the Window List  window  of  Presentation
  Manager.
2) From the  Window List window, double click on the Desktop option.
3) From the Desktop, double click on the OS/2 System icon.
4) From the OS/2 System window, double click on the Command Prompts
  icon.
5) From  the  Command Prompts window, double click on the  OS/2  Full
  Screen icon.

Installing Multi-User DOS                             3-1


If  a previous version of Terminal Manager already exists on the  computer,
TINSTALL  may  fail with an error message while trying to  copy  the  file
TRMMAN.MSG.  This occurs because of a problem in OS/2 which  causes
the existing TRMMAN.MSG file on the hard disk to be permanently locked
and  thus  unable to be replaced by the new TRMMAN.MSG  being  copied
by  TINSTALL.   OS/2  2.11 and later versions appear  to  have  fixed  the
problem,  however, you should wait for at least 5 minutes after booting  the
system  before  installing Terminal Manager or the Multi-User  DOS  soft-
ware.

To overcome the problem on other versions of OS/2, you must remove  the
Terminal Manager DEVICE statements from the CONFIG.SYS file located
on  the boot drive.  The statements in CONFIG.SYS will appear  similar  to
the following :-

  DEVICE=C:\TRMMAN\TRMINT.SYS
  DEVICE=C:\TRMMAN\TRMMAN.SYS
  DEVICE=C:\TRMMAN\TRMDOS.SYS

The  OS/2 system editor may be used to remove the statements.   The  third
line  will  only be present if you have already  installed  Terminal  Manager
and the Multi-User DOS facility.

After  modifying CONFIG.SYS, you should re-boot the computer and  then
resume  the  re-install  of Terminal Manager.  The  computer  must  be  re-
booted for the modifications to CONFIG.SYS to become effective.

The  Terminal  Manager  diskette must be inserted into  the  diskette  drive,
usually  drive A, and the following command must be entered at  the  com-
mand prompt, followed by the ENTER key:-

  A:TINSTALL /R

The  TINSTALL program installs the Terminal Manager software  and  the
Multi-User  DOS  software into a directory called TRMMAN  on  the  boot
drive;  the boot drive is normally drive C.  Before proceeding,  TINSTALL
displays  a  message and waits for the ENTER key to be  pressed;   pressing
the ESC key at this point will terminate the installation procedure.

If  you  are  installing  on a system that already  has  Terminal  Manager,  a
warning message will be displayed reminding you that the DEVICE  state-
ments  should  be removed from CONFIG.SYS as  described  above.   You
may press ESC to exit or ENTER to continue with the installation if you are
sure that the statements have been removed from CONFIG.SYS.

3-2                             Installing Multi-User Dos


TINSTALL  copies  the Terminal Manager files and  the  Multi-User  DOS
files  from  the diskette into the TRMMAN directory and then  modifies  or
adds certain statements to the CONFIG.SYS file in the root directory of the
boot  drive.   When TINSTALL has successfully completed,  the  computer
must be re-booted before the changes made to CONFIG.SYS become effec-
tive.

Whilst modifying CONFIG.SYS, TINSTALL creates a temporary file  with
the  name  CONFIG.$$$  and renames the existing  CONFIG.SYS  file  to
CONFIG.BAK.   After  the installation is completed,  TINSTALL  deletes
the CONFIG.$$$ file.

Chapter  3  of the separate manual Terminal Manager - Multi-User  OS/2  -
Reference  Manual  discusses the Terminal Manager installation  process  in
some detail.

The  TINSTALL program does not make any changes to the PATH  state-
ment  in  CONFIG.SYS.  If you wish to access any of the programs  in  the
TRMMAN directory whilst logged into other drives or directories, you will
need to ensure that the TRMMAN directory is included in the PATH state-
ment; this may be achieved either by setting it in CONFIG.SYS or by using
the SET command, possibly in a batch file.























Installing Multi-User DOS                             3-3















































3-4                             Installing Multi-User Dos


-------------------------------------------

Chapter 4

The RUNDOS Program

-------------------------------------------

As described in chapter 2, DOS programs are run from a parent OS/2  ses-
sion by issuing the OS/2 command RUNDOS.

RUNDOS.EXE  is  a  native OS/2 program which  reads  the  Settings  File
specified  on  the RUNDOS command line and starts a DOS  program  in  a
DOS session configured according to the DOS settings contained in the Set-
tings File.

The  RUNDOS  command and its parameter string are best  placed  into  an
appropriately named .CMD file so that it is transparent to the operator  that
RUNDOS  is  being  executed first.  The operator is thus  able  to  type  the
same  command  as  would  be  typed on a  DOS  or  OS/2  command  line.
Alternatively,  the  RUNDOS  command might be  executed  from  a  menu
choice.

The format of the RUNDOS command is :-

  RUNDOS {/S <Settings File>} {<DOS program> {<DOS program parameters>}}

where the elements within braces {...} are optional.  <Settings File> speci-
fies the file name and optional path of the Settings File; if no file  extension
is  given,  a  default extension of .SET is assumed.  If  no  Settings  File  is
specified, RUNDOS runs the DOS program using the default DOS  settings
without  performing  any check on lock names or on the  total  CPU  index.
<DOS  program>  is the file name, including the extension, of  the  DOS  pro-
gram  to be run in the new DOS session.  If the DOS program is not in  the
current  default  directory,  the full drive and path must  also  be  specified.
<DOS program parameters> represents the parameter string that would  norm-
ally be typed on the DOS command line for the program.

If  <DOS  program>  and <DOS program> parameters are  not  specified  on  the
RUNDOS  command  line, a DOS session is started with a  DOS  command
prompt from which other DOS programs may be run.  In this situation, if  a
Settings File is specified on the RUNDOS command line, any DOS  settings
in  the Settings File will apply to all programs run from the DOS  command
prompt.

The RUNDOS Program                              4-1


The following is an example of the use of the RUNDOS command :-

  RUNDOS /S WPSETNGS C:\PROGS\WP.EXE REPORT.DOC

where  WPSETNGS specifies the Settings File WPSETNGS.SET in the  current
directory, C:\PROGS\WP.EXE is the DOS program to be run and REPORT.DOC  is
the parameter string for the WP.EXE program.

If  any errors are detected in the Settings File, a diagnostic message is  dis-
played generally detailing the line number and position in the line where the
error  was  detected.   Some  errors are considered  fatal  and  the  program
terminates  without  running the DOS program.  If the errors  are  less  ser-
ious,  the program continues processing the Settings File and  then  displays
the following message :-

  Press ENTER to continue or ESC to exit:

The  user may then decide whether the errors displayed are likely  to  cause
problems should the DOS program continue and may press the ESC key  to
exit.   If  the errors are unlikely to cause a problem,  pressing  the  ENTER
key  will continue to run the DOS program.  Chapter 5 details  the  sections
and statements available in the Settings File.

If  a  lock name was specified in a LOCKNAME statement  in  the  Settings
File,  RUNDOS  ensures  that the lock is not currently  in  use.   If  another
program  in the system currently owns the lock, the following  messages  is
displayed :-

  The DOS program is currently in use -
          please wait or press ENTER to exit:

RUNDOS  then waits until the program owning the lock terminates and  the
lock becomes free or until the user presses the ENTER key to exit the pro-
gram.

If  the Settings File contained a CPUINDEX statement, RUNDOS adds  the
CPUINDEX  index value to the total index of all DOS  programs  currently
running.  If the new total exceeds the maximum specified in the DOSCPU-
LIMIT  statement in the TRMMAN.INI file, the following message is  dis-
played :-

  Too many DOS programs are active -
          please wait or press ENTER to exit:


4-2                              The RUNDOS Program


RUNDOS  then  waits until one or more of the currently  active  DOS  pro-
grams  terminate  and  reduce the total index value to a level  that  does  not
exceed  the DOSCPULIMIT value.  When this occurs, RUNDOS will  then
start  the  new DOS session with the command specified  on  the  RUNDOS
command  line.   While  RUNDOS is waiting for the  CPU  index  value  to
decrease, the user may press ENTER at any time to terminate the process.

If RUNDOS is started with no DOS program name or parameters specified,
but with a Settings File that contains the LOCKNAME and/or  CPUINDEX
statements,  the  statements are effective only for the initial  running  of  the
COMMAND.COM  program  in the DOS session.   Any  programs  started
from within the session are not subject to the LOCKNAME or CPUINDEX
control.

The DOS session terminates when the requested DOS program ends.  If the
session was started with a DOS command prompt because no DOS program
name  was specified, the operator must type the EXIT command to end  the
COMMAND.COM  program  implicitly started when the session  was  cre-
ated.    When  the  DOS  session  terminates,  RUNDOS   regains   control,
decrements  any CPU index value, frees up any owned lock and  exits  after
displaying  any  error conditions encountered while running the  DOS  pro-
gram.























The RUNDOS Program                              4-3















































4-4                              The RUNDOS Program


-------------------------------------------

Chapter 5

The Settings File

-------------------------------------------


The  Settings File is used by the RUNDOS program to control  the  running
of  DOS programs and to define the DOS session settings under  which  the
DOS program will run.

The  Settings  File is specified in the /S parameter of the  RUNDOS  com-
mand, for example :-

  RUNDOS /S WPSETNGS WP.EXE

In  the  above  example, WPSETNGS is specified as  the  Settings  File  for
running  the  WP.EXE  program.  The Settings File name  may  be  a  fully
qualified  OS/2 file name i.e. it may include a drive and  multiple  directory
names.   If  no  qualified path is specified, the file must  be  located  in  the
current default directory.  A file extension may be specified if required.   If
no  extension is given, an extension of .SET is assumed.  The Settings  File
in  the  above example would therefore be the file  WPSETNGS.SET  from
the current default directory.

The  Settings File is an ASCII format text file and may be created  or  mod-
ified  using the OS/2 system editor E.EXE or any other text editor or  word
processor able to handle ASCII text files.

The  Settings  File is structured in the standard format of .INI files  as  used
by  other  components  of  Terminal Manager  e.g.  TRMMAN.INI.   It  is
divided  into a number of sections each starting with a keyword enclosed  in
square  brackets  '[.....]'.  Within each section a number of  statements  are
specified,  each  starting  with a keyword followed  by  a  parameter  value.
The file may contain comment lines starting with the ';' character; anything
following  the  ';' character on any line of the file is treated  as  a  comment
and  is not used by RUNDOS.    Blank lines are ignored and may be  inser-
ted to aid readability.

The  file  must  contain at least the RUNDOS section  described  below,  al-
though  no  statements  need be contained in  the  RUNDOS  section  itself.
This  allows  the RUNDOS program to verify that the named file  is  a  Set-

The Settings File                                 5-1


tings  File  created for RUNDOS.  The RUNDOS section must be  the  first
section  in  the  file, although it need not start on the first  line  of  the  file.
Other sections of the file can appear in any desired order.

The following section keywords are permissible :-

  [RUNDOS]  contains statements for defining the CPU index value  and
          the Lock Name.

  [COLORMAP] contains  statements  defining  the  translation  of  colours
          used  by  the DOS program into colours  suitable  for  the
          attached terminal.

  [SETTINGS] contains statements that define the DOS Setting values  for
          the DOS session.

Each  of the sections and the statements contained in them are  described  in
the following pages.


-------------------------------------------
5.1  The RUNDOS Section

The  RUNDOS section must be present in every Settings File and  must  be
the  first section in the file.  It need not start on the first line of the file  and
may be preceded by blank lines or comments.  The RUNDOS program uses
the  presence  of  the RUNDOS section to verify that it is  a  valid  Settings
File.

The statements in the RUNDOS section are optional and if not required, the
RUNDOS  section will be a blank section containing just the  section  key-
word  itself  followed by the next section keyword if there are  further  sec-
tions, for example :-

  [RUNDOS]
  [SETTINGS]
    .
    .
    .

The  format  of  the RUNDOS section is described  below.   The  keywords
representing each statement may be given in any desired order.



5-2                                 The Settings File


  [RUNDOS]

  CPUINDEX=  specifies  the  CPU index value to be associated  with  the
          DOS program
  LOCKNAME=  specifies  the  name of the lock to be  associated  with  the
          DOS program

The following sections describe each of the above keywords in detail.

The CPUINDEX Statement

The  CPUINDEX statement specifies a value which is to be associated  with
the  DOS  program and is used to limit the number of DOS  programs  run-
ning.   This  ensures that overall system responsiveness is not  degraded  by
too many DOS programs running concurrently.

Section  2.2 discusses the operation of Multi-User DOS with respect  to  the
CPUINDEX setting.

The parameter following the statement keyword is a decimal number in  the
range  1  through  65535.   The  value is relative to  the  value  set  for  the
DOSCPULIMIT  statement in the SYSTEM section of  the  TRMMAN.INI
file.

Effectively,  DOSCPULIMIT defines the absolute maximum  proportion  of
the  CPU  time to be used to run DOS programs.  The  CPUINDEX  values
for  all  currently running DOS programs are never allowed  to  exceed  the
DOSCPULIMIT  value.   For  this feature to work  effectively,  each  DOS
program  to  be run on the system should be assigned a  CPUINDEX  value
which  describes  its  processor  usage in  relation  to  the  DOSCPULIMIT
value.   The CPUINDEX value is determined empirically by  analysing  the
effect  that  the  DOS  program  exhibits  on  overall  system  performance.
Where  possible, it helps to run multiple instances of the program to  multi-
ply its effect on processor usage.  Although this can be done on the  console
of the host computer, it is best done on terminals since the Multi-User DOS
optimisation logic might have an effect on the terminal which would not  be
seen  on the host console.  Additionally, if multiple instances are being  run
on  terminals to determine the CPUINDEX value, they should all  be  fore-
ground sessions on the terminals, since Multi-User DOS lowers the priority
of any background DOS sessions to minimise processor overhead.

The following is an example of the use of the CPUINDEX statement :-

  CPUINDEX = 10

The Settings File                                 5-3


If the CPUINDEX statement is omitted, Multi-User DOS will run the  DOS
program  without  any reference to the DOSCPULIMIT value  specified  in
the SYSTEM section of the TRMMAN.INI file.

The LOCKNAME Statement

The  LOCKNAME  statement specifies the name of a lock to  be  associated
with  a program or a group of related programs which might access  a  vul-
nerable resource without using any DOS locking mechanisms.

Multi-User  DOS  ensures that only one program at a time  associated  with
the lock is able to run in the system.  Section 2.3 discusses the operation  of
Multi-User DOS with respect to the LOCKNAME setting.

The parameter following the statement keyword is a string of up to 65 char-
acters in length.  The string must not contain any spaces and must comprise
a mix of just the characters A-Z, 0-9 and the underline character '_'.

The following is an example of the use of the LOCKNAME statement :-

  LOCKNAME = ACCOUNTS

If  the  LOCKNAME  statement is omitted,  Multi-User  DOS  imposes  no
locking restriction on the program.

-------------------------------------------
5.2  The COLORMAP Section

The  COLORMAP section is used to specify the translation of colours  used
by the DOS program into colours suitable for displaying on the terminal.

This  colour  mapping operation is particularly  useful  where  monochrome
terminals are being used to run DOS programs which are running in  colour
mode.   Some  DOS  programs  can  be  configured  directly  to  operate  in
monochrome mode.  Where this is possible, it is preferable to use this facil-
ity  of  the DOS program if it produces the desired result  on  the  terminal.
The TRMATTR program, described in the Terminal Manager -  Multi-User
OS/2  -  Reference Manual, may be used as an aid to  determining  the  ap-
propriate colour translation for a specific DOS program.

The  statement keywords in the COLORMAP section are descriptive of  the
foreground  and  background  colour settings being displayed  by  the  DOS
program.  Each statement is in the form :-


5-4                                 The Settings File


  <original colour> = <new colour>

where  <original  colour>  is that displayed by the  DOS  program.   <new
colour>  may  be  any of the colours specified  for  <original  colour>,  for
example :-

  GREEN_ON_BLACK = WHITE_ON_BLUE

would  translate all characters displayed in a foreground colour of green  on
a background of black into a foreground of white on a background of blue.

Alternatively,  <new  colour>  may specify  a  combination  of  monochrome
attribute settings :-

  REVERSE  specifies  that  the character will be  displayed  in  reverse
          video i.e. black on a white background.

  NORMAL   specifies  that  the character will be  displayed  in  normal
          video i.e. white on a black background

  BLANK    specifies that the character will be displayed as hidden i.e.
          black on a black background

  BLINK    may  be  used  in combination with reverse  or  normal  to
          cause the character to blink.  The blinking will only occur
          if  the  terminal hardware supports the blink  function.   If
          the terminal is a DOS PC using the TERM.EXE program,
          the blink attribute is sometimes interpreted as high  intens-
          ity background.

  BRIGHT   may  be  used  in combination with reverse  or  normal  to
          cause  the  foreground to be displayed  in  high  intensity.
          This will only occur if the terminal hardware supports the
          high intensity function.

  UNDERLINE  may  be  used  in combination with reverse  or  normal  to
          cause the character to be underlined.  This will only occur
          if  the terminal hardware supports the underline  function.
          If  the terminal is a DOS PC using the  TERM.EXE  pro-
          gram,  the underline attribute may be displayed as  a  blue
          foreground.

The  format  of  a statement using the monochrome attribute  settings  is  as
follows :-

The Settings File                                 5-5


  <original colour> = <mono attr> { + <mono attr> }

where the parameters within the brace characters {...} may be repeated 0 or
more  times.   <mono attr> represents one of the  monochrome  settings  de-
scribed above, for example :-

  WHITE_ON_BLUE = NORMAL
  WHITE_ON_RED = NORMAL + BRIGHT + UNDERLINE

All  the  statements  in the COLORMAP section are  optional  and  for  any
which  are  not  specified,  no colour mapping will  be  performed  for  that
colour combination.

The  display  attribute  byte  used by the DOS  program  has  the  following
format, where bit 0 is the least significant bit in the byte :-

  BitMeaning

  0 foreground blue
  1 foreground green
  2 foreground red
  3 foreground intensity
  4 background blue
  5 background green
  6 background red
  7 background intensity (or on some systems foreground blink)

These  bit settings combine together to form the following  background  and
foreground colours for the following values of the display attribute byte.

Attribute  Colour               COLORMAP Name

xxxx0000  black foreground          BLACK_ON_bbb
xxxx0001  blue foreground          BLUE_ON_bbb
xxxx0010  green foreground          GREEN_ON_bbb
xxxx0011  cyan foreground          CYAN_ON_bbb
xxxx0100  red foreground           RED_ON_bbb
xxxx0101  magenta foreground         MAGENTA_ON_bbb
xxxx0110  brown foreground          BROWN_ON_bbb
xxxx0111  white foreground          WHITE_ON_bbb
xxxx1000  light black foreground        LIGHTBLACK_ON_bbb
xxxx1001  light blue foreground        LIGHTBLUE_ON_bbb
xxxx1010  light green foreground        LIGHTGREEN_ON_bbb
xxxx1011  light cyan foreground        LIGHTCYAN_ON_bbb

5-6                                 The Settings File


xxxx1100  light red foreground         LIGHTRED_ON_bbb
xxxx1101  light magenta foreground      LIGHTMAGENTA_ON_bbb
xxxx1110  light brown foreground (yellow)   LIGHTBROWN_ON_bbb
xxxx1111  light white foreground        LIGHTWHITE_ON_bbb

0000xxxx  black background          fff_ON_BLACK
0001xxxx  blue background          fff_ON_BLUE
0010xxxx  green background          fff_ON_GREEN
0011xxxx  cyan background          fff_ON_CYAN
0100xxxx  red background           fff_ON_RED
0101xxxx  magenta background        fff_ON_MAGENTA
0110xxxx  brown background         fff_ON_BROWN
0111xxxx  white background          fff_ON_WHITE
1000xxxx  light black background        fff_ON_LIGHTBLACK
1001xxxx  light blue background        fff_ON_LIGHTBLUE
1010xxxx  light green background       fff_ON_LIGHTGREEN
1011xxxx  light cyan background        fff_ON_LIGHTCYAN
1100xxxx  light red background        fff_ON_LIGHTRED
1101xxxx  light magenta background      fff_ON_LIGHTMAGENTA
1110xxxx  light brown background (yellow)   fff_ON_LIGHTBROWN
1111xxxx  light white background        fff_ON_LIGHTWHITE


The  xxxx  represents  any value for these  bit  settings.   The  COLORMAP
Name  column  gives the name of the foreground/background colour  to  be
used  in  the keyword statements in the COLORMAP section.   The  colour
names are in the form :-

  <foreground colour>_ON_<background colour>

The  bbb in the above table must therefore be replaced with the  appropriate
background colour and the fff must be replaced with the appropriate  fore-
ground colour.  The foreground/background colour expressed by the colour
name  may  also be used as the <new colour> parameter of the  statement  as
described earlier.

The  colour  names use the 'LIGHT' prefix applied to the  base  colour  for
consistency, for example, a yellow foreground on a grey background would
be  LIGHTBROWN_ON_LIGHTBLACK.   Similarly,  if the  system  or  a
terminal  interprets bit 7 as foreground blink instead of  background  intens-
ity,   a  white  blinking  foreground  on  a  brown  background   would   be
WHITE_ON_LIGHTBROWN.



The Settings File                                 5-7


-------------------------------------------
5.3  The SETTINGS Section

The  SETTINGS section allows the user to define the DOS Settings  for  the
session in which the program will run.  Section 2.5 discusses the use of  the
SETTINGS section.

Each  statement  in the SETTINGS section corresponds to an option  in  the
dialog  box displayed from the Session page of the Settings menu of a  DOS
program icon object in the Workplace Shell.

The  parameter  following the statement is generally the same as  would  be
entered in the Settings dialog box.  However, purely for syntactical reasons,
a  number  of them differ slightly.  The following sections give a  brief  de-
scription  of each of the statements but a full description of each  is  outside
the  scope  of this manual.  The OS/2 documentation and  the  OS/2  online
help  should  be consulted for further information on the use of each  of  the
DOS settings.  Each statement is specified in the form :-

  <dos setting> = <parameter>

where <dos setting> is one of the statement keywords described below  and
<parameter> is as detailed in the description for the statement.  An  example
is given to demonstrate the use of each statement.

If any of the statements is omitted, the default for that statement is  assumed
as detailed in the description.

Some of the statements take a string parameter enclosed by single or double
quote  delimiters.   For some statements, the string may  need  to  represent
several lines of text.  Because each statement in the Settings File is termina-
ted by a new line character, the new line character cannot be included in the
string parameter.  To overcome this limitation, a pseudo new line  character
may  be entered into the string.  The value of this character is  decimal  254
and  usually  appears  as a ''`' character.  The character can  be  entered  in
most text editors by keeping the ALT depressed while entering the keys '2',
'5' and '4' from the numeric keypad and then releasing the ALT key.

The COM_DIRECT_ACCESS Statement

This  statement  allows  the  DOS  program  to  have  direct  access  to  the
communication ports if the parameter ON is specified.  A parameter value of
OFF causes OS/2 to emulate the action of the port.


5-8                                 The Settings File


  COM_DIRECT_ACCESS = OFF

The default value is OFF.

The COM_HOLD Statement

This  statement  tells OS/2 to hold the communication ports  open  until  the
session  ends if ON is selected.  A parameter value of OFF releases a  port  as
soon as a program using it ends.

The following is an example of the use of this statement :-

  COM_HOLD = OFF

The default value for this statement is OFF.

The COM_RECEIVE_BUFFER_FLUSH Statement

This  statement  tells  OS/2 how to handle data in  the  communication  port
receive buffer.  The valid parameter values for this statement are :-

  ALL
  RECEIVE_DATA_INTERRUPT_ENABLE
  SWITCH_TO_FOREGROUND
  NONE

Note  that  the parameter values above include the  underline  character  '_'
between  the individual words; this differs from the value in Settings  dialog
box.

The following is an example of the use of this statement :-

  COM_RECEIVE_BUFFER_FLUSH = RECEIVE_DATA_INTERRUPT_ENABLE

The default value for this statement is NONE.

The COM_SELECT Statement

This statement is used to limit the DOS program's access to communication
ports.  The parameter value specifies which port or ports the program is al-
lowed to access.  The valid parameter values are :-

  ALL
  COM1

The Settings File                                 5-9


  COM2
  COM3
  COM4
  NONE

The following is an example of the use of this statement :-

  COM_SELECT = COM1

The default value for this statement is ALL.

The DOS_AUTOEXEC Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The DOS_BACKGROUND_EXECUTION Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The DOS_BREAK Statement

This  statement  enables  the use of CTRL-C and  CTRL-BREAK  as  break
characters  for  the  DOS session if the parameter value is  set  to  ON.   The
break characters are disabled if OFF is selected.

The following is an example of the use of this statement :-

  DOS_BREAK = OFF

The default value for this statement is OFF.

The DOS_DEVICE Statement

This statement specifies device drivers which are to be loaded into the DOS
session   as   though   the   DEVICE=  statement   had   been   used   in   a
CONFIG.SYS  file.  The parameter value is a string delimited by single  or
double  quotes.   Multiple  device  drivers may  be  specified  by  using  the
pseudo  new line character in the string.  The pseudo new line  character  is
described at the start of this section.

Multi-User  DOS does not check the data in the string and passes it  directly
to the system.

5-10                                 The Settings File


The following is an example of the use of this statement :-

  DOS_DEVICE = "C:\MYDEV\DRIVERA.SYS'`C:\MYDEV\DRIVERB.SYS"

The  default  value  for  this statement is a blank  string  indicating  that  no
device drivers are to be loaded.

The DOS_FCBS Statement

This  statement is used to define the number of File Control Blocks that  are
to  be allocated for the DOS session.  The parameter value may  range  be-
tween 0 and 255.

The following is an example of the use of this statement :-

  DOS_FCBS = 16

The default value for this statement is 16.

The DOS_FCBS_KEEP Statement

This  statement  defines the number of File Control Blocks  that  cannot  be
automatically  closed  by the system.  The parameter value  may  range  be-
tween 0 and 255.

The following is an example of the use of this statement :-

  DOS_FCBS_KEEP = 16

The default value for this statement is 16.

The DOS_FILES Statement

This  statement  specifies the maximum number of file handles that  can  be
opened in a DOS session.  The parameter value may range between 20  and
255.

The following is an example of the use of this statement :-

  DOS_FILES = 20

The default value for this statement is 20.



The Settings File                                 5-11


The DOS_HIGH Statement

This  statement tells the system to load the DOS kernel above the  1  mega-
byte memory address if ON is selected.  If this is not required, the parameter
value OFF should be specified.

The following is an example of the use of this statement :-

  DOS_HIGH = OFF

The default value for this statement is OFF.

The DOS_LASTDRIVE Statement

This  statement defines the highest disk drive letter to be made  available  to
the DOS session.  Parameter values may be in the range A through Z.

The following is an example of the use of this statement :-

  DOS_LASTDRIVE = K

The default value for this statement is Z.

The DOS_RMSIZE Statement

This  statement sets the amount of real-mode memory in kilobytes that  will
be  available to the DOS session.  The parameter value may be in the  range
128 through 640 in increments of 4.

The following is an example of the use of this statement :-

  DOS_RMSIZE = 512

The default value for this statement is 640.

The DOS_SHELL Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The DOS_STARTUP_DRIVE Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

5-12                                 The Settings File


The DOS_UMB Statement

This  statement  specifies  that  DOS TSRs  and  device  drivers  should  be
loaded  into  the DOS upper memory blocks when ON  is  selected  otherwise
OFF should be specified.

The following is an example of the use of this statement :-

  DOS_UMB = ON

The default value for this statement is OFF.

The DOS_VERSION Statement

This statement specifies the DOS versions that should be reported to  speci-
fic  applications.  This ensures compatibility with applications that expect  a
specific DOS version.

The  parameter  value  is  a  string delimited  by  single  or  double  quotes.
Multiple version assignments may be specified by using the pseudo new line
character  in  the string.  The pseudo new line character is described  at  the
start of this section.

Multi-User  DOS does not check the data in the string and passes it  directly
to the system.

Each line in the string is in the following format :-

  <program name>,<DOS major version>,<DOS minor version>,255

where  <program name> is the name of the program, including its file  exten-
sion,  to which the system will return <DOS major version> and <DOS  minor
version> whenever the program requests the DOS version number.

The following is an example of the use of this statement :-

  DOS_VERSION = "MYPROG1.EXE,5,00,255'`MYPROG2,EXE,3,30,255"

The  default  value  for  this statement is the  release  number  of  the  OS/2
operating system itself.





The Settings File                                 5-13


The DPMI_DOS_API Statement

This  statement  specifies  how  the  translation  for  DOS  API  services  is
handled by the system.  The following keywords are valid as the  parameter
value :-

  AUTO
  ENABLED
  DISABLED

The following is an example of the use of this statement :-

  DPMI_DOS_API = ENABLED

The default value for this statement is AUTO.

The DPMI_MEMORY_LIMIT Statement

This statement specifies the amount of DPMI memory to be made  available
to a DOS session.  The parameter value may be in the range 0 through  512
and indicates the number of megabytes to be made available.

The following is an example of the use of this statement :-

  DPMI_MEMORY_LIMIT = 16

The default value for this statement is 4.

The DPMI_NETWORK_BUFF_SIZE Statement

This statement specifies the size of the network translation buffer for DPMI
applications.   The  parameter value may be in the range 1 through  64  and
indicates the number of kilobytes to be allocated.

The following is an example of the use of this statement :-

  DPMI_NETWORK_BUFF_SIZE = 4

The default value for this statement is 8.

The EMS_FRAME_LOCATION Statement

This  statement specifies the address of the 64KB EMS frame for  the  DOS
session.  The keyword parameter may be one of the following values :-

5-14                                 The Settings File


  AUTO NONE C000 C400 C800 CC00 D000 D400
  D800 DC00 8000 8400 8800 8C00 9000

The following is an example of the use of this statement :-

  EMS_FRAME_LOCATION = AUTO

The default value for this statement is AUTO.

The EMS_HIGH_OS_MAP_REGION Statement

This  statement specifies the size in kilobytes of an additional EMS  region.
The parameter value must be in the range 0 through 96 in increments of 16.

The following is an example of the use of this statement :-

  EMS_HIGH_OS_MAP_REGION = 16

The default value for this statement is 0.

The EMS_LOW_OS_MAP_REGION Statement

This  statement  specifies  the size in kilobytes of  the  remappable  area  of
conventional memory.  The parameter value must be in the range 0 through
576 in increments of 16.

The following is an example of the use of this statement :-

  EMS_LOW_OS_MAP_REGION = 16

The default value for this statement is 0.

The EMS_MEMORY_LIMIT Statement

This  statement  specifies  the amount of EMS memory  in  kilobytes  to  be
made  available  to the DOS session.  The parameter value must  be  in  the
range 0 through 32768 in increments of 16.

The following is an example of the use of this statement :-

  EMS_MEMORY_LIMIT = 4096

The default value for this statement is 2048.


The Settings File                                 5-15


The HW_NOSOUND Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The HW_ROM_TO_RAM Statement

This  statement  specifies that the ROM area should be copied to  the  RAM
area if ON is selected otherwise OFF should be specified.

The following is an example of the use of this statement :-

  HW_ROM_TO_RAM = ON

The default value for this statement is OFF.

The HW_TIMER Statement

This  statement specifies that programs in the DOS session should be  given
direct  access  to the hardware timer ports if ON is  selected  otherwise  OFF
should be specified.

The following is an example of the use of this statement :-

  HW_TIMER = ON

The default value for this statement is OFF.

The IDLE_SECONDS Statement

This statement specifies the number of seconds of idle time that must elapse
before  the operating system reduces the priority of the DOS  session.   The
parameter value must be in the range 0 through 60.

The following is an example of the use of this statement :-

  IDLE_SECONDS = 60

The default value for this statement is 0.

The IDLE_SENSITIVITY Statement

This  statement  sets the threshold at which the system will  reduce  a  DOS
session's  time  slice  if the DOS program enters into a  polling  loop.   The

5-16                                 The Settings File


parameter value must be in the range 1 through 100.  A setting of 100  dis-
ables the idle sensitivity.

The following is an example of the use of this statement :-

  IDLE_SENSITIVITY = 100

The default value for this statement is 75.

The INT_DURING_IO Statement

This statement allows interrupts to occur during file input and output if ON is
selected otherwise OFF should be specified.

The following is an example of the use of this statement :-

  INT_DURING_IO = ON

The default value for this statement is OFF.

The KBD_ALTHOME_BYPASS Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The KBD_BUFFER_EXTEND Statement

This  statement  increase  the size of the keyboard buffer  if  ON  is  selected
otherwise OFF should be specified.

The following is an example of the use of this statement :-

  KBD_BUFFER_EXTEND = ON

The default value for this statement is ON.

The KBD_CTRL_BYPASS Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.





The Settings File                                 5-17


The KBD_RATE_LOCK Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The MEM_EXCLUDE_REGIONS Statement

This  statement  specifies  regions of memory  that  EMS/XMS  cannot  use
because  they  are  needed for device drivers or for  some  other  use.   The
parameter  value is a string delimited by single or double quote  characters.
The  string contains the hexadecimal addresses of the 4KB memory  regions
to  be excluded; each memory address is separated by a comma.  If an  area
is larger than 4KB, a range may be given.

Multi-User  DOS does not check the data in the string and passes it  directly
to the system.

The following is an example of the use of this statement :-

  MEM_EXCLUDE_REGIONS = "C0000,D0000-D8000"

The default value for this statement is a blank string.

The MEM_INCLUDE_REGIONS Statement

This  statement  specifies  regions of memory that EMS/XMS  can  use  be-
tween  the  value  specified in the DOS_RMSIZE  statement  and  the  1MB
address.   The  parameter  value is a string delimited  by  single  or  double
quote characters.  The string contains the hexadecimal addresses of the 4KB
memory  regions  to  be included; each memory address is  separated  by  a
comma.  If an area is larger than 4KB, a range may be given.

Multi-User  DOS does not check the data in the string and passes it  directly
to the system.

The following is an example of the use of this statement :-

  MEM_INCLUDE_REGIONS = "C0000,D0000-D7FFF"

The default value for this statement is a blank string.





5-18                                 The Settings File


The MOUSE_EXCLUSIVE_ACCESS Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The PRINT_SEPARATE_OUTPUT Statement

The  statement  specifies  that printer output from two or  more  DOS  pro-
grams  running in the DOS session should be kept separate if ON is  selected
otherwise OFF should be specified.

The following is an example of the use of this statement :-

  PRINT_SEPARATE_OUTPUT = OFF

The default value for this statement is ON.

The PRINT_TIMEOUT Statement

This  statement  specifies  the  number of seconds  of  inactivity  before  the
system will force data to be printed.  The parameter must be in the range  0
through 3600.

The following is an example of the use of this statement :-

  PRINT_TIMEOUT = 60

The default value for this statement is 15.

The SESSION_PRIORITY Statement

This statement assigns the scheduling priority for the DOS session.  It  may
be  used  to balance the processor usage amongst a mix of  OS/2  and  DOS
programs.   A program with a higher priority will appear  more  responsive
to  the  user.   The  parameter may be in the range 1 to 32  where  1  is  the
lowest and 32 is the highest priority.

The following is an example of the use of this statement :-

  SESSION_PRIORITY = 16

The default value for this statement is 1.



The Settings File                                 5-19


The VGA_8514A_XGA_IOTRAP Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The VIDEO_FASTPASTE Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The VIDEO_MODE_RESTRICTION Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The VIDEO_ONDEMAND_MEMORY Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The VIDEO_RETRACE_EMULATION Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The VIDEO_ROM_EMULATION Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The VIDEO_SWITCH_NOTIFICATION Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.

The VIDEO_WINDOW_REFRESH Statement

This  statement  is only valid for DOS sessions running on the  host  and  is
invalid for DOS sessions running under Multi-User DOS.






5-20                                 The Settings File


The XMS_HANDLES Statement

This  statement specifies the number of XMS handles to be  allocated.   The
parameter may be in the range 0 through 128.

The following is an example of the use of this statement :-

  XMS_HANDLES = 16

The default value for this statement is 32.

NOTE:  There is a bug in OS/2 which, at the time of printing this  manual,
prevents  the  use  of this statement.  The bug has  been  reported  to  IBM.
You  may  try  to use this statement to determine whether  your  version  of
OS/2  has  been fixed.  If the bug is still present, RUNDOS will  return  the
'TMD0025' message.

The XMS_MEMORY_LIMIT Statement

This  statement  specifies  the amount of XMS memory  in  kilobytes  to  be
made  available  to  the DOS session.  The parameter value may  be  in  the
range 0 through 16384 in increments of 4.

The following is an example of the use of this statement :-

  XMS_MEMORY_LIMIT = 4096

The default value for this statement is 2048.

NOTE:  There is a bug in OS/2 which, at the time of printing this  manual,
prevents  the  use  of this statement.  The bug has  been  reported  to  IBM.
You  may  try  to use this statement to determine whether  your  version  of
OS/2  has  been fixed.  If the bug is still present, RUNDOS will  return  the
'TMD0025' message.

The XMS_MINIMUM_HMA Statement

This  statement  specifies the minimum allocation size of the  high  memory
area.  The parameter value may be in the range 0 through 63.

The following is an example of the use of this statement :-

  XMS_MINIMUM_HMA = 63


The Settings File                                 5-21


The default value for this statement is 0.

NOTE:  There is a bug in OS/2 which, at the time of printing this  manual,
prevents  the  use  of this statement.  The bug has  been  reported  to  IBM.
You  may  try  to use this statement to determine whether  your  version  of
OS/2  has  been fixed.  If the bug is still present, RUNDOS will  return  the
'TMD0025' message.






































5-22                                 The Settings File


-------------------------------------------

Index

-------------------------------------------

COLORMAP section 5-4/7
Colour Mapping facility 2-7 5-4/7
COM_DIRECT_ACCESS statement 5-9
COM_HOLD statement 5-9
COM_RECEIVE_BUFFER_FLUSH
    statement 5-9
COM_SELECT statement 5-9
CONFIG.SYS 3-2/3
CPU index 2-4/5 4-2
CPUINDEX statement 2-5 4-2/3 5-3
DOS settings 2-2 2-4 2-7 4-1 5-8
DOS_AUTOEXEC statement 5-10
DOS_BACKGROUND_EXECUTION
    statement 5-10
DOS_BREAK statement 5-10
DOS_DEVICE statement 5-10
DOS_FCBS statement 5-11
DOS_FCBS_KEEP statement 5-11
DOS_FILES statement 5-11
DOS_HIGH statement 5-12
DOS_LASTDRIVE statement 5-12
DOS_RMSIZE statement 5-12
DOS_SHELL statement 5-12
DOS_STARTUP_DRIVE statement 5-12
DOS_UMB statement 5-13
DOS_VERSION statement 5-13
DOSCPULIMIT statement 2-5 4-2 5-3
DPMI_DOS_API statement 5-14
DPMI_MEMORY_LIMIT statement 5-14
DPMI_NETWORK_BUFF_SIZE statement
    5-14
EMS_FRAME_LOCATION statement
    5-14
EMS_HIGH_OS_MAP_REGION statement
    5-15
EMS_LOW_OS_MAP_REGION statement
    5-15
EMS_MEMORY_LIMIT statement 5-15
HW_NOSOUND statement 5-16
HW_ROM_TO_RAM statement 5-16
HW_TIMER statement 5-16
IDLE_SECONDS statement 5-16
IDLE_SENSITIVITY statement 5-16
Installation 3-1/3
INT_DURING_IO statement 5-17



Index


KBD_ALTHOME_BYPASS statement
    5-17
KBD_BUFFER_EXTEND statement 5-17
KBD_CTRL_BYPASS statement 5-17
KBD_RATE_LOCK statement 5-18
LOCK facility 2-3 2-6/7 4-2/3 5-4
LOCKNAME statement 4-2/3 5-4
MEM_EXCLUDE_REGIONS statement
    5-18
MEM_INCLUDE_REGIONS statement
    5-18
MOUSE_EXCLUSIVE_ACCESS
    statement 5-19
OS/2
 versions 2-1
PRINT_SEPARATE_OUTPUT statement
    5-19
PRINT_TIMEOUT statement 5-19
RUNDOS section 5-1/2
RUNDOS.EXE 2-2/3 4-1/2 5-1
SESSION_PRIORITY statement 5-19
Settings File 2-3/8 4-1/2 5-1/2
SETTINGS section 5-8
TINSTALL.EXE 3-1/3
VGA_8514A_XGA_IOTRAP statement
    5-20
VIDEO_FASTPASTE statement 5-20
VIDEO_MODE_RESTRICTION statement
    5-20
VIDEO_ONDEMAND_MEMORY
    statement 5-20
VIDEO_RETRACE_EMULATION
    statement 5-20
VIDEO_ROM_EMULATION statement
    5-20
VIDEO_SWITCH_NOTIFICATION
    statement 5-20
VIDEO_WINDOW_REFRESH statement
    5-20
XMS_HANDLES statement 5-21
XMS_MEMORY_LIMIT statement 5-21
XMS_MINIMUM_HMA statement 5-21



                                        Index

