Structure CPData

        CPData is shown in the following.

        CPData is used with CBatchParam<T>::DoBatch for sending multiple sets of parameter data into a data source or with CBulkRecordParam<T>::GetBulkRecord for obtaining a new rowset with a set of new parameter data without closing its underlying command object. For how to use it, see examples BLOBs, MultiProcs, Scroll and MultiRecords.

        It is somewhat confusing to set a CPData structure when a data type is not one of fix-length types. For setting m_nLen correctly when a parameter data type is one of variable-length types, it is a must to follow these rules.

  1. When a parameter type is DBPARAMIO_INPUT and its data type is DBTYPE_BYTES, DBTYPE_IUNKNOWN (BLOB) or DBTYPE_VARNUMERIC, it is a must to set m_nLen.
  2. When a parameter type is DBPARAMIO_INPUT and its data type is DBTYPE_STR or DBTYPE_WSTR, prefers setting m_nLen. However, it is not required if a string data is null terminated.
  3. When a parameter type is DBPARAMIO_OUTPUT, it is a must to set m_nLen for all variable-length types of parameter data. Under this case, m_nLen indicates the length of a buffer in bytes, which will receives a returned data from a parameterized stored procedure. OleDBPro directly copies the returned data into a client-allocated buffer according to its length.
  4. When a parameter type is DBPARAMIO_INPUT|DBPARAMIO_OUTPUT, it is a must to set m_nLen for all variable-length types of parameter data. Under this case, m_nLen indicates the length of a buffer in bytes, which will receives a returned data from a parameterized stored procedure. OleDBPro directly copies the returned data into a client-allocated buffer according to its length. Additionally, a string data must be null-terminated. Under a very particular case, if client codes set a parameter data to NULL and still want to get a returned data from a parameterized stored procedure, client codes need to set m_nLen, m_pData to a buffer, and m_nDBStatus to DBSTATUS_S_ISNULL.
  5. When a parameter type is DBPARAMIO_OUTPUT and its data type is one of data types, DBTYPE_BSTR, DBTYPE_VARIANT, DBTYPE_IUNKNOWN and DBTYPE_PROPVARIANT, It is the client responsibility to free the memory allocated by a provider with a proper method as described in the OLEDB documentation in Platform SDK/MSDN.

        Usually, m_nDBStatus is ignored. However, under a very particular case you may set it to DBSTATUS_S_ISNULL. See the above rule 4.

        If m_pData is NULL, it means that a parameter is set to NULL in a relational DBMS.