The Make2D-DB II Package current version: 3.10.2 -- December 2011

Read-Me (Configuration)

This is a help file to assist users configuring their tool. Although during the configuration process many parameters are fairly well described, more details can be found within this document. At the end of this file, you will also find some notes on how to configure the test database(s).

How To Launch The Configuration Process

There is a main configuration file, namely basic_include.pl which is located in the config directory. This file is automatically copied from this config directory to your Apache server directories (into cgi-bin/your_database_interface/inc/basic_include.pl). This file contains some global definitions for both the installation process and the running server parameters. It may be modified by users for some special behaviors (you may inspect this file to have an idea of what it does control and edit it to make some very specific changes). There is also a default master copy of this file in the lib2d directory with the name basicIncludeInitial.pl. Whenever you need to restore the initial default values, just copy this basicIncludeInitial.pl to the config directory under the name of basic_include.pl.

In addition to this basic file, there are two configuration files that have to be set up by the user before executing the database conversion / creation process. Those two files are the following:

• include.cfg (main configuration file for the database conversion / creation process, example)
• 2d_include.pl (server configuration file for the Web server interface, example)

The syntax for a parameter is:

         $parameter_name = "parameter value";

The "parameter value" are included between quotes or double quotes, and the line must end with a semicolon. Digital parameter values do not need to be included inside quotes.
A line starting with a '#' sign indicates that this is simply a comment line and is ignored, while comments at the end of some parameters' lines (like # Do not change! or # evaluated!) are used internaly by the tool and should not be removed.

In most cases, users do not need to directly generate or edit those files themselves. Instead, they can interactively generate them by typing the command:

perl make2db.pl -m config

The very first time you use the tool, you should choose to generate the files by selecting:

[1] New Installation

then

[1] Default Configuration

If you decide later to replace some of your settings from your previous generated configuration files, then execute again the main script with the '-m config' (and -c some_path if needed) option. Choose

[2] Last Personal Configuration Files

after selecting

[1] New Installation

Your old configuration files will then be renamed 'include.cfg.old'and '2d_include.pl.old' inside the <config> directory (or the alternative path).

As mentionned before, the first configuration file (include.cfg) will be used only for your conversion process, while the second (2d_include.pl) will be used by the Web query interface as long as it is running on your server. If you decide at any later moment to change the initial behavior of your running query interface or to add  more or suppress some local databases / projects, then you can directly edit this file (which will be then located inside your server directories tree, by default in 'cgi-bin/your_database_interface/inc/2d_include.pl') or execute again the main script using the '-m config' option. This time you will need to choose the

[2] Changing a Running Server Parameters

option and follow the instructions.

Finally, if you are only interested in building a Web portal to access remote interfaces from one single entry point, event if you do not have any local data, then select 

[1] New Installation

then

[3] Configure a Web portal

and follow the instructions

During the configuration set up process, the different parametres are described to the user and default values are proposed. Nevertheless, in this Readme file, we will list in details the meaning of each parameter for both files. All parameters are given a default value. But whenever you see a parameter in red color this means that this parameter SHOULD/IS EXPECTED to be set up by the user.

One final remark: each time a parameter is followed by the comment "# Do not change!" you will not be able to change its value interactively (and logically you will not need to). A "# evaluated!" comment means that the proposed default value will be initially evaluated depending on some of your previous settings.

Tips:

- If you want to inspect or to modify just one or a couple of values, then you may find it easier to edit directly those files manually, rather than using the -m config option.

- For each parameter, you are asked if you want to change the current value (y/n). You may enter 'y', then type the new value. But you may also directly enter the new value (if it is not empty) without entering 'y' before.

The Main Configuration File: 'include.cfg'

(You may inspect the two configuration files, example.include.cfg and example.2d_include.pl, given as an example within the "data_test/examples" directory)

# The postgreSQL main user (or your postgreSQL user name! being the main owner of the new database and having full write permissions)
# if the postgreSQL main user is set to 'default' the name (system login ID) of the current user will be used

$postgres_user = "your_ID"; # evaluated!

This is the 2D database owner ID. By default it is supposed to be the user login ID to the system. Change it if your postgreSQL user account is not the same. This account is also supposed to have "create users" permissions. If it is not the case, you will be asked to "create a user" manually during the installation. Any defined value is automatically removed, for obvious security reasons, from the copy of this file that goes into the server directories!

# Password for the postgreSQL main user:

$postgres_user_password = '';

Your postgreSQL user account password. Any defined value is automatically removed, for obvious security reasons, from the copy of this file that goes into the server directories!

# PostgreSQL select user (the tool will create this user with no write permissions, only to query the database)

$select_user = "select2d";

This is the default select user name that the query interface will use to connect to the postgreSQL database. You can set it to any other valid postgres user name.

# PostgreSQL select user password, if not specified, the password will be set up identical to the select user name
# (adapted to pg_hba.conf with password parameters -> no trust)
 
$select_user_password = "";

This is the password to use with the previous select user. If you leave this value blank, as proposed, the password will be the same as the select user ID (by default 'select2d').

The block marked:  'Perl'

# PERL Location (for the CGI server scripts to run)
# The PERL you are currently using has been detected at the following path:

$perl = "/usr/bin/perl"; # evaluated!

This is where the default Perl has been detected on your system

# Is the Perl *libwww-perl* module installed (LWP)? or is Perl 5.6 or Active Perl installed (0 for no, 1 for y)?
# If not, set $libwww to 0. Doing so will imply deactivation of all external http connections to collect external data.
# Information about this module can be found within this package in the 'libs' directory.
# (For an up-to-date version of the module, visit http://search.cpan.org/dist/libwww-perl/)

$libwww = 1;

With recent perl versions there is no need to worry about changing this parameter.
Only if you are using perl 5.005 then you will have to check for the presence of the LWP module (part of the libwww module). If the module is not present, then set this value to 0 (otherwise you will get this error message during execution: ''Can't locate LWP/UserAgent.pm...'') or install the module from CPAN (see with your system administrator). When set to 0, no external data retrieval will be performed.

# Is the Perl *XML::Parser* (XML-Parser), *XML::Parser::PerlSax* (libxml-perl) and *XML::Twig (XML-Twig)
# modules installed (0 for no, 1 for y)?
# If none of them is installed, set $libxml to 0. Doing so will deactivate all XML parsing and write operations:
# e.g. not reading Melanie XML files or not exporting queries in XML format.
# Information about those modules can be found within this package in the 'libs' directory.
# (For an up-to-date version of the modules, visit 'http://search.cpan.org/~coopercl/XML-Parser/',
#  'http://search.cpan.org/~kmacleod/libxml-perl/' and 'http://search.cpan.org/~mirod/XML-Twig/')

$libxml = 1;

Only if your are providing data in XML format (Melanie XML exports) or if your are using the InSilicoSpectro MS converter to read MS XML documents (mzData and mzXML) that you have to make sure this perl modules are installed in your system (by the way, take care that version 1.13 of the XML-XPath perl module has a bug that prevents the InSilicoSpectro to work correctly)

The block marked:  'Paths & Locations'

# Path of the directory containing your data: flat file, reports, images and (annotated) maps

$data_dir = "/working_dir/data"; # evaluated!

 The path of the data directory containing  your reports, falt file, images,  (annotated) maps and related documents. If you don't want to use the default data directory, then enter another full path.

# Name of your existing *flat file* (data file), including its extension (e.g. my_flat_file.dat).
#  If you are using spreadsheets (e.g. EXCEL reports), then do not define any name here!
#  If you are using (Melanie) XML exports and have no flat file, the tool will generate one if you do not definie any file here!

$db_file = "";

The name of your database flat file based on the SWISS-2DPAGE / Make2D-DB II format (do not include any path).
If you are not using a flat file, but some tabulated text reports (e.g. EXCEL spreadsheets), then do not define any name here. This is also true if you have only Melanie XML exports with no flat file.
Defining a name for your flat file here switches the tool into the flat file mode.

# Name of the file listing the maps names, coordinates and other annotations:
#
$maps_file = "existing.maps";

If you decide to use another name for this file (existing.maps), then type it here.

# A name for your database to be created:
# when the DB name is set to 'default', the name of the new database will be read from the first line of the database flat file (if any)
# Otherwise, define a valid name for your database here!
# This name will be *lower-cased* to suite the postgreSQL pgsl progra
# Note also that only alphanumeric characters and underscores will be retained.

$database_name = 'default';

This will be the name given to the new database. When $database_name is set to 'default', the name of the new database will be read from the first line of the database.dat file (if present). For clarity, it is better to already define the name of your database here. Use only letters, digits and underscores (no spaces allowed) as this will be the postgreSQL database name.

The block marked:  'Behaviour'

# Do you use Melanie / ImageMaster^TM 2D Platinum annotated maps (0 for no / 1 for yes)?

# If you provide Melanie / ImageMaster(TM) 2D Platinum XML/text reports for the spots' data then set this value to 1.
# The tool will try to extract data directly from your Melanie / ImageMaster^TM 2D Platinum annotated maps if this value is set to 1 and no reports are found.

$Melanie = 0;

If your using exported XML reports for your annotated gels with Melanie / ImageMaster^TM 2D Platinum software and you are exporting their data in XML format then change this value to to 1. If you have not defined a value for the falt file $db_file variable, then this will switch you to the Melanie XML mode.

# Do you want to include in your database non identified spots (0 for no / 1 for yes)?
#
$include_not_identified_spots = 0;

When set to 1, you will be able to add not-yet-identified spots in your database by listing them in the spots reports (in the flat file mode you will get a short warning message informing you that they are not referenced in the flat file). Melanie users will have all not-yet-identified spots added to their database if they provide a standard Melanie XML report.

# if you do not extract spots' positions directly from the Melanie / ImageMaster^TM 2D Platinum annotated maps,
# give a default value (in pixels) for the spots X position on the viewer (for SDS maps):
 
$default_SDS_x = 200;

# Prefix given to the spot IDs: #
#
# The spot IDs listed in the spots position reports should be *exactly* the same as those used in your flat file (the text data file).
# If this is not the case, and if your spot IDs used in the flat file include an extra prefix not present in your spots position reports,
# then give the expected prefix string here. Leave blank otherwise.
# (e.g. if a spot ID *444* in the report corresponds to a spot ID *2D-444* in the flat file, then the prefix should be *2D-*)

$spot_ID_prefix = '';

Has only effect in flat file mode.
The tool expcets the spot IDs used in the spots position reports to be exactly the same as those used within the entry annotations in your flat file. In some cases, people tend to add a prefix to their spots ID within their flat file (e.g. 2D-/1D-/2D-MY_BASE, etc..). Although this would confuse the tool, defining this prefix here would help in matching those IDs with those given in the position reports.
Ignore this parameter if your spot IDs are identical in both your reports and your flat file.

# EXPASY SERVER URL to address during installation:
#
#  $expasy =  "http://www.expasy.org"; #

$expasy =  "http://www.expasy.org";

Choose the nearest or the fastest Expasy site for the external connections.

# EXTERNAL DATA BEHAVIOUR #
#
# Include external data (Swiss-Prot, Newt, SWISS-2DPAGE, etc..) by connecting to the Expasy server
# (0 for no / 1 for yes)?
# this has only effect if $libwww is set to 1, otherwise it will be ignored
# * for commercials, check the 'readme/Copyright for external data.txt' file *
 
$include_sp_external_data = 1;

You may deactivate all general external data retrieval by setting this value to 0. You may also activate/deactivate *individually* the various data ressources
from within the 'basic_include.pl' configuration file.

The blocks marked:  'Default Values For Missing Required Lines: xxx'

 
# DEFAULT values for MISSING REQUIRED LINES: RELEASE lines (DT lines) #
# (the tool will use those default values if they are missing from the text files) #

# creation date of the entries (default date):
#
$dt_cr_default = "today's date";

# creation release (default):
#
$dt_cr_num_default = 1;

# last update of entries (default date):
#
$dt_up_default = "today's date"; # evaluated!

# update release (default):
#
$dt_up_num_default = 1; # evaluated!

Those default values will be used whenever a date information
is missing for any protein. In the current version of the tool, they will always be missing except when using a flat file. The format for dates is 'DD-MMM-YYYY' or 'DD-MM-YYYY', e.g. 31-JAN-2006 or 31-01-2006. Sub-releases may be atteched with a period to the release numbers, e.g. 1.1 or 2.15.
 

# DEFAULT values for MISSING REQUIRED LINES: SPECIES lines (OS, OC, OX lines) #
# (the tool will use those default values if they are missing from the text files) #

# OS line: species common name (e.g: Human, Mouse, etc.)
#
$os_default = 'undefined';

# OC line: organism classification / taxonomy (the standard separator ';' is displayed as a simple comma ',' for security resaons)
#
$oc_default = 'parent, child';

# OX: organism/species taxonomy ID (NCBI), you can enter 'NCBI_TaxID=number' or simply type directly the ID value, e.g 1000
#
$ox_default = 'NCBI_TaxID=0';

Those default values will be used whenever any of the organism lines is missing
OS   common_species_name.
OC   organism_classification_parent;...; organism_classification_child.
OX   NCBI_TaxID=xxx;

Whenever a map has been annotated with a Taxonomy ID, proteins attached to this map will adopt its Taxonomy ID. Otherwise, they will use those default values. Only in flat file mode, if an entry contains another occurence of those lines, then those specific lines will be retained for the protein.
 

# DEFAULT values for MISSING REQUIRED LINES: IMAGES line (IM line) #
# (the tool will use those default values if they are missing from the text files) #

# IM line: Image(s) name(s)
#
$im_default = 'undefined';

Has only effect in flat file mode.
If the images line, e.g.
'IM   PLASMA'. 
is omitted from an entry and no '2D   MASTER...' line is given, and if the entry is related to only one map -  then it is read from here.
 

# DEFAULT values for MISSING REQUIRED LINES: BIBLIOGRAPHY REFERENCES lines(RP, RA, RL lines) #
# You are encouraged to fill those reference values according to your personal work #
# Yo may refere to the SWISS-2DPAGE documentation for the precise definition of the syntax to use #
# (the tool will use those default values if they are missing from the text files) #

# RP line: extent of the work:
 
$rp_default = '2D GEL CHARACTERISATION';

# RA line: authors (separated by ','):
 
$ra_default = 'Author 1., Author 2.';

# RL line: refernece location:

$rl_default = 'Submitted (JAN-2006) to the Current database';

The minimal required reference lines can also be omitted from any entry and read from here
RP   extent_of_the_work
RA   Author1 first_name., Author2 first_name;
RL   some_location location_details.

See the Swiss-Prot or the SWISS-2DPAGE manuals on bibliographic references.
 

The block marked:  'Server Directories to Query the Database'

 
# SERVER DIRECTORIES TO QUERY THE DATABASE #
# (The 2d sub-directories will be created by the tool, provided that you have write permissions into the server tree) #

# main path to the server (Apache Document Root):

$web_server_dir = "/var/www";

Type here the path to your Apache Document Root. Usually an Apache server tree is located in '/var/www', it could also be in '/home/httpd' or any path/html_public, etc..

# reference name for the directories containing your data in the server:
# (not the path! this name will be given to different sub-directories in the server directory tree)
# (you can give the name of your database, making sure it does not contain spaces nor special characters)
#
$web_server_ref_name = "2d";

This will be the name given to the 2 sub directories the tool creates in the Apache directories tree. By default, '2d' means that a sub-directory called '2d' will be created in the Apache 'cgi-bin' directory, this sub-directory will receive all the interface CGI scripts.  A second directory will also be created by default in the html directory (../html/2d) and will receive all the maps to be displayed and all related documents and data. At the end of the installation, you should be able to access the query interface by typing directly into your browser 'http://your_domain/2d' or 'http://your_domain/html/2d'. Replace '2d' in the URL by the value you set here for this parameter.

# path for the running CGI server scripts:
#
$web_server_cgi = "/var/www/cgi-bin/2d"; # evaluated!

This is the path where the interface scripts are to be found. The default path that will be proposed is evaluated from your previous settings. If you keep the default value, make sure the sub-directoy 'cgi-bin' is present and correctly declared in the Apache configuration files.

# path of the directory containing the map images sub-directories and related documents in the server:
#
$web_server_html = "/var/www/html/2d"; # evaluated!

This is the directory path for your database maps (images directories), all related documetns and the home page of the interface (index.html). A default value will also be evaluated and proposed. If you keep the default value, make sure the sub-directoy 'html' is present and declared in the Apache configuration files.

# path for a directory to store temporary files in the server:
#
$web_server_html_tmp = "/var/www/html/2d/data/tmp"; # evaluated!

This directory (and its sub-directories) will have open permissions for everybody! just to *make* sure the http/nobody/apache user can write into it. For a better security, you should limit manually those permissions yourself to the approriate HTTP server owner.

# path for the small icons and logos in the server:
#
$web_server_icons = "/var/www/icons"; # evaluated!

Evaluated. Make sure the sub-directoy 'icons' is present and declared in the Apache configuration files. This is where the viewer icons and the server database logo will be copied.

# name of the main script to query the database:
# by default this name is "2d.cgi", but you can change it to any other value (e.g. nice2dpage.pl)
#
$web_server_main_script = "2d.cgi";

This is the name of the main interface to access the database(s). If you activate the apache mod_rewrite option (see later), then you will not need to care about this interface name.

[top]

---

The Server Configuration File: '2d_include.pl'

(You may inspect the two configuration files, example.2d_include.pl and example.include.cfg, given as an example within the "data_test/examples" directory)

The block marked:  'General Behaviour - Title Name of the Server and some other settings'

# URL Redirection (Apache mod_rewrite) #

# Activate the redirection of URLs using the Apache mod_rewrite module (1 for yes, 0 for no)?
# (if activated, make sure after your installation to include the generated redirection rules into your Apache configuration file)
# (see the 'Readme: Interface' page for more details)

$modeRewriteOn    = 0;

'mod_rewrite' is the Apache module that is able to rewrite URL adresses at the server level for redirection. It is based on some transformation rules that let, for example, the server underastand directly something like:

http://domain/my_2dpage/P12345

instead of having to use or type the less intuitive:

http://domain/cgi-bin/my_2dpage/2d.cgi?ac=P12345

If you do not want to use this more convenient way of accessing data with the tool interface, then leave this value null. Otherwise, activate it by '1'. If you do so, then make sure to read the readme file Readme: Interface. In fact, the tool will generate all the necessary instructions and rules needed for the redirection. You will only need to incorporate them within your Apache (version 2.0) server configuration file (see with your system administrator if you do not have the required permissions).

A text containing all the rules to be incorporated will be generated and located in your cgi-bin/2d/inc Apache server directory (or similar) in a file called mod_rewrite.txt. You may inspect this file content before including it into your Apache configuration file httpd.conf (often located in /etc/httpd/conf/httpd.conf). Once done, you will need to restart your Apache server for the effects to take place. Have also a look at make2db_map.txt, located in the same cgi-bin/2d/inc directory. This file contains some useful comments on how to apply the rules.


# Title Name to display on the server:

$name2d           = "My 2D-PAGE";

The displayed title name for the site / server pages.

# Sub-Title:
# You may type any text to be displayed (including HTML tags),
# Note: In addition, the tool will look for a file that is called:
# * subtitle.html *
# that you may provide within your data directory to make it included into the interface home page
# The *subtitle.html* file will be copied into your server_path/html/your_database/data (tmp) directory

$title_comment = "This is the 2D-PAGE server to query 'My 2D-PAGE'"; # evaluated!

A displayed sub-title for the site / server home page. If you want to include a more detailed sub-section under your page title, than it may be a good idea to provide a subtitle.html file in addition.

# Do you wish to add the running database name to the displayed title (1 for yes, 0 for no)?
# If you are running several databases at the same time, this option will be automatically activated

$add_database_name_to_title = 0;

We call the 'running database' the last selected database(s) or project(s) by the user (an interface can query more than one database/project at once). The running database name(s) will then be attached to the site title between brackets. This option is always automatically activated if the interface is addressing several databases/projects at once.

# The name of Person/Institution that maintains the database (optional)
# This name will be displayed on the bottom of the web pages as a contact address

$maintainer           = '';

At the bottom of the web interface, you may define a short name to be displayed for the institution or the person maintaining the database/server.
If an e-mail address is defined in the next field, this e-mail will be attached to this maintainer name.

# Database Author/contact e-mail address (optional): !! Do not omit the *backslah* before the '@' sign !!

$email                 = 'your.name\@somewhere.org';

This is the e-mail address for any contact. Do not omit the backslash '\' before the @ sign!

# Background colour of the pages (use standard HTML defined colours):

$bkgrd            = "yellow";

The colour used should be identifiable by HTML standards. English common color names are well understood. Hexadecimal values are also accepted (e.g "fff00").

# Main font color (use standard HTML defined colours):

$basic_font_color = "black";

Make sure the font colour is visible on the background.

# Menu graphic mode: type '1' or '2' to choose one of the 2 graphic menus, type '0' for a simple textual menu
 
$menu_graphic_mode = 1;

# If buttons menu is selected, choose a color for the buttons:
 
$menu_button_color = "#f0e68c";

# If buttons menu is selected, choose a color for the selected active button:
 
$menu_selected_button_color = "#a52a2a";

# If buttons menu is selected, either use the default font color for the button text (0),
# or the reverse color between active and non active buttons (1):

$menu_reverse_font_color    = 1;

You have the choice between a graphic menu, buttons or simple text to select your actions. With the buttons' menu (mode = 2), you can choose both the active and non active buttons color. The last parameter, when set to 1, means to use those colors for both the background and the font colors on the buttons.

# The viewer displays spot information inside a small box. Give a size (in pixel) for the width of the box:
 
$ballon_size      = "280";

# Any private data, marked 'hidden', is not displayed to public users, except if this value is set to (1):

$show_hidden_entries = 0;

You have the control to set some data types visible or not to public users. When you set the $show_hidden_entries value to 1 you make all data (hidden or not) visible to public users.

# A user may access private data using the following password
# No access to private data will be allowed to users if no password is defined here

$private_data_password = "";

You should define a password here that will be used by privileged users to access hidden data. If no password is given, nobody except the administrator himself, will be able to access those data.

# Include in your viewer non identified spots (0 / 1):

$include_not_identified_spots = 1;

This makes the map viewer display graphically or not the non identified spots.

# Show the external data gathered when displaying an entry / include this data within the search engine (0 / 1)

$show_external_data   = 1;

By setting this value to 1, the gathered external data will be displayed within the entries. It will also be possible to address search queries over the content of the external data. Type 0 to set this off.

The block marked:  'Expasy Server URL'

#  $expasy =  "http://www.expasy.org"; #

$expasy = "http://www.expasy.org";

Those are some available Expasy mirror sites. If you are aware of another site near your location that is not in this list, you can simply use it instead of those propositions.

The block marked:  'Paths of Data in the Server'

# main path to the server (Apache Document Root):

$server_path              = "/var/www";

Type here the path to your Apache Document Root. Usually an Apache server tree is located in '/var/www', it could also be in '/home/httpd' or any path/html_public, etc..

* If you are configuring a new installation, and have already set this value in the 'include.cfg' main configuration file (the $web_server_dir parameter), then this value you have already set will be proposed here.

# reference name for the directories containing your data in the server:
# (this name is the one you would have already provided in the main configuration file)
 
$web_server_ref_name      = "2d";

This is the name given to the sub-directories that contain the interface scripts, the data and the maps in the Apache directories tree. By default, '2d' means that a sub-directory called '2d' has been created in the Apche 'cgi-bin' directory, this sub-directory contains all the interface CGI scripts.  A second directory should have been also created in the html directory (../html/2d) to contain the maps and all related documents. You should be able to access the query interface by typing directly into your browser 'http://your_local_domain/2d' or 'http://your_local_domain/html/2d'. Replace '2d' in the URL by the value you set here for this parameter. This address is formaly a redirection to the 'http://your_local_domain/cgi-bin/2d/2d.cgi' interface script.

* Note that the proposed value should be the one you would have already defined in the 'include.cfg' main configuration file (for the $web_server_ref_main parameter) if you were running a new configuration process.

# path of the parent html subdirectoy in the server:

$html_path                = "/var/www/html"; # evaluated!

This is the path for the 'html' Apache directory where your '2d' sub-directory (or whatever name you may have defined for the $web_server_ref_name parameter) should be created. The later should contain the database maps (images directories), the documents and the home page of the interface (index.html). A default value will also be evaluated and proposed. If you keep the default value, make sure the sub-directoy 'html' is present and declared in the Apache configuration files.

# path for a directory to store temporary files in the server:
 
$tmp_path                 = "/var/www/html/2d/data/tmp"; # evaluated!

The block marked:  'Server Absolute/Relative URLs'
 

# relative URL for the main 2D html page:
# (on some systems you may need to precede this value by '/html' or '/html_public'!)

$url_www2d                = "/2d"; # evaluated!

This is the absolute URL to access your '2d' (or whatever name you may have defined for the $web_server_ref_name parameter) documents. Do not forget to precede it by a slash '/'. If your Apache server is configured so that you have to include the 'html' directory name in the URL to access documents located within this directory, then redefine this parameter to reflect this by: $url_www2d  = "/html/2d";

# relative URL for the running CGI server scripts:
 
$cgi_2ddb                 = "/cgi-bin/2d"; # evaluated!

This is usually where the cgi-bin scripts should be located. Change this value to reflect your settings. Do not forget to precede it by a slash '/'.  

# name of the main script to query the database:
 
$main_script_file         = "2d.cgi";

This is the name of the main interface to access the database(s).

* If you are configuring a new installation, and have already set this value in the 'include.cfg' main configuration file (the $web_server-main_script parameter), then this value you have already set will be proposed here.

# relative URL for the small icons and logos on the server:
 
$icons                    = "/icons";

Although this value is not evaluated, it should be the same as the $web_server_icons parameter defined for the main configuration file. Do not forget to precede it by a slash '/'.

# name of the HTML top page file to include at the top of the server pages (leave blank if no file is needed):
# the file is assumed to be in server_path/html/your_database/data directory, otherwise, give a complete path to look in another direcroty
 
$db_server_include_file   = "";

You can provide a top page file (written in HTML) to be included at the top of the server pages. By default, the file is assumed to be in the 'server_path/html/your_database_interface/data' directory created by the tool, except if you define here a specific path (UNIX path) before the file name.

# shift the initial display position of the maps within the viewer by: (in pixels, change this value if you have provided a top page file)
 
$increase_map_display_shift_down = 0;

You may prefer to shift the maps' display in the graphic viewer by a certain amount of pixels. Give this amount here.

# name of the logo image you have provided:
 
$db_server_logo_name      = "make2DBLogo.gif";

If you have provided a logo image by putting it with your initial data, it will be copied to the Apache /icons directory. Type here the file name of your logo image.

# display the logo image in the viewer (1 for yes, 0 for no):
 
$display_db_server_logo_in_viewer  = 1;

If your logo image exists, it will be automatically displayed within the search engine (the main serach script). If you want it also to be displayed in the graphical viewer, then keep this value = 1.

# rescale your logo image to a fixed width (in pixels), type 0 to skip redimension:

$db_server_logo_width       = 0;

Logo image will be rescaled to this given width (in pixel). Type 0 to keep its original width

# Home link: text to display for the link
#
$home_displayed_text      = "Home";

A link to your site home page, your institution, or any other URL. This link is added to the buttom of your pages (between [ ]). Write here the text to display for this link.

# Home link: URL ('/' means the Document Root)
#
$home_url                 = "/";

Type here the URL for the previous link ('/' will link to your server Document Root).

The block marked:  'Databases to Include'
 

# Several local or remote databases can be included within the same interface.
# You will be asked to define the connection parameters for each of them separately.
# To decide which databases are to be included in the query interface,
# type between brackets the databases IDs (only numbers) you would like to give them, separated by commas: e.g. (1,2,3).
# You will be asked later to define the specific parameters for each of these databases.
#
# For a single database installation, keep the default value (1).
 
@DATABASES_Included = (1);

Here you declare the local databases/projects IDs that the interface has to manage. By default, you will need to give at least one number (1 is the default) as a database identifier. You will be asked later to define the specific connection parameters for each of the databases that you may have defined here. For example, if you define:

"@DATABASES_Included = (1,2,8);"

you will be asked (below, in section 'Database Specific Parameters') to define specific parameters for three different databases/projects, with IDs 1, 2 and 8.

The block marked:  'Default Database Parameters'
 

The following default database parameters are invoked when specific database parameters are missing. For example, If you have declared 3 databases, like in the example of the previous section, and that you select database #2 for your query, the tool will try to look for the specific parameters of the database with the ID number 2. If it fails to evaluate one of those specific parameters, or if a specific parameter has a void value or is missing, then it will read its value from the default values you set here.
 

# Each added database will have its own specific parameters (they will be set later) #
# Whenever those parameters are missing, the following default ones will be taken into consideration #
 

# Address of the running postgreSQL server.
# If the postgreSQL server is running on the same machine where the Apache server is running, then use 'localhost'

$default_host     = "localhost";

# default port (usually 5432):
 
$default_port     = 5432;

# default options (leave blank): 

$default_options  = "";

# default tty (leave blank):
 
$default_tty      = "";

# Name of the database to be used by default:
# (during installation, you may leave 'last_created_database' to let the tool automatically insert the name of the new database you are about to create)
 
$default_dbname   = "last_created_database";

When several databases/projects are included. The one you mention here is the one selected by default. For a new installation, the value 'last_created_database' informs the tool to select by default the last converted or last created database (not necessarely the postgreSQL database name). This name should contain only alphanumerical characters (including underscores).

# PostgreSQL select user (user with no write permissions to query the database):
 
$default_select_user = "select2d"; 

This is the postgres 'select2d' user, created by the tool, who has no permissions to write to the database (only select permissions on the public schema are granted to him)

# PostgreSQL select user password, by default, the password is set up identical to the select user name:
 
$default_select_user_password = "select2d";

If you have previously set up *another* password for the 'select2d' user, then re-type it here.

# extract the image absolute URL from the database [type 1]) / or read it from the specific DB parameters [type 0] (0 or 1)?
# (note 1: if you type 0 and no specific DB parameters are found, then default values - see after - will be used)
# (note 2: if you have built other databases for the same interface without any server configuration file, then type also 0)

$extract_image_URL_from_DB = 1;

The interface has to know where to look for the images of the maps. During the conversion / creation process of the database the absolute (not the full) URL is inserted inside the database tables (providing a server configuration file has been used). By typing 1, you ask the tool to extract the URL from within the database itself. Otherwise, by typing 0, the tool will read the images URLs from this configuration file (first by looking on each database specific parameters, then by using the default values that follow in this block). This parameter may be useful to set up if you decide to move your database content to another location in the future.

# absolute URL for the map images:
 
$default_image_url        = "/2d/data/gifs"; # evaluated! # Do not change!

Do not change, except if you have changed your $url_www2d parameter.

# graphical map image type (gif, jpg, png, tif, etc..)?
 
$default_image_type       = "gif";

Type here (in lower cases) the extension associated to the graphical type of your images. If you set it to 'gif' and have for example a map called PLASMA, then the tool will look for a graphic image named PLASMA.gif.

# absolute URL for the small map images:
 
$default_small_image_url  = "/2d/data/small-gifs"; # evaluated! # Do not change!

Do not change, except if you have changed your $url_www2d parameter.

# graphical small map image type (gif, jpg, png, tif, etc..)?
 
$default_small_image_type = "gif";

Type here (in lower cases) the extension associated to the graphical type of your small images.

# an URL link to describe sample origin and preparation (leave blank if you do not have any)
 
$default_sample_origin_URL = "";

Type either a full or an absolute URL to link to your own external pages describing origin and samples preparation. This is a very general annotation for the whole server. More specific description and links can be given within the maps' list file (the existing.maps file).

# default copyright message (to be displayed within each entry):
# !! do not press <return> before finishing your message!!
# write your message in just one line, or use the special escaped character '\n' - backslah & n - to impose new lines.
# You can use HTML tags (e.g. <BR>), as well as single-quotes (not double quotes).
 
$default_copyright_text   = "This is just a default copyright text!!\nWith a second line!!";

If defined, this copyright message will be displayed inside your entries. You can use any formatting HTML tags (like <BR>, <B>..</B>, etc..). Do not press <return> for a new line (you can write the escaped character '\n'.

The block marked:  'Database Specific Parameters'
 

The configuration process will generate as many blocks, like the one that follows, as you would have indicated to it by setting the @DATABASES_Included parameter. Supposing your first defined database ID is 1, you will have to set specific parameters for a database with the index '1', and so on..

$database[1] =
{

# the 'database_name' is the name to displaye on the server, not the postgreSQL database name
database_name => "My 2D-PAGE Database"

Note that 'database_name' is the name to be displayed on the server (the 'dbname' parameter below is the one to hold the real postgreSQL database name!).
The 'database_name' parameter may contain alphanumerical characters and spaces (including underscores) like you want your database name to be displayed on the server pages.

main_index => "SWISS-PROT",
# do not change (specific to SWISS-2DPAGE)
swiss_2d_page => 0,
# an URL link to describe sample origin and preparation (leave blank if you do not have any)
sample_origin_URL => "",

This is a very general annotation to apply on this specific database. More specific description and links can be given within the maps' list file (the existing.maps file).

# connection parameters  ('dbname' is the postgreSQL database name)
dbname => "your_database_name",

Now, this is the real postgreSQL database name.

host => "localhost",
port => "5432",
options => "",
tty => "",
select_user => "select2d",
select_user_password => "select2d",

# map viewer: image type & shifting
image_url => "/2d/data/gifs/your_database_name",
image_type => "gif",
small_image_url => "/2d/data/small-gifs/your_database_name",
small_image_type => "gif",
# shift the map's x position to the left (pixels): default 0
map_shift_left => 0,
# shift the map's y position down (pixels): default 0
map_shift_down => 0,

# apply a correction for the given x-horizontal positions on *all* maps: default 1.0, overridden by map specific values <> 1.0 within the relational DB (set up in existings.maps)
map_x_ratio => 1.0,
apply a correction for the given y-vertical positions on *all* maps: default 1.0, overridden by map specific values <> 1.0 within the relational DB (set up in existings.maps)
map_y_ratio => 1.0,
no image rescaling (keep only the 100% scale on the graphical viewer)
no_rescale => 0,

# database/project specific subtitle file: in case several databases are accessed from a single interface (data repository)
subtitle => "subtitle_project.01.html",

# name of institution/perosn owning the data (optional - define only if differnet from the database maintainer).
data_owner => "Dr. Somebody, My institute, My Country",
# Data owner Web address: define an e-mail or a Web address !! Do not omit the *backslah* before any '@' sign !!.
data_owner_address => "somebody\@somewhere.com",

# COPYRIGHT message:
# To deactivate copyright message on full entry view (or to use the default text), leave copyright_text empty,
# otherwise, type your text between the quotes.
copyright_text => "",

# Data owner: name of institution/perosn owning the data (optional - define only if differnet from the database maintainer) data_owner => "Dr. Zhenyu Cheng, University of Waterloo, Canada", # Data owner Web address: define an e-mail or a Web address !! Do not omit the *backslah* before any '@' sign !! # Displayed on the server only if 'data_owner' has been defined (optional) data_owner_address => "czhenyu\@uwaterloo.ca",

};

Those specific parameters have exactly the same meaning as their counterpart defined in the 'Default Database Parameters' section, except that they do only apply to the specified database. Two new parameters do not have nevertheless a default value read from your previous settings: map_shift_left and map_shif_down. The spots positions can be shifted respectively to the right and to the buttom (if you enter positive values) or to the left and the top (if you enter negative values). This shifting acts at the database level and not at the maps level. To make it specific for a map, you should modify those values directly inside the database itself (contact us for more info). Defining those values may be useful, for example, if your spots positions are based on an image that you have modified afterwards to include some extra borders (like a pI and a Mw axis, etc..).

[top]

The Maps' List File: 'existing.maps'

The Basic Configuration File: 'basic_include.pl'