Share via

2.2.3.14.3.6 adtgColumnDescriptorCommon

  • Article

The adtgColumnDescriptorCommon element specifies the properties of a column of data in a RecordSet, and is used by the adtgColumnDescriptorParent and adtgColumnDescriptorChild elements.

The syntax of an adtgColumnDescriptorCommon element is defined as follows.

 adtgColumnDescriptorCommon        = adtgTokenColumnDescriptor
                                     adtgTokenColumnDescriptorSize
                                     adtgColumnDescriptorPresenceMap
                                     ColumnOrdinal
                                     [FriendlyColumnName]
                                     [adtgBaseTableInformation]
                                     adtgColumnDBTYPE
                                     adtgColumnMaxLength
                                     Precision
                                     Scale
                                     ColumnFlags
                                     [BaseCatalogName]
                                     [BaseSchemaName]
                                     [CollatingSequence]
                                     [ComputeMode]
                                     [DateTimePrecision]
                                     [VariantDefaultValue]
                                     [IsAutoIncrement]
                                     [IsCaseSensitive]
                                     [IsMultiValued]
                                     [IsSearchable] 
                                     [IsUnique]
                                     [OctetLength]
                                     IsVisible
  
 adtgTokenColumnDescriptor       =  %x06
  
 adtgTokenColumnDescriptorSize   =  USHORT
  
 adtgColumnDescriptorPresenceMap = adtgColumnDescriptorPresenceByte1
                                   adtgColumnDescriptorPresenceByte2
                                   adtgColumnDescriptorPresenceByte3
  
 adtgColumnDescriptorPresenceByte1 = fBaseSchemaName
                                     fBaseCatalogName
                                     RESERVEDBIT
                                     RESERVEDBIT
                                     fBaseTableColumnName
                                     fBaseTableColumnOrdinal
                                     fBaseTableOrdinal
                                     fFriendlyColumnName
  
 adtgColumnDescriptorPresenceByte2 = fIsAutoIncrement
                                     RESERVEDBIT
                                     RESERVEDBIT
                                     RESERVEDBIT
                                     fVariantDefaultValue
                                     fDateTimePrecision
                                     fComputeMode
                                     fCollatingSequence
  
 adtgColumnDescriptorPresenceByte3 = RESERVEDBIT RESERVEDBIT
                                     fCalculationInfo
                                     fOctetLength
                                     fIsUnique
                                     fIsSearchable
                                     fIsMultivalued
                                     fIsCaseSensitive
  
 adtgBaseTableInformation          = BaseTableOrdinal 
                                     BaseTableColumnOrdinal
                                     BaseTableColumnName
  
 fBaseSchemaName         = BIT
 fBaseCatalogName        = BIT
 fBaseTableColumnName    = BIT
 fBaseTableColumnOrdinal = BIT
 fBaseTableOrdinal       = BIT
 fFriendlyColumnName     = BIT
 fIsAutoIncrement        = BIT
 fVariantDefaultValue    = BIT
 fDateTimePrecision      = BIT
 fComputeMode            = BIT
 fCollatingSequence      = BIT
 fCalculationInfo        = BIT
 fOctetLength            = BIT
 fIsUnique               = BIT
 fIsSearchable           = BIT
 fIsMultivalued          = BIT
 fIsCaseSensitive        = BIT
  
 ColumnOrdinal           = USHORT
  
 FriendlyColumnName      = LENGTH-PREFIXED-STRING
  
 BaseTableOrdinal        = USHORT
  
 BaseTableColumnOrdinal  = USHORT
  
 BaseTableColumnName     = LENGTH-PREFIXED-STRING
  
 adtgColumnMaxLength     = ULONG
  
 Precision               = ULONG
  
 Scale                   = LONG
  
 ColumnFlags             = DBCOLUMNFLAGS
  
 DBCOLUMNFLAGS           = DWORD
  
 BaseCatalogName         = LENGTH-PREFIXED-STRING
  
 BaseSchemaName          = LENGTH-PREFIXED-STRING
  
 CollatingSequence       = LONG
  
 ComputeMode             = LONG
  
 DateTimePrecision       = ULONG
  
 VariantDefaultValue     = VARIANT
  
 IsAutoIncrement         = VARIANT-BOOL
  
 IsCaseSensitive         = VARIANT-BOOL
  
 IsMultiValued           = VARIANT-BOOL
  
 IsSearchable            = ULONG
  
 IsUnique                = VARIANT-BOOL
  
 OctetLength             = ULONG
  
 IsVisible               = VARIANT-BOOL

The fields in this element have the following lengths, types, and meanings:

  • adtgTokenColumnDescriptor

    Length: 1 byte

    Datatype: BYTE

    Identifies this component as an adtgColumnDescriptorCommon element. The value MUST be set to 0x06.

  • adtgTokenColumnDescriptorSize

    Length: 2 bytes

    Datatype: USHORT

    Specifies the length in bytes of the rest of this element. This value is variable and does not include the lengths of the adtgTokenColumnDescriptor and adtgTokenColumnDescriptorSize fields.

  • adtgColumnDescriptorPresenceMap

    Length: 3 bytes

    Datatype: BYTE

    Contains bit flags that specify which of the optional fields are present.

    The byte array contains one bit for each optional field. If a bit is set to 1, the corresponding field is present; otherwise, it is absent, and therefore not transmitted.

    The following table identifies the optional fields and their corresponding adtgColumnDescriptorPresenceMap bit flags.<53>

     Field name

     Bit flag

    FriendlyColumnName

    0x800000

    BaseTableOrdinal

    0x400000

    BaseTableColumnOrdinal

    0x200000

    BaseTableColumnName

    0x100000

    (Reserved)

    0x080000

    (Reserved)

    0x040000

    BaseCatalogName

    0x020000

    BaseSchemaName

    0x010000

    CollatingSequence

    0x008000

    ComputeMode

    0x004000

    DateTimePrecision

    0x002000

    VariantDefaultValue

    0x001000

    (Reserved)

    0x000800

    (Reserved)

    0x000400

    (Reserved)

    0x000200

    IsAutoIncrement

    0x000100

    IsCaseSensitive

    0x000080

    IsMultivalued

    0x000040

    IsSearchable

    0x000020

    IsUnique

    0x000010

    OctetLength

    0x000008

    CalculationInfo

    0x000004

    (Reserved)

    0x000002

    (Reserved)

    0x000001

  • ColumnOrdinal

    Length: 2 bytes

    Datatype: USHORT

    Contains the ordinal of the column in the RecordSet. Column ordinal values begin at a value of 1.

    Columns in the RecordSet that were not specified as part of the original query but are part of the TableGram (such as the primary key and time stamp columns for keyset implementations), are always transmitted after all the visible columns. This results in the ordinal value for such columns being greater than the value of the VisibleColumnsCount in the adtgResultDescriptor element.

  • FriendlyColumnName

    Length: Variable

    Datatype: LENGTH-PREFIXED-STRING

    A string that contains the human-readable name of the column.

    The FriendlyColumnName field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.

  • BaseTableOrdinal

    Length: 2 bytes

    Datatype: USHORT

    Specifies the base table to which the column belongs. The value of this field MUST match the value of the TableOrdinal field in the adtgTableDescriptor element. For computed columns, the BaseTableOrdinal field is not present.

    The BaseTableOrdinal field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.

  • BaseTableColumnOrdinal

    Length: 2 bytes

    Datatype: USHORT

    Specifies the ordinal of the column in the base table. For computed columns, the BaseTableColumnOrdinal field is not present.

    The BaseTableColumnOrdinal is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.

  • BaseTableColumnName

    Length: Variable

    Datatype: LENGTH-PREFIXED-STRING

    A string that contains the name of the column in the base table. The value can be the same as the value of the FriendlyColumnName field.

    The BaseTableColumnName field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.

  • adtgColumnDBType

    Length: 2 bytes

    Datatype: DBTYPE

     adtgColumnDBType = DBTYPE
  
 DBTYPE = WORD

    Specifies the datatype of the column. The following table illustrates how the value of the adtgColumnDBType field of a column's metadata determines how to interpret the ColumnData field, which contains the values of the column's fields. For details on the ColumnData field, see section 2.2.3.14.4.9.

    The following table specifies how the values of the adtgColumnDBType field and the adtgColumnMaxLength field in a column's metadata determine which of the possible fields of ColumnData will actually be used for that column. In the following table, the "Type" column refers to the value in the adtgColumnDBType field for this adtgColumnDescriptorCommon. The "<=255" column refers to whether the value in the adtgColumnMaxLength field for this adtgColumnDescriptorCommon is to be less than or equal to 255. The "Fixed?" column contains the value of the DBCOLUMNFLAGS_ISFIXEDLENGTH bit in the ColumnFlags field of this adtgColumnDescriptorCommon. The "ColumnData" column specifies that any ColumnData fields corresponding to this adtgColumnDescriptorCommon MUST be of the type indicated when the conditions specified in the remainder of the table row are met.

     Type

     <=255

     Fixed?

     ColumnData

    %x00.00 (VT-EMPTY)

    Yes

    1

    ()

    %x01.00 (VT-NULL)

    Yes

    1

    ()

    %x02.00 (VT-I2)

    Yes

    1

    WORD

    %x03.00 (VT-I4)

    Yes

    1

    LONG

    %x04.00 (VT-R4)

    Yes

    1

    FLOAT

    %x05.00 (VT-R8)

    Yes

    1

    DOUBLE

    %x06.00 (VT-CY)

    Yes

    1

    CY

    %x07.00 (VT-DATE)

    Yes

    1

    DATEVAL

    %x08.00 (VT-BSTR)

    Yes

    0

    (ShortColumnDataLen BSTRVAL)

    %x08.00 (VT-BSTR)

    No

    0

    (LongColumnDataLen BSTRVAL)

    %x08.00 (VT-BSTR)

    Any

    1

    BSTRVAL

    %x0A.00 (VT-ERROR)

    Yes

    1

    VARIANTERROR

    %x0B.00 (VT-BOOL)

    Yes

    1

    BOOLVAL

    %x0E.00 (VT-DECIMAL)

    Yes

    1

    DECIMAL

    %x10.00 (VT-I1)

    Yes

    1

    BYTE

    %x12.00 (VT-UI2)

    Yes

    1

    USHORT

    %x13.00 (VT-UI4)

    Yes

    1

    ULONG

    %x14.00 (VT-I8)

    Yes

    1

    2LONG

    %x15.00 (VT-UI8)

    Yes

    1

    2ULONG

    %x48.00 (VT-CLSID)

    Yes

    1

    16BYTE

    %x80.00 (DBTYPE-BYTES)

    Yes

    0

    (ShortColumnDataLen *BYTE)

    %x80.00 (DBTYPE-BYTES)

    No

    0

    (LongColumnDataLen *BYTE)

    %x80.00 (DBTYPE-BYTES)

    Any

    1

    *BYTE

    %x81.00 (DBTYPE-STR)

    Yes

    0

    (ShortColumnDataLen ASCIISTRING)

    %x81.00 (DBTYPE-STR)

    No

    0

    (LongColumnDataLen ASCIISTRING)

    %x81.00 (DBTYPE-STR)

    Any

    1

    ASCIISTRING

    %x82.00 (DBTYPE-WSTR)

    Yes

    0

    (ShortColumnDataLen BSTRVAL)

    %x82.00 (DBTYPE-WSTR)

    No

    0

    (LongColumnDataLen BSTRVAL)

    %x82.00 (DBTYPE-WSTR)

    Any

    1

    BSTRVAL

    %x85.00 (DBTYPE-DBDATE)

    Yes

    1

    dbDBDATEData

    %x86.00 (DBTYPE-DBTIME)

    Yes

    1

    dbDBTIMEData

    %x87.00 (DBTYPE-DBTIMESTAMP)

    Yes

    1

    dbDBTIMESTAMPData

    %x88.00 (DBTYPE-HCHAPTER)

    Any

    1

    ()

    %x8B.00 (DBTYPE-VARNUMERIC)

    Yes

    1

    dbVARNUMERICData

    If the value in the "ColumnData" column of the preceding table is BSTRVAL or *BYTE then length, in bytes, of ColumnData corresponding to this adtgColumnDescriptorCommon MUST be equal to the value of the adtgColumnDescriptorCommon's adtgColumnMaxLength field. This is not the case when the BSTRVAL or *BYTE is preceded by a length constant in the ColumnData field.

  • adtgColumnMaxLength

    Length: 4 bytes

    Datatype: ULONG

    Specifies the maximum size of the column. If the value of this field is 0xFFFFFFFF, no maximum size is defined for the column.

  • Precision

    Length: 4 bytes

    Datatype: ULONG

    Specifies the number of digits if the datatype specified by the adtgColumnDBType field is NUMERIC; otherwise, zero.

  • Scale

    Length: 4 bytes

    Datatype: LONG

    Specifies the number of digits to the right of the decimal point if the data specified by the adgtColumnDBType field is NUMERIC; otherwise, zero.

  • ColumnFlags

    Length: 4 bytes

    Datatype: DBCOLUMNFLAGS

    Flags that specify characteristics of the column. Each flag is 1 bit. Of the 32 flags, 16 are used. The remaining flags are either unused or reserved for future use. If a flag is unused or reserved, the flag SHOULD be set to zero and ignored on receipt.

    Note The following pairs of flags are mutually exclusive. Both flags MUST NOT be set to 1. The mutually exclusive pairs of flags are the following.

     DBCOLUMNFLAGS_WRITE
     and DBCOLUMNFLAGS_WRITEUNKNOWN
  
 DBCOLUMNFLAGS_SCALEISNEGATIVE
     and DBCOLUMNFLAGS_ISCHAPTER

     Name and bit position

     Meaning

    DBCOLUMNFLAGS_RESERVED0

    0

    Reserved.

    DBCOLUMNFLAGS_MAYDEFER

    1

    Set to 1 if the column can be deferred. If the value of this flag is 1, the column values are not obtained from the data source until they are explicitly accessed.

    DBCOLUMNFLAGS_WRITE

    2

    Set to 1 if the value of the column can be updated.

    DBCOLUMNFLAGS_WRITEUNKNOWN

    3

    Set to 1 if it is not known if the value of the column can be updated.

    DBCOLUMNFLAGS_ISFIXEDLENGTH

    4

    Set to 1 if all data in the column has the same length.

    DBCOLUMNFLAGS_ISNULLABLE

    5

    Set to 1 if null can be written to the column.

    When a row contains a null value for a column that can contain null values, the value for this column is omitted from the RDS Transport Protocol serialization of the row. The ColumnValuePresenceMap field of the adtgParentUnchanged or adtgChildUnchanged element represents the absence of the column by setting the bit that corresponds to the column to 0.

    DBCOLUMNFLAGS_MAYBENULL

    6

    Set to 1 if null can be read from the column.

    When a row contains a null value for a column that can contain null values, the value for this column is omitted from the serialization of the row. The ColumnValuePresenceMap field of the adtgParentUnchanged element represents the absence of the column by setting the bit that corresponds to the column to 0.

    DBCOLUMNFLAGS_ISLONG

    7

    Set to 1 if the column contains a large amount of data. The definition of "large amount" is specific to the server implementation.

    DBCOLUMNFLAGS_ISROWId

    8

    Set to 1 if the column contains a persistent row identifier. This row identifier is read-only and has no meaningful value except to identify the row.

    DBCOLUMNFLAGS_ISROWVER

    9

    Set to 1 if the column contains a time stamp or other version information to track updates.

    10 - 11

    Unused/reserved.

    DBCOLUMNFLAGS_CACHEDEFERRED

    12

    Set to 1 if the column is cached. If the value of this flag is 1, the server caches the value of a deferred column when the client first gets a value from that column. When the client later gets a value from the column, the server returns the value in the cache.

    DBCOLUMNFLAGS_ISCHAPTER

    13

    Set to 1 if the column is a chapter that specifies a specific child RecordSet related to this Parent column. Typically, chapter columns are used with data shaping or filters.

    DBCOLUMNFLAGS_SCALEISNEGATIVE

    14

    Set to 1 if the scale of the column is negative.

    DBCOLUMNFLAGS_KEYCOLUMN

    15

    Set to 1 if the column is a key.

    16 - 31

    Unused/reserved.

  • BaseCatalogName

    Length: Variable

    Datatype: LENGTH-PREFIXED-STRING

    A string that contains the name of the base table catalog.

    The BaseCatalogName field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.

  • BaseSchemaName

    Length: Variable

    Datatype: LENGTH-PREFIXED-STRING

    A string that contains the name of the base table schema.

    The BaseSchemaName field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.

  • CollatingSequence

    Length: 4 bytes

    Datatype: LONG

    Data strings in adtgTableGram MUST always be encoded as Unicode. This field specifies the collating sequence, as specified in [UNICODE], and MUST set to %x00.00.

    The CollatingSequence field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<54>

  • ComputeMode

    Length: 4 bytes

    Datatype: LONG

    Specifies an implementation-specific hint to the method used to compute the column.

    Because server implementations vary, the meaning of the ComputeMode field is specific to the server. The ComputeMode field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field. RDS Transport Protocol servers SHOULD<55> omit this field.

     Value

     Meaning

    DBCOMPUTEMODE_COMPUTED

    0x00000001

    The value in the column is determined on the server based on a formula or other operation involving one or more columns; for example, mathematical or string functions.

    DBCOMPUTEMODE_DYNAMIC

    0x00000002

    The value in the column is reserved for a special type of computed column that enforces computation rules without a round trip to the server. These columns are treated as normal columns when encoded; therefore, this flag has no meaning within the context of a TableGram. Servers SHOULD NOT send this flag, and client implementations SHOULD ignore it if observed.

    DBCOMPUTEMODE_NOTCOMPUTED

    0x00000003

    The value in the column is not computed.

  • DateTimePrecision

    Length: 4 bytes

    Datatype: ULONG

    Specifies the precision of the date and time (the number of digits in the fractional seconds portion) if the column is of datetime or interval type. If the column's datatype is not datetime, DateTimePrecision SHOULD NOT be present.

    DateTimePrecision is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<56>

  • VariantDefaultValue

    Length: 16 bytes

    Datatype: VARIANT

    Contains the default value of the column.

    VariantDefaultValue is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<57>

  • IsAutoIncrement

    Length: 2 bytes

    Datatype: VARIANT-BOOL

    0xFFFF if the values of the column are autoincrementing; otherwise, 0x0000.

    IsAutoIncrement is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.

  • IsCaseSensitive

    Length: 2 bytes

    Datatype: VARIANT-BOOL

    0xFFFF if the values of the column are case-sensitive; otherwise, 0x0000.

    IsCaseSensitive is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<58>

  • IsMultivalued

    Length: 2 bytes

    Datatype: VARIANT-BOOL

    0xFFFF if the cells in this column contain more than one value; otherwise, 0x0000.

    IsMultivalued is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<59>

  • IsSearchable

    Length: 2 bytes

    Datatype: VARIANT-BOOL

    0xFFFF if the values in this column are searchable; otherwise, 0x0000.

    IsSearchable is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<60>

  • IsUnique

    Length: 2 bytes

    Datatype: VARIANT-BOOL

    0xFFFF if the values of the column are unique within the table; otherwise, 0x0000.

    The IsUnique field is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<61>

  • OctetLength

    Length: 4 bytes

    Datatype: ULONG

    Specifies the maximum length, in octets (bytes) of the column if the type of the column is character or binary. A value of zero means the column has no maximum length. This field is absent for all other types of columns.

    OctetLength is optional, and its presence or absence is specified by the value of the corresponding bit in the adtgColumnDescriptorPresenceMap field.<62>

  • IsVisible

    Length: 2 bytes

    Datatype: VARIANT-BOOL

    0xFFFF if the column is in the Selection list of the original query; otherwise, 0x0000 if the column is an extra column generated by the query (key columns in a keyset are examples of extra columns).