
Application Environment and Configuration
==================================================

Running an application
--------------------------------------------------

In general, all applications will run in the same working directory as
each other. This includes stand alone programs, batch programs and the
server program for the user interface. This working directory defines
a consistent installation environment and will contain a number of
standard elements:

  :lk_config.ini:

    A configuration file. It can be called anything, so long as the
    extension is `.ini` (case insensitive). The file is found in the
    current working directory. If there is more than one `.ini` file
    (of any name) in the directory then the search is refined to
    `lk*.ini`. There must be only one resulting `.ini` file.

  :job_environment.conf:

    A configuration file for the job environment used by batch
    (background) programs. Individual programs can use a different
    file if they require. See `tb_job_manager/job_environment.py`

  :job_environment.d: 

    A directory containing parameter files for the command line
    (batch) programs. Each command line program expects to find a file
    that has the same name as the main module of the program. See also
    `tb_job_manager/job_environment.py` for possible variations on
    this.

 :initial data:

    Files that define the initial settings for user interface elements 
    (such as the user sign-on).

Configuration file
--------------------------------------------------

The configuration file is structured in a similar way to what you
would find on Microsoft Windows INI files.

To quote the python documentation:

  The configuration file consists of sections, led by a "[section]"
  header and followed by "name: value" entries, with continuations in
  the style of RFC 822; "name=value" is also accepted. Note that
  leading whitespace is removed from values. The optional values can
  contain format strings which refer to other values in the same
  section, or values in a special DEFAULT section. Additional defaults
  can be provided on initialization and retrieval. Lines beginning
  with "#" or ";" are ignored and may be used to provide comments.

The configuration file is concerned primarily with defining the user
interface environment. Standalone programs, including batch programs,
will use the configuration file only when they need to connect to a
database. Each database used within the installation must appear in at
least one section in the configuration file. 

sections
++++++++++++++++++++++++++++++++++++++++++++++++++

The configuration file contains a number of sections. In general each
section corresponds to a single component that will appear at the top
level of the menu structure in the user interface. Some standard
sections are defined, and any component that is need for the
particular installation will require its own section.

These sections are pre-defined:

 :[server]:

    Defines how the web server environment works. This section contains
    the definition of the database that holds http session data.

 :[all]:

    Gives comon parameters for the display of the user interface.

 :[login]:

    Defines a component that gives log in and log out menu
    items. This section contains the definition of the database that
    holds the tables that support the user interface, such as user
    identity and permissions.

 :[admin]:

    Defines a component that allows access to user details.

 :[home]:

    Defines a component that provides a default set of screens when #
    no user is logged in.



database connection definitions
++++++++++++++++++++++++++++++++++++++++++++++++++

Within any section it is possoble to define access to one or more
databases. A database connection is defined by one or more name/value pairs where
the name is made up of a prefix and a suffix. The prefix is the name
by which the database is known in the application code, and the suffix
is one of a number of possible values that help to define the
database.

That is, a name looks like `ddddddd.ppp` where `dddddddd` is the
database internal name, and `ppp` is a specific database parameter.

For example, if the application defines a database with the internal
name `data_store`, the following names can be used:

 :data_store.url:

    A url that defines where the database is, and how to access
    it. The url is introduced by a database type and followed by
    optional access parameters and a database name. For example: 
    **postgresql://user:password@localhost:5432/database_name**. 
    This item is mandatory for defining a database connection.

    It is possible to define multiple connections to a single
    database. In this way, a single database can be shared between
    applications and such a shared database may contain a number of
    application specific tables.

 :data_store.convert_unicode:

    An SQL Alchemy parameter that defines how SQL Alchemy should
    handle unicode data.

 :data_store.echo:

    An SQL Alchemy parameter that controls echo of the underlying SQL
    statements


----
