Easysoft XML-ODBC Server User Guide - Running the Server

Running the Easysoft XML-ODBC Server as a service

This section explains the how the Easysoft XML-ODBC Server runs as a service to which external client applications can connect.

Chapter Guide

Introduction

Once it has been successfully installed, the Easysoft XML-ODBC Server acts like an ordinary ODBC-compliant application and runs as a service.

In Windows it takes the form of a network service, controlled by the Windows service control manager and configured to start automatically.

On Unix, the Easysoft XML-ODBC Server is a either a service under {x}inetd (the default) or a standalone process, and can be linked to any specified ODBC driver manager.

If the control port for the Easysoft XML-ODBC Server is enabled, then clients may obtain Easysoft XML-ODBC Server statistics, but only if the server is running as a standalone process (Unix) or under the service control manager (Windows).

Starting the server from the command line

For local access, the Easysoft XML-ODBC Server client software does not need to be installed in order to issue requests to the server and have it return the results in XML.

The Easysoft XML-ODBC Server program can be run directly from the command line with a request in a file.

e.g.

If a file called request.xml in the current directory contains a valid Easysoft XML-ODBC Server request, type:

xmlodbcserver.exe file request.xml out.xml

./esxmlodbcserver file request.xml out.xml

The output is written to out.xml (or use "-" to direct to standard out instead).

There is also a "pipe" method allowing an XML request to be piped into the Easysoft XML-ODBC Server program and output to standard out.

You can run xmlodbcserver/esxmlodbcserver with "-?" as an argument to get a full usage summary, although only the "file", "pipe", "siteinfo" and "version" methods should be used directly.

unixODBC

You are required by Easysoft to use the unixODBC driver manager on Unix platforms in order to run the Easysoft XML-ODBC Server.

unixODBC is an open source project sponsored by Easysoft which is fast becoming the standard across the data access community.


REF

unixODBC is not an Easysoft product, but the unixODBC driver manager is included with the Easysoft XML-ODBC Server distribution.

http://www.unixodbc.org/ is the home page for unixODBC. The distribution found here contains the unixODBC driver manager plus a set of ODBC drivers.


For the details of how to connect to the Easysoft XML-ODBC Server, go to the section appropriate to your server platform:

Running on Windows

Before a client application can connect to a data source on the server machine, the Easysoft XML-ODBC Server must be running.

On Windows 2000, NT and XP, the installation program configures the Easysoft XML-ODBC Server to start automatically as a service.


NB

The Easysoft XML-ODBC Server writes errors and startup information to the Application section of the Event Log. If there is a possibility that the Easysoft XML-ODBC Server is not functioning correctly then it is recommended that the Event Logis checked with the Event Viewer before other lines of enquiry are pursued.


Checking the service

This procedure is only necessary if problems are experienced in connecting with the Easysoft XML-ODBC Server.

1.  Choose the Servicesicon from Start > Settings > Control Panel.


2000/

Choose Start > Settings > Control Panel and open the Administrative Tools icon followed by the Services icon.



XP

Choose Start > Settings > Control Panel > Administrative Tools > Services.


A dialog box displays all the registered services on your NT system.


2000/

XP

The Services dialog box is displayed differently in Windows 2000 and Windows XP, but its principles and the functionality are the same.


Find the entry for Easysoft XML-ODBC Server:

Figure 11: The Easysoft XML-ODBC Server Services entry

2.  If the Startup field says Disabled then click Startup....

3.  In the resulting dialog box, select Automatic and then click OK.

4.  If the Status field does NOT say Started then click Start to bring the Server on-line.

5.  Click Close.

6.  Close the Control Panel.

Services File entries

The Easysoft XML-ODBC Server does not require an entry in the services file to function correctly, but if you want to see the service name (rather than the port number) displayed by the netstat command or reserve the port, you can edit the services file.

On Windows, the services file is usually located in

<install directory>\system32\drivers\etc

Edit the services file with any Windows text editor, such as Notepad. The Easysoft XML-ODBC Server service should be defined as "8895/TCP" assuming you accepted the default port of 8895 during installation. The entry should look like:

esxmlodbcserver 8895/tcp

If you have enabled the control interface for the Easysoft XML-ODBC Server (it is enabled by default), then you may also add:

esxmlodbcserver_c 8896/tcp

To start or stop the service

The Easysoft XML-ODBC Server can be configured like any other service.

For instance, you can set it up not to start automatically on system boot.

You can also explicitly stop the service, as follows:

1.  Choose:

Start > Settings > Control Panel > Administrative Tools (in Windows 2000)

¯ OR ¯

Start > Settings > Control Panel (in Windows NT)

2.  Open the Services icon.

The Service Manager displays a list of services, along with their status (see To start or stop the service) and their startup configuration (see Startup configuration).

3.  In the Services dialog box, ensure that the Easysoft XML-ODBC Server entry is selected.

4.  If the service does not have Started recorded in the Status column, you can click Start to run the service.

¯ OR ¯

If the service has Started recorded in the Status column, you can click Stop to stop the service. Click Yes when the Service Manager asks you to confirm your action.

Startup configuration

When installed, the Easysoft XML-ODBC Server is configured to run automatically when Windows starts.

Windows offers two other options for services:

1.  In the Services dialog box, ensure that the Easysoft XML-ODBC Server entry is selected.

2.  Click Startup... (notStart!) to open the Service configuration dialog box.

3.  In the Startup Type section, choose the relevant radio button:

¯ OR ¯

¯ OR ¯

4.  Click OK to close the dialog box.

User accounts

Windows distinguishes two types of service with respect to their privileges:

The Easysoft XML-ODBC Server is designed to be run in the System Account, with administrative privileges, which allow it access to any System data source on the system.

This is the default configuration of the Easysoft XML-ODBC Server and it provides the greatest general flexibility and security.

The other option is to set up the server to always run with the permissions of a specific user.

This is not recommended, but if you do want to do this the procedure is as follows:

1.  Be sure that the user account you wish to use is set up and that you know its password.

 This account may be that of an existing user or one created specifically for the Easysoft XML-ODBC Server.


Caution!

For the Easysoft XML-ODBC Server to function correctly when running as a specific user, that user needs two important access rights:Log On as a Service, which is needed for the service to start, and Act as Part of Operating System, which is needed so that the service can authenticate connecting users for the Easysoft XML-ODBC Server.


2.  In the Services dialog box, ensure that the Easysoft XML-ODBC Server entry is selected.

3.  Click Startup... (notStart) to open the Service configuration dialog box.

4.  In the Log On As section, select the This Account radio button.

5.  In the This Account text box, type the user name or click ... to browse for a user name.

6.  In the Password box, type the user account password.

7.  Type the same password in the Confirm Password box.

8.  Click OK to close the dialog box and commit your changes.

You may have noticed the Allow Service to Interact With Desktop checkbox. This has no effect on the Easysoft XML-ODBC Server.

Running on Unix

When the Easysoft XML-ODBC Server is installed as an inetd-controlled service, entries are added to the inetd.conf and services files.

Examples of these entries might be

esxmlodbcserver stream tcp nowait root /bin/sh /bin/sh /usr/local/easysoft/xmlodbc/server/server

esxmlodbcserver 8888/tcp # Easysoft XML-ODBC Server

These are just examples and may differ if you picked a different port, service name or installation path.

The mechanics of inetd

inetd handles incoming network connections and starts the relevant program to service each incoming request.

When inetd starts (or is sent a SIGHUP) , it reads /etc/inetd.conf for a list of what services to supply and to configure its handler for each service. It then listens on each port used by those services that have been configured in the /etc/services file.

When a new connection is requested from outside, inetd starts the relevant program and hands over control.

The following example applies to the default installation, when a client connects to port 8895 and inetd uses the information read from /etc/inetd.conf to decide which program to run and with what arguments.


NB

Note that /bin/sh is repeated. The first time it appears (in the sixth position on the line) it is the name of the executable to run. The second time it appears it is the value to be passed as the zeroeth argument to /bin/sh. Normally this is the same as the name of the executable.


In the default installation, the arguments on the line cause /bin/sh to run the Easysoft XML-ODBC Server startup script <InstallDir>/easysoft/xml-odbc/server/server.

The script then sets any necessary environment variables required by the dynamic linker and runs esxmlodbcserver.

The script passes an argument of inetd to the server executable. This notifies the server that it is running under inetd, rather than at the command line.

The Easysoft XML-ODBC Server inherits the sockets from inetd and begins communicating with the client application.

inetd returns to listening on port 8895 for any new connections.

Changing the Port or Service Name

If you have a port conflict or a service name conflict, or for some other reason you want to change the port or service name of the Easysoft XML-ODBC Server, then you will need to edit the configuration files manually.

The port number is only included in /etc/services, but the service name is required in both /etc/inetd.conf and /etc/services.

After making the necessary amendments you will have to send SIGHUP to the inetd process to make it re-read the files.

This can be achieved with the command:

kill -HUP pid

where pid is the process ID of inetd. You need to be root to edit the configuration files and send inetda SIGHUP.

Configuring the server as Standalone

On Unix, the Easysoft XML-ODBC Server is installed as a service running under {x}inetd by default, which prevents any meaningful statistics information about the program being retrieved (see "Example Statistics XML").

However, the Easysoft XML-ODBC Server will also run in standalone mode (i.e. without {x}inetd), which may be preferable if you are making a lot of small connections (as these will then be accepted much faster) and will also allow you to retrieve statistics.

Running standalone means that {x}inetd does not know about the Easysoft XML-ODBC Server service, which must therefore be run either manually or by some other process.

Note that as the Easysoft XML-ODBC Server no longer uses {x}inetd to listen on the socket when running as standalone, you cannot run tcp wrappers.

To start the Easysoft XML-ODBC Server in standalone mode:

1.  Comment out the esxmlodbcserver entries in the{x}inetd and /etc/services files.

2.  Force the configuration files to be re-read using:

kill -HUP pid

where pid is the process ID of inetd

Use the ps command to find the Process ID (PID) of the xinetd process and send either a SIGUSR1 or SIGUSR2 signal (consult the xinetd(8) man page for the correct option):

kill -USR1 pid

¯ OR ¯

kill -USR2 pid

3.  Start the server with:

path/esxmlodbcserver standalone

This notifies the server that it must listen on the port itself and fork its own child process when a connection is made.

The Easysoft XML-ODBC Server reads the <Port> and <ControlPort>settings in path/config.xml for its configuration (see "Example Configuration XML").


NB

Start the Easysoft XML-ODBC Server Server as the root user.


It is possible to add a line to one of your rc scripts to have the Easysoft XML-ODBC Server start up as standalone every time the machine boots.

The file you need to edit depends on your operating system, so consult your system administrator for further information.