2.2.3.14.3.1 adtgResultDescriptor

An adtgResultDescriptor element specifies the composition and properties of the RecordSet. A TableGram can contain multiple RecordSets. There is one adtgResultDescriptor element for each RecordSet.

The syntax of an adtgResultDescriptor element is defined as follows.

 adtgResultDescriptor        = adtgTokenResultDescriptor
                               adtgTokenResultDescriptorSize
                               adtgGUIDResultDescriptor
                               adtgResultInfo
                               adtgCursorModel
                               adtgNormalization
                               VisibleColumnsCount
                               TotalColumnsCount
                               ComputedColumnsCount
                               TableCount
                               OrderByColumnsCount
                               RowCount
                               [adtgPropertySets]
  
 adtgTokenResultDescriptor   = %x03
  
 adtgTokenResultDescriptorSize = USHORT
  
 adtgGUIDResultDescriptor    = GUID
  
 adtgResultInfo              = RESERVEDBYTE
  
 adtgCursorModel             = adtgCursorSnapshot     /
                               adtgCursorGreedyKeyset /
                               adtgCursorKeyset       /
                               adtgCursorUpdatableSnapshot
  
 adtgCursorSnapshot          = %x00
  
 adtgCursorGreedyKeyset      = %x01
  
 adtgCursorKeyset            = %x02
  
 adtgCursorUpdatableSnapshot = %x03
  
 adtgNormalization           = adtgNonNormalized /
                               adtgNormalized
  
 adtgNonNormalized           = %x00
  
 adtgNormalized              = %x01
  
 VisibleColumnsCount         = USHORT
  
 TotalColumnsCount           = USHORT
  
 ComputedColumnsCount        = USHORT
  
 TableCount                  = USHORT
  
 OrderByColumnsCount         = USHORT
  
 RowCount                    = ULONG

The fields of an adtgResultDescriptor element have the following lengths, types, and meanings:

  • adtgTokenResultDescriptor

    Length: 1 byte

    Identifies this component as an adtgResultDescriptor element. The value MUST be set to 0x03.

  • adtgTokenResultDescriptorSize

    Length: 2 bytes

    Datatype: USHORT

    Specifies the size, in bytes, of the remainder of the adtgResultDescriptor element. The value in this field is equal to the total size of the adtgResultDescriptor element, less the size of the adtgTokenResultDescriptor field (1 byte) and the size of the adtgTokenResultDescriptorSize field (2 bytes).

  • adtgGUIDResultDescriptor

    Length: 16 bytes

    Datatype: GUID

    A GUID that identifies a particular RecordSet descriptor in the TableGram.<51>

  • adtgResultInfo

    Length: 1 byte

    Datatype: RESERVEDBYTE

    Reserved and not used. This SHOULD be set to 0 and MUST be ignored on receipt.

  • adtgCursorModel

    Length: 1 byte

    Specifies the type of the cursor model represented by the RecordSet.<52>

     Value

     Meaning

    adtgCursorSnapshot

    0x00

    The TableGram contains only those columns that were explicitly selected.

    adtgCursorGreedyKeyset

    0x01

    The TableGram contains key columns, even if they were not explicitly selected, and all columns selected in the query.

    adtgCursorKeyset

    0x02

    Specifies that the transmission of data MUST be limited to only the key columns and values for update.

    adtgCursorUpdatableSnapshot

    0x03

    All original values of the selected columns are used to identify rows when submitting updates to the database.

  • adtgNormalization

    Length: 1 byte

    A flag that specifies if the row data will be transferred in a normalized form.

    The RDS Transport Protocol does not support normalization. This value MUST be set to 0x00.

     Value

     Meaning

    adtgNonNormalized

    0x00

    Not normalized

    adtgNormalized

    0x01

    Reserved

  • VisibleColumnsCount

    Length: 2 bytes

    Datatype: USHORT

    Specifies the total number of visible columns. A column is visible when its corresponding adtgColumnDescriptorParent or adtgColumnDescriptorChild element has the IsVisible field set to VARIANT_TRUE (0xFFFF).

  • TotalColumnsCount

    Length: 2 bytes

    Datatype: USHORT

    Specifies the total number of columns in the RecordSet, including the key columns and version columns added to the RecordSet by the server for keyset implementations. For snapshots, this count is the same as the VisibleColumnsCount. This field also determines how many adtgColumnDescriptorParent or adtgColumnDescriptorChild elements there will be in the adtgResultDescriptor element.

  • ComputedColumnsCount

    Length: 2 bytes

    Datatype: USHORT

    Specifies the number of computed columns (that is, those that are not present in any base table) in the RecordSet.

  • TableCount

    Length: 2 bytes

    Datatype: USHORT

    Specifies the number of base tables included in the current RecordSet. This value determines how many adtgTableDescriptor elements there will be in the adtgResultDescriptor element. If the RecordSet contains an adtgChildChange or an adtgParentChange element, the value MUST be 1.

  • OrderByColumnsCount

    Length: 2 bytes

    Datatype: USHORT

    Reserved and not used. This SHOULD be set to 0 and MUST be ignored on receipt.

  • RowCount

    Length: 4 bytes

    Datatype: ULONG

    Specifies the number of rows in the RecordSet. Set the value to 0x00000000 if a row count is not available.

  • adtgPropertySets

    Length: Variable

    If adtgPropertySets appears in adtgResultDescriptor, adtgTokenResultDescriptorSize MUST be greater than 33. If adtgPropertySets is omitted, adtgTokenResultDescriptorSize is 33. For more information, including a description of this field, see section 2.2.3.14.3.7.

A counted field is one of the following fields: VisibleColumnsCount, TotalColumnsCount, ComputedColumnsCount, TableCount, OrderByColumnsCount, and RowCount. A parent result descriptor is an adtgResultDescriptor element that is part of an adtgParentMetaInformation group. A child result descriptor is an adtgResultDescriptor element that is part of an adtgChildMetaInformation group.

The RecordSet used to calculate the value of a counted field varies for parent and child result descriptors. For parent result descriptors, the RecordSet used as a basis for calculation is the set of columns in the base table. For child result descriptors, the RecordSet used as a basis for calculation is the set of columns in the child RecordSet. For both parent and child result descriptors, if the request is to not persist the whole hierarchy (but only the parent RecordSet), then chapter columns are excluded from the set of columns forming the basis for calculation.