To insure a successful installation, check that you have handled the issues listed below before you begin installation.
The installer checks for free space to use for temporary files during installation. It requires 250MB on the SYSTEM drive (where the operating system is installed) and 225MB on the TEMP drive (where the %TEMP% environment variable is pointing). If the full product is installed, the maximum space required during installation will be about 500MB and the final disk space usage will be about 300MB when the temporary files are deleted.
The installer must find drive C: or it will issue an error message. If your
system does not contain a C: drive, use the SUBST command to map virtual
drive C: as an existing drive before you start the installer. For example, run
the DOS command SUBST C: D: which will create a virtual C: drive that points to
your D: drive.
Databases from version 7.x and earlier of SQLBase have physical differences that require migration. It is strongly recommended that you back up such databases with the UNLOAD command before installing version 8.5. Full information about the migration process is found in Migrating Databases to SQLBase 8.5. Even after such migration, you may find that some additional steps are needed before your existing databases work properly in version 8.5, particularly if you had been using National Language Support or user ID SYSREP, or you plan to run earlier versions of SQLBase simultaneously with version 8.5. For more information about potential extra steps, see Additional Migration Notes.
Version 8.x of SQLBase requires (and installs) MDAC 2.7 to support the OLE DB provider. MDAC, in turn, requires Internet Explorer 4.01 or higher to be already installed prior to the SQLBase installation.
There are several other dependencies between SQLBase and various Windows components. SQLBase 8.5 will install successfully, but will not run correctly until these dependencies are satisfied. You can find details in Compatibility and System Requirements.
If you install SQLConsole 8.5 without installing the other SQLBase components, then install the other components at a later time, the SQL.INI file may contain only information for the single-user edition of SQLBase (dbnt1sv.exe). If you allow this file to persist unchanged, you will encounter error messages when trying to run other editions of SQLBase (5-user, unlimited, etc.). To prevent this, you can edit SQL.INI manually after the second install; or you can watch for the advisory message during the second install which warns about overwriting SQL.INI and confirm that you want to overwrite.
To view the most recent versions of online books, please visit our web site at: http://www.guptaworldwide.com/tech/books_online.asp
SQLBase 8.5 contains significant structural incompatibilities with versions 7.x and earlier of SQLBase databases. Therefore a “conversion process” must occur in these cases. For databases from version 7.x and earlier, this process can be accomplished in one of two ways:
The auto-conversion has the following restrictions, and will irreparably fail and harm your database if these restrictions are violated:
Your database is now converted.
(See also the following sections, “What’s new in SQLBase 8.1” and "What's new in SQLBase 8.0".)
The features described briefly in this section are documented in greater detail in the book "SQLBase Guide to New Features" (sqlbnew.pdf). Gupta recommends reading this book before installation of SQLBase 8.5.
Version 8.5 prompts you for a server name upon installation. This name must begin with an alpha character and cannot include special characters such as underscore, hyphen or plus. Server names can be managed using SQLBase Management Console. Gupta recommends that you use SMC only to manage these names, since SMC will correctly modify the associated Windows registry entries at the same time.
Each SQLBase 8.5 installation on a computer now uses a separate SQL.INI file. In fact, the file does not even have to be named "SQL.INI" in version 8.5. You have control over the name and path of the SQL.INI file. You can also control the location of binary components required for the server and client. Multiple SQLBase engines can run simultaneously. However, only one copy of SQLBRM.EXE (used for supporting COM+ transactions) can be active at a time.
For simplicity, the SQLBase configuration file continues to be named "SQL.INI" in all relevant documentation, even though your actual file name may be different.
Previous versions of SQLBase wrote information to the HKEY_LOCAL_MACHINE portion of the Windows registry. Version 8.5 writes to HKEY_CURRENT_USER. This means that now the user doing the installation of SQLBase does not need Administrator privileges. In such a case, the SQLBase installation would then be available only to that particular user ID on the machine. However, if SQLBase is to be registered as a Windows service, then the user does need appropriate privileges for doing so.
The multiple installation feature requires several new keywords in SQL.INI. These are ordinarily created in response to your answers during the install process. For more detailed information, see chapter 3 of the "Database Administrator's Guide". The new keywords are AUTOSTARTSERVERPATH and CLIENTRUNTIMEDIR. Keyword SERVERPATH, previously only in the WS32 protocol section, will now also appear in sections SPX32, WSSPX, MPIPE, and APIPE.
To support flexible configuration file names and locations, SQLNGCI.DLL is no longer a part of SQLBase. SQLWNTM.DLL is still provided as a wrapper for backward compatibility for customers who have written client applications in C. However, no SQLBase executables have any dependencies on SQLWNTM.DLL. Actual API code is now located in the new SQLBAPW.DLL module.
Each of the various SQLBase server executables (such as DBNTSRV.EXE) has been
modified to accept a command-line argument, in the form of INI=<configuration filename>,
after the name of the executable. This
argument is the name of the configuration file (always
named SQL.INI in previous versions.) If you install SQLBase as a Windows service
and then browse its service information, you will see a command line constructed
in this manner. If you manually start SQLBase without specifying that command-line
argument, the server will presume that the configuration file is named SQL.INI and
that it is located in the same directory as the server executable. The new feature
"Register" in SQLBase Management Console is designed to construct a properly
formatted command line.
The SQLBase API has been enhanced to allow you to call function sqlget with new parameters SQLPCINI (client-side configuration file) and SQLPSINI (server-side configuration file). These are read-only parameters, and can't be set.
SQLTalk has been enhanced to allow you to choose which configuration file to use. This choice is available in a dialog box that is accessed from menu items Options, Session Settings. You can also supply the file name as a command-line argument. Here is an example:
SQLTalk.exe "c:\program files\km.sql" "ini=c:\program files\sql.ini"
This particular example shows a SQL script as the first argument, and the configuration file as the second argument. Both are optional, but if both are used, the script file argument should come first.
Connectivity Administrator has been enhanced to allow you to manage multiple servers on the client side for the local, SPX, and TCP/IP protocols. New right-click menu options on the Connectivity tab allow you to add server names to a specific protocol and to invoke the Properties dialog for a client, individual server name, or protocol. The keywords AUTOSTARTSERVERPATH and CLIENTRUNTIMEDIR are accessible through these dialogs. On the Server tab, it displays all installed servers and provides property dialogs for them.
The SQLBase OLEDB Data Provider now supports optionally specifying a configuration file through property DBPROP_INIT_PROVIDERSTRING in the following format:
INI=<Configuration File Name with full path>
(You may also specify the string in the UDL/Data Link property dialog box. The configuration file name with the above format could be entered as a value for "Extended Properties" in the "All" page.) Using these features allows you to connect via OLEDB to databases on more than one server machine. Earlier versions of the provider permitted connections to only one server machine.
The SQLBase .NET Data Provider now allows you to specify a configuration filename in the connection string. An example of such a connection string is:
SQLBaseConnection conn = new SQLBaseConnection("data source=island;
uid=sysadm; pwd=sysadm; ini=c:\\sqlbase\\sql.ini");
The SQLBase ODBC Driver "Gupta SQLBase Data Source Properties" dialog box has been extended to allow you to optionally enter the configuration filename.
Version 8.5 offers much more complete support for the SQL99 join syntax. Supported elements that are new to this version include:
These new keywords can potentially conflict with the names of tables, views, columns, or other database objects in your existing databases. For this reason, SQL99 compatibility is optional, not automatic, for a specific SQLBase server. You can select it at installation, select/deselect it later through Connectivity Administrator, or control it using the new SQL.INI keyword "AnsiJoinSyntax".
If you are unsure whether these new keywords are present in your existing databases, you can use the Keyword Check, new in version 8.5, to analyze those databases and detect potential keyword conflicts. You will find Keyword Check in the Gupta, SQLBase program group in the Start menu.
The SQLBase API has been enhanced so that client applications can query whether the server to which they are connected is currently supporting SQL99 compatibility, and use this information to construct their queries.
ODBC Driver property DBPROP_SQLSUPPORT value returned has been changed. For versions prior to 8.5 it always returns 0. For version 8.5, if the server is running with AnsiJoinSyntax value set to 1, the value returned will be DBPROPVAL_SQL_ANSI92_ENTRY; otherwise it will be 0.
ODBC Driver property SQL_OJ_CAPABILITIES value returned has been changed. If the server is running with ANSIJoinSyntax value set to 1, then its value will have the additional bit mask SQL_OJ_NESTED.
For backward compatibility, SQLBase supports multiple forms of syntax in database queries. If you use the SQL99 syntax, you can specify multiple outer joins in a query. The SQLBase native syntax supports only a single outer join in a query.
New function @COALESCE returns the first non-null value found in a list of two or more values. The values in the list can be mixed datatypes. The return value's datatype matches the datatype of the first value in the list. If every value in the list is null, the function returns NULL.
The OLE DB Data Provider datatypes have changed. The provider data type "long" has been renamed to "long varchar" and the type has been changed from DBTYPE_BYTES to DBTYPE_STR. The datatype for "number" has been changed from DBTYPE_NUMERIC to DBTYPE_R8, to be consistent with the SQLBASE ODBC driver. FLOAT type has been removed from the providers list. The default value of property DBPROP_UPDATABILITY has been set to 0. Client applications should set the value to one or more of DBPROPVAL_UP_CHANGE | DBPROPVAL_UP_DELETE | DBPROPVAL_UP_INSERT. Otherwise the methods return DB_E_NOTSUPPORTED depending on the value set.
Enhancements to the OLEDB Data Provider now support specifying a configuration
file before connecting to the data source . To make use of this feature, new
property TDataSource.DBPROP_INIT_PROVIDERSTRING must be given a valid string
value. The format of this string is:
INI=<Configuration File Name with full path>;ims=<Value>;oms=<Value>
ims (input message buffer) and oms (output message buffer) must have values between
1 and 32000.
OLEDB Provider and .NET Data Provider now support ODBC escape sequences in the SQL statement.
Enhancements to the .NET Data Provider now support scrollable result sets. To
make use of this feature, the new property SQLBaseCommand.ResultSetMode must be
set to TRUE. The SQLBaseDataReader object now implements interface IEnumerable, with
a single method, GetEnumerator, which returns an IEnumerator object. That object
has methods MoveNext and Reset, and get/set property RowPos (current row of result
set), which allow you to move to a specific row in the result set.
Before the JDBC sample programs can be run, an additional SQL script must be run against the ISLAND sample database. For more information, see README.HTML in the samples/jdbc folder beneath your database server install folder.
The JDBC driver does not yet support the increased length of identifiers in SQLBase 8.x. You will only be able to connect to databases with names of 8 or fewer characters. Similarly, identifiers such as table and column names are limited to 18 characters.
JDBC Driver setTransactionIsolation() functional behavior has been changed to map isolation as given below:
| TRANSACTION_NONE | "RL" |
| TRANSACTION_REPEATABLE_READ | "RR" |
| TRANSACTION_READ_COMMITTED | "CS" |
| TRANSACTION_SERIALIZABLE | Not Supported |
| TRANSACTION_READ_UNCOMMITTED | Not Supported |
JDBC Driver connect URL has been extended to specify the SQLBase IMS (InputMessageSize) and OMS(OutputMessageSize) values. These are optional. The new URL format will look like:
jdbc:sqlbase://localhost[:2157]/island;ims=ddddd;oms=ddddd
The value of ddddd should be greater than zero and less than or equal to 32000. If the value specified does not fall in this range, then default values IMS=2000 and OMS=1000 are set.
The method of handling the CLIENTNAME keyword in the configuration file has changed in SQLBase 8.5. The value of CLIENTNAME defaults to the name of the machine on which the install is running. However, if that name exceeded 12 characters in previous versions, the SQLBase API issued an error message and stopped. In version 8.5, the API simply truncates the name to 12 characters and proceeds without issuing an error message.
The behavior of the IS NULL clause in a query, when that query contains outer joins, has been corrected. Previously the "IS NULL" clause, when used against the "outer" table, created a result set where all rows of the other table were present, and all column values for the outer table, matching or not, were null. Version 8.5 now returns a correct result set.
The method of searching for a database has changed in version 8.5. The DBDIR directive, if used in SQL.INI or in a command-line argument, causes the scope of the search to be more limited than it was in earlier versions. If you use DBDIR the search will ignore the following folders:
Note that you can still cause these folders to be searched, but only if you avoid using the DBDIR directive, or if you explicitly name these folders as part of the DBDIR directive. There are complete descriptions of the old and new search algorithms under keyword DBDIR in Chapter 3 of the Database Administrator's Guide.
This section is intended for customers moving from version 7.x or earlier of SQLBase, to version 8.5.
The SQLBase 8 server and client have important considerations regarding backward compatibility. An older SQLBase client (SQLBase 7.x) can connect to SQLBase 8. Certainly, no new features of SQLBase 8 would be available to applications still using the SQLBase 7.x client.
This version of SQLBase requires Microsoft Management Console (MMC) version
1.1 or higher be installed for the SQLBase Management Console (SMC) snap-in to
work. MMC is not a part of the Windows 98 and Windows ME operating systems;
however, users of those operating systems can download MMC from the Microsoft
web site.:
http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com/support/mmc/mmcdown.asp
To properly use the SQLBase 8.5 .NET data provider, you must have installed
the .NET Framework SDK version 1.1. For Windows XP machines, you should
have installed Service Pack 1 for Windows XP. You can download the most current
.NET framework redistributable components at:
http://msdn.microsoft.com/library/default.asp?url=/downloads/list/netdevframework.asp
If you are still using version 1.0 of the .NET Framework SDK, and you wish to use the SQLBase .NET Data Provider in that environment, you must follow the instructions provided in this link: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcontargetingnetframeworkversion.asp>
The SQLBase 8.5 .NET data provider has undergone continuing enhancements. If you have previously installed an earlier version of the provider (including the one supplied with the 8.5 beta), you must insure that your applications are using the latest version of the provider, not an earlier version. The best way to do this is to edit a project that uses the provider, drop the reference to Gupta.SQLBase.Data, then add that reference to the project again. A second option is to copy the newest Gupta.SQLBase.DLL into the physical locations to which those earlier references pointed.
To deploy applications that use the SQLBase 8.5 .NET data provider, you must
copy the provider DLL (Gupta.SQLBase.Data.DLL) into either the same folder as
the application, or into the Global Assembly Cache that is part of the .NET
Framework. For information on how to install that DLL into the Global Assembly
Cache, visit the Microsoft web site that explains the cache and methods of
installation:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconinstallingassemblyintoglobalassemblycache.asp
If you were using version 7.5.1 PTF3, version 7.6, version 8.0, or version 8.1, and the National Language Support feature was being used in those versions, the sequence of your indexes will be incompatible with version 8.5. To resolve this, you can drop and rebuild all your indexes, or perform an UNLOAD and LOAD on the affected databases. This UNLOAD can be done either before or after the conversion to version 8.5.
The special user ID SYSREP, present in earlier versions of SQLBase, is not present in version 8.5 starter databases (START.DBS). If you utilize a database UNLOAD created from a version prior to 8.5, and that unload file contains objects owned by SYSREP, then you must perform a GRANT CONNECT and GRANT DBA prior to using the UNLOAD file with an 8.5 starter database.
The default program directory for SQLBase has changed in version 8.5. The directory was previously "C:\Program Files\Gupta" (presuming you were installing to drive C:). It is now "C:\Program Files\Gupta\SQLBase 850".
SQLBase Management Console, a client application, always uses the same configuration file as the server itself. For SMC to work properly, that configuration file must contain at least a minimal [win32client] section, with the appropriate COMDLL entries matching the protocols on which the server is listening.
The configuration file keyword cache has a minimum value of 15 (pages) and a maximum
value of 1,000,000. In earlier versions of SQLBase, an invalid value for cache
would be ignored, but in version 8.5, an invalid value will actually prevent the
server from starting.
If you wish to use SQLWSSPX or SQLSPX32 protocols, you must specify the name of the server you are connecting to. In previous versions, you did not need to provide this information. If the server name is not provided with version 8.5 WSSPX and SPX32 DLLs, they will not be able to connect.
The server name should be provided in the corresponding sections
[WIN32CLIENT.WSSPX] and [WIN32CLIENT.SPX32] using the keyword SERVERPATH. For example:
[WIN32CLIENT.WSSPX]
serverpath=server1
[WIN32CLIENT.SPX32]
serverpath=server1
If SQL99 ANSI syntax is used in a query, then the value of keyword ORACLEOUTERJOIN is irrelevant. That configuration file keyword only affects the results of queries that are constructed in native SQLBase syntax.
If your computer has an earlier version of SQLBase presently installed, there are potential conflicts involved in installing version 8.5 using some of the prompts presented by the installer. Note these steps to avoid such conflicts.
The keyword "limitnlscompares", available in the beta version, is not supported in the final SQLBase 8.5 release.
Query features CROSS JOIN and FULL OUTER JOIN are not supported in the final SQLBase 8.5 release.
The SQLBase installer inserts information into the PATH environment variable during installation. Upon uninstallation, this information is not removed, and if SQLBase is reinstalled later, the information will be inserted a second time into the PATH. If you uninstall and reinstall several times, you may want to edit the PATH to eliminate duplicates and reduce its string size.
PowerBuilder uses quoted identifiers when constructing SQL commands. If you are using the SYSADM user ID against SQLBase, but you enter it as lowercase sysadm, that lowercase value will be passed to SQLBase in quotes, which prevents it from being recognized as equivalent to SYSADM. SQLBase will return a "does not exist" error message for the user ID. To prevent this, you must use uppercase when keying in the user ID in PowerBuilder.
SQLBase Management Console will attempt to refresh the status of a server onscreen when you invoke the Stop action. If the server stops within a normal time, status will be refreshed automatically. However, if the server takes a long time to stop, the status will not be refreshed unless you invoke Refresh manually. This is a feature of Microsoft Mangement Console and is outside Gupta's control. Note that Windows 98 and Windows ME will also require manual refresh after a change in status.
SQL.INI keyword sortcache has a maximum value of 65535, not 1,000,000 as documented
in previous versions. In previous versions, setting this keyword to an invalid
value would cause it to be ignored by the server. In version 8.5, an invalid value
will actually prevent the server from starting and will display an error.
(Setting this value too high can adversely affect performance. Gupta recommends
leaving this setting at the default value of 2000.)
The API function sqlget and the SQLTalk command SQLGET will not display a CACHE
value larger than 65535. It is possible to set the value of CACHE in SQL.INI to a
maximum of 1,000,000, and the server will implement this larger value, but the
API to fetch the parameter still uses the smaller limit from older versions.
SQL.INI keywords autostartserverpath and clientruntimedir
may contain values with embedded spaces. If you are editing
SQL.INI yourself, be certain that a value containing spaces is enclosed by double
quotes. Such a value, without double quotes, will yield confusing results in some
tools such as Connectivity Administrator. If you are editing these keywords with
Connectivity Administrator, do not add quotes - it will do so for you.
In the JDBC Driver connect string there are parameters for ims (input message buffer size) and oms (output message buffer size). When the ims and oms parameter values are equal to zero, then the values are set to the default values (2000 and 1000). But when the ims parameter is requested with a non-zero value of less than 28, the value is instead set to the default value of 2000. When the oms parameter is requested with a non-zero value of less than 37, it is instead set to the default value of 1000.
Copyright © Gupta Technologies LLC. Gupta, the Gupta logo, Centura, and all Gupta products are licensed or registered trademarks of Gupta Technologies, LLC., All other products are trademarks or registered trademarks of their respective owners. Copyright © 2001, 2002, and 2003 Gupta Technologies