This section explains how to configure the Easysoft XML-ODBC Server.
To describe and control the configuration of the software, the Easysoft XML-ODBC Server uses an XML file called config.xml, which is included with the distribution.
config.xml is read and parsed at startup to retrieve all the configurable parameters, but after the server has started any client application is able to use an XML request to either request the current running configuration of the Easysoft XML-ODBC Server or to update it.
The Document Type Definitions required for defining configuration requests, responses and updates are defined in the following sections:
If you want to query the current configuration of a running Easysoft XML-ODBC Server, then send an XML configuration request to the control port, using the layout in "config_request.dtd".
Here is a simple request asking for the current configuration:
<?xml version="1.0" encoding="UTF-8" ?>
The Easysoft XML-ODBC Server responds to this request with an XML file defining its current configuration using the layout in "configuration.dtd".
If you want to update the current configuration of a running Easysoft XML-ODBC Server, then send an XML configuration update request to the control port using the layout in "configuration.dtd".
The Easysoft XML-ODBC Server responds to this request with an XML file describing the success or failure of the update using the layout in "config_response.dtd"=.
You can use the xmlodbc_client compiled C example to issue these requests.
There is an XML format for a request for Easysoft XML-ODBC Server configuration details and for either a response to that request or a request to update those details:
An example XML request to return server configuration details:
<?xml version="1.0" encoding="UTF-8"?>
| This code is available as config_request.xml in <InstallDir>/easysoft/xml-odbc/documentation/dtds on Unix or <InstallDir>\Easysoft\XML-ODBC Server\Documentation\dtds on Windows. |
See "config_request.dtd" for the Document Type Definition for this file.
Example XML for either receiving or updating Easysoft XML-ODBC Server configuration details:
<?xml version="1.0" encoding="UTF-8" ?>
<ControlPort>8896</ControlPort>
<MaxConcurrentConnect>0</MaxConcurrentConnect>
<MaxClientConnect>0</MaxClientConnect>
<WaitForChildrenTerminationOnClosedown/>
<!-- Allow a specific client to issue requests on the normal request port -->
<Client Allow="Yes">194.131.236.64/255.255.255.255</Client>
<!-- Disallow all other clients from using the normal request port -->
<Client Allow="No">0.0.0.0/0.0.0.0</Client>
<!-- Allow a specific client to issue control requests -->
<ControlClient Allow="Yes">194.131.236.64/255.255.255.255</ControlClient>
<!-- Disallow all other clients from using the control port -->
<ControlClient Allow="No">0.0.0.0/0.0.0.0</ControlClient>
| This code is available as config_change.xml in <InstallDir>/easysoft/xml-odbc/documentation/dtds on Unix or <InstallDir>\Easysoft\XML-ODBC Server\Documentation\dtds on Windows. |
The format elements of this file are as follows:
The port on which the Easysoft XML-ODBC Server listens for connections from clients for SQL requests.
This is set to 8895 in the initial Easysoft XML-ODBC Server distribution.
The port on which the Easysoft XML-ODBC Server listens for connections from clients for configuration requests.
This is set to 8896 in the initial Easysoft XML-ODBC Server distribution.
The maximum number of threads or processes that the Easysoft XML-ODBC Server will allow at any one time (there will be one thread or process for every ODBC connection). If MaxConcurrentConnect is set to 0 (the default) then there is no limit, but you can use this parameter to prevent too many simultaneous connections from swamping your server.
The maximum number of concurrent connections from a single client (where a client is defined as the IP address of the machine where the client is running). There is no limit if MaxClientConnect is set to 0 (the default). You can use this parameter to prevent people from swamping your machine with ODBC connections.
A bitmask specifying the events to be logged by the Easysoft XML-ODBC Server.
Logging slows the server down considerably and should only be set as directed by Easysoft support.
The number may be specified as decimal (e.g. in the format 2047) or hexadecimal (e.g. in the format 0x7ff).
The directory to which log files are written if logging is turned on (see Logging).
The default values are /tmp in Unix (used in this example) and c:\temp in Windows, but logging is turned off by default.
Set MultiThreaded to start a new child thread for each connection to the Easysoft XML-ODBC Server or MultiProcess to start a new child process for each incoming connection (the default).
This is set to MultiProcess if an ODBC driver which is not thread-safe is being used or if your ODBC driver leaks memory.
Currently on non-Windows platforms the server always starts new processes as it is NOT multi-threaded and so this flag has no effect.
Set EnableControlInterfaceto enable the control port or DisableControlInterface to disable it.
This is set to EnableControlInterface in the initial Easysoft XML-ODBC Server distribution.
Specifies whether the server should wait for its child processes or threads handling connections to terminate before closing down the server.
This is set to WaitForChildrenTerminationOnClosedown in the initial Easysoft XML-ODBC Server distribution.
Specifies whether child processes or threads created by the server to handle incoming connections should be terminated when the server is closed down (i.e. if KillChildrenOnClosedown is set and a client is connected when the Easysoft XML-ODBC Server service is closed down, then the processes or threads handling the client connections will be killed, causing those clients to lose their connection to the server).
This is set to KillChildrenOnClosedown in the initial Easysoft XML-ODBC Server distribution.
Specifies whether the Easysoft XML-ODBC Server should perform a reverse lookup on the connecting client's IP address to get the client's name.
The name can be used in the statistics and is set to ReverseLookup in the initial Easysoft XML-ODBC Server distribution.
See Access control.
See Access control.
See "configuration.dtd" for the Document Type Definition for this file.
There is a request and a response XML format for Easysoft XML-ODBC Server statistics:
An example XML request for server statistics:
<?xml version="1.0" encoding="UTF-8"?>
| This code is available as statistics_request.xml in <InstallDir>/easysoft/xml-odbc/documentation/dtds on Unix or <InstallDir>\Easysoft\XML-ODBC Server\Documentation\dtds on Windows. |
See "stats_request.dtd" for the Document Type Definition for this file.
An example of an XML response to a request for server statistics:
<?xml version="1.0" encoding="UTF-8"?>
<UpTime>0 days, 1 hour, 20 minutes and 24 seconds</UpTime>
<MaxConcurrent>1</MaxConcurrent>
<ChildrenCreated>3</ChildrenCreated>
<LastConnect>Fri Jul 05 09:24:26 2002</LastConnect>
<LastDisconnect>Fri Jul 05 09:24:31 2002</LastDisconnect>
<Client Name="test.easysoft.com">192.168.0.0</Client>
The elements of this file are as follows:
The result of a request, containing State="xxxxx", where a successful result is indicated by State="00000"(as in ODBC) and any other value indicates an error.
The time in days, hours, minutes and seconds since the Easysoft XML-ODBC Server was started.
The kernel CPU time consumed by the Easysoft XML-ODBC Server process, including the ODBC Driver Manager, any ODBC drivers and any child processes.
The user CPU time consumed by the Easysoft XML-ODBC Server process, including the ODBC Driver Manager, any ODBC drivers and any child processes.
The total number of connections (or attempted connections) to the Easysoft XML-ODBC Server, including refused connections, port scanners or anyone using telnet to access the Easysoft XML-ODBC Server ODBC port.
The total number of connections refused by the Easysoft XML-ODBC Server.
The total number of active threads or processes the Easysoft XML-ODBC Server has created to handle ODBC connections.
The maximum value recorded in the Active field.
The total number of threads or processes that the Easysoft XML-ODBC Server has created during its execution. Connections denied access do not count, because the Easysoft XML-ODBC Server does not start a thread or process for these.
The time the last Easysoft XML-ODBC Server client connected.
The time the last Easysoft XML-ODBC Server client was disconnected.
The number of different client machines which have connected to the Easysoft XML-ODBC Server (where a client machine is identified by its IP address). "Name" is only displayed if you have ReverseLookup enabled (see ReverseLookup/NoReverseLookup).
This field contains the same list of elements as the Connections element (<Total>, <Refused>, <Active>, <MaxConcurrent>, <ChildrenCreated>, <LastConnect> and <LastDisconnect>), but for the Easysoft XML-ODBC Server Control Port.
See "stats_response.dtd" for the Document Type Definition for this file.
On startup, the Easysoft XML-ODBC Server opens the ports specified in config.xml (see Example Configuration XML) in order to accept connections with SQL requests (as specified by the Port element) and with requests or updates to the server configuration (as specified by the ControlPort element).
Access to these ports is controlled by access control rules which are defined by using the Client and ControlClientelements (see "configuration.dtd").
Clients allowed or denied access to the standard SQL request port are defined using the <Client> element.
Clients allowed or denied access to the configuration request port are defined using the <ControlClient> element.
The order of defined clients is important as the server stops when it finds the first match for a client. If the server finds no match for a client it is allowed access.
<Client Allow="Yes">194.131.236.64/255.255.255.255</Client>
The Allow attribute may be "Yes" or "No" specifying whether the named client or network is permitted access to the Easysoft XML-ODBC Server or not.
The Client element data should be of the form:
Both the IP address and the network mask are optional but you need to specify at least one of them. If the network mask is omitted it implies an exact IP address match (i.e. as if network mask is 255.255.255.255).
If the network mask is specified it is applied to the IP address and the client IP address before comparison.
In this example, client 194.131.236.64 is allowed access to the Easysoft XML-ODBC Server (i.e. it may issue SQL requests to the main port).
This example rule applies ONLY to client 194.131.236.64 because the network mask is 255.255.255.255. In this particular case the network mask is not required. However, the network mask is useful when defining networks of computers.
<Client Allow="Yes">194.131.236.0/255.255.255.0</Client>
For this class B address any client in that network is allowed access.
A useful way of denying everyone except the clients you specify as allowed is to terminate the list of clients with a rule like this:
<Client Allow="No">0.0.0.0/0.0.0.0</Client>
This works because the mask 0.0.0.0 is applied to the IP address 0.0.0.0 to get 0.0.0.0. The same mask is applied to the client IP address, which also produces 0.0.0.0 and hence the client matches when a comparison is made.
You may define as many or as few clients as you like, but you are recommended to use this last mechanism as a method of ensuring that only the required clients can gain access to the Easysoft XML-ODBC Server.
© 1993 - 2024 Easysoft Limited. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other trademarks and registered trademarks appearing on easysoft.com are the property of their respective owners.
