Enabling LOB Locator Support

Use the EnableLOBLocator connection property to enable the LOB locator support.

1. To enable LOB locator support in Adaptive Server ODBC Driver, establish a connection to Adaptive Server with the EnableLOBLocator connection property set to 1.

   When EnableLOBLocator is 0, the default value, the Adaptive Server ODBC Driver cannot retrieve a locator for a LOB column. When enabling LOB Locators, the connection should be set to autocommit off.

2. Include the sybasesqltypes.h file in your program.

   The sybasesqltypes.h file is located in the include directory, under the ODBC installation directory.

   Note: LOB Locators can be used reliably when the application is linked directly to the driver. When a driver manager is used and LOB Locators are used, some driver managers may restrict the use of vendor defined C and SQL Types and the application may encounter an Unsupported Type error.

• ODBC Datatype Mapping for Locator Support
  The ODBC datatype mapping for the Adaptive Server locator datatypes.
• Supported Conversions
  The supported conversions for the Adaptive Server locator datatypes.
• ODBC API Methods that Support LOB Locators
  Review the Adaptive Server ODBC API methods that support LOB locators.
• Retrieving Implicit Conversion of Prefetched LOB Data
  Use SQLGetData and SQLBindCol to retrieve the underlying prefetched LOB data by binding the column to SQL_C_CHAR or SQL_C_WCHAR for text locators, or to SQL_C_BINARY for image locators, when Adaptive Server returns a LOB locator.
• Access and Manipulate LOBs Using Locators
  The ODBC API does not directly support LOB locators. An ODBC client application must use Transact-SQL® functions to operate on the locators and manipulate LOB values.
• Initialize a Text Locator
  Use sp_drv_create_text_locator to create a text_locator and optionally initialize it with value. sp_drv_create_text_locator accesses the Transact-SQL function create_locator.
• Initialize a Unitext Locator
  Use sp_drv_create_unitext_locator to create a unitext_locator and optionally initialize it with value. sp_drv_create_unitext_locator accesses the Transact-SQL function create_locator.
• Initialize an Image Locator
  Use sp_drv_create_image_locator to create an image_locator and optionally initialize it with value. sp_drv_create_image_locator accesses the Transact-SQL function create_locator.
• Obtain Complete Text Value From a Text Locator
  Use sp_drv_locator_to_text which accesses the Transact-SQL function return_lob.
• Obtain Complete Unitext Value From a Unitext Locator
  Use sp_drv_locator_to_unitext which accesses the Transact-SQL function return_lob.
• Obtain Complete Image Value From an Image Locator
  Use sp_drv_locator_to_image which accesses the Transact-SQL function return_lob.
• Obtain a Substring From a Text Locator
  Use sp_drv_text_substring which accesses the Transact-SQL function substring.
• Obtain a Substring From a Unitext Locator
  Use sp_drv_unitext_substring which accesses the Transact-SQL function substring.
• Obtain a Substring From an Image Locator
  Use sp_drv_image_substring, which accesses the Transact-SQL function substring.
• Insert Text at Specified Position
  Use sp_drv_text_setdata which accesses the Transact-SQL function setadata.
• Insert Unitext at Specified Position
  Use sp_drv_unitext_setdata which accesses the Transact-SQL function setadata.
• Insert an Image at Specified Position
  Use sp_drv_image_setdata which accesses the Transact-SQL function setadata.
• Insert Text Referenced by a Locator
  Use sp_drv_text_locator_setdata which accesses the Transact-SQL function setadata.
• Insert Unitext Referenced by a Locator
  Use sp_drv_unitext_locator_setdata which accesses the Transact-SQL function setadata.
• Insert Image Referenced by a Locator
  Use sp_drv_image_locator_setdata which accesses the Transact-SQL function setadata.
• Truncate Underlying LOB Data
  Use truncate lob to truncate the LOB data referenced by a LOB locator.
• Find Character Length of Underlying Text Data
  Use sp_drv_text_locator_charlength to find the character length of a LOB column referenced by a text locator. sp_drv_text_locator_charlength accesses the Transact-SQL function char_length.
• Find Byte Length of Underlying Text Data
  Use sp_drv_text_locator_bytelength to find the byte length of a LOB column referenced by a text locator. sp_drv_text_locator_bytelength accesses the Transact-SQL function data_length.
• Find Character Length of Underlying Unitext Data
  Use sp_drv_unitext_locator_charlength to find the character length of a LOB column referenced by a unitext locator. sp_drv_unitext_locator_charlength accesses the Transact-SQL function char_length.
• Find Byte Length of Underlying Unitext Data
  Use sp_drv_unitext_locator_bytelength to find the byte length of a LOB column referenced by a unitext locator. sp_drv_unitext_locator_bytelength accesses the Transact-SQL function data_length.
• Find Byte Length of Underlying Image Data
  Use sp_drv_image_locator_bytelength to finds the byte length of a LOB column referenced by an image locator. sp_drv_image_locator_bytelength accesses the Transact-SQL function data_length.
• Find Position of a Search String Within the Text Column Referenced by a Locator
  Use sp_drv_varchar_charindex which accesses the Transact-SQL function charindex.
• Find Position of a String Referenced by a Text Locator Within the Text Column Referenced by Another Locator
  Use sp_drv_textlocator_charindex which accesses the Transact-SQL function charindex.
• Find Position of a Search String Within the Unitext Column Referenced by a Locator
  Use sp_drv_univarchar_charindex which accesses the Transact-SQL function charindex.
• Find Position of a String Referenced by a Unitext Locator Within the Unitext Column Referenced by Another Locator
  Use sp_drv_unitext_locator_charindex which accesses the Transact-SQL function charindex.
• Find Position of a Byte Sequence Within the Column Referenced by an Image Locator
  Use sp_drv_varbinary_charindex which accesses the Transact-SQL function charindex.
• Find Position of Byte Sequence Referenced by an Image Locator Within the Image Column Referenced by Another Locator
  Use sp_drv_image_locator_charindex which accesses the Transact-SQL function charindex.
• Check If a text_locator Reference is Valid
  Use sp_drv_text_locator_valid which accesses locator_valid.
• Check If a unitext_locator Reference is Valid
  Use sp_drv_unitext_locator_valid which accesses locator_valid.
• Check If an image_locator Reference is Valid
  Use sp_drv_image_locator_valid which accesses locator_valid.
• Free or Deallocate a LOB Locator
  Use deallocate locator.
• Examples
  Some examples for enabling LOB locator support.