home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / systools / startdos / readme < prev    next >
Encoding:
Text File  |  1994-01-20  |  9.4 KB  |  245 lines
  1. StartDos                        Monte Copeland, IBM Boca Raton
  2.  
  3. (c) Copyright International Business Machines Corporation 1993.
  4. All rights Reserved.
  5.  
  6. REVISION HISTORY
  7.  
  8. 20JAN94: IBM Employee Written Software release
  9. 05JAN94: tweak readme
  10. 11NOV93: new api StartSeamless(); tweak readme
  11. 25OCT93: settings.exe; sprintf pid into term queue name
  12. 11OCT93: fix rexx file search bug; tweak readme
  13. 09OCT93: tweak readme; new Rexx API SetSessionTitle()
  14. 21SEP93: new Rexx API SetCommandArgs()
  15. 27AUG93: default session full screen; searches PATH environment
  16. for CMD file; startdata length changed to 32.
  17. 06MAY93: first release on OS2TOOLS.
  18.  
  19.  
  20. --------------------------- STARTDOS USAGE -------------------------------
  21.  
  22. STARTDOS <Rexx CMD file> <optional command.com arguments>
  23.  
  24. Example StartDos command lines:
  25.  
  26. startdos                        prints this readme
  27. startdos sets.cmd               searches path for sets.cmd
  28. startdos sets                   adds .CMD then searches path
  29. startdos sets /c wp             /c for call; session exits with wp
  30. startdos sets /k dir            /k for keep; dir and session stays
  31.                                 /c and /k are command.com-defined switches
  32. startdos sets /c winos2 word    starts winos2 and a windows program
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39. -------------------------------- INTRODUCTION ----------------------------
  40.  
  41. StartDos is an OS/2 program to start virtual DOS mode sessions under OS/2.
  42. The nature of DOS sessions under OS/2 is controlled by DOS settings, some of
  43. which can only be set at session startup. StartDos accepts these settings via
  44. a Rexx command file then starts a DOS session. Examples of some setting
  45. strings that can only be specified at start time:
  46.  
  47.   DOS_DEVICE=<device driver file spec>
  48.   DOS_HIGH=1                                (1 means yes)
  49.   DPMI_DOS_API=ENABLED
  50.   DPMI_MEMORY_LIMIT=8                       (integer represents megabytes)
  51.  
  52. Most settings that require ON accept either ON or 1, but some settings must
  53. have a 1 instead of ON. For help with settings strings, run SETTINGS.EXE.
  54.  
  55. To specify DOS settings to StartDos, name a Rexx command file on the command
  56. line. StartDos will add .CMD if necessary. StartDos looks in the current
  57. directory for the Rexx file. If not present, it searches the PATH. StartDos
  58. invokes the Rexx interpreter, and the command file executes in a special
  59. StartDos environment. In this environment, the Rexx program can call
  60. functions in StartDos like AddDosSetting() and StartWindowed(). Example Rexx:
  61.  
  62.   /* Rexx command file for StartDos (comment mandatory on first line!) */
  63.   parse arg szCommandComArgs
  64.   if 'STARTDOS' <> address()  then do
  65.     say 'Expected STARTDOS environment'
  66.     return 2
  67.   end
  68.   rc = SetSessionTitle( 'DPMI DOS Session' )
  69.   rc = AddDosSetting( 'DOS_DEVICE=C:\OS2\MDOS\ANSI.SYS' )
  70.   rc = AddDosSetting( 'DOS_HIGH=1'  )
  71.   rc = AddDosSetting( 'DPMI_DOS_API=ENABLED' )
  72.   rc = AddDosSetting( 'DPMI_MEMORY_LIMIT=8' )
  73.   /* override the default and start the session in a text window */
  74.   rc = StartWindowed()
  75.   return 0
  76.  
  77. The Rexx program should return a zero result code, and StartDos will start
  78. the DOS session.
  79.  
  80. StartDos is IBM Employee Written Software. Please read the "as-is" license
  81. agreement from IBM. Essentially, you use this program "as is," and IBM
  82. makes no warranty about the correctness of this program or its suitability
  83. to any purpose.
  84.  
  85. Monte Copeland, IBM Boca Raton.
  86.  
  87.  
  88.  
  89. ----------------------- SPECIAL STARTDOS FUNCTIONS -----------------------
  90.  
  91. These special functions are available to Rexx programs invoked from StartDos:
  92.  
  93.   AddDosSetting( <setting string> )    /* may be called multiple times */
  94.   ExecSynchronous()                    /* asynchronous start is default */
  95.   SetCommandArgs( <command.com args> ) /* args acceptable to command.com */
  96.   SetSessionTitle( <session title> )   /* title to appear in window list */
  97.   StartBackground()                    /* start session in background */
  98.   StartForeground()                    /* foreground start is default */
  99.   StartFullscreen()                    /* fullscreen start is the default */
  100.   StartSeamless()                      /* start windows program seamlessly */
  101.   StartWindowed()                      /* start session in a text window */
  102.  
  103. AddDosSetting( <setting string> ) -- AddDosSetting may be called multiple
  104. times in order to specify all the setting strings to StartDos. Expects one
  105. string parameter.
  106.  
  107. ExecSynchronous() -- The default exec is asynchronous; i.e., StartDos will
  108. end as soon as the child DOS session is started. A synchronous exec is one
  109. where StartDos waits until the child DOS session ends before StartDos itself
  110. ends. In this case, StartDos will return the same errorlevel as COMMAND.COM.
  111. COMMAND.COM in OS/2 returns the same errorlevel as the DOS program invoked
  112. with the /c option. Therefore, a synchronous exec and /c option causes
  113. StartDos to return with the same errorlevel as the DOS program. This is
  114. important when invoking DOS programs from OS/2 batch (or make) files. Expects
  115. no parameter.
  116.  
  117. SetCommandArgs( <command.com args> ) -- Parameters to COMMAND.COM may be
  118. specified two different ways: on the StartDos command line after the Rexx
  119. command file name, or by using SetCommandArgs() in the batch file.
  120. SetCommandArgs() always overrides arguments given on the StartDos command
  121. line. COMMAND.COM arguments given on the StartDos command line may be
  122. examined from the Rexx file by using PARSE ARG. NOTE: when using
  123. StartSeamless(), SetCommandArgs() sets arguments to WINOS2.COM, not
  124. COMMAND.COM. Expects one string parameter.
  125.  
  126. SetSessionTitle( <session title> ) -- Sets the session title that appears in
  127. the Window List. Expects one string parameter.
  128.  
  129. StartBackground() -- Start the DOS session in background. No parameters.
  130.  
  131. StartForeground() -- Start the DOS session in the foreground. This is the
  132. default action. No parameters.
  133.  
  134. StartFullscreen() -- Start the DOS session in its own, full screen session.
  135. This is the default action. No parameters.
  136.  
  137. StartSeamless() -- Starts a windows program seamlessly on the PM desktop. Use
  138. SetCommandArgs() to name the windows program using a command syntax
  139. acceptable to WINOS2.COM. For example, to start windows write.exe, use
  140.  
  141.   rc = StartSeamless()
  142.   rc = SetCommandArgs( "/s write" )
  143.  
  144. StartSeamless() expects no parameters.
  145.  
  146. StartWindowed() -- Start the DOS session in a PM text window. Expects no
  147. parameters.
  148.  
  149.  
  150.  
  151.  
  152. --------------------- SAMPLE REXX: CLEAN.CMD -----------------------------
  153.  
  154. Assume there is a DOS program called CLEANDSK.EXE that writes zeroes to
  155. unused sectors on a floppy disk. Using the Rexx address() function, you can
  156. write one Rexx file that senses whether it is running under CMD.EXE or
  157. STARTDOS.EXE. Under CMD, it invokes StartDos. Under StartDos, it calls the
  158. special StartDos functions.
  159.  
  160.      /* clean.cmd */
  161.      parse arg szDriveLetter .
  162.      parse source . . szRexxFileName .
  163.      select
  164.        when 'CMD' = address()  then do
  165.          'STARTDOS' szRexxFileName szDriveLetter
  166.        end
  167.        when 'STARTDOS' = address()  then do
  168.          rc = SetCommandArgs( "/c cleandsk" szDriveLetter )
  169.          rc = StartBackground()
  170.          rc = ExecSynchronous( )
  171.        end
  172.        otherwise do
  173.          say 'Unexpected execution environment'
  174.          return 4
  175.        end
  176.      end
  177.      return 0
  178.  
  179.  
  180. Then from an OS/2 prompt, enter
  181.  
  182.      CLEAN A:
  183.  
  184.  
  185. --------------------- SAMPLE REXX: SEAMLESS WINDOWS WRITE ----------------
  186.  
  187. This Rexx program starts the windows program WRITE.EXE seamlessly. For
  188. seamless starts, SetCommandArgs() really sets the arguments to WINOS2.COM. To
  189. WINOS2.COM, /s means standard mode and /3 means enhanced mode.
  190.  
  191.      /* write.cmd */
  192.      parse source . . szRexxFileName .
  193.      select
  194.        when 'CMD' = address()  then do
  195.          'STARTDOS' szRexxFileName
  196.        end
  197.        when 'STARTDOS' = address()  then do
  198.          rc = StartSeamless()
  199.          rc = SetCommandArgs( "/s write" )
  200.        end
  201.        otherwise do
  202.          say 'Unexpected execution environment'
  203.          return 4
  204.        end
  205.      end
  206.      return 0
  207.  
  208. --------------------- SAMPLE REXX: MULTIPLE SETTING STRINGS  ----------
  209.  
  210. You can specify more than one DOS character device driver with the DOS_DEVICE
  211. setting. You can specify more than one DOS_VERSION string at a time. In both
  212. cases, the strings must be separated with the linefeed character, ascii 10.
  213. The REXX function d2c(10) works to embed the linefeed character. Sample REXX:
  214.  
  215.     /* for startdos */
  216.     if 'STARTDOS' <> address() then do
  217.       say 'Expected StartDos environment.'
  218.       return 2
  219.     end
  220.  
  221.     /* this shows d2c(10) and the comma used for REXX line continuation */
  222.     rc = AddDosSetting( 'DOS_VERSION=DFIA0MOD.SYS,3,40,255'||d2c(10)||,
  223.     'EXCEL.EXE,10,10,4'||d2c(10)||,
  224.     'WIN200.BIN,10,10,4' )
  225.  
  226.     /* similar thing */
  227.     rc = AddDosSetting( 'DOS_DEVICE=c:\os2\mdos\ansi.sys'||d2c(10)||,
  228.     'c:\os2\mdos\ega.sys' )
  229.     return 0
  230.  
  231.  
  232.  
  233. -------------------------- ERROR CHECKING ---------------------------------
  234.  
  235. If you specify an incorrect DOS setting, chances are the session will start
  236. anyway. You may get an error message from OS/2. StartDos itself may exit with
  237. a failed assertion.
  238.  
  239. For brevity, most of the sample Rexx shown here does not do error checking.
  240.  
  241.  
  242. ------------------------ LICENSING  ---------------------------------------
  243.  
  244. Please read the IBM license agreement in LICENSE.TXT.
  245.