XPRINT ATTACH statement

Purpose

Connect a host-based (GDI) printer for use with XPRINT code.

Syntax

XPRINT ATTACH {DEFAULT | PrinterName$} [,JobName$]

XPRINT ATTACH CHOOSE [USING Flags&] [,JobName$]

Remarks

XPRINT ATTACH connects to a host-based (Windows-only or GDI-based) printer for use with subsequent XPRINT operations. Host-based printing is device-independent and performed through the Windows printing system and printer driver. Device independence can be achieved because the printer driver handles the task of converting text into the manufacturers proprietary binary format used by the printer.

To send device-dependent print data (such as plain text) to a line printer device, use the LPRINT ATTACH statement instead.

XPRINT ATTACH allows you to change the printer device used by XPRINT operation. When executed, the current connection (if any) is closed and the new connection is established.

DEFAULT

If DEFAULT is specified, the default printer (as set in the Printers applet in Control Panel) is used. For example:

XPRINT ATTACH DEFAULT

CHOOSE

If CHOOSE is specified, the Choose Printer common dialog is opened, allowing the user to select from the list of installed printers. For example:

XPRINT ATTACH CHOOSE

With CHOOSE, you may elect to include an optional numeric expression called Flags&. This value consists of one or more of the following equates to control the execution of the Printer Dialog:

%PD_ALLPAGES	"All Pages" button is the default.
%PD_SELECTION	"Selection" button is the default.
%PD_PAGENUMS	"Numbered Pages" button is the default. (Only one of the above is allowed)
%PD_NOSELECTION	Disables the "Selection" button.
%PD_NOPAGENUMS	Disables the "Numbered Pages" button.
%PD_COLLATE	"Collate" option is checked.
%PD_PRINTTOFILE	"Print To File" option is checked.
%PD_DISABLEPRINTTOFILE	Disables the "Print To File" option.
%PD_HIDEPRINTTOFILE	Hides the "Print To File" option.

PrinterName$

The name of the printer to attach (as shown in the Printers applet in Control Panel, or returned by the PRINTER$ function). printername$ must be a valid device name and cannot exceed 259 characters in length. For example:

XPRINT ATTACH "HP LaserJet 5MP"

JobName$

The name of the print job. This will be shown in the print spooler. If you do not supply a name, "Printjob" is used by default.

If XPRINT ATTACH is not successful, XPRINT$ returns an empty string. Error 68 ("device unavailable") is generated if an invalid printer was specified. No error is generated if the user cancels the Choose Printer dialog (with XPRINT ATTACH CHOOSE). Therefore, for host-based printing, applications should always use XPRINT ATTACH to explicitly select the intended host-based printer, then test for a successful selection with the XPRINT$ and ERR functions to ensure the host-based printer selection was successful.

Unlike direct printing (LPRINT ATTACH), host-based printing is handled by a printer driver and the operating system's spooler subsystem. Therefore, spooler settings such as "work offline" in the Printer Properties dialog will not impede the creation of a spooled print job. Once all the data has been sent to the printer, detach the printer so other applications can use it., with the XPRINT CLOSE statement.

Host-based printers use proprietary control protocols, unlike line printers, so it is usually not possible to send them printer-dependent control codes. To attach a line printer, use LPRINT ATTACH instead of XPRINT ATTACH.

Note: You can enumerate the available printers with the PRINTERCOUNT and PRINTER$ functions.