TDM ICIS Application and Database Installation

From ICISWiki

Jump to: navigation, search

Contents

ICIS APPLICATION AND DATABASE INSTALLATION

C.G. McLaren, R.. Casumpang, W. Eusebio, C. aan den Boom, J. Heber, S.Micallef and A.Portugal

INTRODUCTION

Before ICIS applications can be used new or existing databases need to be set up and software installed. A standard directory structure, as shown below, has been adopted to facilitate the process, and existing databases and software are available from two sources, the ICIS CD or the ICIS Ftp site.

The ICIS Directory Structure

A standard directory structure has been adopted for ICIS implementations in order to facilitate installation and communication. The structure is shown in Fig 4.1.1. Databases are stored in the DATABASE subdirectory which has sub-branches denoted as <crop n> for each implementation such as IRIS for rice and IWIS for wheat. More than one local database can be stored in the LOCAL subdirectory for each implementation. Local databases may also be stored on different computers in a network environment. The TEMPLATE subdirectory contains empty databases which can be copied and renamed to form new implementations or installations. Application development is carried out in appropriate subdirectories of the DEVELOP tree and working executable files are transferred to the EXES subdirectory so that users have access to all working applications. Some documentation and reports stored as word documents in the DOCUMENT subdirectory,but the main location for documentation is the ICIS Wiki. Graphic posters and slide shows are in the PRESENT subdirectory. Data manipulation and download projects require special parse programs and these are developed, executed and stored in various branches of the PROJECTS directory. Figure 4.1.1. The ICIS Directory Structure 

				\ICIS
				\ICIS\DATABASE
				\ICIS\DATABASE\<crop n>\
				\ICIS\DATABASE\<crop n>\CENTRAL
				\ICIS\DATABASE\<crop n>\LOCAL

				\ICIS\DATABASE\TEMPLATE\ACCESS
				\ICIS\DATABASE\TEMPLATE\FOX
				\ICIS\DATABASE\TEMPLATE\<dbs n>

				\ICIS\DEVELOP
				\ICIS\DEVELOP\GMSDLL
				\ICIS\DEVELOP\LAUNCHER
				\ICIS\DEVELOP\IDEND
				\ICIS\DEVELOP\SETGEN
				\ICIS\DEVELOP\FLDBK
				\ICIS\DEVELOP\<application n>

				\ICIS\DOCUMENT
				\ICIS\EXES

				\ICIS\PROJECTS
				\ICIS\PROJECT\<project n>

The ICIS CD

Periodic releases of ICIS databases and software are provided on CD. This contains a set up program which allows users to install the software and set up databases for new or existing implementations.

The ICIS Ftp facility

A second way to obtain ICIS software and existing databases is from the ICIS Ftp facility at CGNET. The following points detail the steps for using this facility:

  • Run any FTP program and connect to the ICIS FTP site by specifying the URL (FTP address) as ftp.cgiar.org. If asked for a username and password, enter anonymous as username and your complete e-mail address as password.
  • Change the current logged-on directory to /ICIS and then to the desired version eg /Version5.4_Release. Or with a web browser you can go directly to ftp://ftp.cgiar.org/icis/Ver5.4_Release. This contains self-extracting EXE files for each central database. For example IBIS.exe for barley, and one for the ICIS software, ICISPROG.EXE.
  • Select the files for the central database(s) you require and the ICISPROG.EXE file. Download them to any temporary directory on the target computer, e.g., C:\WINDOWS\TEMP.
  • After downloading is complete, extract the contents of the required central database(s) by running the downloaded database EXE programs. These programs ask the user to specify the path to the directory where ICIS is to be installed. C:\ICIS5 is proposed, but another drive may be specified.
  • Run the ICISPROG.EXE program to unpack the ICIS software and run the ICIS Setup program. ICISPROG will ask for the ICIS directory. This must be the same directory specified in the previous step.
  • When installation is complete, all downloaded files can be deleted.
  • The installation process sets up the directory tree. This contains the central and local databases specified during installation and template databases in branches of the DATABASE subdirectory (Figure 4.1.1). The set up program will have established ODBC data source names for local and central databases and ICIS INI files for each installation specified. A link to the ICIS launcher will have been placed on the desktop and this can be executed immediately.
  • The ICIS Documentation is now on the ICIS Wiki at http://cropwiki.irri.org/icis/.

Installation of ICIS databases

Once the software is available, there are five steps in installing ICIS databases: installing a central implementation, and installing local installations, establishing ODBC data source names, creating an INI file and setting up the Launcher. If the central system is already installed there is no need to follow the first step in order to add an installation. Step by step procedures for all these stages are given below. A set up program has been produced on the ICIS CD and on the ICIS Ftp site which automates these steps so that new users can conveniently implement or connect to an ICIS database.

Setup a New Implementation (Central Database)

A new ICIS implementation should be set up by the administrator for the new crop as follows:

  • Establish a new \ICIS\DATABASE\<crop>\CENTRAL branch and copy the appropriate central template database from the TEMPLATE branch to this subdirectory. (Replace <crop> by a suitable mnemonic for the crop databases). Rename the new central database to better reflect the crop and role of the database.

If a database program other than ACCESS is required then a new template must be made and it would be useful to store it in a new subdirectory of the TEMPLATE branch. New templates can sometimes be made by converting one of the existing templates to the desired database program.

  • The USERS table contains three records, the first (user 1) should be the central database administrator with access privilege 150. The second should be a GUEST user with access privilege 20, NAME=GUEST and UPSWD=GUEST. The third should be the first local database administrator with access privilege 100. The two specific users may be the same person, but require different user IDs and User names. Change the user names and passwords for users 1 and 3 as desired and set ADATE to the current date for all users.

The central administrator and the guest user should have INSTALID=0, allowing them to access any installation to which they have physical access (read only for the GUEST). The local database administrator should have INSTALID=2 since this is the first local database (central database is installation 1).

  • The INSTLN table contains two records: one for installation 1, the central database, and one for installation 2, the first local database. Change UDATE to the current date and enter descriptions as desired in IDESC. The description for the central database should contain an initial string of four characters, followed by a version number or date for the central database. These can be followed by a text description. For example the current description of the IRIS central database is 'IRIS Central Database v 5.4.2007.039". The first four letters are used to indicate the crop in the construction of unique germplasm identifiers (to indicate crop), and the version is useful for managing udates.
  • The METHODS, LOCATION and UDFLDS tables contain data items which should be standard across implementations

Once this has been done, the local database needs to be set up.

Setup an Installation (Local Database)

A new local database can be set up by anyone wanting access to an ICIS implementation.

  • Copy a blank local template database from the appropriate \ICIS\DATABASE\TEMPLATE subdirectory to the directory where the new installation is to be installed (\ICIS\DATABASE\<crop>\LOCAL). The local database may be on the same or on a different computer to the central database. Rename each local database installed to better reflect the crop and purpose.
  • The local database, like the central, may have GMS and DMS in the same database, or in separate database files. If separate, the access control is managed in the GMS database.
  • A new local database can be registered or anonymous. If the user intends to submit data for publication in the central database it should be registered with the central administrator. This however, can be done at the time the first update is submitted. If the local database is being renewed after update, it should already have been registered and all that is necessary is to copy the appropriate INSTLN record from the central database to the new, local INSTLN table.
  • To install a new anonymous database you need to add a record in the local USERS table with USERID=-1, INSTALID=-1, USTATUS=1, UACCESS=100, UTYPE=422, UNAME any chosen user name not already in the central database, UPWD any unique user password, PERSONID=0, ADATE today's date as YYYYMMDD, and CDATE=0. Next you must add a record to the local INSTLN table with INSTALID=-1, ADMIN=-1, IDESC any suitable description of the local database, and all other fields zero. Further users can be added to the USERS table with USERIDs -2, -3 etc. They should have INSTALID=-1, USTATUS=1, UACCESS <100, UTYPE=423 and their own usernames and passwords.
  • If the new local database is to be registered immediately then the ICIS administrator needs to add new users to the USERS table of the central database. One user must be the local database administrator . The new local database must also be defined by adding a new record to the central INSTLN table . Copy this record exactly to the INSTLN table in the new local database. (If this is the first installation, and if the central database has been established then the administrator should be user 3 and the installation record should be installation 2 already in the central INSTLN table).

Establish ODBC Data Source Names

ICIS requires Microsoft ODBC version 3.5 or higher together with the appropriate ODBC drivers for the DBMS being used. If these are not installed, they can be installed from their original sources or, for certain DBMS, from the set up program (4.3). ODBC data source names (DSNs) must be set up for central and local databases. A DSN may already exist for the central database in which case a new one need not be added. DSNs for local databases must be set up permanently on each machine by the following method or by the Install program. DSNs for the central databases may be set up in the sam way or they may be set up at run time by the Application Launcher which can read inialization parameters from the [ODBC SOURCES] section of the INI file. This is particularly useful for connecting to central databases over a network. The steps for setting a DSN are as follows:

  • To set up a data source, run the application ODBCAD32.EXE or call it from the control panel in Windows, a dialog box showing established data sources will appear. Int the System DSN Tab, click the ADD button and a second dialog will appear with a list of available ODBC drivers. Highlight the driver which is appropriate for the database being connected and press the OK button. (If there is no driver of the required type, it must be installed through Windows setup before the DSN can be set.)
  • A new dialog box will appear. Fill in the data source name field with a name for the GMS database. For example "IRIS-Central" is the data source name for the central rice database. Enter a description for the database in the description field. The next step is to choose the database with the select button. For Microsoft Access, only one file needs to be selected. For some databases like dBase and Paradox the subdirectory containing the tables and indexes must be specified. Still others like ORACLE and SQL Server require the server and the database instance to be specified. After selecting the database and pressing the OK button, the data source name will be placed in the list of Data Sources by the ODBC administrator program.

ICIS INI Files

When no INI file or path is specified, ICIS applications look for an initialization file, ICIS.INI, in the %TEMP% directory. This contains information on the data sources and defaults to be used. When more than one ICIS installation is set up on the same computer, one working session may use databases different from other working sessions. To differentiate one installation from another and to facilitate transfer between them, separate INI files must be maintained. These may be stored in individual directories, or collected together in a single directory, usually the EXES directory. The required INI file then only needs to be copied to ICIS.INI in the windows temp directory to set up access to a different installation. The SETUP program creates an INI file for new installations and the LAUNCHER application facilitates this copying and can also be used to create INI files. However, they are simply text files with a specific format as in Figure 4.2.1. They must contain the sections "Central GMS" and "Local GMS" and may contain other sections specific to different applications: 

    Figure 4.2.1. Example INI file.
    
    [ICIS]
    INI_DIRECTORY=E:\ICIS5\Exes\ADMIN.INI
    WALLPAPER=E:\ICIS5\Exes\IMAGES\DefWallpaper.BMP
    LOGO=E:\ICIS5\Exes\IMAGES\RICE.BMP
    
    [CONFIGURATION]
    DEBUG=NO
    
    [DLL SETTINGS]
    #Determines the level of access or security to the ICIS applications and databases (Default is 1)
    SECURITY=1

    [Central GMS]
    DSN=IRIS-Central-GMS
 
    [Local GMS]
    DSN=IRIS-Local
    UID=Admin
    PWD=Equity
 
    [Central DMS]
    DSN=IRIS-Central-DMS
 
    [Local DMS]
    DSN=IRIS-Local

In any INI file, leading and/or trailing spaces are considered as part of a key name or value. For example, DSN=IRIS-Central and DSN =IRIS-Central are different keys (the first key only has three characters, while the second key has four). Therefore, it is important that no spaces appear on either side of the '=', unless the space is part of the value. The [ICIS] section has a key pointing to the location of the current INI file (so that it can be edited in the Launcher) and two keys pointing to some customizable image files which can be used to give a graphic indication of which installation is being addressed. The [CONFIGURATION] section has a key to turn off a debugging log from the DLL. (This file can be very large if it is left on).

The Central and Local database sections each contain a DSN key which has value equal to the ODBC data source name as described in the last section. These sections must have UID (username) and PWD (password) keys if usernames and passwords are required to connect to the particular DBMS being used. The example in Fig 4.2.1 assumes ACCESS databases which do not require authentication so most sections do not have the UID and PWD keys. The Oracle database management system, however, requires users to connect with a username and password. Note that the values of UID and PWD are distinct from ICIS USERIDs and passwords used to control access to ICIS functions, however, if the DBMS does not require them, or if the ICIS values are chosen to match the RDBMS values then some applications can log on to both RDBMS and ICIS without requesting the user for these details. This is why the [Local GMS] section in Fig 4.2.1 has a UID and PWD. These match the USER record for the local installation and allow applications to connect.

INI files will also contain further sections appropriate to specific applications.

When setting up ICIS on several computers where the central databases will be accessed through a network server, the administrator can ease the burden of setting up DSNs for the central databases on each computer. by adding the [ODBC SOURCES] section at the beginning of the .INI file as follows: Usage: [ODBC SOURCES] 

    ODBC_GMS_CEN=[network path]\[crop]-GMS.MDB
    ODBC_DMS_CEN=[network path]\[crop]-DMS.MDB

The Launcher program reads the database paths from the [ODBC SOURCES] section and assigns them user DSNs with names found in the [Central GMS] and [Central DMS] sections.

Install applications and Set up the ICIS Launcher

Installing ICIS and setting up the ICIS Launcher is automatically done by running the ICIS set-up program, but can also be manually set up as follows:

  • If the ICIS applications do not exist on the local computer, copy them from the \ICIS\EXES directory of the ICIS CD to \ICIS\EXES. Create a shortcut to LAUNCHER.EXE.
  • Edit LAUNCHER.TXT and make sure the path statements on each line are valid for the current set up.
  • Run LAUNCHER.EXE. If the window 'Select or Create an ICIS.INI File' does not appear, click the <Change INI> button. Select the desired directory to store the INI file. Enter the name for the INI file. Click <OK> or press <Enter>.

A form will appear requiring DSNs, UIDs, and PWDs for local and central databases. [Note: The UIDs and PWDs are for the database programs, if they require users to log on. These are NOT the same as the ICIS username and password (see 5.3.3 for a convenient shortcut).] Click <OK> or press <Enter> when the form is complete. The ICIS menu is now ready to launch applications.

Retrieved from "http://localhost../../../../articles/t/d/m/TDM_ICIS_Application_and_Database_Installation_0520.html"
Personal tools