Share via

2.2.3.14.3.7 Common Fields in adtgAllMetaInformation

  • Article

The following common fields are used by the adtgResultDescriptor and adtgRecordSetContext elements of the adtgAllMetaInformation submessage.

  • adtgPropertySets

    Length: Variable

    A collection of property sets. The properties specified are RecordSet properties. The adtgPropertySets field contains exactly one adtgPropSetCount member and one or more adtgPropertySet members.

    The syntax of the adtgPropertySets field is defined as follows.

      adtgPropertySets            =  adtgPropSetCount *adtgPropertySet
             
  adtgPropSetCount            =  USHORT
             
  adtgPropertySet             =  GUIDPropertySet
                                 PropertyCount 
                                *adtgProperty
             
  GUIDPropertySet             =  GUID
             
  PropertyCount               =  USHORT
             
  adtgProperty                =  PropertyId PropertyValue
  PropertyId                  =  DWORD
  PropertyValue               =  BooleanProperty /
                                 IntegerProperty /
                                 StringProperty
             
  BooleanProperty             =  BooleanSize BooleanValue
  BooleanSize                 =  %x02.00
  BooleanValue                =  VARIANT-BOOL
             
  IntegerProperty             =  IntegerSize IntegerValue
  IntegerSize                 =  %x04.00
  IntegerValue                =  LONG
             
  StringProperty              =  BYTECOUNT-PREFIXED-STRING

    • adtgPropSetCount

      Datatype: USHORT

      Length: 2 bytes

      Specifies the number of property sets that are present.

    • adtgPropertySet

      Length: Variable

      Contains a collection of properties.

      The adtgPropertySet member contains one GUIDPropertySet member, one PropertyCount member, and one or more adtgProperty members, in that order.

    • GUIDPropertySet

      Datatype: GUID

      Length: 16 bytes

      Specifies the unique identity of a property set. The adtgTablegram uses the DBPROPSET_ROWSET and DBPROPSET_ADC property sets. See the PropertyId member for a list of valid properties for each property set.

      There are two possible values for the GUIDPropertySet member.

      Value

      Meaning

      C8B522BE-5CF3-11CE-ADE500AA0044773D

      The property set is of type DBPROPSET_ROWSET.

      B68E3CC1-6DEB-11D0-8DF600AA005FFE58

      The property set is of type DBPROPSET_ADC.

    • PropertyCount

      Datatype: USHORT

      Length: 2 bytes

      The number of properties in the property set.

    • adtgProperty

      Length: Variable

      Specifies a property identifier and the property value.

      The adtgProperty member contains exactly one PropertyId member and exactly one PropertyValue member, appearing in that order. One or more adtgProperty members can appear in sequence after the PropertyCount member. The number of adtgProperty members is specified by the value of the PropertyCount member.

    • PropertyId

      Datatype: DWORD

      Length: 4 bytes

      Specifies a unique identifier of the property

      The range of possible values for the PropertyId member depends on the value of the GUIDPropertySet member specified in the parent adtgPropertySet member.

      The following table shows the possible PropertyId values for a property set of type DBPROPSET_ROWSET; that is, a property set with the GUIDPropertySet value set to C8B522BE-5CF3-11CE-ADE500AA0044773D. All DBPROPSET_ROWSET properties are valid only for adtgRecordSetContext.

      PropertyId value

      Property name

      Description

      %x22.00.00.00

      DBPROP_COMMANDTIMEOUT

      Type: IntegerProperty

      Specifies the number of seconds for which a RecordSet implementation needs to wait for the data store to process the operation.

      %x7F.00.00.00

      DBPROP_IRecordSetChange

      Type: BooleanProperty

      Specifies if the RecordSet can be changed.

      VARIANT_TRUE (0xFFFF). The RecordSet can be changed.

      VARIANT_FALSE (0). The RecordSet is read-only.

      %x86.00.00.00

      DBPROP_IRecordSetUpdate

      Type: BooleanProperty

      Specifies if the changes to the RecordSet can be propagated to the originating server. The RDS Transport Protocol update mechanism MUST be used for propagation. For more information about the RDS Transport Protocol update mechanism, see the adtgParentChange and adtgChildChange elements.

      VARIANT_TRUE (0xFFFF). Changes to the RecordSet can be propagated to the originating server.

      VARIANT_FALSE (0). The RecordSet does not support the interface.

      %x49.00.00.00

      DBPROP_MAXROWS

      Type: IntegerProperty

      Specifies the maximum number of Rows that can be returned in this RecordSet.

      The following tables show the possible PropertyId values for a property set of type DBPROPSET_ADC; that is, a property set with the GUIDPropertySet value set to B68E3CC1-6DEB-11D0-8DF600AA005FFE58.

      The following values are encoded only if the data in the TableGram can be used without parsing the entire RecordSet. This means that the TableGram data could be processed further or displayed to the end user without parsing the whole RecordSet. Further parsing of the RecordSet can happen asynchronously.

      The following DBPROPSET_ADC properties are valid only for adtgRecordSetContext.

      PropertyId value

      Property name

      Description

      %x03.00.00.00

      "Background Fetch Size"<63>

      Type: IntegerProperty

      Default value: 15

      The number of Rows to fetch when parsing the RecordSet data incrementally.

      %x07.00.00.00

      "Initial Fetch Size"<64>

      Type: IntegerProperty

      Default value: 50

      The number of Rows to parse when the RecordSet is used. This is a hint to the receiver to parse the Rows up front.

      %x08.00.00.00

      "Background Thread Priority"<65>

      Type: IntegerProperty

      Default value: adPriorityNormal

      The allowed range of values is:

      • adPriorityLowest: 1

      • adPriorityBelowNormal: 2

      • adPriorityBelowNormal: 3

      • adPriorityBelowNormal: 4

      • adPriorityBelowNormal: 5

      The priority of the thread performing asynchronous or incremental operations, relative to the average system thread. An average system thread has priority adPriorityNormal.

      %x04.00.00.00

      "Batch Size"<66>

      Type: IntegerProperty

      Default value: 15

      The number of Rows to be batched together when changes to the RecordSet are propagated to the originating server.

      %x05.00.00.00

      "Update Criteria"

      Type: IntegerProperty

      Default value: 2 (adCriteriaUpdCols)

      Possible values include the following:

      • adCriteriaKey: 0

      • adCriteriaAllCols: 1

      • adCriteriaUpdCols: 2

      • adCriteriaTimeStamp: 3

      The criterion used to select the columns of an altered row included in a propagation message (such as an adtgParentChange element). This field tells the client how to identify rows in a record for a given action. If adCriteriaKey is sent, then the client only needs to return the fields for those columns that are marked as keys. adCriteriaAllCols means that the client needs to send all of the columns. adCriteriaUpdCols means that the client needs to send only the update columns. With adCriteriaTimeStamp, the client needs to include the time stamp column, because this column will be used to determine update status on the record in the data store.

      The following DBPROPSET_ADC properties are valid only for adtgResultDescriptor.

      PropertyId value

      Property name

      Description

      %x0B.00.00.00

      "Auto Recalc"

      Type: IntegerProperty

      Default Value: %x01.00.00.00

      Specifies when calculated expressions in the RecordSets obtained by executing a Shape command language query need to be recalculated. The range of allowed values is %x01.00.00.00 (always recalculate) and %x00.00.00.00 (recalculate on access). A value of %x00.00.00.00 is not valid in the context of the RDS Transport Protocol and SHOULD be ignored on receipt.

      The Server SHOULD set this property to %x 01.00.00.00 when the Shape command language is used, and omit it otherwise. Clients SHOULD never set this property, and Servers SHOULD ignore it on receipt.

      %x0D.00.00.00

      "Unique Table"

      Type: StringProperty

      Default Value: BSTRNULL

      Specifies the table (last part of a SQL-92 three-part name, as specified in [FIPS127]) to which the update or updates in this adtgTablegram need to be applied. When the original adtgTablegram that is retrieved from the data store is the result of a complex query containing nested joins or subqueries, update attempts can fail due to ambiguity about what part of the schema needs to be updated with the new value. This property is specified to target the update to a specific table in the data store.

      This property SHOULD be BSTRNULL when sent from the server to the client, and MUST be ignored by the client on receipt.

      %x0E.00.00.00

      "Unique Schema"

      Type: StringProperty

      Default Value: NULL-BPS

      Specifies the schema (middle part of a SQL-92 three-part name, as specified in [FIPS127]) to which the update or updates in this adtgTablegram need to be applied. When the original adtgTablegram that is retrieved from the data store is the result of a complex query containing nested joins or subqueries, update attempts can fail due to ambiguity about what part of the schema needs to be updated with the new value. This property is specified to target the update to a specific table in the data store.

      This property SHOULD be NULL-BPS when sent from the server to the client, and MUST be ignored by the client on receipt.

      %x0F.00.00.00

      "Unique Catalog"

      Type: StringProperty

      Default Value: NULL-BPS

      Specifies the catalog (first part of a SQL-92 three-part name, as specified in [FIPS127]) to which the update or updates in this adtgTablegram need to be applied. When the original adtgTablegram that is retrieved from the data store is the result of a complex query containing nested joins or subqueries, update attempts can fail due to ambiguity about what part of the schema needs to be updated with the new value. This property is specified to target the update to a specific table in the data store.

      This property SHOULD be NULL-BPS when sent from the server to the client, and MUST be ignored by the client on receipt.

      %x10.00.00.00

      "Resync Command"

      Type: StringProperty

      Default Value: NULL-BPS

      Specifies the query that is executed on the data store to refresh the data in the adtgRecordset after update, insert, and delete operations have been applied.

      %x12.00.00.00

      "Reshape Name"

      Type: StringProperty

      Default Value: NULL-BPS

      Specifies a unique name for each RecordSet in an adtgTablegram that is generated from a Shape command language query.

      Clients SHOULD NOT set this property or allow its value to be modified. Servers MUST ignore the value of this property on receipt if it is set or changed by a client.

      Servers SHOULD<67> set this property to a unique value for every RecordSet when the Shape command language is used to specify a query.

      Clients can ignore this value on receipt.

      %x13.00.00.00

      "Update Resync"<68>

      Type: IntegerProperty

      Default value: 1

      Defines if the update operation on the RecordSet is followed by an implicit synchronize operation. The scope of the implicit synchronize can be the rows that have conflicts or the entire set of rows in the RecordSet.

      The following are valid values for this property. Implementations can extend this list as appropriate, and are not required to support all update resync modes.

      • adResyncNone

        Value=0

        No auto-resynchronization performed.

      • adResyncAutoIncrement

        Value=1

        Auto-resynchronization, autoincrement columns for inserted rows.

      • adResyncConflicts

        Value=2

        Auto-resynchronization performed on rows with conflicts.

      • adResynchUpdates

        Value=4

        Auto-resynchronization performed on any successfully updated row.

      • adResyncInserts

        Value=8

        Auto-resynchronization performed on any newly inserted rows.

      • adResyncAll

        Value=15

        Auto-resynchronization performed on all columns for all changes; acts as a shortcut for all the others.

      The adRsyncAutoIncrement, adResyncUpdates, adResyncInserts, and adResyncConflicts values can be used simultaneously.

      The resynchronization operation performed in adResyncConflicts is very different from the other two because it stores the resync values as underlying values but does not override pending changes.

    • PropertyValue

      Length: Variable

      Contains a BooleanProperty, an IntegerProperty, or a StringProperty.

      The PropertyValue member MUST contain a BooleanProperty if the PropertyId has a value of 0x7F (DBPROP_IRecordSetChange) or 0x86 (DBPROP_IRecordSetUpdate); otherwise, the PropertyValue member MUST contain an IntegerProperty or a StringProperty.

    • BooleanProperty

      Contains a Boolean property value. The BooleanProperty member contains the following members.

      Term

      Description

      BooleanSize

      Length: 2 bytes

      Indicates that the following member contains a Boolean value, and gives the size, in bytes, of the Boolean value. The value in the BooleanSize member MUST be %x02.00.

      BooleanValue

      Datatype: VARIANT-BOOL

      Length: 2 bytes

      A Boolean property value.

    • IntegerProperty

      Contains an integer property value. The IntegerProperty member contains the following members.

      Term

      Description

      IntegerSize

      Length: 2 bytes

      Specifies that the following member contains an integer value, and gives the size, in bytes, of the integer value. The value in the IntegerSize member MUST be %x04.00.

      IntegerValue

      Datatype: LONG

      Length: 4 bytes

      An integer property value.

    • StringProperty

      Contains a BYTECOUNT-PREFIXED-STRING, which is a Unicode character string prefixed by its length, in bytes.

  • RelationConditions

    RelationConditions specifies a relationship between a column in the parent table (specified by the containing adtgResultDescriptor) and a related column in a child RecordSet. The relationship is defined according to the following rules:

    • Child RecordSets containing related columns MUST be in the same order as the RelationConditions fields for the parent table. There is one RelationConditions field for each chapter column in the table.

    • The column in the parent table is specified by the ParentColumnOrdinal value.

    • The related column in the child RecordSet is specified by the ChildColumnOrdinal.

    The syntax of RelationConditions is as follows.

     RelationConditions = RelationConditionsSize
                      RelationConditionsData
                      ZEROBYTE
                      ZEROBYTE
                      ZEROBYTE
                      ZEROBYTE
            
 RelationConditionsSize = ULONG
 RelationConditionsData = ParentColumnOrdinal
                          ChildColumnOrdinal
                          RelationType
            
 ParentColumnOrdinal = ULONG
 ChildColumnOrdinal  = ULONG
 RelationType        = ULONG

    • RelationConditionsSize: Specifies the size of RelationConditionsData, in bytes. The value of RelationConditionsSize MUST be the constant 12 (%x0C.00.00.00).

    • ParentColumnOrdinal: Specifies the ordinal of the related column in the parent table. The value of ParentColumnOrdinal MUST be the value in the primary key column's ColumnOrdinal.

    • ChildColumnOrdinal: Specifies the ordinal of the column in the child RecordSet. The value of ChildColumnOrdinal MUST be the value in the child RecordSet column's ColumnOrdinal.

    • RelationType: Specifies properties of the relationship. The value of RelationType MUST be one of the values in the following table.

      Value

      Meaning

      %x00.00.00.00 (RelationType_Relation)

      The relationship described by the RelationType is a foreign key relationship ([FIPS127]), and the column specified by ParentColumnOrdinal is the primary key.

      %x01.00.00.00 (RelationType_Grouped)

      The relationship is the result of a "GROUP BY clause" ([FIPS127]) of a SQL command or equivalent instruction. The rows in the related table MUST share a value with the column in the parent table matching ChildColumnOrdinal.

      %x02.00.00.00(RelationType_GrandTotal)

      The value in the column specified by ParentColumnOrdinal MUST be the sum of the values in the column specified by ChildColumnOrdinal.

  • CalculationInfo:

    Specifies the computation of a column. The following rules apply:

    • If FunctionType is FunctionType_Expression or FunctionType_AggregateExpression, then the calculation is the expression specified by the string CalculationExpression.

    • For all other values of FunctionType, the aggregation function specified by FunctionType is computed on the column specified by the ChildColumnOrdinal on the ChildRecordSet.

    The syntax of CalculationInfo is as follows.

      CalculationInfo = (CalculationInfoSize CalculationInfoData)\
                    CalculationInfoNull
             
  CalculationInfoSize = ULONG
  CalculationInfoData = FunctionType
                        ChapterColumnOrdinal
                        ChildColumnOrdinal
                        CalculationExpression
             
  FunctionType          = ULONG
  ChapterColumnOrdinal  = ULONG
  ChildColumnOrdinal    = ULONG
  CalculationExpression = BYTECOUNT-PREFIXED-STRING
             
  CalculationInfoNull  = %x01.00.00.00 ZEROBYTE

    • CalculationInfoSize: Specifies the size of CalculationInfoData, in bytes.

    • FunctionType: Specifies the type of function used to calculate values in this column. The value of FunctionType MUST be one of the values in the following table.

      Value

      Meaning

      %x00.00.00.00 (FunctionType_Expression)

      The function is the expression specified by the string CalculationExpression. ChapterColumnOrdinal and ChildColumnOrdinal MUST be ignored if this value is specified.

      %x01.00.00.00

      (FunctionType_AggregateExpression)

      The function is the aggregate expression specified by the string CalculationExpression. ChapterColumnOrdinal and ChildColumnOrdinal MUST be ignored if this value is specified.

      %x02.00.00.00 (FunctionType_Sum)

      The function is the arithmetic sum.

      %x03.00.00.00 (FunctionType_Average)

      The function is the arithmetic mean.

      %x04.00.00.00 (FunctionType_Maximum)

      The function is the maximum, defined as returning the largest value.

      %x05.00.00.00 (FunctionType_Minimum)

      The function is the minimum, defined as returning the smallest value.

      %x06.00.00.00 (FunctionType_Count)

      The function is the count of rows.

      %x07.00.00.00 (FunctionType_StandardDeviation)

      The function is the arithmetic standard deviation.

    • ChapterColumnOrdinal: Specifies the ordinal of the chapter column in the table whose RelationConditions field identifies the child RecordSet.

    • ChildColumnOrdinal: Specifies the ordinal of the column in the child RecordSet.

    • CalculationExpression: Specifies a data store-specific command expression that describes how values in the current column are computed from values in the column of the child RecordSet. CalculationExpression MUST be set to a zero-length string and ignored on receipt unless FunctionType is FunctionType_Expression or FunctionType_AggregateExpression.