XPRINT ATTACH statement

Purpose

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

Syntax

XPRINT ATTACH {CHOOSE | DEFAULT | PrinterName$} [,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

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.

See also

LPRINT ATTACH, PRINTER$, XPRINT CANCEL, XPRINT CLOSE, XPRINT$

Example

ERRCLEAR

XPRINT ATTACH "HP DeskJet 960c"

IF ERR = 0 AND LEN(XPRINT$) > 0 THEN

  XPRINT COLOR RGB(0,0,255) ' Blue

  XPRINT "This is your printer talking"

  XPRINT FORMFEED           ' Issue a formfeed

  XPRINT CLOSE              ' Deselect the printer

END IF