Specifies the new input source for a stream.
Syntax
INPUT [ STREAM stream | STREAM-HANDLE handle ] FROM
{ opsys-file
| opsys-device
| TERMINAL
| VALUE ( expression )
| OS-DIR ( directory ) [ NO-ATTR-LIST ]
}
[ LOB-DIR { constant | VALUE ( expression ) } ]
[ BINARY ]
[ 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 AVM uses the unnamed stream. 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.
-
opsys-file
- The absolute or relative pathname of a file that contains the
data you want to input. Any relative pathname is relative to the
current working directory. Remember that UNIX file names are case
sensitive. The pathname can contain Unicode characters. See OpenEdge
Development: Internationalizing Applications for more information
about Unicode.
-
opsys-device
- The name of a UNIX or Windows device.
- TERMINAL
- Indicates that you want to get input from your terminal. The terminal
is the default input source. You cannot use TERMINAL with STREAM.
- VALUE ( expression )
- An expression whose value is the source where you want to input data.
The value can contain Unicode characters.
- OS-DIR (directory)
- Indicates that you want your input to be the filenames found
in directory. The value of directory is
a character expression specifying an operating system directory.
This value can contain Unicode characters. If directory is
not a directory or you do not have permission to read it, then the
INPUT statement raises ERROR. Otherwise, the AVM generates the directory
list and feeds it back to the calling program through the INPUT
stream. An INPUT CLOSE statement discards any unread filenames from
the list.
Each line read from the input stream is a string composed
of three tokens: the file's base name, the file's absolute path
name, and an attribute list indicating the file type, which consists
of one or more of the characters listed below.
You will get
one of the following characters:
- F — Regular file
or FIFO pipe
- D — Directory
- S — Special device
- X — Unknown file type
You might also get
one or more of the following characters:
- H — Hidden
file
- L — Symbolic link
- P — Pipe file
If you specify the NO-ATTR-LIST
option, you will not get the attribute list for any line read from
the input stream.
The two filenames in each input line are
in EXPORT format; that is, they are enclosed in quotes and any embedded
quotes are doubled. This means that INPUT FROM can process any filename,
containing any characters, as long as IMPORT is used to read the
input. The two filenames can use Unicode characters.
- NO-ATTR-LIST
-
Omits the attribute list indicating the file type. This can
speed up program execution. The following example illustrates this
form of the statement:
INPUT FROM OS-DIR("c:\mydir") NO-ATTR-LIST.
|
- LOB-DIR {constant| VALUE ( expression ) }
- Specifies the directory from which you want the IMPORT statement to
read large object data files (such as BLOB and CLOB data files).
The constant and expression arguments
are character expressions that evaluate to an absolute pathname
or a relative pathname (relative to the directory specified for opsys-file).
If
the specified character expression evaluates to either the Unknown value (?) or
a directory that does not exist, or you do not have permission to
read the specified directory, the AVM raises the ERROR condition.
The LOB-DIR option
is valid only when you specify an operating system file as the input
data source.
- BINARY
- Allows all input to be read directly without any conversion
or interpretation. By default, NUL (\0) terminates character strings,
and other control characters are interpreted as expected for the
operating system.
- ECHO
- Displays all input data on the current output device. Data is
echoed by default.
- NO-ECHO
- Accepts input data without displaying it on the current output device.
If you do not use this option, INPUT FROM automatically displays
input data 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 from 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 OpenEdge
Development: Internationalizing Applications for more information
on PROTERMCAP and 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 you
can intermingle the input operations of a UNIX process, invoked
with the ABL UNIX statement, with the input that follows the ABL
INPUT FROM statement.
- CONVERT
- Allows you to modify the character conversions occurring between the
external file and ABL. By default, the INPUT FROM 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 external file (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 external file
and memory. By default, the INPUT FROM statement converts characters
from the -cpstream code page to the -cpinternal code page.
Example
Instead
of getting input from the terminal, this procedure gets input from a
file named r-in.dat. The SEARCH function determines the
full pathname of this file.
r-in.p
INPUT FROM VALUE(SEARCH("r-in.dat")).
REPEAT:
PROMPT-FOR Customer.CustNum Customer.CreditLimit.
FIND Customer USING INPUT Customer.CustNum.
ASSIGN Customer.CreditLimit.
END.
INPUT CLOSE.
|
This is what the contents of the r-in.dat file
look like:
The PROMPT-FOR statement uses the first data
item (1) as the CustNum and the second data item
(55800) as the CreditLimit. The FIND statement
finds the customer whose CustNum is 1 and assigns
the value of 55800 as that Customer's credit limit. On the next
iteration of the REPEAT block, the PROMPT-FOR statement uses the
value of 2 as the CustNum, the value of 41300 as
the CreditLimit, etc.
The INPUT CLOSE statement
closes the input source, resetting it to the terminal. When you
run this procedure, the data in the window is simply an echo of
the data that the procedure is reading from the taxno.dat file.
If you do not want to display the data, add the word NO-ECHO to
the end of the INPUT FROM statement.
Notes
- To
close the current input to a procedure, use the INPUT CLOSE statement.
(The input source is automatically closed at the end of the procedure
or when another default input source is opened.)
- The BINARY option allows you to use the READKEY statement to read
control characters from the input source without interpretation.
For example, NUL (\0) does not terminate strings, CTRL+Z does not signal EOF, and CTRL+J is not converted to CTRL+M, but their binary values
are provided directly.
- If the input source and output destination are both the TERMINAL, then
ECHO is always in effect.
- Use the IMPORT, INSERT, PROMPT-FOR, SET, or UPDATE statements
to read data into an ABL procedure. The data is placed into the frame
fields referenced in these statements, and, if you use ECHO, then 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 appear, then the input data also appears if
the frame is not yet in view.
- SEEK is not supported in conjunction with the OS-DIR option.
- When using the OS-DIR option, the UNBUFFERED option is ignored.
OS-DIR always buffers exactly one filename at a time.
- If you use the PROMPT-FOR, SET, or UPDATE statement to read data
from a file, the FORMAT for the data is ignored. Therefore, if you
rely on FORMAT to validate input, you might read invalid characters.
- If you use the PROMPT-FOR, SET, or UPDATE statement to read data
from a file, and there is a piece of data in each line of the file
that you want to disregard, use a caret (^) in the PROMPT-FOR, SET,
or UPDATE statement. For more information on this symbol, see the
reference entry for any of those statements.
- If end of file is reached, the AVM responds as if you pressed ENDKEY.
- If a line consisting of a single period is read, that is treated
as if you pressed END-ERROR. If
the period is in quotes (".") it is treated as an ordinary character.
- When you use the INPUT FROM statement to read data from a file, there
are two special characters you can use in that data file: tilde
(~) and (slash (\) on UNIX, and hyphen (-).
If characters in an
input file take up more than one physical line, you can use tilde
(~) to indicate a line continuation. This is an input file that uses
a tilde:
92 "Match Point Tennis" "66 Homer Ave" "Como" ~
"TX" 75431
93 "Off the Wall" "20 Leedsville Ave" "Export" "PA" 15632
|
Do not include a space after the tilde. For
example:
- You can see that the record containing the tilde was treated
as a single input line.
-
A hyphen in an input file indicates that you do not want
to change the corresponding field in the INSERT, PROMPT-FOR, SET
or UPDATE statement. This is the same input file as shown above,
including the hyphen:
92 "Match Point Tennis" - "Como" "TX" 75431
93 "Off the Wall" "20 Leedsville Ave" "Export" "PA" 15632
|
The procedure in the following example uses
this file to set records in the customer file. When those records
are displayed, the Match Point Tennis address does not change.
To
enter a literal hyphen from a file, enclose it in quotes ("-").
- In Windows, the data in the input file must have the following
characteristics:
- The lines of data in the file are separated
by CR-LF pairs.
- There is no CTRL+Z (EOF) embedded
in the file.
- 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.
- If the field being input is MEMPTR, you must use the BINARY
and NO-CONVERT mode of operation to prevent your data from becoming corrupted
if it contains binary data.
- With the BINARY and NO-CONVERT options, you will not get a translation
of new-lines to the appropriate characters for your operating system
and there will be no code page conversion between -cpinternal and -cpstream.
- If the field being input is MEMPTR and your MEMPTR contains ASCII
data you may want code page conversion. However, you cannot get conversion
by using the CONVERT parameter on the MEMPTR. You can get code page
conversion by using the MEMPTR with the GET-STRING and CODEPAGE-CONVERT
functions and the PUT-STRING statement.