MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 6: Getting and Setting Data

Setting Data

To set data—for example, with IRowsetChange::SetData for rowset data or ICommand::Execute for input parameter data—the consumer must perform the following actions:

1. Create an accessor to bind the columns or input parameters.
   
   
2. Allocate a buffer to hold the data to pass to the provider.
   
   
3. Place data in this buffer. (For more information, see the next procedure.)
   
   
4. Call a method that sets data and passes the handle to the accessor and a pointer to the buffer.

For each column or input parameter specified in the accessor, the consumer performs the following actions. When passing key values to an index rowset, the consumer performs these actions only for the number of key columns specified in the cKeyValues argument in IRowsetIndex::Seek or in the cStartKeyValues or cEndKeyValues arguments in IRowsetIndex::SetRange.

Note   This procedure assumes that the consumer has bound the value, length, and status for each column or input parameter. If any of these are not bound, the actions to be performed are the same except that the consumer does not set the unbound part.

1. If the data is NULL, the consumer sets the status to DBSTATUS_S_ISNULL and proceeds to the next column or input parameter.

   If the provider is to use the default as the input value for an input or input/output parameter in a procedure, or if the provider updates the column, the consumer sets the status to DBSTATUS_S_DEFAULT and proceeds to the next column or input parameter.

   If the provider is to ignore this column in performing an insert or update, the consumer sets the status to DBSTATUS_S_IGNORE.

   Otherwise, the consumer sets the status to DBSTATUS_S_OK.

   The address where the status value is stored is calculated from the buffer address passed to the method and the obStatus element of the binding.

2. If wType is a variable-length data type, the consumer sets the length to the length of the data in bytes, not counting the null-termination character for strings.

   For all other data types, the provider ignores the length, so the consumer does not need to set it.

3. The consumer sets the data value.
   
   The address where the data value is stored is calculated from the buffer address passed to the method and the obValue element of the binding. If wType is DBTYPE_BSTR or is combined with DBTYPE_BYREF, DBTYPE_VECTOR, or DBTYPE_ARRAY, the consumer stores the data in separately allocated memory and stores in its buffer a pointer to the data. For information about how this memory is allocated and freed, see "Responsibility for Freeing Memory," earlier in this chapter.

For each column or input parameter specified in the accessor, the provider performs the following actions. When passing key values to an index rowset, the provider performs this procedure only for the number of key columns specified in the cKeyValues argument in IRowsetIndex::Seek or in the cStartKeyValues or cEndKeyValues arguments in IRowsetIndex::SetRange. This procedure assumes that the consumer has bound the value, length, and status for each column or input parameter. If any of these are not bound, the procedure is the same except that the provider does not attempt to retrieve the unbound part from the consumer's buffer. For more information, see "Binding Data Values," earlier in this chapter.

1. If it has not already done so, the provider validates the accessor against the metadata.
   
   The provider can validate the entire accessor before setting any data or on a binding-by-binding basis while setting data. If validation fails before the provider sets data, the provider produces the appropriate return code and does not set any data. If it fails when the provider is setting data, the provider sets the status to DBSTATUS_E_BADACCESSOR and proceeds to the next column or output parameter.
   
   
2. The provider retrieves the status value from the consumer's buffer, depending on the status setting, as follows:
   • DBSTATUS_S_ISNULL—The provider uses a null value and proceeds to the next column or input parameter.
     
     
   • DBSTATUS_S_DEFAULT—The provider uses the default value and proceeds to the next column or input parameter.
     
     
   • DBSTATUS_S_IGNORE—The provider skips the column and proceeds to the next column to be inserted or updated. 
     
     
   • DBSTATUS_S_OK—The provider proceeds to the next step.

   If the status is any other value, the provider sets the status to DBSTATUS_E_BADSTATUS and proceeds to the next column or input parameter.

   The address from which the status value is retrieved is calculated from the buffer address passed to the method and the obStatus element of the binding.

3. If wType is a variable-length data type, the provider retrieves the length from the consumer's buffer.

   For all other data types, the provider ignores the length. The address from which the length value is retrieved is calculated from the buffer address passed to the method and the obLength element of the binding.

4. The provider retrieves the data value from the consumer's buffer. The address from which the data value is retrieved is calculated from the buffer address passed to the method and the obValue element of the binding.
   • Variable-length data types—The provider retrieves the number of bytes of variable-length data as specified by the length, up to cbMaxLen bytes. It is usually a consumer programming error if the length is greater than cbMaxLen. If no length is bound, the provider retrieves strings up to the first null-termination character.
     
     
   • Fixed-length data types—The provider retrieves the number of bytes of fixed-length data from the consumer's buffer based on the size of the data type. It ignores cbMaxLen, as well as the bound length pointed to at the offset indicated by obLength.

     If the type indicator is DBTYPE_IUNKNOWN or DBTYPE_IDISPATCH, the provider retrieves a pointer to an interface on the object from the consumer's buffer. For information about how the provider retrieves the object itself, see Chapter 7, "BLOBs and COM Objects."

     If the type indicator is DBTYPE_BSTR, the provider retrieves the pointer to the BSTR from the consumer's buffer and the BSTR itself from the memory to which this pointer points. The provider ignores cbMaxLen. That is, it does not truncate the BSTR to cbMaxLen bytes.

   • DBTYPE_BYREF—The provider retrieves a pointer to the data from the consumer's buffer and the data from the memory to which this pointer points. The provider retrieves the data from this memory as if it were retrieving it directly from the consumer's buffer, except that it always ignores cbMaxLen, even when DBTYPE_BYREF is combined with DBTYPE_STR, DBTYPE_WSTR, DBTYPE_VARNUMERIC, or DBTYPE_BYTES.

     Note   It is an error to combine DBTYPE_BYREF and DBTYPE_BYTES with no bound length.

   • DBTYPE_VECTOR—The provider retrieves a pointer to an array of data and a count of the number of elements in the array from a DBVECTOR structure in the consumer's buffer. It retrieves the data itself from the array to which this pointer points. The provider retrieves the data from this memory as if it were retrieving it directly from the consumer's buffer.
     
     
   • DBTYPE_ARRAY—The provider retrieves a pointer to a SAFEARRAY structure from the consumer's buffer. It retrieves the data from the SAFEARRAY to which this pointer points.
5. The provider converts the data from the type that is stored in the consumer's buffer, as specified by the wType element of the binding, to the type of the column or input parameter.

   If an error occurs while converting the data, the provider sets the status accordingly and proceeds to the next column or output parameter. For a list of status values that describe conversion errors, see "Status Values Used When Setting Data" in "Status," earlier in this chapter. For more information about converting data, see "Data Type Conversion Rules" in Appendix A, "Data Types."

If the provider encounters an error while retrieving a column or input parameter value, it sets the status value of that column or input parameter. Depending on the provider, it also does one of the following:

• Stops processing and backs out any changes already made
  
  
• Stops processing and leaves any changes already made
  
  
• Continues processing the remaining columns or input parameters

If the provider stops processing, it must set the status value to DBSTATUS_E_UNAVAILABLE for any column or input parameter that was not in error and was not successfully set. Thus, the consumer can determine which column or input parameter values were valid, which were invalid, and which were not validated.

When setting column data, except when searching for a key value or setting the index range, the provider then produces one of the following return codes:

• DB_S_ERRORSOCCURRED—The method successfully set data for at least one column.
  
  
• DB_E_ERRORSOCCURRED—The method did not successfully set data for any columns.

When setting input parameter data, searching for a key value, or setting the index range, the provider then returns DB_E_ERRORSOCCURRED.