Getting started

Antivirus program blocks vDosSetup

Before a new version of vDos is released, vDosSetup and vDos are submitted to www.virustotal.com and tested against over 60 anti-virus programs. Eventual false positives are then reported to those anti-virus companies.

But it seems an anti-virus program could still later on mistrust the same vDosSetup it once approved of; Windows Defender (once/twice?) did.

If your anti-virus program complains about vDosSetup; first make sure its virus database is up-to-date. Eventually go to www.virustotal.com, and check vDosSetup (www.vdos.info/vDosSetup.exe) for yourself.

Install vDos

When you run the downloaded vDosSetup installation program, it will offer to create a vDos folder on your C: drive. You can select another location, but C:\vDos is a good starting point for a first-time impression and testing.

vDosSetup doesn’t modify anything to your Windows system internals. It only creates that vDos folder, a start menu entry and a shortcut on the desktop. There’s even no uninstall option. If vDos doesn't work for you, you'll have to delete those mentioned items by hand!

The vDos folder will contain these files:
autoexec.txt
The equivalent of DOS autoexec.bat.
config.txt
DOS had config.sys, Windows config.nt, vDos config.txt. Like autoexec.txt, the .txt extension is for easy editing, without Windows trying to ‘execute’ something.
Getting Started.pdf
An introduction to vDos, please read this.
Printing.pdf
Documentation on vDos’ printing capabilities. To be read once you come to printing from your DOS application(s).
vDos.exe
The Windows program emulating a DOS PC to run your application(s).

And one subfolder:
DPTEST
The DataPerfect TestDrive demo program, started by the initial autoexec.txt file. Once you ran it to confirm vDos will work on your Windows system, you can of course delete this folder.

Start vDos by either the desktop shortcut, or the vDos start menu.
The vDos window should appear, waiting for a keystroke to start the DataPerfect Testdrive demo DOS program.

The demo ran fine; how do I run/test my DOS application

Once your application ran in DOS, then it was migrated to Windows 32-bit.
Now you’re facing vDos, it is ‘merely’ a Windows program that should enable you to run that DOS application (with additional features) in Windows 32 or 64-bit.

For now, we’re in a testing phase, and assume vDos is installed to the default Windows C:\vDos folder.
Open the vDos autoexec.txt file, and just delete all its contents; the demo program doesn't need to start anymore. Save the empty file, and start vDos again.
That will bring the famous C:\: DOS prompt. Notice however that vDos C: isn't Windows C:! Instead the vDos C: at this moment defaults to the Windows C:\vDos folder. Eventually do a DIR command to see the files and folders on this vDos C: drive. Leave the vDos window open.
You will still have your application running on some system. Copy its folder(s) to the vDos folder. So you’ll have something like C:\vDos\DosApp, C:\vDos\DosData…
Have a close look at how the application was started before. That would be by some batch file, we’ll assume it is “start.bat”. If it isn’t already in the copied folder(s), copy that also to the C:\vDos folder.
Do another DIR command in the vDos window, you’ll see the newly copied folder(s). Now start the application by start.bat (it’s in vDos C:), or folder\start.bat (substituting folder by the name start.bat is located in). If the application starts, you end it and get back to the DOS prompt; Close the vDos window by issueing EXIT.
If the application doesn’t start, that will most likely be because it expects (relies on) a drive letter or directory structure that doesn’t match what we got so far in vDos. If it for instance expects a F: drive letter with the program and data files (DosApp, DosData…), you’ll have to assign the vDos F: to the correct Windows folder. That would be C:\vDos in this example. Issue USE F: C:\vDos, then select that drive by F:, so you’ll get a F:\> DOS prompt. Now try to start the application again. If it still doesn’t start, open the batch file that starts the application in for instance Notepad (don’t double click the batch file!). Look for the line that starts your application. If some other program is started before that, temporary disable that by adding REM. For instance REM program, save the batch file, and try again.
If you still have troubles starting the application, post your problem at the vDos forum. Specify what vDos version you’re using (should be the most recent), what directory structure you have (C:\vDos\DosApp…), what application you try to start, and how it is supposed to start (the start.bat contents).

Start the application by starting vDos

Open autoexec.txt, if you didn’t already delete its contents, do it now.
Add the command lines that you entered by hand in the previous section, for instance:
USE F: C:\vDos
F:
CALL DosApp\start.bat
Save the file, and start vDos again.
Issue EXIT to close the vDos window.
If your application didn't start, correct the command lines in autoexec.txt.
Add a last command line to autoexec.txt: EXIT, so the vDos window will close the moment you end the application.

Roundup, ‘going live’

We assumed you copied the application folder(s) temporary to Windows C:\vDos. And the application was started by autoexec.txt with:
USE F: C:\vDos\
F:
CALL DosApp\start.bat
EXIT

To start the application with the ‘live’ data, change the folder reference in the first line to where the DosApp is actually located. For instance:
USE F: D:\DOS\
or
USE F: \\server\share\

That’s it.

If you have more than one DOS application:
Copy config.txt and autoexec.txt to a separate folder, preferably nearby the second application.
Modify autoexec.txt so that application is started. Eventually temporary rem-out the last EXIT and test.
Create a new (desktop) shortcut to vDos.exe, or just copy the installed one.
Give it a sensible name, like “DOS accounting”. That will also be displayed in the caption bar of the vDos window.
Go to the properties of the shortcut (right click), set the "Start in:" property to the folder containing the autoexec.txt and config.txt of that second application.
Eventually, if you like to; assign a Shortcut key, or some other icon image to the shortcut.

Miscellaneous

FILES= and other directives, once in config.sys

BUFFERS=nn
This was a kind of basic disk caching, it has no meaning anymore. Since vDos isn't the operating system (DOS once was) controlling the drive, any caching would be a disaster for your data on the drive, waiting to happen.

DOS=HIGH,UMB
DOS itself in vDos runs outside the virtual PC; it is no longer some 16-bit code executed by the (emulated) CPU. So this directive is also meaningless in vDos; there is no DOS code in the virtual PC/memory.

DEVICE=whatever
vDos doesn't need device drivers. For instance ansi.sys is built-in.

FILES=nn
The number of global DOS file handles in vDos is always 255. The maximum, since DOS file handle numbers are bytes.

STACKS=nn,nn
Simulated 32-bit DOS in vDos has no use for this directive.

SHARE - Record locking (RL) by multi-user applications

In the DOS days, RL was provided by the SHARE program. If more than one need to access the same data, the (mostly a database) program occasionally requires exclusive access to some parts of files (RL data and indexes). “I’m going to modify those, can’t have someone else messing around with that while doing so”.

The operating system (OS) in control of the disk maintains a table of regions granted a RL request by a program. DOS is since Windows NT no longer that OS, SHARE useless: Its functionality provided by Windows itself, or the OS managing the network drive. vDos secures RL is reliable functioning for a drive, then mostly just forwards SHARE requests to the equivalents of Windows. RL (by database programs) is more complex, but this will do.

Some DOSBox mods (like that of dbDOS) 'support' RL, but turn out to be a disaster. dbDOS even once demonstrated RL functionality! But besides exclusive access, the DOS program data has to match what’s actually on disk that moment. DOSBox (mods) caches disk operations, possibly outdated data lurking all around. One DOSBox mod ‘solution’ first updates the caches with RL. That doesn’t do it either: Local caches at other PC’s will still destroy the delicate database structures. Especially indexes are vulnerable due to the very compact and structured organization. DOSBox file caching is also why it can sometimes outperform Windows NTVDM, and then certainly vDos.

My application (sometimes) runs slower than before

To overcome Windows 64-bit not able to execute 16-bit programs, vDos emulates a 80386 CPU in software. A single emulated CPU instruction will result in many instructions to the actual CPU. The operating state, internal registers of the emulated CPU are maintained in relatively slow memory, and more technical stuff...
In raw processing power the emulated CPU can be up to 40 times slower than the real thing! The emulated CPU got over 100% faster the last years, but no further significant improvements should be expected.

DOS applications however don’t run that much slower. They frequently call BIOS and DOS functions, mostly executing faster than before (emulated in 32-bit mode). Reading from and writing data to disk is the real bottleneck for a program, that also is at least as fast. On average DOS programs will operate only a few times slower than on a real DOS PC or Windows 32-bit/NTVDM. Not that an issue; with user interaction, a program is still constantly waiting for user input. Whether she/he then has to wait 0.01 or 0.05 seconds before the program responds, isn’t noticeable.

But w/o user interaction, few BIOS/DOS calls, little disk access, lengthy CPU intensive tasks. Like sorting database records in memory, the slowness of the emulated CPU will become more profound. You just have to life with that.

No LFN support?

DOS was originally restricted to 8.3 filenames; 1-8 characters for the name, 1-3 characters for an optional extension. Windows came along with Long File Names (LFN’s), supporting up to 255 characters. Microsoft also came up with a scheme so DOS programs could access those LFN files: Short File Names (SFN’s).

vDos doesn't support LFN's: LFN’s are used/supported by only a few (mainly utility) DOS programs. One specific version of a Zip/Unzip program, ditto file manager, and other obscure examples, just silly to be started in vDos. You have genuine Windows program for that!

vDos/DOS drive letters are not those of Windows

Once you had a DOS system, solely dedicated to run DOS programs and store its data. That DOS PC got replaced by a Windows PC. For simplicity we forget about Windows 3.x - 98 (mainly DOS programs), and skip to Windows NT/XP (not DOS based anymore).

Microsoft had to make sure DOS programs would still run. Not to make the same mistake as OS/2. Its lack of adequate DOS support (besides of being ahead of affordable hardware) was a deal breaker for DOS users.

Microsoft came with NTVDM (New Technology Virtual DOS Machine), integrated in Windows 32-bit. DOS programs could be started, largely as before in DOS. But that integration came with a cost; the Windows PC is surely no longer dedicated to run DOS programs. The Internet is surfed, email checked, MS Office used, and a lot more Windows specific stuff. Most folders and files have no meaning to DOS programs.

DOS programs got access to all Windows drives (letters) and directories, while there is no need for that. Certainly not the root of Windows boot drive C:. Windows even doesn’t like that. DOS programs need drive letters, these then have to be created for non-local drives in Windows, while Windows (programs) doesn’t need those.

Although you might be accustomed to DOS drive letters being those of Windows: Forget about that. The vDos
USE command allows to only make available those regions of Windows filesystem your DOS program needs accessing. Even if you don’t want to forgo for instance a Windows F: drive being mapped to a network share; don’t do USE F: F:\. That is a (possibly confusing, even troublesome) roundabout. Instead do the direct USE F: \\server\share\.

vDos full screen mode isn’t real full screen

PC monitors evolved since DOS; CRT to LCD/LED, 4:3 to 16:9 widescreen. TV’s also did, occasionally a popular old serial (DOS) is rerun, 4:3 content however doesn’t fit a 16:9 sized modern TV (PC monitor). You get bars alongside, or a stretched image:


It’s not vDos (nor Windows) to blame you don't get what you expected. If you really want a full screen image, you'll have to connect a 16:10 or old-fashion 4:3 sized monitor to your new Windows PC.

Some programs of all I tried out, didn’t run

vDos is meant to run productive DOS programs still being used (by you). Not to play with.

Printing

DOS printing

Printing by a DOS application differs completely from Windows printing. vDos should however by default mostly determine correctly how to handle that. So just start with what that will bring.

One major exception will be if you print to an actual old-style DOS printer. vDos supports that also, but you might consider to switch to Windows printing. So you can use any printer supported by Windows (for instance also PDF).

Keep in mind, the DOS LPT/COM in vDos isn’t that of Windows. With that you were only able to print to actual DOS printers. Even if you convinced Windows to print to an USB or network printer instead.

Troubleshooting

The printing capabilities/options of vDos are covered by the Printing.pdf document in the vDos folder. If printing doesn't work as expected: Read that document. Many questions in the past just came from not reading (anything).

vDos creates two files before the actual printing process starts: #LPTx/#COMx.asc (x being the port number), and a .txt version of that. Those however have no value for vDos itself whatsoever. The .txt version is mostly a means to export (large amounts of) data, to be imported by a Windows program (the DOS ASCII text is translated to Windows Unicode). The .asc version contains the data stream as send by your program to the printer. It is generated to facilitate an eventual third-party DOS-to-Windows print processor, and for debugging purposes.

If you have an issue with printing: Submit a copy of the generated .asc file, so the problem can be reproduced and investigated (that’s the debugging part).

The COMx port isn’t related to a printer

By default, writing to LPTx/COMx ports (DOS, BIOS or direct hardware) is considered to be a printing task.

If COMx however is supposed to access some serial device; use the
COMx = "COMy": directive in config.txt. Mind the trailing colon, it is mandatory. You also have to initialize the (Windows) COMy device before starting vDos. By the MODE COMy command, or the device manager.

Support of serial devices is basic. To add further support, I would to have such a port, hardware device, and DOS software using those. I don’t, and gave up communicating with those (initially) willing to do some testing. Though that basic support should mostly work, as reported so far.

Digital printing with stationary (PDF)

Documents are more and more stored and sent digitally, instead of printed out on paper. Sending documents to clients by email, you want those to resemble closely the former printouts on your stationary. vDos’ internal print processor doesn’t support (bitmap) graphics, but that actually is of no concern to produce high quality digital documents.

You’ll need:
A digital copy of your stationary, ask your print supplier for the PDF file(s), vector based! Eventually modify those, or even create your own. As I did with PagePlus X8 of Serif; I created InvoiceBack.pdf from scratch as an example.
A virtual PDF printer that creates a PDF file, instead of printing to paper. A freeware PDF printer, capable of merging two PDF files, could do. But for instance novaPDF Professional is more versatile with his profiles, options and different handlings of documents: What stationary to use, how to name, where to store…

I created two files by hand:
InvoiceBack.pdf: The stationary used for invoices.
Invoice.txt: Output of an imaginary DOS invoicing program, just plain ASCII (DOS) text.

The setup in config.txt:
LPT1 = sel:"novaPDF 9".

Since there’s no actual invoicing program to print, this was mimicked by COPY INVOICE.TXT LPT1 at the vDos command prompt. The Select Profile dialog of novaPDF pops up (I have several profiles), I chose the temporary test profile “Invoice”. That is setup to merge the printers output with InvoiceBack.pdf to a PDF file with an incrementing number as its name (matching the invoice number), save it to the designated folder for invoices, and open it in the default PDF viewer. The result isn’t that bad for a simple test.

Generating PDF’s this way, keep in mind:
Make sure (test one PDF file) the PDF documents can actually be printed as expected; PDF version 1.4 gives consistent good results for me. Effective general testing: Print to Microsoft XPS document Writer :).
Consider what actions to allow with the PDF's; you won’t want for instance invoices to be modified. I just set them to print-only.
Spent some initial time on fine-tuning the PDF's, and optimizing the automated document handling.

Advanced

Windows environment variables in vDos

If you want to use a Windows environment variable (for example, %systemroot% or %homedrive%) in vDos you must first explicitly declare it, either in autoexec.txt, in another batch file, or at the command line. The Windows variable must be surrounded by two percent signs on each side:
set vdosvar=%%windowsvar%%

For example, before you can use Windows %systemroot% in your DOS program or batch files, you must first declare it:
set systemroot=%%systemroot%%

At startup, one Windows variable is already set to a DOS variable:
WIN_VDOS: The VDOS variable if set in Windows (%VDOS%), the command line parameters of vDos.exe, or “” if both are missing.

Start a Windows program or command processor

The vDos specific CMD command is linked to Windows command processor (CMD). It can be used at the vDos command line, or from within a program by:
CMD ["program"] [WAIT][HIDE] command line

"program": If supplied, the quotes are mandatory.
WAIT: Wait for the program or command processor to complete.
HIDE: Start the program or command processor minimized.
command line: Passed on to the program or command processor.

Eventual paths in command line (as in “program”) are those of Windows.

The optional WAIT and HIDE have to be in capitals. Mind, WAIT in combination with the Windows command processor has a major limitation: If that executes a command or program, it will exit immediately. While for instance the external program could still be running. The exit code will then merely indicate if the program could be started.

Some examples:
CMD notepad mydoc.txt
CMD HIDE /c mytest.bat
CMD /c start /max notepad


You can also call a Windows program from within a DOS program, without the use of the Windows command processor:
program [WAIT][HIDE] command line

Here program is a DOS reference with its limitations like 8.3 file names. Essentially vDos will determine what it is supposed to be: A DOS or Windows program. And will start that inside the virtual PC (DOS program), or in a new window (Windows program). Program can for instance even be a document, to be opened by the associated Windows program.

Note: Some DOS programs don’t execute external programs directly, but call the DOS command processor (command.com) to do that.

A portable DOS application

In autoexec.txt you could have something like:
USE F: \\server\DOS\
F:
CD DOSapp
mydosapp.exe

Great, you already used the direct UNC path, instead of mapping a Windows drive letter to it, and then refer to that drive letter. Can we even do without any (Windows) path at all?

Sure, when vDos is started, the Windows work directory for this vDos instance is set to the folder vDos.exe is started from. If vDos.exe would be located in \\server\DOS, that will become the Windows work directory. A relative path works equally well for the USE command. So we can also do:
USE F: .\
Or if we have a separate vDos folder (\\server\DOS\vDos):
USE F: ..\

What will a portable DOS application eventually bring?
First, if you can get to (start) vDos.exe, your application will run. No matter from where it is started, or its location (local, network, RDP, VPN, in the cloud…).
Second, you can relocate the application without any modification needed. Or create a copy of it on another location, for testing, backup…

Build your own copy/version of vDos

Here is a beginner's guide to building a copy of vDos from the sources. There is only one reason to do this: If you want to make your own copy of vDos that includes changes in the source code. This procedure was tested under Windows 8.1, but should work with any recent Windows version.

This assumes a basic understanding of Windows software (for example, you should know how to open .7z archives). You will be able to do very little with the source code unless you know something about C/C++, but you may be able to make some useful changes with very little knowledge.

If you have any questions about these instructions, you should be able to figure out the answers for yourself by experimenting or by searching the internet.
Request the vDos source code; start by visiting this page.
Use a standard archive manager (e.g. 7zFM.exe) to extract the vDos folder from the vDosSources.7z archive to any convenient place on your system (such as your desktop).
Download the free Visual Studio Community Edition from the Download link on this page.
Run the downloaded installation program, and proceed as follows.
Check the box where you agree to the license terms; click Next.
Remove the checkmarks from everything on the list of “Optional features to install”; click Install and proceed through the installation. At the end, do not click “Launch" but simply close the installation program.
In the vDos folder that you extracted to your disk in step 2, open the visualc_net folder and double-click on vDos.sln.
When Visual Studio opens, you can sign in with a Microsoft account if you want, or you can ignore the sign-in option.
Visual Studio will offer to upgrade the VC++ Compiler and Libraries. Click OK.
In the Solution Explorer on the left you will see vDos in bold. Right-click on it, and choose Build from the pop-up menu, and wait while the project builds.
When the Output window shows “Build: 1 succeeded…”, go back to the vDos folder and go to the vDos\bin folder. You will find the copy of vDos.exe that you built.

You may now experiment with the vDos source code and rebuild vDos to experiment with the results of your changes.

You may close Microsoft Visual Studio after building vDos.