Getting started

Antivirus program blocks vDosSetup

Before a new vDos version is released, vDosSetup (and so vDos itself) is submitted to www.virustotal.com and tested against many antivirus programs. Eventual false positives are then reported to those antivirus companies.

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

If your antivirus 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. It only creates that vDos folder, a start menu entry and a shortcut on the desktop. So 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 has config.txt. Like autoexec.txt, the .txt extension is for easy editing, without Windows trying to ‘execute’ something.
Printing.pdf
Documentation on vDos’ printing capabilities. To be read once you come to printing from your DOS application(s).
Readme.pdf
An introduction to vDos, please read this.
vDos.exe
The program that will emulate a DOS PC to run your applications.

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

Start vDos by either the desktop icon, or the Windows 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 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 “startme.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 startme.bat (it’s in vDos C:), or by folder\startme.bat (substituting folder by the name startme.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 appropriate 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/those 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 startme.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 doesn’t start, correct the command lines in autoexec.txt.
Add a last command line to autoexec.txt: EXIT, so the vDos window will close automatically 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\startme.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 title bar of a framed 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 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 doesnt need device drivers. For instance ansi.sys is built-in.

FILES=nn
The number of global 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) in 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 needs 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 a disk maintains a table of regions that were granted a RL request by a program. DOS is since Windows NT no longer that OS, SHARE is 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 DOS SHARE requests to the equivalents of Windows. RL (by database programs) is more complicated, 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, w/o the DOS program knowing. One DOSBox mod ‘solution’ first updates the caches with RL. That doesn’t do it either: Local caches at other PC’s (eventually even waiting to be written to disk) 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. One single hardcoded real CPU instruction will result in many instructions to emulate this. The CPU operating state, internal CPU registers are maintained in relatively slow memory, and more technical stuff...
In raw processing power the emulated CPU can theoretically be as much as 70 times slower than the real thing!

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. DOS programs in vDos 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, disk access, the program doing lengthy CPU intensive tasks, the slowness of the emulated CPU will become more profound. You just have to life with that.

No LFN/SFN 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).

When a LFN file like “Microsoft1.doc” is created, Windows also creates a SFN for that file: “MICROS~1.DOC”. The first 6 characters of the LFN, followed by a tilde, then a digit. When another LFN file is created with the same first 6 characters, for instance “Microsoft3.doc”, the digit is incremented: “MICROS~2.DOC”. That digit goes up to 4, a fifth LFN file, like “Microsoft2.doc” will become “MI1BC3~1.DOC”. The first two characters, a 4 digit hexadecimal CRC of the LFN, a tilde and a digit.

vDos doesn’t support LFN, moreover these files don't show up as SFN in DOS (applications).
Only a few vDos users ever requested such support. When asked why, none was actually able to come with a general, practical, non-fictional reason or case.
LFN’s are supported by only a few (mainly utility) DOS programs. One specific version of a Zip program, ditto file manager, and other obscure examples, just silly to be started in vDos. You have genuine Windows program for that.
The whole idea of LFN’s is to get more descriptive filenames. The concept of SFN’s however results in less descriptive, even confusing or cryptic filenames. DOS programs intended to run in vDos cannot create LFN’s, nor the associated SFN’s (only Windows can do that). So why should they be able to open a LFN file by means of a SFN. That LFN file is obviously created by a non-DOS (Windows) program.
SFN’s are not ‘fool proof’. If “Microsoft1.doc” (SFN: “MICROS~1.DOC”) is copied to another folder, already containing that SFN (LFN: “Micros-whatever and case-.doc”), “Microsoft1.doc” will become SFN “MICROS~2.DOC”. Can it get more confusing or misleading, with SFN’s? Yes it sure can, just do some experimenting yourself.
SFN’s aren’t always created by Windows, some server editions don’t by default. External filesystems like on a NAS might suffer the same ‘problem’.
Microsoft already announced some time ago SFN’s were to be dropped in future Windows versions. It’s a mystery why for instance desktop Windows 64-bit still generates SFN’s, while it doesn’t support DOS programs at all.
Generating a SFN for a LFN is a burden for Windows. The SFN has to be unique within the containing folder. So Windows will start off with “MICROS~1.DOC”, then has to cycle through possible SFN’s, examining the complete folder listing over and over. Until it comes up with an new unique SFN. You should consider to turn off Windows generating SFN’s!

Note: You can still open a LFN/SFN file while hidden in directory listings. Just supply the SFN: “MICROS~2.DOC”. With 'full' SFN support, you also would have to know what that SFN actually refers to (“Microsoft1.doc”…?).

vDos/DOS drive letters are not those of Windows

Once you could have had a DOS system, solely dedicated to run DOS programs, and store the data of those programs. 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, mail checked, and a lot more Windows specific stuff. Most folders and files just 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 that 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:\ in vDos autoexec.txt. That is a (possibly confusing, even troublesome) roundabout. Instead do the direct USE F: server-name\share\.

vDos full screen mode isn’t real full screen

PC monitors evolved since DOS: CRT to LCD, 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 an old-fashion 4:3 sized monitor to your new Windows PC.

Some DOS programs I found and 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.

If you still 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 port or device 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. Read that when you get to printing from your DOS application.

If printing doesn’t work (as expected): First read the Printing.pdf document. Most 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 need to have such a port, hardware device, and DOS software using those. I don’t, and gave up communicating with someone who has, and (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 created and stored digitally, instead of printed out on paper. Sending those to clients, you'll want them 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 8".

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 resulting PDF 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

XMEM=: The more, the better?

In overall no, a DOS application will need a minimum amount of memory to run. Mostly, extra memory beyond this will remain unused, can even have a negative performance effect. For instance FoxProX will first ‘format’ all memory made available by XMEM= in config.txt. If it only needs 3 MB, while 63 MB is set, it will still initialize that extra 60 MB of memory. FoxProX won’t run any faster, but will take much longer to start!

Why then support 63 MB of XMS/EMS/EXT memory, while for instance 4 MB was already considered a luxury when most DOS programs were developed? Simply because 63 MB plus 1 MB conventional memory = 64 MB. In the past vDos made sure a program didn’t read/write beyond the set memory. An absolute maximum of 64 MB provided for some speed gain with these constant tests. For some time vDos is more optimistic with that, and leaves it to Windows to catch eventual memory violations.

The next vDos version won't have this directive anymore. 8 MB of both XMS and EMS memory will be provided.

Windows environment variables in vDos

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

For example, before you can use %systemroot% in vDos, you first declare it as:
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 to vDos.exe, or empty 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 exit.
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. An 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 start a Windows program directly from within a DOS program:
program [WAIT][HIDE] command line

Here program is a DOS reference with its limitations like 8.3 file names. 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). It 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 instead call the DOS command processor.

A portable DOS application

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

Great, you already use the direct UNC path, instead of mapping a Windows drive letter to it, and then refer to that. 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.