Before you can print any information from a DP4 C program, you must open a print device, using either the dvc_choose() (if you want to allow the user to select the output device, or specify a filename) or dvc_open(), if you want to hard code the device to be opened, or you are going to manage device selection yourself. The opened device can have three distinct destinations: file,"printer" (the actual device, which may not actually be a printer), and screen.
A program can only have one set of print devices open at a time. However if you are printing to a device controlled by an OSDI you can use the dvc_set_subdevice() function to switch between the different component devices it controls. For example you might switch between a journal and a receipt printer on a POS device. There are also various other functions used only with OSDI devices. These are covered in more detail in the OSDI Developers Guide here.
Here is a typical call to dvc_choose():
dvc_choose(SCREEN + DP4_FILE + FT_DEFAULT, 1, "PRINT", ".OUT");The first parameter specifies the output devices. In this case, SCREEN and DP4_FILE are used to direct output by default to the screen and to a file, and not in fact to the printer.
The value FT_DEFAULT allows you to specify (as a fourth parameter) a default file extension to be used if the user specifies a filename without an extension. If FT_DEFAULT is not used the default file extension is .PRN
The second parameter is the number of the printer that you wish to use. Device 1 is a pre-defined device, "DP4", which can be used for creating files readable by the DP4 utilities DP4ED and VIEW. Usually you would not hard code a number here directly, but would use a symbolic constant such as MY_PRINTER. The DP4 utility DFSETUP has an option to create an include file with pre-processor definitions based on the devices on the system database. You also use DFSETUP to set up new printers and devices, if necessary.
We recommend that programs doing general purpose printing should print to the DEFAULT device, and that at installation time you arrange for this device to use a suitable print device. If you are using DP4 version 4.6xx on a on a Windows based computer you may choose to configure (via DFSETUP) the pre-defined DEFAULT_PRINTER device to use DFPRINT. This can then print to any printer supported by the Windows OS wiith full support for fonts,color and bitmaps. One drawback of doing this is that files created using this device are not readable by other software, so you may prefer to print to DFPRINT when doing real printing, and some other device when printing to a file. You can also use the -device command tail to specify the DP4 print device on the command line.
The third parameter is the default value for the filename (without extension). The filename can be changed by the user through the dialog dvc_choose() creates. If this filename exists, a second screen is displayed that allows the user to delete the file, append output to it, or to cancel output to the file and return to the device selection dialog.
If dvc_choose() succeeds one of two values is returned:
The value 1 is returned if a real printer is opened, or the call to dvc_choose() did not specify the PRINTER flag.
The value 0 is returned if the program specified the PRINTER flag and printing will be via a spooler, such as the DFPRINT.
If the function fails, because the user cancelled the dialog, or because a file could not be opened etc, then the value ESCAPE is returned.
It should be noted that at present a DP4 program can only have one set of print devices open at a time. If a program calls dvc_choose() or dvc_open() a second time any existing print device is released.