Operational Settings

Operational settings affect how HttpCommand behaves.

Instance settings

Description	A Boolean which indicates whether `HttpCommand` close the client connection after receiving the response from the host. `1` = keep connection alive `0` = close connection
Default	`1`
Example(s)	`h.KeepAlive←0 ⍝ close the connection`
Details	`KeepAlive` is only applicable when you persist an instance of `HttpCommand` and has no effect when you use the shortcut methods `Get`, `GetJSON`, or `Do` as these methods destroy the `HttpCommand` instance they create when they finish execution. HTTP version 1.1 specifies that connections should be kept alive to improve throughput. Nevertheless, a host may close the connection after sending the response or after a period of inactivity from the client (`HttpCommand`). If the connection is closed, `HttpCommand` will open a new connection on a subsequent request.

Description	The maximum response payload size that `HttpCommand` will accept. `¯1` = no maximum `≥0` = maximum size
Default	`¯1`
Example(s)	`h.MaxPayloadSize←100000 ⍝ set a 100,000 byte limit`
Details	If `MaxPayloadSize` is set to a value `≥0` and the response contains a payload, `HttpCommand` checks the payload size as follows: If the response contains a `content-length` header, its value is compared to `MaxPayloadSize`. If exceeded, `HttpCommand` will return with a return code of `¯1` and no payload. Otherwise, the response payload is sent in chunks and `HttpCommand` will accumulate each chunk and compare the total payload size to `MaxPayloadSize`. If exceeded, `HttpCommand` will return with a return code of `¯1` and whatever payload has been accumulated. In either case, if `MaxPayloadSize` is exceeded, the client connection will be closed.

Description	The maximum number of redirections that `HttpCommand` will follow. A setting of `¯1` means there is no limit to the number of redirections followed; exposing the possibility of an infinite redirection loop and eventually a `WS FULL` error. A setting of `0` means no redirections will be followed.
Default	`10`
Example(s)	`h.MaxRedirections←0 ⍝ do not follow any redirections`
Details	If the response HTTP status indicates a redirection (3XX) to another URL, `HttpCommand` will retain information about the current request in the `Redirections` element of the result namespace and issue a new request to the new URL. `HttpCommand` will do this up to `MaxRedirections` times.

Description	`Outfile` has up to 2 elements: `[1]` The name of the file or folder to which `HttpCommand` will write the response payload. If a folder is specified, the file name will be the same as the resource specified in `URL`. `[2]` an optional flag indicating: `0` do not write to an existing, non-empty file (the default) `1` replace the contents, if any, if the file exists `2` append to the file, if it exists
Default	`'' 0`
Example(s)	`c ← HttpCommand.New ''` `c.URL←'https://www.dyalog.com/uploads/files/student_competition/2022_problems_phase2.pdf'` `c.OutFile←'/tmp/'` `c.Run` `[rc: 0 \| msg: \| HTTP Status: 200 "OK" \| 399766 bytes written to c:/tmp/2022_problems_phase2.pdf]` `c.OutFile←'/tmp/problems.pdf' 1` `c.Run` `[rc: 0 \| msg: \| HTTP Status: 200 "OK" \| 399766 bytes written to c:/tmp/problems.pdf]`
Details	Output to file is subject to `MaxPayloadSize`.

Description	If set to 1, `HttpCommand` will return the character vector HTTP request that would be sent, instead of actually sending the request.
Default	`0`
Example(s)	`h.RequestOnly←1`
Details	This setting is useful for debugging a request that isn't behaving as you expect. Setting optional left argument of shared methods `Get`, `GetJSON`, `Do`, or `New` to `1` will have the same effect as setting `RequestOnly` as will the instance method `Show`.

Description	`SuppressHeaders` is a Boolean setting indicating whether `HttpCommand` should suppress the generation of its default HTTP headers for the request. `1` - suppress the default headers `0` - generate the default headers
Default	`0` which means `HttpCommand` will generate its default headers
Example(s)	`h.SuppressHeaders←1`
Details	`HttpCommand` will only generate headers that you have not specified yourself. `HttpCommand` generates the following default headers: `Host` - the host name in the URL. This header must be supplied. `User-Agent: Dyalog-HttpCommand/<version>` `Accept: /` By default, `HttpCommand` will accept any response type `Accept-Encoding: gzip, deflate` By default, `HttpCommand` will accept compressed response payloads `Authorization` set only if you provide HTTP Basic authentication credentials, or set `Auth` and `AuthType` `Cookie` - any saved cookies applicable to the request. `Content-Type` is conditionally set as described here Setting `SuppressHeaders←1` will suppress ALL `HttpCommand`-generated headers which means you will need to specify any necessary request headers yourself. Individual headers can be suppressed by using the `SetHeader` instance method and assigning the header a value of `''`. Note: Conga will always insert a `Content-Length` header for any request that has a payload.

Description	The number of seconds that `HttpCommand` will count down to wait for a response from the host. If `Timeout` is positive, `HttpCommand` will exit with a return code of 100 (Timeout) if it has not received the complete response from the host before the countdown reaches 0. If `Timeout` is negative, `HttpCommand` will check if Conga has received any data and if so, will reset the countdown to `\|Timeout`.
Default	`10`
Example(s)	h.Timeout←30
Details	This is the setting to adjust (and not `WaitTime`) if your request is timing out. See Timeout and WaitTime for more information on the relationship between the `Timeout` and `WaitTime` settings.

Description	Set this to `1` to have `HttpCommand` attempt to convert the response payload for the following content types. `'application/json'` - `HttpCommand` will use `⎕JSON` `'text/xml'` or `'application/xml' - HttpCommand will use ⎕XML`
Default	`0`
Example(s)	`c←HttpCommand.New 'get' 'https://api.github.com/users/dyalog' c.TranslateData←0 50↑(⎕←c.Run).Data [rc: 0 \| msg: \| HTTP Status: 200 "OK" \| ⍴Data: 1306] {"login":"Dyalog","id":4189495,"node_id":"MDEyOk9y c.TranslateData←1 (⎕←c.Run).Data [rc: 0 \| msg: \| HTTP Status: 200 "OK" \| ⍴Data: ⍬] #.[JSON object]`

Shared settings are set in the HttpCommand class and are used by all instances of HttpCommand.

Description	Set `Debug` to 1 to turn off `HttpCommand`'s error trapping. In this case if an error occurs, execution of `HttpCommand` will be suspended. Set `Debug` to 2 to have `HttpCommand` stop just before sending the request to the host so that you can examine the request and `HttpCommand`'s current state. Both of these settings can be useful for debugging.
Default	`0`
Example(s)	`c←HttpCommand.New 'get' 'https://api.github.com/users/dyalog'` `c.OutFile←0` `c.Debug←1` `c.Run` `DOMAIN ERROR: Invalid file or directory name` `HttpCmd[130] outFile←∊1 ⎕NPARTS outFile` `∧` `c.Debug←0` `c.Run` `[rc: ¯1 \| msg: DOMAIN ERROR while trying to initialize output file '0' \| HTTP Status: "" \| ⍴Data: 0]`