2.2.3.14.2 adtgHandlerOptions

  • Article

An adtgHandlerOptions submessage specifies how the TableGram is handled. This component is used by the source process (the process that generates the TableGram) to communicate handling specifics to the receiving process.

The syntax of the adtgHandlerOptions submessage is defined as follows.

 adtgHandlerOptions      = adtgTokenHandlerOptions
                           adtgTokenHandlerOptionsSize
                           adtgRecordSetGUID
                           adtgUpdateTableGramType
                           adtgOriginalURL
                           adtgUpdateURL
                           adtgFriendlyName
                           adtgAsyncOptions
  
 adtgTokenHandlerOptions = %x02
  
 adtgTokenHandlerOptionsSize = USHORT
  
 adtgRecordSetGUID       = %xB6 %x92 %xF2 %x3F 
                           %x04 %xB2 %xCF %x11
                           %x8D %x23 %x00 %xAA
                           %x00 %x5F %xFE %x58
  
 adtgUpdateTableGramType = adtgUpdateColumnsOnly / 
                           adtgUpdateRowsOnly / 
                           adtgUpdateAllRows
  
 adtgUpdateColumnsOnly   = %x01
 adtgUpdateRowsOnly      = %x02
 adtgUpdateAllRows       = %x03
  
 adtgOriginalURL         = LENGTH-PREFIXED-STRING
 adtgUpdateURL           = LENGTH-PREFIXED-STRING
 adtgFriendlyName        = LENGTH-PREFIXED-STRING
  
 adtgAsyncOptions        = adtgAsyncOptionSynch /
                           adtgAsyncOptionAsynchBlocking /
                           adtgAsyncOptionAsynchNonBlocking
  
 adtgAsyncOptionSynch             =  %x01.00
 adtgAsyncOptionAsynchBlocking    =  %x02.00
 adtgAsyncOptionAsynchNonBlocking =  %x03.00

The fields of the adtgHandlerOptions submessage have the following lengths, types, and meanings:

  • adtgTokenHandlerOptions

    Length: 1 byte

    Datatype: BYTE

    Identifies this component as an adtgHandlerOptions submessage. The value MUST be set to 0x02.

  • adtgTokenHandlerOptionsSize

    Length: 2 bytes

    Datatype: USHORT

    Specifies the length of the rest of the adtgHandlerOptions submessage. The value is variable and does not include the length of the adtgTokenHandlerOptions and adtgTokenHandlerOptionsSize fields.

  • adtgRecordSetGUID

    Length: 16 bytes

    Datatype: GUID

    Contains the class identifier of an object; a GUID that is used as a processing instruction to the receiver of the TableGram.<47>

  • adtgUpdateTableGramType

    Length: 1 byte

    Datatype: BYTE

    Specifies the type of information included in an update message. The value is fixed at 0x01. Other values of adtgUpdateTableGramType MUST NOT be specified by a server, and SHOULD be treated as 0x01 when received by a client.

     Value

     Meaning

    adtgUpdateColumnsOnly

    0x01

    Send only the updated columns of each row. The key columns and version columns are also sent.

    adtgUpdateRowsOnly

    0x02

    Send only the updated rows. The updated columns of each row along with the original values are sent. The key columns and version columns are also sent. This value is reserved but not supported.

    adtgUpdateAllRows

    0x03

    Send all of the initially selected rows, both updated and not updated. All columns of a row are sent. This value is reserved but not supported.

  • adtgOriginalURL

    Length: Variable

    Datatype: LENGTH-PREFIXED-STRING

    Specifies the source of the TableGram as a URL. The first two bytes of this field store the length, in bytes, of the string, which follows. Supplying a URL is not required, and a zero-length string MAY<48> be safely used.

  • adtgUpdateURL

    Length: Variable

    Datatype: LENGTH-PREFIXED-STRING

    Reserved and not used. This SHOULD be set to a zero-length string and MUST be ignored on receipt.

  • adtgFriendlyName

    Length: Variable

    Datatype: LENGTH-PREFIXED-STRING

    Specifies the human-readable name of the table handler that generated the TableGram. If the length is zero, no name is supplied.<49>

  • adtgAsyncOptions

    Length: 2 bytes

    Datatype: USHORT

    The adtgAsyncOptions is used as a hint to the client on the suggested method for loading the RecordSet into memory.<50>

     Value

     Meaning

    adtgAsyncOptionsSync

    0x0001

    Fetch row data synchronously.

    adtgAsyncOptionsBlocking

    0x0002

    Fetch row data asynchronously while blocking.

    adtgAsyncOptionsNonBlocking

    0x0003

    Fetch row data asynchronously while not blocking.