Messages and Return Codes

`rc` Values

The value of rc may be interpreted as follows:

Error Type	`rc` Value	Description
No error	`0`	`HttpCommand` was able to format and send the request and receive a response without error.
Conga error	`>0`	If `rc` is a positive integer, it is a return code that is signalled by Conga when sending the request and receiving the response. If Conga detects an error at the operating system level, it will return the operating system return code. For instance, 10013 is the Microsoft Windows return code for "port in use".
Translation Error	`¯2`	You specified `TranslateData←1` and `HttpCommand` was unable to translate an XML or JSON response payload using `⎕XML` or `⎕JSON` respectively or you used `GetJSON` and response content-type header was not `'application/json'`.
Everything else	`¯1`	This is the generic return code for any error condition that is not signalled by Conga.

In general if rc=0 then msg will be empty. There are circumstances where msg will contain an informational message even if rc=0. These messages are included below.

In the following message descriptions, items that are enclosed in {} represent the value of that named item. For instance, {BufferSize} represents the value of the BufferSize setting. In many cases, the message text itself is sufficient to explain the condition and its resolution, but we document them nonetheless for completeness.

"Catch All" Messages

Message	`Unexpected {ERROR} at {location}`
Description	You should rarely, if ever, see this message. It is returned when an error occurred that wasn't anticipated or otherwise handled.
Resolution	Try to find a consistently reproduceable example and contact Dyalog support.

Message	`Invalid HttpCommand setting(s): {setting name(s)}`
Description	You passed a namespace argument `New`, `Get`, `GetJSON`, or `Do` or as a constructor argument to `⎕NEW` and that namespace contained named elements that are not valid `HttpCommand` setting names.
Resolution	Remove the named elements that are not `HttpCommand` setting names.

Message	`Stopped for debugging... (Press Ctrl-Enter)`
Description	This message is not returned in the result namespace, but is displayed when you have set `Debug←2` and `HttpCommand` has stopped intentionally just prior to establishing the connection to the host.
Resolution	Pressing Ctrl-Enter will open the debugger and trace into `HttpCommand`. Entering `→⎕LC+1 will resume execution.`

Non-Conga Setting Messages

These messages report problems with settings that prevent HttpCommand from creating a proper HTTP request to send to the host.

Message	`No URL specified`
Description	You didn't specify a `URL` setting.
Resolution	Specify a valid `URL`.

Message	`URL is not a simple character vector`
Description	The `URL` setting isn't a simple character vector.
Resolution	Make sure `URL` isn't nested or non-character.

Message	`Invalid host/port: {host}`
Description	You specified a URL that has a hostname followed by a colon (`':'`) followed by something that does not parse as an integer. For example: `'dyalog.com:ducky'`
Resolution	Correct (or omit) the bad port specification.

Message	`No host specified`
Description	`HttpCommand` couldn't find a host in the `URL` setting.
Resolution	Ensure your `URL` conforms to the specification.

Message	`Invalid port: {port}`
Description	The port you specified is not in the range 1-63535.
Resolution	Specify an integer port number in the range 1-65535.

Message	`Invalid protocol: {protocol}`
Description	`HttpCommand` thinks you've specified a protocol other than `'http://'` or `'https://`.
Resolution	`HttpCommand` supports only the HTTP and HTTPS protocols. If you have not specified the protocol in your `URL` setting, `HttpCommand` will default to use HTTP. HTTPS will be used if you've specified either the default secure port (443) or supplied certificate information.

Message	`Cookies are not character`
Description	`Cookies` are specified as name/value pairs. All of the names and values need to be character.
Resolution	Make sure `Cookies` names and values are character.

Message	`Headers are not character`
Description	`Headers` may be specified as name/value pairs. All of the names and values need to be character.
Resolution	Make sure `Headers` names and values are character.

Message	`Improper header format`
Description	You used a value for `Headers` that did not conform to one of the formats described in the `Headers` specification.
Resolution	Ensure that `Headers` conforms to the specification

Message	`Output file folder {foldername} does not exist.`
Description	The folder in your {OutFile} setting does not exist. `HttpCommand` will create the output file, if necessary, in an existing folder but `HttpCommand` will not create a new folder.
Resolution	Either create the folder or change the `OutFile` setting.

Message	`No filename specified in OutFile or URL`
Description	If you do not specify a file name in `OutFile`, `HttpCommand` will attempt to use the file name specified in `URL`. However, if there is also no file name in `URL`, you will receive this message.
Resolution	Specify a file name in either `OutFile` or `URL`.

Message	`Output file "{OutFile}" is not empty`
Description	You specified the name of an existing, non-empty, file in `OutFile` but did not specify to overwrite or append to the file.
Resolution	Either specify a filename of a file that doesn't exist or is empty, or specify that the file is to be overwritten or appended to.

Conga Setting Messages

The messages in this section are related to the Conga settings in HttpCommand, not the actual execution of Conga code whose messages are described in "Conga Execution"-Related Messages.

Message	`CongaRef {CongaRef} does not point to a valid instance of Conga`
Description	You specified a `CongaRef` setting that is not the name of, or a reference to, the `Conga` or the `DRC`namespace.
Resolution	Check that `CongaRef` is actually the name of, or a reference to, the `Conga` or the `DRC`namespace.

Message	`{location}.{namespace} does not point to a valid instance of Conga`
Description	`HttpCommand` searches for the Conga API according to these rules and found a namespace named either `Conga` or `DRC`, but that namespace is not a valid Conga namespace.
Resolution	Either set `CongaRef` to point to a proper `Conga` or `DRC` namespace, or remove/rename the offending namespace.

Message	`CongaPath "{CongaPath}" does not exist`
Description	You specified a `CongaPath` that could not be found.
Resolution	Set `CongaPath` to the name of an existing folder containing the Conga shared libraries, or do not set `CongaPath` and let `HttpCommand` use the Dyalog installation folder.

Message	`CongaPath "{CongaPath}" is not a folder`
Description	You specified a `CongaPath` that exists, but is not a folder.
Resolution	Set `CongaPath` to the name of an existing folder containing the Conga shared libraries, or do not set `CongaPath` and let `HttpCommand` use the Dyalog installation folder.

Message	`{Conga API} was copied from {path}, but is not valid`
Description	`HttpCommand` was able to copy either the `Conga` or the `DRC` namespace according to the procedure described in Conga Default Behavior, but the namespace was not a valid Conga API.
Resolution	Ensure that conga workspace from which `HttpCommand` attempted to copy the Conga API is proper and the same version as the shared libraries. See Integrating `HttpCommand`.

Message	`Neither Conga nor DRC were successfully copied`
Description	`HttpCommand` was unable to copy either the `Conga` or the `DRC` namespace according to the procedure described in Conga Default Behavior.
Resolution	The most likely cause is that there is no conga workspace in the paths from which `HttpCommand` tried to copy. See Integrating `HttpCommand`.

Message	`Not found PublicCertFile "{PublicCertFile}"` `Not found PrivateKeyFile "{PrivateKeyFile}"` `Not found PublicCertFile "{PublicCertFile}" and PrivateKeyFile "{PrivateKeyFile}"`
Description	One or both of the file names you specified for `PublicCertFile` and `PrivateKeyFile` does not exist.
Resolution	Set `PublicCertFile` and `PrivateKeyFile` to the names of certificate files that actually exist.

Message	`PublicCertFile is empty` `PrivateKeyFile is empty`
Description	You have specified one of `PublicCertFile` or `PrivateKeyFile`, but not the other.
Resolution	Be sure to set both `PublicCertFile` and `PrivateKeyFile`.

Message	`Invalid certificate parameter`
Description	You specified a value for `Cert` that is not a valid instance of Conga's `X509` class.
Resolution	Make sure that `Cert is a valid instance of the X509 class.`

Message	`Unable to decode PublicCertFile "{PublicCertFile}" as certificate`
Description	An error occurred when Conga attempted to use `X509Cert.ReadCertFromFile` with the value you specified for `PublicCertFile`.
Resolution	Make sure `PublicCertFile` contains a valid certificate. See the Conga User Guide for more information.

Conga Execution Messages

The messages in this section are returned when Conga returns a non-zero return code, or an unexpected Conga event occurs. If there is a non-zero return code from Conga, it is returned in rc.

HttpCommand uses Conga's "HTTP" mode, where Conga will parse the response from the host. Some of the messages occur when the host sends an ill-formed response and Conga cannot parse it as HTTP. The ill-formed data is returned in the Data element of HttpCommand's result namespace.

Message	`Could not initialize Conga due to...`
Description	Conga could not be initialized for one of many reasons. The remainder of the message should give some indication as to what the problem was. Examples of problems include: the `Conga` or `DRC` namespace that `HttpCommand` found is not a valid Conga interface. the `CongaPath` setting does not point to an existing folder containing the Conga shared libraries. `HttpCommand` was unable to find a valid `Conga` or `DRC` namespace and could not copy either from the `conga` workspace.
Resolution	The resolution will depend on the circumstances described in the message. The Conga User Guide and/or the Integrating `HttpCommand`section could be helpful here.

Message	`Conga client creation failed...`
Description	This will occur if Conga is not able to create a client connection to the host. The remainder of the message will indicate the specific Conga error message.
Resolution	The resolution will depend on the circumstances described in the message. See the Conga User Guide.

Message	`Conga could not parse the HTTP response`
Description	The response from the host is not a properly formatted HTTP message.
Resolution	Inspect the data returned by the host in the `Data` element of the result.

Message	`Response payload not completely received`
Description	This occurs when `HttpCommand` was able to receive and parse the HTTP headers from the host but, during the receipt of the response payload, an error occurred.
Resolution	Attempt the request again. If the error persists, examine the headers and payload data, if any, returned by the host.

Message	`Conga error processing your request: {Conga return code}`
Description	Conga encountered some error that wasn't otherwise diagnosed or trapped.
Resolution	See the Conga User Guide for guidance.

Message	`Socket closed by server`
Description	During processing of the request, the server unexpectedly closed the connection to `HttpCommand`.
Resolution	Check that your request is proper for the host. See the Troubleshooting guide.

Message	`Unhandled Conga event type: {Conga event}`
Description	This should never occur, but for the sake of paranoia, we coded for the possibility of a Conga event that we didn't anticipate.
Resolution	Try to find a consistently reproduceable example and contact Dyalog support.

Message	`Conga wait error: {Conga return code}`
Description	An error occurred while Conga was waiting for a response from the host.
Resolution	Re-attempt the request. Examine any data or headers that may have been received for clues.

Message	`Could not set DecodeBuffers on Conga client "{Conga client name}": {Conga return code}`
Description	This is another error that should never occur.
Resolution	Try to find a consistently reproduceable example and contact Dyalog support.

Message	`Conga failed to parse the response HTTP header`
Description	Conga received an HTTPHeader event but was unable to parse the received data as HTTP headers.
Resolution	The unparseable data is returned in the `Data` element of the result namespace and may provide insight as to the problem.

Message	`Conga failed to parse the response HTTP chunk`
Description	Conga received an HTTPChunk event but was unable to parse the received data as an HTTP chunk.
Resolution	The unparseable data is returned in the `Data` element of the result namespace and may provide insight as to the problem.

Message	`Conga failed to parse the response HTTP trailer`
Description	Conga received an HTTPTrailer event but was unable to parse the received data as an HTTP trailer.
Resolution	The unparseable data is returned in the `Data` element of the result namespace and may provide insight as to the problem.

Message	`Conga error while attempting to send request: {Conga return code}`
Description	Conga was able to establish a connection to the host, but encountered an error when attempting to send the HTTP request.
Resolution	Examine the request being sent as described in the Troubleshooting guide. The Conga User Guide may also be helpful.

Message	`Unable to set EventMode on Conga root`
Description	This is another message that should never occur.
Resolution	Try to find a consistently reproduceable example and contact Dyalog support.

Operational Messages

Message	`{ERROR} while trying to initialize output file "{OutFile}"`
Description	You specified an `OutFile` setting and an error occured while trying to initialize the file.
Resolution	{ERROR} should provide information that will help determine the resolution.

Message	`Response header size exceeds BufferSize {BufferSize}`
Description	The size of the response's HTTPHeader message exceeded the value set for `BufferSize.`
Resolution	`BufferSize` is intended to help counteract maliciously large message headers. If the response headers are expected to be very large, increase the value of `BufferSize`.

Message	`Payload length exceeds MaxPayloadSize`
Description	The `content-length` header in the response had a value that exceeded the `MaxPayload` setting.
Resolution	`MaxPayloadSize` is intended to help counteract maliciously large messages. If the response payload is expected to be very large, increase the value of `MaxPayloadSize`

Message	`Request timed out before server responded`
Description	The host did not respond within the number of seconds specified in the `Timeout` setting.
Resolution	If you expect the host to be slow in responding, increase the magnitude of the `Timeout` setting.

Message	`Redirection detected, but no "location" header supplied.`
Description	The host responded with a 3XX HTTP status (redirection), but the response did not contain a `location` header indicating where to redirect the request.
Resolution	This is a server-side problem.

Message	`Too many redirections ({MaxRedirections})`
Description	The host sent more 3XX HTTP status responses (redirections) than `MaxRedirections` specified.
Resolution	`MaxRedirections` is intended to prevent redirection loops or too many redirection hops. If the redirections are legitimate, increase the value of `MaxRedirections`.

Message	`Could not translate XML payload`
Description	If you specify `TranslateData←1` and the response content-type header contains `'text/xml'` or `'application/xml'`, `HttpCommand` will attempt to use `⎕XML` to translate the payload. If `⎕XML` fails, this message is returned and `rc` is set to `¯2`.
Resolution	This is probably due to the response payload containing incorrectly formatted XML. The untranslated payload is returned in `Data`.

Message	`Could not translate JSON payload`
Description	If you specify `TranslateData←1` or use the `GetJSON` shared method and the response content-type header contains `'application/json'`, `HttpCommand` will attempt to use `⎕JSON` to translate the payload. If `⎕JSON` fails, this message is returned and `rc` is set to `¯2`.
Resolution	This is probably due to the response payload containing incorrectly formatted JSON. The untranslated payload is returned in `Data`.

Message	`Response content-type is not application/json`
Description	You used `GetJSON` and the response content-type header is not `'application/json'`. `rc` is set to `¯2` and `Data` contains the response payload.
Resolution	`GetJSON` expects the response content-type to be `'application/json'`. If the host is expected to return some other content-type, consider using a method other than `GetJSON`.

Informational Messages

These messages are issued to inform you that, while there was no actual error,

Message
Description
Resolution

Message	`Connection properties changed, connection reset`
Description	Unless otherwise specified, an instance of `HttpCommand` will attempt to keep the connection for the last request open. If any of the connection properties change on a subsequent request, the old connection closed and a new connection is established.
Resolution	No resolution necessary.

Message	`Unhandled content-encoding: {content-encoding}`
Description	This message occurs if the response's content-encoding header is something other than `'gzip'` or `'deflate'`.It is intended to inform you that `HttpCommand` did not automatically decode the payload.
Resolution	Your application will need to decode the payload.

Other Messages

These messages are not found in the msg element of result namespace, but are issued when using other features of HttpCommand.

Message	`Could not ⎕FIX file: {ERROR}{: Message}`
Description	The `Fix` method was not able to `⎕FIX` the file content returned as the response payload.
Resolution	Ensure that the requested file contains `⎕FIX`-able contents.

Message	`Could not ⎕FIX new HttpCommand: {ERROR}{: Message}`
Description	The `Upgrade` method was not able to `⎕FIX` a newer `HttpCommand`.
Resolution	See `Upgrade`. If the problem persists, contact Dyalog support.

Message	`Upgraded to {new-version} from {old-version}`
Description	The `Upgrade` method was able to `⎕FIX` a newer version of `HttpCommand`.
Resolution	See `Upgrade`.

Message	`Already using the most current version {version}`
Description	The `Upgrade` method did not find a newer version of `HttpCommand`.
Resolution	See `Upgrade`.