WIN$PRINTER Routine

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.

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, margins, and the like. Though you may print bitmaps with the WIN$PRINTER routine, you may not do so when you use "-P SPOOLER-DIRECT" (You may include bitmaps only 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 note that, 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.

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 detailed in the WIN$PRINTER op-codes section below.

RESULT

A signed numeric data item that 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, WINPRINT-COLUMN and USER-DATA, shown 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(21).
   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             SIGNED-INT.
   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.

WINPRINT-COLUMN Group item defined in "winprint.def" as follows:

01  WINPRINT-COLUMN, SYNC.
    03  WINPRINT-COL-START              PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-INDENT             PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-SEPARATION         PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-FONT               HANDLE OF FONT.
    03  WINPRINT-COL-UNITS              PIC 99 COMP-X.
    03  WINPRINT-COL-ALIGNMENT          PIC X.
    03  WINPRINT-TRANSPARENCY           PIC 99 COMP-X.
        88  WINPRINT-TRANSPARENT        VALUE 1, FALSE 0.

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 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, and WINPRINT-COLUMN included in "winprint.def" may change in future versions as capabilities are added to WIN$PRINTER. However, ACUCOBOL-GT will continue to support the formats 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.

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-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-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-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.

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:

Printer Information op-codes

WINPRINT-DATA op-codes

WINPRINT-SELECTION op-codes

WINPRINT-COLUMN op-codes

USER-DATA op-codes