`session` (Set session parameters)

Under certain circumstances it may be useful to adjust how queries use system resources such as processing power and virtual memory. The session transaction provides a means to specify such settings.

Query string

The query string in the HTTP header must contain the following parameters:

api

Specify the name of the API transaction.

apiversion

Specify the version of the API that should handle the requested transaction.

For the most up-to-date version, use apiversion=3.

uid

Specify a valid 1010data user name.

pswd

Specify a valid password for the 1010data user name provided to the uid parameter.

Note: The pswd value should be the encrypted password returned from the login transaction.

sid

The session ID for the current API session.

This value is returned by the login transaction and must be provided to every transaction (except login).

kill (optional)

Valid values for kill are as follows:

yes: Terminate the existing session and start a new one.
no: Do not terminate the existing session.
If no session exists, a new one will be created. If a session does exist, an error is returned.

Note: If kill=no and a session is active, the system returns an error.
possess: Log in and possess the existing session.
auth: Authenticate with the system but do not kill, possess, or start any session.

The default is yes.

XML input to server

The specifications must contain the following elements:

<inf2na>

Accepts the values on to activate and off to disable. If active, this feature reduces or eliminates the number of errors and/or infinity values returned from computations resulting in such values. In cases when infinity values are generated, they will be turned into N/A values instead. Here are some things to keep in mind when deciding whether to use <inf2na>:

Division by zero (X/0) returns 0i or -0i if the numerator is not zero.
Checking this box causes N/A to be returned instead of 0i and -0i.
Exponentiation (X^Y) can generate error messages if X is negative.
Checking this box mostly eliminates such messages and causes N/A to be returned in the event of an error.
The range functions (range1, range1f, etc.) return 0I, -0I, 0i, or -0i for column values that lie outside the specified ranges.

<stepwise> (optional)

Accepts the values on to activate and off to deactivate. Stepwise aggregation can be used to save memory for the session. While memory is saved, queries may run more slowly. Should only be used when experiencing issues with virtual memory when working with large tables.

<blocking>(optional)

Accepts an integer value between 0 and 10. Specifies whether to break selections and tabulations into sections to reduce memory usage when working with large tables. Should be set lower when virtual memory issues are experienced.

XML response from server

A successful session contains the following elements:

<rc>: The return code generated by the transaction. For a list of return codes, see Return codes.
<msg>: The message returned by the system. Specific messages correspond to specific return codes.

Query string example

https://www2.1010data.com/gw.k?api=session&apiversion=3&uid=$UID&pswd=$PSWD&sid=$SID

XML input example

<in>
    <inf2na>on</inf2na>
    <stepwise>off</stepwise>
    <blocking>0</blocking>
</in>

XML response example

<out>
  <rc>0</rc>
  <msg>Session parameters set</msg>
</out>

session (Set session parameters)