DATA IMPORT FACILITY The Data Import facility lets you import data from an external source file

into a target form in the current database. The source file can be a DataEase data f ile or a data file created by another program in any of these widely used format s: DataEase, dBase II, dBase III, DIF (Data Interchange Format), Lotus 1-2-3, M ailMerge, Variable Length ASCII, or Fixed Length ASCII. If the source file is not in one of these formats, you must first convert it to an acceptable format and then import it. Summary of Import File Formats The figure shown below summarizes the eight import formats, the type of program that generates the format, and the filename extension DataEase uses if you don't specify an extension for the source file. -------------------------------------------------------------------- Import Form at For Import Default File Type From Extension ------------------------------------------------------------------- DataEase Another DataEase .DB A Source Form database .DBM Data File Lotus 1-2-3 Lotus 1-2-3/ .WKS Lotus Symphony .WK1, .WK2 DIF Spreadsheets .DIF dBASE II dBASE III/IV dBASE III PLUS MailMerge dBASE II dBASE III, Wordstar .DBF .DBF dBASE IV .DAT

Variable Mainframe Databases, .DAT Length Custom Programs, ASCII Word Processors Fixed Mainframe .DAT Length Databases ASCII Custom Programs ------------------------------------------------------------------Special Import considerations for each of the eight formats are explained in the following pages. Destination Fields When importing data in the DataEase or the dBASE formats, DataEase automatically formats the data for each field. For the other import formats, the Field Type on the destination form determines how the source data is imported as explained below: Text Field All characters and embedded spaces are imported into the destination field. Quotation marks surrounding Variable Length ASCII and DIF format text dat a are removed. During an import, text data is imported line by line from a mult iple line text field; no word wrap takes place as it enters a DataEase Long:Text field. Number Field or Dollar Field Punctuation marks and plus and minus signs are incl uded in the import. When importing data in Fixed or Variable Length ASCII format , DataEase asks whether to import decimal points or not.

Numeric String Field or Time Field Punctuation marks in formatted strings (such as the colons in a time value or the dashes in telephone numbers) are imported. Other punctuation marks are removed. Date Field If the source data expresses all date values with six digits (e.g., 0 1/10/89), punctuation marks are removed. If date values are expressed with fewer than six digits (e.g., 1/10/89), punctuation marks are included in the import. Choice Field If the first character of the source data value is a number, DataEa se assumes it is the choice number. If the first character is not a number, Dat aEase assumes it is the choice value. If the imported value is not a valid choi ce number or value, a blank (unspecified) value is stored in the destination fie ld. Derived Fields When records are imported, DataEase automatically rederives the v alues for all fields in the destination form that are defined with Derivation Fo rmulas. If a field value that is used in the Derivation Formula of another field is overwritten by an imported value, DataEase automatically rederives the Deriv ed field's value. Sequence fields are always rederived after data is imported i nto the destination form. Source and Destination Forms The import process for all of the import file formats requires that you initiall y answer the same three questions: First, DataEase prompts: Please select the destination form name : Specify the name of the form that you want to use as the destination form for th e import by selecting the form name from the list of forms displays. If you select System, displays a list of the DataEase System forms. From this l ist, select the System form you want to use as the destination form for the impo rt. Next, DataEase prompts: Please enter the source data file name : Enter the DOS filename of the source file that contains the data to be imported into the specified destination form. If the source file is in a different directory than the import specification, sp ecify the full DOS pathname, including the drive letter, directory, and DOS file name (including the three-letter file extension). File Format Next, DataEase prompts: What is the data file format? Specify the format of the source data file by selecting one of the eight file fo rmats from the list displayed by . After you specify the destination form name, the source filename, and the format of the source file, DataEase asks various additional questions depending on whi ch format you have selected.

Processing Matching Records Regardless of the source file format, when defining the import specification Dat aEase prompts: How should matching records be processed? DataEase is asking how to handle records in the source file that have a Unique f ield value that matches the value in an existing record in the destination form. Records are imported from the source file according to one of the following ru les: Add non-matching: DataEase imports only the source file records that do not mat ch any record in the destination form. The non-matching records are added to th e records in the destination form. The matching records that are not imported a re noted in an Exception file. Update Matching: DataEase imports only the source file records that match a reco rd in the destination form. Each imported record overwrites the matching record in the destination form. The non-matching records that are not imported are no ted in an Exception file. Add or Update: DataEase imports all the source file records, adding non- matchin g records and overwriting matching records in the destination form. Do not Match: DataEase imports all the source file records. The imported record s are added to the existing records in the destination form without any regard f or matching Unique field values. NOTE: When using "Do not Match", the imported records are not checked for unique ness. You should not select this option unless you are sure there are no duplic ate records in the two forms. IMPORT FORMATS DataEase Import Format The DataEase import format is used to import data from a form in another DataEas e database (the source form) into a form in the current database (the destinatio n form). After you've specified the destination form and source data file name, select DA TAEASE as the source data file format. DataEase then prompts: Is the source form the same as the destination form? DataEase is asking if the source and destination forms are identical. If the Fi eld Names, field definitions, and field sequence on the two forms are identical, answer yes. If you answer yes, DataEase immediately proceeds to the matching r ecords question (discussed earlier in this chapter). If the two forms are not identical, answer no. If you answer no, DataEase promp ts: Please enter the source form filename: Enter the correct filename (including the drive and directory name) and press RE TURN. The default drive for this file is the current data drive and the file ex tension is .DBA. DataEase then asks:

How should matching records be processed? In response, select one of the four matching record handling options from the me nu and then press F2 SAVE to save the Import Specification. NOTE: The data in a form in which the records are encrypted cannot be imported. Each record must be decrypted before you can transfer the data into another for m. Lotus 1-2-3, DIF, dBASE, and Mail-Merge Import Formats When importing data in the Lotus, DIF, dBASE, or Mail Merge format, after you sp ecify the destination form name, source data file name, and source data file for mat, you must specify how the source data should be inserted into the destinatio n fields. asks: How is the source file organized? and offers two choices as explained below: By field order: If you select this option, imports the first field in each sour ce record into the first field in the destination form, the second source field into the second destination field, etc. If the source file has more fields per record than the destination form, the excess source fields in each record are no t imported. If the source form has fewer fields per record than the destination form, the excess destination fields receive a blank (unspecified) value. By field name: If you select this option, only transfers data from a source fie ld into a destination field with the same field name. Data in a source field th at does not have a matching destination field is not imported. When comparing F ield Names for this transfer, DataEase treats upper and lower case as identical. DataEase finds the source Field Names by reading the first line or record in th e source file. When importing data by field name, DataEase must be supplied with the Field Name s used in the source file. The source Field Names are automatically supplied wh en the import is in the dBASE format. To import data in the DIF, Lotus 1-2-3, or Mail Merge format, the first record i n the source file must contain the names of the source fields. Programs that pro duce DIF or Mail Merge format files usually list the Field Names in the first re cord; however, it is wise to check the file first using the DOS TYPE command. F or Lotus 1-2-3 files, be sure the first row of the output file contains the Fiel d Names, one per column. Variable Length ASCII Import Format When you import data in the Variable Length ASCII file format, the first record must contain the Field Names used in the source file. In addition, because the source fields and records vary in length, you must tell DataEase what character is used by the source program to separate fields and to separate records. After you specify the destination form name, source data filename, and source da ta file format, prompts: FIELD SEPARATOR character (If new line, press RETURN): In response, enter the field separator character used in the source file and pre ss RETURN. The default field separator is the new line character. If the new li

ne character is used as the field separator, just press RETURN. If you are using a program that lets you designate the field separator, we recom mend that you use the new line character, a semicolon (;) or a vertical bar (|). The new line character may be stored in the source file either as a Carriage R eturn (decimal code 13) alone, or as a Carriage Return followed by a Line Feed ( decimal code 10). Next, prompts: RECORD SEPARATOR character (If new line, press RETURN): DataEase also needs to know the character used to separate records in the source file. In response, enter the record separator character used in the source fil e and press RETURN. The default record separator is the new line character. If the new line character is used as the record separator, just press RETURN. NOTE: Any character other than the field separator can be used as the record sep arator. If receives two consecutive record separator characters during an Impo rt, it creates a null record of blank fields. If the target form has any Requir ed fields, and receives consecutive record separator characters, the data trans fer will be erroneous and an error will be listed an exception file. When importing data in the Variable Length ASCII file format, DataEase also asks : For fixed point fields, should the decimal be automatically inserted?

Some programs store decimal numbers without the decimal point. DataEase is aski ng if it should insert decimal points into Fixed Point Number fields. If you ans wer yes, DataEase adds the decimal point when importing the data. If you answer no, DataEase does not insert decimals, although it does import decimal points th at exist in the source file. DataEase then asks: How is the source file organized? and offers two choices as explained below: By field order: If you select this option, DataEase imports the first field in e ach source record into the first field in the destination form, the second sourc e field into the second destination field, etc. If the source file has more fie lds per record than the destination form, the excess source fields are not impor ted. If the source form has fewer fields per record than the destination form, the excess destination fields receive a blank (unspecified) value. By field name: If you select this option, DataEase only transfers data from a so urce field into a destination field with the same Field Name. Data in a source field that does not have a matching destination field is not imported. When comp aring Field Names for this transfer, DataEase treats upper and lower case as ide ntical. When importing data by field name, DataEase must be supplied with the Field Name s used in the source file. If your source file does not have the Field Names in the first record, you can add them using DOS or a word processor that can edit ASCII files. Fixed Length ASCII Import Format

When you import data in the Fixed Length ASCII file format, the Field Names used in the source file are automatically included as part of the data. However, bec ause the source fields have fixed lengths, the length of each field in the DataE ase destination form must exactly match the length of the source file field. In addition, the order of the fields must be identical on both forms. Unlike othe r import formats, DataEase does not ask you to specify the order in which the da ta should be transferred. A Fixed Length data file is automatically imported by field order. Before importing a Fixed Length ASCII data file, you must know the length of eac h field in the source file and have a DataEase destination form with fields that exactly match the source file fields. To measure the source fields, count each character and space (or use the field lengths specified in a printed form defin ition if the source program can generate the data). Do not use the number of dig its in a Number field or the field size in the record as these do not account fo r spaces necessary to accommodate decimal points or commas. To ensure valid results, Number field data in the source file must be formatted in one of the two following ways: - If the number includes a decimal point, there must be a comma separating e ach group of three digits to the left of the decimal point. - If the decimal point and/or commas are excluded, the field must incorporate leading spaces, zer os, or trailing spaces that equal the number of punctuation marks omitted. The resulting total field width should equal the number of characters needed for the fully punctuated format. If you cannot create a field with the proper punctuation or spacing, import the data into a Numeric String field. After the import, change the field to the des ired number type; the contents will be automatically converted correctly. After you specify the destination form name, source data filename, and source da ta file format, DataEase prompts: Is the file in a Fixed Length with NO SEPARATORS? DataEase is asking if the source data file has a field separator character (a sp ecial character that marks the end of each field). Answer yes if the source file has no field separator. If you answer no, DataEase immediately terminates the import. If there is a fie ld separator, the destination form must be modified before the import can be exe cuted. The destination form is modified by adding a one-character length field immediat ely after each field to accommodate the field separator character during the dat a import. Without these extra fields, the source data will not correctly match its proper location in the destination form. After the import, you can delete t hese fields. Next, DataEase asks: Do the field ORDER and LENGTHS match the DATAEASE form? DataEase is asking if the length and order of the fields in the destination form exactly match the length and order of the fields in the source data file. If y ou answer yes, DataEase continues with the import. If you answer no, DataEase terminates the import. Before the import can be exec

uted, you must modify the destination form so the two forms match. If your source file contains more the import using an intermediate to exactly match the field length ort the data from the source file Next, DataEase asks: For fixed point fields, should the decimal be automatically inserted? Some programs store decimal numbers without the decimal point. DataEase is aski ng if it should insert decimal points into Fixed point Number fields. If you ans wer yes, DataEase adds the decimal point when importing the data. If you answer no, DataEase does not insert decimals although it does import decimal points tha t exist in the source file. IMPORT SCREEN MESSAGES Once you have answered all the Import Specification port or selected Run Defined Import from the Import ry and name of the import, the data import begins. r of each record being imported is displayed in the ed record modifies (overwrites) an existing record, n modifies m where n is the number of the source file record, and m is the number of the dest ination form record that is being updated. During an import, if any source file records are placed in an Exception file and are not imported, the message reads: n discarded where n is the number of the record that was not imported. When all the eligible records have been imported, the message summarizes the res ults of the import as follows: n added, m updated, p discarded where n is the number of records added to the destination form, m is the number of records updated (overwritten), and p is the number of records discarded (not imported). EXCEPTION FILES DataEase performs all required value checks on the data imported from a source f ile. If a source file value does not conform to the target form definition, the record is imported into the destination form, but the invalid field value is di scarded. When imported records do not conform to the target form definition or the matchi ng records section of the Import Specification, DataEase lists the record in an Exception file. The Exception file contains the record number of each problem re cord as recorded in both the source file and the destination form. During an import, when an Exception file is created DataEase notifies you with t he following message: questions for a One- time Im menu and entered the directo During the import, the numbe message area. If the import the message reads: fields than your target form, you can complete temporary form. Define the intermediate form and order of the source data form and then imp to the intermediate form.

Errors written to file FORMNAME.ENN An Exception file always has the same name as the destination form, and an exten sion beginning with the letter E. The NN portion of the filename extension is a hexadecimal number from 1 to 255 (see below). To view an Exception file, use t he following procedure: 1. Select Option 4, DOS Functions, from the Database Maintenance menu. 2. Select Option 6, Other, from the DOS Functions menu. 3. To view the file on the screen, issue the DOS command: TYPE FORMNAME .ENN To print the contents of the file, issue the DOS command: COPY FORMNAME.ENN LPT1: DataEase creates up to 255 Exception files for each database form. DataEase alwa ys assigns the lowest number available each time it creates a new Exception file . If you haven't deleted any exception files, the most recent Exception file is the highest numbered file with the same name as the destination form. Once you have deleted any of the Exception files for a particular form, the most recent file is usually not the highest numbered file.