SQLBase Starter Guide

20-2905-1005

Trademarks
GUPTA, SQLBase, SQLRouter, Team Developer,and, and SQLTalk are trademarks of Gupta Technologies, LLC registered in the United States and/or other countries. SQLWindows is a registered trademark of Microsoft Corporation, and is used under license to Gupta Technologies, LLC. Centura and Centura Software are registered trademarks of Centura Software Corporation, and are used under license to Gupta Technologies, LLC. Team Object Manager, Web Developer, QuickObjects, Object Nationalizer, Report Builder, Connectivity Administrator, Development Kit, Component Development Kit, SQLBase Resource Manager, and SQLConsole are names of products from of Gupta Technologies, LLC. Adobe is a registered trademark of Adobe Systems, Incorporated .in the United States and/or other countries. IBM, OS/2, and AIX are registered trademarks of International Business Machines Corporation in the United States and/or other countries. NetBIOS/IX is a trademark of Micro Computer Systems, Inc. Linux is the registered trademark of Linus Torvalds. in the United States and other countries. Red Hat is a registered trademark of Red Hat, Incorporated. in the United States and other countries. Novell and NetWare are registered trademarks of Novell, Inc. in the United States and other countries. SuSE is a registered trademark of SuSE Linux AG, a Novell business. SOLARIS, JAVA, and all JAVA-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Outlook, PowerPoint, Visual C++, Visual Studio, Internet Explorer, Internet Information Server, MS-DOS, Win 32, Windows, ActiveX, MSDN, SQL Server, and Visual Basic are either registered trademarks or trademarks, and Internet Information Server is a product name, of Microsoft Corporation in the United States of America, and/or other countries, or both. Other company, product, or service names may be trademarks or service marks of others ICU Copyright GUPTA SQLBase incorporates the ICU libraries.
ICU License - ICU 1.8.1 and later COPYRIGHT AND PERMISSION NOTICE Copyright (c) 1995-2003 International Business Machines Corporation and others All rights reserved. Permission is hereby granted,

free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

Copyright
Copyright 1985-2006 by Gupta Technologies LLC. All rights reserved. 20-6245-0001 April 2006

SQLBase Starter Guide

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-i Who should read this manual . . . . . . . . . . . . . . . . 1-ii What is in this manual. . . . . . . . . . . . . . . . . . . . . . 1-ii Notation conventions . . . . . . . . . . . . . . . . . . . . . . 1-ii Other helpful resources . . . . . . . . . . . . . . . . . . . . 1-iii Send comments to.... . . . . . . . . . . . . . . . . . . . . . . 1-v

1 Introducing SQLBase

. . . . . . . . . . . . . . . . . . 1-1

SQLBase platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 SQLBase packages . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 SQLBase Server for Windows . . . . . . . . . . . . . . . 1-2 SQLBase Desktop . . . . . . . . . . . . . . . . . . . . . . . . 1-3 SQLBase Server for Linux . . . . . . . . . . . . . . . . . . 1-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Helpful resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Send comments to.... . . . . . . . . . . . . . . . . . . . . . . 1-7

2 Configuring SQLBase for Windows

. . . 2-1

Connectivity Administrator . . . . . . . . . . . . . . . . . . . . . 2-2 SQL.INI file configuration settings . . . . . . . . . . . . . . . . 2-3 Do I need to configure sql.ini? . . . . . . . . . . . . . . . 2-3 How SQLBase finds sql.ini . . . . . . . . . . . . . . . . . . 2-4 Running SQLBase Server as a Windows service . . . . 2-5

3 Configuring SQLBase for Linux . . . . . . . . 3-1

sql.ini file configuration settings . . . . . . . . . . . . . . . . . 3-2 How SQLBase finds sql.ini . . . . . . . . . . . . . . . . . . 3-2 Do I need to configure sql.ini? . . . . . . . . . . . . . . . 3-3

SQLBase Starter Guide

-5

4 Running SQLBase

. . . . . . . . . . . . . . . . . . . . . 4-1

Starting and stopping the server . . . . . . . . . . . . . . . . . 4-2 Windows NT, 2000, Server 2003, and Windows XP4-2 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Uninstalling SQLBase . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 On Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 On Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

5 What now? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Finishing your configuration . . . . . . . . . . . . . . . . . . . . 5-6 Testing your installation . . . . . . . . . . . . . . . . . . . . . . . 5-6 SQLTalk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 Using drivers and data providers . . . . . . . . . . . . . . . 5-11 Client applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11 Linux considerations . . . . . . . . . . . . . . . . . . . . . . 5-11 Loading database files into SQLBase . . . . . . . . . . . . 5-12

SQLBase Starter Guide

Preface
This book contains instructions for configuring Gupta SQLBase. Topics include: Configuring your server and clients Starting and stopping the server Testing the client/server connection using SQLTalk Using National Language Support and database drivers and data providers Loading data into your database

SQLBase Starter Guide

-i

Preface

Who should read this manual

The SQLBase Starter Guide is intended for: Application Developers building client applications that access databases using frontend products like SQLTalk, SQLWindows, and the SQL/API. Database Administrators (DBAs) performing day-to-day operation and maintenance of the database. System Administrators maintaining and configuring the operating system. This includes maintaining operating system access security. Network Administrators maintaining and configuring the network. This includes the network access security, logical and physical network address assignment, and network resources allocations.

What is in this manual

This manual is organized by task into the following chapters. There is also an index at the end of the manual.
1 2 3 4 5

Introducing SQLBase Configuring SQLBase for Windows Configuring SQLBase for Linux Running SQLBase
What now?

Whats new in SQLBase, platforms, SQLBase packages Connectivity Administrator, SQL.INI file, sql.ini file configuration Starting and stopping the SQLBase Server, uninstalling SQLBase. Testing your installation with SQLTalk, National Language Support, loading database files into SQLBase

Notation conventions
The table below shows the notation conventions that this manual uses.
Notation User bold type Courier 9 sql.ini MAPDLL.EXE Warning: Precaution Explanation The end-user of applications that you write Menu items, push buttons, and field names. Things that you select. Keyboard keys that you press. Code example Program names and file names

-ii

SQLBase Starter Guide

Notation Important: Note: Alt+1 Vital information Supplemental information

Explanation

A plus sign between key names means to press and hold down the first key while you press the second key

Other helpful resources

Gupta Books Online. The Gupta document suite is available online. This document collection lets you perform full-text indexed searches across the entire document suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the Gupta Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group. Online Help. This is an extensive context-sensitive online help system. The online help offers a quick way to find information on topics including menu items, functions, messages, and objects. World Wide Web. Gupta Technologies World Wide Web site contains information about Gupta Technologies LLCs partners, products, sales, support, training, and users. The URL is http://www.guptaworldwide.com. To access Gupta technical services on the Web, go to http:// www.guptaworldwide.com/tech/support/default.asp. This section of our Web site is a valuable resource for customers with technical support issues, and addresses a variety of topics and services, including technical support case status, commonly asked questions, access to Guptas Online Newsgroups, links to Shareware tools, product bulletins, white papers, and downloadable product updates. For information on training, including course descriptions, class schedules, and Certified Training Partners, go to http://www.guptaworldwide.com/partners/ training.asp. SQLBase Documentation Set. SQLBase Database Administrators Guide This book contains information for DBAs creating and maintaining SQLBase databases. SQLBase SQL Language Reference This book describes the SQL commands that you can execute in applications such as SQLTalk. SQLBase SQLTalk Command Reference

SQLBase Starter Guide

-iii

Preface

This book describes the SQLTalk interface and commands. SQLTalk Help System This online documentation provides SQLBase users with a context-sensitive help system. SQLBase SQL Application Programming Interface Reference This book is for application developers using Guptas SQL/API to write programs that access SQLBase databases. SQLConsole Guide This book describes how to use SQLConsole, an online database monitoring and maintenance tool. SQLConsole also has an extensive on-line help facility.

-iv

SQLBase Starter Guide

Send comments to...

Anyone reading this manual can contribute to it. If you have any comments or suggestions, please send them to: Technical Publications Department Gupta Technologies LLC 975 Island Drive Redwood Shores, CA 94065 or send email, with comments or suggestions to: techpubs@guptaworldwide.com

SQLBase Starter Guide

-v

SQLBase Starter Guide

Chapter 1

Introducing SQLBase
This chapter offers a general discussion of some of the features of SQLBase. Additionally, it describes the two SQLBase packages, SQLBase Server and SQLBase Desktop, and their respective components. Each of the topics mentioned throughout this book is covered in far greater detail in other books that make up the SQLBase Books Online collection. Be sure to check there for more information.

SQLBase platforms
SQLBase supports the following platforms: Windows 2000 , XP, or Server 2003 SUSE Linux and Red Hat Linux (see file certify.htm for exact versions)

SQLBase supports multiple users with remote communication through a network as well as local communication.

SQLBase Starter Guide

1--1

Chapter 1

Introducing SQLBase

SQLBase packages
SQLBase comes with a single installation package that installs the version of SQLBase that you have licensed. GUPTA offers two SQLBase versions: SQLBase Desktop (single-user) and SQLBase Server (multi-user). They are available in three editions offering various levels of security: Standard with no encryption Medium (56-bit) encryption High (128-bit) encryption (available only as an Embedded Deployment Kit with the multi-user version)

This section describes each of these versions and their components.

SQLBase Server for Windows

SQLBase Server is a multi-user database server that runs on Windows 2000, XP, and Server 2003. SQLBase for Windows is licensed based on concurrent user connections and comes in various user bands; for example: 5-user, 50-user, and unlimited users. The following table describes the options in the SQLBase Server package:
Component option Windows 32-bit Server Description SQLBase Server is a 32 bit, multi-user database server program that can communicate both with local and remote client applications. This option also includes the Connectivity Administrator and SQLBase Management Console (SMC). Also included is SQLBase Resource Manager, with support for COM+ transactions. Client Software The Client Software contains the following components:

Communication libraries
Front-end programs communicate with the server through support programs called communication libraries. Connectivity Administrator (32 bit clients and servers only) A tool for editing your SQL.INI file. DBError A utility for looking up SQLBase error messages. Provides the error text, reason for the error, and suggested solutions. This is typically used during the application development process. SQL/API The application programming interface. Included with the SQL/API is sample source code you can use to learn how to utilize the SQL/API.

1-2

SQLBase Starter Guide

SQLBase packages

Component option Client Software (continued) SQLTalk

Description

A front-end interface for SQL. You can run SQLTalk from Windows 2000, Server 2003, and XP; Red Hat Enterprise (Workstation and Server) 3.0 and 4.0,; Red Hat Desktop 4.0; SUSE Enterprise Server 9; and SUSE Professional 9.2 and 9.3. Release notes and certification description

SQLConsole DBA utility

SQLConsole is a database administration and monitoring tool for SQLBase Servers and databases. From a single Windows desktop, SQLConsole lets you perform administrative tasks for a local SQLBase server and all the SQLBase servers on a network. The GUPTA Books Online collection is created using Adobe Acrobat and lets you perform full-text indexed searches across the entire document suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the GUPTA Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group.

GUPTA Books Online

SQLBase ODBC Driver SQLBase OLE DB Data Provider SQLBase .NET Data Provider SQLBase JDBC Driver C Programmers interface

An industry-standard ODBC 3.5 Driver, fully supporting multi-threaded applications. An industry-standard set of COM objects providing access to SQLBase databases. Supports COM+ (MTS) distributed transactions. An industry-standard set of COM objects providing access to SQLBase databases for development tools that use the .NET SDK Framework. A set of Java classes allowing access to SQLBase from Java applets and applications. SQLBase C example programs and interface.

SQLBase Desktop
SQLBase Desktop is a single-user database server that runs on Windows 2000, XP, and Server 2003. It is licensed by machine, and comes in various licensing packs,

SQLBase Starter Guide

1-3

Chapter 1

Introducing SQLBase

such as 5- and 25-machine packs. The following table describes the installation options in the SQLBase Desktop package:
Component option Desktop Server Description SQLBase Server is a 32-bit database server program that runs under Windows 2000, XP, and Server 2003. It can communicate both with local and remote client applications. Client software includes:

Communication libraries
Front-end programs communicate with the server through support programs called communication libraries. Connectivity Administrator A tool for editing your SQL.INI file. SQL/API The application programming interface. Included with the SQL/API is sample source code you can run to learn how the SQL/API handles certain SQLBase features. SQLTalk A front-end interface for SQL. You can run SQLTalk from Windows 2000, Server 2003, and XP; Red Hat Enterprise (Workstation and Server) 3.0 and 4.0,; Red Hat Desktop 4.0; SUSE Enterprise Server 9; and SUSE Professional 9.2 and 9.3. Release notes and certification description SQLConsole DBA Utility SQLConsole is a database administration and monitoring tool for SQLBase servers and databases. From a single Windows desktop, SQLConsole lets you perform administrative tasks for a local SQLBase server and all the SQLBase servers on a network. Contains the SQL/API software and SQLBase ++. The SQL/API is a language interface that lets you develop a client application that uses SQL. You embed SQL/API functions within your C program, which allows you to use SQL without giving up the power and flexibility of either programming language. You can create and run SQL/API applications on any of the server platforms. SQLBase ++ is a C++ based source library for application development. SQLBase ODBC Driver SQLBase OLE DB Data Provider SQLBase .NET Data Provider A standard ODBC 3.5 driver that fully supports multi-threaded applications. An industry-standard set of COM objects providing access to SQLBase databases. Supports COM+ (MTS) distributed transactions. An industry-standard set of COM objects providing access to SQLBase databases for development tools that use the .NET SDK Framework.

SQLBase Programmers Interface

1-4

SQLBase Starter Guide

SQLBase packages

Component option SQLBase JDBC Driver GUPTA Books Online

Description A set of Java classes allowing access to SQLBase from Java applets and applications. The GUPTA Books Online collection is created using Adobe Acrobat and lets you perform full-text indexed searches across the entire document suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the GUPTA Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group.

SQLBase Server for Linux

SQLBase Server is a multi-user database server that runs on Red Hat Linux and SUSE Linux (see release notes for exact versions supported.) The following table describes the options in the SQLBase Server package:
Component option Linux 32-bit Server Client Software Description SQLBase Server is a 32-bit, multi-user database server program that can communicate both with local and remote client applications. The Client Software contains the following components: DBError A utility for looking up SQLBase error messages. Provides the error text, reason for the error, and suggested solutions. This is typically used during the application development process. SQL/API The application programming interface. Included with the SQL/API is sample source code you can use to learn how to utilize the SQL/API. The API binary files also contain communication components to handle TCP/IP communication with the database server. SQLTalk A character-mode front-end interface for SQL. You can run SQLTalk from the Linux command line. Release notes and certification description

SQLBase Starter Guide

1-5

Chapter 1

Introducing SQLBase

Component option GUPTA Books Online

Description The GUPTA Books Online collection is created using Adobe Acrobat and lets you perform full-text indexed searches across the entire document suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection in Windows by selecting the GUPTA Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group.

SQLBase ODBC Driver SQLBase JDBC Driver C Programmers interface

An industry-standard ODBC 3.5 Driver, fully supporting multi-threaded applications. A set of Java classes allowing access to SQLBase from Java applets and applications. SQLBase C example programs and interface.

Helpful resources
GUPTA Books Online. The GUPTA document suite is available online. This document collection lets you perform full-text indexed searches across the entire document suite, navigate the table of contents using the expandable/collapsible browser, or print any chapter. Open the collection by selecting the GUPTA Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group. World Wide Web. GUPTAs world wide Web site contains information about Gupta Technologies partners, products, sales, support, training, and users. The URL is http://www.guptaworldwide.com. The technical services section of our Web site is a valuable resource for customers with technical support issues, and addresses a variety of topics and services, including technical support case status, commonly asked questions, access to GUPTAs online newsgroups, links to shareware tools, product bulletins, white papers, and downloadable product updates. Our Web site also includes information on training, including course descriptions, class schedules, and certified training partners. SQLBase Documentation Set. Guide to Connecting to SQLBase This book contains information about using Gupta database drivers, data

1-6

SQLBase Starter Guide

Helpful resources

providers, and native routers to connect client applications to SQLBase servers. SQLBase Database Administrators Guide This book contains information for DBAs creating and maintaining SQLBase databases. SQLBase SQL Language Reference This book describes the SQL commands that you can execute in applications such as SQLTalk. SQLBase SQLTalk Command Reference This book describes the SQLTalk interface and commands. SQLBase SQL Application Programming Interface Reference This book is for application developers using GUPTAs SQL/API to write programs that access SQLBase databases. SQLConsole Guide This book describes how to use SQLConsole, an Windows-based online database monitoring and maintenance tool. SQLConsole also has an extensive on-line help facility. SQLTalk Help System This online documentation provides SQLBase users with a context-sensitive help system. Topics both specific to SQLTalk and more generally applicable to SQLBase are included. In Windows, access help by pressing F1 within SQLTalk. In Linux, load file index.htm or sqllxtlk.htm into a browser.

Send comments to...

Anyone reading this manual can contribute to it. If you have any comments or suggestions, please send them to: Technical Publications Department Gupta Technologies 975 Island Drive Redwood Shores, CA 94065 or send email, with comments or suggestions to: techpubs@guptaworldwide.com

SQLBase Starter Guide

1-7

Chapter 1

Introducing SQLBase

1-8

SQLBase Starter Guide

SQLBase Starter Guide

Chapter 2

Configuring SQLBase for Windows

This chapter provides information about configuring SQLBase. Topics include: Connectivity Administrator SQL.INI file

SQLBase Starter Guide

2--1

Chapter 2

Configuring SQLBase for Windows

Connectivity Administrator
The Connectivity Administrator lets you edit your SQL.INI file, adding databases and routers. Using this tool, you can set the configuration for SQLBase Server, including: Setting the options for a SQLBase server Enabling and disabling communication protocols Adding or removing a database name Viewing a list of database names

The Connectivity Administrator detects all relevant software installed on your computer, including network protocols and configurations. The automated configuration also sets simple and advanced parameters of the database server. You can configure connectivity for both your client and server during the same Connectivity Administrator session. To configure your server, click the Server tab.

Using the Connectivity Administrator

1. Select Programs, GUPTA, SQLBase 10.0, Connectivity Administrator from the Start menu.

2. 3.

Click the Server tab to show the installed server. Click the + symbol next to the server name to display listening protocols and databases.

The following actions are available when using the Connectivity Administrator. 2--2 SQLBase Starter Guide

SQL.INI file configuration settings

Left-click to select an item Double-click to change properties Right-click to display a menu of connectivity functions

For detailed information about the Connectivity Administrator, read the online help that is provided with this tool.

SQL.INI file configuration settings

GUPTA products read the SQL.INI file at program start-up. The SQL.INI file is the common file containing software configuration settings. Each client and server machine must have a SQL.INI file. Beginning with version 8.5, it is possible to name SQL.INI to any other name, and store it in any location on the computer. However, in Guptas documentation, the name of the configuration file will always be referred to as SQL.INI, even though your files name may be different. In version 8.5 or later, you can use Connectivity Administrator or SQLBase Management Console to control the name and location of the configuration file. Note: The Windows version of SQLBase is not case-sensitive, but the Linux version of
SQLBase expects this file to be in lowercase: sql.ini.

To use a SQLBase client, you must first enable the appropriate communication libraries by setting the correct comdll value in the sql.ini file. The easiest way to do this is by setting the communications interfaces through the GUPTA Connectivity Administrator if you are on Windows 2000 , XP, or Server 2003, or your preferred text editor. Read the online help for the GUPTA Connectivity Administrator for more information, or refer to chapters two and three of the Database Administrator Guide.

Do I need to configure sql.ini?

If you have just installed SQLBase, and you wish to verify that it is running correctly, you probably will not need to change the configuration in sql.,ini. The installation of SQLBase for Windows provides default values that allow the server to run and to make itself available using the TCP/IP protocol on port 2155. The client components installed at the same time are configured to talk to that server and to access the sample database ISLAND. However, once you have tested SQLBase and you wish to begin using it for your own applications and data, you will need to make configuration changes in the sql.ini file. Some of the reasons that you would make these changes include: Adding new databases to the server. The database names must be added to both the client and server portions of sql.ini

SQLBase Starter Guide

2--3

Chapter 2

Configuring SQLBase for Windows

Restricting which databases are visible to client applications. The default at installation time is to make all databases on a server visible. Changing performance settings. sql.ini contains keywords related to cache sizes, types of joins, log files, and other performance features. You can change the values associated with those keywords. The most complete information about configuring sql.ini is found in the Database Administrator Guide, chapters 2 and 3.

How SQLBase finds sql.ini

When a server starts, or when a client attempts to connect to a server, three important configuration files must be found or an error message is issued. These are the main configuration file, referred to as sql.ini throughout the documentation, and files error.sql and message.sql, which influence messaging between server and client.

Logic for servers

Each server executable accepts an optional command-line argument that contains the file name (and, optionally, the path) of the configuration file. The name might be something other than sql.ini An example of a command line specifying the argument is:
dbntsrv.exe ini=c:\my work directory\myconfigfile.cfg

If the command-line argument is left blank when the executable starts, it is presumed that the configuration file is named sql.ini and that it resides in the same directory as the executable itself. Two other important files, error.sql and message.sql, are always required to be in the same directory as the database server executable itself.

Logic for clients

If a client application connects to the database using the API function sqliniEx, then it supplies the explicit name and location of the configuration file, and the API will simply attempt to open that file. No other searching will be done. Some Gupta client tools, such as SQLTalk, can accept a command-line argument specifying the configuration file, and if such an argument is specified then the sqliniEx method of connecting is used. If no explicit configuration file is named, the SQLBase API attempts to locate a file named sql.ini, looking in the following locations: 1. 2. The directory named in the SQLBASE environment variable. Current directory.

2--4 SQLBase Starter Guide

Running SQLBase Server as a Windows service

3. 4. 5.

\SQLBASE (for Windows) or /SQLBASE (for Linux) directory on the current drive. Root directory on the current drive. Directories specified by the PATH environment variable.

Note: If the SQLBASE environment variable is set, SQLBase looks only in the directory to
which it points. It does not continue to follow the search order outlined above.

Client logic for error.sql and message.sql

Once the configuration file (default name sql.ini) has been located, two other important files must be located. The search logic for error.sql and message.sql is very similar to that for SQL.INI, with one important difference. Since sql.ini has already been located, we can check for the CLIENTRUNTIMEDIR keyword in that file. If the keyword exists and has a value, then only the directory named by that value will be searched for error.sql and message.sql. If that keyword has no value in Windows, the search logic shown in steps 1 through 5 above is used to locate these two files. If there is no value for that keyword in Linux, the default Linux logic is used, which will search directories that are specified in configuration file /etc/ld.so.conf. error.sql and message.sql must be located in the same directory that contains the client shared library libsqlbapl.so.

Running SQLBase Server as a Windows service

Note: In order to install SQLBase Server for Windows as a service, you must have
Administrator privileges.

Running SQLBase Server for Windows as a service is supported on Windows 2000, XP, and Server 2003. SQLBase Server for Windows offers the option, during installation, to run as a Windows service. If this option is chosen, SQLBase is set to run as a system account and to interact with the desktop. Pior to version 8.5 only one instance of SQLBase Server could be run on a Windows machine at any given time, regardless of whether it was being run as a service or an application program. Beginning with version 8.5, multiple SQLBase Server engines can run simultaneously, although only one of these instances can be a version prior to 8.5. You can use the SQLBase Management Console (SMC) to start and stop SQLBase as an Windows service. SMC also allows you to rename a SQLBase service, and to register as an service a SQLBase instance that was previously

SQLBase Starter Guide

2--5

Chapter 2

Configuring SQLBase for Windows

configured to run as an application. For information, read Chapter 6, DBA Operations, in the Database Administrators Guide. For more information on running SQLBase Server for Windows as a service, read Chapter 13, Running SQLBase Server as a Windows Service in the Database Administrators Guide. Note: SQLBase cannot run as a service automatically if you are using the user account in the
Services setup.

2--6 SQLBase Starter Guide

SQLBase Starter Guide

Chapter 3

Configuring SQLBase for Linux

This chapter provides information about configuring SQLBase on Linux machines.

SQLBase Starter Guide

3--1

Chapter 3

Configuring SQLBase for Linux

sql.ini file configuration settings

GUPTA products read the sql.ini file at program start-up. The sql.ini file is the common file containing software configuration settings. Each client and server machine must have a sql.ini file. It is possible to name sql.ini to any other name, and store it in any location on the computer. However, in Guptas documentation, the name of the configuration file will always be referred to as sql.ini, even though your files name may be different. Note: Some areas in books and online help refer to the file as SQL.INI, but on Linux, with its
case-sensitivity, you should always use the lowercase form.

How SQLBase finds sql.ini

When a server starts, or when a client attempts to connect to a server, three important configuration files must be found or an error message is issued. These are the main configuration file, referred to as sql.ini throughout the documentation, and files error.sql and message.sql, which influence messaging between server and client.

Logic for servers

Each server executable accepts an optional command-line argument that contains the file name (and, optionally, the path) of the configuration file. The name might be something other than sql.ini. An example of a command line specifying the argument is:
./dblxsrv ini=/usr/etc/my work directory/myconfigfile.cfg

If the command-line argument is left blank when the executable starts, it is presumed that the configuration file is named sql.ini and that it resides in the same directory as the executable itself. Two other important files, error.sql and message.sql, are always required to be in the same directory as the database server executable itself.

Logic for clients

If a client application connects to the database using the API function sqliniEx, then it supplies the explicit name and location of the configuration file, and the API will simply attempt to open that file. No other searching will be done. Some Gupta client tools, such as SQLTalk, can accept a command-line argument specifying the configuration file, and if such an argument is specified then the sqliniEx method of connecting is used.

3--2 SQLBase Starter Guide

sql.ini file configuration settings

If no explicit configuration file is named, the SQLBase API attempts to locate a file named sql.ini, looking in the following locations: 1. 2. 3. 4. 5. The directory named in the SQLBASE environment variable. Current directory. \SQLBASE (for Windows) or /SQLBASE (for Linux) directory on the current drive. Root directory on the current drive. Directories specified by the PATH environment variable.

Note: If the SQLBASE environment variable is set, SQLBase looks only in the directory to
which it points. It does not continue to follow the search order outlined above.

Client logic for error.sql and message.sql

Once the configuration file (default name sql.ini) has been located, two other important files must be located. The search logic for error.sql and message.sql is very similar to that for SQL.INI, with one important difference. Since sql.ini has already been located, we can check for the CLIENTRUNTIMEDIR keyword in that file. If the keyword exists and has a value, then only the directory named by that value will be searched for error.sql and message.sql. If that keyword has no value in Windows, the search logic shown in steps 1 through 5 above is used to locate these two files. If there is no value for that keyword in Linux, the default Linux logic is used, which will search directories that are specified in configuration file /etc/ld.so.conf. error.sql and message.sql must be located in the same directory that contains the client shared library libsqlbapl.so.

Do I need to configure sql.ini?

If you have just installed SQLBase, and you wish to verify that it is running correctly, you probably will not need to change the configuration in sql.,ini. The installation of SQLBase for Linux provides default values that allow the server to run and to make itself available using the TCP/IP protocol on port 2155. The client components installed at the same time are configured to talk to that server and to access the sample database ISLAND. The CLIENTRUNTIMEDIR keyword in sql.ini has a value that points to the same directory in which client program sqllxtlk is installed. However, once you have tested SQLBase and you wish to begin using it for your own applications and data, you will need to make configuration changes in the sql.ini file. Some of the reasons that you would make these changes include: Adding new databases to the server. The database names must be added to both the client and server portions of sql.ini
SQLBase Starter Guide

3--3

Chapter 3

Configuring SQLBase for Linux

Restricting which databases are visible to client applications. The default at installation time is to make all databases on a server visible. Changing performance settings. sql.ini contains keywords related to cache sizes, types of joins, log files, and other performance features. You can change the values associated with those keywords. The most complete information about configuring sql.ini is found in the Database Administrator Guide, chapters 2 and 3.

3--4 SQLBase Starter Guide

SQLBase Starter Guide

Chapter 4

Running SQLBase
This chapter provides step-by-step instructions for starting and stopping the SQLBase Server. It also includes information on uninstalling SQLBase.

SQLBase Starter Guide

4--1

Chapter 4

Running SQLBase

Starting and stopping the server

Windows NT, 2000, Server 2003, and Windows XP
This section describes how to start and stop the SQLBase Server for Windows NT, 2000, Server 2003, and XP. You must start the database server before clients can access a database, unless you are using the Anonymous Pipes protocol. When this protocol is used, SQLBase will be started automatically when an application attempts to connect to a database on the same machine.

Starting
By default, the setup installs SQLBase as a service. If you choose to run SQLBase Server as a Windows application, you should use SQLBase Management Console or the Windows Service Manager to make sure that the SQLBase service is disabled first. You can manually start SQLBase as a service using either SQLBase Management Console or the Windows Service Manager. For more information on running SQLBase Server as a service program, read Chapter 13 of the Database Administrators Guide. To start SQLBase as an application, select Programs, GUPTA, and SQLBase 5User Server from the Start menu. This item name varies depending upon your installation directory and the server version installed.

Stopping
It is recommended that you disconnect all users prior to stopping SQLBase. If you use SQLBase Management Console to stop SQLBase, that tool allows you to automatically disconnect any current users if you wish. If, however, users are still connected when you stop the server, SQLBase automatically performs recovery on these databases during the next connection. If RECOVERY is set to off, SQLBase will be unable to recover the affected databases.

SQLBase as a Windows service

SQLBase can be stopped by using either SQLBase Management Console or the Windows Service Manager. GUPTA recommends you use SQLBase Management Console since this tool enables you to verify that there are no users connected before you stop the server. For more information about SQLBase Management Console, see the Database Administrators Guide.

SQLBase as an application
To stop SQLBase Server, do one of the following: 4--2 SQLBase Starter Guide

Uninstalling SQLBase

Select File, Exit from the SQLBase menu bar. Close the SQLBase Server window. Select File, Exit from the SQLBase menu bar. Close the SQLBase Server window. Use the SQLBase Management Console to stop the SQLBase application. Programmatically shut down the server using either SQLTalk or using the SQLBase API. For information on the SQLBase API, read the SQLBase SQL Application Programming Interface Reference.

Linux
This section describes how to start and stop SQLBase on Linux operating systems. See the release notes for the specific Linux brands and versions supported.

Starting SQLBase
The name of the SQLBase binary is dblxsrv. Navigate to the directory that contains this binary and enter the binary name as a command. Enter ./dblxsrv from the command prompt; do not double-click the file in File Manager. When SQLBase starts, it displays a console window showing basic statistics about the server. To learn more about this window, read Chapter 5 of the Database Administrator Guide.

Stopping SQLBase
In the console window which displays SQLBase statistics, press Ctrl-X. If users are currently connected, SQLBase will prompt whether to stop anyway, and you may answer Y or N. Otherwise, SQLBase stops immediately.

Uninstalling SQLBase
On Windows
To remove the SQLBase software from your Windows computer, use the Add/ Remove Programs applet in the systems Control Panel.

On Linux
To remove the SQLBase software from your Linux computer, navigate to directory containing the SQLBase engine. Then run the following RPM commands in the sequence shown. Note that the term build stands for a 5-digit build number that will be provided in the release notes.
SQLBase Starter Guide

4--3

Chapter 4

Running SQLBase

rpm -e SQLBase10-docs-10.0.0-build rpm -e SQLBase10-samples-10.0.0-build rpm -e SQLBase10-jdbc-driver-10.0.0-build rpm -e SQLBase10-devel-10.0.0-build rpm -e SQLBase10-odbc-driver-10.0.0-build rpm -e SQLBase10-client-10.0.0-build rpm -e SQLBase10-server-10.0.0-build rpm -e SQLBase10-common-10.0.0-build

4--4 SQLBase Starter Guide

SQLBase Starter Guide

Chapter 5

What now?
This chapter contains information on testing your configuration using SQLTalk, National Language Support, using drivers and data providers, and loading database files to the SQLBase Server.

SQLBase Starter Guide

5--5

Chapter 5

What now?

Finishing your configuration

You are encouraged to edit sql.ini to make several settings that improve performance of the SQLBase server and client. The keywords whose values need to be set are listed below. Refer to the Database Administrator Guide, Chapter 3, to see full detail for the meaning and possible values of each keyword.

Server-related settings
fileaccess should be set to 0 for security reasons. cache should be set to one-quarter of your of physical memory for good performance. dbdir should be set to a specific directory, initially the one in which the ISLAND subdirectory can be found. servername should be set to a unique name. Note that this unique name must be echoed in some of the client-related settings, too. password should be set to a non-null value for increased security.

Client-related settings
clientruntimedir should be set to a directory, even if it is the same as the directory that contains your client components. serverpath should be configured with correct information for the servers that your client will be communicating with.

Testing your installation

You can test the connection between your server and client using SQLTalk or SQLConsole.

SQLTalk
Before starting SQLTalk, make sure that the server program is running, as described in the previous chapter.

Starting the SQLTalk program in Windows

To start SQLTalk, invoke the SQLTalk item from the GUPTA program group.

Using SQLTalk with Windows

This section describes how to run SQLTalk using the sqltalk.exe Windows interface. There is also a sqlnttlk.exe that runs on Windows but behaves much like the Linux version described in the next section.

5--6 SQLBase Starter Guide

Testing your installation

1.

Be sure that the server program is running. Refer to Starting and stopping the server on page 4-2. On some single-user installations in Windows, the server will start automatically when a client program like SQLTalk begins, but ordinarily the server must be started in advance. Start SQLTalk on the client machine, as described in the previous section. Select Connect from the Session menu. In the dialog box, enter a database name (for example ISLAND), and click Connect.

2. 3.

Note: ISLAND is the standard default database that ships with SQLBase.

SQLBase Starter Guide

5--7

Chapter 5

What now?

If your network and software components are configured correctly, a connection will be added to the list as shown below (Windows example).

The Current Connections box displays ISLAND as the database name, which confirms your connection to this database. Click Close. As an alternate technique in Windows, you can also connect to a database by entering the following command in a SQLTalk window. For example:
CONNECT ISLAND; CURSOR 1 CONNECTED TO ISLAND

5--8 SQLBase Starter Guide

Testing your installation

4.

Enter SQLTalk commands. Remember to end every command with a semicolon. You can start entering commands at the cursor in the top pane of the SQLTalk window. For example:

To execute the command that the cursor is currently over, press Ctrl+Enter.

SQLBase Starter Guide

5--9

Chapter 5

What now?

Starting the SQLTalk program in Linux

The SQLTalk executable is named sqllxtlk. Navigate to that directory containing it (or make sure the directory is in the path) and launch the executable.

Using SQLTalk on Linux

Entering commands in the Linux version of SQLTalk is similar to Windows, but the console interface is more basic. All commands are ended with a semicolon. Here is an example of a sign-on and simple query:

You can enter SQL and SQLTalk commands as described in the SQL Language Reference Manual and the SQLTalk Reference Manual.

5--10 SQLBase Starter Guide

Using drivers and data providers

Ending SQLTalk.
When you are ready to end your SQLTalk session, enter this command at the cursor:
exit;

On Linux, you can also press Ctrl-C to end the session. On Windows, you can press Alt-F4.

Using drivers and data providers

SQLBase offers five main methods for clients to connect to the server: Native API (for Windows and Linux) ODBC driver (for Windows and Linux) JDBC driver (for Windows and Linux) OLE DB data provider (Windows only) .NET data provider (Windows only)

The first method is covered in the SQLBase API Reference. There is an entire book that covers the other four methods in detail; see Connecting to SQLBase.

Client applications
All client applications that connect to SQLBase require a configuration file (default name sql.ini). Even clients that are simply using one of the drivers or data providers need a configuration file, with the exception of clients using the JDBC driver. For infomation on how to structure the configuration file, see chapters 2 and 3 of the Database Administrator Guide.

Linux considerations
If you run a Linux client application from a directory other than the one where the binary is actually located, and you have not specified the clientruntimedir keyword in your configuration file, you may encounter an error due to the programs inability to find the supporting binary files. To remedy this, you can either change to the binarys directory before running, or you can use the LD_LIBRARY_PATH environment variable to point to the directory that contains those binary files. You would do this with commands similar to this example:
$LD_LIBRARY_PATH=SQLBaseBinaryDirectory $export LD_LIBRARY_PATH

SQLBase Starter Guide

5--11

Chapter 5

What now?

Loading database files into SQLBase

If you are upgrading from SQLBase 7.x, it is recommended that you unload your old database files with your old version of SQLBase client then load them to the new SQLBase Server. There is an auto-migration feature, but it is subject to several limitations. For more information, see the release notes. You can also load a non-SQLBase database to SQLBase using a common file format, such as .CSV. For information on loading and unloading, read the LOAD and UNLOAD command documentation in the SQL Language Reference. You can improve the performance of the load by performing the following tasks: 1. 2. Defragment your disk. This is also useful for server operations in general. Run SET RECOVERY OFF before you run LOAD. Be aware that when you set recovery off, SQLBase does not generate log files and this speeds up the load. When you are finished with the load, run SET RECOVERY ON. Run the LOCK DATABASE command to place an exclusive lock on the database. When you are finished with the load, run UNLOCK DATABASE. Use the ON SERVER clause of the LOAD and UNLOAD command. This decreases network traffic by performing the operation on the server machine, if the load file is local to the server. Set the server screen to show the minimal level of process detail (level 0). This is also useful for server operations in general.

3. 4.

5.

5--12 SQLBase Starter Guide