The WIN$PRINTER library routine is designed to enhance the ability of COBOL to take advantage of the Windows print spooler. This routine is available on all systems that run ACUCOBOL-GT, but is useful only with Microsoft Windows. Not all printer drivers are supported by this routine.
WIN$PRINTER configures the Windows print spooler only and cannot be used to configure the printer directly.
You must assign your print file to -P SPOOLER or to -Q printername in the configuration file to access the Windows print spooler.
If you have assigned your print file to -P SPOOLER-DIRECT or to -Q printername using the DIRECT=ON option, then you retain control over the format of the pages. In this situation, WIN$PRINTER can be used to select a printer, but not to print bitmaps or determine paper size, page orientation, fonts, margins, and the like. The information returned by WIN$PRINTER about the numbers of lines and columns on the page may not be accurate in this situation and should not be used.
When you change Windows settings in general, and printer settings in particular, Windows posts a message informing its subsystems of the change. The runtime looks for these messages and passes that information on to the WIN$PRINTER operation codes when they are called. This may cause inconsistencies between the information stored in the COBOL program and the runtime, such as the order of printers in the internal printer list. To avoid this problem, always use the printer name, rather than the printer number, when calling op-codes that require a printer identity. The name will always be unique, while the number is relative to the internal printer list and may not be accurate.
WIN$PRINTER always performs the printer number test before the printer name test. This means that if WINPRINTER-NO-OF-PRINTERS is a positive number, the function will look for that printer number before looking for the printer name. This could result in a WPRTERR-BAD-ARG error. To overrule this ranking and use the printer name, set the argument WINPRINT-NO-OF-PRINTERS to zero before accessing printer-specific information.
CALL "WIN$PRINTER"
USING OP-CODE, parameters,
GIVING RESULT
| OP-CODE |
A numeric value that selects which WIN$PRINTER function to perform. The op-codes are defined in winprint.def and described in the WIN$PRINTER op-codes section below. |
| RESULT |
A signed numeric data item that returns the status of the operation. The data type of the returned value is SIGNED-INT or PIC S9(9) COMP-5. Unless otherwise stated below, 1 indicates success, and a zero or negative result indicates failure. |
| parameters |
The remaining parameters vary depending on the operation code chosen. They provide information and hold results for the operations specified. Parameters may be omitted from those operations that do not require them. The parameters that apply to WIN$PRINTER op-codes are WINPRINT-DATA, WINPRINT-SELECTION, WINPRINT-COLUMN, WINPRINT-MEDIA, WINPRINT-JOB-STATUS and data defined in WORKING-STORAGE by the user. These are all defined in winprint.def. The parameters correspond to each of the op-codes as follows: |
| OP-CODE | Parameter |
|---|---|
| WINPRINT-SUPPORTED | none |
| WINPRINT-SETUP | none |
| WINPRINT-SETUP-USE-MARGINS | none |
| WINPRINT-GET-SETTINGS-SIZE | none |
| WINPRINT-GET-SPOOL-ERR | none |
| WINPRINT-SET-JOB | none |
| WINPRINT-UPDATE-PRINTERS | none |
| WINPRINT-GET-SETTINGS | user defined |
| WINPRINT-SET-SETTINGS | user defined |
| WINPRINT-SET-DATA-COLUMNS | WINPRINT-COLUMN |
| WINPRINT-CLEAR-DATA-COLUMNS | WINPRINT-COLUMN |
| WINPRINT-SET-PAGE-COLUMN | WINPRINT-COLUMN |
| WINPRINT-CLEAR-PAGE-COLUMNS | WINPRINT-COLUMN |
| WINPRINT-GET-PAGE-COLUMN | WINPRINT-COLUMN |
| WINPRINT-COLUMN-ALIGN-VERT | WINPRINT-COLUMN |
| WINPRINT-SET-STD-FONT | WINPRINT-DATA |
| WINPRINT-GET-PAGE-LAYOUT | WINPRINT-DATA |
| WINPRINT-SET-FONT | WINPRINT-DATA |
| WINPRINT-SET-LINES-PER-PAGE | WINPRINT-DATA |
| WINPRINT-GET-CAPABILITIES | WINPRINT-DATA |
| WINPRINT-PRINT-BITMAP | WINPRINT-DATA |
| WINPRINT-SET-MARGINS | WINPRINT-DATA |
| WINPRINT-GET-MARGINS | WINPRINT-DATA |
| WINPRINT-GRAPH-BRUSH | WINPRINT-DATA |
| WINPRINT-GRAPH-PEN | WINPRINT-DATA |
| WINPRINT-GRAPH-DRAW | WINPRINT-DATA |
| WINPRINT-SET-CURSOR | WINPRINT-DATA |
| WINPRINT-SET-TEXT-COLOR | WINPRINT-DATA |
| WINPRINT-SET-BKMODE | WINPRINT-DATA |
| WINPRINT-GET-JOB-STATUS | WINPRINT-JOB-STATUS |
| WINPRINT-SET-JOB-STATUS | WINPRINT-JOB-STATUS |
| WINPRINT-GET-PRINTER-MEDIA | WINPRINT-MEDIA |
| WINPRINT-GET-NO-PRINTERS | WINPRINT-SELECTION |
| WINPRINT-GET-PRINTER-INFO | WINPRINT-SELECTION |
| WINPRINT-SET-PRINTER | WINPRINT-SELECTION |
| WINPRINT-GET-CURRENT-INFO | WINPRINT-SELECTION |
| WINPRINT-GET-CURRENT-INFO-EX | WINPRINT-SELECTION |
| WINPRINT-SET-PRINTER-EX | WINPRINT-SELECTION |
| WINPRINT-GET-CURRENT-INFO-EX | WINPRINT-SELECTION |
| WINPRINT-GET-PRINTER-STATUS | WINPRINT-SELECTION |
To use this library routine you must include the COPY file winprint.def. You will need to copy this file into the Working-Storage section of any program that calls WIN$PRINTER. You must also assign the print file to either -P SPOOLER or to -Q <printername>, as described in your Getting Started guide.
WIN$PRINTER takes one or more parameters. The first parameter is a mandatory operation code that indicates which sub-function of WIN$PRINTER to perform. The operation codes are described under WIN$PRINTER op-codes, below.
The other parameters are optional data items defined in winprint.def or defined by the user in Working-Storage. You use these data items to pass data to and from WIN$PRINTER. The specific data passed depends on the particular operation being called. Some operations do not use a data item, in which case it can be omitted.
The definitions of WINPRINT-DATA, WINPRINT-SELECTION, WINPRINT-COLUMN, WINPRINT-MEDIA, and WINPRINT-JOB-STATUS are included in winprint.def. These definitions may change in future versions as capabilities are added to WIN$PRINTER. However, ACUCOBOL-GT will continue to support the existing formats.
When WIN$PRINTER is called, it sets a return value to indicate whether the call succeeded or failed. A positive value indicates success. A zero or a negative value indicates an error. The error codes are defined in the section on error handling, below.
If the call to WIN$PRINTER does not include a GIVING item for the return value, the return value is placed in the special register RETURN-CODE.
See graphprn.cbl and prndemox.cbl for examples of many of the WIN$PRINTER functions.
Several operations accept parameters that have values measured in the dots-per-inch (DPI) resolution of the output device. Using the Windows graphical device interface (GDI), a program can get DPI information for a given printer on the system. A demonstration program written in COBOL is available in the Support area of the Acucorp Web site. To download the program, open your Web browser and navigate to: www.acucorp.com/support/public/sample_programs/index.php. Select Graphical User Interface Sample Programs from the drop down list and click GetPrinterResolution.cbl.