======================================
The GNUe "Connections Definition File"
======================================

-----------
File Format
-----------

The Connections Definition File is a text file consisting of sections and 
parameters. 

The file is line based.  Each end of line denotes the end of a parameter or 
comment.  However, any line ending in an "\" is continued on the next line.

Parameter and section names are not case dependent.  Case is preserved in 
parameter values (the text to the right of the equals sign.)

Any line beginning with a "#" or a ";" is considered a comment and is ignored.

Whitespace before or after the first equals sign ("=") is ignored.  All
whitespace in a parameter's value is preserved.


--------
Sections
--------

A section begins with a connection name enclosed in brackets ("[" & "]").  It
is then followed by one or more parameters.  A section ends either when a new
section is defined or at the end of the file.  A sample section that defines
a connection named "gnue":

      [gnue]
      provider = postgresql
      dbname = mydb
      host = localhost


----------
Parameters
----------

connection

   This parameter specifies a connection string to be used by the database
   provider.  The format of the connection string is provider dependent and
   not all providers recoognize this parameter.

   In most implementations, a connection string can be used in place of the
   "dbname" and "host" parameters.

   Example (for an ODBC connection):

      connection = "Driver={mySQL};Server=localhost;Database=gnue;"

   This parameter has no default and is not required unless implemented as
   such by the provider.


comment

   This parameter is a text field that is seen in a list of available
   connections.  The comment should provide more information regarding
   the connection than the connection name.

   Example (for a connection named "acctaud"):
       
      comment = Accounting's Audit Trail Database

   This parameter has no default and is not required.


dbname

   This specifies the name of the database to attach/connect to.  
   Implementation is provider specific.

   Example (for a mysql connection with a database named gnue): 
   
       dbname = gnue

   This parameter has no default and is not required unless implemented as
   such by the provider.


host

   This parameter specifies the name of the host that the database server 
   is running on.  Implementation is provider specific but is usually 
   an IP address or DNS resolvable hostname.  

   "localhost" is a valid host name but keep in mind that the client machine
   (in a client/server or peer-to-peer implementation) will be resolving the 
   host name.  Therefore, even though the connections definition file and 
   the database server may reside on the same machine (and therefore to that
   machine "localhost" IS the machine's name), the client will read the 
   connections definition file from the server and do its own name resolving.

   Example (for a database residing on the dbserver.mydomain server): 
   
       dbname = dbserver.mydomain

   This parameter has no default and is not required unless implemented as
   such by the provider.


provider 

   This specifies the database provider. See the PROVIDERS section for a list 
   of supported providers.

   Example (for a postgresql database): 

      provider = postgresql

   This parameter has no default and is required.


aliases

   This space delimited parameter creates "aliases" for the current connection.
   For example, if you have a section:

   [test1]
   aliases = test2, test3
   provider = postgresql


   Then "test1" can also be referred to in datasources as "test2" and "test3".
   

---------
Providers
---------

See README.databases for a complete list of providers.


--------------
File Locations
--------------

The Connections Definition File may be a locally readable file or a URI 
resource.  Supported URL identifiers are "http://", "ftp://", "file://", and
"gopher://".

The location of the file can be provided to the GNUe client application in 
one of two ways.  All client applications support the "--connections <loc>"
command line option.  For example, if the connections file is located at
"http://appserv.mydomain.org/connections.gnue", then a client could be 
started as such: 

   $ gnue-forms --connections "http://appserv.mydomain.org/connections.gnue"

Another example using a local file: 
   
   $ gnue-forms --connections "/usr/local/gnue/etc/connections.gnue"

If no command line option is provided, then the client application will then 
check for an environment variable called "GNUE_CONNECTIONS".  If this is 
set, the client assumes this variable points to the connections file.  As with
the --connections option, this can point to either a local file or a URI 
resource.  An example using GNUE_CONNECTIONS: 

   $ GNUE_CONNECTIONS="http://appserv.mydomain.org/connections.gnue"
   $ export GNUE_CONNECTIONS
   $ gnue-forms

Also, using a local file: 
   
   $ GNUE_CONNECTIONS="/usr/local/gnue/etc/connections.gnue"
   $ export GNUE_CONNECTIONS
   $ gnue-forms

Ideally, GNUE_CONNECTIONS would be set in a user's .profile file.  In a 
multi-system environment (where the individial clients can be run on
different machines), it would be best to home the connections file either
on a shared drive or as a URL referencable resource.  This way, only one 
connections file must be maintained.

When URL resources must be accessed via a proxy, the environment variables
http_proxy and ftp_proxy can be used to specify the proxy.  For example: 

  $ http_proxy="http://proxy.mycompany.org:3128"
  $ GNUE_CONNECTIONS="http://appserv.mydomain.org/connections.gnue"
  $ export http_proxy, GNUE_CONNECTIONS
  $ gnue-forms someform.gfd

Due to limitations of the python libraries, proxies requiring authentication 
are not currently supported.



