Advantage Crystal Reports Driver

README.TXT for Crystal Reports v9 7.0

============ ================================== ============

Contents:
==========
1. Requirements
2. Installation
3. Creating a New Report
4. Important Alias Notes
5. What's New in v7.0
6. Known Problems
7. Frequently Asked Questions

1. Requirements
============================================

a) Seagate Crystal Reports version 9

b) Advantage client DLLs version 7.0:

* CRDB_ADS.DLL (Advantage Crystal Reports DLL)
* ACE32.DLL (Advantage Client Engine DLL)
* AXCWS32.DLL (Advantage Comm Layer DLL used when accessing the
Database Server)
* ADSLOC32.DLL (Advantage Local Server DLL)

c) Advantage Database Server or Advantage Local Server version 7.0

or greater

2. Installation
============================================

a) The Advantage Crystal Reports Driver consists of one DLL,

crdb_ads.dll. To install the driver, copy crdb_ads.dll into the
Crystal bin directory
(e.g. - c:\program files\common files\crystal decisions\2.0\bin).

If you will be using reports created with a version of Crystal

Reports older than Crystal v9, you will also need to make an
additional copy of the crdb_ads.dll, but name this copy crdb_p2sads.dll.
This can be accomplished by going to the Crystal bin directory at a
command promt and using the following command:
copy crdb_ads.dll crdb_p2sads.dll

3. Creating a New Report

============================================

a) Crystal 9
To create a new report that uses the Advantage Crystal Reports
driver, create a new report as you normally would with Crystal.
When prompted to select the data you will be reporting on, expand
the 'Create New Connection' tree item. Expand the 'Advantage'
tree item. All Advantage alias entries will be shown in the list.
If you have never configured an Advantage alias, see the
'Important Alias Notes' section later in this readme for a
description and example ads.ini file. Select the desired Advantage
 entry in the list and continue developing the report. This is the
only Advantage-specific selection you will have to make.

4. Important Alias Notes

============================================

The Advantage Crystal Reports Driver utilizes Advantage aliases.

Advantage aliases are similar to the Delphi database alias.
Aliases are added to the [DATABASES] section in the ADS.INI file
located in the WINDOWS directory (by default). Advantage clients
use the search path to locate the ads.ini file, so this file can
be placed in your application's directory or anywhere in the search
path of the client machine. The key name is the name of the alias
and the value is the "Data Path", semi-colon, followed by the first
letter of the index type. For example, adding an alias name
"MyAlias" with a data path of "C:\MYPATH" using index type ADT will
cause "MyAlias=C:\MYPATH;A" to be written to the ADS.INI file under
the [DATABASES] section.

Example ADS.INI file:

[Settings]
ADS_SERVER_TYPE=2

[Databases]
ADS_ADT=x:\MyAdtFiles;A
ADS_CDX=x:\MyDbfFiles;C
ADS_DD=x:\MyFiles\mydiction.add;D

Explanation of the ADS_SERVER_TYPE key:

The ADS_SERVER_TYPE key in the ADS.INI file can be used to select
the Advantage server type(s) to use when obtaining an Advantage
server connection. The available Advantage Server types are
ADS_REMOTE_SERVER which is the Advantage Database Server,
ADS_AIS_SERVER which is the Advantage Internet Server, and
ADS_LOCAL_SERVER which is the Advantage Local Server. These
Advantage server type constants are defined in the ACE.H, ACE.PAS,
and ACE32.BAS files. ADS_REMOTE_SERVER has the value 2,
ADS_AIS_SERVER has the value 4, and ADS_LOCAL_SERVER has the
value 1. For example, if you wanted your Advantage application to
attempt to connect to all Advantage server types, if necessary, you
need to set the value for the ADS_SERVER_TYPE key to 7 (1 + 2 + 4
= 7). The default ADS_SERVER_TYPE value is to use ADS_REMOTE_SERVER
and ADS_AIS_SERVER, which is 6 (2 + 4 = 6).

5. What's New in v7.0

============================================

a) New Advantage functionality associated with the SQL engine:

* Added ability to execute SQL scripts via a semicolon delimited

list of SQL statements. Not only is executing scripts in this
fashion convenient, it can also increase performance, as the
statements are sent to the server in one request and processed
individually by the server. In low bandwidth situations, or when
executing a large script, this can result in a dramatic speed
increase. See the "Scripts" topic in the "Advantage SQL" |
"Supported Grammar" book in the Advantage Help file for details.
 * Added transaction syntax support. BEGIN TRANSACTION, COMMIT WORK,
ROLLBACK WORK, and SET TRANSACTION statements are now supported.

* Added database permission GRANT and REVOKE statements.

* Added CREATE DATABASE and CREATE TRIGGER statements.

* All data dictionary metadata is now accessible through SQL system

tables and modifiable through system stored procedures. See the
"Advantage SQL" | "System Views" book in the Advantage Help file
for details.

* Added CAST scalar for precision data type conversions.

* Improved RAND scalar so that the number produced exhibits a

better "random" behavior.

* Added a virtual system table named iota. Iota is a table

with one logical (SQL_BIT) column named "iota" and has a single
row in the table with a NULL value in the "iota" column. The main
purpose of the IOTA table is to provide an efficient method for
evaluating an SQL expression on the server.

* Improved performance of some SQL operations that require temporary

sort files with larger data sets. For example, GROUP BY statement
performance may be more than 10 times faster on data sets of 1
million records and larger. In addition to GROUP BY statements,
this can improve the speed of UNION, DISTINCT, and ORDER BY
operations.

b) Miscellaneous new functionality:

* Added a highly optimized Full Text Search engine. It is possible

to search character, memo, and BLOB data using intuitive search
phrases constructed of words and logical operators. See the "Full
Text Search" topic in the Help file for details.

* Added support for compression of all network communications

between the client and the server. By default, compression is
only turned on for connections made over the Internet. See the
"Communications Compression" topic in the Advantage Help file
for details and to determine if turning on compression will help
your application's performance.

* Added support for triggers. A trigger is a piece of code (similar

to a stored procedure) that is executed on the server in response
to an insert, update, or delete operation. Triggers can provide a
very powerful means to maintain business rules at the database
level.

* Improved the performance of various database operations. For

example, one should expect performance improvements of 10% and
greater with insert/append operations, operations involving
Advantage Optimized Filters, and deleting of records when the
table contains one or more memo/BLOB fields.

* When creating new indexes on a table with many records or when

performing a reindex operation on a table with many records, the
 creation of that index will be much faster in 7.0 than earlier
versions of Advantage Database Server. On tables with fewer than
100,000 records, the performance improvement may not be
significant. Tables with more than 100,000 records can expect up
to a 50% performance increase. Table with multiple millions of
records can expect even better performance increases, perhaps as
much as 300% faster. Increasing the Advantage Database Server
SORT_BUFFER configuration value can lead to even larger index
creation performance increases with very large tables.

* Added various Advantage Extended Procedure (AEP) Enhancements. A

new AEP interface has been developed, which includes the following
features:
- AEP is passed an active connection handle, as opposed to a
username and password. This active connection handle can be
used to perform all data operations; no additional
connections are required.
- AEPs can be called inside a transaction, and all operations
performed in the AEP using the active connection handle passed
to the AEP are included in the context of the transaction.
- Input and output parameters are passed through the virtual
tables __input and __output. No more parsing of input/output
table paths is necessary.
- An additional connection to read the input and output tables
is no longer necessary.
- An in-memory table (__error) can be used to return
descriptive error messages to the client application.
- The number of rows affected can be returned and used from the
client application just like it can with traditional SQL
INSERT/UPDATE/DELETE statements.
- New AEPs do not check user privileges when executing, which
allows you to hide tables from the user(s), but allow access
and modifications to those tables through AEPs that you
control.
- A combination of several of the above new features result in
overall better AEP performance than with earlier versions.

* Added new Money field data type for ADTs. This BCD-like field
allows for currency data stored internally as a 64-bit integer,
with 4 implied decimal digits from -922,337,203,685,477.5807 to
+922,337,203,685,477.5807. No precision will be lost when doing
calculations involving this data type.

* Added support for DBF memo and BLOB data encryption. If all
records in a DBF table are encrypted, all fields in the table will
be encrypted, including and memo and binary fields.

* Added support for fixed and keyset-driven Advantage Optimized

Filter (AOF) types in addition to the existing dynamic type when
used with the Advantage Database Server. These different AOF types
provide different levels of filter membership when used with
the Advantage Database Server (not Advantage Local Server). With
dynamic AOFs, filter membership is affected by modifications all
users make to record data. With keyset-driven AOFs, filter
membership is only affected by updates from the filter owner (the
table instance that set the filter). Updates made by other users
will not affect a record's membership in the filter. With fixed
AOFs, filter membership does not change. If other users modify
records, they will always remain visible within this fixed filter,
 even if the changes have modified field values such that the
record no longer passes the original filter expression.

6. Known Problems
============================================

a) Dictionary links are currently not working. If you create a link in

a dictionary to a table in some other dictionary, Crystal will not
build the correct SQL syntax to query that table. This bug has been
submitted to Seagate Software (bug ID ADAPT00145238), and we are
waiting for a fix.

b) Reports created with previous versions of the Advantage Crystal

Reports Driver that use INNER joins may not function correctly.
When opened with the new Crystal driver, the report might switch
the INNER joins to LEFT OUTER joins. To work around this issue:

1) open the report in the Crystal IDE

2) Select 'Database Expert...' from the 'Database' menu option
3) Select the 'Links' tab
4) Right-click on each link and select 'Link Options...'
5) Select the correct join type
6) Save the report

7. Frequently Asked Questions

============================================

a) How do I change the default Advantage locking mode?

The Advantage Crystal Reports Driver by default uses the

Advantage Proprietary Locking mode. If you have applications
accessing your data that are not also using this proprietary
mode, you will get a 7028 error (or some other
locking-related error) when attempting to open data files or
execute reports. To force the Advantage Crystal Reports Driver
to use the Advantage Compatible Locking mode, add the following
two lines to your ads.ini file:
[Crystal]
LockingMode=0 ; ADS_PROPRIETARY_LOCKING=1 ADS_COMPATIBLE_LOCKING=0

b) How do I change the default Advantage Character Type?

The Advantage Crystal Reports Driver by default uses the

ADS_ANSI character type. To force the Advantage Crystal Reports
Driver to use the ADS_OEM character type, add the following two lines
to your ads.ini file:
[Crystal]
CharType=0 ; ADS_ANSI=1 ADS_OEM=2

c) How do I change the default rights checking mode?

The Advantage Crystal Reports Driver by default uses the

ADS_CHECKRIGHTS option on all statements. To force the Advantage
Crystal Reports Driver to use the ADS_IGNORERIGHTS option, add the
following two lines to your ads.ini file:
[Crystal]
RightsChecking=1 ; ADS_CHECKRIGHTS=1 ADS_IGNORERIGHTS=2
d) Which files do I need to add to my report distribution?

The following Advantage-specific files must be included in your

report distribution:
crdb_ads.dll - Advantage Crystal Reports Driver
crdb_p2sads.dll - copy of crdb_ads.dll, only necessary if shipping
reports generated with versions of Crystal Reports
prior to v9.
ads.ini - this is the most important file to note, as
Crystal will not detect this file as being
necessary for the report, so you must manually
add this file to your distribution.
ace32.dll
axcws32.dll (if using Advantage Database Server)
adsloc32.dll (if using Advantage Local Server)
adslocal.cfg (if using Advantage Local Server)

NOTE: These DLLs must be in the application folder or in the search

path.

e) Why can't I find my Advantage aliases in Crystal?

If your ads.ini file is configured correctly and you still don't see
any Advantage aliases in the Crystal Report designer there is most-
likely a version mismatch with the Advantage Client Engine (ACE). Verify
the following DLLs are all the same version: crdb_ads.dll, ace32.dll
axcws32.dll and adsloc32.dll.

f) How do I make Crystal show deleted records in a DBF table?

The Advantage Crystal Reports Driver filters out deleted DBF

records by default. To force the driver to show deleted
records, add the following two lines to your ads.ini file:
[Crystal]
ShowDeleted=1