2.2.7.1 ALTMETADATA

Token Stream Name:

 ALTMETADATA

Token Stream Function:

Describes the data type, length, and name of column data that result from a SQL statement that generates totals.

Token Stream Comments:

The token value is 0x88.

This token is used to tell the client the data type and length of the column data. It describes the format of the data found in an ALTROW data stream. ALTMETADATA and the corresponding ALTROW MUST be in the same result set.

All ALTMETADATA data streams are grouped.

A preceding COLMETADATA (section 2.2.7.4) MUST exist before an ALTMETADATA token. There might be COLINFO and TABNAME streams between COLMETADATA and ALTMETADATA.

Note ALTMETADATA was deprecated in TDS 7.4.

Token Stream-Specific Rules:

 TokenType        =   BYTE
 Count            =   USHORT
 Id               =   USHORT
 ByCols           =   UCHAR
  
 Op               =   BYTE
 Operand          =   USHORT
 UserType         =   USHORT/ULONG; (changed to ULONG in TDS 7.2)
  
  
 fNullable        =   BIT
 fCaseSen         =   BIT
 usUpdateable     =   2BIT        ; 0 = ReadOnly
                                  ; 1 = Read/Write
                                  ; 2 = Unused
 fIdentity        =   BIT
 fComputed        =   BIT         ; (introduced in TDS 7.2)
 usReservedODBC   =   2BIT
 fFixedLenCLRType =   BIT         ; (introduced in TDS 7.2)
 usReserved       =   7BIT
  
 Flags            =   fNullable
                      fCaseSen
                      usUpdateable
                      fIdentity
                      (FRESERVEDBIT / fComputed)
                      usReservedODBC
                      (FRESERVEDBIT / fFixedLenCLRType)
                      usReserved
  
 NumParts         =   BYTE                  ; (introduced in TDS 7.2)
 PartName         =   US_VARCHAR            ; (introduced in TDS 7.2)
  
 TableName        =   US_VARCHAR            ; (removed in TDS 7.2)
                      /
                      (NumParts
                      1*PartName)           ; (introduced in TDS 7.2)
 ColName          =   B_VARCHAR
 ColNum           =   USHORT
  
 ComputeData      =   Op
                      Operand
                      UserType
                      Flags
                      TYPE_INFO
                      [TableName]
                      ColName

The TableName field is specified only if a text, ntext, or image column is included in the result set.

Token Stream Definition:

 ALTMETADATA      =   TokenType
                      Count
                      Id
                      ByCols
                      *(<ByCols> ColNum)
                      1*ComputeData

Token Stream Parameter Details:

Parameter

Description

TokenType

ALTMETADATA_TOKEN<39>

Count

The count of columns (number of aggregate operators) in the token stream.

Id

The Id of the SQL statement to which the total column formats apply. Each ALTMETADATA token MUST have its own unique Id in the same result set. This Id lets the client correctly interpret later ALTROW data streams.

ByCols

The number of grouping columns in the SQL statement that generates totals. For example, the SQL clause compute count(sales) by year, month, division, department has four grouping columns.

Op

The type of aggregate operator.

 AOPSTDEV        = %x30   ; Standard deviation (STDEV)
 AOPSTDEVP       = %x31   ; Standard deviation of the population (STDEVP)
 AOPVAR          = %x32   ; Variance (VAR)
 AOPVARP         = %x33   ; Variance of population (VARP)
 AOPCNT          = %x4B   ; Count of rows (COUNT)
 AOPSUM          = %x4D   ; Sum of the values in the rows (SUM)
 AOPAVG          = %x4F   ; Average of the values in the rows (AVG)
 AOPMIN          = %x51   ; Minimum value of the rows (MIN)
 AOPMAX          = %x52   ; Maximum value of the rows (MAX)

Operand

The column number, starting from 1, in the result set that is the operand to the aggregate operator.

UserType

The user type ID of the data type of the column. Depending on the TDS version that is used, valid values are 0x0000 or 0x00000000, with the exceptions of data type timestamp (0x0050 or 0x00000050) and alias types (greater than 0x00FF or 0x000000FF).

Flags

These bit flags are described in least significant bit order. With the exception of fNullable, all of these bit flags SHOULD be set to zero. For a description of each bit flag, see section 2.2.7.4:

  • fNullable is a bit flag, 1 if the column is nullable.

  • fCaseSen

  • usUpdateable

  • fIdentity

  • fComputed

  • usReservedODBC

  • fFixedLenCLRType

TableName

See section 2.2.7.4 for a description of TableName. This field SHOULD never be sent because SQL statements that generate totals exclude NTEXT/TEXT/IMAGE.

ColName

The column name. Contains the column name length and column name.

ColNum

USHORT specifying the column number as it appears in the COMPUTE clause. ColNum appears ByCols times.