2.2.1.4 Variable-Length Types

  • Article

The following specifies groupable data types of variable length. The data length appears in a known location in the data. 

 VAR-LEN-VTDATA-GROUPABLE = (VT-BSTR BSTRNULLABLE) /
                            (VT-ERROR VARIANTERROR)

  • VT-BSTR:

    Designated datatype: BSTRNULLABLE

    A 2-byte-aligned Unicode string. The syntax of BSTRNULLABLE is:

     BSTRNULLABLE    = BSTRNULL / BSTRNONNULLABLE
 BSTRNULL        = ZEROULONG NULLDICATOR
 BSTRNONNULLABLE = BSTRLENGTH BSTRVAL
 BSTRLENGTH      = ULONG
 BSTRVAL         = *(UNICODECHAR)
 NULLDICATOR     = %x00.00

    The length of BSTRVAL, in bytes, MUST be equal to the value in BSTRLENGTH. Note that BSTRLENGTH is the length of the string in bytes, not in characters. Also note that BSTRs are not null-terminated.

    Common BSTR constructs

      
 BSTR        = (VT-BSTR BSTRNULLABLE) 
 BSTREMPTY   = BSTR / VT-EMPTY
  
 UHEXDIGIT   = HEXDIGIT %x00
 HEXDIGIT    = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
  
 GUIDBSTRLEN = %x4C.00.00.00
 GUIDBSTRVAL = "{" %x00 8UHEXDIGIT 3("-" %x00 4UHEXDIGIT) "-" %x00
 GUIDBSTR    = (VT-BSTR GUIDBSTRLEN GUIDBSTRVAL) / VT-EMPTY

  • VT-ERROR:

    Designated datatype: VARIANTERROR

    Specifies errors and related information that allow the recipient of an RDS Transport Protocol message to determine the appropriate course of action or to send a failure message to the end user. The syntax of VARIANTERROR is as follows:

     VARIANTERROR        = SCODE [EXCEPINFO] 
 SCODE               = LONG
 EXCEPINFO           = SCODE2 BSTRSOURCE BSTRDESCRIPTION BSTRHELPFILE
 SCODE2              = LONG
 BSTRSOURCE          = BSTRNULLABLE
 BSTRDESCRIPTION     = BSTRNULLABLE
 BSTRHELPFILE        = BSTRNULLABLE
 DB-S-ERRORSOCCURRED = %xDA.0E.04.00

    • EXCEPINFO: Contains additional descriptive information about the error. EXCEPINFO MUST be present if the MOST significant bit of SCODE (corresponding to bitmask %x00.00.00.80) is set to 1 or if SCODE is equal to DB-S-ERRORSOCCURRED. EXCEPINFO MUST NOT be present otherwise.

    • BSTRSOURCE, BSTRDESCRIPTION, BSTRHELPFILE: Friendly descriptions of the error. The information in these strings can be ignored by the recipient with no harm to the flow of RDS Transport Protocol communication, and the sender can set these strings to BSTRNULL with no ill effect.

    • SCODE: The SCODE MUST comply with the syntax and semantics of HRESULT values, as specified in [MS-ERREF] section 2.1. For more details on the use of SCODEs in RDS Transport Protocol messages, see section 3.3.5.1.2.

    • SCODE2: The SCODE2 can be equal to the value of SCODE. If specified as a different value than SCODE, which can be done at the implementer's discretion, it is considered informative to the end user and not a determining factor of protocol behavior. The SCODE2 MUST comply with the syntax and semantics of HRESULT values, as specified in [MS-ERREF] section 2.1. For more details on the use of SCODEs in RDS Transport Protocol messages, see section 3.3.5.1.2.<12>

    • DB-S-ERRORSOCCURRED: Specifies an error condition in which the rowset was opened, but one or more properties failed to be set.