StartDos

StartDos (c) Copyright International Business Machines Corporation 1993-1995. All rights reserved. Monte Copeland, monte@vnet.ibm.com Introduction to StartDos StartDos is an OS/2 program to start virtual DOS mode (VDM) sessions under OS/2. The nature of DOS sessions under OS/2 is controlled by DOS settings strings. StartDos accepts these strings via a REXX command file then starts a DOS session using those settings. Here are some examples of DOS setting strings for StartDos and OS/2: Setting string Comment ---------------------------------------- ------------------------------ "DOS_DEVICE=c:\os2\mdos\ansi.sys" load ANSI support "DOS_HIGH=1" 1 means yes, load DOS high "DPMI_DOS_API=ENABLED" DPMI is enabled "DPMI_MEMORY_LIMIT=8" DPMI will have 8 megabytes RAM StartDos uses REXX as a string-delivery mechanism. You will create REXX command files especially for StartDos. These REXX command files use StartDos functions to set up the DOS settings. StartDos comes with a separate utility program, SETTINGS.EXE, to help you create REXX scripts for StartDos. StartDos is normally used in text mode. A version for OS/2 Presentation Manager exists and may prove useful for some applications. StartDos is IBM Employee Written Software. Please read the "as-is" license agreement from IBM. Essentially, you use this program "as is," and IBM makes no warranty about the correctness of this program or its suitability to any purpose. StartDos Usage StartDos expects a REXX command file name on the command line. Usually this file name ends with .CMD. StartDos will add .CMD if necessary. StartDos looks in the current directory for the file. If not found, it searches the PATH. Then StartDos loads it and runs REXX on it. An example StartDos command line might be: startdos mydos where mydos implies MYDOS.CMD somewhere in the PATH. In general, StartDos command lines look like this: startdos <REXX file> <optional arguments> REXX for StartDos The REXX command file executes in a special StartDos environment. The REXX program calls StartDos functions such as AddDosSetting(). Here is an example REXX program that starts a DPMI DOS session. Note that all REXX programs must have a comment at line 1, column 1. /* DPMI.CMD: a REXX command file for StartDos */ if 'STARTDOS' <> address() then do say 'ooops, expected StartDos' return 2 end rc = AddDosSetting( 'DPMI_DOS_API=ENABLED' ) rc = AddDosSetting( 'DPMI_MEMORY_LIMIT=8' ) return 0 This program checks the environment to make sure it is StartDos. A REXX program can switch its behavior depending on the current environment. This one works under both CMD and STARTDOS: /* DOS.CMD: a REXX command file for StartDos */ select when address() = 'CMD' then do parse arg szArgs parse source . . szREXX . 'startdos' sREXX szArgs end when address() = 'STARTDOS' then do rc = AddDosSetting( 'DPMI_DOS_API=ENABLED' ) rc = AddDosSetting( 'DPMI_MEMORY_LIMIT=8' ) end otherwise do say 'ooops, expected StartDos or CMD.' return 2 end end return 0 This program parses arguments and passes them to StartDos. StartDos normally passes these arguments to COMMAND.COM. Examples of DOS.CMD command-line usage: Example Remarks ------------ --------------------------------------------------------- dos starts a DOS session dos /k dir starts DOS, does a dir, and keeps (/k) the session dos /c wp starts DOS, calls (/c) wp.exe, session stops when wp ends The REXX program should return a zero result code, and StartDos will start the session. If non-zero, no session is started. If you specify an incorrect DOS setting, chances are the session will start anyway. You may get an error message from OS/2. REXX is always installed on OS/2 Warp, but it was optional on earlier versions of OS/2. You must have REXX installed to use StartDos. Get help on REXX with the OS/2 command: VIEW REXX Special StartDos Functions These special functions are available to REXX programs invoked from StartDos: StartDos function Comment ------------------------------------ --------------------------------- AddDosSetting( <setting string> ) may be called multiple times ExecSynchronous() asynchronous start is default QueryDesktop() returns PM desktop size in pels SetCommandArgs( <command.com args> ) args acceptable to command.com SetWindowPos( x, y, cx, cy ) set position, size of window SetSessionTitle( <session title> ) title to appear in window list StartBackground() start session in background StartForeground() foreground start is default StartFullscreen() fullscreen start is the default StartWindowed() start session in a text window StartSeamless() start windows programs AddDosSetting( <setting string> ) -- AddDosSetting may be called multiple times in order to specify all the setting strings to StartDos. Expects one string parameter. ExecSynchronous() -- The default exec is asynchronous, so StartDos will end as soon as the DOS session is started. A synchronous exec is one where StartDos waits until the DOS session ends before StartDos itself ends. In this case, StartDos will return the same errorlevel as COMMAND.COM. COMMAND.COM in OS/2 returns the same errorlevel as the DOS program invoked with the /c option. Therefore, a synchronous exec and /c option causes StartDos to return with the same errorlevel as the DOS program. This is important when invoking DOS programs from OS/2 batch (or make) files. Expects no parameter. QueryDesktop() -- returns a string "xxx yyy" which is the size of the PM desktop window in pels. For example, the string "640 480" is returned for PM on VGA. This is useful to compute x, y, cx, cy for the SetWindowPos() function. There are no parameters to QueryDesktop(). Returns a zero-length string under TShell. SetCommandArgs( <command.com args> ) -- Parameters to COMMAND.COM may be specified two different ways: on the StartDos command line after the REXX command file name, or by using SetCommandArgs() in the REXX command file. SetCommandArgs() always overrides arguments given on the StartDos command line. Optional arguments given on the StartDos command line are available via PARSE ARG to the REXX program running in the StartDos environment. SetSessionTitle( <session title> ) -- Sets the session title that appears in the Window List. Expects one string parameter. SetWindowPos( x, y, cx, cy ) -- provide initial placement and size of a DOS session when a windowed session is desired. When SetWindowPos() is used, StartWindowed() is not required. Expects four numeric parameters in pels. x and y are position, cx and cy are size. See QueryDesktop(). Invalid under TShell. StartBackground() -- Start the DOS session in background. No parameters. StartForeground() -- Start the DOS session in the foreground. This is the default action. No parameters. StartFullscreen() -- Start the DOS session in its own, full screen session. This is the default action. No parameters. StartWindowed() -- Start the DOS session in a PM text window. Expects no parameters. Invalid under TShell. StartSeamless() -- When used without parameters, will start WINOS2.COM in its own seamless VDM session, and SetCommandArgs() will supply parameters to WINOS2.COM. When used with parameters, they are as follows: Parameter 1. program category, a numeric parameter parameter program category --------- ------------------------------- 13 PROG_30_STDSEAMLESSVDM 14 PROG_30_STDSEAMLESSCOMMON 15 PROG_31_STDSEAMLESSVDM 16 PROG_31_STDSEAMLESSCOMMON 17 PROG_31_ENHSEAMLESSVDM 18 PROG_31_ENHSEAMLESSCOMMON 19 PROG_31_ENH 20 PROG_31_STD Parameter 2. windows program exe name Parameter 3. startup directory (optional) Any parameters set with SetCommandArgs() are for the windows program exe. If you specify any StartSeamless() parameters, parameter 3 is optional. Helper Program: settings.exe Settings.exe is a program to help write REXX for StartDos. Settings.exe is a Presentation Manager program. Start settings.exe from any command prompt with the command settings The program presents a DOS Settings window. Change the settings as required and press OK. The program generates REXX code for StartDos for those settings. Settings.exe has no save-to-file function, but it can copy to the Presentation Manager clipboard. From the menu, select Copy, then paste into an editor such as the EPM.EXE enhanced editor that comes with OS/2. REXX programs must have a starting comment, /*, in line 1 column 1. Sample REXX: Diskette cleaner Assume there is a DOS program called cleandsk.exe that writes zeroes to unused sectors on a floppy disk. This REXX program runs it in the background. Because of ExecSynchronous(), StartDos will not end until cleandsk.exe ends. When it does, StartDos returns the same errorlevel as cleandsk.exe. This program takes control of argument passing. It sets them explicitly with SetCommandArgs(). /* clean.cmd */ parse arg szDriveLetter . parse source . . szREXXFileName . select when 'CMD' = address() then do /* CMD "magically" sets rc when StartDos ends */ 'STARTDOS' szREXXFileName szDriveLetter say 'cleandsk.exe errorlevel' rc end when 'STARTDOS' = address() then do rc = ExecSynchronous( ) rc = SetCommandArgs( "/c cleandsk" szDriveLetter ) rc = StartBackground() end otherwise do say 'Unexpected execution environment' return 4 end end return 0 Then from an OS/2 prompt, enter CLEAN A: Sample REXX: Seamless windows write In OS/2, windows programs may run "seamlessly" on the same desktop as the OS/2 Presentation Manager. This REXX program starts the windows program WRITE.EXE to run "seamless." For seamless starts, SetCommandArgs() really sets the arguments to WINOS2.COM. To WINOS2.COM, /s means standard mode and /3 means enhanced mode. /* write.cmd */ parse source . . szREXXFileName . select when 'CMD' = address() then do 'STARTDOS' szREXXFileName end when 'STARTDOS' = address() then do rc = StartSeamless() rc = SetCommandArgs( "/3 write" ) end otherwise do say 'Unexpected execution environment' return 4 end end return 0 Sample REXX: Seamless Common VDM For performance reasons, you may want to run all your windows programs in a common VDM session. The first start takes longer, but subsequent starts load much more quickly. /* notepad.cmd */ parse source . . szREXXFileName . select when 'CMD' = address() then do 'startdos' szREXXFileName end when 'STARTDOS' = address() then do rc = StartSeamless( 18, "notepad.exe" ) end otherwise do say 'Unexpected environment' end end return 0 Sample REXX: Multiple Settings Strings The DOS_DEVICE and DOS_VERSION settings have multiple components. For example, the DOS_DEVICE setting requires that all device drivers be set with a single DOS_DEVICE setting string. These device driver names are separated with the line feed character, an ASCII 10. The REXX function d2c(10) helps to build the string acceptable to DOS_DEVICE and DOS_VERSION. Example REXX: /* for startdos */ if 'STARTDOS' <> address() then do say 'Expected StartDos environment.' return 2 end /* this shows d2c(10) and the comma used for REXX line continuation */ rc = AddDosSetting( 'DOS_VERSION=DFIA0MOD.SYS,3,40,255'||d2c(10)||, 'EXCEL.EXE,10,10,4'||d2c(10)||,'WIN200.BIN,10,10,4' ) /* similar thing */ rc = AddDosSetting( 'DOS_DEVICE=c:\os2\mdos\ansi.sys'||d2c(10)||, 'c:\os2\mdos\ega.sys' ) return 0 Sample REXX: Window Size and Position This sample calls QueryDesktop for PM information, then starts a windowed DOS session squarely in the center of the screen. /* for startdos */ if 'STARTDOS' <> address() then do say 'Expected StartDos environment.' return 2 end /* ask about PM */ xy = QueryDesktop() if length( xy ) = 0 then do /* must be TShell, where there is no PM */ return 2 end x = word( xy, 1 ) y = word( xy, 2 ) rc = SetWindowPos( x/4, y/4, x/2, y/2 ) return 0