INPUT FROM statement

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` ] } ]

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.

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.

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. 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.

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:


1 55800 2 41300 5 88000

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.