Skip to content

Operational Settings

Operational settings affect how HttpCommand behaves.

Instance settings

KeepAlive

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.

MaxPayloadSize

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.

MaxRedirections

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.

Outfile

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.

RequestOnly

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.

Secret

Description If set to 1, HttpCommand will suppress the display of credentials in the Authorization header, instead replacing them with >>> Secret setting is 1 <<<. This applies when using the Show or Config methods or setting RequestOnly to 1. Secret will not affect the request that is actually sent to the host.
Default 1
Example(s) 
      h←HttpCommand.New 'get' 'userid:password@someurl.com'
      h.Show
GET / HTTP/1.1
Host: someurl.com
User-Agent: Dyalog-HttpCommand/5.5.0
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: >>> Secret setting is 1 <<<

      h.Secret←0
      h.Show
GET / HTTP/1.1
Host: someurl.com
User-Agent: Dyalog-HttpCommand/5.5.0
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Basic dXNlcmlkOnBhc3N3b3Jk
Details This setting is useful when doing an HttpCommand demonstration as it will avoid inadvertently displaying credentials in the APL session.

SuppressHeaders

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.

Timeout

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.

TranslateData

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

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

Debug

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]