Event:Inprise / BorCon 98 About:Presentation Paper Author:Markus Kemper Who:Interbase Presentation Group Topic:Introduction to InterBase Presenters:Markus Kemper and Brett Bandy Revision:Final Revision An Introduction To Interbase "You just bought , C++Builder or JBuilder and you've found InterBase! What's next? An InterBase support engineer will address some commonly asked product pre and post sales questions as well as some implementation issues raised by new InterBase developers."

Objective

My objective in writing this paper is to provide answers to many of the frequently asked InterBase questions. Reading questions and answers could be quite boring. I have attempted to consolodate the common questions into more comprehensive topics derived from them. As well, I hope to make the reader familiar with InterBase so that a new user has a good working knowledge of the product before beginning their first InterBase development project.

Preface This paper is not a 'how to use' InterBase document. It is geared towards making new InterBase users aware of some of the important things to pay attention to. This paper is intended for the beginner or intermediate InterBase programmer. I make reference to Inprise's '' brand of Rapid Application Development RAD tools because I am assuming that you will be using them for upcoming development projects.

Terms

I think it is important to briefly define some terms. By describing them we can establish a base upon which to approach the topics within this paper. InterBase: InterBase is an ANSI SQL 92 compliant Relational Management System. InterBase Software Corporation is a wholly owned subsidiary of Inprise Corporation. Pre sales: The definition of pre sales is occasionally a tricky subject. The boundaries of pre sales type questions can be difficult to pinpoint. Often the related questions are non technical and tend to be repetitive. Regardless of their nature they are vital for both the success of our customers and InterBase itself. I am the Technical Sales Lead for InterBase. It has been a great experience for me in that it has forced me to wear the customers shoes and tromp around in the little known universe called InterBase. There will never be the perfect doc/example set, the all encompassing FAQ or maybe not even a totally bugless product but, there will always be the opportunity to improve all of the individual components that make up a software package. The development success of new and existing InterBase programmers is directly related to the quality of the documentation resources that InterBase Software Corporation provides. Pre Sales, to me, is any product related question not pertaining to example generation, syntax analysis, code evaluation, design aid or post installation trouble shooting. Pre sales could include subjects like; feature support confirmation, pricing, licensing, estimated systems sizing recommendations or other similar pre installation inquiries. Post Sales: The definition of post sales is much easier to define. By definition it is limited in scope to product inquiries made after purchase. Post sales issues can be lumped into product related questions like; configuration, installation, performance analysis. There is a fine line to be walked with regard to the point at which pre sales migrates itself into support or consulting. It is a natural process. It just happens. A software vendor has the duty to document its product while at the same time an application software developer wants to be self sufficient. The time at which a product related issue qualifies for reasonable monetary compensation is outside the scope of this paper.

Pre Sales Inprise Database Client/Application Development Tools

Inprise Corp. formerly Borland International has a long standing reputation for producing the most advanced, productive and powerful compilers in the industry. Borland's flagship RAD tool, Delphi has paved the way and set the standard for its current fleet of enterprise strength development tools. Inprise currently has three distinct software development tools that it releases under the 'Borland' brand name. The most famous tool Delphi, is built upon the Object Pascal programming language. Version 4.0 of Delphi is soon to be released. Borland has always been a leader in the C/C++ compiler arena. With the push for more robust graphical development tools Borland has incorporated its powerful C/C++ compiler technology into the award winning RAD development tool C++Builder. The current release of C++Builder is version 3.0. In keeping with the wave of new and upcoming technology and the advent of Sun Microsystems' Java programming language, Borland has delivered again with JBuilder. JBuilder is currently on release 2.0 and is setting a precedence in the market of Java based development tools.

Inprise Development Tool Editions Inprise offers four different editions of each of its 'Borland' development tools. The editions are: 'Enterprise', 'Client/Server', 'Professional' and 'Standard'. Each of these aim to meet the needs of a wide range of software developers and their development tasks. Every edition, with the exception of the 'Standard' release of the Borland RAD tools comes with a free copy of the InterBase Server. A big misconception amongst new InterBase users is that there is a difference between the 'local' and 'multi-user' servers. InterBase is InterBase. Aside from the number of users available and the network capabilities, the product is exactly the same. The functionality of the InterBase Server shipped with the Borland tools is determined by the license included with each edition.

Tool Edition InterBase Capability

Enterprise 1 User Local InterBase Server License (IERDQ)

" 5 User InterBase Server License (IERDSQ)

Client Server 1 User Local InterBase Server License (IERDQ)

" " 5 User InterBase Server License (IERDSQ)

Professional 1 User Local InterBase Server License (IERDQ)

Standard InterBase is not included

InterBase Database Management and Development Tools All of the tools that ship with the InterBase product line can be found in the \bin sub directory under the InterBase root directory. The InterBase 'root' directory is determined during the installation process. InterBase installs in the following default directories.

Platform Default Location

Windows \ Program Files \ InterBase Corp \ InterBase

Unix based / usr / interbase

Novell \ sys \ interbas

InterBase Tools NOTE: The documentation references below pertain to InterBase version 5.x. ISQL ISQL.exe - stands for Interactive SQL. It is a general purpose command line tool. It allows for Database Definition Language DDL creation and manipulation, data retrieval, data insertion, update and deletion as well as some limited debugging and performance tuning capabilities. (Operations Guide, page 200) Windows ISQL WISQL32.exe - is the GUI implementation of the command line tool ISQL.exe. (Operations Guide, page 18) Server Manager IBMGR32.exe - is a GUI based server and database management tool. The Server Manager encompasses the functionality of most of the command line tools. All InterBase Servers either v4.0 or greater are accessible by the Server Manager. This tool allows for database backup / restore, user administration as well as some other database related tasks like; validation, shutdown, repair and configuration. (Operations Guide, page 12 - 18) Communications Diagnostics COMDG32.exe - is a vital tool. This tool is used to test connections between InterBase Windows Clients and InterBase Servers. The Communications Diagnostic tool supports all valid InterBase protocols against all InterBase Servers version 4.0 or greater (Operations Guide, page 19, 87 - 95) License Manager IBLICENSE.exe - is, by name, rather self explanatory. The License Manager tool is used to manage (add/remove) licenses on an InterBase Server. This tool is only supported for version 5 InterBase Servers. (Operations Guide, page 19, 57)

Registry Configuration REGCFG.exe - is used to configure some InterBase registry settings, InterBase Server process priority as well as control the Guardian Process run modes. (Operations Guide, page 70 - 75) GBAK GBAK.exe - is the most important tool in the bin directory. This tool is used to backup and restore . Backups are necessary to protect against unexpected data loss or file corruption. GBAK is also a great way to archive old databases. A backup copy is the only recommended way of preparing a database for machine transfer. By default GBAK generates a 'transportable' backup from a target database. This 'transportable' format allows a DBA to seemlessly backup databases and restore them on different InterBase Server platforms. This allows InterBase to provide a platform independent database solution. The GBAK functonality is surfaced in the Server Manager tool. (Operations Guide, page 156 - 163) GSPLIT GSPLIT.exe - is a tool new to InterBase version 5. This tool was created to solve a critical problem with regard to our support of unlimited database size. InterBase supports 'multi-file' databases. Operating systems enforce maximum file size limits (most commonly 2 GB). This presents a major problem when attempting to backup large InterBase databases. GSPLIT is to be used in conjunction with GBAK to create a 'multi-file' database backup from either a single or multi-file database. GSPLIT enables the backup of databases of practically unlimited size. (Operations Guide, page 163) GSEC GSEC.exe - is a command line tool used to manage (add/delete/modify) InterBase Server USERs' attributes such as (first_name, last_name, passwords, etc.). USER information is stored in the InterBase Security Database (ISC4.gdb). The functionality represented in this tool can also be found in the Server Manager tool. (Operations Guide, page 104 - 109)

GFIX GFIX.exe - is a command line utility used to perform various database maintenance operations like database validation and repair. It also allows for the setting of some specific database properties. Most all of the functionality available in GFIX command line can be found in the GUI Server Manager tool. (Operations Guide, page 140 - 142) GSTAT GSTAT.exe - is a utility that can be used to view a database's statistics about the transaction inventory, data distribution, index selectivity as well as some other vital database properties. All of the functionality found in GSTAT is also surfaced in the Server Manager tool. (Operations Guide, page 21)

GPRE GPRE.exe - is a pre-processor used by programmers that wish to use InterBase Embedded SQL. This tool converts InterBase 'SQL' statements into InterBase API calls prior to compiling and linking your application code. GPRE supports various programming languages. The languages supported vary between platforms. GPRE requires the purchase of a pre-processor license. (Programmer's Guide, page 18, 68, 287 - 293) On Line Help The InterBase manuals are now made available in .PDF Acrobat file format. The on-line documentation files can be found in the \doc sub directory of the InterBase root directory. Having the documentation in Acrobat format provides a cross platform solution for on-line documentation. There are some exceptions with regard to the tools provided based upon platform release. There are no server side Tools with the Novell product offerings due to Netware NLM Architecture. All InterBase tools for Novell are implemented via the Windows clients. There are no based GUI utilities at this time. A Windows client can be used to access the UNIX servers. (Please note: Documentation Reference is based upon the InterBase v5.0 Documentation Set) Systems Sizing 'Systems Sizing', in general refers to a machine's processing power which is obtained by a combination of hardware and software. As a general rule, the more robust and stable the combination, the more powerful and reliable your production server environment will be. Database Servers Database Server software is very processor and memory intensive. When performance is important it is a good idea to invest in a fast CPU and adequate RAM. A fast disk subsystem will increase performance too. InterBase does NOT currently scale symmetrically across multi-processor SMP machines. You might see some performance enhancement with SMP machines but, it is probably wiser to invest in a faster single processor machine until InterBase can fully support SMP. For maximum database server performance it is recommended to treat your machine as a dedicated RDBMS host. Do not use the database server host as a file server. InterBase Server Platforms Please note: The (systems requirements) data presented is based upon the current shipping InterBase v5.x software at the time of writing this paper, (6/98). UNIX Based InterBase has released version 5.x on two UNIX based operating systems. The two platforms are, Sun Microsystems', Solaris (2.5/2.6) and Hewett Packard's, HPUX (10.20). Our other v5.x UNIX based releases (SCO and AIX) will be released later this calendar year. The system requirements and compiler certifications are listed below. Solaris

Component Requirement Operating Solaris 2.5.x or 2.6.x System Memory (RAM) 64 MB min., 128 MB or greater recommended Processor / SPARC or UltraSPARC Hardware C Compiler SPARCWorks SC 4.2 C Compiler C++ Compiler SPARCWorks SC 3.0.1 C++ Compiler Fortran Compiler SPARCWorks SC 4.0 Fortran Compiler COBOL MicroFocus Cobol 4.0 Compiler Ada Compiler SPARCWorks SC 4.0 Ada Compiler

HPUX

Component Requirement

Operating System HPUX 10.20

HP DCE/9000 runtime support (DCE-Core) must be OS Related installed

Memory (RAM) 64 MB min., 128 MB or greater recommended

Processor / PA-RISC / HP9000 Series 7xx or 8xx Hardware

C Compiler HP C/HPUX Version A.10.32

C++ Compiler HP C++/HPUX Version A.10.22

Fortran Compiler 10.20 release of HP Fortran/9000

Linux Why isn't grouped with the other UNIX based listings? I wanted to bring attention to it. This is the first time in history that InterBase has been ported to the Linux platform. Later references to UNIX in this paper are to include the Linux platform. The current release is free and downloadable from the InterBase website. The software is certified for Red Hat Linux 4.2. InterBase will be releasing InterBase version 5.x for Red Hat Linux 5.0 later this year. This release will not be free. See the Windows NT requirements listed below for basic systems sizing.

Windows NT Our InterBase Server resource requirements for Windows NT (Server and ) are listed below. Component Requirement

Operating System Windows NT 4.0

Memory (RAM) 64 MB min., 128 MB or greater recommended

Processor / Pentium 100MHz or greater recommended Hardware

Compilers Borland C++ 5.0 / Microsoft Visual C++ 4.2

Windows 95 In general, Windows 95 is considered an unstable operating system for an RDBMS Server business application. I tend to think of using a Windows 95 Server as a low cost multi-user development environment. Our InterBase Server system requirements for Windows 95 are.

Component Requirement

Operating System Windows 95

Memory (RAM) 16 MB min., 64 MB or greater recommended

Processor / 486DX2 66MHz min., Pentium 100MHz or greater Hardware recommended

Compilers Borland C++ 5.0 / Microsoft Visual C++ 4.2

Novell InterBase has not yet released version 5.x for the Novell Netware platform. We have recently released version v4.2.2 to support Netware 4.x. We will be releasing InterBase version v5.x for Netware 4.x later this year. Please see Windows NT requirements listed above for basic systems sizing.

Database Client Sizing What exactly is a database client? In its most simplistic form a database client is any application that makes an attachment to a database server. A client can be resident on the server machine itself or located on a remote machine. There are a gigantic number of combinations and configurations that could comprise a client solution. It is this wide range of possibilities that make generic client system sizing recommendation difficult. Client system sizing is very application dependent. To suggest a one size fits all formula for client sizing would be doing a disservice to our developers. It is however, possible to make some basic assumptions about various types of client solutions. If your client solution uses the 'local' connection method then one can infer that the server is no longer a dedicated RDBMS server. In this scenario the client applications would be installed and executed on the same machine as the RDBMS. This means that valuable system resources will have to be allocated to support both the client applications as well as the database server software thus, lowering the RDBMS total performance. If your client solution is character rather that graphical based it will require less overhead to run. The lower the overhead required to support an application, the lower the system requirements become for the client platform. If your client solution, graphical or not, uses direct - 'native', access to the RDBMS it will be less resource dependent. If the application makes use of 'middleware' it will require more resources.

InterBase Licensing

It is important to understand how InterBase licensing works. InterBase licensing is what governs how the Server functions. When you purchase an InterBase Server, single or multi user you are purchasing the same exact product. It is the license that controls how the server functions.

Licensing History If you have used InterBase versions less than 5.0 you will want to understand how we have changed our licensing scheme. The functionality of the Server is still based upon 'key' bits in the license file but, the administration, deployment and validation of the options has been modified. If you are new to InterBase our licensing scheme will hopefully be straightforward and logical. Described below are some of the differences between v4.x and v5.x licensing as well as some details about why we made various changes.

What's New Concurrent Connections and Users InterBase recognizes that your client applications may have the need to make multiple connections to a database(s) on a server. We attempt to be reasonable with this aspect of our licensing model and allow a single user to have multiple concurrent connections. InterBase version 5.x allows a single user to have four connections to a database(s) on a server. The four connection per user limit does allow connections to multiple databases on a single server. For example, a single user could connect to four different databases or 4 connections to a single database located on a server. Other combinations not exceeding the four connection limit are allowed. There is one exception to this rule. If developing with 'Local InterBase' LIBS the server will allow eight concurrent connections to the server. A LIBS InterBase Server is one that is run in a stand alone environment. This means that the server will not accept connections from remote client machines.

Node Locking vs. Non-node Locking Briefly described, a node is a platform dependent id that uniquely identifies a machine. If you have used a UNIX based InterBase version greater than 5.0 other than Santa Cruz Operations SCO, you will be pleased to know that we have done away with node locking. Node locking, to the best of my knowledge, is a UNIXism not appropriate for the method in which PCs are sold. Being that SCO is most commonly run on PC based hardware , it does not enforce node locking. In past versions of InterBase a 'node' was required to generate a license key thus, making licenses machine dependent. With InterBase version 5.0 licenses are only platform dependent.

Connection Governor New to InterBase version 5.x is the addition of the Server's attachment governor. The attachment governor simply manages the number of concurrent connections to database(s) on the server. It does not regulate which databases are being accessed to nor does it monitor USER names. Your total connection limit for a server is bound to the number of concurrent user licenses that is purchased and installed on the server. Licensing Registration Tool The license registration tool serves no other purpose than adding and deleting license keys from the server. There is a GUI version shipped with the Windows based platforms and a character based version that is shipped with the UNIX based releases. InterBase License File Contents The InterBase license file (ib_license.dat) on UNIX, (iblicense.dat) on Windows and (isc_lic.dat) on Novell defines the servers functionality. The license file is located in the InterBase root directory. An InterBase license file is made up of many components. Each individual license string present within a license file is made up of the following eight items. InterBase license files are additive thus, multiple license strings are combined to make up the total functionality of a server. Component Description COMMENT Descriptive comments ID Unique identification for a key KEY Encoded key you need to activate a server capability Set of single character codes for enabling specific InterBase OPTIONS server or client functionality. PRODUCT 'InterBase' or 'InterClient' UNTIL Expiration date of the license USERS User limit for the attachment governor VERSION Code for InterBase platform identification

Licenses File OPTIONS When the 'KEY' component in the license file is valid it activates the listed OPTIONS in the string. The OPTIONS are the bit-like flags that are responsible for enabling the server to support various functionality. Each flag represents a unique capability.

Option Enables Functionality

A GPRE preprocessor for Ada compilers

C GPRE preprocessor for C compilers

D Metadata changes with CREATE, ALTER, or DROP statements

E External table access

F GPRE preprocessor for Fortran compilers

I Internal table access

Listening server capability (like the 'S' option) for the J InterServer component of InterClient. This option will found in InterServer's license file not the InterBase license file

Q Query capability R Client capability, required for clients

S Server capability, required for servers

W Internet (web server) access license

Licenses In version 5.x of InterBase we have decided to break the server functionality apart into functional groups. These groups make up the individual licenses that actually get installed on the server. Being that the license file is additive, this concept works quite nicely and enables a DBA to have more flexibility in controlling the servers available functionality.

License Options Functionality Name

This key enables 'Local Interbase' functionality. Applications can connect to databases on the resident IEQ Activation disk subsystem and access internal and external tables.

This key enables the server to listen for incoming S Server client connections.

This key enables a client to connect to an InterBase server that has the (S) option. If you wish to connect R Remote through 'local loopback' on a server you must have this option installed on the server.

This key enables the server, through user SQL D Metadata commands (CREATE, ALTER and DROP) to make database metadata changes.

Depending on your server platform a two digit code ?? Users will be present for the servers simultaneous user count. For example on Windows it is (WI).

The remaining licenses are considered special licenses. These include (A,C,F and W). The are ? Special necessary only if your development or deployment requires their functionality.

Licensing InterBase Servers Administration License administration (additions/deletions) are to be performed with the License Registration tool. When using this tool it will require specific license information to be supplied. This information, the Certificate ID and the Certificate Key, can be found on the printed license material received upon purchasing InterBase licenses. Application Considerations It is always a good idea to make sure that your licensing allocation is adequate for your application design. If your client application exceeds more than four connections you will need to calculate this into your simultaneous user count. Licensing InterBase Clients The InterBase Windows clients do not require the licensing tool. The Windows InterBase Client installation process creates the license for you. UNIX clients are a little different. Because there is not a separate client library for UNIX, the license registration tool is required to supply the correct OPTIONS to the license file. InterBase clients are freely distributable because the licensing is enforced on the server. Licensing InterBase's InterClient The InterServer / InterClient JDBC InterBase solution is freely deployable with your InterBase Server installation. License Locations The InterBase license files can to be found in the InterBase root directory on all server installations. The InterClient license files are located in the root directory of the InterClient installation.

InterBase Deployment InterBase deployment is the bundling of the RDBMS with other software developed to create a business solution. Often the application is referred to as the 'front end' and the database that it relies on is termed the 'back end'. There are many different ways to deploy an application with an InterBase back end. Deployment Strategies The type of application is generally a good indication of what type of deployment method to pursue. Listed below are a few common deployment scenarios. Common Deployment Strategies Unbundled (Do It Yourself) By 'unbundled' I mean that there is nothing fancy involved. This type of deployment would require a user of the development package to purchase InterBase separately. The end user would install InterBase and then install the developed solution. These 'unbundled third party' solution are usually purchased and used by software or IT developers. Fat (Semi-Embedded) A 'fat' deployment package would be one in which a 'total' solution is sold to the end user. In this case, InterBase is sold with the development solution. It is the installation of the InterBase software that is 'fat'. This solution would involve the software developer to call the InterBase installation routines from the solution installation routine. I call it 'fat' because all InterBase files are installed rather than just the ones required by InterBase or the software solution. These are generally classified as 'vertical' applications. Silent (VAR) A 'silent' software deployment package could also be called an 'embedded' installation. It is much like the 'fat' deployment method described above except that it is very compact. There is no reference to the generic InterBase installation routines. This model requires the developer to supply the required InterBase files and setup the Windows registry and other configurations. Because the developer has the ability control the minimum number of files that need to be installed, a tiny InterBase footprint can be achieved. This is usually the most desired type of deployment for a 'vertical' application. Zero (Web) The 'zero' deployment method generally refers to the client application side of the picture. This scenario is most commonly implemented via the web. I use the term 'zero' because the nature of the application does not require the end user of it to install InterBase related software.

InterBase Database Connectivity 'Database connectivity' is the means by which an application talks to a database. There are many different ways of doing this. There are two basic connection methods for InterBase, the API and Embedded SQL. Connectivity Methods The most common characteristics to consider when determining which method to use are; performance, portability and ease of use. All connection methods use either the InterBase API or InterBase Embedded SQL. These connection methods can be further broken down into what I call 'access methods', meaning that they are either 'native' or 'middleware'. The 'native' methods are the InterBase API and Embedded SQL. Any other method is considered a form of 'middleware'. As a general rule the 'native' methods are more complex to use but, offer better performance. Middleware on the other hand tends to offer ease of use, database independence and sometimes extended functionality but, always at the cost of performance. InterBase only supports 'native' connection methods with specific development languages on various platforms. The InterBase 'native' connection methods allow any tool that can access a shared library to use the API. There also are many 'middleware' methods of accessing InterBase databases. Common Connection Methods Native InterBase API The InterBase API is a collection of low level functions that allow a developer to construct and send SQL statements to an InterBase server. The API supports all possible InterBase database functionality. The API is the most powerful and flexible method to access InterBase databases. It is however, more complex to use. A developer is required to build and populate the underlying structures commonly hidden at the SQL level. Some other advantages of programming to the API are; speed, control over memory allocation, control over error messaging, direct control over transactions and the lack of the need for pre compilation. InterBase Embedded SQL InterBase's Embedded SQL requires a programmer to pre compile an application before actually compiling and linking to create the executable. While it is possible to have dynamic querying with Embedded SQL, it is most often used for application in which the database queries do not change and are known prior to runtime usage. With Embedded SQL a developer would 'embed' [EXEC SQL] statements into the application code and run the InterBase pre-processor against it. GPRE, the pre-processor, converts the embedded statements into InterBase API calls. FreeIBComponents (by Greg Deatz) FreeIBComponents is a Delphi Visual Component Library VCL to be used with Delphi 3 or greater. FreeIBComponents are built upon the Delphi 3 Architecture to provide native data access to InterBase. FreeIBComponents support InterBase databases version 4.2 or greater. FreeIBComponents are not an official product offering of InterBase Software or Inprise Corporation. It is offered with no guarantee or certification. Neither InterBase Software, Inprise Corporation nor any of their respective employees accept liability for use or misuse of this software. FreeIBComponents are available for download from the InterBase website now. IBObjects (by Jason Wharton) IBObjects differs from FreeIBComponents in that it is built upon the Delphi 1 and 2 Architecture. It does not support the standard Borland RAD visual controls. Jason has built his own visual controls into the package. IBObjects is made up of more than 30 components that provide native InterBase connectivity. IBObjects allows you to eliminate both the BDE as well as ODBC from Delphi or C++Builder InterBase applications. IBObjects also comes with a vital SQL trace monitor. The monitor allows a developer to ensure that the database related code is as efficient as possible. IBObjects are available for download from the InterBase website now. Middleware BDE / SQLLinks The BDE and SQLLinks are 'Borland' brand products. The BDE is a 'middleware' tool that manages various SQLLinks drivers. The BDE has SQLLinks drivers that supports InterBase directly as well as many other RDBMS and flat file databases. It is this 'Borland' technology that allows a developer to write highly portable database applications. The InterBase SQLLinks driver (sqlint32.dll) is built on top of the InterBase API. InterBase's - InterClient InterClient is InterBase's Java Database Connectivity JDBC solution. This solution can be a little confusing because there are multiple parts to the complete package. The first thing to understand is that InterClient is an InterBase ONLY solution, it does not connect to other RDBMS'. InterClient (interclient.jar) is the JDBC driver (a client library) that communicates with InterServer which in turn communicates with an InterBase Server. InterServer is a process that is written in C and it is supported on all InterBase v5.x platforms. InterServer allows for the construction of multi-tier InterBase applications because it does not have to be resident on the same machine as the InterBase server. IB Perl (by Bill Karwin) IBPerl is an object oriented class module and extension for Perl 5 written by InterBase engineer, Bill Karwin. It provides an interface to the InterBase client API, for programming SQL applications with the RDBMS server. IBPerl provides a Perl interface to the InterBase API. IBPerl is an InterBase cross platform database access solution available for both UNIX and Windows ports. IBPerl is now certified for our free Linux release too. ODBC (Microsoft) Open Database Connectivity ODBC is a Microsoft developed standard to allow for uniform database access across dissimilar RDBMS back ends. InterBase has two different ODBC drivers, a 16bit as well as a 32bit version. The 16bit version built by InterSolv is still available but, development of it has been discontinued. Our current shipping 32bit ODBC driver was built by Visigenic. The driver is ODBC level 2.5 compliant. It can only be obtained through an InterBase Client installation. The development of the Visigenic driver has also been discontinued. InterBase is currently working with InterSolv again to develop our upcoming 32bit ODBC driver. The new 32bit driver will be ODBC level 3.0 compliant and will support multithreaded applications. Thread support is vital in that many data driven web server products require threaded ODBC drivers. The new InterSolv driver is scheduled to be released with the v5.5 maintenance release of InterBase. Post Sales

Pre - Installation It is always a good idea to evaluate the development environment before you begin any project. Described below are just a of the items to be considered before installing the InterBase software. Software Evaluation It is always a good idea to make sure that the software that being used has the technical capability to handle the development projects needs. Being successful is important. The software chosen should not get in the way of this. For example, lets say a developer is trying to write a multi-user database application and they have the 'professional' edition of one of the Borland brand tools. It would be possible to develop the application to some degree but, it would not be testable in parity to a production environment. InterBase product shipped with the professional editions do not accept remote connections nor does the BDE/SQLlinks middleware allow for remote access. Testing is very important to success. It must happen before the deployment phase of a product cycle. By understanding these things before development starts, unexpected suprises and roadblocks can be avoided ahead of time. Software (Already) Installed It is a good idea to be able to identify what development tools you have installed prior to starting the development process. Please see the vendor documentation for instructions on how to do this. It is possible to use some of the InterBase identification methods described below to determine what InterBase software is installed. There are many ways of determining if InterBase is installed. The most basic Windows method would be to search the task tray for InterBase icons. When using any of the InterBase GUI tools the [Help | About] menu item will display its version. Next, you could select 'start' then 'programs' and look for InterBase. The add/remove software icon in the Windows control panel will also display InterBase if it is installed. The Windows registry is also a good source to identify if InterBase is installed. Windows shipped a registry editor with both Windows NT and 95. Version Editor Location NT \ winnt \ system32 \ regedt32.exe 95 \ windows \ redgedit.exe

Upon loading this tool open the SOFTWARE sub directory in the HKEY_LOCAL_MACHINE directory. From this point use [Edit | Find] and search for 'InterBase'. Upon finding an InterBase Key entry there will be a 'CurrentVersion' subkey. Click on it to find the 'gds' version of the InterBase kit installed. This 'gds' version is our most specific identification stamp. When InterBase became a subsidiary company we changed our registry entries to reflect this change. Please see the matrix below that describes the different Windows Registry entries.

Version Registry Entry

< v5.0 hkey_local_machine | software | Borland | InterBase

= v5.0 hkey_local_machine | software | InterBase Corp | InterBase

Searching the hard drive for specific files is also a good method of identifying if InterBase is already installed on the machine. To search for a InterBase server use Windows Explorer and scan for "ibserver.exe". To search for InterBase client software use Windows Explorer and scan for "gds*.dll". There are many versions of both the server and client. You can determine which you have by the time stamp of the file. For example: (4:21:00am) indicates InterBase gds version 4.2.1. This method is also handy in identifying the BDE/SQLlinks and Borland tools versions as well. It is not recommended to have more than one version of either the InterBase server or the client software installed on a machine at the same time. A more cross platform method of identifying what InterBase software is installed is by using the command line tools in the \bin directory. By passing the flag (-z) to any of these tools will return their 'gds' version. Example: (Getting InterBase GDS Version Information)

# This example demonstrates obtaining the InterBase GDS # version by passing the (-z) flag to one of the # command line tools in InterBase's \bin directory. This # example assumes that you have the \bin directory is in # $PATH.

E:\work\databases E:\work\databasesgbak -z (return) gbak: gbak version WI-V4.2.1.328 Software (To Be) Installed I recommend examining the README or Release Notes included on the software media prior to installation. Often times software has what is called a major and minor (point) release schedule. A major release would generally introduce new features or functional changes. A 'point' release is often deemed a 'bug fix' release. Software packages sometimes do not clearly indicate this important point release information. It is important to validate this if upgrading or installing new software because of known enhancements or fixes in a point release. Generally, point revision information is documented in one of these two files. Environment Considerations Environmental considerations can play a big part in the success or failure of a development cycle. There are some common areas of consideration with regard to InterBase to pay attention to. The are described below. Hardware and Platform Hardware and Platform are vital considerations. Either the hardware configuration chosen is a tested, certified and supported platform or it is not. Using the software in an uncertified configuration can cause unexpected and unknown results even if the software installs and appears to be working properly. Please consult your installation media or documentation for valid hardware configurations. As well, there is some limited hardware and platform information in the 'systems sizing' section previously described. Networking Protocols Networking is also a major concern if developing for an application that will require remote access to the database server. InterBase supports various transport protocols based upon platform and its protocol support. These specifics are described in detail below. Licensing InterBase licensing is also very important. It is important to make sure that the InterBase Server licensing supports the desired development as well as runtime environment. If developing without network access then a 'local' server license should be adequate. If there are multiple developers or network development a 'multi-user' server license will be required. Please see the information previously described for the license key's functionality. InterBase Networking Requirements By Protocol A networking 'protocol' is simply just a method by which information is sent and received over the wire between two machines. There are many different types of protocols that are available on various platforms. If an application requires remote access there are some protocol requirements that must be met before InterBase will successfully be able to use them. TCP / IP (TCP) InterBase supports TCP on (all) its server platform offerings. TCP is a transport protocol. Transport protocols move information across the network in data packets. There are many layers to the TCP protocol stack. It is these layers that send, receive and make sense of the data packets. TCP is the recommended protocol for InterBase. TCP is very efficient and does not consume a lot of network band width, which is important in multi-user environments. In order for InterBase to be able to use TCP, the protocol must be configured so that machines can resolve network address based upon machine 'host name'. This is important because some software allows for resolution by IP address. InterBase does not do this. For examples on how to test this please see the section below on trouble shooting your network configuration. TCP uses several files to perform its network identification magic. These files must be present on both the InterBase Server machine and the InterBase Client machines. Below are detailed explanations of these required files. SERVICES Files The 'services' file is not used only by InterBase. A 'services' file describes TCP network port address. A port address is assigned to a particular software package. InterBase uses port 3050 and InterBase's InterClient uses port 3060. The services file binds a service, 'gds_db' in InterBase's case, to a predefined numeric port address. InterBase then listens for requests of this service 'gds_db'. Again, the services files must be present on both the server host as well as all the application client machines. The services file is located in different places depending on the server or client platform being used. Below is a matrix describing where they can be located.

Platform SERVICES File Location

Windows NT \ winnt \ system32 \ drivers \ etc \ services

Windows 95 \ windows \ services

UNIX based / etc / services

Novell sys: \ etc \ services

The entries located within these files are very specific and must be exact in order for InterBase to function properly. Example: (InterBase SERVICES file entries)

# SERVICES file example # # This file allows TCP to pass communications to # InterBase Servers on port 3050 and InterBase's # InterServer on port 3060. It is required to be # on all InterBase Servers and Clients. # # Format: # # service port/protocol description

# Some common entries found ftp 21/tcp # FTP support telnet 23/tcp # Telnet support

# InterBase related entries gds_db 3050/tcp # InterBase Corp InterBase Server interserver 3060/tcp # InterBase Corp InterServer HOSTS Files The 'hosts' file is not only used by InterBase. A hosts file describes a machine's name and its unique id (IP address) for a network. It is this file that InterBase requires to resolve a machine's network location with regard to its host name. Again, the hosts files must be present on both the server host as well as all the application client machines.

Platform HOSTS File Location

Windows NT \ winnt \ system32 \ drivers \ etc \ hosts

Windows 95 \ windows \ hosts

UNIX based / etc / hosts

Novell sys: \ etc \ hosts

The entries located within these files are very specific and must be exact in order for InterBase to function properly. Example: (InterBase HOSTS file for a SERVER)

# HOSTS file example (InterBase Server No. 1) # # This file allows an InterBase Server resolve its # clients by their host machine name. # # Format: # # IP address hostname.domain Description

127.0.0.1 localhost #Common to all TCP

123.123.123.100 ibserver1.ib.com #IB Server No. 1 123.123.123.101 ibclient1.ib.com #IB Client No. 1 123.123.123.102 ibclient2.ib.com #IB Client No. 2 123.123.123.103 ibclient3.ib.com #IB Client No. 3 Example: (InterBase HOSTS file for a CLIENT)

# HOSTS file example (InterBase Client No. 1) # # This file allows an InterBase Client resolve the # network location of InterBase Servers by their host # machine names. # # Format: # # IP address hostname.domain Description

# Some common entries found 127.0.0.1 localhost #Common to all TCP

123.123.123.100 ibserver1.ib.com #IB Server No. 1 123.123.123.200 ibserver2.ib.com #IB Server No. 2

123.123.123.101 ibclient1.ib.com #IB Client No. 1 Netbeui (Named Pipes) The Netbeui protocol was developed by the Microsoft Corporation. It is designed to network Windows machines together. Netbeui, unlike TCP is a broadcast protocol. It is this fact that makes it a network intensive protocol. In order for the protocol to work and have knowledge of other machines on the network, each host must periodically broadcast a signal indicating its existence. This can sometimes make Netbeui an undesirable protocol for multi-user applications. By nature its design consumes network bandwidth even when a network application is sitting idle. Netbeui is only supported by InterBase on the Windows platforms. Because of limitations within Windows 95, Netbeui is not supported if using Windows 95 as an InterBase Server. In this case you must use TCP. SPX / IPX (SPX) The SPX protocol is a Novell Netware developed protocol. It is often used to network together Netware Clients, often Windows based machines, and Netware Servers. SPX, like Netbeui is a broadcast protocol. Understanding the negative characteristics of the Netbeui protocol described above it is obvious why SPX might not be a protocol of choice. InterBase supports SPX only on specific Netware Servers and Windows Clients. The SPXS.NLM must be loaded on the Novell server for SPX to work. Please see the matrix below for details. Windows Clients IB Netware Servers

Windows 16bit - WS-V4.0a(4) IB for Netware 3.x (NW-V4.0)

Windows 32bit - WI-V5.1.1 IB for Netware 4.x (NW-V4.2.2)

Software Installation

The installation process should always be a painless operation. It is always a good idea to make sure that all pre installation issues have been taken care of before beginning this process. Inprise 'Borland' Brand Software Installation Please consult the Borland documentation for installation instructions. If installing the BDE with the Borland tool set and the BDE version is 4.51 or lower, please take note of the following information. During the BDE installation process, its routines search the Windows registry for existence of an InterBase entry. The BDE install looks for the old InterBase registry entries. This is not a problem with InterBase versions prior to 5.0. The BDE uses the InterBase Client library (gds32.dll) and installs a copy if it does not identify a previous installation via the registry entries. This creates a problem with InterBase installations version 5.0 or greater. If the BDE is installed after the InterBase version 5.x Client library has been installed, it will overwrite the gds32.dll library with an older version. This can propagate bugs that have been fixed in the InterBase version 5.x client libraries. The solution is to install the InterBase software after the BDE software. InterBase Software Installation If a previous InterBase installation has been detected it should be removed before installing and new InterBase software. Use the following instructions to remove the existing InterBase software. Example: (Removing an existing InterBase installation)

# To manually uninstalling the Windows InterBase # Software the following steps are required.

1a) Uninstall the InterBase service. If running InterBase as an application go to instruction 1b.

a) At the command prompt run: interbase\bin\instsvc stop (to stop the service). The service can also be stopped with the 'services' control panel applet. b) At the command prompt run: interbase\bin\instsvc remove (to remove the service). The service can also be removed from the registry manually. The entry is found in:

HKEY_LOCAL_MACHINE SYSTEM CurrentContorlSet Services

1b) Shut down the Server by right clicking on the InterBase icon in system tray and choose server shutdown.

2) Delete the InterBase Registry entries.

At the command prompt run: interbase\bin\instreg remove (to remove registry entries). The registry entries can also be deleted manually. The entry is found in:

(version < 5.0) HKEY_LOCAL_MACHINE SOFTWARE Borland InterBase

(version = 5.0) HKEY_LOCAL_MACHINE SOFTWARE InterBase Corp InterBase

3) Delete the InterBase Client library gds32.dll from the system.

On Windows 95 this file will be found in:

c:\windows\system

On Windows NT this file will be found in:

c:\winnt\system32

4) Delete all shortcuts.

On NT 3.51 delete InterBase server icon from startup groups.

On Windows 95 or NT 4.0, delete registry entry for Windows Startup of InterBase. This entry can be found in:

HKEY_LOCAL_MACHINE SOFTWARE CurrentVersion Run

5) Delete the InterBase directory. It is a good idea to have the InterBase licenses handy before beginning the installation process. The version 5.x InterBase installation process will prompt only for the InterBase Server Activation Key previously described. InterBase version 5.x is distributed on CD-ROM for all releases. The InterBase installation for Windows has a GUI based menu system that launches upon inserting the CD-ROM. The installation process is very simple and fast. The whole process takes between 5 to 10 minutes. The InterBase version 5.x installation for the UNIX based servers is not GUI menu driven. Please see the CD-ROM for platform specific installation instructions.

Post - Software Installation

Configuration After the installation process has completed successfully it is a good idea to configure the server. Don't forget to register the InterBase software just installed. Below are some items to pay attention to when configuring the InterBase server. Licensing While the InterBase licenses are handy it is the first logical configuration step to take. Use the GUI License Registration tool to load the remainder of the InterBase licenses. Upon finishing this, store the licenses in a safe place. The InterBase Server Process The InterBase Server Process is configurable on Windows NT. It can be run as a service or an application. It is recommended to run it as an NT service. This allows, among other things, the server to run while no-one is actively logged on to the NT Server. Due to the fact that Windows 95 does not support services, the InterBase server must be run as an application. It is possible to configure the InterBase process priority level too. The process can be set to run at 'high' or 'normal'. It is recommended to run the process at the 'normal' level. Setting the process to 'high' increases the priority of the InterBase thread that listens for incoming connections. This can decrease the performance of the threads active in the engine itself. This setting can be manipulated by selecting the 'advanced' tab in the Registry Configuration tool. The InterBase Guardian Process The InterBase Guardian Process, new to InterBase version 5.x also has multiple settings. The guardian is designed to restart the InterBase Server Process if it should abnormally terminate for any unknown reason. Its configuration can also be found by selecting the 'guardian' tab in the Registry Configuration tool. The guardian process has two basic settings. The settings are 'start once' and 'start forever'. The 'start once' setting tells the guardian to only start the InterBase server one time. If the process terminates abnormally it will not be restarted by the guardian. The 'start forever' setting does just the opposite. If selected, the guardian will continue to restart the server for as long as the machine is running. I recommend either disabling the guardian process or selecting the 'start once' option. If the server abnormally terminates I want to know about it so that the termination's cause can be debugged or traced. If the 'start forever' option is selected I would recommend that coding client applications to detect a loss of connection to the server so that they will know to reconnect. Environment Variables InterBase supports some special system and user environment variables. The matrix below describes the available environment variables and their functionality.

Variable Functionality

This variable is read by InterBase client applications when ISC_USER connecting to the ISC4.gdb if there is no (-user) flag passed in the connection string.

ISC_PASSWO This variable is used in conjunction with the ISC_USER RD variable.

This variable is used to set the InterBase home directory during INTERBASE runtime.

This variable is used to configure where InterBase will write its sort files. If it is not set the server will default to and write files INTERBASE_ to wherever TEMP (Windows) TMP (UNIX) is pointing. Both TMP of these options will be overridden if TMP_DIRECTORY is set in the InterBase Configuration file. (See page 78 of the Operations Guide for details)

INTERBASE_ This variable defines the location of where the InterBase lock LOCK file is created.

INTERBASE_ This variable defines the location of where the interbase.msg file MSG is to be.

The InterBase Configuration File The InterBase Configuration file (ibconfig) on Windows, (isc_config) on UNIX or interbas.cfg on Novell, is a text file used by the InterBase server. This file is used to control various distinct configuration parameters of the InterBase server, some of which are platform dependent. The InterBase Configuration file can be found in the InterBase root directory.

Variable Default Platform Supported On

CONNECTIO 180 All N_TIMEOUT

DATABASE_ CACHE_PAG 256 All ES

DEADLOCK_ 10 All TIMEOUT

DUMMY_PA CKET_INTER 60 All VAL

LOCK_AQUI 0 SMP machines Only RE_SPINS

LOCK_HASH 101 All _SLOTS

SERVER_CLI ENT_MAPPIN 4096 All G

SERVER_PRI ORITY_CLAS 1 Windows Only S

SERVER_WO RKING_SIZE 0 Windows Only _MAX

SERVER_WO RKING_SIZE 0 Windows Only _MIN

TMP_DIRECT none All ORY

TMP_DIRECT none All ORY V4_EVENT_ 32768 All MEMSIZE

V4_LOCK_G RANT_ORDE 1 All R

V4_LOCK_M 98304 All EM_SIZE

V4_LOCK_SE NA for v5.x None M_COUNT

V4_LOCK_SI NA for v5.x None GNAL

V4_SOLARIS _STALL_VAL NA for v5.x None UE

Upon installing the InterBase product you will find a default configuration file. By default none of the settings in the file are active. The '#' symbol is a marker indicating that the parameter is commented out. If the '#' symbol is removed the InterBase server will use the value specified for the parameter named. The InterBase configuration file is only read upon server start up. If changes are made to the configuration file, the server must be stopped and restarted before the changes will take effect. It is not recommended to make entries or changes to this file unless the resulting characteristics are understood and an application will benefit from its implementation. See (Pages 79,80 in the Operations Guide for details) Example: (All available Windows parameters with defaults)

# This is an example showing all the available Windows # InterBase Configuration settings. Each line in this file # has an 80 character max.

# CONNECTION_TIMEOUT 180 # DATABASE_CACHE_PAGES 256 # DEADLOCK_TIMEOUT 10 # DUMMY_PACKET_INTERVAL 60 # LOCK_AQUIRE_SPINS 0 # LOCK_HASH_SLOTS 101 # SERVER_CLIENT_MAPPING 4096 # SERVER_PRIORITY_CLASS 1 # SERVER_WORKING_SIZE_MAX 0 # SERVER_WORKING_SIZE_MIN 0 # TMP_DIRECTORY d:\interbase\temp # LOCK_HASH_SLOTS 101 # V4_EVENT_MEMSIZE 32768 # V4_LOCK_GRANT_ORDER 1 # V4_LOCK_MEM_SIZE 98304 The InterBase Security Database The InterBase Security Database is required for all servers. The Security Database can be found in the InterBase root directory. It is simply an InterBase database and is named ISC4.gdb. This database is used to store all USER information. There must be an entry in this database before a user can connect to a database on an InterBase Server. It is always a good idea to back up and archive ISC4.gdb. Having to recreate a user list can be an unfriendly task. NOTE: DO NOT DELETE the old ISC4.gdb before recreating it or GBAK will not function. GBAK must attach to ISC4.gdb and verify USER information before it will proceed thus, it is vital. Please see the example below for help. ISC4.gdb is used by the Server for validating USERs. It does not manage any database SQL Security. The security database can be administered with the Windows GUI tool, Server Manager. It can also be managed with GSEC.exe. When using 'add', a 'USER' name must be supplied prior to any USER attribute parameters. Passwords of up to 32 characters are accepted but, only eight will be utilized. 'uid' and 'pid' are displayed by default on all platforms but, are only used on the UNIX releases. It is also a good idea to change the sysdba password. Please see the following example. Example: (GSEC.exe usage)

# Example: GSEC.exe # # Environment variables ISC_USER and ISC_PASSWORD must be set # before running this executable. Use 'help' to display # parameters not used in this example.

E:\DBSgsec gsec - unable to open database Your user name and password are not defined. Ask your database administrator to set up an InterBase login.

E:\DBSset ISC_USER=sysdba E:\DBSset ISC_PASSWORD=masterkey

E:\DBSgsec GSEC

# Use 'display' to show USERs.

GSEC display user name uid gid full name ------SYSDBA 0 0 GSEC

# Use 'add' to add a new USER.

GSEC add AnAliasName -fname My -lname Name -pw NeverTell Warning - maximum 8 significant bytes of password used

# Use 'modify' to change USER attributes.

GSEC modify sysdba -pw Unknown GSEC modify analiasname -mname Real

GSEC display user name uid gid full name ------SYSDBA 0 0 ANALIASNAME 0 0 My Real Name

# Use 'delete' to delete a USER

GSEC delete analiasname

GSEC display user name uid gid full name ------SYSDBA 0 0 GSECquit E:\DBScd c:\apps\IB\v511

# Backup ISC4.gdb

C:\apps\IB\v511gbak -b isc4.gdb isc4.gbk

# Restore ISC4.gdb under a new name.

C:\apps\IB\v511gbak -c isc4.gbk isc4.new.gdb

# Rename the original ISC4.gdb

C:\apps\IB\v511rename isc4.gdb isc4.old.gdb

# Rename the new ISC4.gdb to replace the old one

C:\apps\IB\v511rename isc4.new.gdb isc4.gdb

Testing Your InterBase Network Configuration If using 'local' InterBase this section does not apply. It is always a good idea to fire up the server (if not already started from the install) and connect to a database. Starting the Server The process of starting and stopping the InterBase server process differs between Windows based releases and UNIX based releases. Windows It is recommended to run the InterBase server as an NT Service on Windows NT. The InterBase service can be started from the 'service' applet in the NT Control Panel. InterBase can run as an application on both Windows NT and 95. The server can be started as an application by selecting Start | Programs | InterBase | InterBase Server. Starting and stopping of the server can also be controlled via command line utilities as well. Example: (Windows service command line start and stop)

# The following commands are to be placed in a DOS batch # files.

@echo off

rem echo starting InterBase Server net start "InterBase Server"

------

@echo off

rem echo stopping InterBase Server net stop "InterBase Server" UNIX On the UNIX based platforms the command line tool 'ibmgr' must be used. 'ibmgr' can be found in the \bin from the InterBase root directory. 'ibmgr' requires that you supply a password when stopping the InterBase server. Example: (UNIX 'ibmgr' command line startup)

# The following command is to be run by 'root' or the # 'interbase' user.

ibmgr -start -once (or) ibmgr -start -forever (default)

ibmgr -shut -passwd masterkey Novell On the Netware based platforms the server runs as an NLM. NLMs must be 'loaded' to begin running. Loading the InterBase NLM essentially starts the InterBase server. Example: (Novell NLM command line startup) Load IBSERVER.NLM

Unload IBSERVER.NLM Using The Communications Diagnostic Tool The Communications Diagnostic tool can be used to test many different connectivity issues. It can be used to test connections to individual databases using all platform supported protocols. It can be used to test TCP as well as Netbeui configuration too. Please see the following example for each method. Example: (Using Communications Diagnostic)

# The Communications Diagnostic tool must be started prior to # performing these tests.

# Test No. 1 - Testing TCP Winsock

1) Select the 'winsock' tab 2) In the 'host' edit box enter a machine_name. Both client and server machines are valid. This test is ensuring that the SERVICES files are set up correctly. 3) In the 'service' edit box, select either 'gds_db' or the port '3050'. 4) Press 'Test'.

# If the test does not indicate success 1st check the services # file on the target machine for the appropriate InterBase # entries (see above), 2nd make sure that your TCP networking # is set up correctly.

# Test No. 2 - Testing Netbeui

1) Select the 'NetBEUI' tab 2) In the 'NT Server Name' edit box enter your NT Server's machine_name. Remember, NetBeui is not supported for servers on Windows 95. 3) Press 'Test'.

# If the test is unsuccessful, make sure that the NetBeui # protocol is installed. It can be checked by selecting # the 'protocols' tab on the 'network' icon in the Control # panel applet.

# Test No. 3 - Database Connection

1) Select either remote or local engine. 2) In the 'server' edit box enter your target server_name. 3) In the 'protocol' edit box select the protocol. 4) In the 'database' edit box enter the path to the database.

(ie. c:\dbs\employee.gdb)

5) In the 'user name' edit box enter the USER name. 6) In the 'password' edit box enter the USERs password. 7) Press 'Test'.

# If the test does not report success, make sure that the # above tests _do_ report success. If they do check to make # sure that there are no typing errors in the database path # or server_name. Finally, make sure that the database does # in fact exist. Understanding How InterBase Resolves Protocols It is important to understand how the InterBase Client resolves which pc i TD (gorstartandatabase.)Tj 12 Tf 721425 528.25 T test doesIt lyandasolureeor TD (In unlled orors inets pk. I TD (goor ned byors isyntax ofe that the)Tj 12 Tf 720075 573.connectiorostrrstarlureyou USERe path tw the InteS# or . ThD (Is or y(It is impowhen debs\rstat the)Tj 12 Tf 74.375 686.7your BDE e dad applicatiorsucOften developto fider sure thy therusrstaNetbeuiowhen thy thinkat the)Tj 12 Tf 7453 86.7 thy therusrstaTCPtabase.)Tj 12 Tf 744925 528.2Exat le: ( olves Pr Syntax Recognitioree.gdb))Tj ET 1 41425 5672.5 465.75 11.25 re 4035672.5 465.75 11.25 re 391. 581.75 465.75 11.5 re f BT /F4 10 Tf 0 g 739475 573.5 TI TD (or y(It is important to underolurewhich pc an cBase .gdb))Tj ET 1 38073 593.25 465.75 11.25 re f BT 0 g 738375 596.25 TD (usrstartacommunicatasoithea( # or r_nNdoeu TD (Underst.gdb))Tj ET 1 3 73 569 465.75 11.25 re f BT 0 g 7372596.25 Tth tfollowno tyxat les can leadartafals inets pk diagnosis'Test'.)Tj ET 1 357. 581.75 465.75 11.5 1 34673 593.25 465.75 11.25 re f BT 0 g 734925 528.25 T"Remote" connectiorostrrstasyntax'Test'.)Tj ET 1 33 5672.5 465.75 11.25 re 32 73 683.75 465.75 11.25 re f BT 0 g 732375 686.75#aTCP/IPTest'.)Tj ET 1 31273 593.25 465.5 11.25 re 301683.75 465.75 11.25 re f BT 0 g 730375 664(syntaxTD = " # or serve:drive(ieabas\to\the_o the datloy"Test'.)Tj ET 1 28 73 649.75 465.75 11.25 re f BT 0 g 729375 652.75(yxat leTD = "mtnbkr:d(ie. c:\dbs\employ"Test'.)Tj ET 1 27873 593.25 465.5 11.25 re 267649.75 465.75 11.25 re f BT 0 g 7270686.75#aNetBeuiTest'. # As with the previous GSEC example the InterBase # environment variables ISC_USER and ISC_PASSWORD are # set. This is not a requirement for ISQL but, does # eliminate having to supply USER and PASSWORD # information each time you connect to a database. For # the remainder of this paper the examples will assume # that these variables are set.

D:\dbsisql connect d:\dbs\employee.gdb Database: employee.gdb

SQL show database; Database: employee.gdb Owner: SYSDBA PAGE_SIZE 1024 Number of DB pages allocated = 467 Sweep interval = 0 SQL Testing a Local Loopback Connection What is 'local loopback'? The local loopback operation is a way in which a server's remote connection acceptance can be tested. Local loopback does require networking to be configured. This test uses the 'loopback' address, 127.0.01 seen in the examples above. It is often a good test to perform before installing any of the client software. Making sure that this test succeeds can eliminate any 'server' setup questions when installing the client software. Example: (Local Loopback Connection)

D:\dbsisql connect the_server:d:\dbs\employee.gdb Database: the_server:d:\dbs\employee.gdb

SQL show database; Database: the_server:d:\dbs\employee.gdb Owner: SYSDBA PAGE_SIZE 1024 Number of DB pages allocated = 467 Sweep interval = 0 SQL Testing a Remote Connection Testing a connection to a remote server from a client is exactly the same as with the local loopback method except that the target server is a different machine than the one performing the communications test. Example: (Remote Connection) D:\dbsisql connect remote_server:d:\dbs\employee.gdb Database: remote_server:d:\dbs\employee.gdb

SQL show database; Database: remote_server:d:\dbs\employee.gdb Owner: SYSDBA PAGE_SIZE 1024 Number of DB pages allocated = 467 Sweep interval = 0 SQL

Trouble Shooting Common InterBase Network Failures

Trouble shooting a network configuration can be a messy operation. Having a networking expert present to configure and test is a worth while investment. If a networking expert can not be afforded there are some simple tests that can be performed to validate the existence of machine connectivity. The examples below are very entry level tests. Setting up a network is outside the scope of this paper. TCP / IP Related Failures The TCP protocol has a very simple testing mechanism that enables machine identification on a network. Testing With (Ping) In this example I will demonstrate two tests with ping. The first tests to ensure that the two machines can communicate with each other. The second test ensures that the machine name can be resolved to an IP address. It is the second test that is important to ensure that InterBase can communicate successfully. This test's the success or failure is directly related to the entries in the HOSTS files on machines. Ping has various implementations based on platform. Do not be alarmed if the output from ping does not look exactly like this example. Example: (Testing with Ping)

# Pinging by IP address.

d:\ping 123.123.123.100

Pinging 123.123.123.100 with 32 bytes of data:

Reply from 123.123.123.100: bytes=32 time<10ms TTL=32 Reply from 123.123.123.100: bytes=32 time<10ms TTL=32 Reply from 123.123.123.100: bytes=32 time<10ms TTL=32 Reply from 123.123.123.100: bytes=32 time<10ms TTL=32

# Pinging by Machine Name. d:\ping ibserver1

Pinging ibserver1.ib.com [123.123.123.100] with 32 bytes of data:

Reply from 123.123.123.100: bytes=32 time=10ms TTL=255 Reply from 123.123.123.100: bytes=32 time<10ms TTL=255 Reply from 123.123.123.100: bytes=32 time<10ms TTL=255 Reply from 123.123.123.100: bytes=32 time<10ms TTL=255

# Ping by Machine Name failure. InterBase will not work # if you are receiving this message.

d:\ping NotOutThere Bad IP address NotOutThere. Netbeui Related Failures If the installation of Netbeui has already been confirmed there is a simple test that can be done to ensure that it is working properly. In addition to the command line test described below, mapping a drive between machines through the Windows Explorer is also a good test of a successful Netbeui installation. Testing With (Net Send) Net Send is a command line utility that allows for messages to be sent between machines. Example: (Testing with Net Send)

# For help on using net send type "net send /?"

# Net Send from the server to the server. A loopback # like Test

net send the_server "testing loopback"

# If the communication is successful a message box will # display on the screen.

# Net Send from the server to a client.

net send client_one "are_you_there"

# If the communication is successful there will be a # message on the client machine screen.

# Net Send failure.

net send NotOutThere "Hello" An error occurred while sending a message to NotOutThere.

The message alias could not be found on the network. More help is available by typing NET HELPMSG 2273. SPX / IPX Related Failures The SPX protocol can be tested with IPXPING.

Migrating Databases From Version 4.x To Version 5.x Are InterBase version 4.x databases compatible with version 5.x Servers? Yes! There are however some important issues to consider when making this migration step. Listed below are a few of the more important things to consider when migrating v4.x databases to a v5.x InterBase server. On Disk Structure - ODS The InterBase ODS is a database characteristic kept on the database's header page that allows for support of various database structures and server version specific features. InterBase v4.x has an ODS version of 8.0. InterBase v5.x has an ODS version of 9.0. A v5.x server can access a v4.x database. Upon doing so the server converts the ODS to 8.2. This allows for some of the v5.x features (index garbage collection) to work. The database will not be converted to ODS 9.0 until a full backup and restore on the v5.x server is performed. Example: (GBAK upgrading a database ODS)

# View a v4.x database header page before accessing # it with a v5.x InterBase Server engine.

D:\dbsgstat -h my_ODS_80.gdb

Database "my_ODS_80.gdb"

Database header page information: Flags 0 Checksum 36703 Generation 25 Page size 1024 ODS version 8.0 isql connect my_ODS_80.gdb Database: my_ODS_80.gdb SQL exit;

# View a v4.x database header page after accessing # it with a v5.x InterBase Server engine.

D:\dbsgstat -h my_ODS_80.gdb

Database "my_ODS_80.gdb" Database header page information: Flags 0 Checksum 36759 Generation 27 Page size 1024 ODS version 8.2 gbak -z -b my_ODS_80.gdb my_ODS_82.gbk gbak: gbak version WI-V5.1.1.680 gbak: Version(s) for database "my_ODS_80.gdb" InterBase/x86/Windows NT (access method), version "WI-V5.1.1.680" on disk structure version 8.2

# Restore the v5.x backup ON using the InterBase # v5.x engine.

D:\dbsgbak -z -c my_ODS_82.gbk my_ODS_90.gdb gbak: gbak version WI-V5.1.1.680 gbak: Version(s) for database "my_ODS_90.gdb" InterBase/x86/Windows NT (access method), version "WI-V5.1.1.680" on disk structure version 9.0

# View the new v5.x database header page after # restoring it with a v5.x InterBase Server engine.

D:\dbsgstat -h my_ODS_90.gdb

Database "my_ODS_90.gdb"

Database header page information: Flags 0 Checksum 12345 Generation 25 Page size 1024 ODS version 9.0 To avoid any potential problems it is always a good idea to deploy a backup (.gbk) file and have a customer restore the database with the server engine that they have. WARNING: The v4.x server CANNOT access a v5.x ODS 9.0 database. This is because when the InterBase v5.x Server was built the v4.x Server had no knowledge of nor did ODS 9.0 exist. New Key Words There are new key words with InterBase v5.x. These new key words are: ACTION ADMIN CASCADE RESTRICT ROLE FREE_IT In order to work properly InterBase v5.x database definitions cannot contain the above mentioned key words. For compatibility, migration and data loss reasons GBAK will NOT detect nor disallow these key words during the backup or restore process. A good way to local or test for these key words is to perform a metadata extract of a database on a v5.x server. Write the output to a file and either perform a word search on the file or attemp to rebuild the database structure with the v5.x engine. If there are key words present in the DDL the ISQL parser will detect them and error out. Example: (Extracting DDL to locate key words)

# Use ISQL to extract the DDL and write it to # a text file.

D:\dbsisql -extract my_ODS_80.gdb -o my_ODS_80_DDL.

# Use the new DDL script to attempt to rebuild the # database structure. The script file may require the # renaming of the database to be created.

D:\dbsisql -i my_ODS_80_DDL.sql It is possible to manually edit the system tables to remove the new key words from a v4.x database and replace them with non-offending DDL names. Please see the InterBase documentation for instructions on how to do this. Optimizing Query Performance This is a crucial element in migrating to a new server version. A slow performing database will be the first thing a customer notices if the new engine does not process queries as fast as the older engine did. There were many changes to the InterBase optimizer between v4.x and v5.x. The optimizer is the utility that determines and builds the best access plan to retrieve the data requested. InterBase offers the SET PLAN option for use with ISQL and WISQL. It should be used with the 'SET STAT' option to display performance statistics. When using this option the engine will return the query plan that the optimizer has chosen to take. If the optimizer does not for some reason take what may be the fastest method, it can be over-ridden by naming the plan in the queries syntax. Please note that this example does NOT really demonstrate a sub_optimal plan selection but, rather what might happen and how to use the 'SET PLAN' and how to name the PLAN in a query. It is for this reason that I do not demonstrate the 'SET STAT' output in this example. Example: (Using SET PLAN) # Example DDL Script:

# ------begin script ------create database "demo_plan.gdb" user "sysdba" password "masterkey"; create table index_test1 ( a integer not null, b integer); commit; create unique index single_key_on_a_idx on index_test1 (a); create unique index multi_key_on_ab_idx on index_test1 (a,b); commit; insert into index_test1 (a,b) values (1,1); insert into index_test1 (a,b) values (2,1); insert into index_test1 (a,b) values (3,2); insert into index_test1 (a,b) values (4,1); insert into index_test1 (a,b) values (5,1); commit; set plan; select * from index_test1 where a = 3; select * from index_test1 where a = 3 and b = 2; commit; select * from index_test1 where a = 3 PLAN (INDEX_TEST1 INDEX (SINGLE_KEY_ON_A_IDX)); commit;

# ------end script ------

# Example Script Output:

D:\dbsisql -i demo_plan.sql Use CONNECT or CREATE DATABASE to specify a database Database: demo_plan.gdb, User: sysdba Database: demo_plan.gdb, User: sysdba

PLAN (INDEX_TEST1 INDEX (MULTI_KEY_ON_AB_IDX))

A B ======3 2

PLAN (INDEX_TEST1 INDEX (MULTI_KEY_ON_AB_IDX))

A B ======3 2 PLAN (INDEX_TEST1 INDEX (SINGLE_KEY_ON_A_IDX))

A B ======3 2

Getting Started With InterBase When first beginning to create InterBase databases it is a good idea to become familiar with the SQL statement syntax that InterBase supports. A description of our SQL support can be found in the (Language Reference and Programmers Guides). There are many tools that can be used to manipulate InterBase DDL. InterBase ships ISQL and WISQL. The Borland brand client server tools ship with the Database Explorer. There are many third party data modeling and special purpose tools available. A good source of information for this kind of stuff is the Dunstan Thomas website. The DT site is a huge resource for information and tools. I find that it is a good idea to manage my DDL files much like source code. I tend to version and archive my databases throughout the development cycle so that I can return to past code if necessary. Depending on the size of the schema, I either keep a script copy or sometimes just a .gbk file with no data. The GBAK utility makes this process really easy. GBAK has a 'metadata only' flag that allow for the data to be excluded from a backup.

The Most Commonly Made Mistakes Using InterBase It is quite common that developers make the same initial mistakes when using a new product. I think these mistakes occur due to three primary reasons. First may be a lack of product documentation. Second, they might occur because of simple misuse. A typing or syntax error is often the cause of these kinds of mistakes. The third generally occurs when a developer is unfamiliar with the technology or used to a mind set better applied with a similar type of technology. A great example of this is when Paradox developers try to apply their flat file techniques with InterBase's relation database functionality. Below are some of the most commonly encountered mistakes in the InterBase Technical Support department.

The Top (n) Common Mistakes Services File or InterBase Entries Missing This problem occurs because InterBase requires that SERVICES files are present on both the client and the server when using the TCP protocol. Please reference the example SERVICES file previously discussed in this paper. Hosts files entries missing There are different ways of configuring TCP networking. When using straight HOSTS files in a networking configuration, the entries within them must be exact for the machines to be able to communicate. Please reference the example HOSTS files previously discussed in this paper. Not starting the server Sometimes a connectivity problem can be as simple as the accidentally not starting the InterBase Service. If the service is not started there will be no open socket for port 3050 and a remote client will not be able to connect to databases on the server. General host equivelence (trusted host) General host equivelence is required for InterBase. To establish a trusted host relationship between the client and the server, an entry must be in the server's /etc/hosts.equiv or /etc/gds_hosts.equiv file. The hosts.equiv file will setup an OS trusted host relationship, which extends to other services (for example rlogin, rsh, rcp). The gds_hosts.equiv will setup an InterBase only trusted host relationship. If running in 'loopback' mode the word 'localhost' be present in the /etc/hosts.equiv file. Trying to connect with IP address InterBase does not support connection strings with IP addresses. InterBase requires that it be able to resolve machine location by host_name. Please see the section of this paper that explains this. DNS server times out. This results in and unable to locate host message. It simply means that the DNS resolution cannot resolve and the request has timed out. Incorrect Licensing Incorrect licensing can often be a cause of problems. This can occur if trying to connect to LIBS from a remote client. It can occur if the correct license file is not present on the client machine. It can also occur if the server machine does not have an 'S' bit, LIBS, or if this bit has not been uninstalled from the license file. Using the wrong protocol in connection string InterBase resolves which protocol to use by the syntax used in the connection string. If the remote server does not support the protocol the connection will fail. The connection can also fail if the appropriate protocol is not installed. It is important to understand what protocol is being used when writing InterBase applications so that the connection syntax will be valid. Trying to connect with a Mapped drive InterBase does not support the use of 'mapped' or 'shared' drive names on the Windows platform. As well it does not support NFS mounted drives on UNIX. If there is not an InterBase server running on the machine where the disk housing the database is resident, the connection will fail. NFS with no server running on host machine This can occur when using NFS mounted file systems with UNIX. InterBase does not support NFS mounted file systems. Unless there is an InterBase server running on the machine from which the file system is being mounted from the databases must be resident on the local machines disk array. ODBC or BDE driver is not installed When using ODBC or BDE based applications the appropriate drivers must be installed for the applications to work. Database is not in location that one thought it was This can occur is the DBA or owner of the database has moved the database. This is most common when applications that use database alias' that hard code the path to the database are not recompiled to reflect the new location of the database. Database name has changed If the name the target database has changed and the connection syntax has not changed to reflect this the connection will fail. Spelling errors in connection string If there is a typing error in the connection string for the target database the client will not be able to resolve its location and the connection will fail. File / Directory Permissions problems This can occur if there are not sufficient file permissions in the directory containing the database. Non C/S Development Tool The Borland development tools editions 'professional' and 'standard' do not include the appropriate BDE and SQLLinks drivers to make connections to remote databases. Using Windows 95 as a Server with Netbeui Windows 95 does not support the Netbeui protocol as a service. This restricts InterBase and forces developers to use TCP as a protocol when running InterBase as a multi-user server. This is not a limitation of InterBase but, rather a limitation of Windows 95. ISC4.gdb (no user) This problem occurs when a user attempts to connect to an InterBase database but, does not have an entry in the InterBase security database. Client library not installed This problem occurs most frequently with deployed BDE and ODBC applications where the InterBase client library (gds32.dll) has not been installed or is incorrectly installed. Using v5.x client library with v4.x license This occurs when attempting to use the Interbase v5.x client library with the older v4.x licenses. The license files between InterBase versions are not compatible. License file missing This occurs when InterBase license file is incorrectly installed or missing all together. BDE alias not created This problem can occur when trying to connect to an InterBase database using BDE or ODBC based middleware and an appropriate alias has not been set up. SYSDBA - masterwhat? This problem can occur if the customer does not have the product documentation or perhaps if the user is not the person who installed the software. The default 'administrator' for InterBase is 'SYSDBA' and the default password is 'masterkey'. SQL privileges are not granted by default SQL security requires that a user be granted whatever actions they are trying to perform against an object in a database. This can be resolved by using SQL GRANT statements. TCP NLM not loaded first When using Novell as an InterBase server the TCP.NLM must be loaded prior to loading the InterBase NLM.