PrtScrn

(Engine-Level Function)

Description:	Prints the image in a window on the default Windows™ printer and returns an error code.
Returns:	Numeric
Usage:	Script Only.
Function Groups:	Printer
Related to:	Print \| PrintLine \| Redirect
Format:	PrtScrn([Window, PaletteChanges, PrinterSpec])
Parameters:

Window

An optional object value of a module instance that specifies the window to print. If it is not specified, it defaults to Self which will print the window from which the PrtScrn function is executed.

PaletteChanges

An optional two-dimensional array of RGB values. Each RGB value overrides the default printed color for the palette index, which is the same as the first array subscript.
The first array subscript may have any size (e.g. [0..255] for the whole palette, or [123..125] for just palette indices 123 to 125). (Please see the example in the "Example" section.)
The second array subscript should be sized [0..2] and holds the red, green, and blue components of the color respectively. Each color value must be a real number between zero and one. "0" represents a total absence of that color, while "1" represents the full intensity of the color.

Colors that are in other indexed positions of the palette, but which have the same RGB value as the indexed color to be changed, will usually also change. The danger is that the process of mapping colors from VTS’s palette to that of the printer may cause results to differ from those expected. If using the PaletteChanges parameter, you are advised to test this function to determine the actual results.

PrinterSpec

An optional parameter that will accept any of the following:

Local Printer:
Port name (including virtual ports) with or without a trailing colon (e.g. DEF or DEF:. COM1 or COM1:; USB001 or USB001:; etc.)
Windows printer share (e.g. "XYZ Laser Printer")
Windows share name (if the printer is shared) (e.g. "XYZLaser")
Local or Remote Printer:
UNC share name (which includes the host and share name (e.g. "\\localhost\XYlaser" or "\\lab1\NetPrinter")

A note to OEM programmers:

When the VTScada Display Manager or Trend Manager performs a screen print, printer palette color substitution is performed by calling module "GetPrinterPalette". This module is searched for in Code. The VTS layer does not provide this module. The default printing palette is the display palette. If you wish to provide a separate palette, provide a GetPrinterPalette module. This should be a subroutine module that returns an array of palette color substitution values in the same format required by the PrtScrn statement's PaletteChanges parameter.

Comments:

The return value for this function is as follows

Return Value	Description
0	Success
1	Printing
2	Failure

When printing using this function, make sure that the print job is spooled to the Windows™ Print Manager, otherwise execution of the application will be suspended for the duration of the print job.

Care should be taken to ensure that the graphics in the window you are printing do not change while printer output is being generated. If the graphics do change, the printer output is unpredictable.

In VTS 7.0 and later, all print functions are now compatible with the values returned in either of the first two parameters of the new PrintDialogBox function.

Within an Anywhere Client session, this function does nothing.

Example:

If MatchKeys(2, "p") && ! wait;
[
  wait = PrtScrn();
]

This will cause the window containing the PrtScrn statement to be printed out when the "P" key is pressed so long as another print job is not already printing or has failed.

Another example might be:

 PalValues = New(256, 3); { Sized enough for entire palette }
 PalValues[0][0] = 1;  { Red - Full intensity }
 PalValues[0][1] = 1;  { Green - Full intensity }
 PalValues[0][2] = 1;  { Blue - Full intensity }
 .
 .
 .
 PrtScrn(Self(), PalValues);

This will set the color for palette index 0 (default black) to be white.