|GUI ScreenIO for Windows|
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.
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.
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.
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 available to copy to your system:
--- Typical calls - one of each type --- ---
SET PRINTAPI-OPEN-PRINTER-DEFAULTS TO TRUE
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.
This field is OUTPUT from an OpenPrinter call, and Input to each subsequent call. After you ClosePrinter, it is no longer valid.
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)
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.
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.
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.
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.
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.
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,
Error code that was returned by Windows. This is not generally useful unless you have the Windows Platform SDK documentation available to you.
Plain-text error message that describes why the operation failed.
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|