Setting up ODBC Connectivity to MS SQL Server on UNIX (XI 3.1)

This tutorial walks an Administrator through the basic steps to configure MS SQL Server connectivity through ODBC on a UNIX platform.  The walk-through covers this particular environment:

Client

• Windows 32-bit OS
• BusinessObjects Enterprise XI 3.1 SP7 Client Tools
• 32-bit ODBC Drivers for MS SQL Server

Server

• Solaris 10 (although similar steps apply for other UNIX platforms)
• BusinessObjects Enterprise XI 3.1 SP7 Server
• DataDirect 7.0.1 drivers are installed

Creating the ODBC connection on the Client/Designer Machine

1. Launch the 32-bit Data Source (ODBC) program from Start / All Programs / BusinessObjects XI 3.1 / BusinessObjects Enteprise
2. Create a System DSN by Clicking the Add button under the System DSN tab in the ODBC Data Source Administrator
3. Choose the SQL Server driver from the list of available drivers and click Finish
4. Give it a Name, Description and type in the Server name or IP address.  Click Next
5. Specify the authentication type, Login ID and Password for your database. Click Next
6. You can specify a default Database and other options in the next 2 dialogs or except the defaults and click Next  and then Finish.
7. The final step shows you the configuration options that you chose and gives you a Test Data Source... option.  Click this to ensure the connection works
   
8. You should see a "TESTS COMPLETED SUCCESSFULLY!" message in the next dialog if your connection is setup correctly.
   

Creating a Universe Connection off of our ODBC connection

The Next Step is to create a Universe off of this ODBC connection and publish it to your UNIX BusinessObjects Enterprise XI 3.1 system.

1. Open Designer (Universe Designer) application on the same Client machine.
2. Log in to your BusinessObjects Enterprise system using an account that has rights to create Universes and Connections.
3. Click the Begin button on the Quick Design Wizard dialog or go to File / New to create a new Universe.  This tutorial uses the File / New option
4. Give your Universe a Name and then click the "New..." button under the Connection drop-down box.
   
5. Click the Next button in the New Connection Wizard that appears
6. Enter a name for your connection in the Connection Name text box
7. Expand the Middleware list and choose:  Microsoft / MS SQL Server 2... / ODBC Drivers.  Click Next
   
   
8. Enter your Authentication Mode, User name, Password, and select the newly created DSN from the Data source name list.  Click Next
9. Review the Configuration Parameters, make any changes you may need and click Next and then Finish.
10. This returns you to the Universe Parameters dialog.  Click Ok to start building your universe.
    
    At this stage, you will design and build your universe.  This tutorial doesn't go through that.  For the purpose of this tutorial, I will just add 1 table to my universe so that we can test connectivity once it is in Webi.
    
    
    
    
11. Once the universe is designed, click the File / Save option.  This saves it on your local disk for future revisions and safe keepings.
12. Next, we will export it to our BusinessObjects Enterprise deployment.  Click the File / Export option.
13. Choose a Domain (folder) in the Export Universe dialog and click Ok
14. This should produce an "Universe successfully exported." dialog.

That's it.  We now have a universe in our BusinessObjects Enterprise (BOE) system that uses an ODBC connection.  The next step is to configure the back-end so that our ODBC connection works on the UNIX BOE system.

Setting up the ODBC connection on the UNIX BOE 3.1 Server

The next stage is where things often get a little messy.  These are the steps I went through on my system to get this working.  Depending on the variables in your environment, there may be other things to consider.

1. Login to your UNIX system as the user that installed BOE. I do this using a terminal program such as PuTTY
2. go to the /bobje/setup directory and source the env.sh to ensure that you have all the environment variables set that the BOE servers would have when they were running.  More importantly, this sets our ODBC variables so we can ensure that we modify the correct files in the coming steps
   > cd <installdir>/bobje/setup
   > . ./env.sh
3. next, we need to check to see which ODBC file we need to update.  We can check the ODBC environment variables by using this command:
   > env |grep ODBC
   
   output should look like this:
   
   DEFAULT_ODBCFILE=/build/home/xi3170/bobje/defaultodbc.ini
   ODBC_HOME=/build/home/xi3170/bobje/enterprise120/solaris_sparc/odbc
   ODBCINI=/build/home/xi3170/.odbc.ini
4. We have to now edit the ODBC ini file to include our ODBC DSN from the client machine.  We can edit the file referenced in the ODBCINI variable using this command:
   > vi $ODBCINI
5. This opens the /build/home/xi3170/.odbc.ini file for us to edit and append.  To add our DSN entry, we can do the following
   1. Open a 2nd PuTTY or terminal session to the same server and login with the same user
   2. Source the env.sh again using the instructions from step 2.
   3. use the vi command to edit the <installdir>/bobje/odbc.ini file
   4. Copy the section under "[CRSQLServerWP]" and paste it into Notepad on your desktop machine.  It should look similar to the below one:
      
      
      ** This is an image for a reason.  I didn't want to put the text here in case people decided to copy and paste it from here.  It is important that the text you use in vi editor and in text files in general on UNIX are free of any carriage returns or other invisible characters that a copy and past can introduce.  Notepad is just plain text for the most part so I use it to strip out any unwanted characters that the naked eye might miss.
      
   5. Once the text is in notepad.  Make your changes here.  This is easier for most than using vi editor.  Fill in all that apply to your scenario.  At the very least we need Address to be filled out as the rest of the info is stored in the Universe Connection any ways.
   6. The [CRSQLServerWP] text should be replaced with the exact same name of the ODBC connection on your Windows machine.  For example, mine is "test-sql" on my Windows client machine. It needs to be exactly this in here too.  Below is a screenshot of my completed text
      
      
      *** IMPORTANT *** Be sure to add the port at the end of the address or this will not work for you.  <SERVER>, <PORT>
      
      
   7. Copy the text from notepad into your clipboard and ensure that when the text is selected, there is no whitespace that is selected at the end of any of the lines. 
   8. In the original terminal, where we have the ODBCINI file opened, we need to paste this text at the end of the file.  We also create an entry under the "[ODBC Data Sources]" section.  Below is a screenshot of my file once edited.
      
      
      
   9. Save the file in vi using the /wq! command
      
      
6. The next step is to append the <Installdir>/bobje/enterprise120/<os>/odbc/lib path to your LD_LIBRARY_PATH variable.  I have outline the steps I used to do this below:
   1. Using vi editor, edit your user's profile file.  For bash shell, this file is in your home directory and is called .bash_profile.  An easy way to edit this is to type:
      > vi ~/.bash_profile
   2. If this file doesn't exist, it will likely be empty.  Mine only had one entry that I use to set my LC_ALL variable.  We want to go to the end of this file and add an entry like this:
      export LD_LIBRARY_PATH=/build/home/xi3170/bobje/enterprise120/solaris_sparc/odbc/lib:$LD_LIBRARY_PATH
   3. Here is a screenshot of what my .bash_profile looks like after I am done adding the entry
      
      
      
      *** Keep in mind that different UNIX OSes have different paths here.  "solaris_sparc" is valid only for Solaris installs.  The easiest way to find this location is from the odbc.ini file that we got our SQL Server connection parameters from in earlier steps.  This path is the same one used in the Driver= section of Step 5 above.
      
      
   4. Save this file and log off your current shell and open up a new one.  This loads your .bash_profile and using the env |grep LD command should show you that the new environment variable has taken affect.Once this is updated, you will need to restart your node to ensure the changes are reflected in your environment.
      
      
7. Once the node is up and running again, you can login to InfoView and create a new report off of this Universe!

Issues you may encounter

Here are a few issues you may run into.

"DBDriver failed to load" error when running a query off of this universe

This is a common error to see if you have not added the LD_LIBRARY_PATH entry to your profile.  This error basically means that the libodbc.so file is not found in the library path that the WIReportServer.bin has available.  By adding the path to the /odbc/lib directory, as we do in Step 6 above, we are expanding the search path to include the location of this libodbc.so file.

To Solve this, simply double-check that steps 6 above was done correctly.

Full error for searchability:
<Query Name> - <Universe Name>

A database error occured. The database error text is: (CS) "DBDriver failed to load : <installdir>/bobje/enterprise120/<os_specific_dir>/dataAccess/RDBMS/connectionServer/libdbd_wmssql.so (ld.so.1: WIReportServer.bin: fatal: libodbc.so: open failed: No such file or directory)" . (WIS 10901)

Error:  A database error occurred... 20800 (WIS 10901)

This error is hard to troubleshoot because it gives us no real clues as to the root cause.  I did a search internally at SAP for this error and I luckily found an old incident that suggested the solution as being a missing port # in the odbc.ini file.  I added the port to my odbc.ini entry and the error went away.  So, if you get this error, ensure that you double-check your odbc.ini and specifically the Address=<Server>, <Port> section.

Full error for searchability:

<Query Name> - <Universe Name>

A database error occured. The database error text is: [SAP Business Objects][ODBC SQL Server Driver]20800. (WIS 10901)