ODBCAdaptor

Inherits From:
EOAdaptor : NSObject

Declared in: ODBCEOAdaptor/ODBCAdaptor.h

Class Description

An ODBCAdaptor represents a single connection to an ODBC database server, and is responsible for keeping login and model information, performing ODBC-specific formatting of SQL expressions, and reporting errors.

ODBC (Open Data Base Connectivity) defines a standard interface that Windows applications can use to access any data source. Unlike the other Enterprise Objects Frameworks adaptors that support a single type of database, the ODBC adaptor supports any data source that has an ODBC driver. Consequently, in addition to having standard adaptor features, the ODBC adaptor also manages information relating to the driver and to the data types defined by the data source the driver supports.

The ODBCAdaptor class doesn't support nested transactions.

The Connection Dictionary

The connection dictionary contains items needed to connect to an ODBC server, such as the data source (it's common to omit the user name and password from the connection dictionary, and prompt users to enter those values in a login panel). The keys of this dictionary identify the information the server expects, and the values of those keys are the values that the adaptor uses when trying to connect to the server. For ODBC the required keys are as follows:

dataSource

userName

password

The connection dictionary can also optionally have the keys connectionString, typeInfo, and driverInfo.

The connectionString contains the user name, password, and data source. If the connectionString key is present in the connection dictionary, the other logon keys are ignored and this string is used to connect to the database.

The typeInfo key refers to the typeInfo dictionary, which is used to cache type information in the connection dictionary. This is done because different ODBC drivers work with different data types. Caching type information in the connection dictionary avoids costly connections to the driver and the database. The typeInfo dictionary contains the following information for every type in your database:

defaultODBCType = (<CHAR/TIMESTAMP/BIT/...>, ...)
precision = <precision>
minScale = <minScale>
maxScale = <maxScale>
isUnsigned = <YES/NO>
isNullable = <YES/NO>
isSearchable = <YES/NO>
createParams = <0/1/2>

Likewise, the driverInfo key refers to the driverInfo dictionary, which stores information about the driver, such as its name and version. This information is also cached in the connection dictionary.

Locking

All adaptors use the database server's native locking facilities to lock rows on the server. If you're using the Microsoft SQL Server, the ODBC adaptor locks a row by using the HOLDLOCK keyword in SELECT statements. In all other cases it uses the SELECT... FOR UPDATE... statement. Locking occurs when:

Data Type Mapping

Every adaptor provides a mapping between each server data type and the Objective-C type to which a database value will be coerced when it's fetched from the database. ODBC adds an intermediate layer: the generic ODBC type (identifier) to which each database data type maps.

For example, the following table shows the mapping from some of the Access database data types to ODBC to Objective-C:

Access Database Type

Generic ODBC Type

Objective-C Type

TEXT SQL_VARCHAR NSString
CURRENCY SQL_NUMERIC NSDecimalNumber
BINARY SQL_BINARY NSData
DATETIME SQL_TIMESTAMP NSCalendarDate

The following table lists the mapping between generic ODBC types and Objective-C types.

ODBC Data Type Objective-C Data Type
SQL_VARCHAR NSString
SQL_CHAR NSString
SQL_LONGVARCHAR NSString
SQL_DECIMAL NSDecimalNumber
SQL_NUMERIC NSDecimalNumber
SQL_BIGINT NSNumber
SQL_SMALLINT NSNumber
SQL_INTEGER NSNumber
SQL_REAL NSNumber
SQL_FLOAT NSNumber
SQL_DOUBLE NSNumber
SQL_BIT NSNumber
SQL_TINYINT NSNumber
SQL_VARBINARY NSData
SQL_BINARY NSData
SQL_LONGVARBINARY NSData
SQL_TIMESTAMP NSCalendarDate
SQL_DATE NSCalendarDate
SQL_TIME NSCalendarDate

IBM DB2 specifics types
SQL_GRAPHIC NSData
SQL_VARGRAPHIC NSData
SQL_LONGVARGRAPHIC NSData
SQL_BLOB NSData
SQL_CLOB NSData
SQL_DBCLOB NSData
Since ODBCAdaptor's type information is stored in a model's connection dictionary, the type mapping methods-externalTypesWithModel: , internalTypeForExternalType:model: , and isValidQualifierType:model: -use the model argument if it is provided. If the model argument isn't provided, these methods don't have data type information available to them.

Method Types

Mapping external types to internal types
+ assignExternalInfoForAttribute:
+ externalTypeForOdbcType:model:
+ externalTypesWithModel:
+ internalTypeForExternalType:model:
+ odbcTypeForExternalType:model:
+ getOdbcInfoWithConnectionDictionary:
+ odbcTypeForStringRepresentation:
+ resetOdbcInfoWithConnectionDictionary:
+ stringRepresentationForOdbcType:
Access information in the connection dictionary
+ driverInfoForModel:
+ typeInfoForModel:
- driverInfo
- typeInfo
Testing the connection dictionary
- assertConnectionDictionaryIsValid
- defaultExpressionClass
- isValidQualifierType:model:
- odbcConnectionString
- odbcEnvironment

Class Methods

assignExternalInfoForAttribute:

(void)assignExternalInfoForAttribute:(EOAttribute *)attribute

Sets the external information for attribute based on the internal type, precision, and width.

driverInfoForModel:

+ (NSDictionary *)driverInfoForModel:(EOModel *)model

Returns an NSDictionary containing the driver information cached in the connection dictionary of model. If the information is not yet cached in model, connects to the database to get it.

See also: + typeInfoForModel: , - driverInfo , - typeInfo

externalTypeForOdbcType:model:

+ (NSString *)externalTypeForOdbcType:(int)type model:(EOModel *)model

Returns the external type that represents the best match for an ODBC type in model.

externalTypesWithModel:

+ (NSArray *)externalTypesWithModel:(EOModel *)model

Overrides the EOAdaptor method externalTypesWithModel: to return the ODBC database types.

See also: + internalTypeForExternalType:model:

getOdbcInfoWithConnectionDictionary:

+ (NSDictionary *)getOdbcInfoWithConnectionDictionary:(NSDictionary *)connectionDictionary

Sets up the typeInfo and driverInfo dictionaries in connectionDictionary, and returns an updated connection dictionary. Creates an ODBCAdaptor, ODBCContext, and ODBCChannel, and connects to the database to get the information for the typeInfo and driverInfo dictionaries.

internalTypeForExternalType:model:

+ (NSString *)internalTypeForExternalType:(NSString *)externalType model:(EOModel *)model

Overrides the EOAdaptor method internalTypeForExternalType: to return the name of the Objective-C class used to represent values stored in the database as externalType.

See also: + externalTypesWithModel:

odbcTypeForExternalType:model:

+ (NSString *)odbcTypeForExternalType:(NSString *)externalType model:(EOModel *)model

Returns the ODBC type for externalType, as defined in the typeInfo dictionary in model's connection dictionary.

odbcTypeForStringRepresentation:

+ (int)odbcTypeForStringRepresentation:(NSString *)type

Returns the ODBC type (such as SQL_CHAR) for type (such as @"CHAR"). The method stringRepresentationForOdbcType: performs the opposite function: returning a string for a specified ODBC type. These methods are used in conjunction to encode ODBC types in the typeInfo dictionary.

resetOdbcInfoWithConnectionDictionary:

+ (NSDictionary *)resetOdbcInfoWithConnectionDictionary:(NSDictionary *)connectionDictionary

Removes the typeInfo and driverInfo dictionaries from connectionDictionary and returns the modified connection dictionary.

stringRepresentationForOdbcType:

+ (NSString *)stringRepresentationForOdbcType:(int)type

Returns the string representation of type-for example, for the type SQL_CHAR this method would return the string @"CHAR". The method odbcTypeForStringRepresentation: performs the opposite function: returning the ODBC type for a specified string. These methods are used in conjunction to encode ODBC types in the typeInfo dictionary.

typeInfoForModel:

+ (NSDictionary *)typeInfoForModel:(EOModel *)model

Returns an NSDictionary containing the type information cached in the connection dictionary of model. If the information is not yet cached in model, connects to the database to get it.

See also: + driverInfoForModel: , - driverInfo , - typeInfo

Instance Methods

assertConnectionDictionaryIsValid

- (void)assertConnectionDictionaryIsValid

Determines whether the receiver's connection dictionary is valid. The adaptor uses this method in conjunction with displaying a server login panel. Raises an exception if an error occurs.

Note that this method doesn't open a connection to the database-that happens when the first adaptor channel is sent an openChannel message.

defaultExpressionClass

- (Class)defaultExpressionClass

Returns the ODBCSQLExpression class.

driverInfo

- (NSDictionary *)driverInfo

Returns an NSDictionary containing the driver information cached in the receiver's model's connection dictionary. If the information is not yet cached in the model, connects to the database to get it.

See also: - typeInfo

isValidQualifierType:model:

- (BOOL)isValidQualifierType:(NSString *)typeName model:(EOModel *)model

Returns YES if model's attribute of the type typeName can be used in a qualifier, otherwise returns NO.

odbcConnectionString

- (NSString *)odbcConnectionString

Returns the user name, password, and data source as a string that's used to connect to the database.

odbcEnvironment

- (void *)odbcEnvironment

Returns the ODBC Environment Handle HENV as a void*; to work with it, you must cast it to HENV.

typeInfo

- (NSDictionary *)typeInfo

Returns an NSDictionary containing the type information cached in the receiver's model's connection dictionary. If the information is not yet cached in the model, connects to the database to get it.

See also: - driverInfo , + driverInfoForModel: , + typeInfoForModel:

Copyright © 1997, Apple Computer, Inc. All rights reserved.