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