TenDo: Managing connectivity

TenDo offers various connectivity options.

TenDo provides functionality for terminating sessions, keeping sessions alive, and connecting to 1010data from behind corporate proxy servers.

Kill an existing session

You may encounter a situation in which the account you use to connect to 1010data has already established a connection outside of your TenDo session. This could happen if you recently logged into 1010data via another interface and didn't log out, or if you use a shared account within your workgroup. If you try to send a query in TenDo while your account is already logged in, TenDo will return an error:
can't log in: rc=5 (Already logged in)
In this event, you will need to end the existing connection before TenDo can use the account to connect to 1010data. You do this by killing the existing session with the -k switch. This option doesn't take an argument and is called as follows:
$ tendo -k -u [USERNAME] [TABLE] @[QUERY]
This command will automatically disconnect your existing session and run your query via TenDo.

Connecting from a corporate proxy

If you connect to the internet from behind a corporate proxy server, you can tell TenDo to connect through the proxy. TenDo provides this functionality with the -P switch, followed by a space and the proxy information, formatted as follows:
$ tendo -u [USERNAME] -P http://[PROXYUSERNAME]:[PROXYUSERPASSWORD]
      @www.corporateproxyserver.com:8080 [TABLE] @[QUERY]
This command routes the TenDo connection through the specified proxy server, then connects to 1010data and runs your query as normal. If you do not know the correct proxy server information to provide, ask your network administrator. If you encounter the Transport error 7: Couldn't connect to server message, you need to add proxy credentials.
Note: Not all proxy servers require a user name and password. Check with your network administrator to find out exactly what information you need to connect via your company's proxy server.

Forced retry logic

Note: TenDo automatically sends HTTP keep-alive packets to 1010data, which usually prevents connection failures. The techniques in this section should only be used when a connection issue has been encountered.

Some queries take longer to finish running than others. Occasionally, a TenDo session will timeout while a query is running if the query is very large. This is especially true if you are behind a corporate proxy server. To help manage your connection and prevent unwanted timeouts from occurring, TenDo provides two useful options: -~ and --retries. You can use these options in unison to prevent timeouts from happening before your query finishes running.

First, let's look at the -~ option. This option takes any number greater than 300 as an argument. The argument is the number of seconds you want the system to wait before it retries the transaction. The number you specify for -~ should be lower than the time it takes your proxy server to cause a timeout. The -~ option is called in a TenDo command as follows:
$ tendo -u [USERNAME] [TABLE] @[QUERYFILE] -~ 400
This command tells TenDo to reestablish the transaction after 400 seconds. If a timeout has occurred, when TenDo retries the query, it will pick up where it left off at the time of the timeout. Note that we have not provided a number of times to retry. If you do not provide a number of retries using the --retries option, TenDo will default to 10 total attempts; the initial attempt and 9 retries.
If you need TenDo to retry more than 10 times, you can specify your retry preference with --retries. You can only use --retries if you have provided a retry duration with the -~ option, as follows:
$ tendo -u [USERNAME] [TABLE] @[QUERYFILE] -~ 400 --retries=15
This command tells TenDo to retry the query every 400 seconds for 15 consecutive attempts. If you multiply your specified retry interval by the number of retries you've specified, the product will be the total amount of time (in this case 6000 seconds or 1 hour and 40 minutes) before the transaction will timeout entirely. This is important because your total time before a complete timeout should roughly be as long as the maximum theoretical time it will take your query to run. You may need to experiment with your proxy server and your queries to find the optimal number.
Note: Queries make numerous "transactions" with 1010data when they are run. The retries option applies to each individual transaction in a query. This means that if your query makes one transaction with the system that times out twice before completing, the next transaction will start with a new set of retries, as specified in your command. Remember, 10 retries is the default. So, if you don't specify a number of retries, then every transaction in your queries will have 10 retries. If you specify 15, each transaction will have 15...etc.

SAM pools

If you access 1010data as part of a SAM pool, you need to use different login credentials than if you had your own, unique 1010data ID. SAM stands for: Shared Access Management. SAM pools are generally used to share a single set of login credentials with a larger pool of actual users. Specifying your SAM pool is done with the --pool switch in TenDo. It takes the [GROUP_NAME] as its only parameter. However, you will still need to pass TenDo a username and password, as follows:
$ tendo --pool=[GROUP_NAME] -u [GROUP_OWNER_NAME] -p [GROUP_OWNER_PASSWORD] [TABLE] @[QUERY]
This tells TenDo to login to 1010data with the first free account in the SAM pool. If no accounts are presently available, TenDo will return an error stating that the system is busy.