gettab (Get information about a table)

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:

<name>

The full name of a table. Table names are specified as a full path to the location of the table, e.g., directory1.directory2.directory[N].table.

<include> (optional)

This optional element provides facility for specifying which specific metadata elements about the directory should be returned. Provide a list of <name> elements containing the names of the metadata elements that should be returned (e.g., <name>ldesc</name>. See the XML Response section of this topic for a complete list of metedata elements that may be returned by the transaction.

<include> also contains the mode attribute.

Use mode="1" to return metadata for parent and child directories.

Use mode="2" to only return information about child directories.

XML response from server

A successful response from the server 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.

<tab>

Contains information about a table. The table's metadata is contained within attributes of the <tab> element.

The table metadata is returned as a series of attributes contained within the <tab> element. The attributes are as follows:

id

The id number of the table. Table id is represented as an integer value.

name

The full name of the table, represented as a path to the table.

type

Specifies the type of table. Possible return values are as follows:

• REAL
• VIEW
• PARAM
• MERGED
• UQ
• TOLERANT

display

The output type of the table. Possible return values are as follows:

• TABLE
• EXCEL
• CHART
• REPORT
• TEXT
• XML

report

A boolean flag indicating whether the table or query has report specifications saved. Returns 1 if there are saved specifications and 0 if there are no saved specifications.

chart

A boolean flag indicating whether the table or query has chart specifications saved. Returns 1 if there are saved chart specifications and 0 if there are no saved chart specifications.

title

The title of the table.

sdesc

The short description of the table.

ldesc

The long description of the table.

link

A string that will be prepended to table headers during a link.

rows

The number of rows in the table.

bytes

The number of bytes the table consumes on disk.

segs

The number of segments contained in the table.

tstat

Specifies whether the table can be accessed by time-series functions. If so, returns 1. If not, returns 0.

access

Specifies whether the table is accessible. If so, returns 1. If not, returns 0.

secure

Returns 1 if the directory, table, or query is marked as "secure" and 0 if it is not marked as "secure".

Note: This metadata element is still returned but has been deprecated.

own

Boolean flag specifying whether the UID used for the API transaction is the owner of the directory.

update

The date and time the directory's metadata was last modified. If it was created and never modified, returns the date and time the directory was created.

users

A space-separated list of users and groups whom are allowed to access this directory, table, or query.

maxdown

The maximum number of rows that can be downloaded from the table at a time.

favorite

Specifies whether the table is flagged as a favorite for the user ID making the request. Returns 1 if the table is a favorite and a 0 if it isn't.

If the table is a query (i.e., type is VIEW, PARAM, MERGED or TOLERANT) then the tab element will contain ops and dependencies elements. Any dependencies on other tables (i.e., links, merges) are available in the <dependencies> element, which contains a list of table references if the table is a Quick Query or a merged table.