This guide will assist you in configuring an Oracle Spatial database and ESM using the supplied tutorial dataset. No responsibilty is assumed for the accuracy of the data herein.
Upon installing Xmarc'c Enterprise Spatial Product Suite into your installation directory (referred to as <XMARC_ROOT> from now on), note the 2 highlighted sub-directories which contain many of the scripts that will be used throughout the discussion:
The <XMARC_ROOT>/es/oracle directory contains data and SQL script files that will be used to setup example schemas and datasets. The <XMARC_ROOT>/es directory also contains various scripts that will allow you to administer an ESM data site (run_admin); register the ESM site as a web service (run_esm_svc); register the map data as web service (run_tutorial_db_svc); and to test all the "back-end" services by running a Fire client (run_viewer ).
You will need to edit the run_esm_svc and run_tutorial_db_svc scripts in order to successfully execute them. This typically involves setting the location of the installation root directory and the web server hostname.
Additionally, you may also need to modify files in the <XMARC_ROOT>/deploy/app directory:
You will need one of each of the following products installed in addition to Fire in order to get ESM working.
Please refer to the relevent web server and/or servlet engine documentation for installation intructions. It will be assumed that these products have been installed and configured.
Do not proceed until you can access a web page from the web server and get a valid response from a request such as http://<web_server>/xmarc/index.html
It is assumed you have access to an Oracle 8i/9i Spatial Database.
You will create and load the ESM schema database using SQL scripts found in the <XMARC_ROOT>/es/oracle directory. These will create all the necessary tables required by ESM. But first, you need to create an Oracle account for the ESM user and grant the appropriate rights. We will use username = ESM2 & Password = ESM2.
NB: You will need to be logged in as a DBA such as SYSTEM to do this. You may also need some additional system privileges on Windows NT which are not automatically granted to the Administrator user. These are 'Act as part of the operating system', 'replace a process level token' and 'Log on as a service'. You can set these from the 'advanced user rights' section of the NT user manager interface.
Start an Oracle SQLPlus session and enter the following. Alternatively you can use Oracle's Enterprise Manager Console tool. Be sure to check that the tablespace names and userid's etc are correct for your system (Note: alternatively you may run the supplied SQL script cr_esm2_user.sql ).
CREATE USER esm2 IDENTIFIED BY esm2
DEFAULT TABLESPACE USERS
TEMPORARY TABLESPACE TEMP
PROFILE DEFAULT
ACCOUNT UNLOCK;
GRANT CONNECT TO esm2;
GRANT DBA TO esm2;
ALTER USER esm2 DEFAULT ROLE ALL;
QUIT;
When this is done, go ahead and create the schema. You will find a file called cr_esm.sql. You can start SQLPlus, login as the newly created ESM2 user and execute this script (don't forget to include the full path) OR you can go to a DOS Command prompt or UNIX shell and run the following command from the shell prompt:
sqlplus esm2/esm2 @CR_ESM.SQL
NB:If you accidentally load the ESM Schema into the wrong user ID (a very common error even for experienced ESM users!) there is a dr_esm.sql (drop ESM) script in the es/oracle directory which will remove all the ESM tables so you can start again with the install.
Now we need to load the user data. We create another new user who will own this data by logging in once again as a DBA user. Remember the ESM user is for managing the ESM schema only, not the spatial tables (Note: alternatively you may run the supplied SQL script cr_tutorial_user.sql )..
CREATE USER tutorial IDENTIFIED BY tutorial
DEFAULT TABLESPACE USERS
TEMPORARY TABLESPACE TEMP
PROFILE DEFAULT
ACCOUNT UNLOCK;
GRANT IMP_FULL_DATABASE TO tutorial;
GRANT CONNECT TO tutorial;
GRANT UNLIMITED TABLESPACE TO tutorial;
ALTER USER tutorial DEFAULT ROLE ALL;
QUIT;
Now you can load the Oracle dump file EST_ORACLE817.DMP in the es/oracle directory into the database using the Oracle Import tool. Go to a DOS Command prompt and cd to the es/oracle directory and then run these commands.
C:> imp tutorial/tutorial Import file: EXPDAT.DMP > est_oracle817.dmp Enter insert buffer size (minimum is 4096) 30720> Export file created by EXPORT:V08.00.04 via conventional path List contents of import file only (yes/no): no > Ignore create error due to object existence (yes/no): no > Import grants (yes/no): yes > Import table data (yes/no): yes > Import entire export file (yes/no): no > yes
If you run into problems loading the data and would like to start over, the quickest way to get back to where you were is to use the drop user command which removes the user and all objects owned by that user:
DROP USER esm2 CASCADE
Start the ES Admin tool by executing the run_admin script in the <XMARC_ROOT>/es directory.
If the ES Admin application fails to start you may want to look in the <XMARC_ROOT>/fire/config/fire.ini file and see if the correct database interface is set correctly.
Please refer to the ESM Admin Tutorial for a full discussion on ES Admin.
Start the ES Viewer application by executing the run_viewer script in the <XMARC_ROOT>/es directory. Check the "Client Server" box, make sure the connection details are correct and then select Accept .
This tool will allow you to view the data that you have just configured using ES Admin. You may need to edit the <XMARC_ROOT>/deploy/app/es_viewer.fsc file in order to set the dbhost variable to the setting used for Oracle's TNS listener name.
Once the ESM Admin tool has been used to configure the ESM metadata, you can make its metadata accessible for client applications to access via the web. This is accomplisded by executing the run_esm_svc script in the <XMARC_ROOT>/es directory.
You may need to edit this file in order to set the URL that Fire will use to register itself as a service with the Service Broker. Make sure the web server you are connecting to is running the xmarc.war servlet package and that the password you use to register with is what the Broker servlet expects (the default password is set to "X").
In addition, you may need to edit the <XMARC_ROOT>/deploy/app/es_mgr.fsc (or es_mgr.xml as the case may be) file. Typically this involves setting the dbhost variable to the setting used for Oracle's TNS listener name.
Finally, copy (or otherwise deploy) the <XMARC_ROOT>/deploy/resources directory to your web server. The URL you use to access this resource area is dictated by what you entered in the "URL path to Web Resources" field during the ES Admin Tool Site setup page.
To publish the TUTORIAL data as a web service you will need to add a "New Service" via the Service Manager Console which is part of the xmarc.war servlet deployment. The figure below is an example of what information is needed to fill out the New Service form:
From the diagram, we can see that a maximum of 5 fx9i services (in this case - running on a Solaris platform) are going to be registered to the Broker servlet running on a host a called websrv1. The service name will be called TUTORIAL.The Oracle database connection details are give in the field, "Service Start Parameters". In this example we are making an Oracle network connection from the Solaris machine (called server1) to an Oracle database running on a host called dbsvr1.
Simply click the submit button after filling out the fields to start the service.
Once an ESM service and a TUTORIAL service have been registered to the Broker servlet, you can then execute the ES Viewer application again but this time accessing them via the web.
Start the ES Viewer application by executing the run_viewer script in the <XMARC_ROOT>/es directory. Check the "Web Service" box, make sure the URL is correct and then select Accept.
This tool will allow you to view the data that you have just configured using ES Admin. You may need to edit the <XMARC_ROOT>/deploy/app/es_viewer.fsc file in order to set the ~es_viewer.ESM_SVC_URL variable to the correct URL value.