Simba ODBC Driver

for
SQL Server

Configuration Guide for

Custom Framework

Version 1.1.3.1004

January 23, 2015

Simba Technologies Inc.

Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Copyright ©2012-2014 Simba Technologies Inc. All Rights Reserved.

Information in this document is subject to change without notice. Companies, names and data
used in examples herein are fictitious unless otherwise noted. No part of this publication, or the
software it describes, may be reproduced, transmitted, transcribed, stored in a retrieval system,
decompiled, disassembled, reverse-engineered, or translated into any language in any form by
any means for any purpose without the express written permission of Simba Technologies Inc.

Trademarks

Simba, the Simba logo, SimbaEngine, SimbaEngine C/S, SimbaExpress and SimbaLib are registered
trademarks of Simba Technologies Inc. All other trademarks and/or servicemarks are the property
of their respective owners.

ICU License - ICU 1.8.1 and later

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1995-2014 International Business Machines Corporation and others. All rights
reserved.

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so,
provided that the above copyright notice(s) and this permission notice appear in all copies of the
Software and that both the above copyright notice(s) and this permission notice appear in
supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL
THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR
ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising
or otherwise to promote the sale, use or other dealings in this Software without prior written
authorization of the copyright holder.

All trademarks and registered trademarks mentioned herein are the property of their respective
owners.

www.simba .c om 2
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

OpenSSL

Copyright (c) 1998-2011 The OpenSSL Project. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials
provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the
following acknowledgment:
"This product includes software developed by the OpenSSL Project for use in the OpenSSL
Toolkit. (http://www.openssl.org/)"
4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or
promote products derived from this software without prior written permission. For
written permission, please contact openssl-core@openssl.org.
5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL"
appear in their names without prior written permission of the OpenSSL Project.
6. Redistributions of any form whatsoever must retain the following acknowledgment:
"This product includes software developed by the OpenSSL Project for use in the OpenSSL
Toolkit (http://www.openssl.org/)"

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT “AS IS”' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL
PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This
product includes software written by Tim Hudson (tjh@cryptsoft.com).

www.simba .c om 3
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Contact Us

Simba Technologies Inc.

938 West 8th Avenue

Vancouver, BC Canada
V5Z 1E5

www.sim ba.com

Telephone: +1 (604) 633-0008

Information and Product Sales: Extension 2
Technical Support: Extension 3

Fax: +1 (604) 633-0004

Information and Product Sales: solutions@simba.com

Technical Support: support@simba.com
Follow us on Twitter: @SimbaTech

Printed in Canada

www.simba .c om 4
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Table of Contents
Introduction ..............................................................................................................................6
Mac OS X Driver........................................................................................................................6
System Requirements ....................................................................................................................... 6
Using the Driver................................................................................................................................ 6
iOS Driver ..................................................................................................................................7
System Requirements ....................................................................................................................... 7
Using the Driver................................................................................................................................ 7
Configuring the Driver .............................................................................................................7
Connecting to Databases .........................................................................................................8
Error Messages ..........................................................................................................................8
Logging .....................................................................................................................................8
Driver Logging .................................................................................................................................. 9
Wire Protocol Component Logging ................................................................................................ 9
Features .................................................................................................................................. 10
Data Types ...................................................................................................................................... 10
OLE DB Properties .......................................................................................................................... 12
Contact Us .............................................................................................................................. 13
Appendix: Driver Configuration Options ............................................................................. 14

www.simba .c om 5
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Introduction
The Simba ODBC Driver for SQL Server enables Business Intelligence (BI), analytics, and reporting
on data that is stored in Microsoft SQL Server databases. The driver complies with the ODBC 3.80
data standard and adds important functionality such as Unicode and 32- and 64-bit support for
high-performance computing environments.

ODBC is one of the most established and widely supported APIs for connecting to and working
with databases. At the heart of the technology is the ODBC driver, which connects an application
to a database. For more information about ODBC, see http://www.simba.com/odbc.htm. For
complete information on the ODBC specification, see the ODBC API Reference at
http://msdn.microsoft.com/en-us/library/windows/desktop/ms714562(v=vs.85).aspx

The custom framework for the Simba ODBC Driver for SQL Server provides a way for developers
to integrate the driver with a Mac OS X or iOS application. This guide is suitable for developers
who want to implement the Simba ODBC Driver for SQL Server as part of their application.

Mac OS X Driver
System Requirements
The following is a list of the minimum system requirements for using the Simba ODBC Driver for
SQL Server custom framework on Mac OS X:
• Xcode 6.1 or later, with OS X 10.9 base SDK
• Mac OS X version 10.9 or later

The driver has been tested using SQL Server 2005 to 2012.

Using the Driver

The Simba ODBC Driver for SQL Server custom framework is delivered in a tar file named
SimbaSQLServerODBC.tar.gz

For information about how to use a custom framework in your OS X Xcode project, refer to the
Xcode documentation at https://developer.apple.com/library/ios/recipes/xcode_help-
project_editor/Articles/AddingaLibrarytoaTarget.html#//apple_ref/doc/uid/TP40010155-CH17-
SW1.

www.simba .c om 6
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

iOS Driver
System Requirements
The following is a list of the minimum system requirements for using the Simba ODBC Driver for
SQL Server custom framework on iOS:
• Xcode 6.1 or later, with iOS 8.1 base SDK
• iOS version 7.1 or later

The driver has been tested with SQL Server 2005 to 2012.

Using the Driver

The Simba ODBC Driver for SQL Server custom framework is delivered in a tar file named
SimbaSQLServerODBC.tar.gz.

For information about how to use a custom framework in your iOS Xcode project, refer to the
Xcode documentation at https://developer.apple.com/library/ios/recipes/xcode_help-
project_editor/Articles/AddingaLibrarytoaTarget.html#//apple_ref/doc/uid/TP40010155-CH17-
SW1.

Configuring the Driver

Configure the Simba ODBC Driver for SQL Server using the simba.sqlserverodbc.plist file found in
the following folders:
• OS X—SQLServerODBC.framework’s Resources directory
• iOS—SqlServeriOSBundle.bundle’s root directory
Using the simba.sqlserverodbc.plist file, you can configure the following attributes:
• LogLevel—Sets the logging level for driver logging. See “Driver Logging” on page 9 for
more details.
• LogPath— Sets the location where log files produced by driver logging are saved. See
“Driver Logging” on page 9 for more details.
• DriverManagerEncoding—Specifies the encoding used by the application. For example,
the value can be UTF-16 or UTF-32 depending on the application into which you are
integrating the Simba ODBC Driver for SQL Server. The default value is UTF-16
• TDSTRACE—Sets the logging level and log file location for wire protocol logging. See
“Wire Protocol Component Logging” on page 9 for more detail.

www.simba .c om 7
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Connecting to Databases
Because the Simba ODBC Driver for SQL Server custom framework is used without a driver
manager, all connection options must be specified in the connection string. The driver uses the
connection options in the connection string during the SQLDriverConnect API call. Specify
connection options as key-value pairs, using the following format: key1=value1;key2=value2

Important: The custom framework requires you to specify either a “DSN” or “DRIVER” key in the
connection string, but the driver does not actually use the value. You must specify the key, but
the value that you specify is irrelevant.

The following is an example of a connection string:

DSN=Sample Simba SQL Server DSN;SERVER=192.168.222.123,1434;uid=user;pwd=
password;Database=test_database

For information about the connection options available for controlling the behavior of the Simba
ODBC Driver for SQL Server, see “Appendix: Driver Configuration Options” on page 14.

Error Messages
Error messages are set using the following .STRINGS files, encoded using UTF-16LE with the byte
order mark:
• ◾DSI.strings
• ◾ODBC.strings
• ◾OLEDB.strings
• ◾SQLEngine.strings
• ◾SqlServerODBC.strings
• ◾Support.strings

For OS X, the files are looked up in the Localization.lproj directory in the

SQLServerODBC.framework’s Resources directory.

For iOS, the files are looked up in the Localization.lproj directory in the
SqlServeriOSBundle.bundle’s root directory.

Logging
To help troubleshoot issues, you can enable logging in both the driver and the wire protocol
component.

www.simba .c om 8
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Important: Only enable logging long enough to capture an issue. Logging decreases performance
and can consume a large quantity of disk space.

Driver Logging
The driver allows you to set the amount of detail included in the driver log files. Table 1 lists the
logging levels provided by the Simba ODBC Driver for SQL Server, in order from least verbose to
most verbose.

Logging Level Description

0 Disables all logging.

1 Logs very severe error events that will lead the driver to abort.

2 Logs error events that might still allow the driver to continue
running.

3 Logs potentially harmful situations.

4 Logs general information that describes the progress of the

driver.

5 Logs detailed information that is useful for debugging the driver.

6 Logs more detailed information than the DEBUG level.

Table 1 Simba ODBC Driver for SQL Server Logging Levels

When logging is enabled, the Simba ODBC Driver for SQL Server produces a log file named
SqlServerODBC.log at the location specified in the LogPath driver configuration setting. For
further details on configuring logging in the driver, see “Configuring the Driver” on page 7.

Wire Protocol Component Logging

The wire protocol component allows you to set the amount of detail included in wire protocol log
files. Table 2 lists the logging levels provided by the wire protocol component, in order from least
verbose to most verbose.

Logging Level Description

0 Disables all logging.

1 Logs error events that might still allow the wire protocol
component to continue running. 1 is the default logging level.

www.simba .c om 9
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Logging Level Description

2 Logs general information that describes the progress of the wire

protocol component.

3 Logs detailed information that is useful for debugging the wire

protocol component.

4 Logs more detailed information than the level useful for

debugging.

Table 2 Wire Protocol Component Logging Levels

To enable wire protocol logging, set values for the key having the name TDSTRACE in the Driver
branch in the .PLIST file.

For OS X platforms, the value of the TDSTRACE key uses the format log_level:log_file_path,
where log_level specifies the level of information to include in the wire protocol log file and
log_file_path specifies the path and name of the log file within the Documents directory of the
app bundle. For example, the value 3:Logs/MyTDSTraceLog.log creates a log file containing
detailed information useful for debugging at the location AppBundlePath/Documents/Logs/
MyTDSTraceLog.log

For iOS platforms, the value of the TDSTRACE key uses the format log_level:log_file_path, where
log_level specifies the level of information to include in the wire protocol log file and
log_file_path specifies the path to the log file within the Documents directory of the app bundle.
For iOS platforms, the wire protocol log file always uses the name TDSLog.log. For example, the
value 3:Logs creates a log file containing detailed information useful for debugging at the
location AppBundlePath/Documents/Logs/TDSLog.log

Features
Data Types
The Simba ODBC Driver for SQL Server supports many common data formats, converting between
SQL Server data types and SQL data types.

Table 3 lists the supported data type mappings.

SQL Server Type SQL Type

BIGINT SQL_BIGINT

BINARY SQL_BINARY

www.simba .c om 10
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

SQL Server Type SQL Type

BIT SQL_BIT

CHAR SQL_CHAR

DATE SQL_TYPE_DATE

DATETIME SQL_TYPE_TIMESTAMP

DATETIME2 SQL_TYPE_TIMESTAMP

DATETIMEOFFSET SQL_SS_TIMESTAMPOFFSET

DECIMAL SQL_DECIMAL

FLOAT SQL_FLOAT

GUID SQL_GUID

INT SQL_INTEGER

MONEY SQL_DECIMAL

NCHAR SQL_WCHAR

NUMERIC SQL_NUMERIC

NVARCHAR SQL_WVARCHAR

REAL SQL_REAL

ROWVERSION SQL_BINARY
Note: Before SQL Server 2008, this
data type was called TIMESTAMP.

SMALLDATETIME SQL_TYPE_TIMESTAMP

SMALLINT SQL_SMALLINT

SMALLMONEY SQL_DECIMAL

TIME SQL_SS_TIME2

TIMESTAMP SQL_BINARY
Note: In SQL Server 2008 and later,
this data type is called

www.simba .c om 11
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

SQL Server Type SQL Type

ROWVERSION.

TINYINT SQL_TINYINT

VARBINARY SQL_VARBINARY

VARCHAR SQL_VARCHAR

Table 3 Supported Data Types

OLE DB Properties
Table 4 lists OLE EB properties used by SQL Server. Properties appearing in italics are custom
properties. OLE DB property keys appearing in italics are keys defined by the Simba ODBC Driver
for SQL Server, not the OLE DB protocol.

SQL Server Connection String Property OLE DB Property

Key Description Req’d Key Value

TDS_UID_KEY User ID False DBPROP_AUTH_USERID 0xcL

TDS_PWD_KEY Password False DBPROP_AUTH_PASSWORD 0x9L

TDS_SERVER_KEY Server True DBPROP_INIT_DATASOURCE 0x3bL

TDS_DATABASE_KEY Database False DBPROP_INIT_CATALOG 0xe9L

TDS_INTEGRATED_ Integrated Security False DBPROP_AUTH_INTEGRATED 0x7UL

SECURITY_KEY Possible values:
• SSPI—
Kerberos
(OS X only)
• SQLServer
—User
name and
password

TDS_ENCRYPT_KEY Encrypt data with True TDS_SSPROP_INIT_ENCRYPT 13 + 0x70000000UL

SSL (Boolean for
value) SQL
Azure

www.simba .c om 12
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

TDS_TRUST_SERVER_ Use self-signed False TDS_SSPROP_INIT_TRUST_ 21 + 0x70000000UL

CERT_KEY certificate when SERVER_CERTIFICATE
using an SSL
connection
(Boolean value)

TDS_SERVER_SPN_ Service principle False TDS_SSPROP_INIT_ 22 + 0x70000000UL

KEY name for Kerberos SERVERSPN

TDS_PORT_KEY Server port False TDS_SSPROP_INIT_PORT 0 + 0x7A000000UL

Table 4 OLE DB Properties Used by SQL Server

Contact Us
If you have difficulty using the driver, please contact our Technical Support staff. We welcome
your questions, comments, and feature requests.

Technical Support is available Monday to Friday from 8 a.m. to 5 p.m. Pacific Time.

Important: To help us assist you, prior to contacting Technical Support please prepare a detailed
summary of the client and server environment including operating system version, patch level,
and configuration.

You can contact Technical Support via:

• E-mail: support@simba.com
• Web site: www.simba.com
• Telephone: (604) 633-0008 Extension 3
• Fax: (604) 633-0004

You can also follow us on Twitter @SimbaTech

www.simba .c om 13
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Appendix: Driver Configuration Options

Table 5 lists, in alphabetical order, the configuration options that you can use to control the
behavior of the Simba ODBC Driver for SQL Server. Set these options in the connection string
when using the SQLDriverConnect API call.

Key Default Value Description

CACertificate cacerts.pem The full file path of the CA certificate to
use when Encrypt is set to “yes” and
TrustServerCertificate is set to “no”.
Database The name of the default database to use
when the connection is established.
(Optional)
Encrypt no Use this option to control whether
communication with the SQL Server
database is encrypted before it is sent
over the network. The following values
are possible:
• yes – Use encryption.
• no – Do not use encryption.
(Optional)
Port 1433 The port to connect to on the SQL Server
database.
(Optional)
PWD The password corresponding to the user
name that you provided in the UID
property.
(Required if authenticating through user
login)
Server The IP address or hostname of the SQL
Server database.
(Required)
ServerSPN MSSQLSvc/hostname:port, The service principal name of the SQL
where hostname is the Server database.
server name in the Server (Required if authenticating through
key and port is the port Kerberos)
number in the Port key.

www.simba .c om 14
Simba ODBC Driver for SQL Server Configuration Guide for Custom Framework

Key Default Value Description

TrustServerCertificate Use this option to control whether the
driver trusts the server certificate. The
following values are possible:
• yes – The driver trusts the server
certificate.
• no – The driver does not trust the
server certificate. The CA Certificate
is used to verify the server
certificate.
UID The username to use to connect to the
SQL Server database.
(Required if authenticating through user
login)
Table 5 Driver Configuration Options

www.simba .c om 15