set
Last updated
Last updated
The set statement is used to configure a setting for use by a subsequent http or buffer statements.
setsetting value
A protocol such as http offers a number of configuration options. Any given option is either persistent or transient:
The following settings can be configured using set:
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.
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.
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.
set http_authtypetype
Persistent. Specifies the type of authentication required when initiating a new connection. The type parameter can be any of the following:
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
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
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.
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.
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.
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:
The minimum allowable timeout is 1 second.
set http_retry_countcount
Persistent. Sets the number of retries that will be made in case of transport-level failures, such as an inaccessible server or a name resolution issue. Server responses with non-200 HTTP code are not considered transport-level failures.
By default this option has a value of 1, which means one initial request and one retry. To disable retrying set the value to 0.
set http_retry_delaymilliseconds
Persistent. Set the pause between retries in milliseconds. Default value is 5000 milliseconds. Used only if http_retry_count is non-zero.
set http_redirect_countcount
Persistent. Set the maximum number to follow HTTP redirects. Valid values are in the range 0-32, where 0 disable redirects completely. By default redirects are disabled.
set http_secure yes|no
Persistent. Switches on or off several server HTTPS certificate validation check, such as:
certificate is issued by trusted CA (Certificate Authority) or certificate chain of trust can be traversed to trusted CA (list of trusted CAs is located in common/certificates/cacert.pem file within Exivity home directory)
server name matches the name in the certificate
Other certificate checks, such as certificate expiration date, cannot be disabled.
Starting from Exivity version 3 this option is switched on by default.
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:
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
Value
Meaning
none (default)
no authentication is required or should be used
basic
use basic authentication
ntlm
use NTLM authentication
digest
use digest authentication