Debugging IQX Connection Failures [iqx]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Debugging IQX Connection Failures ======
<panel type="primary" title="Scope">This article is primarily concerned with resolving login failures rather than disconnection problems. Disconnection problems are almost invariably caused by faulty network connections.

This article applies to recent versions of IQX that use FireDAC for database communications. For older versions of IQX using BDE connections (check Help | About, if in doubt) see this page - [[DeguggingBDEConnectionFailures|Debugging IQX BDE Connection Failures]].</panel>

===== Overview of relationship between iqx.ini, database and server names===== 

[[http://www.iqxusers.co.uk/iqxhelp/lib/exe/fetch.php?media=iqxshortcuts-servernames.pdf|{{ :iqxshortcuts-servernames.jpg?900direct |Overview of IQX connections - please click to enlarge}}]]

//please click image to enlarge//

=====IQX.INI=====
The iqx.ini file contains many settings controlling the behaviour of iqx. It is found in the same folder as the copy of the iqx.exe program that is being run. Depending on how IQX has been installed, this may be on a local computer, a shared folder / mapped drive on a file server or on a remote desktop server. If there is any doubt about the location of the IQX program being run or iqx.ini, check the Properties of the short cut icon used to launch IQX and inspect the Target setting. Full details of the settings in iqx.ini can be found on [[technical:th14-00|this help page]].
===== The IQX Login Screen =====
The login screen  takes three parameters:
{{ :iqx_login_screen.jpg?200nolink |}}
==== Database, User & Password ====
**Database** should be defined in iqx.ini. If not, IQX will look for an ODBC DSN or the same name defined on the local computer. NB the fall back to DSN is provided for ease of upgrading older installations and is NOT the preferred method.

**User** is the IQX user Login Name held in the database. It is often but not necessarily the same as users Windows user name.

**Password** is the case sensitive password associated with the User in IQX.

===== Narrowing Down the Likely Causes of Connection Failure =====
<html>
<head>
<style>
.col0 {font-size: 14px; }
.col1 {color: #4CAF50;
      font-size: 14px; }
.button {}
.button1 {
            font-size: 14px;    
            background-color: #4CAF50 !important; /* Green */
            border-radius: 12px;
            display: inline-block;
            padding: 5px 5px
            }
.button1:hover {background-color: #3e8e41}
.button1:active {
  background-color: #3e8e41;
  box-shadow: 0 5px #666;
  transform: translateY(4px);
}
</style>
</head>
<div class="level2">
<ul class=" fix-media-list-overlap">
<li class="level1"><div class="li"> Are other users currently connected to the same database? If so, 4 cannot be the issue. <button type="button" class="button button1" onclick="document.getElementById('4').style.color='lightgrey'">Yes</button></div>
</li>
<li class="level1"><div class="li"> Are other uses on the same Local Area Network (ie the same office) connected to the database? If so, 4 &amp; probably 5 are eliminated. (it is possible, but unlikely that a network problem is effecting the single computer).<button type="button" class="button button1" onclick="document.getElementById('4').style.color='lightgrey'; document.getElementById('5').style.color='grey'">Yes</button></div>
</li>
<li class="level1"><div class="li"> Can the user having the problem login from another computer in the same office, with their credentials? If so then 1, 2, 4 &amp; probably 5 are ruled out.<button type="button" class="button button1" onclick="document.getElementById('1').style.color='lightgrey'; document.getElementById('2').style.color='lightgrey'; document.getElementById('4').style.color='lightgrey'; document.getElementById('5').style.color='grey'">Yes</button></div>
</li>
<li class="level1"><div class="li"> Can other users that share the same iqx.ini file (on a network share or mapped drive) connect? If so then 3 &amp; 7 are not the problem.<button type="button" class="button button1" onclick="document.getElementById('3').style.color='lightgrey'; document.getElementById('7').style.color='lightgrey'">Yes</button></div>
</li>
<li class="level1"><div class="li">Does the problem affect all users in one office (who have connected in the past) while other offices can connect alright. If so, then 5 is almost certainly the problem, unless there have been changes made to all the computers' iqx.ini files (or a shared iqx.ini).<button type="button" class="button button1" onclick="document.getElementById('1').style.color='lightgrey'; document.getElementById('2').style.color='lightgrey'; document.getElementById('3').style.color='lightgrey'; document.getElementById('4').style.color='lightgrey'; document.getElementById('5').style.color='#4CAF50'; document.getElementById('6').style.color='lightgrey'; document.getElementById('7').style.color='gray';">Yes</button></div>
</li>
<li class="level1"><div class="li"><button type="button" class="button button1" onclick="document.getElementById('1').style.color='#4CAF50'; document.getElementById('2').style.color='#4CAF50'; document.getElementById('3').style.color='#4CAF50'; document.getElementById('4').style.color='#4CAF50'; document.getElementById('5').style.color='#4CAF50'; document.getElementById('6').style.color='#4CAF50'; document.getElementById('7').style.color='#4CAF50';">Reset Choices</button></div>
</li></div>
</ul>
<div class="level2">
<div class="bs-wrap bs-wrap-panel panel panel-primary"><div class="panel-body"><div class="bs-wrap bs-wrap-panel-body panel-body">The reasons that a login fails is likely to be one of the following:</div><div class="table-responsive"><table class="inline table table-striped table-condensed">
	<tr class="row0">
		<td class="col0">1</td><td class="col1" id="1">The user name is incorrect or not authorised to connect to the requested database</td>
	</tr>
	<tr class="row1">
		<td class="col0">2</td><td class="col1" id="2">The wrong password has been supplied</td>
	</tr>
	<tr class="row2">
		<td class="col0">3</td><td class="col1" id="3">The requested database is incorrect or not defined</td>
	</tr>
	<tr class="row3">
		<td class="col0">4</td><td class="col1" id="4">The database server is not running</td>
	</tr>
	<tr class="row4">
		<td class="col0">5</td><td class="col1" id="5">There are network connectivity issues</td>
	</tr>
	<tr class="row5">
		<td class="col0">6</td><td class="col1" id="6">The necessary SQL Anywhere driver files are not installed or registered on the client computer</td>
	</tr>
	<tr class="row6">
		<td class="col0">7</td><td class="col1" id="7">The requested database is incorrectly defined</td>
	</tr>
</table></div>
</div></div>
</html>
===== Error Messages =====
==== Invalid User Name or Password  ====
{{ ::invalidusernameorpassword.jpg |}}
This error indicates that the user has provided an incorrect or expired username or an incorrect password for their user account. To establish which, as user with Maintenance rights can connect to IQX and view  Connections in Maintenance | Database Diagnostics | Connection.

With <key>Failed</key> pressed, the Connections view will show attempted logins where IQX was to connect to the database but the users login credentials were rejected because:
  * the password was incorrect - **Invalid Password**
  * the User was not defined in the database - **Invalid User Name**
  * the user was defined but was marked as Not in Use in Maintenance | Users - **User 'Not In Use'**

The relevant record in Connections can be found using IP address of the computer that is attempting to connect and the time of the attempted connection. If there is no corresponding record, then then IQX has not been able to connect to the database.\\ \\ 

This is an example of Reasons 1 or 2 in the [[#narrowing_down_the_likely_causes_of_connection_failure|list]] above.

====Database name incorrect or not set up====
{{ :databasenameincorrect.jpg |}}
This message indicates that the settings for the requested database cannot found in the iqx.ini file or as an ODBC data source. The actions to be taken are to:
    - Check that the short cut from which IQX was launched is pointing to the correct folder, and therefore the correct iqx.ini file
    - Setup the database details in the [Databases] section of iqx.ini

This is an example of Reason 3 in the [[##narrowing_down_the_likely_causes_of_connection_failure|list]] above.
====Database connection error====
{{ ::databaseconnectionerror.jpg |}}
This message indicates that while connection settings have been identified for the requested database, a successful connection could not be established. To get more information, press the <key>Details</key> button. This results in a detailed and somewhat technical error log, which can be copied to the Windows clipboard. The following sections give guidance for the possible different error messages:
\\
<panel title="Data source name not found and no default driver specified">
{{ :nodefaultdriverspecified.jpg? |}}This is a rather misleading error message from the Microsoft ODBC driver manager that indicates that the ODBC driver requested is not installed. The driver version required is specified in the connection string in iqx.ini. In the example above the setting in the ini file was:<code>[Databases]
v16test=asa19;eng=Chill16;dbn=v16Test;links=tcpip;</code>
The =asa19 part tells the system to connect using a SQL Anywhere v19 driver. \\ \\ 
The action to be taken is: either that ODBC driver needs to be installed on the client computer (using the IQX Client Installer) or the iqx.ini file needs to be corrected to use the installed ODBC driver.
\\ \\ This is an example of Reason 6 in the [[##narrowing_down_the_likely_causes_of_connection_failure|list]] above. "asa" stands for "Adaptive Server Anywhere" the former name of "SQL Anywhere".
</panel>

<panel title="Unsupported database protocol">{{ ::unsupporteddatabaseprotocol.jpg? |}}This indicates that a non-SQL Anywhere driver has been requested. The specified drives for IQX connections must be in the format asaNN, where NN is the major version number e.g. asa11 for SQL Anywhere 11, asa16 for SQL Anywhere 16 etc. In this example the setting in the iqx.ini file was:<code>[Databases]
v16test=qasa16;eng=Chill;dbn=v16Test;links=tcpip(host=192.168.1.138:2638);prows=1000;pbuf=81920;comp=YES;</code> The action to be taken is that the iqx.ini file needs to be corrected.\\ \\ 
This is an example of Reason 7 in the [[##narrowing_down_the_likely_causes_of_connection_failure|list]] above.
</panel>
<panel title="Database server not found">
There can be a number of causes behind this error. The network location of the server may be incorrectly specified, the database server name may be wrong (even though the network address is right), the details specified may be correct but the server may not be running, or networking issues may mean that the is not accessible by the local computer. The details of the error message have to be examined to determine which of these applies.
<callout type="primary"> 
===Database server not found + Found server, verifying server name===
{{ :databaseservernotfound.jpg |}}  
In this case there is no error with the drivers, but IQX has been unable to connect to the requested database server. The database server ChillXX has been specified, and a network address and port given (host=). A database server has been found at that network address, but the name is wrong, so the connection fails. This indicates that either the requested name is wrong or an incorrect network address has been specified. The required action is to correct whichever of these settings in the iqx.ini file is wrong.\\ \\ 
This is an example of Reason 7 in the [[##narrowing_down_the_likely_causes_of_connection_failure|list]] above.
</callout>
<callout type="primary"> 
===Database server not found + error 10061===
{{ ::databaseservernotfounderror10061.jpg? |}}
Again the reported error is "Database server not found" however the TCPIP error 10061 is reported. This means that the target computer actively refused the connection, in order to do so there must be a running computer at the address specified, so either the address is wrong, or most likely the incorrect TCPIP port has been specified. \\ \\
The required action is to correct the settings in the iqx.ini file.\\ \\ 
This is an example of Reason 7 in the [[##narrowing_down_the_likely_causes_of_connection_failure|list]] above. </callout>
<callout type="primary"> 
===Database server not found, but no other indication===
{{ :databaseservernotfoundwithoutotherindication.jpg |}}
This indicates that IQX can get no response from the given network address nor by trying to find the database engine by name. Either the address is wrong, or the database server is not running, or there is a network problem (which could include a firewall blocking traffic). If it is a firewall issue on a central/hosted server then it is likely that no one at all will be able to connect.  If it is a firewall or antivirus issue on the local pc then you may find that some others can connect when one user can't.  It is best to check the other things first before investigating a port blocking issue.  If there is an IT department or hosted IT company that manages the client's IT then any network or server changes should be carried out by them. \\ 
This is an example of either Reason 4, 5 or 7 in the [[##narrowing_down_the_likely_causes_of_connection_failure|list]] above. 
<callout type="primary"> 
</callout>
</panel>
<panel title="Specified database not found">
{{ ::specifieddatabasenotfound.jpg |}}
This error indicates that IQX has been able to connect to the database server specified in the iqx.ini file, but it has not found a database of the name specified in the dbn= setting. The most likely cause is that the database name in iqx.ini is wrong, there is a possibility that an administrator has temporary stopped the individual database while leaving the database engine running on the server. In the case of a live database this latter reason is highly unlikely, but is possible for a training or test database.\\ \\ The required action in most cases is to correct the dbn= setting in iqx.ini. \\ \\ This is an example of Reason 7 in the [[##narrowing_down_the_likely_causes_of_connection_failure|list]] above.
</panel>

The guidance above assumes that iqx.ini rather than the ODBC administrator is being used to manage database connection details. For help with the ODBC administrator, refer to [[DeguggingBDEConnectionFailures#issues_with_the_odbc_dsn_or_the_network|Issues With the ODBC DSN]] in the BDE troubleshoot guide.