Included Data

It is possible to migrate only the following information to the QTRACS/400 databases using this utility. Note that only the 'major' data elements are migrated.

QTRACS Simple Entities:

• Users
• Vehicles
• Vehicle Message Groups

QTRACS Complex Entities (groupings of simple entities):

• Address Lists
• Vehicle Coverage Lists

Macro Template Information

• Forward Macro Templates
• Return Macro Templates

Message Information

Position History Information

Import Utility Characteristics

1. Duplicate import data will not supersede existing data. Any duplicate data contained in the import shall be kicked-out to the exceptions file.
2. The import utility performs data validation where necessary. For instance, the importation of message data requires that the message information (sender, addressees, macro number, etc.) be valid in the current QTRACS context. Sender and addressee entities must already exist. Macro templates must already exist.
3. The import utility generates an exception file containing a copy of every record that was rejected during importation. The utility will fill in the transfer reason code (XFREASON) field for all rejected records. After resolving the reason for the rejection, and editing the exceptions file so that the data is correct, the exceptions file may be reprocessed via the very same import utility.
4. The import utility produces a spooled audit log showing a summary of the import activity. This log will be found in the same location that all spooled files are sent for the user running the utility. The log will show up only after the utility has completed running.
5. The utility will run only in batch mode.

OmniTRACS Account Issues

Certain QTRACS data is specific to the OmniTRACS Account. This means that there is data within QTRACS that is synchronized with data within the NMC. Examples of this data are vehicle group numbers and macro template definitions.

The data import utility was designed to support the migration of data into a new OmniTRACS account only.

This scenario involves the creation of a new OmniTRACS account into which existing QTRACS information (ideally from another platform or from another account) will be migrated. This also involves the transfer of vehicles from one account to another at the NMC. Two accounts will exist simultaneously.

The data import utility does not support the migration of data from an existing OmniTRACS account into the same OmniTRACS account. This scenario implies a one-shot migration from one platform to another in which the same OmniTRACS account will be used. All migration will be treated as if data was going to a new account. This means that the initial QTRACS/400 installation will be performed using standard methods. Data imported into the account will be treated as new information.

Invoking the QTRACS Data Import Utility

Before import can begin, data to be imported must first be placed on the target AS/400. All import data must be placed in a uniquely named member within the OMIMPORT file in the data library (OMNIDATA). The import file is a physical file (PF) with a single field of length 3000. This length accommodates the largest record format.

Using a standard QTRACS library list type the command OMIMPORT and press the F4 key to prompt. You will be asked to specify the name of the member in the OMIMPORT file containing the data that you wish to import to QTRACS/400. You will also be asked to specify the name of an exception file (a member of OMIMPORT) which will contain a log of all the records which did not get imported successfully. Note that the input member must exist, and the exception member must not exist, because it will be created during import.

After the import is complete, all exception file records will contain a reason code in the first four characters. This reason code corresponds to a message ID in the message file OMIMPDTAM. Append the letters "IMP" to the four character reason code, and find the corresponding message ID in the message file to determine what went wrong with the import of each particular record.

The exception file can be "reprocessed". Edit the exception file, fix the errors in the data, and save the exception file. You can then run the data import utility again, using the exception file as input, and naming a second exception file to contain any errors for this iteration. This process can be repeated until all errors have been removed from the input data.

Make sure that your OmniTRACS job subsystem (usually "QUALCOMM") is up and running when you invoke the data import utility. A connection with the HUB should be active when the importer runs, so that definitions of vehicles and vehicle message groups can be transmitted immediately to the HUB.

Import File Record Formats

The data import utility demands that the import files adhere to the following file-type and data-type rules.

When writing the non-AS/400-based export utilities, one must consider what transfer mechanism will be used to get the file to the AS/400. For instance, if the transferring mechanism is FTP, which handles ASCII to EBCDIC conversion, then the export utilities need not necessarily generate EBCDIC.

The bottom line is that regardless of how the import files arrive on the AS/400, they must adhere to the following specifications prior to being processed by the import utilities.

Data Types

Import data must be specified via the following data types only.

Note: All distances will be assumed to be in miles, not kilometers. The export utility must convert to miles if the source units are kilometers.

Optional Fields

Certain fields in the import record are required in order for the import to succeed. Required fields are marked with a in the following record definitions. The export utility must supply a valid value for every field in the record that is tagged as required. Optional fields are fields that are not required in order for the import to be successful. Character fields that are not included should be set to all blanks . Numeric fields that are not included should be set to blanks as well . A blank is defined as an EBCDIC space (hex 40).

Order of Definition

The order of the records in the import file is very significant because of the relationships of the entities. The recommended order of definition is as follows:

1. Users
2. Address Lists
3. User to Address List Associations
4. Vehicle Message Groups
5. Vehicles
6. Return Macros
7. Forward Macros
8. Messages
9. Position History
10. Drivers

Failure to follow this sequence could result in the rejection of huge amounts of import data.

QTRACS Import File Record Formats

In order to import the various types of entities to the QTRACS database, the import file can have several different types of record formats, each conveying information about a different type of entity.

All import records begin with the following fields:

User Entity Import Record Format

The following table describes the User Entity import record. This record causes a new user entity to be added to the QTRACS database.

Note that not all of the fields defined in this input format are required. The optional fields will be replaced with data from the QTRACS Default User record when importing user data. Therefore, it is important that your QTRACS Default User record be set up to your specifications before beginning the user import.

User Capability Flags

The following table describes the user capability flags. Each flag occupies a single bit in the user import record. Set the bit off (0) to indicate that the user should not be granted the capability. Set the bit on (1) to indicate that the user should be granted the capability.