Share via

2.2.7.19 RETURNVALUE

  • Article

Token Stream Name:

 RETURNVALUE

Token Stream Function:

Used to send the return value of an RPC to the client. When an RPC is executed, the associated parameters might be defined as input or output (or "return") parameters. This token is used to send a description of the return parameter to the client. This token is also used to describe the value returned by a UDF when executed as an RPC.

Token Stream Comments:

  • The token value is 0xAC.

  • Multiple return values can exist per RPC. There is a separate RETURNVALUE token sent for each parameter returned.

  • Large Object output parameters are reordered to appear at the end of the stream. First the group of small parameters is sent, followed by the group of large output parameters. There is no reordering within the groups.

  • A UDF cannot have return parameters. As such, if a UDF is executed as an RPC there is exactly one RETURNVALUE token sent to the client.

Token Stream-Specific Rules:

 TokenType        =   BYTE
 ParamName        =   B_VARCHAR
 ParamOrdinal     =   USHORT
 Status           =   BYTE
 UserType         =   USHORT/ULONG; (Changed to ULONG in TDS 7.2)
  
  
 fNullable        =   BIT
 fCaseSen         =   BIT
 usUpdateable     =   2BIT            ; 0 = ReadOnly
                                      ; 1 = Read/Write
                                      ; 2 = Unused
  
 fIdentity        =   BIT
 fComputed        =   BIT             ; (introduced in TDS 7.2)
 usReservedODBC   =   2BIT
 fFixedLenCLRType =   BIT             ; (introduced in TDS 7.2)
 usReserved       =   7BIT
 usReserved2      =   2BIT
 fEncrypted       =   BIT             ; (introduced in TDS 7.4)
 usReserved3      =   4BIT
  
 Flags            =   fNullable
                      fCaseSen
                      usUpdateable
                      fIdentity
                      (FRESERVEDBIT / fComputed)
                      usReservedODBC
                      (FRESERVEDBIT / fFixedLenCLRType)
  
                      (usReserved   / (usReserved2 fEncrypted usReserved3))
                                      ; (introduced in TDS 7.4)
  
 TypeInfo         =   TYPE_INFO
 Value            =   TYPE_VARBYTE
 BaseTypeInfo     =   TYPE_INFO       ; (BaseTypeInfo introduced in TDS 7.4)
  
 EncryptionAlgo   =   BYTE            ; (EncryptionAlgo introduced in TDS 7.4)
  
 AlgoName         =   B_VARCHAR       ; (introduced in TDS 7.4)
  
 EncryptionAlgoType =   BYTE          ; (introduced in TDS 7.4)
  
 NormVersion        =   BYTE          ; (introduced in TDS 7.4)
  
 CryptoMetaData     =   UserType      ; (CryptoMetaData introduced in TDS 7.4)
                        BaseTypeInfo
                        EncryptionAlgo
                        [AlgoName]
                        EncryptionAlgoType
                        NormVersion

Token Stream Definition:

 RETURNVALUE      =   TokenType
                      ParamOrdinal
                      ParamName
                      Status
                      UserType
                      Flags
                      TypeInfo
                      CryptoMetadata
                      Value

Token Stream Parameter Details:

Parameter

Description

TokenType

RETURNVALUE_TOKEN

ParamOrdinal

Indicates the ordinal position of the output parameter in the original RPC call. Large Object output parameters are reordered to appear at the end of the stream. First the group of small parameters is sent, followed by the group of large output parameters. There is no reordering within the groups.

ParamName

The parameter name length and parameter name (within B_VARCHAR).

Status

0x01: If ReturnValue corresponds to OUTPUT parameter of a stored procedure invocation.

0x02: If ReturnValue corresponds to return value of User Defined Function.

UserType

The user type ID of the data type of the column. Depending on the TDS version that is used, valid values are 0x0000 or 0x00000000, with the exceptions of data type timestamp (0x0050 or 0x00000050) and alias types (greater than 0x00FF or 0x000000FF).

Flags

These bit flags are described in least significant bit order. All of these bit flags SHOULD be set to zero. For a description of each bit flag, see section 2.2.7.4.

  • fNullable

  • fCaseSen

  • usUpdateable

  • fIdentity

  • fComputed

  • usReservedODBC

  • fFixedLengthCLRType

  • fEncrypted

TypeInfo

The TYPE_INFO for the message.

BaseTypeInfo

TYPE_INFO for the unencrypted type.

EncryptionAlgo

A byte that describes the encryption algorithm that is used. AlgoName is populated with the name of the custom encryption algorithm. For all EncryptionAlgo values other than 0, AlgoName MUST NOT be sent. If EncryptionAlgo is set to 1, the algorithm that is used is AEAD_AES_256_CBC_HMAC_SHA512, as described in [IETF-AuthEncr] section 5.4.

AlgoName

Algorithm name literal that is used to encrypt the plaintext value.

EncryptionAlgoType

A field that describes the encryption algorithm type. Available values are defined as follows:

1 = Deterministic encryption.

2 = Randomized encryption.

NormVersion

The normalization version to which plaintext data MUST be normalized. Version numbering starts at 0x01.

CryptoMetaData

This describes the encryption metadata for a column. It contains the UserType, the TYPE_INFO (BaseTypeInfo) for the plaintext value, the encryption algorithm that is used, the algorithm name literal, the encryption algorithm type, and the normalization version.

Value

The type-dependent data for the parameter (within TYPE_VARBYTE).