Instance Methods

The methods documented in this section are instance methods and may be called from an instance of HttpCommand. In the documentation below, we will use the name instance to represent an instance of HttpCommand.

Run

Run "runs" the HTTP request defined by the instance's settings. Run is called internally by the shared "shortcut" methods Get, GetJSON, and Do.

Syntax	result←instance.Run
result	result depends on the RequestOnly setting. If RequestOnly=1, Run will return, if possible, the HTTP request that would be sent if RequestOnly was set to 0. If HttpCommand cannot form a proper HTTP request, Run will return a result namespace with pertinent information. If RequestOnly=0, Run will return a result namespace containing the result of attempting to build and send the HTTP request specified by the instance's settings.
Examples	instance←HttpCommand.New '' instance.RequestOnly←1 There isn't sufficient information for HttpCommand to build a proper HTTP request. ⊢result ← instance.Run [rc: ¯1 | msg: No URL specified | HTTP Status: "" | ⍴Data: 0] instance.URL←'dyalog.com' Now, there's enough information to form a proper HTTP request. ⊢result ← instance.Run GET / HTTP/1.1 Host: dyalog.com User-Agent: Dyalog-HttpCommand/5.0.3 Accept: */* instance.RequestOnly←0 ⊢result ← instance.Run [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 23127]

Show

Returns the HTTP request that HttpCommand would send when Run is executed and RequestOnly is 0. Show is equivalent to setting RequestOnly to 1 and running Run.

Syntax	r←instance.Show
Example	instance ← HttpCommand.New 'get' 'dyalog.com' instance.Show GET / HTTP/1.1 Host: dyalog.com User-Agent: Dyalog-HttpCommand/5.0.3 Accept: */*

Config

Config returns the current state of all HttpCommand settings.

Syntax	r←instance.Config
r	A 2-column matrix where [;1] contains the setting names [;2] contains the corresponding setting values
Example	instance←HttpCommand.New 'get' 'dyalog.com' instance.Config Auth AuthType BufferSize 200000 Cert Command get CongaPath CongaRef CongaVersion ContentType Cookies Debug 0 Headers KeepAlive 1 LDRC not set MaxPayloadSize ¯1 MaxRedirections 10 OutFile Params Priority NORMAL:!CTYPE-OPENPGP PrivateKeyFile PublicCertFile RequestOnly 0 Secret 1 SSLFlags 32 SuppressHeaders 0 Timeout 10 TranslateData 0 URL dyalog.com WaitTime 5000

Init

Init initializes Conga, Dyalog's TCP/IP utility library. Normally, HttpCommand will initialize Conga when Run is first called. Init is intended to be used when the user wants to "tweak" Conga prior to Run being executed. It's very unlikely that you'll ever need to use Init.

Syntax	r←instance.Init
r	a 2-element vector of [1] the return code. 0 means Conga is initialized. Non-0 indicates some error occurred in Conga initialization. [2] a message describing what went wrong if the return code is not 0
Example	instance←HttpCommand.New '' instance.CongaPath←'/doesnotexist' instance.Init ¯1 CongaPath "c:/doesnotexist/" does not exist

Header-related Methods

There are two sets of headers associated with an HTTP request - the request headers and the response headers. The methods described here deal with request headers.

HttpCommand's request headers are stored in the Headers setting which is a 2-column matrix of name/value pairs. Header names are case-insensitive; header values are not. While you can manipulate the Headers array directly, HttpCommand has three methods to manage Headers that accommodate the case-insensitive nature of header names.

By default, HttpCommand will automatically generate several request headers if you haven't specified values for them. See SuppressHeaders for the list of these headers. To suppress the generation of specific headers, you can set its value to ''.

You may specify that HttpCommand should substitute the value of an environment variable in a header name or value by surrounding the name of the environment variable with %. For example:

      1 HttpCommand.Get 'someurl.com' '' ('MyHeader' '%DYALOG%')
GET / HTTP/1.1
MyHeader: C:\Program Files\Dyalog\Dyalog APL-64 19.0 Unicode
Host: someurl.com
User-Agent: Dyalog-HttpCommand/5.5.0
Accept: */*
Accept-Encoding: gzip, deflate

Note: The examples below were run using ]boxing on.

AddHeader

AddHeader will add a header if a user-defined header with that name does not already exist. Use SetHeader to set a header regardless if one with the same name already exists.

Syntax	{hdrs}←name instance.AddHeader value
value	the value for the header
name	the name for the header
hdrs	the updated matrix of user-specified headers
Example	instance←HttpCommand.New '' 'My-Header' instance.AddHeader 'Drake Mallard' instance.Headers ┌─────────┬─────────────┐ │My-Header│Drake Mallard│ └─────────┴─────────────┘ AddHeader will not replace an existing header with the same case-insensitive name 'my-header' instance.AddHeader 'Daffy Duck' instance.Headers ┌─────────┬─────────────┐ │My-Header│Drake Mallard│ └─────────┴─────────────┘ Setting the value of an HttpCommand-generated header that to '' will suppress that header from being sent in the request. 'accept-encoding' instance.SetHeader ''

SetHeader

SetHeader will set a header, replacing one of the same name if it already exists.

Syntax	{hdrs}←name instance.SetHeader value
value	the value for the header
name	the name for the header
hdrs	the updated matrix of user-specified headers
Example	instance←HttpCommand.New '' ⊢'My-Header' instance.SetHeader 'Drake Mallard' ┌─────────┬─────────────┐ │My-Header│Drake Mallard│ └─────────┴─────────────┘ SetHeader will replace an existing header with the same case-insensitive name ⊢'my-header' instance.SetHeader 'Daffy Duck' ┌─────────┬──────────┐ │My-Header│Daffy Duck│ └─────────┴──────────┘ Setting the value of an HttpCommand-generated header that to '' will suppress that header from being sent in the request. 'accept-encoding' instance.SetHeader ''

RemoveHeader

RemoveHeader removes a user-specified header. If the header does not exist, RemoveHeader has no effect. RemoveHeader does not affect the HttpCommand-generated headers.

Syntax	{hdrs}←instance.RemoveHeader name
name	the case-insensitive name of the header to remove
hdrs	the updated matrix of user-specified headers
Example	'My-Header' instance.SetHeader 'Daffy Duck' 'another' instance.SetHeader 'some value' instance.Headers ┌─────────┬──────────┐ │My-Header│Daffy Duck│ ├─────────┼──────────┤ │another │some value│ └─────────┴──────────┘ instance.RemoveHeader 'my-header' instance.Headers ┌───────┬──────────┐ │another│some value│ └───────┴──────────┘