Tryag File Manager

//proc/self/root/usr/share/doc/freetds-0.64/tds.html

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <meta name="GENERATOR" content="Mozilla/4.7 [en] (WinNT; I) [Netscape]">
 <title>TDS Protocol Documentation</title>
</head>

<body>
<H1>TDS Protocol Documentation</h1>

This document attempts to cover the TDS protocol for:

<table border=1>
	<tr><td align=center>TDS Version</td><td>Supported Products</td></tr>
	<tr><td align=center>4.2</td><td>Sybase SQL Server &lt; 10 and Microsoft SQL Server 6.5</td></tr>
	<tr><td align=center>5.0</td><td>Sybase SQL Server &gt;= 10</td></tr>
	<tr><td align=center>7.0</td><td>Microsoft SQL Server 7.0</td></tr>
	<tr><td align=center>8.0</td><td>Microsoft SQL Server 2000</td></tr>
</table>

Contents
 
<ul>
<li><a href="#terms">Common Terms</a>
<li><a href="#examples">Typical Usage Sequences</a>
<li><a href="#packet">The Packet Format</a>
<li><a href="#login">Login Packet</a>
<li><a href="#login7">TDS 7.0 Login Packet</a>
<li><a href="#collate">Collate structure</a>
<li><a href="#requests">Client requests</a>
<li><a href="#responses">Server Responses</a>
</ul>

<a name="terms"></a>
Common Terms
<pre>
TDS protocol versions
 TDS5 tds version 5.0
 TDS7 tds version 7.0
 TDS7+ tds version 7.0 and 8.0
 TDS5- tds version 5.0 and previous

Variable types used in this document:
 CHAR 8-bit char
 CHAR[6]	string of 6 chars
 CHAR[n] variable length string
 XCHAR single byte (TDS5-) or ucs2le (TDS7+) characters
 INT8 8-bit int
 INT16 16-bit int
 INT32 32-bit int
 UCS2LE Unicode in UCS2LE format
</pre>
Note: FreeTDS uses TDS_TINYINT for INT8 and TDS_SMALLINT for INT16.

<a name="examples"></a>
Typical Usage sequences
 
 
These are TDS 4.2 and not meant to be 100% correct, but
I thought they might be helpful to get an overall view 
of what goes on.
<pre>
--&gt; Login
&lt;-- Login acknowledgement

--&gt; INSERT SQL statement
&lt;-- Result Set Done

--&gt; SELECT SQL statement
&lt;-- Column Names
&lt;-- Column Info
&lt;-- Row Result
&lt;-- Row Result
&lt;-- Result Set Done

--&gt; call stored procedure
&lt;-- Column Names
&lt;-- Column Info
&lt;-- Row Result
&lt;-- Row Result
&lt;-- Done Inside Process
&lt;-- Column Names
&lt;-- Column Info
&lt;-- Row Result
&lt;-- Row Result
&lt;-- Done Inside Process
&lt;-- Return Status
&lt;-- Process Done
</pre>

<a name="packet"></a>
The packet format
 
 
All packets start with the following 8 byte header.

Fields:
packet type 
 0x01 <a href="#p1">TDS 4.2 or 7.0 query</a>
 0x02 <a href="#login">TDS 4.2 or 5.0 login packet</a>
 0x03 <a href="#p3">RPC</a>
 0x04 <a href="#responses">responses from server</a>
 0x06 cancels
 0x07 Used in Bulk
 0x0F TDS 5.0 query
 0x10 <a href="#login7">TDS 7.0 login packet</a>
last packet indicator 
 0x00 if more packets
 0x01 if last packet
packet size
 (in network byte order)
unknown?
 always 0x00
 this has something to do with server to server communication/rpc stuff
</pre>

The remainder of the packet depends on the type of information it is
providing. As noted above, packets break down into the types query, login,
response, and cancels. Response packets are further split into multiple
sub-types denoted by the first byte (a.k.a. the token) following the
above header.
 
 
Note:
 A TDS packet that is longer than 512 bytes is split on the 512 byte
 boundary and the "more packets" bit is set. The full TDS packet is reassembled
 from its component 512 byte packets with the 8-byte headers stripped out. (I
 believe the 512 is the block_size in the login packet, so it could be set to a
 different value. *mjs*)

<a name="login"></a>
Login Packet

Packet type (first byte) is 2. The numbers
on the left are decimal offsets including the 
8 byte packet header.
<pre>
byte var type description
------------------------------
 8 CHAR[30] host_name
 38 INT8 host_name_length
 39 CHAR[30] user_name
 69 INT8 user_name_length
 70 CHAR[30] password
 100 INT8 password_length
 101 CHAR[30] host_process
 131 INT8 host_process_length
 132 ? magic1[6] /* mystery stuff */
 138 INT8 bulk_copy 
 139 ? magic2[9] /* mystery stuff */
 148 CHAR[30] app_name
 178 INT8 app_name_length
 179 CHAR[30] server_name
 209 INT8 server_name_length
 210 ? magic3[1] /* 0, don't know this one either */
 211 INT8 password2_length
 212 CHAR[30] password2
 242 CHAR[223] magic4
 465 INT8 password2_length_plus2
 466 INT16 major_version /* TDS version */
 468 INT16 minor_version /* TDS version */
 470 CHAR library_name[10] /* "Ct-Library" or "DB-Library" */
 480 INT8 library_length
 481 INT16 major_version2 /* program version */
 483 INT16 minor_version2 /* program version */
 485 ? magic6[3] /* ? last two octets are 13 and 17 */
 /* bdw reports last two as 12 and 16 here */
 /* possibly a bitset flag */
 488 CHAR[30] language /* e.g. "us-english" */
 518 INT8 language_length
 519 ? magic7[1] /* mystery stuff */
 520 INT16 old_secure /* explanation? */
 522 INT8 encrypted /* 1 means encrypted all password fields blank */
 523 ? magic8[1] /* no clue... zeros */
 524 CHAR sec_spare[9] /* explanation? */
 533 CHAR[30] char_set /* e.g. "iso_1" */
 563 INT8 char_set_length
 564 INT8 magic9[1] /* 1 */ 
 565 CHAR[6] block_size /* in text */
 571 INT8 block_size_length 
 572 ? magic10[25] /* lots of stuff here...no clue */
</pre>
Any help with the magic numbers would be most appreciated.

<hr>

<a name="login7"></a>
TDS7.0 Login Packet
<pre>
byte var type description
---------------------------
 0 INT32	total packet size
 4 INT[4]	TDS Version	0x00000070 for TDS7, 0x01000071 for TDS8
 8 INT32	packet size (default 4096)
 12 INT8[4]	client program version
 16 INT32	PID of client
 20 INT32	connection id (usually 0)
 24 INT8	option flags 1
 0x80 enable warning messages if SET LANGUAGE issued
 0x40 change to initial database must succeed
 0x20 enable warning messages if USE &lt;database&gt; issued
 25 INT8	option flags 2
 0x80 enable domain login security
 0x02 client is an ODBC driver
 0x01 change to initial language must succeed
 26 INT8	sql type flags (0)
 27 INT8	reserved flags (must be 0)
 28 INT8[4]	time zone (0x88ffffff ???)
 32 INT8[4]	collation information
 36 INT16	position of client hostname (86)
 38 INT16	hostname lenght
 40 INT16	position of username
 42 INT16	username length
 44 INT16	position of password
 46 INT16	password length
 48 INT16	position of app name
 50 INT16	app name length
 52 INT16	position of server name
 54 INT16	server name length
 56 INT16	0
 58 INT16	0
 60 INT16	position of library name
 62 INT16	library name length
 64 INT16	position of language
 66 INT16	language name
 (for italian "Italiano" coded UCS2)
 68 INT16	position of database name
 70 INT16	database name length
 72 INT8[6]	MAC address of client
 78 INT16	position of auth portion
 80 INT16	NT authentication length
 82 INT16	next position (same of total packet size)
 84 INT16	0
 86 UCS2LE[n] hostname
 UCS2LE[n]	username
 UCS2LE[n]	encrypted password
 UCS2LE[n]	app name
 UCS2LE[n]	server name
 UCS2LE[n]	library name
 UCS2LE[n]	language name
 UCS2LE[n]	database name
 NT Authentication packet

NT Authentication packet
 0 CHAR[8]	authentication id "NTLMSSP\0"
 8 INT32 1 message type
 12 INT32	0xb201 flags
 16 INT16	domain length
 18 INT16 domain length
 20 INT32 domain offset
 24 INT16 hostname length
 26 INT16 hostname length
 28 INT32 hostname offset
 32 CHAR[n] hostname
 CHAR[n] domain
See documentation on Samba for detail (or search ntlm authentication for IIS)
</pre>
"current pos" is the starting byte address for a Unicode string within
the packet. The length of that Unicode string immediately follows. 
That implies there are at least 2 more strings that could be defined.
(character set??)
 
Password and user is not used is NT authentication is used (setted as empty).
<hr>

<a name="collate"></a>
Collate type - TDS8
Collate structure contain information on characters set encoding and compare
method.
<pre>
 INT16 INT16 INT8
+----------+--------+------------+
| codepage | flags | charset_id |
+----------+--------+------------+

codepage windows codepage (see <a href="http://www.microsoft.com/globaldev/nlsweb/">http://www.microsoft.com/globaldev/nlsweb/</a>)
 also specified in lcid column of master..syslanguages
flags sort flags
 0x100 binary compare
 0x080 width insensitive
 0x040 Katatype insensitive
 0x020 accent insensitive
 0x010 case insensitive
 If binary flag is specified other flags are not present
 Low nibble of flags is a charset specifier (like chinese dialect)
charset_id charset id in master..syscharsets table or zero for no SQL collations
</pre>

Collations names can be obtained from <code>select name from ::fn_helpcollations()</code>
query

<hr>

<a name="requests"></a>
Client request

Normal tokens (contained in packets 0xF)
<pre>
TODO
</pre>

Special packets
<pre>
0x1 1 <a href="#p1">Language</a>
0x3 3 <a href="#p3">RPC</a> TDS4.6+
</pre>

<hr>
<a name="p1">Language packet (0x1 1)</a>

This sample packet contain just SQL commands. It's supported by all TDS version
(although TDS5 have others token with similar use)
<pre>
 XCHAR[n]
+---------+
| string |
+---------+

string SQL text
</pre>

<hr>
<a name="p3">RPC packet (0x3 3)</a>

Do not confuse an RPC packet with an RPC token. The RPC packet is supported
by all version of TDS; the RPC token is supported only by TDS 5.0 (and has
different format). This is the oldest (and the only one in mssql) way to call
directly an RPC. Sybase also documents it, but as 0xE.

name length length of RPC name in characters. 
 mssql2k+ support some core RPC using numbers
 If a number is used instead of name name length is marked as -1
 (null) and a INT16 is used for the name.
 0x1 1 sp_cursor
 0x2 2 sp_cursoropen
 0x3 3 sp_cursorprepare
 0x4 4 sp_cursorexecute
 0x5 5 sp_cursorprepexec
 0x6 6 sp_cursorunprepare
 0x7 7 sp_cursorfetch
 0x8 8 sp_cursoroption
 0x9 9 sp_cursorclose
 0xA 10 sp_executesql
 0xB 11 sp_prepare
 0xC 12 sp_execute ???
 0xD 13 sp_prepexec
 0xE 14 sp_prepexecrpc
 0xF 15 sp_unprepare
rpc name name of RPC. 
flags bit flags. 
 0x1 1 recompile procedure (TDS7+/TDS5)
 0x2 2 no metadata (TDS7+)
 (I don't know meaning of "no metadata" -- freddy77)
params parameters. See below
</pre>

Every parameter has the following structure

<pre>
+-----------+------+
| data info | data |
+-----------+------+
data info data information. See below
data data. See results for detail
</pre>

name length   parameter name length (0 if unused)
param name    parameter name
flags         bit Name           Meaning
              0x1 TDS_RPC_OUTPUT output parameter
              0x2 TDS_RPC_NODEF  output parameter has no default value. 
                                 Valid only with TDS_RPC_OUTPUT.

usertype usertype
type param type
size see <a href="#t129">Results</a>
optional see <a href="#t129">Results</a>. Blobs DO NOT have 
 optional on input parameters (output blob parameters
 are not supported by any version of TDS).
collate info only for type that want collate info and using TDS8
locale length locale information length. Usually 0 (if not locale
 information follow, the structure is unknown)
</pre>

<hr>

<a name="responses"></a>
Server Responses

Responses from the server start with a single octet (token) identifying
its type. If variable length, they generally have the length as the second
and third bytes

Tokens encountered thus far:
<pre>
0x21 33 <a href="#t33">"Language packet" ?</a> 	5.0 only, client-side?
0x71 113 <a href="#t113">"Logout"</a>			5.0? ct_close(), client-side?
0x79 121 <a href="#t121">Return Status</a>
0x7C 124 <a href="#t124">Process ID</a>			4.2 only
0x81 129 <a href="#t129">7.0 Result</a>			7.0 only
0xA0 160 <a href="#t160">Column Name</a>		4.2 only
0xA1 161 <a href="#t161">Column Info --- Row Result</a>	4.2 only
0xA4 164 <a href="#t164">Table names</a>		name of tables in a FOR BROWSE select
0xA5 165 <a href="#t165">Column info</a>		column information in a FOR BROWSE select
0xA7 167 <a href="#t167">compute related ? Also "control" ?</a>
0xA8 168 <a href="#t168">Column Info --- Compute Result</a>
0xA9 169 <a href="#t169">Order By</a>
0xAA 170 <a href="#t170">Error Message</a>
0xAB 171 <a href="#t171">Non-error Message</a>
0xAC 172 <a href="#t172">Output Parameters</a>
0xAD 173 <a href="#t173">Login Acknowledgement</a>
0xAE 174 <a href="#t174">"control" ?</a>
0xD1 209 <a href="#t209">Data --- Row Result</a>
0xD3 211 <a href="#t211">Data --- Compute Result</a>
0xD7 215 <a href="#t215">"param packet" ?</a> **bdw**
0xE2 226 <a href="#t226">Capability packet</a>		information on server
0xE3 227 <a href="#t227">Environment Change</a> (database change, packet size, etc...)
0xE5 229 <a href="#t229">Extended Error Message</a>
0xE6 230 <a href="#t230">"DBRPC" ?</a>		5.0 only RPC calls
0xEC 236 <a href="#t236">"param format packet" ?</a>
0xEE 238 <a href="#t238">Result Set</a>
0xFD 253 <a href="#t253">Result Set Done</a> 
0xFE 254 <a href="#t254">Process Done</a>
0xFF 255 <a href="#t255">Done inside Process</a>
</pre>

<a name="t33">&nbsp;</a> <hr>
"Language" (0x21 33)

<pre>
 int? INT8 CHAR[n]
+--------+--------+--------+
| length | status | string |
+--------+--------+--------+
</pre>

<a name="t113">&nbsp;</a> <hr>
"Logout" (0x71 113)

No information. (1 byte, value=0 ?)

<a name="t121">&nbsp;</a> <hr>
Return Status (0x79 121)

<pre>
 4 bytes
+---------------+
| Return status |
+---------------+
</pre>

The return value of a stored procedure.

<a name="t124">&nbsp;</a> <hr>
Process ID (0x7C 124)

<pre>
 8 bytes
+----------------+
| process number |
+----------------+
</pre>
Presumably the process ID number for an executing stored procedure.
(I'm not sure how this would ever be used by a client. *mjs*)

<a name="t129">&nbsp;</a> <hr>
Result - TDS 7.0+ (0x81 129)

<pre>
 INT16 
+----------+-------------+
| #columns | column_info | 
+----------+-------------+
</pre>

The TDS 7.0 column_info is formatted as follows for each column:

usertype	type modifier
flags		bit flags
		0x1  can be NULL
		0x8  can be written (it's not an expression)
		0x10 identity 
type		data type, values &gt;128 indicate a large type
size		none for fixed size types
		4 bytes for blob and text
		2 bytes for large types
		1 byte for all others
optional
                               INT8        INT8
                              +-----------+-------+
  numeric/decimal types:      | precision | scale |
                              +-----------+-------+

INT16               UCS2LE[n]
                              +-------------------+------------+
  blob/text types:            | table name length | table name |
                              +-------------------+------------+

collate info are available only using TDS8 and for characters types (but not
 for old type like short VARCHAR, only 2byte length versions)
</pre>

<a name="t160">&nbsp;</a> <hr>
Column Name (0xA0 160)

<a name="t161">&nbsp;</a>
<a name="t168">&nbsp;</a> <hr>
Column Info - Row Result (0xA1 161)
 
Column Info - Compute Result (0xA8 168)

column name length 
column name column name in result set, not necessarily db column name
unknown unknown (0, 16 ?)
user type usertype column from syscolumns
unknown always 0's
column type (need an appendix for discussion of column types)
column size not present for fixed size columns
precision present only for SYBDECIMAL and SYBNUMERIC
scale present only for SYBDECIMAL and SYBNUMERIC
t length present only for SYBTEXT and SYBIMAGE, length of table name
table name present only for SYBTEXT and SYBIMAGE
unknown always 0x00
</pre>

<a name="t164">&nbsp;</a> <hr>
"tabname" (0xA4 164)

No information.

<a name="t165">&nbsp;</a> <hr>
"col info" (0xA5 165)

No information.

<a name="t167">&nbsp;</a>
<a name="t174">&nbsp;</a> <hr>
compute "control" ? (0xA7 167)
 
"control" (0xAE 174)

Miscellaneous note (from *bdw* ?) found with 0xAE: 
<pre>
 has one byte for each column, 
 comes between result(238) and first row(209),
 I believe computed column info is stored here, need to investigate
</pre>

<a name="t169">&nbsp;</a> <hr>
Order By (0xA9 169)

<pre>
 INT16 variable (1 byte per col)
+--------+---------+
| length | orders |
+--------+---------+

length		Length of packet(and number of cols)
orders          one byte per order by indicating the
                column # in the output matching the
                order from Column Info and Column Names
                and data in following Row Data items.
                A 0 indicates the column is not in the
                resulting rows.

an example:
select first_name, last_name, number from employee
order by salary, number
assuming the columns are returned in the order
queried:
first_name then last_name, then number. we would have:
----------------
| 2 | 0 | 3 |
----------------
where length = 2 then the orders evaluate:
0 for salary, meaning there is no salary data returned
3 for number, meaning the 3rd data item corresponding
to a column is the number
</pre>

<a name="t170">&nbsp;</a>
<a name="t171"></a>
<a name="t229"></a> <hr>
Error Message (0xAA 170)
 
Non-error Message (0xAB 171)
 
Extended Error Message (0xE5 229)

length		Length of packet
msg number	SQL message number
state		?
level		An error if level &gt; 10, a message if level &lt;= 10
m length	Length of message
message		Text of error/message
s length	Length of server name
server		Name of "server" ?
p length	Length of process name
process name	Stored procedure name, if any
line#		Line number of input which generated the message
</pre>

length		Length of packet
c length	Length of colname
colname		Name of column
flags		0x1 Nullable
usertype	cf. systypes table in database
datatype	Type of data returned

The trailing information depends on whether the datatype is
a fixed size datatype.
				 N bytes
				+---------+
  Datatype of fixed size N	| data    |
				+---------+

INT8 INT8 N bytes
				+-------------+---------------+--------+
 Otherwise			| column size | actual size N | data |
				+-------------+---------------+--------+
</pre>

<a name="t173">&nbsp;</a> <hr>
Login Acknowledgement (0xAD 173)

length		length of packet
ack		0x01 success	4.2
		0x05 success	5.0
		0x06 failure	5.0
version		TDS version 4 bytes: major.minor.?.?
t length	length of text
text		server name (ie 'Microsoft SQL Server')
		For TDS7+ this is in ucs2 format
ser_ver		Server version
		(with strange encoding, differring from TDS version)
</pre>

<a name="t209">&nbsp;</a>
<a name="t211">&nbsp;</a> <hr>
Data - Row Result (0xD1 209)
 
Data - Compute Result (0xD3 211)

<pre>
 INT8 variable size
+----------+--------------------+
| token | row data |
+----------+--------------------+
</pre>
Row data starts with one byte (decimal 209), for variable length types,
a one byte length field precedes the data, for fixed length records just
the data appears.
 Note: nullable integers and floats are variable length.

For example: sp_who

The first field is spid, a smallint
 
The second field is status a char(12), in our example "recv sleep "

The row would look like this:
<pre>
 byte 0 is the token
 bytes 1-2 are a smallint in low-endian
 byte 3 is the length of the char field
 bytes 4-15 is the char field

byte 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
hex D1 01 00 0C 72 65 63 76 20 73 6C 65 65 70 20 20
 209 1 0 12 r e c v ' ' s l e e p ' ' ' '
</pre>

<a name="t215">&nbsp;</a> <hr>
Parameter packet (0xD7 215)
 
 
No information

<a name="t226">&nbsp;</a> <hr>
Capability packet (0xE2 226)

<pre>
 INT16 variable
+--------+--------------+
| length | capabilities |
+--------+--------------+

length		Length of capability string
capabilities	Server capabilities? Related to login magic?
</pre>

<a name="t227">&nbsp;</a> <hr>
Environment change (0xE3 227)

env code	Code for what part of environment changed
	0x01  database context
	0x02  language
	0x03  character set
	0x04  packet size
	0x05  TDS7+ LCID
	0x06  TDS7+ ??? (sort method? sql server encoding?)
	0x07  Collation info
text1		Old value
text2		New value

text1 and text2 are text information (coded in ucs2 in TDS7+) except 
collation info that's a structure (see collation structure)
</pre>

<a name="t230">&nbsp;</a> <hr>
DB RPC ? (0xE6 230)
 
 
No information.

length 	length of message following this field
number of parameters	number of parameter formats following
list of formats		I (*bdw*) imagine it uses the column format structure.
</pre>

<a name="t238">&nbsp;</a> <hr>
Result Set (0xEE 238)

Fields:
length length of message following this field
number of columns number of columns in the result set, this many column
 information fields will follow.
column info <a href="#t161">column info</a>
</pre>

<a name="t253">&nbsp;</a>
<a name="t254"></a>
<a name="t255"></a> <hr>
Result Set Done (0xFD 253) 
Process Done (0xFE 254) 
Done Inside Process (0xFF 255)

<pre>
 INT16 INT16 INT32
+-----------+---------+-----------+
| bit flags | unknown | row count |
+-----------+---------+-----------+

Fields:
bit flags 0x01 more results
		 0x02 error (like invalid sql syntax)
		 0x10 row count is valid
		 0x20 cancelled
unknown 2,0 /* something to do with block size perhaps */
row count number of rows affected / returned in the result set. 
		(FIXME check if "affected / returned" is correct)
</pre>

"Result Set Complete" is the end of a query that doesn't create a process
on the server. I.e., it doesn't call a stored procedure.
 
 
"Process Done" is the end of a stored procedure
 
 
"Done In Process" means that a query internal to a stored procedure
has finished, but the stored procedure isn't done overall.

<hr>

Acknowledgements
 
The following people have contributed to this document:

Brian Bruns (first draft, protocol discovery)
 
Brian Wheeler (protocol discovery)
 
Mark Schaal (second draft)
 
Frediano Ziglio

(short list)
</body>
</html>