SaCursorColDynData binds a user variable of type SaDynDataT to a database column.
In search operations, the user variable is updated to contain the value of the current row. Also, if search criteria are involved, this function is used to pass the values for them. In insert and update operations, the new value for the column is taken from the user variable.
In search operations, the column data is stored to the SaDynDataT variable using function SaDynDataMove, which overwrites the old data. The user is responsible for releasing the SaDynDataT variable after the search ends using function SaDynDataFree.
Dynamic data objects (SaDynDataT) are an abstraction that simplifies the handling of variable length data. Although dynamic data can be used with all types of data, it is best fit for variable length data (VARBINARY, LONG VARBINARY, VARCHAR, LONG VARCHAR, and so on).
The memory management of the data object is hidden inside the object. Dynamic data objects have two externally-visible attributes: the data and the length. Typically, the functions SaDynDataMove and SaDynDataAppend are used to set and modify the data value inside the dynamic data object. More memory will be automatically allocated when necessary and all the associated memory will be automatically deallocated when the dynamic data object is disposed of using SaDynDataFree. The user can access the data or the length using the respective functions SaDynDataGetData and SaDynDataGetLen.
The use of SaDynDataMove and SaDynDataAppend might not be feasible when the data already exists completely in a memory buffer. In addition to increasing the memory usage by keeping two copies of the same data, the overhead of the memory copy can be significant if the buffers are large. Therefore, it can be wise to directly assign the data pointer by using SaDynDataMoveRef (rather than copying by using SaDynDataMove). In this case, the user can modify or deallocate the memory buffer only after the dynamic data object itself has been freed.