OUTPUT TO statement

Specifies the new output destination for a stream.

Syntax

OUTPUT [ STREAM stream | STREAM-HANDLE handle ] TO
  {     PRINTER [ printer-name ]
     |  opsys-file
     |  opsys-device
     |  TERMINAL
     |  VALUE ( expression )
     |  "CLIPBOARD"
  } 
  [ LOB-DIR { constant | VALUE ( expression ) } ] 
  [ NUM-COPIES { constant | VALUE ( expression ) } ]
  [ COLLATE ]
  [ LANDSCAPE | PORTRAIT ]
  [ APPEND ]
  [ BINARY ]
  [ ECHO | NO-ECHO ]
  [ KEEP-MESSAGES ]
  [ NO-MAP | MAP protermcap-entry ]
  [ PAGED ]
  [ PAGE-SIZE { constant | VALUE ( expression ) } ]
  [ UNBUFFERED ]
  [     NO-CONVERT
     |  { CONVERT
            [ TARGET target-codepage ]
            [ SOURCE source-codepage ]
         }
  ]
STREAM stream
Specifies the name of a stream. If you do not name a stream, the AVM uses the unnamed stream. See the DEFINE STREAM statement reference entry and the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces for more information on streams.
STREAM-HANDLE handle
Specifies the handle to a stream. If handle it is not a valid handle to a stream, the AVM generates a run-time error. Note that stream handles are not valid for the unnamed streams. See the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces for more information on streams and stream handles.
PRINTER [ printer-name ]
By default, this option sends output to the printer defined in the default print context. Specify a printer name to send output to a specific printer. Specifying a printer name overrides, but does not change, the printer defined in the default print context.

When you use this option, it implies that the device you are sending output to is paged, unless you also specify PAGE-SIZE 0.

In Windows, you must specify network printers in Universal Naming Convention format. For example:

\\fs_dev\hplas4

On UNIX, the printer spooling facilities (lp or lpr) are used automatically.

opsys-file
The absolute or relative pathname of a file to which you want to direct output. If you specify a relative pathname, the AVM locates the pathname relative to the current working directory. The pathname can contain up to 255 characters. If a file with the specified pathname already exists, the AVM overwrites it. The pathname can contain Unicode characters. See OpenEdge Development: Internationalizing Applications for more information about Unicode.
opsys-device
Represents the name of an operating system device.
TERMINAL
Indicates that you want to direct output to the terminal. The terminal is the default output destination.
VALUE ( expression )
Represents an expression whose value is the destination to which you want to send data. The value can contain Unicode characters.
"CLIPBOARD"(graphical interfaces only)
Specifies the system clipboard as the output destination. The quotes are required.
LOB-DIR { constant | VALUE ( expression ) }
Specifies the directory in which you want the EXPORT statement to write large object data files (such as BLOB and CLOB data files). The constant and expression arguments are character expressions that evaluate to an absolute pathname or a relative pathname (relative to the directory specified in opsys-file).

If the specified character expression evaluates to either the Unknown value (?) or a directory that does not exist, or you do not have permission to write to the specified directory, the AVM raises the ERROR condition.

The LOB-DIR option is valid only when you specify an operating system file as the output destination.

NUM-COPIES { constant | VALUE ( expression ) }
Specifies the number of copies to print. The constant or expression parameters must evaluate to a positive integer. This option is supported in Windows only, and only with printer drivers that support multi-copy printing. Specifying the number of copies to print overrides, but does not change, the number of copies defined in the default print context.

The following statement prints three copies of each output page on the selected printer:

OUTPUT TO PRINTER NUM-COPIES 3.
COLLATE
Specifies whether multiple copies of output pages print in collated order. This option is supported in Windows only, and only with printer drivers that support collation.
LANDSCAPE
Specifies a landscape page orientation. This option is supported in Windows only, and only with printer drivers that support landscape page orientation. Specifying a page orientation overrides, but does not change, the page orientation defined in the default print context.

The following statement prints three copies of each output page with a landscape orientation on the selected printer:

OUTPUT TO PRINTER LANDSCAPE NUM-COPIES 3.
PORTRAIT
Specifies a portrait page orientation. This option is supported in Windows only, and only with printer drivers that support portrait page orientation. Specifying a page orientation overrides, but does not change, the page orientation defined in the default print context.
APPEND
Appends the output to the end of a file.
BINARY
Allows output to be written directly without any conversion or interpretation.
ECHO
Sends all input data read from a file to the output destination. Data is echoed by default.
NO-ECHO
Suppresses the echoing of input data to the output destination.
KEEP-MESSAGES
Causes the following messages not to echo to the default window: ABL error and warning messages, and messages from the MESSAGE statement. If you specify KEEP-MESSAGES, these messages are sent only to the output stream you specify.

MESSAGE statements using the VIEW AS ALERT BOX option are an exception. The KEEP-MESSAGES option does not suppress the message box if there is a way available to display it.

MAP protermcap-entry | NO-MAP
The protermcap-entry value is an entry from the PROTERMCAP file. Use MAP to send output to a device that requires different character mappings than those in effect for the current output stream. Typically, protermcap-entry is a slash-separated combination of a standard device entry and one or more language-specific add-on entries (MAP laserwriter/french or MAP hp2/spanish/italian, for example). The AVM uses the PROTERMCAP entries to build a translation table for the stream. Use NO-MAP to make the AVM bypass character translation altogether. See OpenEdge Deployment: Managing ABL Applications for more information on PROTERMCAP. See OpenEdge Development: Internationalizing Applications for more information on national language support.
PAGED
Formats the output into pages. Form feeds are represented by ^L (CTRL+L). When output is PAGED, a page break occurs every 56 lines. PAGED is automatic for output to a printer.
PAGE-SIZE { constant | VALUE ( expression ) }
Specifies the number of lines per page. The expression is a constant, field name, variable name, or expression whose value is an integer. The default number of lines per page is 56. If you are using the TERMINAL option to direct output to the terminal, the default number of lines per page is the number of lines of TEXT widgets that fit in the window. If you specify a non-zero value for n, then the PAGED option is assumed. If you specify PAGE-SIZE 0, the output is not paged in character mode; in a graphical interface, the default page size is used.
UNBUFFERED
Writes one character at a time to a normally buffered data source, such as a file. Use the UNBUFFERED option only when you can intermingle your UNIX output (with the ABL UNIX statement) and your ABL output (with the OUTPUT TO statement). That is, the OUTPUT TO statement manages the buffering of output between the ABL procedure the UNIX program that it invokes, but it does not handle the buffering of output to any other programs that the ABL procedure might also invoke.
CONVERT
Allows you to modify the character conversions occurring between the external file and memory. By default, the OUTPUT TO statement converts characters from the code page specified with the Internal Code Page (-cpinternal) parameter to the code page specified with the Stream Code Page (-cpstream) parameter . If you specify SOURCE source-codepage alone, the conversion accepts source-codepage as the code page name used in memory (instead of -cpinternal). If you specify TARGET target-codepage, the conversion accepts target-codepage as the code page of the external file (instead of -cpstream). If you specify both SOURCE source-codepage and TARGET target-codepage, it converts characters from the source-codepage to target-codepage (instead of -cpinternal to -cpstream).
TARGET target-codepage
Specifies the target code page of the character conversion (replacing -cpstream). The name that you specify must be a valid code page name available in the DLC/convmap.cp file (a binary file that contains all of the tables that ABL uses for character management).
SOURCE target-codepage
Specifies the source code page of the character conversion (replacing -cpinternal). The name that you specify must be a valid code page name available in the DLC/convmap.cp file (a binary file that contains all of the tables that ABL uses for character management).
NO-CONVERT
Specifies that no character conversions occur between the external file and memory. By default, the OUTPUT statement converts characters from the -cpinternal code page to the -cpstream code page.

Examples

The r-out.p procedure sends Customer data to a file. The OUTPUT TO statement directs subsequent output to a file, so all statements that normally send output to the terminal send output to that file. After all the Customer data has been displayed to the file, the OUTPUT CLOSE statement resets the output destination to its previous state, usually the terminal. The final DISPLAY statement displays Finished on the terminal because that is the new output destination.

r-out.p

OUTPUT TO cust.dat.

FOR EACH Customer NO-LOCK:
  DISPLAY Customer.CustNum Customer.Name Customer.Address Customer.Address2
    Customer.City Customer.State Customer.Country SKIP(2)
    WITH 1 COLUMN SIDE-LABELS.
END.

OUTPUT CLOSE.
DISPLAY "Finished".

The r-termpg.p procedure sends Customer data to the terminal. The OUTPUT TO TERMINAL PAGED statement directs output to the terminal in a paged format; all statements send output to the terminal one page at a time.

r-termpg.p

DEFINE VARIABLE ix AS INTEGER NO-UNDO.

OUTPUT TO TERMINAL PAGED.

FOR EACH Customer NO-LOCK BREAK BY Customer.SalesRep:
  FIND SalesRep OF Customer NO-LOCK.
  FORM HEADER TODAY
    "Customer Listing For " TO 43
    "Page " TO 55 PAGE-NUMBER - ix  TO 58 FORMAT "99"
    (SalesRep.RepName) FORMAT "x(30)" AT 25
    WITH FRAME hdr PAGE-TOP CENTERED.
  VIEW FRAME hdr.
  DISPLAY Customer.CustNum COLUMN-LABEL "Customer!Number"
    Customer.Name LABEL "Name"
    Customer.Phone COLUMN-LABEL "Phone!Number" WITH CENTERED.
  IF LAST-OF(Customer.SalesRep) THEN DO:
    ix = PAGE-NUMBER.
    PAGE.
  END.
END. /* FOR EACH Customer */

OUTPUT CLOSE.

Notes

See also

CLIPBOARD system handle, DEFINE STREAM statement, INPUT-OUTPUT CLOSE statement, PAGE-SIZE function, SESSION system handle, Stream object handle, SYSTEM-DIALOG PRINTER-SETUP statement