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.