How to solve problems with QAS API integrations

Summary

This document describes the available tools to help developers diagnose why a QAS API integration may not be working. Standard QAS error messages are sometimes not sufficient to diagnose problems with API integrations.

Please note: The Error message function must be used in order to bring back textual descriptions of errors from Primary level API integrations.

Solution

In order to determine the problems with an API integration logging tools have been developed and are part of the API product.

There are two types of logging possible:

• Kernel Logging
• API Logging

Kernel Logging

This type of logging allows all the problems the API experiences when it is running to be sent to a log file so you can see where and how problems are being generated. Kernel logging basically reports on the files being opened and closed. This is useful in detecting missing or out of date QAS data files.

For example with UK v3.xx product, the error message "could not open streets file" would be displayed as below in the log file:

> File not found (q:\pafdata\qastrt.dat)

>> Could not open streets file

The single chevron indicates the initial problem that occurred. A double chevron means that the error was generated in response to a previous problem. As you can see there is far more information now available to help diagnose the problem.

Setting up Kernel Logging

To generate a kernel log file a couple of lines must be added to the products configuration file. The configuration has the file extension .ini and can be found in the same folder as the executable. The name of this file differs depending on the product you are using. See table below for examples.

UK Products (e.g. Pro/Rapid UK V3)

These are the lines that should be added to the relevant ini file, underneath the Datadir= keyword in the [QADefault] section:

LogTrace=-1

LogFile=mylogfile.txt

LogErrors=yes

This will create an error log file called mylogfile.txt in the same folder as the standard configuration file.

International Products (QAWORLD.INI Configuration File)

Please note that Pro/Pro Web/Batch V3/V4 already have the kernel logging lines added to the configuration file within the [QADefault] section.

[QADefault]

LogFile=

LogErrors=No

All you need to do is enter a file name for the Logfile and change LogErrors to say yes.

API Logging

API logging is used to determine what parameters are being passed to and back from QuickAddress API products. This is particularly useful when checking why a library falls over for ‘no apparent reason’

Create a file called QAAPI.INI in the same directory as the API library. In this file put the line:

ApiFile=C:\temp\apilog.txt (or whatever is appropriate)

Sometimes it is necessary to keep old API log files when examining an integration’s behaviour over time. The default behaviour when setting up API logging is to overwrite the existing file. To change this to append mode, the line in the QAAPI.INI file that usually reads

ApiFile=[path to API log]

should be changed to

ApiLog=Yes

Then the line in the product ini file (e.g. qapro.ini, qaproweb.ini) that usually refers to the kernel log file should be changed from

Logfile=[path to kernel log]

to

Logfile=+[path to API log]

e.g.

Logfile=+C:\Temp\Apilog.log

This procedure means it is not possible to set up ‘append mode’ with API logging concurrently with kernel logging. API logs should be backed up before enabling kernel logging.

Please note that if you are still unable to resolve your problem after reviewing the log files generated you can contact QAS Support. If you do contact Support please send through these log files. There is a facility available to attach  files on the Support website along with your support request.