Names a program (process) for the AVM to start.
This process is the input source as well as the output destination
for the procedure.
Syntax
INPUT-OUTPUT [ STREAM stream | STREAM-HANDLE handle ]
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.
- 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.