Printing

When A QA Build program prints, by sending maps to an output device, it may be sending the output to a printer, a file, the screen, or any combination of the three. The output may in reality be controlling specialised hardware such as a cash drawer or other POS device. Maps for printing are created in exactly the same way as ordinary maps and the same map may be output to the screen in an interactive procedure, and output to a print device in a print procedure. In the context of printing, maps are usually called forms.

Before a program can print, it must initialise a printer or other output device. Initialising an Output device requires two or three main pieces of information:

A bitmask to specify which of the possible output destinations are required, together with the various other flags you can set up in the Output devices dialog.
The name of a print device that determines how information should be sent to and formatted for a particular device. Print devices are described using a Parameterised Output Device, or POD, which describes a particular configuration of a Component Output Device (COD) in a Device Group. PODs, CODs and Device Groups are stored on the system database and are created using DFSETUP. This process is described in the OSDI Developer's Guide here.

The print device is relevant even if you do not select "printer" as one of your output destinations. If you are printing to a file, the print device will determine aspects such as the pagination of the file, and any escape sequences it contains, and can even result in a completely different file format or character set being used. Printing to screen using DFPRINT is radically different from printing to screen using one of the other print devices.
For printing to a file you need to specify the name of the file to open.

Initialising Printing

There are two places where you can initialise printing:

You can initialise printing and specify the output device in the program header.
You can initialise printing and partially specify the device in a procedure body.

In both places, your program can opt to allow the user to select his own print device. Typically you may well want to do this when printing reports to general purpose printers, as it makes the system more flexible. You are most unlikely to want to let the user choose print devices in a program controlling an OSDI - because your program may well want to select various sub devices (i.e. different component device set ups) at various points in the procedure tree. If the user has initially selected a completely different print device your program would fall over in a system error.

Once a program has intialised printing it the output devices remain open throughout that part of the procedure tree beneath it, and the program cannot intialise printing for different output devices, though it can use a Sub device output procedures to change the print characteristics in some way.

For example if a procedure has a procedure body that opens a print device, all the subsidiary procedures can print, or select different sub devices belonging to the same device group, but they cannot select a device belonging to a different device group. The print device will be closed on exit from the procedure, so the procedure on the right cannot print, unless it also opens a print device. You should also remember that if the device opened is a "real" printer other users will probably not be able to gain access to the printer all the time this part of your program is running. (This won't be the case if you print using the DFPRINT print spooler, the older WINPRIN, or the Unix/Linux print spooler)

The steps needed to initialise printing in the two cases are described on the following pages:

Printing to Multiple Print Devices

The behaviour described above can sometimes be a nuisance. For example a program using an OSDI might also want to be able to print a report to the DFPRINT program. There are two ways to achieve this:

Structure the program so that the various print devices you need are opened in completely separate parts of the procedure tree. This is a good solution providing it fits in well with your application architecture.
Call the procedures that need to print to another print device using a subprogram that initialises the appropriate print device. Use the %CALL facility, together with %SEND and %RECEIVE (if required), but do not use %OVERLAY. (See Calling QAB programs for more details of the %CALL facility). QAB will temporarily close the current output device while the called program runs. The called program will print as required. When control returns to the calling program it will reopen the original print device automatically and output will continue normally.

Both solutions work well for printing to ordinary printers. They may not be entirely appropriate if you are using an OSDI, as OSDIs may expect to be loaded throughout the lifetime of a program, once loaded. On systems where the OSDI is loaded as a DLL you may want to add a C exit that additionally loads the library directly from the application, preventing it from being unloaded if the device gruop used by the OSDI is closed temporarily.

This section covers the following topics: