OUTPUT THROUGH statement

Identifies a new output destination as the input to a process that the AVM starts.

Syntax

OUTPUT [ STREAM stream| STREAM-HANDLE handle ] THROUGH 
  { program-name | VALUE ( expression ) }
  [ argument | VALUE ( expression ) ] ...
  [ ECHO | NO-ECHO ]
  [ MAP protermcap-entry | NO-MAP ]
  [ PAGED ]
  [ PAGE-SIZE {constant | VALUE ( expression ) } ]
  [ UNBUFFERED ]
  [     NO-CONVERT
     |  { CONVERT 
            [ TARGET target-codepage ]
            [ SOURCE source-codepage ]
         }
  ]

STREAM stream

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.

program-name

The name of the program to which you are supplying data from a procedure. This can be a standard command or your own program. The name can contain Unicode characters. See OpenEdge Development: Internationalizing Applications for more information about Unicode.

VALUE ( expression )

An expression whose value is the name of a UNIX program to which you are supplying data from a procedure. The program name can contain Unicode characters. An expression is also the argument that you want to pass to the UNIX program. OUTPUT THROUGH passes the value of expression as a character string.

argument

An argument you want to pass to the UNIX program. The OUTPUT THROUGH statement passes this argument as a character string.

If the argument is the literal value paged, page-size, echo, no-echo, or unbuffered, you must enclose it in quotes to prevent the AVM from using that argument as one of the PAGED, PAGE-SIZE, ECHO, NO-ECHO, or UNBUFFERED options for the OUTPUT THROUGH statement.

ECHO

Sends all input data read from a file to the UNIX program. The AVM echoes data by default.

NO-ECHO

Suppresses the echoing of input data to the UNIX program.

MAP protermcap-entry | NO-MAP

The protermcap-entry 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.

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 use 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 on the screen. If you specify a non-zero value for PAGE-SIZE, then the PAGED option is assumed. If you specify PAGE-SIZE 0, the output is not paged.

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 THROUGH statement). That is, the OUTPUT THROUGH 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 UNIX program and ABL. 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 the AVM memory (instead of -cpinternal).

If you specify TARGET target-codepage, the conversion accepts target-codepage as the code page of the UNIX program (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 ABL. By default, the OUTPUT THROUGH statement converts characters from the -cpinternal code page to the -cpstream code page.

Examples

In this example, the Customer names are displayed. This output is sent as input to the UNIX wc (word count) command. The output of wc is directed to the file wcdata using the standard UNIX redirection symbol (>). Finally, the results are displayed as three integers that represent the number of lines, words, and characters that were in the data sent to wc.

r-othru.p

OUTPUT THROUGH wc > wcdata.
/* Word count UNIX utility */

FOR EACH Customer NO-LOCK:
  DISPLAY Customer.Name WITH NO-LABELS NO-BOX.
END.

OUTPUT CLOSE.
PAUSE 1 NO-MESSAGE.
UNIX cat wcdata.
UNIX SILENT rm wcdata.

The r-othru2.p procedure uses the UNIX crypt program, which accepts lines of data, applies an algorithm based on an encryption key and writes the result to the UNIX standard output stream, that can be directed to a file. The output from the procedure is directed to crypt, which encrypts the customer names based on the password, mypass. The results of the encryption are stored in the ecust file. Then, the AVM decrypts and displays this file.

r-othru2.p

OUTPUT THROUGH crypt mypass > ecust.

FOR EACH Customer NO-LOCK WHERE Customer.CustNum < 10:
  DISPLAY Customer.Name WITH NO-LABELS NO-BOX.
END.

OUTPUT CLOSE.

UNIX crypt mypass <ecust.

Notes

• When you use the OUTPUT CLOSE statement to close an output destination used by an OUTPUT THROUGH statement, the AVM closes the pipe, waits one second, and then continues.
• 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.
• For more information on output destinations, see OpenEdge Development: Programming Interfaces.

See also

DEFINE STREAM statement, OUTPUT CLOSE statement, OUTPUT TO statement, Stream object handle