Installation notes for Canaima Software's

f90SQL for Lahey/Fujitsu Fortran 95

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

Product Description
===================

f90SQL-Pro is a library of functions and subroutines

that works as an interface between your Fortran
programs and the Microsoft Windows Open Database
Connectivity (ODBC) API. f90SQL offers a
convenient and familiar way to read and write data
directly from your Fortran programs to many database
and spreadsheet formats, including (but not limited
to): Excel, Lotus 1-2-3, Microsoft Access, FoxPro,
Paradox, Oracle, Sybase, Ingres, Informix, and
Microsoft SQL-Server. As long as the application
offers an ODBC interface to its data files, f90SQL
lets you read and write data to the native
application's format directly from your Fortran
programs.

f90SQL-Lite is a special version of f90SQL-Pro,

Canaima Software's Database Connectivity Library
for Fortran. While f90SQL-Pro is optimized to
handle large record sets with a small memory
foot-print, f90SQL-Lite is optimized to work with
small record sets, and a limited number of database
connections.

Compiling with Lahey/Fujitsu Fortran 95

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

For LF95 ver. 5.6 and above, you can use compiler
switch -f90sql to instruct LF95 to use the f90SQL
modules and library.

Example programs
================

Several of the example programs use the BookSales

database included in the subdirectory
Examples\f90SQL\Database. To run these programs you must
create a Data Source Name (DSN) using the ODBC
Administrator from the Control Panel. There is a
section in this readme.txt file with more detailed
information on how to create a DSN in your
system.

Several of the examples have versions that

demonstrate features available only in
f90SQL-Pro.

Installing on computers with FAT file systems

=============================================
If your hard drive is using FAT, you should
install f90SQL components to directories with
short (8 or less characters) names. Otherwise
the compiler may not be able to resolve the
path to f90SQL modules and libraries.

f90SQL Technical Support

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

Canaima Software's web server

(http://www.canaimasoft.com) has an on-line
discussion group for f90SQL-related topics.
This is the best place to post your questions or
comments, and get quick and knowledgeable
answers from our technical support group.
f90SQL-Lite users are supported only on a
best-effort basis through this discussion group.
f90SQL-Pro users can contact Lahey Computer
Systems technical support at support@lahey.com.

Files included in this release

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

The following is a list of the core files included

in the f90SQL distribution:

File: f90SQL.Lib
Description: f90SQL Library
Location after installation: the Lib directory of
your Lahey Fortran 95.

File: f90SQLLF95.DLL
Description: f90SQL Dynamic Link Library (DLL)
Location after installation: Your Windows System
directory.
Comments: This is the only redistributable
component of the f90SQL ODBC Library for Lahey
Fortran 95.

Files:
f90SQLConstants.f90
f90SQLConstans.mod
f90SQLConstans.obj
f90SQLStructures.f90
f90SQLStructures.mod
f90SQLStructures.obj
f90SQL.f90
f90SQL.mod
f90SQL.obj
Description: f90SQL Modules.
Location after installation: the Include directory
of your Lahey Fortran 95 installation.

File: ReCompilef90SQL.bat
Description: make file to re-compile f90SQL
Modules.
Location after installation: the Include
directory of your Lahey Fortran 95.

Files:
f90SQLHelp.chm
f90SQLHelpTOC.hhc
Description: f90SQL User Manual, in Microsoft's
HTML-Help format.
Location after installation: the Manuals
directory of your Lahey Fortran 95.
If you cannot view the User Manual,
you can install the Microsoft HTML Help Update
from Accessories on the CD Setup Menu.

Verifying the version of the ODBC Driver

Manager
========================================

f90SQL needs version 3.5 or higher of the ODBC

driver manager. Follow the instructions below to
verify the version of the ODBC Driver Manager
installed in your system:

1) Open your Windows System folder with

Microsoft's Windows Explorer.
2) Right-click on file ODBC32.DLL, select
Properties from the pop-up window.
3) Click on the tab labeled version.
4) The version of the Driver manager appears
next to the label "File Version".

If your ODBC Driver Manager version is earlier than

3.5, you should run program mdac_typ.exe to update
the driver. You can download the latest version of
the ODBC Driver manager from Canaima Software's
or Microsoft's web server. You can also install ODBC
ver. 3.5 from from Accessories (Microsoft Data Access)
on the CD Setup Menu.

Creating a DSN for the BookSales Database

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

Many of the examples that come with f90SQL need a

Data Source Name entry for the BookSales database.
Follow the instructions below to create a Data
Source Name (DSN) for the BookSales database
in the Examples\Database directory of your f90SQL
installation:

1) Open Windows Control Panel

2) Double click the ODBC icon
3) Select the tab labeled System DSN
4) Click the Add button, select Microsoft
Access Driver and click Finish
5) This will pop up a window requesting information
about the new data source. Enter the following:
 5.1) In Data Source Name enter "BookSales"
(without the quotes)
5.2) Click the Select button and select
file Booksales.mdb in your hard drive.
5.3) Click Ok

Using compiler optimization switches (-O1) with

f90SQL
===============================================

One of the side effects of the optimization switch

(-O1) in Lahey/Fujitsu Fortran 95, is that the compiler
might use the same memory address for several
parameter definitions and literal constants. This may
cause problems when calling some of the subroutines
in f90SQL using literal values as arguments. This
situation is better illustrated with a simple example:

program OptSideEffect

integer*2,parameter::iconst=0
integer*4 a,b

a=1
b=2

print *,a,b,iconst
call sub(a,b,int(0,2))
print *,a,b,iconst

stop
end

subroutine sub(arg1,arg2,arg3)
integer*4 arg1,arg2
integer*2 arg3

arg1=arg1+1
arg2=arg2+1
arg3=arg3+1

end subroutine

If you compile and link the previous program using:

lf95 -O0 OptSideEffect.f90

the output is what you would expect:

1 2 0
2 3 0

However, if you compile and link using the default

optimization switch (-O1) the output is:

1 2 0
2 3 1

Which indicates that constant iconst has been

modified. This is an unexpected behavior. With the
default optimization on, the compiler sees that
int(0,2) and iconst have the same value and type.
Instead of generating int(0,2) and passing the
address of this generated constant as an argument to
subroutine sub, the compiler uses the address of
iconst. When subroutine sub is called, the third
argument receives the address of iconst, resulting
in the modification of this parameter. Because many
f90SQL subroutines are designed to be called with
parameters that can be constants or variable
arguments, this behavior might affect your programs.

This does not mean you cannot use optimization when

calling f9SQL subroutines. However, if your main
program is compiled using the default optimization,
you must be careful to avoid passing literal
constants as arguments to f90SQL subroutines with
intent(out) or intent(inout) to reduce the chance
of other constants with similar value and type
becoming unexpectedly modified.

The manual included in your distribution of f90SQL

clearly indicates the type of the arguments passed
to each subroutine, as well as their intent
(in, out or inout). As a general rule-of-thumb, if
you want to compile your code with optimization
enabled, you must use variables for all arguments
for which f90SQL subroutines might return values
(i.e. those arguments indicated as intent(out),
intent(inout) or with no indication of intent, as
described in the f90SQL Reference).

For LF95 ver. 5.5 and above, you can use compiler
switch -pca (Protect Constant Arguments) to avoid
the side-effects described above.

Release notes for f90SQL-Lite

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

IMPORTANT: These notes apply only to

f90SQL-Lite users.

f90SQL-Lite and f90SQL-Pro share most of their

functionality. Because of this, both versions are
distributed with the same manual, which describes
f90SQL-Pro. f90SQL-Lite, however, has some
limitations that are not present in f90SQL-Pro.
This section contains a description of these
limitations.

1. Functions and subroutines included in

f90SQL-Pro but not available in f90SQL-Lite:

The following functions and subroutines are not

available in f90SQL-Lite (possible workarounds
are included in parenthesis)

- f90SQLDriverConnect (Use f90SQLConnect instead)

- f90SQLBrowseConnect (Use f90SQLConnect instead)
- f90SQLGetDescField (None, descriptors rarely
need to be used)
- f90SQLGetDescRec (None, descriptors rarely need
to be used)
- f90SQLSetDescField (None, descriptors rarely
need to be used)
- f90SQLSetDescRec (None, descriptors rarely need
to be used)
- f90SQLCopyDesc (None, descriptors rarely need
to be used)
- f90SQLBindParameter (Include parameter values
directly in your query string)
- f90SQLPrepare (Use f90SQLExecDirect instead)
- f90SQLExecute (Use f90SQLExecDirect instead)
- f90SQLDescribeParam (None)
- f90SQLNumParams (None)
- f90SQLParamData (Include parameter values
directly in your query string)
- f90SQLPutData (None)
- f90SQLGetData (None. Do no attempt to read long
data with f90SQL-Lite)
- f90SQLSetPos (None. f90SQL-Lite only allows
forward reading of record sets)
- f90SQLBulkOperations (None)
- f90SQLLenBinaryAttr (None)
- f90SQLLenDataAtExec (None)

2. f90SQL-Lite limitations in the size of record

sets:

f90SQL-Lite is optimized for small record sets.

Because of this, f90SQL-Lite limits the number
of rows in a record set to about 128. However,
this number is not exact.

Attempts to fetch more than 128 rows

will return the value SQL_NO_IMPLEMENTED
in argument iRet. Attempts to fetch data past the
number of rows naturally returned by a query
return SQL_NO_DATA in iRet. You can use these
two constants to discern when you have reached the
natural end of a record set, or if your record set is
larger but you have reached the row-limit imposed
by f90SQL-Lite. A workaround to the 128-row
limitation in f90SQL-Lite is to perform multiple
sequential queries, each query targeting a portion
of the needed data. You must release and reallocate
the statement handle between each query.

f90SQL-Pro has been optimized to handle large

record sets with a small memory footprint. It
does not have any limitations in the number of
rows that can be fetched.
3. f90SQL-Lite limitations in the fetch direction
of record sets:

In f90SQL-Lite, subroutine f90SQLFetchScroll can

only be called with SQL_FETCH_NEXT for the fetch
orientation argument. Attempts to call
f90SQLFetchScroll with an orientation other than
SQL_FETCH_NEXT will fail and return
SQL_NO_IMPLEMENTED in iRet.

f90SQL-Pro allows all the other options for

f90SQLFetchScroll (i.e. SQL_FETCH_PRIOR,
SQL_FETCH_FIRST, SQL_FETCH_LAST,
SQL_FETCH_ABSOLUTE,
SQL_FETCH_RELATIVE and
SQL_FETCH_BOOKMARK).

4. f90SQL-Lite limitations on statement attributes:

f90SQLSetStmtAttr does not accept the following

attribute arguments (you cannot change their
values):

SQL_ATTR_APP_PARAM_DESC,
SQL_ATTR_ASYNC_ENABLE,
SQL_ATTR_CURSOR_SCROLLABLE,
SQL_ATTR_PARAM_BIND_OFFSET_PTR,
SQL_ATTR_PARAM_BIND_TYPE,
SQL_ATTR_PARAM_OPERATION_PTR,
SQL_ATTR_PARAM_STATUS_PTR,
SQL_ATTR_PARAMS_PROCESSED_PTR,
SQL_ATTR_PARAMSET_SIZE, and
SQL_ATTR_ROW_OPERATION_PTR.

Attempts to set any of these attributes will

return SQL_NO_IMPLEMENTED in iRet. You
can, however, review the value of any of these
attributes using f90SQLGetStmtAttr.

f90SQL-Pro does not have any of these limitations.

5. f90SQL-Lite limitations in the number of

concurrent handles and connections:

f90SQL-Lite is optimized to work with just one

database connection. Because of this f90SQL-Lite
only allows one environment handle, one connection
handle and one statement handle to be functional
at any given time. Attempts to allocate more
handles will return SQL_NO_IMPLEMENTED
in argument iRet.

f90SQL-Lite only allows you to open a single

connection to a data source at any given time,
although you may open more than one connection in
a single program.

f90SQL-Pro is optimized to handle many open

database connections at the same time. It does not
have any limitations in the number of connections
you can open.

6. f90SQL-Lite limitation in the number of calls

to f90SQLExecDirect:

f90SQL-Lite limits to 100 the number of calls made

to f90SQLExecDirect using the same statement
handle. The counter is reset each time you
deallocate the statement handle, so your programs
can make more than 100 calls to f90SQLExecDirect
provided you deallocate/reallocate the statement
handle every 100 calls.

f90SQL-Pro does not have any of these limitations.

7. Some example programs do not compile with

f90SQL-Lite:

Several of the example programs included in the

f90SQL distribution are demonstrations of
features available only in f90SQL-Pro. If you
attempt to compile these examples using
f90SQL-Lite you will get error messages indicating
that some external subroutines could not be found.
For some of these cases, we have provided
workarounds that can be compiled using
LF95_MakeLite.bat.

The following examples will not compile with

f90SQL-Lite:

Example51: Demonstrates the use of concurrent

connections. f90SQL-Lite is not capable of this.

Example54: Demonstrates the use of parameterized

queries and prepared statements. f90SQL-Lite does
not support these two options.

Example57: Works only partially because f90SQL-

lite can fetch only in the forward direction.

Example58: Demonstrates the use of queries with

parameters, but f90SQL-Lite does not support
parameterized queries.

Example59: Demonstrates how to update records

using f90SQLSetPos. f90SQL-Lite does not support
this instruction.

Example61: Demonstrates the use of PutData to

update long binary fields. f90SQL-Lite does not
support this instruction.

Example62: Demonstrates column-wise binding of

parameters. f90SQL-Lite does not support this
option.

The following examples have been provided with

workarounds that will compile with f90SQL-Lite:
Example52, Example53, ExcelRead and ExcelWrite.

All other examples work fine with f90SQL-Lite.

Upgrading to f90SQL-Pro
=======================

If you are a user of f90SQL-Lite and want to upgrade

to f90SQL-Pro, check Lahey Computer System's
web page for prices, availability, and international
resellers in your country.

Contacting Lahey Computer Systems, Inc.

=======================================
865 Tahoe Blvd.
P.O. Box 6091
Incline Village, NV 89450
800-548-4778
775-831-2500
775-831-8123 Fax
http://www.lahey.com

Contacting Canaima Software, Inc.

=================================
P.O. Box 13162
La Jolla, CA. 92039 - USA
Tel/Fax: (619) 233-6831
http://www.canaimasoft.com
e-mail: support@canaimasoft.com

Copyrights and trademarks:

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

f90SQL and its logo are trademarks of Canaima

Software, Inc.

f90SQL, f90SQL-Lite and f90SQL-Pro are

Copyright 1998-2000, Canaima Software, Inc.

Windows, Windows 95 and Windows NT, ODBC,

Microsoft Access, Excel and Microsoft SQL-Server
are trademarks of Microsoft Corporation.

Oracle is a trademark of Oracle Corporation.

Lahey, Lahey Fortran 95, LF95, Lahey Fortran 90,

and LF90 are trademarks of Lahey Computer
Systems Corporation.

All other brands and names are the trademarks

of their respective holders.