Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : DBSMIMP.ZIP
Filename : DBSMIMP.DOC

Structure Import Utility
------------------------
Version 2.0

by

Progressive Data Systems

P.O. Box 631
Middleton, WI 53562
Phone (608) 836-5075

































Copyright 1989 Progressive Data Systems. All rights are reserved.
This manual may not be transcribed, reproduced, or translated into any
natural language or computer language in whole or in part, by any means
or in any form without the prior written permission of a duly authorized
representative of Progressive Data Systems in Middleton, Wisconsin.

Page i

Structure Import Utility, Version 2.0

Limited Warranty and Liability
------------------------------

Progressive Data Systems is not responsible for your specific
application or any problems resulting from use of this software.
Progressive Data Systems has no liability to you or any other person or
entity for any lost profit, lost savings, loss of goodwill, or damage
including special, consequential, or incidental damages caused either
directly or indirectly by the use or inability to use this software,
or for any claim by any other party. Some states do not allow the
limitation or exclusion of liability for consequential or incidental
damages, so the above limitation or exclusion may not apply to you.

THE FOREGOING WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES AND
CONDITIONS EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THOSE
CONCERNING MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
Progressive Data Systems DOES NOT WARRANT THAT THE SOFTWARE WILL MEET
YOUR REQUIREMENTS OR THAT THE OPERATION OF THE SOFTWARE WILL BE
UNINTERRUPTED OR ERROR FREE. ALL RISK CONCERNING THE PERFORMANCE AND
QUALITY OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
DEFECTIVE, YOU (AND NOT Progressive Data Systems) ASSUME THE ENTIRE
COST OF ALL NECESSARY CORRECTION, REPAIR, OR SERVICING.

This agreement is governed by the laws of the State of Wisconsin. If
any part of this agreement is invalidated, the remainder of the
agreement will remain in effect. You acknowledge that you agree to
be bound by the terms and conditions of this agreement. Your use of
this software constitutes your acceptance of the limited warranty and
license agreement.

_______
____|__ | (tm)
--| | |-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
-----| | |---------------------
|___|___| MEMBER


The Association of Shareware Professionals is dedicated to
strengthening the future of shareware as an alternative to commercial
software.


Trademark Acknowledgements
--------------------------

CLIPPER is a trademark of Nantucket Corporation.
dBASE, dBASE III, dBASE III PLUS, and dBASE IV are trademarks of
Ashton-Tate, Inc.
DESQview is a registered trademark of Quarterdeck Office Systems.
FoxBase is a registered trademark of Fox Software, Inc.
NANTUCKET is a registered trademark of Nantucket Corporation.

Page ii

Structure Import Utility, Version 2.0

Limited Software License
------------------------

Structure Import Utility is copyrighted.
Copyright 1989 Progressive Data Systems.

The Structure Import Utility is NOT public domain software, nor is it
free (or freeware). Non-registered users are granted a limited
license to use the Structure Import Utility software for a limited
time to determine whether it meets their operating needs and
requirements. This limited license is provided for the sole purpose
of allowing non-registered users to evaluate the Structure Import
Utility software. Continued use of the Structure Import Utility
software requires a valid software license agreement with Progressive
Data Systems. Your use of this software constitutes your acceptance
of the limited warranty and license agreement. The license is
terminated if you fail to comply with any term or condition of this
license agreement.

This limited license is for a single copy of the Structure Import
Utility software and has been granted by Progressive Data Systems
with their mailing address at Post Office Box 631, Middleton,
Wisconsin 53562. The Structure Import Utility software is not sold.
It may be licensed to you for your personal use on any one computer.
The Structure Import Utility is licensed in combination with the
DataBase Structure Manager. (Please refer to Appendix D of the
DataBase Structure Manager documentation for registration
information.)

Copies of this software may be made for trial use and short-term
evaluation by others on a non-commercial basis. You may not charge
anything for the Structure Import Utility software. The only
exception to this is a cost-based fee (not to exceed the equivalent
of fifteen dollars in U.S. currency) to cover distribution costs.
The full set of programs and documentation must be included with
any distributed copies.

You may not modify Structure Import Utility or distribute this
software in a modified form. The modification prohibition includes,
but is not limited to, reverse engineering, disassembling and
decompiling.

You may not distribute this software in combination with any other
service or product, or as a part of an institutionally or
corporate-sponsored distribution. Bundling agreements and site
licenses may be negotiated with Progressive Data Systems.

The documentation provided here may change at any time without notice.
Information presented in this documentation is not a representation of
any form of commitment by Progressive Data Systems. Progressive Data
Systems does not assume responsibility for the use of the
documentation, nor for any patent infringements or other rights of
third parties who may use the documentation.


Page iii

Structure Import Utility, Version 2.0

Table of Contents
-----------------

Limited Warranty and Liability........................... i
Assoc. of Shareware Professionals Membership............. i
Trademark Acknowledgements............................... i
Limited Software License................................. ii
Table of Contents........................................ iii
Introduction............................................. 1
Technical Support........................................ 1
Features Summary......................................... 2
Urgent Information
Structure Import Utility System Files.................. 3
Unique Data Field Names................................ 4
Memory Requirements.................................... 4
Insufficient Memory Error Message...................... 5
Multi-Tasking.......................................... 5
External Program Execution............................. 5
dBASE IV Database File Format.......................... 5
System Configuration
Hardware Requirements.................................. 6
Software Requirements.................................. 6
Runtime Environment Settings........................... 6
Memory Allocation and Use............................ 6
Snow Elimination..................................... 8
Recommended Runtime Settings......................... 9
Enabling DOS Command Execution....................... 9
Network File Control..................................... 10
Technical Specifications
Maximum Database Specifications........................ 11
Corrupted Databases.................................... 11
Installation............................................. 12
System Startup
Database System Application Directory.................. 12
Command Line Parameters................................ 12
First-Time Operation................................... 12
Hard Drive Operation................................... 12
Diskette Drive Operation............................... 13
DOS Command Execution.................................... 13
Database Structure Imports
General Information.................................... 14
Database Directory..................................... 14
Import Database Structure Information.................. 14
Report Output Options................................ 14
Import Report Format................................. 15
Dictionary Consistency Validation.................... 15
Pre-defined Database Dictionary Entries.............. 16
Insufficient System Memory........................... 17
Corrupt Databases.................................... 17
Import All Databases................................. 18
Import A Single Database............................. 18
Delete All Database Dictionary Information............. 18
Utility Menu............................................. 19
Usage Hints.............................................. 19
Index.................................................... 20

Page 1

Structure Import Utility, Version 2.0

Introduction
------------

The Structure Import Utility is a database system development tool
designed to be used in conjunction with the DataBase Structure Manager.
It is specifically designed to import dBASE III PLUS, FoxBase, and
Clipper-compatible databases into the DataBase Structure Manager's
database dictionary.

When importing database structure information, data field definitions
are checked to ensure they are consistent with all existing data fields
defined in the database dictionary. Data field definitions are not
checked during import to ensure compliance with the database type
specified in the Configuration Settings. However, before a new
database structure may be generated by the DataBase Structure Manager,
the database structure specifications are checked to ensure they comply
with the specific type of database being generated.

Data field names must be unique across all databases in the entire
database system. For example, there can only be one data field named
"VENDORID." It can occur in as many databases as required, but there
cannot be any conflicting data field definitions.

An import report is produced for every import operation. It will be
displayed on the screen. There are options to print the report and to
retain a copy of the report with the database descriptions.

(Only information specific to the Structure Import Utility is provided
in this documentation. For all other information, please refer to the
DataBase Structure Manager documentation.)



Technical Support
-----------------

Technical support for registered users is provided for a period of one
year beginning on the first day of registration. The technical support
is available Monday through Friday from 9:00 AM to 5:00 PM (Central
Standard Time). Please use the documentation provided to solve any
problems before requesting technical support and have the following
information available when you call Progressive Data Systems for
technical support at (608) 836-5075:

1. DBSM license registration number.
2. DBSMIMP version.
3. DOS version.
4. CONFIG.SYS and AUTOEXEC.BAT file contents.
5. Available system memory before executing the DBSMIMP program
as reported by the DOS CHKDSK command.

Do not be deterred from requesting technical assistance if you
cannot determine all of the above information. If you are at your
computer when you call, we should be able to work together to gather
the necessary information.

Page 2

Features Summary
----------------
Import Database Structure Information
-------------------------------------
Database structure information may be imported into the DataBase
Structure Manager's database dictionary. Database structures are
identified for import individually or as the group of all databases
in the current directory.


Database Directory
------------------
Report all databases in the current directory. The report includes
the normal file directory information, and the following database
specific information: number of records, number of data fields, and
record length. It is also reported whether the database has a
corresponding database in the dictionary.


Delete All Dictionary Information
---------------------------------
All database dictionary information may be deleted in a single
command. (Appropriate measures are taken to ensure this option is
not accidently initiated.)


Supports Clipper's Very Large Character Fields
----------------------------------------------
Clipper's support for very large character field specifications (up
to 32K) is maintained in a transparent manner. Character data field
lengths are maintained in a single length specification.


Page 3

Urgent Information
------------------
Structure Import Utility System Files
-------------------------------------
USER BEWARE - Your database files may be in jeopardy. All Structure
Import Utility system files are assumed to be under the exclusive
control of the Structure Import Utility program. The DBSMIMP system
files include the dictionary databases, their associated index files
and memo databases, and some temporary files. The program assumes
that it may delete and create these files as needed. Before using
the Structure Import Utility, please ensure that there will not be
any conflicts in the directory in which it will operate.

The file names used by this system have been specifically chosen to
avoid conflicts with most file names. Every file name used by this
system except for the executable files, will begin with a dash, "-"
and has an underscore character, "_", in the fourth position. (For
those of you who are versed in wildcard pattern matching, the pattern
is "-???_*.*".) If you have any files matching this pattern in the
directories where this program will be working, you should examine
the list of system files below for conflicts. If there is a
conflict, you will need to change your file names or refrain from
using this system in the directory with the conflicting names.
Otherwise, you risk having your files deleted and this system will
not operate correctly. You are responsible for ensuring file
compatibility. If you have ANY doubts or are using this system for
the first time, I encourage you to install this system in a
temporary directory and place a COPY of the databases from one of
your systems into it. (Do not simply move the originals into the
temporary directory.) Get to know this system before maintaining
"live" database information.

The names of the system files are as follows:


Databases and Associated Memo Databases
-----------------------------------------------------
-DAT_DCT.DBF Data Field Definitions
-FIL_FLD.DBF Database Data Field Members
-FIL_MST.DBF Configuration Information
-FIL_MST.DBT Configuration Information Memo Database
-FIL_NAM.DBF Database Descriptions
-FIL_NAM.DBT Database Descriptions Memo Database
-FIL_NDX.DBF Index File Specifications

Index Files Temporary Files
------------ ---------------
-CAT_NAM.NTX -TMP_1.DBF
-DAT_FLD.NTX -TMP_1.DBT
-FIL_DSC.NTX -TMP_1.NTX
-FIL_FLD.NTX
-FIL_NAM.NTX
-FIL_NDX.NTX
-FLD_NAM.NTX


Page 4

Urgent Information
------------------
Structure Import Utility System Files (Cont'd)
----------------------------------------------
If you have any doubts about file name conflicts, before
executing this program, execute the following wildcard DOS directory
command in the directory where you expect to work:

DIR -???_*.*

Any files matching the wildcard pattern will be displayed. If the
directory display returns any of your file names, then you should
compare these files individually with the system files listed above
to ensure there is no actual file name conflict.


Unique Data Field Names
-----------------------
Data field names must be unique across all databases in the database
dictionary. For example, there can only be one data field named
"VENDORID" in the database dictionary. It can occur in as many
databases as required. This requirement will ensure a consistent
definition in every database where it occurs.


Memory Requirements
-------------------
The DBSMIMP requires a significant amount of memory to run. The
DBSMIMP will look for the runtime setting "DBSMIMP=V007;..."
character string in the DOS environment to determine how it will
allocate and use different portions of memory when it loads. It is
strongly suggested that the runtime setting be established before
attempting to run the DBSMIMP. The runtime setting may be created
using the DOS SET command.

For a quick start, the following runtime setting should be
sufficient for most systems:

set DBSMIMP=V007;R000

This command is case-sensitive. Where upper-case letters are
indicated, upper-case letters must be used. For more information,
please refer to the system configuration runtime environment
settings description.

The exact amount of memory required for any structure import will
depend on the size of the structure being imported and the size of
the import report (if a copy the import report is being retained
with the database description).

In order to allow the "Run DOS" command feature to be executed, the
"R000" specification needs to be changed to "R026".


Page 5

Urgent Information
------------------
Insufficient Memory Error Message
---------------------------------
An insufficient memory error message will be displayed in the
top line of your screen if there is not enough free memory available
to complete an operation. Please refer to the Import Database
Structure Information documentation for more information.

Multi-Tasking
-------------
Do not run multiple copies of DBSMIMP in a multi-tasking environment
(ie. DESQview, etc.) in the same directory. DBSMIMP uses standard
temporary file names which could easily be mixed up when running
multiple copies of the DBSMIMP. For the same reason, simultaneous
use of DBSMIMP and DBSM in the same directory should also be
avoided.

External Program Execution
--------------------------
DOS commands may be initiated from most menus by pressing "F3".
However, running a DOS command is risky. It is risky in the sense
that the DBSMIMP system may abnormally terminate if the system
memory is not well-ordered. Abnormal termination is not normally
detrimental to any files, but it is inconvenient. For more
information, refer to the "DOS Command Execution" documentation
section in the DBSM documentation.

dBASE IV Database File Format
-----------------------------
dBASE IV databases without memo or floating point data types are
compatible with the DBSM system. They will be treated the same as
the earlier Dbase database file format.

The full dBASE IV file format is not supported by the DBSM system.
Any Dbase databases with memo fields that have been accessed or
created by dBASE IV are currently interpreted by the DBSM system as
corrupt database files. Corrupt databases may not be imported using
the Structure Import Utility.


The databases with memo fields that have been USE-d or created by
dBASE IV are interpreted as corrupt because dBASE IV uses a new code
in the first byte of the database to indicate there is an "associa-
ted memo file." Dbase dialects prior to dBASE IV, use the hexadeci-
mal value "83" in the first byte of a database to indicate an
associated memo file. dBASE IV uses a different value, hexadecimal
value "8B", in the same position of the database file (ie., first
byte) to indicate an associated memo file. If a database with any
memo fields is USE-d by dBASE IV, it will set the first byte of the
database header to its own format. There may be a good reason why
databases with memo fields are not backwards compatible...

The dBASE IV floating point data type is not recognized by the
DBSM system, but databases with the floating point may be imported.
The floating point data type will be interpreted as an undefined
data type, "U", with field length and decimals set to zero.
Database structures may not be generated with undefined data types.

Page 6

System Configuration
--------------------
Hardware Requirements
---------------------
Minimum 512K system memory (640K suggested).

A hard disk is recommended for best operating performance. Floppy
disk-based systems may be used.


Software Requirements
---------------------
* DOS 2.0 or higher (DOS 3.1 or higher for network file control).

* CONFIG.SYS
The following are minimum specifications for the FILES and
BUFFERS parameters in the CONFIG.SYS file:

1) BUFFERS=8
2) FILES=19

* DBSMIMP (version 2.0) is designed to import database structure
information into any version 2.x DBSM dictionary databases.

* Memory Usage
The amount of system memory the DBSMIMP requires to run will vary
substantially depending on the number of databases recognized in
the current subdirectory, the size of the database structure being
imported, and the import report output options selected. The
option allowing a copy of the import report to be retained with
the database description may require a significant amount of
system memory if the import report is very large.

The DBSMIMP can easily require a minimum of 390K (399,360)
bytes of RAM when all of the load factors are elevated.
See Memory Allocation and Use for more information.


Runtime Environment Settings
----------------------------
* Memory Allocation and Use

Memory allocation and use may be controlled in three different
categories - memory variables, index buffers/external program
execution, and expanded memory (LIM 3.2). The amount of memory
allocated for each category may be tailored (except for memory
variable memory allocation) to meet your specific usage
requirements and hardware/software configuration.


Page 7

System Configuration
--------------------
Runtime Environment Settings (Cont'd)
-------------------------------------
* Memory Allocation and Use (Cont'd)

DBSMIMP.EXE will search for the "DBSMIMP" specification in the DOS
environment. The method for designating the memory allocation is
through the use of the DOS SET command. The DOS SET command for
the "DBSMIMP" specification is as follows:

set DBSMIMP=V007[;Rnnn][;Ennn][;S1]
Where:
V007 = Memory variable memory allocation.
Rnnn = External program execution and
index buffer allocation.
Ennn = Expanded memory allocation for
index buffers.
S1 = "Snow" elimination.

This command is case-sensitive. Where upper-case letters are
indicated, upper-case letters must be used. The runtime settings
are the same settings as defined for Nantucket's Clipper (Summer '87)
runtime settings (ie., set CLIPPER=...). The documentation provided
with Clipper (Summer '87) may be useful if a further description
of the "set DBSMIMP=" settings is necessary.

* Memory Allocation and Use

1. Memory Variable Memory Allocation

Memory variable memory allocation should always be "V007" to
ensure there is sufficient memory available for all memory
variables required.

2. External Program Execution/Index Buffers Allocation

The optional "Rnnn" parameter indicates memory space (in 1024
byte units) to be allocated for index buffers and external
program execution. If the "Ennn" parameter is specified, this
parameter will be used solely to allocate memory for external
program execution. This parameter is optional, but it is
suggested that a value be determined to ensure that memory is
efficiently allocated in a manner that best suits your specific
needs. (Please refer to the documentation "Enabling DOS
Command Execution" for further information on running external
programs.)

The "Rnnn" value is only evaluated at the time the program is
loaded. At that time, the load process will attempt to provide
the amount of memory requested in the "Rnnn" parameter for the
external program execution/index buffering. All memory
allocated to this area will not be available for loading the
main program code and data. If there is insufficient memory
left for the program code and data after allocating memory
according to the "Rnnn" value, the program will terminate with
the message "Not enough memory".

Page 8

System Configuration
--------------------
Runtime Environment Settings (Cont'd)
-------------------------------------
* Memory Allocation and Use (Cont'd)

If you do not intend to run external programs from inside the
Structure Import Utility, you should set the "Rnnn" parameter
value to zero (ie., "R000") to free up the maximum amount of
memory for program data manipulation.

If external programs are to be run, the minimum "Rnnn" value
must be at least 26K bytes (ie., "R026"). This minimum value
will allow the running of DOS internal commands (COPY, DIR,
etc.) and external programs up to approximately 8K in size. If
this runtime setting is specified, the amount of RAM required
to load the DBSMIMP will increase in direct correspondence to
the increase in the "Rnnn" setting. Running larger external
programs will require a corresponding increase in the "Rnnn"
parameter value and an increase in the minimum amount of RAM
required to load DBSMIMP.

If no "Rnnn" parameter value is set in the "set DBSMIMP=..."
statement, a default value will be calculated at load time.
The default value supplied for this parameter is dynamically
determined as a percentage of free memory available at the time
the DBSMIMP program is loaded and executed.

3. Expanded Memory for Index Buffers

The optional "Ennn" parameter identifies expanded memory space
(in 1024 bytes units) to be used for index file buffers. The
expanded memory must conform to the LIM 3.2 specification. If
this parameter is supplied, the minimum value is "E016" which
represents 16k bytes.


* Snow Elimination

The optional "S1" parameter specification will eliminate "snow"
in the screen display. If you use this parameter to eliminate
"snow", the display will be cleaner, but the display will
operate a little bit slower.


Page 9

System Configuration
--------------------
Runtime Environment Settings (Cont'd)
-------------------------------------
* Recommended Runtime Settings

The recommended setting for providing the greatest amount of
free memory for dynamic program allocation and thereby allowing
the largest database structures to be imported is as follows:

set DBSMIMP=V007;R000

The above setting does not allow any external programs to be
run, but there will be sufficient memory made available for
index buffers.

The recommended setting for allowing the minimum external
program execution and still providing a large amount of free
memory for dynamic program allocation is as follows:

set DBSMIMP=V007;R026

Both of the above settings assume there is no expanded memory
available for indexing operations.


* Enabling DOS Command Execution

There are 3 requirements that must be met before external programs
may be executed from within the Structure Import Utility. (The
"Run DOS" command may be initiated by entering "F3" at any menu.)

First, there is a minimum system memory requirement needed to run
external programs. Before loading the program there must be at
least 370K (378,880) bytes of RAM available if any significant
operations are going to be accomplished besides running external
programs. You may determine the amount of memory available using
the DOS CHKDSK command.

Secondly, the "Rnnn" parameter of the runtime environment settings
must be at least 26K (ie. SET DBSMIMP=V007;R026). See the earlier
description of Runtime Environment Settings for more information.

The last requirement is that the DOS command processor
(COMMAND.COM) location must be specified in the DOS environment.
This is required even if COMMAND.COM resides in the same directory
where the DataBase Structure Manger will be run. The DOS SET
command may be used for this purpose. To specify the command
processor location, use the following SET command syntax:

set COMSPEC=[d:][\]\COMMAND.COM
Where:
[d:] Optional disk drive specification.
[\] Optional directory path to COMMAND.COM

For more information regarding the DOS SET command please refer to
your DOS manual.

Page 10


Network File Control
--------------------

DBSMIMP has the ability to coordinate network file access only with
those programs using the same network file-locking procedures as
Nantucket's Clipper-compiled programs. dBASE III PLUS network
file-locking procedures are NOT compatible with Clipper's methods.
Clipper (Summer '87 version) uses the DOS 3.1 RLOCK command in an
unconventional manner.

The network file control operates in two different areas. First,
it controls the Structure Import Utility use so that only one user
is allowed to run it or DBSM in the same directory at the same time.
Essentially, this eliminates the need to personally coordinate with
other developers who may periodically need to make changes in the
same database dictionary. If a user does attempt to run DBSM or
DBSMIMP in a directory where either of these programs is already in
use, one of the following messages and prompt will be displayed:

File "-FIL_MST.DBF" is in use. Retry, Wait up to 2 min., or Exit?

or

File "-FIL_NDX.DBF" is in use. Retry, Wait up to 2 min., or Exit?

The new user will have three options. The new user may retry, wait
up to 2 minutes for the current user to exit, or exit the program.
If the second message is issued (ie., the message containing the
reference to the "-FIL_NDX.DBF" file), the new user should exit
their attempt to run DBSM or DBSMIMP.

The second area of file control concerns the application database
files which may need to be accessed by DBSMIMP to gain information
about the database. If a database is locked by another program
before the database import procedure can access it, the database
will not be imported. If a database has been accessed in "shared"
mode by another program, the database may still be imported. This
applies even if the other program has set a record lock.


,---------------------,
***********************| Special Emphasis! |***********************
`---------------------'

Any file/record-locking and checks for file/record locks must comply
with Nantucket's Clipper-compiled file/record-locking techniques to
facilitate coordinated network file access control with the DBSMIMP.

File/record-locking methods that are not compatible may cause
unpredictable results. If you are not sure about other program's
file/record-locking compatibility with Clipper's techniques, do not
rely on the DBSMIMP's network file control features to eliminate
network file access contention between programs.


Page 11

Technical Specifications
------------------------
Maximum Database Specifications
-------------------------------
The maximum database that may be imported is as follows:

Database record length......: 32,766
Number of database fields...: 1,024
Character field length......: 32,766
Numeric field length........: 20
Decimals field length.......: 18
Index key expression length.: 250
Index key expression fields.: 42

The amount of available system memory may be exceeded prior to
reaching any of these maximum specifications. If a database
structure specification exceeds the maximum dBASE III PLUS database
specifications, Nantucket Clipper (Summer '87 version) conventions
will be used in interpeting and maintaining the database structure.

The database record length values reported by this system are
calculated by summing the length of all data fields in the database.
The 1-byte position in databases for the delete status is not
included in the record length.


Corrupted Databases
-------------------
Some procedures test for the presence of a valid database. A
database is considered corrupt if some of the database header infor-
mation is incorrect. This includes the case where an associated
memo database has been designated in the database header informa-
tion, but no associated memo database is found with the database.
Some dBASE IV database file formats are also interpreted as corrupt
databases (See page 5 for more information). Operations which
detect the invalid databases will provide a message and will either
abandon the current operation or, if possible, continue without it.


Page 12

Installation
------------

The DBSMIMP installation procedure instructions are included with the
DBSM installation documentation.


System Startup
--------------

Database System Application Directory
-------------------------------------
The Structure Import Utility must execute in the same directory
where the DataBase Structure Manger dictionary files reside in
order to import database structure information into them. If the
configuration master file, "-FIL_MST.DBF", is not found in the
current directory, the load process will halt and a prompt message
will be issued to determine if you wish to continue. Choosing not
to continue will allow you to investigate the "missing" files
situation rather than allowing the Structure Import Utility to
continue and generate any missing files.

To facilitate importing databases from outside the current
directory, a search path specification may be entered when
individually importing databases. If the search path is specified,
the database will first be searched for in the current directory.
If it is not found, the search path will be used.


Command Line Parameters
-----------------------
The command line parameters specifications are detailed in the
DBSM documentation.


First-Time Operation
--------------------
Any time DBSMIMP is loaded and it does not find its system files, it
will regenerate them. If the configuration file is generated, the
Configuration Settings procedure will be initiated before proceeding
to the main menu. (Refer to Configuration Settings in the
DataBase Structure Manager documentation for more information.)


Hard Drive Operation
--------------------
If the database structure information is to be imported into
existing DBSM dictionary files, DBSMIMP must be run in the directory
where the DataBase Structure Manager's dictionary databases reside
(if they have been created).


Page 13

System Startup
--------------
Diskette Drive Operation
------------------------
DBSMIMP will operate from a diskette drive. The "/F" command line
parameter must be used to pause the startup procedure to allow the
system disk to be replaced by the applications database disk.

To load DBSMIMP from drive A:, place a diskette with the DBSMIMP.EXE
file in drive A:, make drive A: the current drive (if necessary),
and enter the following command at the DOS prompt:

DBSMIMP /F

The program will begin to load and execute. Shortly, a message will
appear asking you to remove the diskette from the drive and put the
data disk in place of it. The data disk should contain the DBSM
system dictionary files and/or the application database files in the
root directory if they have been created. If they have not been
created, place a formatted diskette which you intend to use for the
data dictionary information into the diskette drive. Once the
diskettes have been exchanged, press Enter to continue. The main
menu will then be displayed.


DOS Command Execution
---------------------
Running a DOS command is risky. It is risky in the sense that the
DBSMIMP system may abnormally terminate if the system memory is not
well-ordered. Abnormal termination is not normally detrimental to
any files, but it is inconvenient since the program must be re-
loaded. The DBSMIMP system code is not rugged enough to
consistently correctly manage the system memory under anything less
than good conditions. Conditions are most favorable to run DOS
commands before extended DBSMIMP use has occurred. With the above
in mind....

A DOS command may be executed by pressing "F3" at any menu. This
option is only available if the "Rnnn" parameter of the DBSMIMP
runtime environment setting has been properly set. (Please refer to
"Enabling DOS Command Execution" for more information.)

After the first command has been executed, subsequent calls will
will allow the previous command to be recalled to the command line
by pressing the "F3" function key.

Please refer to the "DOS Command Execution" documentation section in
the DBSM documentation for a more complete description of possible
error conditions.


Page 14

Database Structure Imports
--------------------------
General Information
-------------------
The Structure Import Utility's ability to recognize database files
is determined by two specifications in the Configuration Settings.
The most critical configuration specification is the Universal
Database File Name Suffix setting (usually "DBF"). It identifies
database files by their file name suffix. Only those files with
suffixes matching the Universal Database File Name Suffix will be
recognized.

The other configuration setting for database recognition is the
"Include DBSM's databases?" setting. When the DBSM system files are
not included, the DBSM system files will not be recognized by the
Database Directory operation or the Import All Databases operation.
(See page 3 for a list of DBSM system files.)


Database Directory
------------------
Report all databases in the current directory. The report includes
the normal file directory information, and the following database
specific information: number of records, number of data fields, and
record length. It is also reported whether the database has a
corresponding database description in the dictionary. As noted
earlier, the databases included in this report will depend on the
configuration settings. Corrupt databases will be noted. Please
see pages 5 and 11 for a description of a corrupt database.


Import Database Structure Information
-------------------------------------
Database structure information may be imported into the DataBase
Structure Manager's database dictionary by individually specifying
each database or by requesting the entire group of databases in the
current directory.

The database structure import process will load up the database
dictionary with the essential database specifications (data field
name, type, length, and decimals). When a data field dictionary

entry is added, it will have a default value of "a" assigned to the
Sequence Code. This particular value was chosen to place the data
field in the middle of the ASCII sort order. From there, the data
field's order may be conveniently changed up or down in the ASCII
sort order.


* Report Output Options

Any import request will issue prompts to determine the production
of three possible types of import report output. The first report
option is to produce a copy of the import report that is retained
with the database description information to allow convenient
future reference. The retained copy may be viewed, written to
disk, or printed by using DataBase Structure Manager operations
provided in the Database Descriptions Maintenance.

Page 15

Database Structure Imports
--------------------------
Import Database Structure Information (Cont'd)
----------------------------------------------
* Report Output Options (Cont'd)

The second type of import report is to produce a copy of the
import report on disk. If the disk file option is selected, a
prompt will be issued for each database imported to determine the
disk file name. If the disk file name is left blank, a default
file name will be used. The default file name is constructed by
using the database file name plus a ".TXT" file name suffix.

The last import report output option is to produce a printed copy.
If a printed copy is requested, an additional prompt will be
presented to determine if the printer should be set to near-letter
quality printing. Additionally, when the printed copy is
requested, it will force all reports to the standard printer form
length.


* Import Report Format

The import report is divided into two sections. The first section
is a listing of the database structure's data fields. Each data
field is listed one per line. Each line includes the four
essential data field specifications (data field name, type,
length, and decimals) with a space provided for data field
comments. When a printed report is produced, the data field
comments area may be used to gather data field information
"offline."

The second section produced will specify the results of the import
process. The report usually operates in the exception mode by
reporting any data fields which could not be accepted into the
data dictionary. However, if a database is being imported into
the data dictionary and there is an existing dictionary entry for
the database, the report will detail all new data fields being
added to the data dictionary. In either case, a summary of the
data fields imported into the dictionary will be produced.


* Dictionary Consistency Validation

Under no circumstances will the DBSM system allow two separate
data fields to be defined with similar data field names. Separate
data field definitions require unique data field names. This
means that data field names must be unique across all databases in
the database dictionary. For example, there can only be one data
field named "VENDORID" in the data field dictionary. It can
belong to as many databases as required.


Page 16

Database Structure Imports
--------------------------
Import Database Structure Information (Cont'd)
----------------------------------------------
* Dictionary Consistency Validation (Cont'd)

The exception report will list data fields which are inconsistent
with existing data fields in the dictionary. If a data field
named "VENDORID" exists in the dictionary with a character data
type definition and a data field with the same name is specified
to be imported, but it has a numeric data type, the numeric data
field is inconsistent. Any data field definitions found to be
inconsistent with existing database dictionary entries will not be
added to the dictionary. The exception report will list the
inconsistency and specify the type of inconsistency (ie., data
type, length, or decimals).

The inconsistent data fields not added to the dictionary must be
manually added to the data dictionary after resolving the
inconsistency. For the above example where the numeric data type
was inconsistent, the resolution may be as simple as going to the
Data Field Maintenance and assigning the "VENDORID" data field
with the "correct" character data type to the newly imported
database. (This, of course, assumes that the data field should be
a character data type.)

If the same data field name is used in separate databases with
different data type, length or decimals specifications, one of the
data field names will have to be changed if the differing
definitions are to be maintained by the DBSM system.


* Pre-Defined Database Dictionary Entries

If database structure information is imported into the dictionary
for a database already in the dictionary, any data fields added to
the database will be individually noted. If a database structure
is imported into the dictionary for a database already defined in
the data dictionary and the import database has a data field
subset of the corresponding database dictionary entry, no
dictionary changes will be made.

Data field definitions are not checked during importation to
ensure compliance with the database type specified in the
Configuration Settings.


Page 17

Database Structure Imports
--------------------------
Import Database Structure Information (Cont'd)
----------------------------------------------
* Insufficient System Memory

If there is not enough free system memory available to complete an
import operation, an insufficient memory error message will be
displayed in the top line of your screen when the system memory
is exhausted. The operation will have to be terminated by
responding "N" to the continuation prompt.

In some cases, it is possible that the import procedure correctly
imported the database structure information into the dictionary,
but the memory problem was caused by retaining a copy of the
import report in with the Database Description. The error
message associated with this condition is as follows:

Proc MEMOREAD out of memory Continue?


In cases like this, the dictionary information will be correct,
but the import report will not have been retained with the
Database Description.

An import procedure may be immediately re-run without affecting
the results of the import, but some changes will be necessary to
reduce the system memory requirements or to increase the amount of
system memory available before re-running the import.

If the size of an import report exceeds the capacity of the
database memo field assigned to hold it (64,000 bytes), the report
will not be added to the database description. An appropriate
error notification will be used in place of the import report.


* Corrupt Databases

Before proceeding with a databases structure import, the database
is tested to determine if it is a valid database structure. If
the database is determined to be corrupt, a message and prompt
will be displayed to indicate the situation. The import process
for that database will be terminated. Please refer to the
Technical Specifications documentation section for a description
of interpreting corrupt databases.


Page 18

Database Structure Imports
--------------------------
Import Database Structure Information (Cont'd)
----------------------------------------------
* Import All Databases

All databases recognized in the current directory may be indicated
for importation. As noted earlier, the databases included in
the grouping will depend on the configuration settings. Use the
Database Directory menu option to determine the databases included
in the Import All Databases group.

The responses provided from the initial prompts to determine
the type of import report output options desired will be applied
to every report produced when importing all database structures in
the directory.

Each database will have a prompt issued to determine if it should
be imported. If the database is not indicated for importation, a
prompt will be issued to determine whether to continue. If you
choose to continue, the import procedure will skip to the next
database and begin again with another prompt.


* Import A Single Database

Individual database imports allow the specification of an
additional search path which is used if the database is not found
in the current directory. The path specification follows the
DOS PATH specification syntax rules. (If you are unfamiliar with
the specification syntax, please refer to your DOS manual for more
information. See the PATH command syntax.)

When a prompt is issued for the database file name, all databases
recognized in the current directory will be displayed. The
database file name should be entered without including the file
name suffix. The Universal Database File Name Suffix (from
Configuration Settings) will be used for the suffix.

If an additional search path has been specified, the databases
from the additional search path will not be listed. This omission
will still allow the databases from the additional subdirectory
path to be entered for importation.


Delete All Dictionary Information
---------------------------------
All DBSM database dictionary information may be deleted in a single
command. (Appropriate measures are taken to ensure this option is
not accidently initiated.)


Page 19

Utility Menu
------------

The Utility Menu options are described in the DBSM documentation.



Usage Hints
-----------
Database Structure Snapshots
----------------------------
When using the DataBase Structure Manager to develop database
systems, the Structure Import Utility may be used to periodically
take "snapshots" of the database structures on disk. If the
database dictionary specifications are consistent with the database
structures on disk (Use the Structure Variance report to evaluate
consistency.), the database structures may be "imported" into the
database dictionary without causing any changes to the dictionary.
In the import process, indicate that a copy of the import report is
to be retained with the database description. This will provide the
database structure snapshot and nothing will be changed in the
database dictionary so long as the dictionary database is consistent
with the database on disk.

A particularly good time for taking the database structure snapshot
is before embarking on a significant change to the database system's
database structures. Another situation where this may be useful is
when the database system is in actual use in one directory and new
versions are being developed in another directory. When a new
release is issued to the "live" database system, a snapshot of all
database structures may be taken.


Page 20
Index
-----

Subject Subject
------------------------------------ ------------------------------------
Application Database Directory 12 Import Report Format 15
Assoc. of Shareware Professionals i Import All Databases 18
BUFFERS 6 Import Single Database 18
Command Line Parameters 12 Index 20
COMMAND.COM 9 Index Buffers Allocation 7
COMSPEC 9 Initialize Dictionary Information 18
CONFIG.SYS 6 Installation 12 (See DBSM docs.)
Consistency Validation 15-16 Insufficient Memory Error Message 17
Corrupt Databases 5, 11, 14, 17 Introduction 1
Data Field Length, Maximum 11 Limited Software License ii
Data Field Names 4, 15-16 Limited Warranty and Liability i
Database Directory 14 Maximum Database Specifications 11
Database Data Field Maximum 11 Memory Allocation 6-8
Database File Format 11 Memory Requirements 6, 17
Database Record Length 11 Memory Use 6-8
Database Technical Specifications 11 Memory Variable Memory Allocation 7
DBSMIMP System Files 3 Multi-Tasking 5
DESQview 5 Multi-User 10
Diskette Drive Operation 13 Network File Control 10
DOS Command Execution 9, 13 Operating System 6
DOS Environment Settings 4, 6-9 Order Form ii
Errors on Import 15-16 Pre-Defined Database Entries 16
Exception Report 15-16 Record-Locking 10
Expanded Memory for Index Buffers 8 Registration ii
External Program Execution 7, 9 Report Output Options 14-15
Features Summary 2 Runtime Environment Settings 6-9
File-Locking 10 Snow Elimination 8
FILES 6 Specifications, Maximum 11
First-Time Operation 12 Software Requirements 6
Hard Drive Operation 12 Structure Import System Files 3
Hardware Requirements 6 System Application Directory 12
Import Database Structure System Configuration 6
Database Directory 14 System Memory 6
General Information 14 System Startup 12
Import Structure Information 14 Table of Contents iii
Corrupt Databases 5, 11, 14, 17 Technical Specifications 11
Dictionary Consistency 15-16 Technical Support 1
Import A Single Database 18 Trademark Acknowledgements i
Import All Databases 18 Unique Data Field Names 4
Import Report Format 15 Urgent Information 3-5
Insufficient System Memory 17 Usage Hints 19
Pre-Defined Database Entrys 16 Utility Menu (See DBSM docs.)
Report Output Options 14-15
Delete Dictionary Information 18