setPrinter

setPrinter(name: String io): Integer updating;

The setPrinter method of the Printer class enables you to programmatically set the output printer, by specifying a valid printer in the name parameter.

To reset the printer back to the default printer of the user, pass an empty string in the name parameter, and the method updates the string with the name of the default printer. The current printer must be closed for this to be valid; that is, you cannot pass a null value when the printer is active.

The printer cannot be altered after printing has begun. The return values, represented by global constants in the Printer category, are listed in the following table.

Return Value	Global Constant	Description
0	Print_Successful	The print to the specified printer was successful.
15013	Print_Currently_Open	The specified printer is currently open. (The application currently has the printer open.) A resumable exception is raised and the method returns this 15013 value.
15014	Print_Failed_To_Obtain_Printer	The task failed to obtain the specified printer. (The API call to obtain the available printers has failed.)
15017	Print_Not_Available	The specified printer does not match the available printers.
15023	Print_Printer_Ignored	You attempted to change the printer in use after printing has begun, before any printing has occurred (the printer must be closed before commencing new output on a different printer).
15032	Print_DocumentType_Invalid	You changed printer.documentType to Print_Custom_Paper instead of calling the printer.setCustomPaperSize method.

The default printer is re-evaluated every time a new print task is initiated and JADE logic has not specifically set the printer name required. If logic sets a specific printer name (even if is the default printer), that printer continues to be used, regardless of any change to the default printer.

In JADE thin client mode, this method sets the local (presentation client) printer to the specified printer.

An exception is raised if this method is invoked from any of the following.

• A serverExecution method.

• A server application running under the jadrap.exe JADE Remote Access Program (because printing requires the jade.exe program).

The following examples show the use of the setPrinter method.

comboBox_click(combobox: ComboBox input) updating;
vars
    printer : String;
    result  : Integer;
begin
    // Uses the setPrinter method to set the printer when the user
    // selects one from the combo box.
    printer := comboBox.listObject.String;
    result  := app.printer.setPrinter(printer);
    if result = Print_Not_Available or result = Print_Currently_Open then
        app.msgBox('Printer is not available', 'Error',
                   MsgBox_Exclamation_Mark_Icon);
        return;
    endif;
end;

buttonUnload_click(btn: Button input) updating;
vars
    default : String;
begin
    default := "";
    app.printer.setPrinter(default);
    self.unloadForm;  // Unloads the form and resets to the default printer
end;