sa26-00

Debugging IQX Connection Failures

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 - Debugging IQX BDE Connection Failures.

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

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 this help page.

The IQX Login Screen

The login screen takes three parameters:

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

  • Are other users currently connected to the same database? If so, 4 cannot be the issue.
  • Are other uses on the same Local Area Network (ie the same office) connected to the database? If so, 4 & probably 5 are eliminated. (it is possible, but unlikely that a network problem is effecting the single computer).
  • Can the user having the problem login from another computer in the same office, with their credentials? If so then 1, 2, 4 & probably 5 are ruled out.
  • Can other users that share the same iqx.ini file (on a network share or mapped drive) connect? If so then 3 & 7 are not the problem.
  • 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).
The reasons that a login fails is likely to be one of the following:
1The user name is incorrect or not authorised to connect to the requested database
2The wrong password has been supplied
3The requested database is incorrect or not defined
4The database server is not running
5There are network connectivity issues
6The necessary SQL Anywhere driver files are not installed or registered on the client computer
7The requested database is incorrectly defined

Error Messages

Invalid User Name or Password

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 Failed 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 list above.

Database name incorrect or not set up

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:

  1. Check that the short cut from which IQX was launched is pointing to the correct folder, and therefore the correct iqx.ini file
  2. Setup the database details in the [Databases] section of iqx.ini

This is an example of Reason 3 in the list above.

Database connection error

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 Details 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:

Data source name not found and no default driver specified

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: 

[Databases]
v16test=asa19;eng=Chill16;dbn=v16Test;links=tcpip;

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 list above. “asa” stands for “Adaptive Server Anywhere” the former name of “SQL Anywhere”.

Unsupported database protocol

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: 

[Databases]
v16test=qasa16;eng=Chill;dbn=v16Test;links=tcpip(host=192.168.1.138:2638);prows=1000;pbuf=81920;comp=YES;

The action to be taken is that the iqx.ini file needs to be corrected.

This is an example of Reason 7 in the list above.

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.

Database server not found + Found server, verifying server name

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 list above.

Database server not found + error 10061

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 list above.

Database server not found, but no other indication

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 list above. <callout type=“primary”>

Specified database not found

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 list above.

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 Issues With the ODBC DSN in the BDE troubleshoot guide.

  • sa26-00.txt
  • Last modified: 2018/07/17 08:23
  • by sean