Specifies the name of a stream. If you do not name a stream, the unnamed stream is used. See the DEFINE STREAM statement reference entry and 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
Identifies the name of the UNIX program where the procedure is getting data and where the procedure is sending data.
VALUE ( expression )
Represents an expression whose value is the name of a UNIX program where the procedure is getting data and where the procedure is sending data.
Or, it is an expression whose value is an argument you want to pass to the UNIX program. INPUT-OUTPUT THROUGH passes the value of expression as a character string.
argument
Specifies an argument you want to pass to the UNIX program. INPUT-OUTPUT THROUGH passes this argument as a character string.
If the argument is the literal value echo, no-echo, or unbuffered, you must enclose it in quotes to prevent the AVM from interpreting that argument as one of the ECHO, NO-ECHO, or UNBUFFERED options for the INPUT-OUTPUT THROUGH statement.
ECHO
Displays all input data to the unnamed stream. Data is not echoed by default.
NO-ECHO
Accepts input data without displaying it on the current unnamed stream. Data is not echoed by default.
MAP protermcap-entry| NO-MAP
The protermcap-entry value is an entry from the PROTERMCAP file. MAP allows you to send output to and receive input from an I/O stream that uses different character translation than the current 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.
UNBUFFERED
Reads and writes one character at a time from a normally buffered data source, such as a file. Use the UNBUFFERED option only when the input-output operations of a process invoked by ABL's UNIX statement can be intermingled with the input-output from the ABL statements that follow the INPUT-OUTPUT THROUGH statement. INPUT-OUTPUT THROUGH handles the buffering of data between the ABL procedure and the UNIX program that it invokes. Use the UNBUFFERED option if your procedure invokes any other programs with the UNIX statement.
CONVERT
Allows you to modify the character conversions occurring between the UNIX program and ABL. By default, the INPUT-OUTPUT THROUGH statement converts characters from the Stream Code Page (-cpstream) parameter to the code page specified with the Internal Code Page (-cpinternal) parameter as data received from program-name. As data is passed to program-name, then INPUT-OUTPUT THROUGH converts from the -cpinternal to -cpstream. If you specify SOURCE source-codepage alone, the conversion accepts source-codepage as the code page name of the UNIX program (instead of -cpstream). If you specify TARGET target-codepage, the conversion accepts target-codepage as the internal code page (instead of -cpinternal). If you specify both SOURCE source-codepage and TARGET target-codepage, it converts characters from the source-codepage to target-codepage (instead of -cpstream to -cpinternal).
TARGET target-codepage
Specifies the target 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).
SOURCE target-codepage
Specifies the source 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).
NO-CONVERT
Specifies that no character conversions occur between the UNIX program and ABL. By default, the INPUT-OUTPUT THROUGH statement converts characters from the -cpstream code page to the -cpinternal code page as data is received from program-name. As data is passed to program-name, then INPUT-OUTPUT THROUGH converts from the -cpinternal to -cpstream.
Examples
This procedure uses a C program to recalculate the price of each item in inventory. Specifically, the C program increases the price of each item by 3% or by 50 cents, whichever is greater. The INPUT-OUTPUT THROUGH statement tells the procedure to get its input from, and send its output to, the r-iothru.p procedure. The INPUT-OUTPUT CLOSE statement resets the input source to the terminal and the output destination to the terminal.
r-iothru.p
FOR EACH Item WHERE Item.ItemNum < 10:
DISPLAY Item.ItemNum Item.Price LABEL "Price before recalculation".
END.
INPUT-OUTPUT THROUGH r-iothru UNBUFFERED.
FOR EACH Item WHERE Item.ItemNum < 10:
EXPORT Item.Price.
SET Item.Price.
END.
INPUT-OUTPUT CLOSE.
FOR EACH Item WHERE Item.ItemNum < 10 WITH COLUMN 40:
DISPLAY Item.ItemNum Item.Price LABEL "Price after recalculation".
END.
You can perform this calculation within a single ABL procedure. The C program is used for illustration purposes only. Use a UNIX program outside ABL to execute specialized calculations or processing.
You must unpack the C program from the proguide subdirectory and compile it before you can use it with the r-iothru.p procedure. If you do not have a C compiler, do not try this example.
Following is the C program used by the r-iothru.p procedure:
r-iothru.c
#include <stdio.h>
#define MAX(a,b) ( (a < b) ? b : a )
main( )
{
float cost;
/* This is important so that buffering does not */
/* defeat attempts to actually write on the pipe. */
setbuf(stdout, (char *) NULL);
while (scanf("%f", &cost) == 1) {
/* Here the item cost is manipulated. We are */
/* increasing the cost by a fixed percentage */
/* (with a minimum increase), to provide */
/* an example. */
cost = cost + MAX( 0.03 * cost, .50);
printf("%10.2f\n", cost);
}
}
Notes
Use EXPORT or PUT, not DISPLAY, to write data to the program.
Use SET to read data from the program.
If you read data from a C program, put an upper limit on how many errors can occur before the program ends. Also remember that if the program prints an error message, that message is sent to ABL as data. You can use fprintf(stderr,...) to display debugging messages to the window, even in the middle of an INPUT-OUTPUT THROUGH operation.
With INPUT-OUTPUT THROUGH in non-interactive mode, an ABL procedure can send information to a UNIX program, and the program can process that information and send the results back to the AVM. Some UNIX utilities you can use in batch mode are wc (word count) and sort.
Here are some pointers for using INPUT-OUTPUT THROUGH in this way:
When the procedure finishes sending data to the program, use the OUTPUT CLOSE statement to reset the standard output stream to the screen. Doing this signals an EOF on the pipe, indicating that the program has received all input. When the procedure has received all data from the program, use the INPUT CLOSE statement to reset the standard input stream. Do not use the INPUT-OUTPUT CLOSE statement, because that closes both pipes at once.
If you want to use the INPUT-OUTPUT THROUGH statement with a UNIX utility that buffers its output, use the non-interactive approach.
To signal an EOF, use OUTPUT CLOSE (rather than attempting to send a CTRL+D).
When you use INPUT-OUTPUT THROUGH in interactive mode the AVM sends data to the program, and the program sends data back to the AVM, etc.
Here are some pointers for using INPUT-OUTPUT THROUGH in this way:
At the end of the interaction between the procedure and the program, use the INPUT-OUTPUT CLOSE statement to shut down both pipes.
Be sure that the program you are using does not buffer its output. If the program is a C program, the first line of the program should be "setbuf(stdout, (char *) NULL):". The program should also include "#include <stdio.h>". These tell UNIX that the standard output of the program is unbuffered. If the program does buffer its output, use the batch approach to INPUT-OUTPUT THROUGH as explained in the previous note.
If the program ends on some condition other than detecting an EOF, make sure that it tells the ABL procedure that it is about to end.
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.
Use EXPORT or PUT, not DISPLAY, to write data to the program.