GUI ScreenIO for Windows

 ScreenIO.com


Printer APIs - Low Level

These are a set of 7 Printer APIs that can be used for sending print to windows printers.

These APIs are sometimes provided by Compiler manufacturers, and sometimes not.  Even when they are provided, the versions from other sources are not capable of being run in a Client/Server environment as our version is.  If you ever intend (or even think you might) run in a client server environment we recommend you not use similar APIs supplied by your compiler manufacturer or third parties.

There are 7 APIs in this set, and they are all documented here because they are all used together, usually in a sequence. They all use the same copybook.  

Why Use These?

The purpose of this set of APIs is to send print to a windows printer via the windows spool system.  However, these APIs do not format your print, and they know nothing about the capabilities of your printer.  

These are still useful in many instances to send raw print files directly to printers of known capabilities, or where the printers default settings are going to be used, or where you are formatting the print via your program by sending or embedding "escape sequences" directly in the print stream.  

Often, COBOL report files can be printed to disk, and that disk file can then be sent through these APIs to "spool" it to the printer, or you can print directly to the printer with these APIs without the intermediate disk file.  These APIs are very fast, if not somewhat primitive.

How they work - Basics

The 7 APIs are typically used together in sequence.  They are listed here in the normal order.  The APIs are:

You use these in order, repeating the middle three (asterisked) as many times as necessary till your print job is finished.  (You can print more than one physical page in each WritePrinter call, but it is recommended that you do not do this.  With Client/Server, each API invocation is limited to 32k bytes, so breaking a print job up into many individual WritePrinter calls is essential.

You can do many StartDocPrinter - EndDocPrinter sets after opening the printer to print many documents sequentially. 

You can do many StartPageprinter - EndPagePrinter pairs to print many pages once you start a document.

You can do many WritePrinter calls on any given page.  In fact, you can send the entire document (in multiple WritePrinter calls) within a single set of StartPagePrinter - EndPagePrinter calls, because you can insert your own pagination (hex 0C) codes in the print.  EndPagePrinter serves mostly to allow windows to start printing the page if the user set the printer to "Start Printing Immediately" in the printer settings.

Don't get sloppy!.  Once you OpenPrinter, make sure you ClosePrinter.  Once you StartDocPrinter make sure you EndDocPrinter.

Ok, you can get a little bit careless in one instance.  If you do not supply a printer name on an OpenPrinter call but you DO supply a panel-HWND in the field provided, we will automatically pop up the Printer Dialog and fetch the printer name for you.

Client/Server issues

This API runs in Client/Server mode normally on the Client side, but they can be forced to run on the Server side if you wish to print on printers connected to the server. 

To print to a printer connected to, or visible from the server:

     SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

To do this you MUST supply a printer name.

Files

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY PRINTAPI.
     COPY GSPRTDEF.

      *     --- --- Typical calls - one of each type --- ---     
      *                                                                 
      *                                                                 
      *                         : (First fetch printer name with        
      *                         : API-PRINTDIALOG, or set               
      *                         : PRINTAPI-DIALOG-HWND to your          
      *                         : panel's Hwnd, and set printe name to  
      *                         : low-values.    

           SET PRINTAPI-OPEN-PRINTER-DEFAULTS TO TRUE    
           MOVE PRTDLG-PRINTER-NAME TO PRINTAPI-OPENPRINTER-NAME        
           SET API-OPENPRINTER TO TRUE                                  
           CALL 'GSWINAPI' USING WIN32API-PARMS                         
                                 PRINTAPI-HANDLE                        
                                 PRINTAPI-OPENPRINTER-DATA              
                                 GS-DEVMODE-DATA                             
                                 WIN32API-D                             
                                 WIN32API-E                             
                                 WIN32API-F.                            
      * 


                                                                
      *                                                                 
           MOVE 'My GUI ScreenIO Report' TO PRINTAPI-STARTDOC-NAME      
           SET  PRINTAPI-DATA-RAW  TO TRUE                              
           SET API-STARTDOCPRINTER TO TRUE                              
           CALL 'GSWINAPI' USING WIN32API-PARMS                         
                                 PRINTAPI-HANDLE                        
                                 PRINTAPI-STARTDOC-DATA                 
                                 WIN32API-C                             
                                 WIN32API-D                             
                                 WIN32API-E                             
                                 WIN32API-F.       


                     
                                                                        
      *                                                                 
           SET API-STARTPAGEPRINTER TO TRUE                             
           CALL 'GSWINAPI' USING WIN32API-PARMS                         
                                 PRINTAPI-HANDLE                        
                                 WIN32API-B                             
                                 WIN32API-C                             
                                 WIN32API-D                             
                                 WIN32API-E                             
                                 WIN32API-F. 


                           
      *                                                                 
      *                                                                 
           MOVE LENGTH OF MY-DATA-BUFFER TO PRINTAPI-WRITEPRINTER-SIZE  
           MOVE ZERO TO PRINTAPI-WRITEPRINTER-WRITTEN                   
           SET API-WRITEPRINTER TO  TRUE                                
           CALL 'GSWINAPI' USING WIN32API-PARMS                         
                                 PRINTAPI-HANDLE                        
                                 PRINTAPI-WRITEPRINTER-DATA             
      *                         : Warning: for Client/Server deployments
      *                         : keep your buffer less than 32k        
                                 MY-DATA-BUFFER                         
                                 WIN32API-D                             
                                 WIN32API-E                             
                                 WIN32API-F.    


                        
      *                                                                 
      *                                                                 
           SET API-ENDPAGEPRINTER TO TRUE                               
           CALL 'GSWINAPI' USING WIN32API-PARMS                         
                                 PRINTAPI-HANDLE                        
                                 WIN32API-B                             
                                 WIN32API-C                             
                                 WIN32API-D                             
                                 WIN32API-E                             
                                 WIN32API-F.                            
      *                                                                 
      *                   (repeat above three calls as necessary)     


  
      *                                                                 
                                                                        
           SET API-ENDDOCPRINTER TO TRUE                                
           CALL 'GSWINAPI' USING WIN32API-PARMS                         
                                 PRINTAPI-HANDLE                        
                                 WIN32API-B                             
                                 WIN32API-C                             
                                 WIN32API-D                             
                                 WIN32API-E                             
                                 WIN32API-F.          


                  
      *                                                                 
      *                                                                 
            SET API-CLOSEPRINTER TO TRUE                                 
            CALL 'GSWINAPI' USING WIN32API-PARMS                         
                                 PRINTAPI-HANDLE                        
                                 WIN32API-B                             
                                 WIN32API-C                             
                                 WIN32API-D                             
                                 WIN32API-E                             
                                 WIN32API-F.            


                
                                                                        
      *                                                                 
      *        After each call, you may want to check status....        
      *                                                                 
      *    IF WIN32API-FAILED                                           
      *      do print-not-possible-or-canceled                          
      *    ELSE                                                         
      *      continue printing report                                   
      *                                                                 

Parameters specific to this function (In printapi.cob)

See the copybook for the fields documented below.  Note that the number of arguments for each API varies as shown in the examples above.  This example also appears in the copybook so that you can cut and paste.

PRINTAPI-HANDLE - Used for ALL of these APIs

This field is OUTPUT from an OpenPrinter call, and Input to each subsequent call. After you ClosePrinter, it is no longer valid.  

PRINTAPI-OPENPRINTER-DATA  - Used only for OpenPrinter

There are two fields in this area, at least one of them must be filled in, the other can remain low-values.

PRINTAPI-OPENPRINTER-NAME This is the windows name for this printer, as provided by our PringDlg API, or our GETPrinters API.  This is also the name that appears in the Printers Control panel applet.

PRINTAPI-DIALOG-HWND This is the panel-HWND (it appears in each panel copybook) and it indicates the owner of the Print Dialog box.  If you do now know the name of the printer, simply fill this in with the Hwnd of the most recently displayed panel, and the OpenPrinter API will invoke the PrintDlg API to collect the printer name, and pass it back to you so that subsequent prints from this same program will go the same printer without the user having to answer the Print Dialog again.  This will be Ignored in a Client Server environment if you SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE.  If intending to print at the server, you must provide a printer name.

Hint:  Users get tired of responding to the Printer Dialog each time you print from an application.  It might make more sense to have a setup panel where they select the printer once for each different type of output, and have you save it in an INI file with our WritePrivateProfile API (which is also Clien/Server aware), or our FUNC-EX-REGISTRY-PUT (also client/server aware).

 (See also GS-DEVMODE-DATA, below, for the OpenPrinter call)

PRINTAPI-STARTDOC-DATA  - Used Only for StartDocPrinter

This area contains two fields which describe your print document.

PRINTAPI-STARTDOC-NAME This is the name of the document.  It appears in the print queue display in windows Printers control panel applet.  If you fail to set it, the API will substitute a default description.

PRINTAPI-STARTDOC-DATA-TYPE This sets the type of data you will be sending.  We recommend you use the 88s provided to set it to RAW unless you have advanced formatting software installed.

PRINTAPI-WRITEPRINTER-DATA -  Used only for WritePrinter

This area consists of two fields.  

PRINTAPI-WRITEPRINTER-SIZE This is the size of the data that you will be sending to print in this single print call.  It is not the size of the buffer, but rather the size of the data in the buffer.  If you have a 20k buffer with only 500 bytes filled, do not set this field to 20000 bytes or you will print 20000 bytes of spaces.

NOTE: This must be less than 32k for Client Server Applications.  This is not a significant limitation because you can do Multiple WritePrinter calls for a single page.

PRINTAPI-WRITEPRINTER-WRITTEN This is returned from the WritePrinter call to indicate how many bytes were printed.  It usually matches how many bytes were sent, unless something goes wrong.  

GS-DEVMODE-DATA - Used only for OpenPrinter

This data element is used only used for OpenPrinter, and its purpose is to provide defaults and printer setup information to the print subsystem.

This data element is in a separate copybook (GSPRTDEF.cob) because it is used for several of the print APIs, and it is desirable (even necessary) to retain the date retrieved into this copybook using the PringDlg API, and pass it to the OpenPrinter api.  If you do not pass a printer name to the OpenPrinter api, it will automatically show the PrintDlg and gather this information for you from the system defaults for this printer. 

The content of the GSPRTDEF.COB copybook are documented on THIS page.

MY-DATA-AREA  - Used only for WritePrinter

This area does not appear in the copybook.  You pass in any data area in your program for this.  The content of this memory is passed intact to the print spooler.

As mentioned above, do not exceed 32k in a single WritePrinter call. (Microsoft makes no such restriction, and you can send truly huge chunks of data if you can be certain you will never run in a our Client/Server environment.  But if you are hugely successful and open a branch office across town, and suddenly decide to run Client/Server, you will regret using large buffers.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.

 


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom