Control parameters using runonce.ini

The runonce.ini is a configuration file used to set the parameters for the next print job. It is typically used by programmers to specify how a PDF should be created and where it should be saved.

In structure the runonce.ini is a normal ini configuration file with a main section and simple name value pairs in a text file. It can look something like this:

[PDF Printer]

One Job

A runonce configuration is only meant for one print job. When the printer sees a runonce configuration it will read it and delete it, so that it does not affect the next job.


Printing is an asynchronous process where a program places a print job on the print job queue. Job on the print queue is handled by the Windows Spooler process and sent to the individual printers. Therefore, a program cannot know when a specific print job is up for printing. It can send it to the queue but then it is up to the Spooler.

When printing multiple jobs without any pause between the jobs, you risk overriding a previous runonce.ini before it has been picked up by the corresponding print job. There are basically two strategies you can use to avoid this problem.

The first is to wait for your print job to finish before sending the next one. Let’s say that you are a programmer and want to print multiple PDF documents in a loop. In this case it is recommended that you use the statusfile setting to specify a unique status file name for each job. After you have written the runonce configuration and sent the job to the printer, you wait for the status file to appear. When you see the status file, you can read it and move on to the next job. The benefit of waiting for a status file instead of the actual document is that the status file will also be created in case of an error. The other benefit is that the resulting PDF document is completed when the status file is written. If you simply look for the PDF document then it may not be complete when you first see it in the file system.

The second method require that you can control the name of the print job in the printer queue. This is possible from many programming languages but it may not be possible in other systems. If you can set the print job name then you can create a specific runonce configuration that will only be picked up by that particular print job. More information is available here:

Parallel Printing

In case you need a high throughput of print jobs, you can install multiple printers with dedicated printer ports. You can read more about Printing to multiple virtual printers simultaneously here:

Terminal Server and Citrix

The runonce configurations are user specific. This means that runonce files from one user does not affect other users on a system with multiple users. This means that it is safe to use on a Terminal Server.

Creating Runonce Files

Given that the runonce is a simple text file, you can use any programming technique for writing text files to create a configuration. The location and character encoding are documented here:

Instead of writing the configuration files directly, it is recommended that you use the API to do that. The API will know the correct location for the current users on the specific version of Windows. The API is available in both COM and Microsoft.NET versions.


This is a link to an example of how to use the runonce from code:

More examples can be found here: