ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Partners
in
Success
ProvideX ODBC
Client-Server & Local Drivers
Presented by: Robert Fayle
NOTE: Some material in this presentation may
be superceded by entries in the ReadMe for
ProvideX Version 5.10.
Copyright © 2002 Best Software Canada Ltd. All rights reserved. No part of this
publication may be reproduced, or transmitted in any form or by any means,
electronic, mechanical, photocopied, recorded or other, without prior written
consent of Best Software Canada Ltd.
1
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Overview
ƒ Brief introduction to ODBC
ƒ Installing the ProvideX ODBC Driver
ƒ Configuring the ProvideX ODBC Driver
y Data Source Names
y Data Definitions
ƒ Using the ProvideX ODBC Driver
y With applications: Excel, Access, Crystal.
y With programming languages: VC++,VB, ASP, Java.
The purpose of this presentation is to assist dealers and developers in setting
up and utilizing the ProvideX ODBC Driver.
The following topics are covered in this session:
• Review of the installation and configuration procedures for the ProvideX
ODBC driver for both a local driver and a client-server version.
• Defining data files.
• Accessing ProvideX files using the driver.
• Using the ODBC Driver within programming languages.
2
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Introduction to ODBC
ƒ What is ODBC?
y Open DataBase Connectivity.
y Common interface standard.
y Uses SQL.
ƒ Architecture
y Four major components: Applications,
Drivers, Driver Manager, Data Sources.
ƒ Why use ODBC?
y Allows standardized access to ProvideX data.
What is ODBC?
ODBC is the acronym for Open DataBase Connectivity.
Common Interface Standard for Accessing Databases
ODBC provides a standard set of functions (API) that can be used by
any application to access a database. The ODBC system administers
the database names and drivers associated with the data files.
Uses SQL as the Retrieval/Update Language
ODBC access is based on SQL (Structured Query Language) which is
an English-like database access language designed to enable end-users
to view and manipulate data files. Over the years, the SQL language
was standardized by ANSI and adopted by a large number of database
manufacturers. SQL's original intent was to provide ad-hoc access to
data — but not as a development language or as a database interface
tool. With the advent of ODBC and other generic interfaces, SQL
became the de-facto standard used to manipulate databases.
Continued…
3
ProvideX ODBC, Client-Server / Local
Introduction to ODBC
Direxions, August 2002
(Continued)
Because the SQL language is English-like in its structure, it is easy to learn and
understand. The basic SQL directives are:
• SELECT to read and return data
• UPDATE to alter existing data records
• INSERT to add records
• DELETE to remove data records
Example:
SELECT cst_id, cst_name FROM Customer
This retrieves customer numbers & names from the Customer file.
Architecture
ODBC's architecture consists of four major components.
Applications
Applications are responsible for interacting with the user and for calling ODBC
functions to submit SQL statements to and retrieve results from one or more data
sources.
Drivers
Drivers process ODBC function calls, submit SQL requests to specific data sources,
and return results to applications. Also, drivers are responsible for interacting with
the software that is needed to access a specific data source.
The Driver Manager
The Driver Manager loads and calls one or more drivers on behalf of an application.
Data Sources
A data source is simply the source of the data. It can be a flat-file, or a particular
database in DBMS.
In ODBC, the term data source refers to the actual location of the data as well the
technical information needed to access the data: the driver name, network address,
user ID and password, and so on.
Continued…
4
ProvideX ODBC, Client-Server / Local
Introduction to ODBC
Direxions, August 2002
(Continued)
Why Use ODBC?
ODBC/SQL allows you to open up your ProvideX data to the most popular
database managers, query applications, and report writers: MS SQL Server 7,
Excel or Word with MSQUERY, Informix, and Crystal Reports, just to name a few.
Most programming languages have an ODBC access facility to allow files to be
read or updated as well.
ODBC/SQL allows standardized access to ProvideX data via:
• Standardized Data Formats:
Text strings, numerics, dates.
• Logical Relationships:
Relates files with common data elements.
• Data Sorting, Grouping and Filtering.
• Simple Data Computations:
Sum, Max, Min, Count, Avg
The ProvideX ODBC driver supports three basic types of data: string data, numeric
data, and dates.
The SELECT statement is used to establish logical relationships between data files
which is usually referred to as joining files. A typical JOIN would be:
SELECT cst_id, cst_name, smn_name FROM Customer, Salesman
WHERE smn_id = cst_smn
The statement reads the entire Customer file and for each customer, reads the
Salesman file for any records whose smn_id matches cst_smn. If the field
smn_id is a Key field for the file, then the ProvideX ODBC driver reads the file
directly by key, otherwise the file is read in its entirety. The WHERE clause can be
used to selectively filter out any unwanted data.
The ODBC driver can sort the data on any field using the ORDER BY clause of the
SELECT statement. If the ORDER BY fields match any of the key fields of the primary
file, then the primary file is accessed by this key. In addition, you can GROUP data
BY common fields.
SUM, COUNT, AVG, MAX, MIN functions can be used to provide statistical
information on the data fields.
You can find a list of SQL keywords supported by the driver in Appendix A.
5
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Registration
Enter the registration key,
SSSSSS-UU-AAAAAAAAAAAAAAAA
Where:
SSSSSSS
serial number
UU
user count
AAAAAAAAAAAAAAAA activation key
To specify Write ability, select Custom setup
The ProvideX ODBC driver requires a
registration key.
This key consists of the product serial
number, user count, and 16 or 17
character activation key.
When prompted for the registration
key, enter this information
(alphanumeric, uppercase) as follows:
SSSSSSS-UU-AAAAAAAAAAAAAAAA
Where:
SSSSSSS is the serial number.
UU
is the user count
AAAAAAAAAAAAAAAA.
is the activation key.
By default, the driver is installed in
Read Only mode. To specify Write
ability, select Custom setup.
6
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Driver Configuration
ƒ ODBC Data Source Administrator located
in the Windows Control Panel.
ƒ ProvideX ODBC driver settings include:
y
y
y
y
y
Database name
Directory for Data Dictionary files
INI file definition
Default Company and User codes
Automatic MAS90 recognition.
ƒ Additional settings for client-server version.
The ODBC Data Source Administrator is located in the Windows Control Panel (in the
Administrative Tools subfolder on Windows 2000/XP). Within the Administrator, you
must define each database and set up any associated configuration details.
The ProvideX ODBC driver configuration includes the following settings:
•
•
•
•
•
Logical Data Source Name (DSN)
Directory containing Data Dictionary file providex.ddf.
INI File to be used to manually define files
Company and User codes
Options.
Either the data file directory or the INI file, (or both), must be defined.
There must be at least one source for a Data Dictionary. If both have
been specified, then the contents of both will be merged.
For MAS90, provide a path to the MAS90 installation in the
'Database Directory'.
Example: 'C:\Program Files\Best Software\MAS90'
When using MAS90, the ProvideX ODBC driver automatically detects
and processes the DDICT directory. In addition, the Company and User
codes are validated against the MAS90 security system.
Additional ProvideX ODBC Server settings are required for the client-server version of
the driver:
•
•
Server Name or IP (e.g., LocalHost or 127.0.0.1)
TCP/IP Port (default: 20222).
7
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Sources
Three Types of Data Source Definitions:
User DSN
Defines data sources for the
user currently signed on.
System DSN
Defines data sources for a
particular workstation
File DSN
Places and maintains data
source definitions in a file.
ODBC Administration allows for the definition of three different types of
database definitions:
User DSN
This is a data source definition that is specific to the user currently signed on.
A data source defined in the USER DSN table is visible only to the user
defined to it. Typically, this is used when a PC is accessed by more than one
person.
System DSN
This is a data source definition that is available to the workstation regardless
of which user is signed on.
File DSN
This is a data source whose description is maintained on a file with the suffix
of .dsn. The advantage of file-based DSNs is that they can be placed in
common directories and shared between users; e.g., a file DSN can be
distributed among the clients as a part of an installation package.
8
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
Required Settings:
• Data Source Name
• Database directory and/or INI file
Optional Default Settings:
• Company code
• UserID
• Password
When defining a ProvideX ODBC data source, you are presented with
the following parameters:
Data Source Name
The name of the database.
Description
A free-form description of the database.
Database Directory
The pathname to the directory containing the data files and/or the data
dictionary.
Definition File
The path and name of the INI file containing the manually maintained
data dictionary.
Default Company code and User ID
Used to control file location and access rights.
ProvideX ODBC Server Settings (client-server version)
The network name and TCP/IP port of the server.
9
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
Data Source Name
y Logical reference name for ODBC.
y Unique within the system.
y Alphanumeric, 32-character maximum.
• Initial character must be alphabetic.
• Should not include special characters as some
applications are unable to handle them.
The Data Source Name (DSN) is the name that other applications will use to
access the database. With regards to the ProvideX ODBC driver, the DSN can
be considered the logical name of the database.
The DSN must be unique on the workstation, although the same set of files
(database) can be accessed under more than one DSN and its name can vary
from station to station.
The name is limited to a maximum of thirty-two (32) characters. The first
character must be alphabetic but the remaining characters can be
alphanumeric (A-Z, a-z, 0-9), spaces, or underscores. We strongly advise
against using other characters in the DSN; while they may work, other utility
programs which rely on ODBC may not be able to handle them.
DSN's are case-insensitive.
10
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
Database Directory
y Must contain location of providex.ddf file:
• Defines all the files accessible by the user
• Base directory for all files
y Automatically uses the embedded data dictionary
y If using MAS90, this must contain DDICT directory instead.
Definition File
y Typically used to define files from older legacy systems not
created using the NOMADS data dictionary facilities
y Supports non-normalized tables
y Provides the ODBC with:
• List of tables and the corresponding physical files
• List of columns within each table, their format, and how they
can be derived from the physical record data.
The Database Directory field defines the location of the NOMADS data
dictionary file (providex.ddf) which is the relative starting point for all
embedded file references. If used with MAS90, then the directory must
contain the location of the DDICT directory.
If providex.ddf is found in this directory, then all file/table definitions
contained in it are made available to the ODBC driver. Using the embedded
data dictionary simplifies the installation and maintenance issues regarding
the ODBC.
The providex.ddf file located in the database directory can be set up to
contain only a subset of the files used by an application. This is a means to
control which files/tables are presented to the ODBC and the end-user. In
order to provide different 'views' of the database, create separate directories,
each containing a different providex.ddf file.
Note: The providex.dde file is not required by the ODBC driver.
The Definition File represents an INI interface (text file) that allows you to
define the data dictionary manually for files that cannot be handled by the
ProvideX embedded data dictionary. This INI file-based data dictionary follows
the ODBC driver to access these files.
11
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
Prefix
y Sets file search rules.
Optional Information
y Company code.
y Default User ID.
y Password.
ƒ Used to validate user rights to data implemented
for MAS90 usage.
ƒ Supported by ProvideX ODBC Server.
Use the Prefix field to define a series of search paths that will be inserted in
front of all relative file references used in Data Dictionary or INI definitions.
The ProvideX ODBC has a built-in facility to allow for User and Company codes
to be defined. Defaults for the Company code and UserID may be set under
the Optional Information section.
Values in these fields can be used in the definition of the data file pathnames.
Whenever a data file pathname starts with an equal sign =, the pathname will
be scanned. All occurrences of %C$ will be replaced with the value set in the
default company code and %U$ will be replaced with the default user ID.
Also, there is the ability to force the user to enter a valid company and user
ID every time a connection to the ProvideX ODBC driver is made.
At present, this facility is tied to MAS90 data files and structures.
For other data sources, enter a question mark ? in default Company code
and/or User ID fields during the DSN setup.
Logical file names that start with an asterisk * are not made available through
the ProvideX ODBC driver.
12
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
ProvideX ODBC Server Settings
y Server Name or IP
y TCP/IP Port
(Default port number: 20222)
To connect to the ProvideX ODBC Server, it is necessary to specify the Server
network name or IP address; e.g.,
ProvideXFileServer
or
127.34.28.15
The server TCP/IP Port should be specified as well. If the TCP/IP port is not
set, then the default (20222) will be used.
You can change the TCP/IP port that the server is running on using the
Control Panel Configuration program, in which case the DSN TCP/IP Port
setting on the client side must be changed as well.
13
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
Burst Mode
y ODBC driver locks the file header once for
every 20 records read (up to a maximum of 2
seconds).
Dirty Read
y File header lock is never executed.
Both options are designed for use in Read Only
mode of the driver.
The ProvideX ODBC driver supports options designed to improve system
performance. These include Burst Mode and Dirty Read along with a local disk
caching system. Significant gains in the overall performance of the ODBC driver can
be achieved through the proper configuration of these parameters.
Burst Mode
Normally, when the ODBC driver accesses data files, it must place a temporary file
lock on the key structure of the file. This temporary lock guarantees that the driver
reads key tables and structure that are in a consistent state and not in the process
of being altered by other applications. Once the temporary lock is established, the
driver checks the file header to see if it has been changed since the last time the file
was accessed. If the file has not been altered, then the ODBC driver can use any of
the data still maintained in its data base buffers. If the file has been altered, then all
data in the data base buffers is discarded. When the driver has completed its access
to the data file, the temporary lock is released. This process is repeated for each and
every file accessed by the driver.
Placing the temporary lock and reading the file header places significant overhead on
the ODBC driver. When Burst Mode is enabled, the ODBC driver locks the file
header only once for every 20 records read (up to a maximum of 2 seconds), thus
eliminating not only the lock overhead, but also the requirement to re-read the file
header. This can eliminate up to 90% of the network traffic required to access data
files.
Dirty Read
The Dirty Read mode of operation further extends Burst Mode in that the file
header lock is never executed and the file update count is not checked. Dirty Read
executes faster, but can result in inconsistent data if the file is being updated while
being read by the ODBC driver.
Note: Both options are recommended for use in Read Only mode of the driver.
14
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
File Cache
y ODBC cache buffer eliminates the need to go to
disk for each pass of the data file.
Key Restrict
y Eliminates use of keys.
Enable Debug
y Creates log file Pvxodb32.log or
Pvxodc32.log (client-server version) in
C:\ directory.
File Cache
The execution of some SQL join commands may require multiple passes
through the same data file. An ODBC cache buffer option can be defined
to eliminate the need to go to disk for each pass of the data file. If
defined, this cache will be used whenever a secondary disk file is
required whose size is equal to or less than the cache size.
Key Restrict
This option allows the driver to be used with applications which do not
support keys or support them with limitations on length, field segments,
use of sub-strings, etc.
For example, Lotus Approach 97 does not manage a stack memory
properly if you are using files with a key consisting of more than one
data field.
Enable Debug
This option starts tracing the driver session on the ISAM level. The driver
will generate log files in C:\ directory with Pvxodb32.log representing
the regular driver and Pvxodc32.log for the client-server version.
15
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Setup
Data Source Parameters
Enforce DOUBLE
y Sets a "double" as a default format for numeric
data representation.
NULL Date
y Replaces invalid date values with a null value
on the fly.
Enforce DOUBLE
This options allows you to set a "double" as a default format for numeric
data. It helps avoid conflicts with MS Office 2000 and other applications that
do not support decimal data type for numerics.
NULL Date
The driver performs a validation of the date value at run time. If the value is
invalid, the driver generates an error message. NULL Date was designed to
suppress the Invalid Date error. Instead, the driver replaces an invalid entry
with a null value and allows the table to be processed anyway.
There is another option for debugging invalid date entries. In the INI
definition you can use class=date-unknown. It will tell the driver to
process the field as a string, without a date validation.
16
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Server Setup
ƒ The ProvideX ODBC Server configuration
program is accessed from the Control Panel.
ƒ Configuration settings include:
y TCP/IP Port number
y Access Permissions
y NT Service Installation
y Activation
The ProvideX ODBC Server configuration program can be accessed from the Windows
Control Panel at any time. The configuration program allows you to
• Specify the TCP/IP Port number (the default is 20222).
• Set up and manage the data files access permission.
• Activate the server or change the registration information.
The registration information (Serial Number, Number of Users, and Activation
key) is required for activating the server. If the registration information is valid, a
confirmation message will be returned when you press Apply.
It is possible to change the registration information at any time. For example, you
may need to update your license when there is an increase in the number of users on
your system. The ProvideX ODBC Server controls the number of concurrent client
connections and denies access if the Number of Users is exceeded.
The configuration program recognizes the version of the operating system where it is
running and allows the ProvideX ODBC Server to be set up as an NT service (for
NT/2000/XP systems) via Control Panel>Administrative Tools>Services.
The ProvideX ODBC Service is installed with the Automatic startup type which means
that the service will be started automatically every time the system reboots.
17
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Server Setup
Access Permissions
*
= Any
The ProvideX ODBC Server installation program sets default permissions:
Access
R/W
UserID
Company Code
Data Dictionary Path
INI Path
A
R
*
*
*
*
Access allowed
Read only
Any users
Any company
Any data dictionaries
Any INI files
These settings grant users almost unrestricted access to the server's data
sources. Therefore, immediately following installation, you should reset the
parameters based on your own business rules.
In the example, we set the R/W permission for the user John from the ABC
company. John is granted access to the data files defined in the
ProvideX.ddf files located in c:\pvxdata and/or c:\pvx\mydata directories
and in the test.ini file located in c:\nomtrain.
Access is temporarily denied by the server Administrator.
If the settings on the client side do not match the permission rules, John will
have access to the c:\tmp directory only. This is based on the rule for User
ID = Any (i.e., *), Company Code = Any, which is checked next in the order
of permissions precedence.
18
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Server Setup
The Permissions Check Order
Lowest Restriction
User ID
______Company Code__
1. Any
Any
2. Specific
Any
3. Any
Specific
4. Specific
Specific
Highest Restriction
The ProvideX ODBC Server starts to check permissions for the client from
"Bottom" to "Top"; i.e, from the maximum restriction to the lowest one.
If the check for a specific User ID and Company Code fails, then the User ID is
substituted with * (i.e., Any) and the combination for User ID = Any,
Company Code = Specific is checked against the corresponding rule if it is
present on the system.
The next check is performed for User ID = Specific, Company Code = Any,
and the last check is for User ID = Any, Company Code = Any.
It is a method to grant access to specific directories on the server based on a
client's User ID and Company Code.
19
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Server Setup
Service Installation
NT4, 2000, or XP
The NT Service tab allows installation of the ProvideX ODBC Server as a
Service. It allows the server to run independently of any logged-on user.
Note: The NT Service tab is hidden on Windows 9x systems as they do not
support applications running as services.
While it is possible to run the server as an application on a Windows 9x
desktop, it is not recommended. Windows 9x is designed to be a single user
system. To avoid performance problems, we suggest that it not be used as a
server.
20
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Data Definition
ProvideX Data Dictionary
ƒ Easily defined using built-in NOMADS Data
Dictionary Maintenance.
ƒ Embedded within the physical file.
• Providex.ddf used to provide list of files/tables
Note: Currently, the ODBC driver supports only Normalized
files (single record format) defined within the ProvideX Data
Dictionary.
The ProvideX Data Dictionary is the preferred method to define tables for
the ProvideX ODBC driver. Files defined using NOMADS Data Dictionary
Maintenance are fully compatible with the ProvideX ODBC driver.
For more information on NOMADS Data Dictionary Maintenance, refer to:
http://www.pvx.com/downloads/documentation/nomad_ref.zip
The ODBC driver reads the providex.ddf file to obtain the list of files that
exist within the system. As each file/table defined in the providex.ddf file is
accessed, its embedded data dictionary is read to determine the columns and
the format of the data.
Any table defined in the providex.ddf file whose logical name begins with an
asterisk * will not be made available to the user by the ODBC driver.
The ability to define Non-Normalized data files (i.e., files with multi-format
records) has recently been added to the Data Dictionary. This functionality has
not yet been incorporated into the current ODBC driver.
21
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Data Definition
INI Text File
ƒ Two types of entries:
• Table Declaration records that indicate the names
of all tables and related physical files.
• Record Layout/Field definition records that
describe the contents of each column.
ƒ Multiple INI files can be used to define record/column
formats.
ƒ Security Considerations.
The ODBC driver is currently limited to using normalized data source definitions from
the Data Dictionary; i.e., single record format per file. In order to define files with more
than one record/format, an INI file must be used.
The INI file contains two pieces of information crucial to the ODBC driver:
• A list of files/tables that are available to the ODBC driver.
• A list of the field elements/columns and their descriptions contained in these tables.
One drawback to the use of the INI file is the lack of security. Unlike the embedded
data dictionary, the INI file can be changed by any user to gain access to data files that
may have been restricted previously. There is no method for us to provide data
security when using an INI file interface.
There is a limit of 64KB on the size of an INI file. To avoid this
limitation, each entry can include, as an option, the pathname of an
alternate INI file following the file pathname. If an alternate INI file is
specified, then it will be searched to find the record/column descriptors.
22
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
INI File Definition
Table Declaration
ƒ [*TABLES*] section lists tables to be accessed.
ƒ Table names are defined as follows:
TableName=FilePathname[,alternate.ini][,SORTTABLE]
Example:
Client = c:\pvx\workshop\cstfile
The Table Declaration section of the INI file defines all the table names and their related
data files.
Example:
[*Tables*]
Client=cstfile
InvHeader=c:\pvx\workshop\odbc\invdta,c:\pvx\workshop\odbc\mydefs.ini,SORTTABLE
InvDetail=c:\pvx\workshop\odbc\invdta
Either absolute or relative pathnames can be specified in the INI file. Relative pathnames
are resolved based on the data directory parameter in the ODBC driver configuration.
The ODBC driver supports two inputs: Company Code and User ID. The contents of the
company code is stored in %C$, and the user ID in %U$. If the first character of the
physical file pathname is an equal sign, then the pathname is considered to be an
expression; all occurrences of %C$ are replaced with the company code, and %U with the
user ID. Plus signs and quotes are discarded.
Example:
Client= =%c$+"cstfile"
In the example above, if the user entered ABC in the company field of the ODBC driver,
then Client would be evaluated to ABCcstfile. If an embedded data dictionary for the
file exists within the file, then that record description will take precedence over the INI file
descriptors. To override an embedded Data Dictionary definition, use the ",alternate.ini "
option on the table entry in the Table Declaration of the INI file.
Example:
Client = cstfile,OdbcPvx.ini
Field definitions in the INI file can be sorted. If the fields in the physical record in a file are
not in sequence, use the ",SORTTABLE" keyword.
Example:
Client = cstfile,OdbcPvx.ini,SORTTABLE
23
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
INI File Definition
Record Layout
ƒ The record descriptor defines the columns with each
entry consisting of:
y The column name as it appears to the user.
y Additional parameters separated by commas.
Example:
[Client]
CST_no=string,LEN=6,field=1,offset=0
Record/column descriptors define the logical columns that are extracted from the ProvideX
data file. Descriptors have the following format:
[TableName]
ColumnName = ColumnDescriptors, . . .
The required parameters for each column are name and length. The ODBC driver assumes
that the column:
• contains string data.
• directly follows any preceding columns in the record.
• is delimited on the file by the default field separator ($8A$).
If you use the SORTTABLE option, you are required to provide field= and offset= for every
field definition.
Typical additional parameters:
numeric
Indicates a numeric field.
fixed
Indicates that the field is of fixed length and is not followed by a field separator.
field=…
Defines the logical field number within the record.
offset=… Defines the offset (zero based) within the field.
length=… Defines the length of the field.
24
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
INI File Definition
Date Fields
ƒ Use the class= option to identify dates.
y Class=DATE defaults to CCYYMMDD
ƒ Define the format of the date.
Internal date formats can be defined via class= name using a series of keywords. Use a dash
to separate keywords. The first keyword must be the word DATE. If you include a second
keyword, then you can use either BCD or PACK to define the internal (stored) date format; e.g.,
Where the internal date is a hex string = month, day, 2-digit year:
class=DATE-BCD-MMDDYY
Where the internal date is a hex string = Julian date:
class=DATE-BCD-JUL
Where the internal date is a 2-digit year, month and day and is packed using the PCK( ) function:
class=DATE-PACK-YYMMDD
If you don't include either of the keywords BCD or PACK, ProvideX stores your data in the internal date
format ASCII.dr=string,len=30; e.g., class=DATE-JUL1900.
Example Date Conversion
The data file DATES has 4 fields each with the same date represented 4 different ways. The INI field
definitions for dates in a DATE_data record are:
[DATE_data]
Date_1=String,len=8,class=DATE-YYYYMMDD
Date_2=String,len=8,class=DATE-YY-MM-DD
Date_3=String,len=4,class=DATE-BCD-JUL
Date_4=String,len=4,class=DATE-PACK-YYYYMMDD
You can use the class= option to define DATE fields in your data definition. The name of the CLASS defines
the internal format that the DATE field data will take (i.e., the form of the data when it's written to your
ProvideX database). The ProvideX ODBC driver gives you two special built-in internal date formats:
• Class=DATE*MAS90 uses the MAS90 algorithm for a packed date
• Class=DATE*SSI uses SSI's FACTS algorithm for a packed date
Date algorithms can be added to the driver upon request.
25
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Non-Normalized Files
External Keys
External keys are part of the ODBC record.
File Layout:
Key
CST_ID
Data
CST_ID
CST_NAME
CST_ADDR
ODBC Layout:
[keydata],[field1],[field2],…
CST_ID
CST_ID
CST_NAME
CST_ADDR
External keys are an issue when working with ODBC as the data may be duplicated on the
file. When an external key is used in a ProvideX file, the key data may be stored as part of
the record data as well.
The ODBC driver prefixes the data record with the external key which can result in the key
data being duplicated on the record. The solution is to hide the data from the ODBC enduser. The keyword HIDE is available only when using the INI file to define the data. When
using the ProvideX data dictionary to define the file layouts, HIDE is not supported, at
present.
Example:
[*Tables*]
Customer=\pvx\nomads\cstfile
[Customer]
CST_ID=STRING,LEN=6,FIXED
CST_ID_DUP=STRING,LEN=6,HIDE,SAMEAS=CST_ID
CST_NAME=STRING,LEN=30
CST_ADDR=STRING,LEN=30
Keyed files with External keys (DIRECT files). For the purposes of defining fields for a
DIRECT file, the external key is inserted in front of the record as it is read from the file and
passed to the ODBC system. For example, if the ProvideX file is created with ORD_NUMBER as
the 6-byte external key, and ORD_CUSTOMER and ORD_AMOUNT as data, then the INI record
descriptor would be:
[Order]
ORD_NUMBER=STRING,LEN=6,FIXED
ORD_CUSTOMER=STRING,LEN=10
ORD_AMOUNT=NUMERIC,LEN=10.2
If the key is duplicated in the data, you should expose the field that is the key and hide the
duplicate that is within the data portion. The SQL optimizer will recognize the key field and
be able sort the file much faster by using the key chain.
26
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Non-Normalized Files
Variant Records
Variant records can be represented through:
ƒ Filtering data, to return one logical table per record.
ƒ Flattening data, to create one logical table with fields
for all possible record formats.
• Technique is compatible with migration to SQL.
Because ProvideX has allowed users to evolve their applications, not every new
feature has been incorporated into an application. Sometimes due to the prohibitive
cost or the principle "if it ain't broke, don't fix it", the developers have files which
are not normalized.
The INI file can be used to convert a non-normalized data file logically into a
normalized one. Two techniques can be used.
Filtering the File Contents
Specifying a MUSTBE clause allows you to access specific record formats only. Any
records found in the ProvideX data file that do not satisfy the MUSTBE condition are
skipped. Filtering the file usually results in less rows in the logical tables than
records in the physical data file.
Flattening the Data File
Using the RECTYPE= and *RECTYPE options allows you to create a logical table that
contains all elements from all possible record formats. This preserves a one-to-one
relationship between the rows in the logical table and the records in the physical
file as all records can be represented as a row.
27
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Non-Normalized Files
Typical Example
An Invoice File with Header and Detail Records
Header Record Format:
Invoice_no
Line_no
Line_count
Customer_id
Order_dt
Detail Record Format:
Invoice_no
Line_no
Product_no
Ord_qty
Sale_price
Here is a typical example of a non-normalized data file and how to go about
representing it using either the filtering or flattening techniques available in the
ProvideX ODBC driver.
The data file INVDTA has two record types.
Record Type 1. An Invoice header record with a key of Invoice number and "000"
(pseudo line number) with data fields of Line count, Customer ID, and Order date.
Invoice_no
Line_no
Line_count
Customer_id
Order_dt
Record Type 2. An Invoice detail record with a key of Invoice number and line
number with data fields of Product number, Order Quantity and Sale Price.
Invoice_no
Line_no
Product_no
Ord_qty
Sale_price
28
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Non-Normalized Files
Filtering Data
Split Non-Normalized File Into 2 Logical Tables
InvoiceHeader:
Invoice_no
Line_no
Line_count
Customer_id
Order_dt
InvoiceDetailLines:
Invoice_no
Line_no
Product_no
Ord_qty
Sale_price
If we apply filtering to the data file, then we end up with two logical tables. The
InvoiceHeader table, containing the invoice header records, and the
InvoiceDetailLines table, containing the invoice detail lines.
The INI file would contain:
[*Tables*]
InvoiceHeader=invdta
InvoiceDetailLines=invdta
[InvoiceHeader]
Invoice_no=STRING,LEN=6
Line_no=STRING,LEN=3,MUSTBE="000",HIDE
Line_count=NUMERIC,LEN=4.0
Customer_id=STRING,LEN=6
Order_dt=STRING,LEN=8
[InvoiceDetailLines]
Invoice_no=STRING,LEN=6
Line_no=STRING,LEN=3,MUSTBE>"000"
Product_no=STRING,LEN=8
Ord_qty=NUMERIC,LEN=5.0
Sale_price=NUMERIC,LEN=8.2
If more than one field defines the record type, then the data must be filtered using
the MUSTBE keyword.
29
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Non-Normalized Files
Flattening Data
Blend Data Based on Record Type Identifier
Invoice_no
Line_no
Invoice_no
Line_count
Line_no
Customer_id
Line_count
Order_dt
Customer_id
Invoice_no
Order_dt
Line_no
Product_no
Product_no
Ord_qty
Ord_qty
Sale_price
Sale_price
If Line_no = "000"
If Line_no not = "000"
When flattened, the data from both potential record formats would exist in each row
of the logical table. The data field Line_no would be declared the record type
identifier (*RECTYPE clause). In the example below, the header records are
identified by the RECTYPE="000" and the detail records by the RECTYPE="~000".
Note the FIELD=1 on the Product_no entry. The driver reads through the fields and
if the FIELD=1 is not there, the driver assumes that Product_no is the fourth field.
The INI file would contain:
[*Tables*]
InvoiceData=invdta
[InvoiceData]
Invoice_no=STRING,LEN=6,FIXED
Invoice_line=STRING,LEN=3,FIXED,*RECTYPE
Line_count=NUMERIC,LEN=4.0,RECTYPE="000"
Customer_id=STRING,LEN=6,RECTYPE="000"
Order_dt=STRING,LEN=8,RECTYPE="000"
Product_no=STRING,LEN=8,RECTYPE="~000",FIELD=1
Ord_qty=NUMERIC,LEN=5.0,RECTYPE="~000"
Sale_price=NUMERIC,LEN=8.2,RECTYPE="~000"
The leading tilde ~ in the RECTYPE="value" clause indicates that the record data
must not match the value given. The *RECTYPE keyword only allows for a single
field per table to be defined. If multiple fields define the record type, then use the
MUSTBE keyword.
30
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Typical Uses of ODBC
ƒ Provide read access for reporting tools.
y Crystal reports
y Excel and Word using MSQuery
ƒ Update ProvideX data files from applications
y MSAccess
ƒ Use ProvideX data source with programming
languages:
y ProvideX, VC++, VB, ASP, Java
Primarily, ODBC is used to provide Read access to data files from other
products such as Crystal reports, Excel, or Word. Most programming
languages have an ODBC access facility to allow files to be read or updated as
well.
You can update your ProvideX data files easily by making a link from a MS
Access session through the ProvideX ODBC Driver.
Use the ADO Data Object and the ProvideX ODBC Driver to get access to
ProvideX data files from other programming languages such as: VC++, VB,
ASP.
31
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Driver
and VC++
Visual C++ Applications
ƒ Add Two ActiveX Controls to Your Project:
y Microsoft ADO Data Control, v. 6.0 (OLEDB)
y Microsoft Data Grid Control, v. 6.0 (OLEDB).
ƒ Setup control properties.
ƒ Link controls.
To simplify processing a ProvideX data file from a VC++ application, use
two ActiveX Controls from Microsoft:
•
Microsoft ActiveX Data Object (ADO) Data Control, version 6.0 (OLEDB)
•
Microsoft Data Grid Control, version 6.0 (OLEDB)
Steps to Access ODBC Data Source for VC++
1. Add these Controls to your Project (Menu: Project > Add To Project >
Components and Controls > Registered ActiveX Controls).
2. Set up Microsoft ADO Data Control Properties:
General Tab
Set a unique ID name (i.e., IDC_MY_ADODC)
Control Tab
Check Use ODBC Data Source Name and enter the DSN
name defined on your system.
RecordSource Tab
Command Type >
1 – adCmdText
Command Text (SQL) >
SQL Statement
(e.g., SELECT * FROM Table_name)
3. Link the Data Grid Control to the ADO data source. On the All Tab of the Data
Grid Control Properties for Data Source value, enter the name of the ADO
Data Control (IDC_MY_ADODC).
32
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Driver
and VB
Visual Basic Applications
ƒ Open VB Data Project
ƒ Add DataGrid and Adodc Controls to Form
ƒ Setup Controls Properties
ƒ Link Controls
In VB, access to the ODBC data source is simplified by the existence of the default
Data Project.
This type of VB project has already included all the necessary controls and
components for processing the ODBC data.
Steps to Access ODBC Data Source for VB
1. Create a new Data Project.
2. Add two controls to your form: DataGrid and Adodc
3. Set up Adodc Data Control Properties:
General Tab
Check Use ODBC Data Source Name and enter DSN name
defined on your system.
RecordSource Tab
Command Type >
1 – adCmdText
Command Text (SQL) >
SQL Statement
(e.g., SELECT * FROM Table_name)
In the Adodc Control Properties table, set a unique control name for the Name
property (e.g., My_Adodc).
4. Link the DataGrid and Adodc controls. In the Property Table of the DataGrid
control for Data Source value, enter the name of the Adodc Data Control
(My_Adodc).
33
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Driver
and ASP
Active Server Pages
ƒ Create connection and recordset objects.
ƒ Connect to data source:
objConn.ConnectionString = strODBCConnectString
objConn.open
ƒ Get data:
Set objRs = objConn.execute (strSQL)
This is an example of an Active Server Page (ASP) program which provides access to the
MAS90 (ProvideX) data source through the ADO object and the ProvideX ODBC Driver,
retrieves the data, and outputs the result as a table.
Data within the AP1_VendorMaster Database:<br><br>
<%
Dim strODBCConnectString, objConn, objRs, strSQL, intCounter, intIndex
strODBCConnectString = "DSN=ASP_MAS90"
! Define a connection string
strSQL = "SELECT * From AP1_VendorMaster "
! Define an SQL statement
Set objConn = Server.CreateObject("ADODB.Connection") ! Create 'connection' object
Set objRs = Server.CreateObject("ADODB.Recordset")
! Create 'recordset' object
objConn.ConnectionString = strODBCConnectString
objConn.open
! Connect to the data source
intCounter = objRs.Fields.Count
! Count number of fields in table
Set objRs = objConn.execute( strSQL )
! Retrieve the data
%>
<TABLE border = 1>
! Output the result in form of simple table
<% Do while (Not objRs.eof) %>
<TR> <% For intIndex=0 to ( intCounter-1 ) %>
<TD VAlign=top><% = objRs ( intIndex ) %></TD>
<% Next %>
</TR>
<% objRs.MoveNext
Loop
%></TABLE>
<% objRs.close
! Close 'recordset' object
objConn.close
! Close 'connection’ object
%>eyc
34
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Driver
and Java
JAVA Applications
ƒ Use JDBC - ODBC Bridge.
ƒ Create Connection and Statement objects.
ƒ Get data:
executeQuery() method of the Statement object
This is an example of the Java class which is making an ODBC connection to the
ProvideX data source via ODBC – JDBC bridge.
import java.sql.*;
public class pvxodbc {
public pvxodbc() {
int x = 10;
try{
Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
String url = "jdbc:odbc:pvxtst";
Connection con = DriverManager.getConnection(url);
Statement stmt = con.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM \"SASPS1 - Cust Slsm (MF)
Units\"");
while (rs.next()) {
String s = rs.getString("COMPANY");
System.out.println("Company "+s );
}
}catch(SQLException e){
int err = e.getErrorCode();
System.out.println("SQL Error code = "+err );
}catch(Exception e){
System.out.println("Error");
}
}
public static void main(String[] args) {
new pvxodbc();
}
}
35
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
ProvideX ODBC Driver
Limitations
ƒ Limited SQL Syntax supported.
ƒ Column and Table Names are not casesensitive.
ƒ Transactions are not supported.
ƒ Special characters " / \ , ." for logical
names should be avoided.
Limitations
• Only a minimum level of SQL is supported with some additional core
level SQL functionality.
• Some level 2 ODBC API calls that are not used commonly are not
supported. Specifically, SQLBrowseConnect, SQLTablePrivileges,
SQLColumnPrivileges, SQLProcedures, and SQLProcedureColumns
are not supported.
• Column and table names are not case-sensitive.
• Interval types are not supported.
• Qualifiers or owners are not allowed on databases, tables, etc.
• Transactions are not supported.
Known Problems
• Using Visual FoxPro as a front-end to access MAS90 data source with
MAS90 user authorization.
• Using special characters ( / \ and . ) for logical names in ProvideX data
source if used in Visual FoxPro.
• Client-Server version does not support a relative path in the INI
definition.
36
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Future of ProvideX ODBC
ƒ Improve performance
ƒ Keep up-to-date with ProvideX file system
Currently, versions for SCO5, AIX & Linux are available.
37
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
End of Presentation
Thank You
Refer to further notes in Appendix A and Appendix B.
38
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Appendix A
SQL Keywords Supported by ProvideX ODBC
The ProvideX ODBC Driver currently supports the following SQL
keywords:
*
+
- (minus)
- (negative)
/
<
<>
<=
=
>
>=
ALL
AND
ANY
ASC
AVG
BETWEEN
COUNT
DELETE
DESC
DISTINCT
EXISTS
FROM
GROUP BY
HAVING
IN
INSERT
INTO
IS
LEFT OUTER JOIN
LIKE
MAX
MIN
NOT
NOT BETWEEN
NOT IN
NOT LIKE
NOT NULL
NULL
OJ
ON
OR
ORDER BY
SELECT
SET
SUM
UPDATE
VALUES
WHERE
39
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Appendix B
Column Descriptor Options
Note: Only the first three characters are required.
One of:
NUMERIC
STRING
UNSIGNEDBINARY
MAS90*YEAR
BNR
Data is numeric.
Data is a string (default).
Data is numeric value stored as an unsigned binary
on the file.
Special MAS90 Year only format.
Data is numeric value stored as a signed binary on
the file.
One of:
BINARY
FIXED
VARIABLE
PADDED
SIGNED
DECIMAL
DELIMITED
FORMAT=…
SEPARATOR=…
HIDE
NOSHOW
MUSTBE < = > ….
CLASS=…
Data is numeric value stored in signed binary on
the file as a sub-string of a field.
Field length is fixed with no field terminator and
trailing spaces are stripped.
Field length is variable, terminated by separator
character. This is the default.
Field length is fixed with field terminator and
trailing spaces are not stripped.
Field is a sub-string with a trailing sign character.
The last character must be ‘+’ if positive,
otherwise, the field is assumed to be negative. No
embedded decimal allowed.
Sub-stringed numeric field with an embedded
decimal.
The field is terminated with a separator character.
A definition of NUMERIC, DELIMITED is how a
DECIMAL field is defined if it is the last sub-string.
Define the format of the data returned (maximum
40 characters).
Delimiter for variable length field. The value is the
delimiter character expressed as a decimal value;
e.g., a LF character (hex $0A$) is declared as
SEPARATOR=10.
This indicates that the field will not be presented to
the user. Primarily, it is used for filler values.
The field name will be presented to the user,
however, the data will never be returned.
Conditional test which will cause the record to be
skipped if not valid. This is used to filter unwanted
records from the file. Maximum of 80 characters.
Class declaration used for Dates etc. Maximum of
20 characters
40
ProvideX ODBC, Client-Server / Local
Direxions, August 2002
Appendix B
Column Descriptor Options (continued)
To Define Multiple Record Formats
*RECTYPE
Record type identification field. Only a single field
per table will be recognized.
RECTYPE=…
Record type conditional value (maximum 40
characters).
Recognized Classes
DATE
DATE*MAS90
DATE*SSI
DATE-UNKNOWN
DATE-BIN
DATE-PACK
DATE-JUL
DATE-BCD
DATE-AAMMDD
DATE-KKMMDD
DATE-PAW
Format of YYYMMDD.
Uses BEST's MAS90 algorithm for a packed date.
Uses SSI's FACTS algorithm for a packed date.
Process date value as a string, without date
formatting and validation.
Date stored as a binary value;i.e., DATE-BINYYMMDD = BIN(990101,4) ! $000F1B95$.
Date stored as a packed numeric; i.e., DATE-PACKYYMMDD = PCK(990101).
Default base year is 1970.
Date stored as a binary packed decimal;
i.e., DATE-BCD-YYMMDD = ATH(STR(990101)).
If the 1st 2 characters are greater than or equal to
“A”, then 200 + character – “A” else 190 +
character – “0”.
190 + character – “A”.
This format is used by TopForm’s application.
4 byte Peachtree Accounting date field. Field is a
sub-string.
INI File equivalents to Data Dictionary Definitions
ProvideX Element Definition
INI File Definition
STRING, Delimited
STRING, VARIABLE
STRING, Fixed
STRING, FIXED
STRING, Padded
Not supported by INI at
STRING, Substring
Not supported by INI at
STRING, Last substring
STRING, PADDED
NUMBER, Delimited
NUMERIC, VARIABLE
NUMBER, Fixed
NUMERIC, FIXED
NUMBER, Padded
Not supported by INI at
NUMBER, Substring
Not supported by INI at
NUMBER, Last substring
NUMERIC, PADDED
NUMBER, Binary numeric
NUMERIC, BINARY
NUMBER, Decimal
NUMERIC, DECIMAL
NUMBER, Decimal delimited
NUMERIC, DELIMITED
NUMBER, Signed fixed numeric
NUMERIC, SIGNED
NUMBER, Unsigned integer
Not supported by INI at
this time
this time
this time
this time
this time
41