libreoffice-mysql.txt

[This rendition has been produced from the original PDF. Accordingly, graphics inclusions have been stripped. 2011 addendum: It should also be noted that LibreOffice replaced OpenOffice.org in 2010 as a result of a code fork.]

OpenOffice.org 1.0, ODBC, and MySQL 'How-to'

Trademarks are owned by their owners. There is no
warranty about the information in this document. Use
and distribute at your own risk. E&OE. The content of
this document is in the public domain, but please be
polite and attribute any quotes.

jpmcc@users.sf.net Version 07-Jun-2002

Table of Contents

'Access' your data - OpenOffice.org 1.0's best kept secret..............3

'Access' for Linux?.................................................3
Software options....................................................3
Notes for users of MS-Windows platforms.............................3

Joining OpenOffice.org 1.0 to MySQL using ODBC..........................4

Installing MySQL....................................................4
Testing MySQL.......................................................4
Installing unixODBC and the MySQL libraries.........................5
Creating the ODBC .ini files........................................6
Testing ODBC........................................................6
Setting up ODBC within OpenOffice.org 1.0...........................7

Using the Data Source Tools in OpenOffice.org 1.0.......................9

Finding the Data Source Tools.......................................9
Working with Table Definitions......................................9
Creating a table...............................................9
Designing Indexes .............................................9
Changing the definition of a table ...........................11
Editing data.......................................................11
Using the Database Toolbar to work with your data..................12
Displaying/Hiding the Data Source Explorer....................12
Find Record...................................................12
Sort Ascending / Sort Descending..............................12
AutoFilter....................................................12
Default Filter................................................13
Sort..........................................................14
Remove Filter / Sort..........................................15
Apply Filter..................................................15
Refresh.......................................................15
Edit Data.....................................................15
Save Current Record...........................................15
Creating new Views of your data....................................16
Rows in the Query Design table................................16
The Query Toolbar.............................................17
More Complex Queries...............................................19
Example 1 - Orders on Hand....................................19
Example 2 Summary Orders on Hand............................21

Using Data Sources in other OpenOffice.org 1.0 programs................22

Calc...............................................................23
Creating a link with Drag and Drop............................23
Menu Options..................................................24
Data Pilot....................................................24
Word...............................................................25
Creating a link with Drag and Drop............................25
Using the Database Toolbar....................................25

Using the Form AutoPilot...............................................27

The Form AutoPilot in action..................................27

-2-

'Access' your data - OpenOffice.org 1.0's best kept secret

'Access' for Linux?
The launch of OpenOffice.org 1.0 in 2002 removed at a stroke one major
obstacle to the universal use of Linux on the desktop. At last, Linux
users have office software - word processor, spreadsheet, graphics, and
presentation - which not only works at least as well as the Microsoft
Office equivalent, but can also use Microsoft Office file formats, and
is genuinely open source.

However, this hasn't prevented objections from Microsoft diehards that
they still can't migrate to Linux, because "Linux hasn't anything like
Microsoft Access". Well, have I got news for you. It has, and it's
called OpenOffice.org 1.0. One of the hidden secrets of OpenOffice.org
1.0 is that it also has a great user-friendly database front end. All
you need to do is wire it up to one of the many open-source databases on
Linux, and you have a Microsoft Access (and more) equivalent.

This document explains how to make this connection, and then provides a
quick tour of the database tools within OpenOffice.org 1.0. Many
hardened OpenOffice.org 1.0 users are completely unaware of what is
hiding under the covers, and are amazed once they start playing with the
'hidden' tools.

Software options
OpenOffice.org 1.0 uses ODBC1 to connect to databases. ODBC is common on
MS-Windows platforms, but is much rarer on Linux. This article will
explain step-by-step how to connect OpenOffice.org 1.0 to the MySQL
database using unixODBC, an implementation of ODBC for *nix. There's no
reason why you shouldn't use another database - as long as it's got an
ODBC component, it should work. I just happen to use MySQL. The starting
point for the examples illustrating this document was a clean laptop
install of RedHat Linux 7.3, so the examples show software installation
from RPMs. If you prefer another installation method, or another
distribution, the principle is the same.

Like many procedures on Linux, it's not difficult to do. Just watch out
for the 'gotchas' - little tricks which are trivial to solve, but which
can cause hours of head scratching if you don't know how.

Notes for users of MS-Windows platforms
The next section of this document applies only to OpenOffice.org 1.0 on
Linux. It's perfectly possible to install OpenOffice.org 1.0, MySQL and
MyODBC on MS-Windows - anyone familiar with software installation on
MS-Windows should find the process quite straightforward.

The rest of the document is applicable to all platforms on which
OpenOffice.org 1.0 runs.

1 or JDBC, for Sun worshippers

-3-

Joining OpenOffice.org 1.0 to MySQL using ODBC

Installing MySQL
Check first to see if MySQL is already installed on your system (warning
- the check is case sensitive)

[root@t22 RPMS]# rpm -qa | grep MySQL
[root@t22 RPMS]#

MySQL is not installed, so you need to download it from
http://www.mysql.com and then install it.

Gotcha: there is a bug in the .49a and .50 versions of the MySQL client
libraries, which prevents the ODBC connection working - you will see
error messages like relocation error: /usr/lib/libmyodbc.so: undefined
symbol: init_dynamic_array. So you need to get a .49 version - if
necessary, search for it using http://www.rpmfind.net.

First of all, you need to install the MySQL server, which runs in the
background on the computer and handles requests from users for access to
MySQL databases.

MySQL Server installation

[root@t22 RPMS]# rpm -ivh MySQL-3.23.49-1.i386.rpm
Preparing... ########################################### [100%]
1:MySQL ########################################### [100%]
Installing all prepared tables

[...snip...]

Starting mysqld daemon with databases from /var/lib/mysql
[root@t22 RPMS]#

You now have a running MySQL database server. By default, the
installation creates an empty database called test, accessible by a user
test without a password (note: the MySQL username is an identifier you
pass to MySQL when you make a connection - it's a different entity from
the username you use to log on to Linux).

You now need to install the MySQL client so you can issue SQL commands
to the server.

Installing the MySQL client

[root@t22 RPMS]# rpm -ivh MySQL-client-3.23.49-1.i386.rpm
Preparing... ########################################### [100%]
1:MySQL-client ########################################### [100%]
[root@t22 RPMS]#

Testing MySQL

Now that the server is running, and you have the client software
installed, you should test that you can access the server from a user
account. Here I'm logged on to Linux as john but I connect using the
pre- defined MySQL username test. I give the select version(); command
just to check everything's ok.

-4-

Testing the MySQL installation

[john@t22 john]$ mysql -utest
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 3.23.49

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> select version();
+-----------+
| version() |
+-----------+
| 3.23.49 |
+-----------+
1 row in set (0.00 sec)

mysql> exit
Bye
[john@t22 john]$

Installing unixODBC and the MySQL libraries
So far so good. You now need to install the ODBC driver, which provides
a standard interface which programs like OpenOffice.org 1.0 can use to
access databases. I use unixODBC from http://www.unixodbc.org.

Installing the ODBC software

[root@t22 RPMS]#[root@t22 RPMS]# rpm -ivh unixODBC-2.2.1-2.i386.rpm
Preparing... ########################################### [100%]
1:unixODBC ########################################### [100%]
[root@t22 RPMS]#

You also need two further pieces of software from http://www.mysql.com -
the MyODBC connection software, and a set of shared libraries it uses to
talk to the MySQL server:

Installing the MySQL libraries

[root@t22 RPMS]# rpm -ivh MySQL-shared-3.23.49-1.i386.rpm
Preparing... ########################################### [100%]
1:MySQL-shared ########################################### [100%]
[root@t22 RPMS]# rpm -ivh MyODBC-2.50.39-4.i386.rpm
Preparing... ########################################### [100%]
1:MyODBC ########################################### [100%]
[root@t22 RPMS]#

-5-

Creating the ODBC .ini files

Now you need to set up the .ini files used by ODBC. These are just text
files which you can edit using your favourite text editor. You will
probably find your RPMs have installed empty templates in /etc

Gotcha: some packagers use /usr/local/etc for the .ini files, and
/usr/local/lib for the libraries

odbcinst.ini lists the ODBC drivers installed on the system. You only
need to define the MySQL driver:

/etc/odbcinst.ini

[MySQL]
Description = ODBC Driver for MySQL
Driver = /usr/lib/libmyodbc.so
Setup = /usr/lib/libodbcmyS.so
FileUsage = 1
CPTimeout =
CPReuse =

odbc.ini defines the links that users will use to link to the actual
database via the driver. Links in odbc.ini are available to all users of
your Linux system.

/etc/odbc.ini

[MySQL-test]
Description = MySQL database test
Driver = MySQL
Server = localhost
Database = test
Port = 3306
Socket =
Option =
Stmt =

Testing ODBC
You're now in a position to repeat the test connection from the user
account, this time using the ODBC connection. isql is a little utility
program provided by unixODBC:

Testing the ODBC software

-6-

| 3.23.49 |
+----------+
1 rows affected
SQL> quit
[john@t22 john]$

Hint: if this doesn't work, try isql MySQL-test -v to get fuller error messages.

What's happening here is that the parameter you pass to isql -
MySQL-test - is passed to the ODBC software. It looks up this parameter
in odbc.ini, and finds the Driver MySQL and the connection information.
It then looks up MySQL in odbcinst.ini, and finds where the libraries
are.

If all this is working, you now have a working database, accessible from
ODBC.

Setting up ODBC within OpenOffice.org 1.0

Nearly there. You now need to tell OpenOffice.org 1.0 about your ODBC
connection. First of all, a couple of little gotchas.

Gotcha: OpenOffice.org 1.0 looks for a library libodbc.so. The RPM I
loaded didn't create this:

[john@t22 john]$ whereis libodbc.so
libodbc:
[john@t22 john]$

so it was back to user root to create a link:

[root@t22 RPMS]# ln -s /usr/lib/libodbc.so.1 /usr/lib/libodbc.so

which solved the problem:

[john@t22 john]$ whereis libodbc.so
libodbc: /usr/lib/libodbc.so
[john@t22 john]$

Gotcha: If your RPMs have installed the libraries into /usr/local/lib,
you still have a problem, because OpenOffice.org 1.0 won't look there,
unless you:

[john@t22 john]$ export LD_LIBRARY_PATH=/usr/local/lib
[john@t22 john]$

before you run OpenOffice.org 1.0

Now we are ready to go. Within OpenOffice.org 1.0, choose Tools / Data
Sources... from the main menu (or press F4), then press the New Data
Source button to open the Data Source Administration window. Type in
Name MySQL-test; select Database type ODBC and press the [...] button.
Next, select the data source you have just created in the Data Source
dialogue (see Figure 1).

-7-

Figure 1 Selecting the new Data Source

Press OK. Back in the Data Source Administration window, choose the ODBC
tab and enter User name test; press OK; and that's all the preparatory
work finished.

-8-

Using the Data Source Tools in OpenOffice.org 1.0

Finding the Data Source Tools
To use database functions at any time, select View / Data Sources from
the main menu (or press F4). The Data Source Explorer on the left hand
side of the Data Sources screen shows all the data sources currently
known to OpenOffice.org 1.02. The usual conventions apply - click on the
+ sign to show more information, right click on an item to see the tools
available. The right hand side of the screen is the Data Source Browser,
which shows the contents of any currently selected data source.

Working with Table Definitions

Creating a table

Expand the MySQL-test link in the Data Source Explorer by clicking on
the plus sign; then right click on the Tables item to pop up a menu.
Choose New Table Design to display the Table Design Screen (see Figure
2).

Figure 2 Using the Data Source Explorer

We're creating a table to hold a bookseller's stock list. OpenOffice.org
1.0 acts as a 'window' into MySQL, so the rules about what you can call
fields, what types of data are available, etc are as per MySQL. The
panel at the bottom right contains context sensitive help, but for
definitive help you should look to the MySQL documentation3.

The completed table definition in the Table Design window is shown in
Figure 3. Note that if you want to be able to update the data in this
table within OpenOffice.org 1.0, you need to define one field as a
primary key - you do this by right-clicking on the indicator bar at the
left hand edge of the screen and setting the Primary Key flag. This is
shown by a key symbol - this example shows ISBN is the primary key. When
you have finished, click the Save button, name the table stocklist, and
close the window. Your new table will now be visible in the Data Source
Explorer.

Designing Indexes

There is also an index designer available from the Table Design window,
either from Tools / Index Design... on the menu or the Index Design
button on the toolbar (see Figure 4).

2 The Bibliography data source is a default installed by OpenOffice.org 1.0.
3 for example, see http://mysql.com/documentation/mysql/bychapter/manual_Reference.html#Legal_names

-9-

Figure 3 Table Design for stocklist

Figure 4 Index Designer

-10-

Changing the definition of a table

If you need to make changes to the fields in your table, right click on
the table name in the Data Source Explorer and select Edit Table. This
will put you back in the Table Design window.

Editing data
Tables can be edited directly from Data Sources screen - simply click on
the tablename in the Data Source Explorer, and the contents of the table
will be displayed in the Data Source Browser on the right. The example
below shows the fully populated stocklist table.

Figure 5 The stocklist table

Note the Navigation Bar at the bottom of the Data Source Browser to help
you move rapidly through your table.

The usual 'spreadsheet' conventions also apply:

double-click on a column heading to resize the column width;
right click on a column heading to set the column width manually,
set a new column format, or hide a column;

right click on any of the row markers to set the row height or
reformat the whole table.

Note: any comments you entered in the 'Description' field when you set
up the table will appear as hints when you move the mouse cursor over
the column heading in the Data Source Browser.

-11-

Using the Database Toolbar to work with your data

Much of the power of OpenOffice.org 1.0 is provided by the Database
Toolbar that appears at the top of the Data Source Browser. This
contains the following buttons from left to right hover the mouse over
each one to see a hint (make sure you have Tips enabled on the Help
menu).

Displaying/Hiding the Data Source Explorer

Useful if you want to maximise the amount of data you can see on the
screen this button toggles the display of the Data Source Explorer on
and off

Find Record

This button displays the Record Search dialogue. For example, see Figure
6 for an example of to find a book with the word 'biggles' in its title.
Note that this will search the table record by record which can be a
slow process on big tables!

Figure 6 Record Search Dialogue

Sort Ascending / Sort Descending

Clicking on a column heading to select a field, and then pressing either
of these buttons will cause the display in the Data Source Browser to be
sorted on the selected column in either ascending or descending order.

Note: the Sort buttons only change the way the data is displayed - the
underlying database is not affected.

AutoFilter

Auto Filtering is a very powerful tool for displaying only the records
that meet certain criteria. For example, one of the publishers in the
stocklist table is 'Dorling'. Clicking on the cell containing the word
'Dorling' (see Figure 7) and then pressing the AutoFilter button will
display only the records where the publisher is 'Dorling'. Note that if
you now do another autofilter, it will add to the one already in force
e.g. repeating the

-12-

process for Cover equals 'H' will show only the Publisher 'Dorling'
Hardbacks. The Remove Filter / Sort button (see below) will reset the
table view.

Note: filters only affect the way the table is displayed - they do not
change the data in the database.

Figure 7 Selecting a value for Auto-filtering

Default Filter

Using this button, you can see or change any filter currently in place.
For example, if you have used the Autofilter as described above, and
then pressed the Default Filter button, you would see the filter in
Figure 8.

Figure 8 Filtering

You could now refine your filter to display Dorling Hardbacks costing
more than £30 by setting the an additional filter - see Figure 9

-13-

Figure 9 Filtering - adding another condition

with the results shown in Figure 10

Figure 10 Filtered data

Sort

The Sort Ascending / Sort Descending buttons described on page 12 enable
you to specify a simple sort on a single field with one click. The Sort
button enables you to set up more complicated sorts, for example in
alphabetical order of title by each author by each publisher (Figure
11).

-14-

Figure 11 Sort Order Dialogue

Remove Filter / Sort

This button returns the view of the table to the default.

Apply Filter

If you have defined a filter using the AutoFilter or Filter buttons,
this button will toggle the filter on and off.

Refresh

It is possible to open multiple editing windows onto the same table,
either from one user or from many users if you are in a multi-user
system. Pressing the Refresh button forces OpenOffice.org 1.0 to reload
its view of the data from the database to reflect any changes made
elsewhere to the underlying data.

Edit Data

If your table has a primary key defined, pressing this key will allow
you to edit the data directly in the Data Source Browser. Any changes
you make on the screen are posted to the database as you move on to a
different record, or you can force an immediate update using the Save
Current Record button.

Save Current Record

If you are editing a record, pressing this button forces any changes to
be written immediately to the database.

-15-

Creating new Views of your data

The Database Toolbar is a very powerful tool for analysing and working
on your data. However, it is sometimes useful to be able to set up a
pre-set view of a table, for example for other people to use. For
example, we might want to set up a view showing just the books published
by Penguin which are currently in stock in alphabetic order of title.

In the Data Source Explorer of the Data Sources window, right click on
Queries and select New Query Design. An Add Tables Dialogue will prompt
for the tables to be used in the query add the stocklist table then
close the Add Tables Dialogue. You will then be in the Query Design
screen, and can design your query (see Figure 12).

Figure 12 Penguins in Stock Query Design

Rows in the Query Design table

Field

The Fields to be included in the query can be double-clicked in the
upper pane, or 'dragged and dropped' from the upper pane, or entered by
clicking in the Field row of the bottom pane and using the drop-down
boxes.

Alias

The 'Alias' row allows you to change a column heading.

Visible

The 'Visible' row allows fields to be used in selection criteria, but
not to be displayed.

-16-

Functions

The 'Function' row allows you to specify summary or grouping functions
(see the Advanced Examples later).

Criterion

The 'Criterion' row sets filter conditons here we have specified
Publisher equals 'Penguin' and Status is not empty (null)4.

The Query Toolbar

The Query Toolbar provides more functionality:

Run Query

will immediately display the results of your query in a new Data Source
Browser (see Figure 13).

Figure 13 Query Designer with Data Source Browser

Note how this Data Source Browser has its own Toolbar as well!

Clear Query

Will remove the query design currently on display

Switch Design View On/Off

Behind the scenes, the Query Designer translates your design into the
SQL commands which MySQL understands. For advanced users, this button
will toggle the display of the raw SQL commands generated

4 You can specify wildcards in the usual way: LIKE 'AB*' finds
everything starting with AB etc.

-17-

by the Query Designer. You can edit these commands directly, and the
changes will be reflected back into the Data Designer.

Add tables...

Allows you to put multiple tables into your query. See 'More Complex
Queries' on page 19.

Functions / Table Name / Alias

These buttons are toggles to display / hide the corresponding rows in
the Query Designer

Distinct Values

This toggle allows you to create a query to answer questions like: "Show
me all the authors who are in the stocklist". The example I am using has
25,000 records in it. If you try to answer the question by creating the
following query:

Figure 14 A 'distinct' Query

without the Distinct button being pressed, OpenOffice.org 1.0 would show
you the 25,000 records one for each record, with the same author
listed as many times as they appear in the table. Selecting Distinct
would show each author once only which is what you want.

Edit

The Edit button toggles the Query Design in and out of edit mode.

-18-

Save

Stores the Query Design5. Once a query has been saved, it is available
within the Data Source Explorer and its contents can be viewed in the
Data Source Browser - see Figure 15.

Figure 15 Displaying a Query

More Complex Queries

The Data Designer is a powerful tool for creating queries which means
you can perform day to day enquiries without needing to know any SQL6.
This includes joining and summarising tables.

Example 1 - Orders on Hand

As an example of what can be achieved, suppose you have created Orders -
a table of books which have been ordered by customers, where you record
the ISBN of the book and the quantity to order. The example in Figure 16
shows how you could link this table with the main stocklist table using
the Query Designer.

Linking tables

Note how the two tables are linked through the common field ISBN to
create this in the Query Designer, simply 'drag and drop' the field from
one list to the other7.

Calculated fields

The field 'Value' is defined as the product of Price and Order_Qty by
entering the calculation in the 'Field' record.

5 Queries are stored in a file DataAccess.xml deep within the your
OpenOffice.org directory structure.
6 You can also run any SQL commands directly, e.g. MySQL specific
commands that are not understood by the Data Designer or by ODBC.
7 Advanced users can define the type of the link by double-clicking
on the connection line

-19-

Formatting data

The 'No', 'Price', and 'Value' fields are formatted by right-clicking on
the relevant columns and choosing the appropriate options (Right
aligned, UK currency).

Figure 16 Advanced Query - Linked Tables

-20-

Example 2 Summary Orders on Hand

Following on from the example above, the next query in Figure 17 shows
how to obtain the total orders on hand by publisher.

Group and Sum functions

Often used together, the Group and Sum functions define at what level
the data is required (Group), and how it is to be calculated (Sum).

Figure 17 Advanced Query - summarising linked tables

-21-

Using Data Sources in other OpenOffice.org 1.0 programs

So far, this document has concentrated on accessing data using the F4
View / Data Sources route. However, sometimes it is more convenient to
pull data directly into another OpenOffice 1.0 tool, such as Calc or
Write. This section shows you how.

-22-

Calc

Creating a link with Drag and Drop

Extracting data from a Data Source into a spreadsheet in OpenOffice.org
is as simple as dragging and dropping. In Calc, press F4 or View / Data
Sources... as usual, and open the Table or Query you want to copy into
Calc. It's easiest if you change from Stick to Floating view (use the
pin icon at the bottom left of the Data Source Explorer) see Figure
18.

Figure 18 Dragging data into a spreadsheet

To link the data into the spreadsheet, simply click on the data, and
drag the data into the spreadsheet. When you drop, a link will be
created between the spreadsheet and the data source see Figure 19.

-23-

Figure 19 A linked spreadsheet

Menu Options

Once you have created the link, there are a number of menu commands you
may find useful, accessible from the main menu once you select a cell
containing linked data.

Any time you want to update the spreadsheet with the latest data in
the database, select Data / Refresh Range from the main menu

Data / Define Range and press More allows you to choose whether
column headings are imported; whether any formatting you set is removed
at every Data / Refresh Range; and whether the imported data is saved
with the spreadsheet or not (to save disk space)

Data Pilot

It is also worth noting that the DataPilot can access data directly from
Data Sources, giving an amazingly powerful tool for crosstabulation,
etc. Well worth exploring!

-24-

Word

Creating a link with Drag and Drop

Gotcha: Although it should be possible to 'drag and drop' data into a
text document in the same way as a spreadsheet, this doesn't work
correctly in OpenOffice.org 1.0.

However, there is a workround.

Using the Database Toolbar

Selecting the data in the Data Source Browser enables two toolbar
buttons, Data to Text... and Data to Fields... .

Data to Text...

There are three options available from this toolbar.

Figure 20 Inserting Data as a Table

Insert Data as Table allows you to select fields from your data source,
whose data is the copied into columns of a table in your document. The
usual table formatting options are available. The data is copied in as
text and will not change if the data in the database changes see
Figure 12.

-25-

Insert Data as Text works similarly, expect the data is simply copied in
without being formatted as a table see Figure 21. Note: this is one
way to convert a data source into a comma delimited text file for
exporting to other software.

Figure 21 Insert Data as Text

Data to Fields... is used for mail merge type operations. The mail merge
facilities in OpenOffice.org 1.0 are comprehensive, and out of scope of
this document (sorry).

-26-

Using the Form AutoPilot

OpenOffice.org 1.0 contains a complete programming environment using a
variant of the popular BASIC programming language. Using this
environment, developers can write complete applications for end users,
such as sophisticated forms.

Fortunately, it is possible to create a fully-functioned form without
any programming knowledge, by using the Form AutoPilot.

The Form AutoPilot in action

From the main menu, select File / AutoPilot / Form... Choose the
MySQL-test database, and the Orders on Hand Query. Copy all the fields
from the Existing Fields box to the Fields in Form box, and press Next.
OpenOffice.org 1.0 will start to build your form in a new window. On the
Choose Layout dialogue, any selections you make will be reflected
immediately in the new form. Figure 22 shows the result of accepting the
defaults and pressing Create.

Figure 22 A Form created by the AutoPilot

What the AutoPilot has done is build into one form all the functionality
needed to maintain this table, with both a Data Navigation Toolbar, and
a Database Toolbar including commonly-used tools for filtering, sorting,
etc. This is a very easy way to create a simple database application.

Note - if you want to explore the options available for developing this
form further, pressing the Form button on the toolbar on the left hand
side of the screen will toggle the window in and out of Design mode. In
Design mode, you can select items on the form and right click on them to
display and edit their Properties, Data, and Events.

Welcome to the world of OpenOffice.org 1.0 BASIC programming you have
now reached the end of what this document can teach you!

-27-