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. All printer drivers are not supported by this routine.
Note that WIN$PRINTER configures the Windows print spooler only and cannot be used to configure the printer directly.
If you have assigned your print file to "-P SPOOLER-DIRECT," then you have retained control over the format of the pages. In this situation, WIN$PRINTER can be used to select a printer, but not to determine paper size, page orientation, fonts, and the like. Though you can print bitmaps with the WIN$PRINTER routine, but you cannot do so when you use "-P SPOOLER-DIRECT"(You may only include bitmaps in reports assigned to "-P SPOOLER"). Note that 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.
CAUTION: 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.
Note that 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.
Also, if you have changed printer settings and you CALL or CHAIN to a different program, your changes will apply in the new environment, unless you have saved and reapplied the defaults before printing in the CHAINed or CALLed program, the modified settings you established in the first program will apply. We recommend that you save the printer defaults with WINPRINT-GET-SETTINGS before making any modifications and restore the defaults with WINPRINT-SET-SETTINGS when concluding the current session of the runtime.
Usage
CALL "WIN$PRINTER" USING OP-CODE, parameters, GIVING RESULT
Parameters
OP-CODE Numeric value
Selects which WIN$PRINTER function to perform. The op-codes are detailed in the description section below.
RESULT Signed numeric data item
Returns the status of the operation. 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 and user-data, described below.
WINPRINT-DATA Group item defined in "winprint.def" as follows:
01 WINPRINT-DATA.
03 WPRTDATA-SET-STD-FONT.
05 WPRT-DATA-STD-FONT PIC X COMP-X.
05 FILLER PIC X(3).
03 WPRT-PAGE-LAYOUT REDEFINES
WPRTDATA-SET-STD-FONT.
05 WPRTDATA-LINES-PER-PAGE UNSIGNED-SHORT.
05 WPRTDATA-COLUMNS-PER-PAGE UNSIGNED-SHORT.
03 WPRTDATA-SET-FONT REDEFINES
WPRTDATA-SET-STD-FONT.
05 WPRTDATA-FONT HANDLE OF FONT
03 WPRTDATA-CAPABILITIES REDEFINES
WPRTDATA-SET-STD-FONT.
05 WPRTDATA-BITMAPS-OK-FLAG PIC 9.
88 WPRTDATA-BITMAPS-OK VALUE 1, FALSE ZERO.
03 WPRTDATA-PRINT-BITMAP REDEFINES
WPRTDATA-SET-STD-FONT.
05 WPRTDATA-BITMAP PIC X(4) COMP-N.
05 WPRTDATA-BITMAP-ROW PIC 9(7)V99 COMP-5.
05 WPRTDATA-BITMAP-COL PIC 9(7)V99 COMP-5.
05 WPRTDATA-BITMAP-HEIGHT PIC 9(7)V99 COMP-5.
05 WPRTDATA-BITMAP-WIDTH PIC 9(7)V99 COMP-5.
05 WPRTDATA-BITMAP-FLAGS UNSIGNED-SHORT.
03 WPRTDATA-MARGINS REDEFINES
WPRTDATA-SET-STD-FONT.
05 WPRTDATA-TOP-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-BOTTOM-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-LEFT-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-RIGHT-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-MARGIN-UNITS UNSIGNED-SHORT.
WINPRINT-SELECTION Group item defined in "winprint.def" as follows:
01 WINPRINT-SELECTION.
03 WINPRINT-NAME PIC X(80).
03 WINPRINT-PORT PIC X(80).
03 WINPRINT-DRIVER PIC X(80).
03 WINPRINT-DRV-VERSION PIC 9(7)V99 COMP-5.
03 WINPRINT-NO-OF-PRINTERS SIGNED-SHORT.
88 WPRTERR-NO-PRINTERS VALUE -1.
03 WINPRINT-IS-DEFAULT SIGNED-SHORT.
88 WPRT-IS-NOT-DEFAULT VALUE 0.
88 WPRT-IS-DEFAULT VALUE 1.
03 WINPRINT-COPIES SIGNED-SHORT.
88 WPRT-HAS-NO-COPY VALUE 1.
03 WINPRINT-ORIENTATION SIGNED-SHORT.
88 WPRT-HAS-NO-LANDSCAPE VALUE 0.
88 WPRT-HAS-LANDSCAPE VALUE 1.
03 WINPRINT-QUALITY SIGNED-SHORT.
03 WINPRINT-CURR-ORIENTATION SIGNED-SHORT.
03 WINPRINT-CURR-COPIES SIGNED-SHORT.
USER-DATA PIC (X)
User-data is defined by the user in Working-Storage.
Description
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 "-P SPOOLER", as described in Appendix A, section A.4.5.
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 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 and WINPRINT-SELECTION included in "winprint.def" may change in future versions as capabilities are added to WIN$PRINTER. However, ACUCOBOL-GT will continue to support the format given above.
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.
OP-CODES
The following is a list of WIN$PRINTER operation codes and their effects. These level 78 items are all defined in "winprint.def".
WINPRINT-GET-SETTINGS-SIZE --This operation returns the number of bytes needed to hold the current spooler configuration. The spooler configuration includes the destination device, paper size, and page orientation. It does not include the current font selection. Use this operation to ensure that you have a large enough buffer when using the WINPRINT-GET-SETTINGS and WINPRINT-SET-SETTINGS operations.
WINPRINT-SETUP --Calls the standard Windows Setup Printer dialog box. This allows the user to select which printer to use, the desired page orientation (landscape or portrait), and the desired paper size and source. The runtime internally configures itself based on the selections chosen by the user. These become the settings used during the remainder of the run (or until the next call to this subfunction). Note that the settings return to their defaults when the runtime exits. When this op-code is performed from the 32-bit runtime, the newer PageSetup dialog box will appear. The 16-bit runtime will use the 16-bit PrintSetup dialog box.
WINPRINT-SETUP-OLD --The WINPRINT-SETUP op-code, when used with the 32-bit runtime, calls the newer PageSetup dialog box by default. If you wish to use the 16-bit PrintSetup dialog box with the 32-bit runtime, you must use the op-code WINPRINT-SETUP-OLD.
WINPRINT-SUPPORTED --Sets the return value of WIN$PRINTER to "1" if the WIN$PRINTER routine is supported (i.e., the host machine is a Windows machine). Otherwise it sets the return value to WPRTERR-UNSUPPORTED.
WINPRINT-DATA op-codes
The following operation codes use the data item WINPRINT-DATA.
WINPRINT-GET-CAPABILITIES --This operation returns information about the capabilities of the currently selected printer to WPRTDATA-CAPABILITIES. Currently, the only capability returned to this parameter is whether or not the printer can print bitmaps. If it can, WPRTDATA-BITMAPS-OK is set to true. Printers that do not use a raster technology (such as a pen plotter) cannot print bitmaps.
WINPRINT-GET-PAGE-LAYOUT --This operation returns the number of print rows that can fit on a page in WPRTDATA-LINES-PER-PAGE, and the number of print columns in WPRTDATA-COLUMNS-PER-PAGE. This accounts for the current page size, orientation, and printer font. You may use this routine either before or after opening a print file.
Note: Because of the large number of variables involved with printing under Windows (for example, the font size, the paper size, and print orientation), we recommend that you use this routine to determine how many lines will fit on a page when you are formatting reports.
WINPRINT-PRINT-BITMAP --This operation prints a bitmap in the current report. The print file must be open when you are using this function. The bitmap is printed according to the data contained in WPRTDATA-PRINT-BITMAP. To ensure that elements are intialized to their default values, you should always INITIALIZE WPRTDATA-PRINT-BITMAP before filling in the elements.
WPRTDATA-BITMAP should contain the handle of the bitmap you want to print. You can obtain this handle by calling the library routine W$BITMAP with the WBITMAP-LOAD option. This can be the same handle as the handle of the bitmap you have displayed on the screen.
The upper left corner of the bitmap is located at the position specified by WPRTDATA-BITMAP-ROW and WPRTDATA-BITMAP-COL. These elements identify the row and column of the report. The currently selected font for the printer determine the rows and columns. The top left corner of the report is row 1, column 1. You can also use fractional rows and columns, but if you specify a row or column less than 1, then the bitmap is placed at row 1, column 1.
Many printers have much higher resolution than screens do. For example, many laser printers can print 300 or 600 dots per inch while most screens display less than 100 pixels per inch. An image that is 1024 pixels wide would fill or overflow many screens, but would be less than 2 inches wide on a 600 DPI printer. For this reason, bitmaps are usually scaled when they are printed. By default, the runtime scales the image so that the relative proportions of the printed image match those of the same image when it is viewed on the screen.
You can inhibit the scaling done by the runtime by setting WPRTDATA-BITMAP-FLAGS to WPRTBITMAP-PRINTER-BITMAP. This informs the runtime that the bitmap was designed directly for printing on the current printer and should not be scaled. You can also add the value of WPRTDATA-BITMAP-FLAGS to the other scaling options discussed below to prevent the runtime from performing an adjustment to the scaling. Adjustments are usually done to account for the difference in the relative proportions of the screen's X and Y density in comparison to the printer's X and Y density. Some devices have a much higher resolution in one dimension than the other. This adjustment handles the changes needed when you are viewing a screen image on a printer. Most applications, however, should avoid this option because most bitmaps are meant to be displayed on the screen only.
You can also scale the bitmap to be a particular size. Place the desired size in WPRTDATA-BITMAP-WIDTH and WPRTDATA-BITMAP-HEIGHT. The units are determined by WPRTDATA-BITMAP-FLAGS settings. One of the following values is used:
WPRTBITMAP-SCALE-CELLS -- the height and width correspond to rows and column in the report.
WPRTBITMAP-SCALE-INCHES -- the units represent inches on the printed page.
WPRTBITMAP-SCALE-CENTIMETERS -- the units represent centimeters on the printed page.
WPRTBITMAP-SCALE-PIXELS -- the units are printer pixels. In this case, fractional values are ignored.
You can either set both dimensions or leave one dimension at zero. When one of the dimensions is set to zero, it is computed to keep the relative proportions of the image unchanged after scaling in the other dimension.
Colors in the bitmap image are preserved by the runtime. It is up to the printer's driver to decide how to print color images on a black-and-white device. Most drivers turn colors into varying shades of gray.
The following sample code prints the ACUCOBOL-GT workbench logo in the center of an 80-character print line. It scales the image to be 30 characters wide to simplify the centering computation. This example assumes that the printer is already open:
77 LOGO-HANDLE PIC S9(9) COMP-4.
:
:
CALL "W$BITMAP" USING WBITMAP-LOAD, "devsuite.bmp" GIVING LOGO-HANDLE
INITIALIZE WPRTDATA-PRINT-BITAMP
MOVE LOGO-HANDLE TO WPRTDATA-BITMAP
MOVE 1 TO WPRTDATA-BITMAP-ROW
MOVE 26 TO WPRTDATA-BITMAP-COL
MOVE 30 TO WPRTDATA-SCALE-WIDTH
*Height left at zero
MOVE WPRTBITMAP-SCALE-CELLS TO WPRTDATA-BITMAP-FLAGS
CALL "WIN$PRINTER" USING WINPRINT-PRINT-BITMAP, WINPRINT-DATA
CALL "W$BITMAP" USING WBITMAP-DESTROY, LOGO-HANDLE
WINPRINT-SET-FONT --This operation allows you to select any printer font for spooled reports. First, you obtain a handle to the desired font with the W$FONT routine described earlier. Once you have the font handle, you can select it as the current font by setting WPRTDATA-FONT to the desired font handle and using WINPRINT-SET-FONT. The font is now associated with the current printer until you change the font again or the runtime finishes. Note that the font is only used for reports printed by the runtime's spooler handler, which you use when you assign a print file to "-P SPOOLER".
Fonts are device-specific. If you let the user change printers via WIN$PRINTER's setup operation, then the user should get a new font handle from W$FONT and associate it with the new printer.
You should not DESTROY a font handle that is currently selected as the print font, unless the printer is closed and you will not open it again. If you do, then that font will not be available to the printer.
You may use proportionally spaced fonts in print files. The runtime handles the proportional spacing correctly (in other words, it does not use a fixed width for each character). Because of this function, lining up columns is difficult, so you should normally use a fixed-width font. The runtime computes the number of columns that fit on a page for a proportional font by using the font's average width.
(See "winspool.cbl" for a sample program that uses arbitrary fonts chosen by the user.)
WINPRINT-SET-LINES-PER-PAGE --This operation sets the number of lines that should be printed on a page.
Printing forms using the Windows spooler is sometimes difficult because you cannot easily control the height of a chosen font. Most Windows fonts do not conform to older standards about font height. For example, 12 point Courier does not necessarily print at 6 lines per inch. You can use the "WINPRINT-GET-PAGE-LAYOUT" operation to determine the number of lines that fit on a page for a given font. Sometimes, however, you need to be able to set the line height explicitly.
This operation allows you to do that. It sets the number of lines that should be printed on a page. The runtime uses this number to adjust the height of the printed font. Note that the font is not scaled--it is simply printed in the specified vertical space.
When using this option, set the number of lines desired in WPRTDATA-LINES-PER-PAGE (also defined in "winprint.def"). Then pass WINPRINT-DATA to the routine. For example:
* Set 60 lines per page
MOVE 60 TO WPRTDATA-LINES-PER-PAGE
CALL "WIN$PRINTER"
USING WINPRINT-SET-LINES-PER-PAGE,
WINPRINT-DATA
You can set the lines per page with the spooler open or closed. If you set it when it is open, then the new font height takes effect the next time the page position is advanced. In either case, the lines per page is reset to the default value the next time the spooler is closed. You can explicitly reset to the default font height by setting WPRTDATA-LINES-PER-PAGE to zero.
WINPRINT-SET-MARGINS This operation allows you to set the margins on a report. Combine this with the ability to set the exact height of a line (see WINPRINT-SET-LINES-PER-PAGE), and you can reliably print on pre-printed forms with many different devices. WINPRINT-SET-MARGINS sets the margins for the next report if the printer is not open, or for the current report if the printer is open. If the printer is open and the current page is blank, the margin change occurs for the current page. Otherwise, the margin change occurs on the next page. Note that most printers have minimum margins that cannot physically be printed in, regardless of the setting of the logical margins.
A group item in WINPRINT-DATA describes the necessary fields. It looks like this:
03 WPRTDATA-MARGINS REDEFINES
WPRTDATA-SET-STD-FONT.
05 WPRTDATA-TOP-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-BOTTOM-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-LEFT-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-RIGHT-MARGIN PIC 9(7)V99 COMP-5.
05 WPRTDATA-MARGIN-UNITS UNSIGNED-SHORT.
This group item should be INITIALIZEd before it is used. It is defined in "winprint.def".
The four margin fields should be set to the values you want to use. For example, to set half-inch top and bottom margins you would move .5 to WPRTDATA-TOP-MARGIN and WPRTDATA-BOTTOM-MARGIN. You can set a margin to zero to use the printer's default margins.
The MARGIN-UNITS field must be set to a level 78 that describes the measurement units. The choices are:
WPRTMARGIN-DEFAULT-MARGINS -- Use printer default margins (this is the default).
WPRTMARGIN-PIXELS -- Margins expressed in printer-dependent units. Laser printers, for example, use either 300 or 600 units per inch.
WPRTMARGIN-CELLS -- Margins expressed as a number of rows or columns based on the currently selected font.
WPRTMARGIN-INCHES -- Margins expressed in inches.
WPRTMARGIN-CENTIMETERS -- Margins expressed in centimeters.
To use the margin-setting feature to simplify printing on pre-printed forms, we suggest this sequence:
1. Establish which printer you want to use.
2. Select the font.
3. Set the margins.
4. Set the line height.
It is important to note that step (3) should precede step (4) because the line height depends on the top and bottom margins that you have set. For an 11" form, a typical scenario might be:
Font: Courier New, 12 point
Margins: .5" top and bottom
Lines per page: 60
This would result in 6 lines per inch with 3 blank lines at the top and bottom of each page. The code to set the margins for this case would be:
INITIALIZE WPRTDATA-MARGINS MOVE .5 TO WPRTDATA-TOP-MARGIN, WPRTDATA-BOTTOM-MARGIN MOVE WPRTMARGIN-INCHES TO WPRTDATA-MARGIN-UNITS CALL "WIN$PRINTER" USING WINPRINT-SET-MARGINS, WINPRINT-DATA
WINPRINT-SET-STD-FONT --Allows you to select one of a number of predefined fonts to use for the report. You must make this selection prior to opening the print file. The selection is used until explicitly changed or the runtime exits. You specify which font to use by moving one of the following level 78 values to WPRTDATA-STD-FONT before calling WIN$PRINTER:
WPRTFONT-DEFAULT --Requests the printer's default font. This is the initial setting.
WPRTFONT-COURIER-12 --Requests a 12-point TrueType Courier font.
WPRTFONT-COURIER-12-COMP --Requests a 12-point TrueType Courier font and rescales it so that at least 132 columns of print will fit on a page. This is similar to the compressed print mode supported by many printers.
WPRTFONT-COURIER-10 --Requests a 10-point TrueType Courier font.
WPRTFONT-COURIER-10-COMP --Requests a 10-point TrueType Courier font and rescales it so that at least 132 columns of print will fit on a page.
When you are using either of the compressed print modes, the rescaling of the font occurs when the print file is opened. This ensures that the font is scaled correctly for the current page size and orientation. The rescaling operation normally results in skinny characters, but can actually result in stretched characters if more than 132 characters would naturally fit on a page. The runtime asks the Windows TrueType font engine to scale the font to fit exactly 132 characters on a line even if more would normally fit.
You should be aware that the TrueType font engine does not always produce exact results, particularly when rescaling a font. You may end up with a font that fits more than 132 columns on a page. You may also end up with a font that is a slightly different height when compressed than when not. You can also end up with a font that is only vaguely related to the requested one if, for example, the user has removed the TrueType fonts or if the print driver cannot handle TrueType fonts. These effects are due to the internal workings of the TrueType font engine and the way that Windows handles fonts in general. Under Windows, an application cannot select a particular font. Instead, it describes the font's characteristics and Windows selects the closest matching font using a weighted-penalty system for deciding which font is the closest match. Sometimes, no font matches exactly, so Windows substitutes the font that has the closest match.
WINPRINT-SELECTION op-codes
The following operation codes use the data item WINPRINT-SELECTION.
WINPRINT-GET-CURRENT-INFO --This operation returns information about the currently selected printer. A printer is considered selected if it has performed a print using the "-P SPOOLER" or if WIN$PRINTER has executed using any of the WINPRINT-DATA op-codes. If no printer is selected, this operation will return information about the Windows default printer.
WINPRINT-GET-NO-PRINTERS --This operation retrieves the number of printers installed on a system. If this is executed in a Windows NT environment, remote printers with drivers stored on network servers will also be included. The number returned will be stored in WINPRINT-NO-OF-PRINTERS. This op-code does not alter any of the current printer settings. It is recommended, but not required, that this op-code be executed before the WINPRINT-GET-PRINTER-INFO op-code.
WINPRINT-GET-PRINTER-INFO --This operation retrieves information about a particular printer. It does not alter any of the current printer settings. Device names up to 80 characters in length will be stored. If a name is wider than 80 characters, it will be truncated from the rightmost position. These names may contain embedded spaces. The following information will be returned:
WINPRINT-NAME --Holds the name of the selected printer as given in the Printers folder under Settings.
WINPRINT-PORT --Holds the name of the selected port as given in the properties of the printer.
WINPRINT-DRIVER --Holds the name of the assigned driver as seen in the properties of the printer. Note that for remote printers, this name will almost always be given as "winspool."
WINPRINT-DRV-VERSION --Holds the version number of the driver for the requested printer.
WINPRINT-NO-OF-PRINTERS --Holds the number of the current printer. Remember, this number is based on the order of printers in the computer's internal printer list, and may change from time to time. It is not recommended to identify a printer by number.
WINPRINT-IS-DEFAULT --Holds the value of 1 if the printer is the Windows default printer, otherwise it is set to 0.
WINPRINT-COPIES --Holds the maximum number of copies the printer is able to provide. The most common value is 99. If a printer is not copy capable, it will have the value of 1.
WINPRINT-CURR-COPIES --Returns the current number of copies the driver is set to print. Note that some printers return a value of 1, indicating that the original is copy number 1. Other printers appear to return a value of 0, indicating an original plus 0 copies. You can change this value to the number of copies you wish to print.
WINPRINT-ORIENTATION --Holds a value indicating the orientation ability of the printer. If portrait and landscape modes are supported, this value is set to 1. If only portrait mode is supported, it is set to 0.
WINPRINT-CURR-ORIENTATION --Returns the current orientation set in the driver, if portrait mode is active, the value is set to 1. If landscape mode is active, the value is set to 2. A value of 0 uses the printer's default setting. You can change this value to set the orientatio you prefer.
Calling the op-code WINPRINT-GET-NO-PRINTERS before calling WINPRINT-GET-PRINTER-INFO is recommended. However, it is not necessary to perform WINPRINT-GET-NO-PRINTERS each time you run WINPRINT-GET-PRINTER-INFO. You can perform the operation once and store the data until it is needed.
Note: If you wish to retrieve information about all the printers on the system, start with a value of "1" in WINPRINT-NO-OF-PRINTERS in the WINPRINT-SELECTION record. Increment this value by one for each new execution until a negative value or a number greater than WINPRINT-GET-PRINTER-INFO is returned.
WINPRINT-SET-PRINTER --This operation allows you to select a specific printer and set properties. WINPRINT-NAME must hold the name of the printer as received by WINPRINT-GET-PRINTER-INFO. If WINPRINT-COPIES is set to a positive value greater than one, you may use WINPRINT-CURR-COPIES to set the number of copies to print. If WINPRINT-CURR-COPIES is set to zero, the printer driver default is used. If WINPRINT-ORIENTATION is set to a positive value, then WINPRINT-CURR-ORIENTATION may be set to any of the following values:
WPRTSEL-ORIENT-DEFAULT -- for printer default.
WPRTSEL-ORIENT-PORTRAIT - for portrait orientation.
WPRTSEL-ORIENT-LANDSCAPE -- for landscape orientation.
WINPRINT-QUALITY may be used to select varying grades of print quality. One may use the predefined constants for this purpose:
WPRTSEL-QUALITY-DEFAULT -- for printer default.
WPRTSEL-QUALITY-HIGH - for high quality.
WPRTSEL-QUALITY-MEDIUM -- for medium quality.
WPRTSEL-QUALITY-LOW -- for low quality.
WPRTSEL-QUALITY-DRAFT -- for draft quality.
Note that this is an issue only for dot-matrix-type printers. Most inkjet and laser printers do not support this method of determining different levels of print quality.
USER-DATA op-codes
The following operation codes use data items defined by the user in Working-Storage.
WINPRINT-GET-SETTINGS --This operation returns the spooler's current configuration in the specified buffer. This buffer should be the second argument to WIN$PRINTER. The spooler's configuration includes information about the destination device, its paper size, and page orientation. It does not include information about the current font selection. The information stored in the buffer is binary data that corresponds to some internal structures used by Windows. This information should be left unchanged. The return value is the number of bytes used in the buffer to hold the settings. Note that the number of bytes needed to hold the configuration can change when new settings are selected by the user, often by several hundred bytes. You should allow for a wide range of configuration sizes. Experiments suggest that 1000 bytes is adequate to hold typical configurations, but there is no guaranteed upper bound.
WINPRINT-SET-SETTINGS --This operation sets the spooler's configuration to match information stored in the specified buffer. This buffer must contain the same data returned by an earlier call using the WINPRINT-GET-SETTINGS operation. Passing other data is an error that can cause a variety of problems, including strange printing or a General Protection Fault in Windows.
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 one of the WINPRINT-DATA data items.
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.
WRTERR-DEVICE-INCAPABLE --This code is returned when you try to print a bitmap and the printer you are using cannot print bitmaps.
WRTERR-ENUM-FAIL --This code is returned when WINPRINT-NO-OF-PRINTERS 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-OPEN --This code indicates that the program tried to change the spooler's configuration while a spooled print file was open.
WPRTERR-SPOOLER-CLOSED --This code is returned when you attempt to print a bitmap on a closed print file.
WPRTERR-UNSUPPORTED --This code is returned whenever WIN$PRINTER is called on a machine that is not a Windows machine.
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-BAD-DRIVER --This code is returned if WIN$PRINTER targets a printer driver that has been determined by Microsoft to be bad. This error should only occur if the printer in question has a 16-bit Windows printer driver.