IMPORT statement

Reads a line from an input file that might have been created by EXPORT.

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 chapter on alternate I/O sources in OpenEdge Development: 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 phrase reference entry for more information.
EXCEPT field
Tells the AVM to import all the fields except those listed in the EXCEPT phrase.
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
Suppresses ABL errors or error messages that would otherwise occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement is not done and execution continues with the next statement. If the statement fails, any persistent side-effects of the statement are backed out. If the statement includes an expression that contains other executable elements, like methods, the work performed by these elements may or may not be done, depending on the order the AVM resolves the expression elements and the occurrence of the error.

To check for errors after a statement that uses the NO-ERROR option:

  • Check the ERROR-STATUS:ERROR attribute to see if the AVM raised the ERROR condition.
  • Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than zero to see if the AVM generated error messages. ABL handle methods used in a block without a CATCH end block treat errors as warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR attribute, but do add messages to the ERROR-STATUS system handle. Therefore, this test is the better test for code using handle methods without CATCH end blocks. ABL handle methods used in a block with a CATCH end block raise ERROR and add messages to the error object generated by the AVM. In this case, the AVM does not update the ERROR-STATUS system handle.
  • Use ERROR-STATUS:GET-MESSAGE( message-num ) to retrieve a particular message, where message-num is 1 for the first message.

If the statement does not include the NO-ERROR option, you can use a CATCH end block to handle errors raised by the statement.

Some other important usage notes on the NO-ERROR option:

  • NO-ERROR does not suppress errors that raise the STOP or QUIT condition.
  • A CATCH statement, which introduces a CATCH end block, is analogous to a NO-ERROR option in that it also suppresses errors, but it does so for an entire block of code. It is different in that the error messages are contained in a class-based error object (generated by the AVM or explicitly thrown), as opposed to the ERROR-STATUS system handle. Also, if errors raised in the block are not handled by a compatible CATCH block, ON ERROR phrase, or UNDO statement, then the error is not suppressed, but handled with the default error processing for that block type.
  • When a statement contains the NO-ERROR option and resides in a block with a CATCH end block, the NO-ERROR option takes precedence over the CATCH block. That is, an error raised on the statement with the NO-ERROR option will not be handled by a compatible CATCH end block. The error is redirected to the ERROR-STATUS system handle as normal.
  • If an error object is thrown to a statement that includes the NO-ERROR option, then the information and messages in the error object will be used to set the ERROR-STATUS system handle. This interoperability feature is important for those integrating code that uses the traditional NO-ERROR technique with the newer, structured error handling that features error objects and CATCH end blocks.
memptr
A variable of data type MEMPTR that contains the imported text. The IMPORT statement my contain a MEMPTR in its field list as long as it is the only field in the list.
longchar
A variable of data type LONGCHAR that contains the imported text. The IMPORT statement may contain a LONGCHAR in its field list as long as the LONGCHAR is the only field in the list and is the result of an EXPORT statement.

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

See also

DEFINE STREAM statement, DISABLE TRIGGERS statement, DISPLAY statement, EXPORT statement, INPUT FROM statement, INPUT CLOSE statement, PUT statement, Stream object handle, STRING function