home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / startdos.zip / readme < prev    next >
Text File  |  1995-10-10  |  14KB  |  367 lines
  1.  
  2.  
  3.  
  4.  
  5. StartDos
  6.  
  7. (c) Copyright International Business Machines Corporation 1993-1995.
  8. All rights reserved.
  9.  
  10. Monte Copeland, monte@vnet.ibm.com
  11.  
  12. Introduction to StartDos
  13.  
  14. StartDos is an OS/2 program to start virtual DOS mode (VDM) sessions under
  15. OS/2. The nature of DOS sessions under OS/2 is controlled by DOS settings
  16. strings. StartDos accepts these strings via a REXX command file then starts a
  17. DOS session using those settings. Here are some examples of DOS setting
  18. strings for StartDos and OS/2:
  19.  
  20.   Setting string                              Comment
  21.   ----------------------------------------    ------------------------------
  22.   "DOS_DEVICE=c:\os2\mdos\ansi.sys"           load ANSI support
  23.   "DOS_HIGH=1"                                1 means yes, load DOS high
  24.   "DPMI_DOS_API=ENABLED"                      DPMI is enabled
  25.   "DPMI_MEMORY_LIMIT=8"                       DPMI will have 8 megabytes RAM
  26.  
  27. StartDos uses REXX as a string-delivery mechanism. You will create REXX
  28. command files especially for StartDos. These REXX command files use StartDos
  29. functions to set up the DOS settings. StartDos comes with a separate utility
  30. program, SETTINGS.EXE, to help you create REXX scripts for StartDos.
  31.  
  32. StartDos is normally used in text mode. A version for OS/2 Presentation
  33. Manager exists and may prove useful for some applications.
  34.  
  35. StartDos is IBM Employee Written Software. Please read the "as-is" license
  36. agreement from IBM. Essentially, you use this program "as is," and IBM makes
  37. no warranty about the correctness of this program or its suitability to any
  38. purpose.
  39.  
  40.  
  41.  
  42.  
  43. StartDos Usage
  44.  
  45. StartDos expects a REXX command file name on the command line. Usually this
  46. file name ends with .CMD. StartDos will add .CMD if necessary. StartDos looks
  47. in the current directory for the file. If not found, it searches the PATH.
  48. Then StartDos loads it and runs REXX on it. An example StartDos command line
  49. might be:
  50.  
  51.                             startdos mydos
  52.  
  53. where mydos implies MYDOS.CMD somewhere in the PATH. In general, StartDos
  54. command lines look like this:
  55.  
  56.               startdos <REXX file> <optional arguments>
  57.  
  58.  
  59.  
  60.  
  61. REXX for StartDos
  62.  
  63. The REXX command file executes in a special StartDos environment. The REXX
  64. program calls StartDos functions such as AddDosSetting(). Here is an example
  65. REXX program that starts a DPMI DOS session. Note that all REXX programs must
  66. have a comment at line 1, column 1.
  67.  
  68.            /* DPMI.CMD: a REXX command file for StartDos */
  69.            if 'STARTDOS' <> address() then do
  70.              say 'ooops, expected StartDos'
  71.              return 2
  72.            end
  73.            rc = AddDosSetting( 'DPMI_DOS_API=ENABLED' )
  74.            rc = AddDosSetting( 'DPMI_MEMORY_LIMIT=8' )
  75.            return 0
  76.  
  77. This program checks the environment to make sure it is StartDos. A REXX
  78. program can switch its behavior depending on the current environment. This one
  79. works under both CMD and STARTDOS:
  80.  
  81.            /* DOS.CMD: a REXX command file for StartDos */
  82.            select
  83.              when address() = 'CMD' then do
  84.                parse arg szArgs
  85.                parse source . . szREXX .
  86.                'startdos' sREXX szArgs
  87.              end
  88.              when address() = 'STARTDOS' then do
  89.                rc = AddDosSetting( 'DPMI_DOS_API=ENABLED' )
  90.                rc = AddDosSetting( 'DPMI_MEMORY_LIMIT=8' )
  91.              end
  92.              otherwise do
  93.                say 'ooops, expected StartDos or CMD.'
  94.                return 2
  95.              end
  96.            end
  97.            return 0
  98.  
  99. This program parses arguments and passes them to StartDos. StartDos normally
  100. passes these arguments to COMMAND.COM. Examples of DOS.CMD command-line usage:
  101.  
  102.     Example        Remarks
  103.     ------------   ---------------------------------------------------------
  104.     dos            starts a DOS session
  105.     dos /k dir     starts DOS, does a dir, and keeps (/k) the session
  106.     dos /c wp      starts DOS, calls (/c) wp.exe, session stops when wp ends
  107.  
  108. The REXX program should return a zero result code, and StartDos will start the
  109. session. If non-zero, no session is started. If you specify an incorrect DOS
  110. setting, chances are the session will start anyway. You may get an error
  111. message from OS/2.
  112.  
  113. REXX is always installed on OS/2 Warp, but it was optional on earlier versions
  114. of OS/2. You must have REXX installed to use StartDos. Get help on REXX with
  115. the OS/2 command:
  116.  
  117.                                 VIEW REXX
  118.  
  119.  
  120.  
  121.  
  122.  
  123. Special StartDos Functions
  124.  
  125. These special functions are available to REXX programs invoked from StartDos:
  126.  
  127.   StartDos function                       Comment
  128.   ------------------------------------    ---------------------------------
  129.   AddDosSetting( <setting string> )       may be called multiple times
  130.   ExecSynchronous()                       asynchronous start is default
  131.   QueryDesktop()                          returns PM desktop size in pels
  132.   SetCommandArgs( <command.com args> )    args acceptable to command.com
  133.   SetWindowPos( x, y, cx, cy )            set position, size of window
  134.   SetSessionTitle( <session title> )      title to appear in window list
  135.   StartBackground()                       start session in background
  136.   StartForeground()                       foreground start is default
  137.   StartFullscreen()                       fullscreen start is the default
  138.   StartWindowed()                         start session in a text window
  139.   StartSeamless()                         start windows programs
  140.  
  141. AddDosSetting( <setting string> ) -- AddDosSetting may be called multiple
  142. times in order to specify all the setting strings to StartDos. Expects one
  143. string parameter.
  144.  
  145. ExecSynchronous() -- The default exec is asynchronous, so StartDos will end as
  146. soon as the DOS session is started. A synchronous exec is one where StartDos
  147. waits until the DOS session ends before StartDos itself ends. In this case,
  148. StartDos will return the same errorlevel as COMMAND.COM. COMMAND.COM in OS/2
  149. returns the same errorlevel as the DOS program invoked with the /c option.
  150. Therefore, a synchronous exec and /c option causes StartDos to return with the
  151. same errorlevel as the DOS program. This is important when invoking DOS
  152. programs from OS/2 batch (or make) files. Expects no parameter.
  153.  
  154. QueryDesktop() -- returns a string "xxx yyy" which is the size of the PM
  155. desktop window in pels. For example, the string "640 480" is returned for PM
  156. on VGA. This is useful to compute x, y, cx, cy for the SetWindowPos()
  157. function. There are no parameters to QueryDesktop(). Returns a zero-length
  158. string under TShell.
  159.  
  160. SetCommandArgs( <command.com args> ) -- Parameters to COMMAND.COM may be
  161. specified two different ways: on the StartDos command line after the REXX
  162. command file name, or by using SetCommandArgs() in the REXX command file.
  163. SetCommandArgs() always overrides arguments given on the StartDos command
  164. line. Optional arguments given on the StartDos command line are available via
  165. PARSE ARG to the REXX program running in the StartDos environment.
  166.  
  167. SetSessionTitle( <session title> ) -- Sets the session title that appears in
  168. the Window List. Expects one string parameter.
  169.  
  170. SetWindowPos( x, y, cx, cy ) -- provide initial placement and size of a DOS
  171. session when a windowed session is desired. When SetWindowPos() is used,
  172. StartWindowed() is not required. Expects four numeric parameters in pels. x
  173. and y are position, cx and cy are size. See QueryDesktop(). Invalid under
  174. TShell.
  175.  
  176. StartBackground() -- Start the DOS session in background. No parameters.
  177.  
  178. StartForeground() -- Start the DOS session in the foreground. This is the
  179. default action. No parameters.
  180.  
  181. StartFullscreen() -- Start the DOS session in its own, full screen session.
  182. This is the default action. No parameters.
  183.  
  184. StartWindowed() -- Start the DOS session in a PM text window. Expects no
  185. parameters. Invalid under TShell.
  186.  
  187. StartSeamless() -- When used without parameters, will start WINOS2.COM in its
  188. own seamless VDM session, and SetCommandArgs() will supply parameters to
  189. WINOS2.COM. When used with parameters, they are as follows:
  190.  
  191.   Parameter 1. program category, a numeric parameter
  192.  
  193.   parameter   program category
  194.   ---------   -------------------------------
  195.          13   PROG_30_STDSEAMLESSVDM
  196.          14   PROG_30_STDSEAMLESSCOMMON
  197.          15   PROG_31_STDSEAMLESSVDM
  198.          16   PROG_31_STDSEAMLESSCOMMON
  199.          17   PROG_31_ENHSEAMLESSVDM
  200.          18   PROG_31_ENHSEAMLESSCOMMON
  201.          19   PROG_31_ENH
  202.          20   PROG_31_STD
  203.  
  204.   Parameter 2. windows program exe name
  205.   Parameter 3. startup directory (optional)
  206.  
  207. Any parameters set with SetCommandArgs() are for the windows program exe. If
  208. you specify any StartSeamless() parameters, parameter 3 is optional.
  209.  
  210.  
  211.  
  212.  
  213. Helper Program: settings.exe
  214.  
  215. Settings.exe is a program to help write REXX for StartDos. Settings.exe is a
  216. Presentation Manager program. Start settings.exe from any command prompt with
  217. the command
  218.  
  219.                             settings
  220.  
  221. The program presents a DOS Settings window. Change the settings as required
  222. and press OK. The program generates REXX code for StartDos for those settings.
  223.  
  224. Settings.exe has no save-to-file function, but it can copy to the Presentation
  225. Manager clipboard. From the menu, select Copy, then paste into an editor such
  226. as the EPM.EXE enhanced editor that comes with OS/2. REXX programs must have
  227. a starting comment, /*, in line 1 column 1.
  228.  
  229.  
  230.  
  231.  
  232.  
  233. Sample REXX: Diskette cleaner
  234.  
  235. Assume there is a DOS program called cleandsk.exe that writes zeroes to unused
  236. sectors on a floppy disk. This REXX program runs it in the background.
  237.  
  238. Because of ExecSynchronous(), StartDos will not end until cleandsk.exe ends.
  239. When it does, StartDos returns the same errorlevel as cleandsk.exe.
  240.  
  241. This program takes control of argument passing. It sets them explicitly with
  242. SetCommandArgs().
  243.  
  244.      /* clean.cmd */
  245.      parse arg szDriveLetter .
  246.      parse source . . szREXXFileName .
  247.      select
  248.        when 'CMD' = address()  then do
  249.          /* CMD "magically" sets rc when StartDos ends */
  250.          'STARTDOS' szREXXFileName szDriveLetter
  251.          say 'cleandsk.exe errorlevel' rc
  252.        end
  253.        when 'STARTDOS' = address()  then do
  254.          rc = ExecSynchronous( )
  255.          rc = SetCommandArgs( "/c cleandsk" szDriveLetter )
  256.          rc = StartBackground()
  257.        end
  258.        otherwise do
  259.          say 'Unexpected execution environment'
  260.          return 4
  261.        end
  262.      end
  263.      return 0
  264.  
  265. Then from an OS/2 prompt, enter
  266.  
  267.      CLEAN A:
  268.  
  269.  
  270. Sample REXX: Seamless windows write
  271.  
  272. In OS/2, windows programs may run "seamlessly" on the same desktop as the OS/2
  273. Presentation Manager. This REXX program starts the windows program WRITE.EXE
  274. to run "seamless." For seamless starts, SetCommandArgs() really sets the
  275. arguments to WINOS2.COM. To WINOS2.COM, /s means standard mode and /3 means
  276. enhanced mode.
  277.  
  278.      /* write.cmd */
  279.      parse source . . szREXXFileName .
  280.      select
  281.        when 'CMD' = address()  then do
  282.          'STARTDOS' szREXXFileName
  283.        end
  284.        when 'STARTDOS' = address()  then do
  285.          rc = StartSeamless()
  286.          rc = SetCommandArgs( "/3 write" )
  287.        end
  288.        otherwise do
  289.          say 'Unexpected execution environment'
  290.          return 4
  291.        end
  292.      end
  293.      return 0
  294.  
  295.  
  296. Sample REXX: Seamless Common VDM
  297.  
  298. For performance reasons, you may want to run all your windows programs in a
  299. common VDM session. The first start takes longer, but subsequent starts load
  300. much more quickly.
  301.  
  302.      /* notepad.cmd  */
  303.      parse source . . szREXXFileName .
  304.      select
  305.        when 'CMD' = address()  then do
  306.          'startdos' szREXXFileName
  307.        end
  308.        when 'STARTDOS' = address()  then do
  309.          rc = StartSeamless( 18, "notepad.exe" )
  310.        end
  311.        otherwise do
  312.          say 'Unexpected environment'
  313.        end
  314.      end
  315.      return 0
  316.  
  317.  
  318.  
  319.  
  320. Sample REXX: Multiple Settings Strings
  321.  
  322. The DOS_DEVICE and DOS_VERSION settings have multiple components. For example,
  323. the DOS_DEVICE setting requires that all device drivers be set with a single
  324. DOS_DEVICE setting string. These device driver names are separated with the
  325. line feed character, an ASCII 10.
  326.  
  327. The REXX function d2c(10) helps to build the string acceptable to DOS_DEVICE
  328. and DOS_VERSION. Example REXX:
  329.  
  330.     /* for startdos */
  331.     if 'STARTDOS' <> address() then do
  332.       say 'Expected StartDos environment.'
  333.       return 2
  334.     end
  335.  
  336.     /* this shows d2c(10) and the comma used for REXX line continuation */
  337.     rc = AddDosSetting( 'DOS_VERSION=DFIA0MOD.SYS,3,40,255'||d2c(10)||,
  338.     'EXCEL.EXE,10,10,4'||d2c(10)||,'WIN200.BIN,10,10,4' )
  339.  
  340.     /* similar thing */
  341.     rc = AddDosSetting( 'DOS_DEVICE=c:\os2\mdos\ansi.sys'||d2c(10)||,
  342.     'c:\os2\mdos\ega.sys' )
  343.     return 0
  344.  
  345.  
  346.  
  347. Sample REXX: Window Size and Position
  348.  
  349. This sample calls QueryDesktop for PM information, then starts a windowed DOS
  350. session squarely in the center of the screen.
  351.  
  352.     /* for startdos */
  353.     if 'STARTDOS' <> address() then do
  354.       say 'Expected StartDos environment.'
  355.       return 2
  356.     end
  357.     /* ask about PM */
  358.     xy = QueryDesktop()
  359.     if length( xy ) = 0 then do
  360.        /* must be TShell, where there is no PM */
  361.        return 2
  362.     end
  363.     x = word( xy, 1 )
  364.     y = word( xy, 2 )
  365.     rc = SetWindowPos( x/4, y/4, x/2, y/2 )
  366.     return 0
  367.