set

Last updated last month

The set statement is used to configure a setting for use by a subsequent http or buffer statements.

Syntax

setsetting value

Details

A protocol such as http offers a number of configuration options. Any given option is either persistent or transient:

Type

Meaning

Persistent

The setting remains active indefinitely and will be re-used over successive HTTP calls

Transient

The setting only applies to a single HTTP call, after which it is automatically reset

The following settings can be configured using set:

http_progress

set http_progress yes|no

Persistent. If set to yes then dots will be sent to standard output to indicate that data is downloading when an HTTP session is in progress. When downloading large files if a lengthy delay with no output is undesirable then the dots indicate that the session is still active.

http_username

set http_usernameusername

Persistent. Specifies the username to be used to authenticate the session if the http_authtype setting is set to anything other than none. If the username contains any spaces then it should be enclosed in double quotes.

http_password

set http_passwordpassword

Persistent. Specifies the password to be used to authenticate the session if the http_authtype setting is set to anything other than none. If the password contains any spaces then it should be enclosed in double quotes.

http_authtype

set http_authtypetype

Persistent. Specifies the type of authentication required when initiating a new connection. The type parameter can be any of the following:

Value

Meaning

none (default)

no authentication is required or should be used

basic

use basic authentication

ntlm

use NTLM authentication

passport

use passport authentication

digest

use digest authentication

negotiate

automatically selects between NTLM and Kerberos authentication

http_authtarget

set http_authtargettarget

Persistent. Specifies whether any authentication configured using the http_authtype setting should be performed against a proxy or the hostname specified in the http URL.

Valid values for target are:

  • server (default) - authenticate against a hostname directly

  • proxy - authenticate against the proxy configured at the Operating System level

http_header

set http_header"name: value"

Persistent. Used to specify a single HTTP header to be included in subsequent HTTP requests. If multiple headers are required, then multiple set http_header statements should be used.

An HTTP header is a string of the form name: value.

There must be a space between the colon at the end of the name and the value following it, so the header should be enclosed in quotes

Example: set http_header "Accept: application/json"

Headers configured using set http_header will be used for all subsequent HTTP connections. If a different set of headers is required during the course of a USE script then the clear statement can be used to remove all the configured headers, after which set http_header can be used to set up the new values.

By default, no headers at all will be included with requests made by the http statement. For some cases this is acceptable, but often one or more headers need to be set in order for a request to be successful.

Typically these will be an Accept: header for GET requests and an Accept: and a Content-Type: header for POST requests. However there is no hard and fast standard so the documentation for any API or other external endpoint that is being queried should be consulted in order to determine the correct headers to use in any specific scenario.

Headers are not verified as sane until the next HTTP connection is made

http_body

set http_body datastring - use the specified string as the body of the request

set http_body filefilename - send the specified file as the body of the request

set http_body{named_buffer} - send the contents of the named buffer as the body of the request

Transient. By default no data other than the headers (if defined) is sent to the server when an HTTP request is made. The http_body setting is used to specify data that should be sent to the server in the body of the request.

When using http_body a Content-Length: header will automatically be generated for the request. After the request this Content-Length: header is discarded (also automatically). This process does not affect any other defined HTTP headers.

After the request has been made the http_body setting is re-initialised such that the next request will contain no body unless another set http_body statement is used.

http_savefile

set http_savefilefilename

Transient. If set, any response returned by the server after the next HTTP request will be saved to the specified filename. This can be used in conjunction with the buffer statement, in which case the response will both be cached in the named buffer and saved to disk.

If no response is received from the next request after using set http_savefile then the setting will be ignored and no file will be created.

Regardless of whether the server sent a response or not after the HTTP request has completed, the http_savefile setting is re-initialised such that the next request will not cause the response to be saved unless another set http_savefile statement is used.

No directories will be created automatically when saving a file, so if there is a pathname component in the specified filename, that path must exist.

http_savemode

set http_savemodemode

Persistent.

  • If mode is overwrite (the default) then if the filename specified by the set http_savefile statement already exists it will be overwritten if the server returns any response data. If no response data is sent by the server, then the file will remain untouched.

  • If mode is append then if the filename specified by the set http_savefile statement already exists any data returned by the server will be appended to the end of the file.

http_timeout

set http_timeoutseconds

Persistent. After a connection has been made to a server it may take a while for a response to be received, especially on some older or slower APIs. By default, a timeout of 5 minutes (300 seconds) is endured before an error is generated.

This timeout may be increased (or decreased) by specifying a new timeout limit in seconds, for example:

set http_timeout 60 # Set timeout to 1 minute

The minimum allowable timeout is 1 second.

odbc_connect

set odbc_connectconnection_string

Persistent. Sets the ODBC connection string for use by the buffer statement's odbc_direct protocol. The connection string may reference an ODBC DSN or contain full connection details, in which case a DSN doesn't need to be created.

A DSN connection string must contain a DSN attribute and optional UID and PWD attributes. A non-DSN connection string must contain a DRIVER attribute, followed by driver-specific attributes.

Please refer to the documentation for the database to which you wish to connect to ensure that the connection string is well formed.

An example connection string for Microsoft SQL Server is:

set odbc_connect "DRIVER=SQL Server;SERVER=Hostname;Database=DatabaseName;TrustServerCertificate=No;Trusted_Connection=No;UID=username;PWD=password"