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