These kinds of web service transactions can be difficult to debug, because you are usually dealing with multiple layers of separation between your app and the web server that is generating cryptic errors over unidentified minutiae. Fortunately, these web service transactions can be reduced to simple streams of text. You send it some text and, assuming you can connect at all, it sends some text back. So debugging almost always starts with obtaining copies of the details of the request and response so that you can compare them to samples provided by the web service, or send to their tech support people to ask for guidance.

To obtain this debugging information, set the XHTTPF_DEBUG flag, repeat your request, and then examine the following files:

•   debug.req - a copy of the full request, including the generated headers

•   ashnet.log - summary details about the connection, port, protocol, and return status will be appended here

•   <response file> - assuming you get a response, and have the XHTTPF_FILERESP flag set, the response will be in the file specified by the response parameter.

•   debug.le - for lower level failures (like a failure to connect at all), details possibly of interest to MicroSabio will be written here

•   debug.log - contains internal details of the operation, plus a transcript of what was sent and received over the wire.

Often you will find that there are differences between the generated headers of your request and those provided in the web service's specifications or samples, in which case you will need to determine whether they are significant, and if so, how to achieve the necessary changes. In some cases of POST transactions, you will be able to use the technique described above (Customizing POST headers). In other cases, you may want to tinker with some of the flags, such as adding XHTTPF_SETFROMURL or changing between XHTTPF_REQUPLOAD and XHTTPF_REQPOST, to see what effect it has on the generated request. If you know what the request should look like, but don't know how to generate it, please contact us with the above details.

An all-too-common scenario is that the web service has cryptic specifications, no sample request documents to model your request on, and the tech support people point you to some utility, tool or web page that works, for you to use as a model. Unless the tool provides a copy of the request text that it generates, and assuming you can run the test in plain HTTP (not HTTPS) you can use a packet sniffing tool, such as WireShark, to capture the raw message and then use it as your model. If the target service uses a secure port, that technique won't help you, but you may want to inquire whether they have a parallel non-secure sample or test version of the service which you can use to debug the basic request format.

History

2018 May, A-Shell 6.4.1555, ASHNET 1.11.162:  Append Connection Failure Codes to the XHTTPF_GETSTSTXT return string, as well as the ashnet.log, to assist with debugging failed connections