Advantage Client Engine
Stores given data as a BLOB in the given field.
UNSIGNED32 |
AdsSetBinary (ADSHANDLE hTable, UNSIGNED8 *pucFldName, UNSIGNED16 usBinaryType, UNSIGNED32 ulTotalLength, UNSIGNED32 ulOffset, UNSIGNED8 *pucBuf, UNSIGNED32 ulLen); |
hTable (I) |
Handle of table, cursor, or statement. |
pucFldName (I) |
Name of field to set. |
usBinaryType (I) |
Indicates type of binary data. Values are ADS_IMAGE and ADS_BINARY. |
ulTotalLength (I) |
Total length of data being stored. If the data is being stored with a single call, this parameter should be the same as ulLen. If the data is being stored with multiple calls, then this parameter should be the same for each call and must represent the total length of the binary date. |
ulOffset (I) |
Offset to which to start writing. |
pucBuf (I) |
Store this data in the field. |
ulLen (I) |
Length of data in the buffer for this call. |
AdsSetBinary sets binary objects that are held in memory. For larger binary objects, AdsFileToBinary is provided. Be sure to specify ADS_IMAGE if storing an image in the field. This API can be used to store binary data in memo fields. If used this way, AdsGetMemoDataType can be called to determine the type of data stored in the memo field.
When passed a statement handle this API can be used to specify parameters in an SQL statement previously prepared with a call to AdsPrepareSQL. For this usage pass pucFieldName as either the name of the parameter (when using named parameters) or the number of the parameter (when using either named or unnamed parameters). Parameter numbers in SQL statements are assigned left to right and utilize a one-based counter. For example, in the statement "SELECT * FROM test WHERE :lname = :value" the lname parameter could be referenced either as "lname" or as parameter 1. Using the same logic the value parameter could be referenced either as "value" or as parameter 2.
The pucFldName parameter can be passed as the field name itself or as the one-based integer field position. To pass an integer field position for the pucFldName parameter, use the ADSFIELD macro that is defined in ACE.H. For example, to specify the first field in the table, pass ADSFIELD(1) for the pucFldName parameter; to specify the second field in the table, pass ADSFIELD(2) for the pucFldName parameter; etc.
AdsPrepareSQL( hStatement,
"INSERT INTO test ( bin_field ) VALUES ( :bin_data )" );
AdsSetBinary( hStatement, "bin_data", ADS_BINARY, ulBufferSize, 0, aiData, ulBufferSize );
AdsExecuteSQL( hStatement, &hCursor);
When using unnamed parameters these parameters MUST be referenced using their parameter number.
AdsPrepareSQL( hStatement,
"INSERT INTO test ( bin_field ) VALUES ( :bin_data )" );
AdsSetBinary( hStatement, ADSFIELD(1), ADS_BINARY, ulBufferSize, 0, aiData, ulBufferSize );
AdsExecuteSQL( hStatement, &hCursor);
Note Use of this function is illegal in a transaction if the entire binary value is not being stored to the Binary/Image field in a single call. In other words, if the value in the ulTotalLength parameter is not the same as the value in the ulLen parameter, use of this function is illegal in a transaction. If the entire binary value is sent in a single call to AdsSetBinary, use of this function is supported in a transaction.