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:
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
- 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.
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 OpenEdge Deployment: 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 LPTn 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 LPTn 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 Development: 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 Development: Programming Interfaces.
- For more information on changing your output destination, see OpenEdge
Development: Programming Interfaces.