2.17 Contents of RWDBEnvironmentHandle

The DB Access Module for Sybase CT returns an environment handle that has the type RWDBSybCtLibEnvironmentHandle. This handle provides methods that an application can use to set or retrieve certain connect time and configuration parameters. In addition, this handle contains the CS_CONTEXT pointer:

CS_CONTEXT*       cscontext() const;

This pointer can be used to set or retrieve configuration parameters that are not directly supported by the environment handle.

The loginTimeout() method defines the length of time in seconds that the Sybase Client-Library waits for a login response when making a connection attempt:

 
CS_INT loginTimeout() const;
RWDBStatus loginTimeout(CS_INT value);

In the Sybase Client-Library documentation, the default value is 60 seconds.

The timeout() method defines the length of time in seconds that the Sybase Client-Library waits for a server response to a command:

CS_INT timeout() const;
RWDBStatus timeout(CS_INT value);

In the Sybase Client-Library documentation, the default is an infinite timeout period. The application can set this value any time. It takes effect for all open connections immediately upon being called.

The applicationName() method defines the application name that gets passed to the Sybase Client-Library when an RWDBConnection is obtained. Two applicationName() methods are available:

RWCString applicationName() const;
RWDBStatus applicationName(const RWCString& name);

To take effect, the method must be called before the RWDBConnection is obtained.

The maximumConnections() method defines the maximum number of simultaneously open connections that an application can have:

int maximumConnections() const;
RWDBStatus maximumConnections(int value);

The default value is 25, according to the Sybase Client-Library documentation. This method has no effect if the maximum number of connections being set is less than the number of currently open connections. This behavior is determined by Sybase, not the Access Module.

The textLimit() method defines the length in bytes of the longest text or image value an application is prepared to receive:

long textLimit() const;
RWDBStatus textLimit(long value);

The Sybase Client-Library will read but ignore any part of the text or image value that goes over the limit defined by this function. Refer to the Sybase Client-Library documentation for more information.

---

NOTE -- This method affects only the client side text limit, not the server side text limit for this connection. To change the server side limit, you must call ct_options() directly.

---

The maxBlobSize() method sets the maximum size in bytes for blobs that can be fetched.

Two methods are defined:

size_t maxBlobSize() const;

Returns the current value for the maximum blob size. The default is 102,400 bytes.

RWDBStatus maxBlobSize(size_t bSize);

Sets the provided size, and returns an RWDBStatus indicating whether the operation succeeded.

The exposeHiddenKeys() method determines whether the Sybase Client-Library exposes any hidden keys that are part of a result set:

bool  exposeHiddenKeys() const;
RWDBStatus exposeHiddenKeys(bool value);

Please see the Sybase Client-Library documentation for hidden keys semantics. The default behavior of the Sybase Client-Library is not to expose any hidden keys. Setting it to true will change the default behavior.

The DB Access Module for Sybase CT has not implemented the virtual functions:

bool foreignKeysFromView();
bool foreignKeysFromView(bool value);

Both functions are therefore no-ops, which return false.

The noLongCharCapability() methods access and define the setting that will be used for the CS_DATA_NOLCHAR capability in future connections. Setting this capability to CS_TRUE disables the use of the CS_LONGCHAR client type (this is not a server side datatype).

The sybase bulk interface has problems with datatypes that expand when copied from the client to the server. This may occur when CS_DATA_NOLCHAR capability is set to CS_FALSE. Try setting the capability to CS_TRUE.

CS_BOOL noLongCharCapability() const;
void noLongCharCapability(const CS_BOOL& value)

The default setting for noLongCharCapability is CS_TRUE, so connections will have the use of CS_LONGCHAR disabled. To take effect, the method must be called before the RWDBConnection is obtained.

Each CS_CONTEXT object has an associated CS_LOCALE structure. The CS_LOCALE structure stores the localization information that is used to process data and generate error messages by the CS_CONTEXT object and the CS_CONNECTION objects that it produces.

The CS_LOCALE structure stores values for four locale properties:

• CS_LC_CTYPE -- Character set to use for data type conversions.

• CS_LC_COLLATE -- Collating sequence to use when sorting and comparing character data.

• CS_LC_TIME -- Date and time data representation to use for a datetime string, such as date and time formats, names in the native languages, and month and day abbreviations.

• CS_LC_MESSAGE -- Language and character set to use for messages.

These definitions are taken from the Sybase International Developer's Guide for Open Client/Server.

The values that can be set for these properties are the vendor_locale values specified in the locales.dat file in the directory <Sybase home directory>/locales. For more details on how to use the various locale values, please see Section 2.10 in this guide and the Sybase International Developer's Guide for Open Client/Server.

The DB Access Module for Sybase CT provides three methods for accessing locales on the CS_LOCALE structure. This CS_LOCALE structure is associated with the CS_CONTEXT structure encapsulated by the RWDBSybCtLibEnvironmentHandle. Any changes on the CS_LOCALE structure are only inherited by the future CS_CONNECTION objects and do not affect the existing CS_CONNECTION objects. The three methods for accessing locales on the CS_LOCALE structure are:

RWCString localeProperty(CS_INT property) const;

Returns the value of the locale property. Any of the four locale properties can be specified as the parameter.

void localeProperty(CS_INT property, const RWCString& value);

Sets the locale property to the value specified. Any of the four locale properties or CS_LC_ALL can be specified as the first parameter. If CS_LC_ALL is used, it sets the value of all four locale properties. If the second parameter is passed as an empty string, it clears the value of the property.

void locale(CS_LOCALE* locale);

Sets the CS_LOCALE structure of the CS_CONTEXT to the one supplied.

The CS_LOCALE structure must be preallocated using Sybase call cs_loc_alloc() before making this call. Sybase copies the contents of the CS_LOCALE structure into the CS_CONTEXT. Hence, it is safe to drop the allocated structure after this call.

If the CS_LOCALE* is passed in as NULL, it clears the CS_LOCALE structure associated with the CS_CONTEXT structure.

The following example shows how to gain access to RWDBSybCtLibEnvironmentHandle. Note that the application must be compiled with an include path to the Sybase Client-Library include files.

#include <rw/db/ctlibsrc/ctlenvh.h>

// Get correct handle by typecasting
RWDBSybCtLibEnvironmentHandle *envHandle = 
         (RWDBSybCtLibEnvironmentHandle  *)aDB.environmentHandle();

// Set login time out
envHandle->loginTimeout(10);

// Get a connection
RWDBConnection conn = aDB.connection();

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.