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 ] 
  {    [ 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.

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.

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

The UNFORMATTED option forces IMPORT to read one physical line at a time. A physical line ends with a newline 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 or LONGCHAR variable, the AVM uses the code page information in the exported file header to determine the variable’s code page. However, the COPY-LOB statement is recommended for Unicode CLOB or LONGCHAR variables.