Managing DOS Settings

Written by Roman Stangl

DOS Settings in OS/2
Under the protected mode of OS/2, DOS Settings cross your way most likely in form of the DOS Settings dialog (which the WPS and applications like PC/2 use to allow a user to specify the settings of VDM sessions) and when passing them to DosStartSession or WinStartApp.

The layout of DOS Settings
When using DOS Settings, a notation similar to the process' environment obtainable from the PIB (Process Information Block) is used, that is individual entries are terminated by a \0 and the complete block is terminated by an additional \0. In C/C++ you would specify for example: char *pcSettings="DPMI_MEMORY_LIMIT=16\0" "EMS_MEMORY_LIMIT=0\0XMS_MEMORY_LIMIT=64\0"; Most importantly, you have to be cautious when using C runtime functions like strcpy, because the end of C strings will be indicated by the first \0 and not by the \0\0 which terminated a DOS Settings string.

Displaying the DOS Settings dialog
The DOS Settings dialog can be displayed by loading and calling entrypoint 11 from the VDM support DLL PMVDMP. PFFUNCPTR   *pWindows32PropertyDialog; if(DosLoadModule(ucBuffer, sizeof(ucBuffer)-1, "PMVDMP", &hDllPMVDMP)==NO_ERROR) DosQueryProcAddr(hDllPMVDMP, 11, NULL, (PFN *)(&pWindows32PropertyDialog)); The function prototype of that entrypoint is: typedef PCH (EXPENTRY PFFUNCPTR) (HWND hwndClient, HWND hwnd, PSZ pcIn, USHORT usIn,\                                  USHORT *pusOut, USHORT *pusWinMode); Assuming that you are using a multiline entryfield to specify the DOS Settings you have to convert the string returned by the MLE, where individual settings are terminated by \r\n, to the DOS Settings format before calling the entrypoint: Once the DOS Settings dialog returns, it has allocated memory where the modified DOS Settings are returned. Again, the DOS Settings format has to be converted into a format acceptable by the MLE:

Converting from and to the DOS Settings format
As said previously, DOS Settings use a format which isn't comfortable handled by C runtime functions. The function ImportDosSettings does perform the required conversions: In the above function you may note that we also check for an asterisk (*). This allows me to represent DOS Settings that may consist of multiple lines understandable to the user in the MLE. For example, DOS_VERSION may be displayed as: DOS_VERSION=EXE2BIN.EXE,5,02,255*MSD.EXE,5,00,255 IDLE_SENSITIVITY=100 IDLE_SECONDS=5 where the DOS Setting C string equivalent would be: "DOS_VERSION=EXE2BIN.EXE,5,02,255\nMSD.EXE,5,00,255\0" "IDLE_SENSITIVITY=100\0IDLE_SECONDS=5\0"

DOS Settings and launching DOS Sessions
Showing how to allow a user specifying DOS Settings with the standard OS/2 DOS Settings dialog is only half of the way to full DOS support, we're still missing how to specify DOS Settings when launching DOS executables (which of course includes WIN-OS2).

Though it is simple once one knows how, the DOS and PM programming references still don't specify that, but try to fool you with reserved fields. Fortunately it's quite easy, as ImportDosSettings can be used once again to convert the DOS Settings. And as many of you may have anticipated, DOS Settings are specified for VDM sessions in the STARTDATA.Environment field for DosStartSession and PROGDETAILS.pszEnvironment for WinStartApp: Depending on the API used, you pass the DOS Settings to DosStartSession as: StartData.Environment=pucDosSettings; or for WinStartApp as: ProgDetails.pszEnvironment=StartData.Environment; One additional word about WIN-OS2 sessions. Though you can start full-screen and seamless WIN-OS2 sessions with DosStartSession it is recommended to use WinStartApp instead, because only the later API honours requests to start a WIN-OS2 application into an already running common WIN-OS2 session (program types PROG_31_STDSEAMLESSCOMMON and PROG_31_ENHSEAMLESSCOMMON). If you're more interested about starting WIN-OS2 sessions from an OS/2 program, you may take a look into the source of my PC/2 application.

Credits
Thanks to Monte Copeland, the author of TSHELL and MSHELL, for telling me about the undocumented entrypoint of the DOS Settings dialog. Passing DOS Settings to OS/2 API is based on some experiments influenced by discussions on Netnews and on IBMPC conference disk.