Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## INPUT-OUTPUT THROUGH statement

> ##
> (NT, UNIX only)

> Names a program (process) for Progress to start. This process is the input source as well as the output destination for the procedure.

> #### Syntax

>     INPUT-OUTPUT [ STREAM stream ]
>       THROUGH { program-name | VALUE ( expression ) }
>       [ argument | VALUE ( expression ) ] ...
>       [ ECHO | NO-ECHO ]
>       [ MAP protermcap-entry | NO-MAP ]
>       [ 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 unnamed stream is used. See the DEFINE STREAM statement reference entry and OpenEdge Development: Programming Interfaces for more information on streams.

> ``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 Progress 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). Progress uses the PROTERMCAP entries to build a translation table for the stream. Use NO-MAP to make Progress bypass character translation altogether. See OpenEdge Deployment: Managing 4GL 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 Progress’s UNIX statement can be intermingled with the input-output from the Progress statements that follow the INPUT-OUTPUT THROUGH statement. INPUT-OUTPUT THROUGH handles the buffering of data between the Progress 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 Progress. 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 Progress 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 Progress uses for character management).

> `NO-CONVERT`

> Specifies that no character conversions occur between the UNIX program and Progress. 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-num < 10:
>         DISPLAY item-num price LABEL "Price before recalculation".
>     END.

>     INPUT-OUTPUT THROUGH r-iothru UNBUFFERED.

>     FOR EACH item WHERE item-num < 10:
>         EXPORT price.
>         SET price.
>     END.

>     INPUT-OUTPUT CLOSE.

>     FOR EACH item WHERE item-num < 10 WITH COLUMN 40:
>         DISPLAY item-num price LABEL "Price after recalculation".
>     END.

> You can perform this calculation within a single Progress procedure. The C program is used for illustration purposes only. Use a UNIX program outside Progress 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.

> This 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 Progress 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, a Progress procedure can send information to a UNIX program, and the program can process that information and send the results back to Progress. 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 Progress sends data to the program, and the program sends data back to Progress, 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 Progress 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 Progress uses for character management).

> - If you specify a value of “undefined” for either `source-codepage` or `target-codepage`, no character conversion is performed.

> #### See also

> DEFINE STREAM statement, INPUT CLOSE statement, INPUT-OUTPUT CLOSE statement

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095