Subject Re: [firebird-support] sample C code for connecting to embedded server?
Author Helen Borrie
At 03:58 PM 9/01/2004 -0500, you wrote:
>Thank you for your response below. Yes, I do have the API guide, and all
>kinds of other documentation that I downloaded. I probably haven't spent
>enough time wading through it all. Also, I don't have a lot of experience
>on Windows, so I'm not all that familiar with how to compile and link source
>code, how to include libraries and/or DLL's, etc. I recently installed
>MetroWerks Code Warrior and was able to successfully build a different
>application, so I'm not at a complete loss, but Firebird looks more involved
>than what I did.
>What I was looking for was a very simple "Getting Started" document that can
>tell me the steps necessary to install Firebird, compile a sample
>application, and run it. In particular, I was hoping to do this using the
>Embedded server (the DLL) that you describe below.

The installation instructions for the embedded server library are in the
release notes. There is also a readme in the \doc directory.

>Instead, there are a
>whole bunch of different PDF docs about different pieces, and I'm further
>confused by the fact that some of them seem to apply to Interbase rather
>than Firebird.

The PDF docs *are* the beta docs that were distributed with the original
open-sourced code.

Currently, "Firebird docs" = IB6 beta docs + release notes for Firebird 1 +
release notes for Firebird 1.5.

>For instance, the Getting Started doc describes an installation program on a
>CD, which I don't have.

The IB 6 Getting Started doc isn't applicable to Firebird 1.5. For a
complete newbie on Windows, the Windows installer would have been your best
bet. It's self-documenting and the defaults ought to get you going.

Download the Quick Start Guide from ibphoenix - it's currently only for
Firebird 1.0 but there's stuff in there that will help to shorten your boot
camp some.

>Instead, I tried the install_super icon in the
>Firebird bin directory and something happened, but I didn't get any kind of
>installation wizard.

Hmm, I dunno. If you already had a Firebird bin directory, you had
probably already installed the server and the remote client. The MSDOS
.bat files are kinda like Linux shell scripts, though with much more
limited capability. They have *already* been run by the installer.

>I think what happened was that Firebird got started as
>a service.

It would, if you took the installer's default option. You can check by
inspecting the Services applet through the Control Panel.

>I suppose this is not what I want, if I want to be using the DLL
>rather than the free-standing server.

Well, you can run a full server on the same machine as an embedded
server. The embedded server depends on its local filestructure to find its
own bits and pieces. You really should read the release notes. To some
extent, the release notes and any other documentation assume that you know
what you are doing on the operating system. If you're a Windows newbie,
you have a certain amount of research to do.

A full installation also has all the docs, examples, command-line tools,
includes, etc. so I reckon you need to keep your full install around at
least until you have a clearer idea of what you are doing. You'll need the
server, to use an admin tool and the command-line tools.

>Also there is mention of some
>IBConsole program which can be used to setup databases, but that doesn't
>seemt to be included in what I downloaded off the webpage.

No, IBConsole is an external program distributed by Borland. Don't bother
with it as it's not fully compatible with Firebird 1.5. Go to the
Downloads > Contributed pages of and choose a graphical
admin tool there. I have to say, though, that if you're not familiar with
either the OS or the operating system, no tool is going to be obvious to
you at first sight.

>I suspect there is a simple way to do what I want, which has steps like the
>1. place the Firebird embedded server DLL (fbembed.dll?) in some directory
>2. place a sample database in some directory
>3. define some environment variables somewhere or other

This much is in the release notes. There is a sample database named
employee.fdb in the \examples directory of a full server installation.

Simple? .. the embedded server provides a "desktop model" for deploying a
client/server database. If you're expecting to grok Firebird from the
perspective of one who hasn't worked with client/server databases before
and doesn't know his way around the OS, it would be hard to claim that it
would be simple.

>4. create a C project with the following files from the examples directory
>and build it, and run it.

Not really; but in \examples there is a series of C source files with some
drop-dead simple examples for using the "essential" API functions in the
raw. All units have names starting with "api". You are more likely to
find sample projects with the component-based tools like IBPP, etc.

>Once I've gone through these steps I'll understand how to make my own
>Obviously I need to do further study, but if you can point me in the right
>direction I'll be most appreciative.

If you're planning to code applications with raw API then the API Guide is
your main resource.

The Operations Guide is a pot-pourri of essential stuff, including manual
material for using the command-line tools. Focus especially on isql to
start with - it is your "eye on a database" as well as an interface for
running interactive queries and data definition scripts. Once you get
frustrated with the shell interface, you'll have a fairly good idea of the
features you want when selecting a GUI admin tool.

The Language Reference relates to SQL syntax - mainly dynamic SQL (which is
the set of SQL statements you can pass through the API) and PSQL (the
language for writing stored procedures and triggers). It also has syntax
(but not instructions) for Embedded SQL which you're not planning to use.

The language stuff in the Embedded SQL Guide won't be applicable but that
manual is actually the best-written of all the InterBase manuals. It has
the only decent expositions about transactions. What I'm saying is that
it's worth having this manual by you for the stuff in it that's not
specific to ESQL, because you won't find that stuff anywhere else.

The Data Definition Guide will give you the basics about data types.

Don't even bother with the Programmer's Guide - it's a complete waste of
space. it was an attempt by some non-Delphi programmer to try and document
a set of Delphi components which were unfinished at the time.