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 topics on alternate I/O sources in OpenEdge 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 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 Internationalize ABL 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 or BUFFER-EXPORT( ) method 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 Manage ABL Applications for more information on PROTERMCAP. See Internationalize ABL 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

• Any ABL statement or construct with the option to output data to a stream can write to the stream specified by this statement.
• The OUTPUT TO TERMINAL statement is the default unless the procedure was called by another procedure while a different output destination was active. The output destination at the beginning of the procedure is the current output destination of the calling procedure.
• The OUTPUT TO TERMINAL PAGED statement clears the screen and displays output on scrolling pages the length of the screen. The AVM pauses before each page header. You can alter the pause using the PAUSE statement.
• ABL can display paged output to the terminal for frames that are wider than the width of the screen. The output is wrapped.
• To send output to a file correctly, you must specify the STREAM-IO option of the Frame phrase for any frame you use to write the file.
• If you send data to a file and you plan to use that data file later as input to a procedure, consider using the EXPORT statement, or the BUFFER-EXPORT() or BUFFER-EXPORT-FIELDS() methods. See the INPUT FROM statement reference entry for more information.
• If you send output to a device other than the terminal, ROW options in Frame phrases have no effect. ROW options also have no effect when you send output to a PAGED terminal. If you do not use the NO-BOX option with a Frame phrase, the AVM omits the bottom line of the box, converts the top line to blanks, and ignores the sides of the box.
• All messages, including compiler error messages and messages produced by the MESSAGE statement, are sent to the current output destination.
• If the field being output is MEMPTR, you must use the BINARY and NO-CONVERT mode of operation to prevent your data from becoming corrupted if it contains binary data.
• With the BINARY and NO-CONVERT options, you will not get a translation of new-lines to the appropriate characters for your operating system and there will be no code page conversion between -cpinternal and -cpstream.
• If the field being output is MEMPTR and your MEMPTR contains ASCII data you may want code page conversion. However, you cannot get conversion by using the CONVERT parameter on the MEMPTR. You can get code page conversion by using the MEMPTR with the GET-STRING and CODEPAGE-CONVERT functions and the PUT-STRING statement.
• On UNIX, if you want to use a print spooler with spooler options, you can use the Printer (-o) startup parameter to specify the options. See Startup Command and Parameter Reference for more information on the Printer startup parameter.
• You must use a printer control sequence to change the number of lines per page produced by your printer.
• Unless otherwise specified, the OUTPUT TO PRINTER statement uses the default print context to determine the printer name, number of copies, and page orientation for a print job. If there is no default print context, the AVM uses the printer control settings from the current environment.
• Use the SYSTEM-DIALOG PRINTER-SETUP statement to let users change the default print context through the Windows Print dialog box.
• Use the PRINTER-NAME attribute of the SESSION system handle to set the printer name in the default print context without user intervention.
• In Windows, the OUTPUT TO statement uses the PrinterFont settings in the current environment (either the Registry, or the [Startup] section of the initialization file) to define a font for a print job. The PrintFont settings are similar to the Font settings in the environment and take the following form:

  PrinterFont [ n ] = facename [ , size = screen-point-size ]

  OUTPUT TO PRINTER uses the PrinterFont setting. OUTPUT TO LPT n uses the corresponding PrinterFontn entry. The facename parameter in a PrinterFont setting represents any valid Windows font supported on your system. If you specify a font that your printer does not support, printing might take a long time and yield unexpected results. The screen-point-size setting represents the point size, in screen units, for the font. The AVM converts the point size to logical printer units.

• OUTPUT TO PRINTER in Windows performs the following processing:
  • Checks the default print context. If there is no default print context, the AVM checks the Windows printer control settings from the current environment. If no printer controls are set, the AVM displays an error message and terminates the print operation.
  • Checks the current environment (either the Registry, or the [Startup] section of the initialization file) for a PrinterFont setting. If there is a valid PrinterFont setting, the AVM uses the font specified for the print job. If there is no PrinterFont setting or the setting specifies a non-existent font, the AVM uses the default printer font for the job. If there is no point size specified for the font in the PrinterFont setting, the AVM uses the default size for the printer.
• OUTPUT TO LPT n in Windows performs the following processing:
  • Checks the ports settings in Windows for a definition of the specified LPT port. If there is no definition of the specified port, the AVM displays an error message and terminates the print operation. If multiple definitions exist for a port, the AVM uses the first definition that it finds.
  • Checks the current environment (either the Registry, or the [Startup] section in the initialization file) for a corresponding PrinterFontn setting (PrinterFont1 is for LPT1, etc.). If there is a valid corresponding PrinterFontn setting, the AVM uses the font specified for the print job. If there is no corresponding PrinterFontn setting or the setting specifies a non-existent font, the AVM uses the "courier new" font for the job and calculates the font height to fit 60 lines on a page. If there is no point size specified for the font in the PrinterFontn setting, the AVM uses the default size for the printer.
  • Defines a header at the top of each page in the output. The size of the header is based upon the following calculation: 1.5 * font-height.
• In Windows only, OUTPUT TO "CLIPBOARD" buffers all output to the specified stream until the next OUTPUT CLOSE for that stream. The OUTPUT CLOSE statement then writes the output to the Windows clipboard in CF-TEXT format. You can buffer only up to 64K of data between any stream-related pair of OUTPUT TO "CLIPBOARD" and OUTPUT CLOSE statements. Any additional buffered data is lost.

  For information on providing additional clipboard reading and writing capabilities to your application, see OpenEdge Programming Interfaces and the CLIPBOARD system handle reference entry.

• For any character conversions to occur, all of the necessary conversion tables must appear in convmap.cp (a binary file that contains all of the tables that ABL uses for character management).
• If you specify a value of "undefined" for either source-codepage or target-codepage, no character conversion is performed.
• The OpenEdge ADE toolset provides a portable solution for printing text files. The solution is a procedure called _osprint.p and it is located in the adecomm directory in the OpenEdge product directory (DLC). The _osprint.p procedure sends a specified text file to the default printer as paged output. For more information on the _osprint.p procedure, see OpenEdge Programming Interfaces.
• For more information on changing your output destination, see OpenEdge Programming Interfaces.

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