# set

The `set` statement is used to configure a setting for use by a subsequent [http](http) or [buffer](buffer) statements.

## Syntax

**`set`**_`setting value`_

## Details

A protocol such as [http](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_username`**_`username`_

**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_password`**_`password`_

**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_authtype`**_`type`_

**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_authtarget`**_`target`_

**Persistent**. Specifies whether any authentication configured using the `http_authtype` setting should be performed against a proxy or the hostname specified in the [http](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_.

{% hint style="info" %}
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
{% endhint %}

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](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](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.

{% hint style="warning" %}
Headers are not verified as sane until the next HTTP connection is made
{% endhint %}

### http\_body

**`set http_body data`**_`string`_ - use the specified string as the body of the request

**`set http_body file`**_`filename`_ - 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.

{% hint style="info" %}
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.
{% endhint %}

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_savefile`**_`filename`_

**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](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.

{% hint style="info" %}
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.
{% endhint %}

### http\_savemode

**`set http_savemode`**_`mode`_

**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_timeout`**_`seconds`_

**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
```

{% hint style="info" %}
The minimum allowable timeout is 1 second.
{% endhint %}

### odbc\_connect

**`set odbc_connect`**_`connection_string`_

**Persistent**. Sets the ODBC connection string for use by the [buffer](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.

{% hint style="info" %}
Please refer to the documentation for the database to which you wish to connect to ensure that the connection string is well formed.
{% endhint %}

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"
```
