GUI ScreenIO for
Windows|
GUI ScreenIO for
Windows |
This API sends a text file to the printer. It does not handle formatting or printer setup. Its purpose is to do a basic file print to a windows printer for files generated out of COBOL Programs. Your program must format the print suitably for the printer you intend to use.
Often, COBOL systems generate report files that are printed directly to the printer, or to disk, and that disk file can then be sent to the printer. Sometimes our CopyFile is all that is needed to get disk files to the printer, but in other instances it is more desirable to hand the print file to the windows spooling system. This is especially true where the print queue is on another machine, or your application is running on our Client Server layer, and print files are generated at the Server, but the output is desired on a printer attached to the client.
Your program calls this API with the name of a file, and (optionally) the name of a printer. The API will send that file to the printer. This API does not allow your program to print directly to the printer, you must first print to a file and then send that file to print. (This method is often faster anyway.) See our low-level print APIs for direct printing to a printer.
If you do not know or do not supply the name of the printer, you can simply give the API the handle to the current panel. (Each panel has a field named panel-HWND in its Panel-1 area.) The API will then ask the user which printer it should send the report to using the Windows Standard Printer Dialog box.
In Client/Server environments this API normally runs on the Client side, but it can be forced to run on the Server side if you wish to print on printers connected to (or known to) the server.
Regardless of where the API runs, you can tell the API that the Source File is located on the Client, or the Server.
What does that all mean? Check the table:
| API Runs: | Source at Client | Source at Server |
|---|---|---|
| On Client | API prints a file from the client's disk to the client's local printer | API automatically transfers the file from the server to a temporary file on the client, and then prints the file on the client's local printer. |
| On Server | API transfers the file from the Client to a temporary file on the server, then prints this file on to the server's local printer. | API prints a file on the server to the server's local printer. |
In the above table, A printer that is said to be Local to the client or the server is one that can be seen in the network neighborhood from that machine. It might actually be attached to a different machine in the same workgroup.
You can only print to printers local to the machine WHERE THE API RUNS.
There is a special Demonstration Program for Client/Server users to demonstrate each of the 4 combinations in the above table: PHAY.Zip
To print to a printer connected to, or visible from the server:
|
SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE |
When you force the API to run on the server you MUST supply a printer name. You can not feed it a hwnd and have the API ask the user which printer to print on when forcing the API to run on the Server side. The user is not located at the server and can not choose a printer there. You can use our GETPrinters API to provide the client with a list of printers on the server if needed.
Naturally, when not running under client server, all sources and destinations are local to the current machine, with no programming changes required.
Files available to copy to your system:
COPY WIN32API.
COPY PRNFILE.
COPY GSPRTDEF.
*
* : Typical call
* : (Using printer name derived from
* : PRINTDLG api.
MOVE PRTDLG-PRINTER-NAME TO PRTFILE-PRINTER-NAME
*
MOVE "C:\MY-REPORT.TXT" TO PRTFILE-FILE-NAME
SET PRTFILE-DATA-RAW TO TRUE
MOVE "System Output Report" TO PRTFILE-DOCUMENT-NAME
MOVE LOW-VALUES TO PRTFILE-PREPEND-BUFFER
PRTFILE-POSTPEND-BUFFER
STRING MY-PRINTER-SETUP-DATA DELIMITED LOW-VALUES INTO
PRTFILE-PREPEND-BUFFER
MOVE "System Status Report" TO PRTFILE-DOCUMENT-NAME
SET FUNC-PRINTFILE TO TRUE
CALL 'GSWINAPI' USING WIN32API-PARMS
PRTFILE-PARMS
GS-DEVMODE-DATA
WIN32API-C
WIN32API-D
WIN32API-E
WIN32API-F.
*
* IF WIN32API-FAILED
* do print-not-possible-or-canceled
* ELSE
* continue printing report
|
See the copybook for the fields documented below.
This field is name of the printer to which you want to send the print. If left blank or low values, AND you supply a panel-HWND (see next) the API will launch the standard Windows Printer Selection Dialog box so the user can choose the printer. This name will be returned to you in this field after the user makes a selection.
If you want the user to have the choice of which printer to use, you may enter the panel-HWND from the current panel in this field and leave the printer name field blank. The PrintFile API will prompt for the printer name with the Windows Printer Dialog box. You can not do this if you are forcing the API to run on the server. Reason: no one can be guaranteed to be at the server to make this choice.
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.
This is the complete file specification of the source file. Drive letter, directory, file and extension. \\machine\name\directory\file.ext is also allowed.
This specifies whether the above source file is on the client or the server. The default is on the server, as output files from your COBOL program are expected to be written to disk on the server. If the 88 named PRTFILE-SOURCE-ON-SERVER is set TRUE, the file will be transferred to the Client automatically, and then printed.
If this file has already exists on the Client, you may tell the API this by setting PRTFILE-SOURCE-ON-CLIENT to TRUE.
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 is a 300 byte buffer in which you can load printer initialization strings (aka Escape Sequences ) to place the printer in the mode you want for your report. This requires some knowledge of the printer type, and this data is best stored in a user configurable file as printers change over time.
If this data is other than low-values, it will be sent to the printer prior to the start of the print job.
This buffer of 100 characters will be sent to the printer after each job if it contains other than low-values. Its purpose is to reset the printer to some common state. Sometimes, setting a printer reset code too soon after job transmission can wipe out your print job.
This switch, with Yes/No 88 values, tells the API if it should paginate the print job or send it as one big page. Embedded page ejects generated by your program will, of course, be honored by the printer hardware in any case.
This switch causes the API to scan your print job for page ejects, and tell windows just after each eject, to start a new "logical page". This allows windows to start printing as soon as the first page has arrived, rather than waiting until the entire job is spooled before it starts printing.
If you send a big report, this can make printing faster. On small reports or single page documents it won't do anything for you.
Some reports do not contain final page ejects, which can leave the final page hanging half in and half out of the printer, or cause it to be retained by some laser printers until the another print job ejects it. You can set this field (via the 88 names supplied) to Force an Eject, or Check for an Eject in the last 5 bytes (and insert one if none is found), or to do nothing.
This area is used to report printer setup information. Usually retrieved from the PringDlg api, Defined Here.
NOTE: While required by the this PRINTFILE API, this area is simply used to show your program how the printer is setup. Changes to the DEVMODE-DATA done by your program will not be honored by Window for the Print File function call when PRTFILE-DATA-TYPE is set to RAW.
This is a Windows limitation. Therefore, if you need to impose a special font, or landscape mode, you will need to either allow users to make that choice when selecting their printer (see PRINGDLG API), or string the appropriate escape sequences into prtfile-prepend-buffer (above).
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-2019 Norcom, all rights reserved |