2.2.3.13.7 rdsSQLCommandParameters

The rdsSQLCommandParameters specifies the parameter information for an rdsSQLCommandString, and is used in one of two ways.

  • To send parameter information to an execute request.

  • To return the parameter information for a given command. rdsExecuteOptions MUST be set to rdsExecuteGetInfo.

The syntax of rdsSQLCommandParameters is as follows:

 rdsSQLCommandParameters = VT-ARRAY-VARIANT 
                           ZEROBYTE 
                           rdsPVWNumDims
                           rdsPVWArrayFeatures
                           rdsPVWElementSize
                           rdsPVWArraySize
                           rdsPVWLowerBound
                           ( 1*(rdsSQLCommandParameterArray) /
                             VT-EMPTY )

Sending rdsSQLCommandParameters set to VT-EMPTY designates that parameters are not included in this execute request. The client MUST send one rdsSQLCommandParameters for each parameter in the rdsSQLCommandString.

  • rdsPVWNumDims: MUST be set to 1.

     rdsPVWNumDims = %x01.00 
    
  • rdsPVWArrayFeatures: MUST be %x80 %x28.

     rdsPVWArrayFeatures = %x80 %x28 
    
  • rdsPVWElementSize: This is an array of variants. It MUST be set to 16.

     rdsPVWElementSize = %x10.00.00.00 
    
  • rdsPVWArraySize: MUST be set to the number of parameters that are being sent.

     rdsPVWArraySize = ULONG
    
  • rdsPVWLowerBound: MUST set to zero.

     rdsPVWLowerBound = %x00.00.00.00  
    
  • rdsSQLCommandParameterArray: An array that specifies the data for a single parameter.

     rdsSQLCommandParameterArray = VT-ARRAY-VARIANT 
                                   ZEROBYTE 
                                   rdsSCPNumDims
                                   rdsSCPArrayFeatures
                                   rdsSCPElementSize
                                   rdsSCPArraySize
                                   rdsSCPLowerBound
                                   ( *(rdsSQLCommandParameter) /
                                     VT-EMPTY )
    
  • rdsSCPNumDims: The number of dimensions of the rdsSQLCommandParameterArray MUST be 1.

     rdsSCPNumDims = %x01.00
    
  • rdsSCPArrayFeatures: Specifies that the rdsSQLCommandParameterArray uses the FADF-RECORD-BIT optimization and has the FADF-VARIANT-TYPE. See section 2.2.1.7 for details.

     rdsSCPArrayFeatures = %x80.08
    
  • rdsSCPElementSize: Specifies that the rdsSQLCommandParameterArray is composed of 16-byte elements.

     rdsSCPElementSize = %x10.00.00.00
    
  • rdsSCPArraySize: Specifies that each parameter is encoded as an 8-element array.

     rdsSCPArraySize = %x08.00.00.00
    
  • rdsSCPLowerBound: MUST always be zero-based.

     rdsSCPLowerBound = %x00.00.00.00
    
  • rdsSQLCommandParameter: Holds the parameter metadata and the parameter value. It has the following syntax.

     rdsSQLCommandParameter = paramFlags
                              (paramName / VT-EMPTY)
                              (paramPrecision / VT-EMPTY)
                              (paramNumericScale / VT-EMPTY)
                              (paramSize / VT-EMPTY)
                              (paramType / VT-EMPTY)
                              paramValue
                              (paramMeta / paramOrdinal)
    
  • paramPrecision: Specifies the precision of a numeric parameter.

     paramPrecision = VT-UI1 BYTE
    
  • paramNumericScale: Specifies the scale of a numeric value.

     paramNumericScale = VT-UI1 BYTE
    
  • paramSize: Specifies the fixed size of the parameter. If the parameter is a string, then this is the length of the string.

     paramSize = VT-I4 LONG
    
  • paramMeta: Specifies if this parameter value includes the metadata information or if this parameter only contains the value. The metadata information includes paramName, paramType, paramNumericScale, and paramPrecision. If paramMeta is paramDataOnly, only the paramValue field is used; other fields can safely be set to VT-EMPTY. Also, with paramMeta set to paramDataOnly, parameter binding is determined by the parameter's position in the rdsSQLCommandParameters array of parameters.

    This field MUST NOT appear in rdsSQLCommandParameters in a response.

     paramMeta        = paramDataOnly / paramIncludeMeta
     paramDataOnly    = %x00
     paramIncludeMeta = %x01
    
  • paramFlags: Specify attributes of a parameter.

     paramFlags = VT-I4 ParamBitFlags
    
  • ParamBitFlags

    Length: 4 bytes

    Datatype: LONG

     ParamBitFlags    = LONG
    

    Each flag occupies 1 bit. Of the 32 bit flags, the following table describes the six that are used. The other flags are unused or reserved, and SHOULD be set to zero and ignored on receipt.

    Name and bit value

    Meaning

    paramReturnValue

    %x40.00.00.00

    Set to 1 to indicate that the parameter is a return value.

    paramOutput

    %x20.00.00.00

    Set to 1 to indicate that the parameter value is an output parameter.

    paramInput

    %x10.00.00.00

    Set to 1 to indicate that the parameter value is an input parameter.

    paramIsLong

    %x08.00.00.00

    Set to 1 if the parameter contains a long stream of data.

    paramNullable

    %x04.00.00.00

    Set to 1 if the parameter can be null (as specified in [FIPS127]).

    paramSigned

    %x01.00.00.00

    Set to 1 if the numeric parameter contains signed content.

  • paramOrdinal: The ordinal value of this parameter in the SQL command. Determined by counting the number of parameter markers, starting with the leftmost parameter marker.

    This field MUST NOT appear in rdsSQLCommandParameters in a request.

     paramOrdinal = VT-I4 LONG
    
  • paramName: Used for named binding of parameters.

     paramName = VT-EMPTY / (VT-BSTR BSTRNULLABLE)
    

    If the command language provides for the naming of parameters, this value can be used to reference the parameter by that name. The default language for RDS Transport Protocol command is SQL-92, and SQL-92 does not provide for parameter naming.

    Implementers can extend the RDS command language to provide a parameter naming mechanism.

  • paramType: Determines the data type of the parameter. The types are defined in section 2.2.1.

     paramType = VT-I4 VTDataType %x00.00
    
  • paramValue: The actual value of the parameter data.

     paramValue = rdsNonGroupableParam /
                  rdsGroupableParam