status (Status of the addtab API)

The status transaction reports the status of an asynchronous addtab transaction (an addtab command with <sync>0</sync>). The return code indicates the state of the load process.

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.

Query String Example

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

XML input to server

None.

XML response from server

A successful status produces the following result:

<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.
<numrecs>
The number of records written to the table so far. This information is returned if the addtab transaction is in the loading state.
XML Element Returned Description of Returned Element Content
<rc> Return code
<msg> Message from the server
<numrecs> Number of records written to the table so far

Reported if addtab is in the Loading state.
<totrecs> Estimate of the number of records in the source file

Possible return codes

  • 0 - Idle – Server is idle and has not started loading anything.
  • 1 - Failed – Server could not load file.
  • 2 - Initializing – Server is validating load specification. Loading has not commenced.
  • 3 - Loading – Server is in the process of loading a table. More tables cannot be loaded until it is complete.
  • 4 - Completed – Server has completed an loading the table.
  • 5 - Diagnosed – The server loaded the table but there were file format issues. The server attempted to automatically correct the issues.

XML Response Example

<rc>4</rc>
<msg>Completed</msg>

ASYNC load example

The following example shows the full async load process for large tables.

submit: 
https://www2.1010data.com/gw.k?api=addtab&apiversion=3&uid=$UID&pswd=$PSWD&sid=$SID
<in>
<spec>...</spec>
</in>

response: 
<out>
<rc>0</rc>
<msg>addtable started</msg>
<name>mycompany.mytable</name>
</out>

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

response: 
<out>
<rc>3</rc>
<msg>loading</msg>
<path>mycompany.mytable</path>
<transaction>load</transaction>
<state>started</state>
<numrecs>0</numrecs>
<ptr>0</ptr>
<totbytes>50291871</totbytes>
</out>

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

response: 
<out>
<rc>4</rc>
<msg>load succeeded</msg>
<path>mycompany.mytable</path>
<transaction>load</transaction>
<state>finished</state>
<totrecs>466869</totrecs>
</out>