
.include title.inc
.include vars.inc
.include vars.eng

.SET TITLE=*[=BASETITLE]*
.ti [=BASETITLE] [=VERSION] Reference
.hi 234

.. ----------------------------------------
.1 [=BASETITLE] Overview
.. ----------------------------------------
.an IDPNL_OVERVIEW
.
[=TITLE] enables you to use the complete set of functions of the
DosStartSession API, which is to be used for starting any kind of
session under *OS/2* or *eComStation*. In addition to the conventional
.. MOD
START command, [=TITLE] supports the following options of the
DosStartSession API:
.ul compact
- start a DOS session with optional DOS settings
- specify a window position for the new session
- specify an icon for the system menu of the new session
.. MOD
- do not close a text window after termination (NOAUTOCLOSE)
- wait for termination of the new session

All of the [=TITLE] command parameters are as well available under
DOS running in a DOS-box under *OS/2* or *eComStation*, which is
especially interesting for the /WAIT function. This makes it
possible to synchronously call an *OS/2* or *eComStation* command
from within a DOS-Box and therefore waiting for its termination.

[=TITLE] contains the functionality of the following programs, which
are hereby credited to have inspired me to write [=TITLE]:
.ul
- STARTD V1.0 Norm Ross 1992
.
.. MOD
  *OS/2* program with nearly all [=TITLE] parameters except e.g. /WAIT,
  but cannot start programs from within *MDOS*.
- START.EXE IBM Internal 1993
.
  DOS program starting programs from within *MDOS*.

[=TOPICS]
.su 1

.. ################
.include copyright.eng
.. ################

.. ----------------------------------------
.2 Prerequisites
.. ----------------------------------------
.an IDPNL_PREREQUISITES
.
The following prerequisites apply to the current version of [=TITLE]
.ul
- the program requires *OS/2 V1.x* or better to start programs from within *OS/2*
- the program requires *OS/2 V2.11* or better to launch programs from within *MDOS* or *DOS*
- the program requires the *?:\OS2* directory to be included in the PATH statement
  of *OS/2* or *eComStation* as well as the *MDOS* environment to be able to properly
  determine the language of the used operating system.
- the program requires the [=TITLE] executable to reside in one of the directories
  of the PATH statement of the  *OS/2* or *eComStation* environment to allow
  usage of the [.FN_PARM_WAIT /WAIT] parameter from within *MDOS*

.. ----------------------------------------
.2 Installation
.. ----------------------------------------
.an IDPNL_INSTALL
.
[=TOPICS]
.su V30 u

.. ----------------------------------------
.3 install [=BASETITLE]
.. ----------------------------------------
.an IDPNL_INSTALL_STARTB
.
The package comes with the following files
.pl compact break=none tsize=15 bold
- startb.exe
= the [=TITLE] program file
- inf\**.inf
= online help files in several languages
- file__id.diz
= package description file

Unzip this package into an empty directory and
copy *STARTB.EXE* to a directory included both in
.. MOD
the PATH statement of both the *OS/2* or *eComStation* and
*MDOS* environment.

Execute [=TITLE] with parameter /? or /?? to get online help
and further information.

.. ----------------------------------------
.3 National Language Support
.. ----------------------------------------
.an IDPNL_INSTALL_NLS
.
The current package contains National Language Support for
the english, german and french language.

The language used is chosen according to the language of your
operating system. If the language of the operating system
is not supported by [=TITLE], english is used as the default language.

In order to enable [=TITLE] to determine the language of your
operating system, the *?:\OS2* directory must be included in
the PATH statement for both the *OS/2* or *eComStation* or *MDOS*
environment. This is normally the case, but if not,
the language is determined by the COUNTRY setting. This may
result in [=TITLE] using a language different to the
language of the operating system.

[=NOTE]
.ul compact
- You can force the usage of a given language by setting an
  [.IDPNL_USAGE_ENVVARS environment variable].

.. ----------------------------------------
.2 Usage
.. ----------------------------------------
.an IDPNL_USAGE
.
[=TOPICS]
.su V30 u 1

.. ----------------------------------------
.3 [=BASETITLE] syntax
.. ----------------------------------------
.an IDPNL_USAGE_TOPIC1
.
.fo off
  STARTB 
    [.FN_PARM_CMDPATH drive]   [.FN_PARM_CMDPATH path] 

 
    [.FN_PARM_TITLE "title"]   [.FN_PARM_K /K] Ĵ  [.FN_PARM_F /F|#/FG#] Ĵ
                  [.FN_PARM_C /C] Ĵ  [.FN_PARM_B /B|#/BG#] 
                  [.FN_PARM_N /N] 
 
    [.FN_PARM_FS /FS]  Ĵ  [.FN_PARM_MAX /MAX] Ĵ
    [.FN_PARM_WIN /WIN] Ĵ  [.FN_PARM_MIN /MIN] Ĵ
    [.FN_PARM_PM /PM]  Ĵ  [.FN_PARM_INV #/INV#] 
    [.FN_PARM_DOS /DOS] Ĵ
    #[.FN_PARM_DOSSET /DOS:settings.dat]# 

 
    #[.FN_PARM_WAIT /WAIT]#   #[.FN_PARM_NC /NC]#   [.FN_PARM_I /I] 

 
    #[.FN_PARM_POS /POS:x,y,x1,y1]#   #[.FN_PARM_ICON /ICON:icon.ico]# 

 
    [.FN_PARM_PGM /PGM]   [.FN_PARM_CMD command] 
                           [.FN_PARM_CMD command inputs] 

.fo on

The parameters displayed in italic are supported by [=TITLE] only,
whereas all other parameters are also available with the 
built-in *START* command of *OS/2* or *eComStation*.

.include fneng.inc

.. ----------------------------------------
.3 [=BASETITLE] environment variables
.. ----------------------------------------
.an IDPNL_USAGE_ENVVARS
.
The following environment variables are supported by [=TITLE]:
.pl bold tsize=1
- STARTB__LANGUAGE
= this setting overides the language used by [=TITLE] and its installation program.
  The following languages are available with the current version:
.pl compact bold break=none tsize=6
  - eng
  = english
  - deu
  = german
  - fra
  = french
- STARTB__DUMPSETTINGS
= this setting lets [=TITLE] dump the settings being passed to
  a *MDOS* session, when the parameter [.FN_PARM_DOSSET /DOS:settings.dat]
  is used. This is particular helpful when [.IDPNL_USAGE_DOSSETTINGS_ENCODED]
  are used that have been modified manually. If that is done incorrectly, 
  this may lead lead to that the complete file or a part of it cannot any longer
  be interpreted correctly.

.. ----------------------------------------
.3 DOS setting files
.. ----------------------------------------
.an IDPNL_USAGE_DOSSETTINGS
.
When calling [=TILE] with the parameter
[.FN_PARM_DOS /DOS:settings.dat] to launch an *MDOS*
session with specific settings, the specified file
must comply to either of two formats. 

[=TOPICS]
.su H50 u

.. ........................................
.4 simple DOS setting files
.. ........................................
.an IDPNL_USAGE_DOSSETTINGS_SIMPLE
.
Simple settings files apply to the following rules:
.ul
- every setting is specified on one line in the format
.
.
   variable=value
- some settings require multiple lines. In such cases the
  *^* character marks a new line, but the value for the setting must
  still remain on a single line
- for the value *ON* a *1* and for *OFF* a *0* must be specified

Here is a sample settings file in the simple format:
.fo off
DOS__AUTOEXEC=C:\MYAUTO.BAT
COM__DIRECT__ACCESS=1
COM__HOLD=1
COM__SELECT=COM2
DOS__BACKGROUND__EXECUTION=1
DOS__DEVICE=C:\TCPIP\BIN\VDOSTCP.SYS^C:\OS2\MDOS\ANSI.SYS
DOS__FILES=100
DOS__HIGH=1
DOS__LASTDRIVE=Z
DOS__RMSIZE=640
DOS__UMB=1
DOS__VERSION=MYAPP.EXE,5,00,255^YOURAPP.EXE,5,00,255
HW__TIMER=1
INT__DURING__IO=1
.fo on

.. ........................................
.4 encoded DOS setting files
.. ........................................
.an IDPNL_USAGE_DOSSETTINGS_ENCODED
.
Coded *DOS* setting files can be created from the properties notebook
of a program object. For that open up the properties notebook of a program
object, of which you would like to use the DOS properties of.
Then select the tab *Session* and press the pushbutton
.ul compact
- *DOS properties*  or
- *Win-OS/2 properties* or *Win-eCS properties*

Then select as category
.ul compact
- *All DOS properties*  or
- *All DOS and Win-OS/2 properties* or *All DOS and Win-eCS properties*

In the next dialog modify the settings, if required, and then 
press the pushbutton *Print*. Within the next dialog choose *Encoded File*
and specify the output filename. After pressing *Ok*, the file will contain
the *DOS* settings in the encoded format.

.at fc=red
[=NOTE]
.ul compact
- if you modify a encoded file (e.g. when removing some unneeded settings),
  don't remove the first line containing the string *s=DCF*, as otherwise
  this file is not longer treated as a encoded file without this signature.
  Using such an invalid file with [=TITLE] will make it assume that the
  file format complies to [.IDPNL_USAGE_DOSSETTINGS_SIMPLE] and not
  refuse to use it. As a reult the values will not be interpreted and
  converted properly anymore and thus the DOS session to be launched will 
  receive only nonsensical settings and no DOS setting will be set.
.at

.. ----------------------------------------
.4 problems with DOS setting files
.. ----------------------------------------
.an IDPNL_USAGE_DOSSETTINGS_PROBLEMS
.
In most cases, you can use [.IDPNL_USAGE_DOSSETTINGS_SIMPLE] and
[.IDPNL_USAGE_DOSSETTINGS_ENCODED] right away with [=TITLE].

There may appear some problems though:
.ul
- In rare cases sessions just do not start, if the DOS settings file becomes too long.
  This is a problem that normally occurs only with [.IDPNL_USAGE_DOSSETTINGS_ENCODED],
  if all possible *DOS settings* were written to it.
.
  In such a case please try to remove some settings from the file.
  You may safely remove blocks of these settings, which values (v=) are 
  equal to the default value (d=) for the setting. For settings of type 2 (t=2)
  the default value (d=) must be taken as the position of the value
  in the listbox of the setting.
.
  Make sure though that you don't remove
  the [.IDPNL_USAGE_DOSSETTINGS_ENCODED first signature line of the encoded file].
- The following settings are being ignored on purpose by [=TITLE] and a warning
  message will be displayed:
.ul compact
  - VIDEO__MODE__RESTRICTION
  - VIDEO__WINDOW__REFRESH
.el
.
  This seems to be necessary, because when specifiying these settings,
  DosStartSession will, for unknown reasons, not start the DOS
  session.

.. ----------------------------------------
.2 Limitations
.. ----------------------------------------
.an IDPNL_LIMITATIONS
.
The current version of [=TITLE] has the following limitations:
.ul
- [=TITLE] cannot start seamless *Win-OS/2* or *Win-eCS* 3.x sessions, for this
  use the *OS/2* or *eComStation* command *START* instead.
- [=TITLE] cannot pass the following settings to a *MDOS* session,
  as otherwise it will not start:
.ul compact
  - VIDEO__MODE__RESTRICTION
  - VIDEO__WINDOW__REFRESH
.el

.. ################
.include history.eng
.. ################

.. ----------------------------------------
.3 Version 1.32
.. ----------------------------------------
.
_*Fixed:*_
.ul
- [=TITLE] does not anylonger open [.IDPNL_USAGE_DOSSETTINGS] exclusively, so that multiple
  instances can read the same file at the same time.

.. ----------------------------------------
.3 Version 1.31
.. ----------------------------------------
.
First release with revision history

_*New:*_
.ul
- Replaced readme file with this INF file
- [=TITLE] now uses the [.IDPNL_INSTALL_NLS language of your operating system],
  as far as it is supported by the program. Former versions used the language according
  to the COUNTRY setting.
- added french [.IDPNL_INSTALL_NLS]
- added several [.IDPNL_USAGE_ENVVARS]

_*Fixed:*_
.ul
- [=TITLE]* /DOS /WIN* now properly opens up a *DOS* window
- [=TITLE] now can start a *Win-OS/2* or *Win-eCS* program directly without first
  invoking an *OS/2* or *eComStation* window
- *Win-OS/2* or *Win-eCS* settings are now properly read from [.IDPNL_USAGE_DOSSETTINGS_ENCODED]

.. ################
.include trademarks.eng
.. ################


.. =============================================================================
.2 Credits
.. =============================================================================
.an IDPNL_CREDITS
.
[=TOPICS]
.su V30

.. -----------------------------------------------------------------------------
.3 General credits
.. -----------------------------------------------------------------------------
.an IDPNL_CREDITS_GENERAL
.
Credits go to:
.ul
- Norm Ross and some unknown programmers inside IBM for their programs *STARTD*
  and *START.EXE* (DOS version), having inspired me to write [=TITLE]

.. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
.3 Credits to translators
.. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
.an IDPNL_CREDITS_TRANSLATORS
.
The following people supported [=TITLE] by translating sources
into the respective language:

.pl tsize=15 break=none
- *Language*
= *Translator*
- German
= Christian Langanke [mailto:cla@clanganke.de]
- French
= Guillaume Gay [mailto:guillaume.gay@bigfoot.com]

