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.
You must assign your print file to "-P SPOOLER" or to "-Q <printername>" in the configuration file to access the Windows print spooler. This is described in section 1.2.9 of your Getting Started book.
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.CAUTIONS
Just as with changes to fonts and menus, modifications to Windows printer settings are global for a specific instance of the runtime. Settings established in one COBOL application will affect subsequent COBOL applications performed in the same runtime instance. If you do not want settings to apply globally in this case, you must reverse the settings manually within the program. However, these modified printer settings will not affect later executions unless you store the settings and reactivate them at the next instance of the runtime. Windows global settings, other windows applications and other instances of the runtime are not affected by changes made by the WIN$PRINTER library routine.
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 INPRINT-NO-OF-PRINTERS to zero before accessing printer-specific information.
Usage
CALL "WIN$PRINTER"
USING OP-CODE, parameters,
GIVING RESULT
Parameters
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.
OP-CODE 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-GET-SETTINGS-SIZE
| none
|
| WINPRINT-GET-SPOOL-ERR
| 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-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-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-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-PRINTER-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 booklet.
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.
Error Handling
When you call WIN$PRINTER, it returns a status value. This numeric value is returned in the CALL statement's GIVING data item, or the special register RETURN-CODE if no GIVING item is specified. A positive value indicates that the routine succeeded. A value of zero or less indicates that an error or exception occurred. These situations have level 78 values defined for them in "winprint.def". The defined values include:
WPRTERR-BAD-ARG This code indicates an unknown operation code or illegal value for any of the WIN$PRINTER functions.
WPRTERR-BAD-DRIVER This code is returned when the spooler can't find a device driver that corresponds to the selected printer.
WPRTERR-BUFFER-TOO-SMALL This code is returned when the data item passed to the WINPRINT-GET-SETTINGS operation is too small to hold the spooler's current configuration.
WPRTERR-CANCELLED This code is returned when you use the WINPRINT-SETUP operation to display the printer setup dialog box and the user presses the "Cancel" button or closes the dialog box without pressing the "OK" button. This status can usually be ignored because the runtime automatically restores the prior configuration.
WPRTERR-DEVICE-INCAPABLE This code is returned when you try to print a bitmap and the printer you are using cannot print bitmaps.
WPRTERR-DRV-LOADFAIL This code is returned when WIN$PRINTER failed to load the driver information for the chosen printer. This could be caused by a corrupted file, bad registry settings, or a remote printer being offline.
WPRTERR-ENUM-FAIL This code is returned when one of the WIN$PRINTER functions does not find any available printers on the system.
WPRTERR-NO-MEMORY This code indicates that the system ran out of memory when trying to perform the requested operation.
WPRTERR-SPOOLER-CLOSED This code is returned when you attempt to print a bitmap on a closed print file.
WPRTERR-SPOOLER-OPEN This code indicates that the program tried to change the spooler's configuration while a spooled print file was open.
WPRTERR-SPOOL-ERR This code is returned when there is an error in the Graphical Device Interface (GDI) layer that is not listed in "winprint.def". Use the operation WINPRINT-GET-SPOOL-ERR to obtain the exact Windows API code and refer to your Windows SDK documentation for a description.
WPRTERR-UNSUPPORTED This code is returned whenever WIN$PRINTER is called on a machine that is not a Windows machine.
WIN$PRINTER op-codes
The following is a list of WIN$PRINTER operation codes and their affects. These level 78 items are all defined in "winprint.def".
More: