Reads a line from an input file that might have been created by the EXPORT statement or the BUFFER-EXPORT() or BUFFER-EXPORT-FIELDS() methods.

Syntax

IMPORT [ STREAM stream | STREAM-HANDLE handle ]
  {    [ DELIMITER character ] { field | ^ } ...
     | [ DELIMITER character ] record [ EXCEPT field ... ]
     | UNFORMATTED field
  }
  [ NO-LOBS ]
  [ NO-ERROR ]
 
IMPORT [ STREAM stream | STREAM-HANDLE handle ] { memptr | longchar }
STREAM stream
Specifies the name of a stream. If you do not name a stream, the AVM uses the unnamed stream.
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.
DELIMITER character
The character used as a delimiter between field values in the file. The character parameter must be a quoted single character. The default is a space character.

If you specify more than one character as a delimiter, ABL uses the first character as the delimiter.

field
The name of a field or variable to which you are importing data. The field or variable must have either the CHARACTER or RAW data type. If the data type is RAW, the IMPORT statement reads enough characters to fill the current length of the variable. If not enough characters are available to fill the current length, the length is reset to the number of characters read.
^
Use a caret (^) to skip a data value in each input line when input is being read from a file.
record
The name of a record buffer. All of the fields in the record are processed exactly as if you had named each of them individually. The record you name must contain at least one field. To use IMPORT with a record in a table defined for multiple databases, qualify the record's table name with the database name. See the record definition in the Record phrase reference entry for more information.
EXCEPT field
Tells the AVM to import all the fields except those listed in the EXCEPT phrase.
Note: The EXCEPT phrase does not support individual elements of an array. If an array element is specified in the EXCEPT phrase, the entire array is omitted from the import, not just the element specified.
UNFORMATTED field
Treats each line of the input file as a single string value. In this case, the field parameter must be a single CHARACTER or RAW field or variable. You can use this option to read text files one line at a time.

Use this option on a RAW variable to import binary data that was not exported to the file as RAW data.

NO-LOBS
Directs the AVM to ignore large object data when importing records that contain BLOB or CLOB fields.
NO-ERROR
The NO-ERROR option is used to prevent the statement from raising ERROR and displaying error messages.
memptr
A variable of data type MEMPTR to which you are importing data.
longchar
A variable of data type LONGCHAR to which you are importing data.

Examples

This procedure takes the data in file customer.d and enters it into the OpenEdge database table Customer. The procedure uses the DISABLE TRIGGERS statement to stop the AVM from executing any triggers for the CREATE, WRITE, and ASSIGN events when loading the data.

Note: The imported files, customer.d and custdump2, in the next two examples are created by running the example programs under EXPORT.

r-imprt.p 

INPUT FROM customer.d.

DISABLE TRIGGERS FOR LOAD OF Customer.

REPEAT:
  CREATE Customer.
  IMPORT Customer.
END.

INPUT CLOSE.

If the file uses a delimiter other than a space to separate fields, use the DELIMITER option of the IMPORT statement.

r-cstin.p 

DEFINE VARIABLE cnum  NO-UNDO LIKE Customer.CustNum.
DEFINE VARIABLE cname NO-UNDO LIKE Customer.Name.
DEFINE VARIABLE cmax  NO-UNDO LIKE Customer.CreditLimit.

INPUT FROM custdump2.

FOR EACH Customer:
  IMPORT DELIMITER ";" cnum cname cmax.
  DISPLAY cnum cname cmax.
END.

INPUT CLOSE.

You can use the UNFORMATTED option to read the contents of a standard text file. For example, the following procedure reads and displays the contents of the hello file:

r-hello.p 

DEFINE VARIABLE text-string AS CHARACTER NO-UNDO FORMAT "x(76)".

INPUT FROM VALUE(SEARCH("hello")).
DO WHILE TRUE ON ENDKEY UNDO, LEAVE:
  IMPORT UNFORMATTED text-string.
  DISPLAY text-string WITH DOWN FRAME x.
  DOWN WITH FRAME x NO-LABELS.
END.
INPUT CLOSE.

In the MEMPTR version of the IMPORT statement, the MEMPTR must be pre-allocated to the size needed for reading. To get the length to read for an imported file, use the FILE_INFO system handle and the SET-SIZE statement as follows:

r-impmem.p 

DEFINE VARIABLE bb AS MEMPTR NO-UNDO.

ASSIGN
  FILE-INFO:FILE-NAME = "big.in"
  SET-SIZE(bb)        = FILE-INFO:FILE-SIZE.

INPUT FROM "big.in" BINARY NO-CONVERT.
IMPORT bb.
INPUT CLOSE.

Notes

  • The IMPORT statement must follow a statement that redirects the input source (usually an INPUT FROM statement). You cannot use the IMPORT statement to read data from the screen.
  • If you do not use the UNFORMATTED option, the data in the input stream must be in a standard format to be read back into ABL. You must enclose all character fields in quotes ("") if they contain any delimiter characters. If you want to import any quotes contained in the data, replace them with two quotes ("" ""). You must display the Unknown value (?) as an unquoted question mark.
  • If an input data line contains an unquoted hyphen in place of a data value, then the corresponding field is skipped, as it is in UPDATE. If you specify a hyphen (-) as the delimiter character, all hyphens are treated as delimiters. If you use the UNFORMATTED option, the hyphen is treated the same as any other character.
  • A period (.) on a line by itself is treated as an end-of-file indicator. The ENDKEY is applied, but the file or stream remains open for input.
  • Data read in with IMPORT is not restricted by frame-related format statements, as is data read in by SET or UPDATE. Since IMPORT does not have to validate the input stream, it is faster than SET or UPDATE.
  • When importing records that contain a BLOB or CLOB field, the AVM uses the value stored in the BLOB or CLOB field of the exported record to determine whether or not the exported record has an associated object data file to import. If the BLOB or CLOB field in the exported record contains the Unknown value (?), the AVM stores the Unknown value (?) in the BLOB or CLOB field of the new or updated record. If the BLOB or CLOB field in the exported record contains a filename, the AVM imports the associated object data. If an updated record already has object data associated with it, the AVM deletes that object data before importing the new object data.

    The AVM raises the ERROR condition if an object data file cannot be found or read.

  • Use the NO-LOBS option with the IMPORT statement to ignore large object data when importing records that contain BLOB or CLOB fields. More specifically:
    • When you import an exported record into a new record, and the BLOB or CLOB field of the exported record contains either the Unknown value (?) or a filename, the AVM sets the value of the BLOB or CLOB field in the newly imported record to the Unknown value (?); the AVM does not create any object data.
    • When you import an exported record as an update to an existing record, and the BLOB or CLOB field of the exported record contains either the Unknown value (?) or a filename, the AVM does not change the value of the BLOB or CLOB field in the existing record and neither creates nor overwrites object data.
  • The IMPORT statement reads large object data files from the directory specified as the input data source in the INPUT FROM statement, by default. You can use the LOB-DIR option on the INPUT FROM statement to specify the directory from which the IMPORT statement reads BLOB and CLOB data files.
  • IMPORT is sensitive to the Date Format (-d), Century (-yy), and European Numeric Format (-E) parameters. When loading data with the IMPORT statement, use the same settings that you used with the EXPORT statement.
  • When importing DATETIME and DATETIME-TZ data, the data format must be fixed and must conform to the ISO 8601 standard for date/time representations (YYYY-MM-DDTHH:MM:SS.SSS+HH:MM). For DATETIME, there is no time zone offset.
  • ABL interprets the null character as a data field terminator. This can cause unexpected behavior if a complete record was not read before the null character was encountered, because IMPORT reads the next line to populate any buffer fields that were not read. Progress strongly discourages the importing of data containing null characters.
  • The UNFORMATTED option forces IMPORT to read one physical line at a time. A physical line ends with a newline or linefeed control character, or the end of the file marker for the last line when it is not terminated with a new line or linefeed character.
  • In the MEMPTR version of the IMPORT statement, the MEMPTR must be pre-allocated to the size needed for reading. See the example, r-impmem.p, above.
  • When importing a CLOB field, the AVM uses the code page embedded in the filename of the <clobfile>.blb to determine the clob's code page. When importing a LONGCHAR variable, the AVM uses the code page information in the exported file header to determine the variable's code page. The COPY-LOB statement is recommended for Unicode CLOB fields or LONGCHAR variables, or when the code page information is not available in the source.
  • When using the IMPORT statement to load data into an indeterminate array, all elements are loaded with the value of the first data value in the input record. To load each input data value into an element of the array, import the entire input file record into a CHARACTER variable and assign the individual values into the array elements in a loop.
  • Imported data can be in Scientific notation format for DECIMAL, INTEGER, and INT64 data types.

See also

BUFFER-EXPORT( ) method, BUFFER-EXPORT-FIELDS( ) method, BUFFER-IMPORT( ) method, BUFFER-IMPORT-FIELDS( ) method, DEFINE STREAM statement, DISABLE TRIGGERS statement, DISPLAY statement, EXPORT statement, INPUT FROM statement, INPUT CLOSE statement, NO-ERROR option, PUT statement, Stream object handle, STRING function