Uses the output from a program as the input to an ABL procedure.

Syntax

INPUT [ 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 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 topics on alternate I/O sources in OpenEdge Programming Interfaces for more information on streams and stream handles.
program-name
Represents the name of the program where you are supplying data to an ABL procedure. This can be a standard UNIX command or your own program. The name can contain Unicode characters. See Internationalize ABL Applications for more information about Unicode.
VALUE ( expression)

Specifies an expression whose value is the name of a program where you are supplying data to an ABL procedure. The name of the program can contain Unicode characters.

Or, it is an expression whose value is an argument you want to pass to the program. INPUT THROUGH passes the value of expression as a character string.

argument
Represents an argument you want to pass to the program. INPUT THROUGH passes this argument as a character string.

If the argument is the literal value echo, no-echo, or unbuffered, 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 THROUGH statement.

ECHO
Displays all input data on the current output destination. Data is echoed by default.
NO-ECHO
Accepts input data without displaying it on the current output device.
MAP protermcap-entry| NO-MAP
The protermcap-entry value is an entry from the PROTERMCAP file. Use MAP to read an input stream that uses a different character translation from 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 Manage ABL Applications for more information on PROTERMCAP. See Internationalize ABL Applications for more information on national language support.
UNBUFFERED
Reads one character at a time from a normally buffered data source, such as a file. Use the UNBUFFERED option only when the input operations of a UNIX process invoked by the ABL UNIX statement might be intermingled with the input from the ABL statements that follow the INPUT THROUGH statement.
CONVERT
Allows you to modify the character conversions occurring between the UNIX program and ABL. By default, the INPUT THROUGH statement converts characters from the code page specified with the Stream Code Page (-cpstream) parameter to the code page specified with the Internal Code Page (-cpinternal) parameter. 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 program and ABL. By default, the INPUT THROUGH statement converts characters from the -cpstream code page to the -cpinternal code page.

Examples

This procedure uses as its input source the output of the UNIX echo command. Before the command runs, the UNIX shell substitutes the process-id number for $ and the current directory search path for $PATH. The results are then echoed and become available as a line of input to ABL. When the IMPORT statement is executed, the line of input from echo is read and the values are assigned to the two variables. Those variables can then be used for any purpose. In this example, the word echo must be lowercase and the word $PATH must be uppercase, since they both pass to UNIX:

r-ithru.p 

DEFINE VARIABLE process-id AS CHARACTER NO-UNDO.
DEFINE VARIABLE dir-path   AS CHARACTER NO-UNDO 
  VIEW-AS EDITOR SIZE 60 BY 10.

INPUT THROUGH echo $ $PATH NO-ECHO.

SET process-id dir-path WITH FRAME indata NO-BOX NO-LABELS.
DISPLAY process-id dir-path FORMAT "x(70)".

INPUT CLOSE.

When you use INPUT THROUGH, the UNIX program you name is executed as a separate process under its own shell. Therefore, the values of shell variables (such as $) are values from that shell rather than the shell from which the AVM executes.

The following procedure uses INPUT THROUGH twice to get input from the UNIX pwd and ls commands. The pwd command supplies the name of the current directory and the ls command supplies the name of each UNIX file in your current directory. After the variable fn is set, it displays on the screen.

r-ithru2.p 

DEFINE VARIABLE dir-name AS CHARACTER NO-UNDO FORMAT "x(64)".
DEFINE VARIABLE fn       AS CHARACTER NO-UNDO FORMAT "x(32)".

FORM fn
  WITH DOWN FRAME dir-list.

/* Get the name of the current directory. */
INPUT THROUGH pwd NO-ECHO.
SET dir-name.
INPUT CLOSE.

/* Use the directory name as a label for fn. */
fn:LABEL IN FRAME dir-list = dir-name.

/* List the directory. */
INPUT THROUGH ls NO-ECHO.

/* For each entry in the directory, read the entry into fn and display it. */
REPEAT:
  SET fn WITH NO-BOX NO-LABELS FRAME indata.
  DISPLAY fn VIEW-AS TEXT WITH FRAME dir-list.
  DOWN WITH FRAME dir-list.
END.

INPUT CLOSE.

Notes

  • INPUT THROUGH specifies the source for subsequent statements that process input. It does not read any data from the source.
  • To use the IMPORT, INSERT, PROMPT-FOR, SET, or UPDATE statement, the AVM puts the data in the frame fields referenced in these statements, and if ECHO is in effect, the frame is output to the current output destination. If you use the NO-ECHO option, then the frame is not output. If a subsequent DISPLAY statement causes the frame to display, the input data also displays.
  • When INPUT THROUGH is closed, the pipe to the UNIX process is also closed.
  • 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 client processes running on UNIX, INPUT THROUGH starts a separate process for the external program from which it takes input. The client keeps track of subprocesses spawned using an in-memory table with a limit of 20 entries. Therefore, only 20 subprocesses can be open concurrently. If this limit is exceeded, you will see an error:
    SYSTEM ERROR: MAXSUBP: too many subprocesses. (357)
    To avoid this error, use INPUT CLOSE to remove the subprocess from the in-memory table.

See also

DEFINE STREAM statement, INPUT CLOSE statement, INPUT FROM statement, Stream object handle