RWDBSybCtLibEnvironmentHandle Class Reference
[DB Access Module for Sybase]

Provides methods for setting and retrieving certain connect time and configuration parameters with Sybase Open Client Client-Library. More...

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

Inheritance diagram for RWDBSybCtLibEnvironmentHandle:

List of all members.

Public Member Functions
CS_CONTEXT *	cscontext () const
CS_INT	loginTimeout () const
RWDBStatus	loginTimeout (CS_INT value)
CS_INT	timeout () const
RWDBStatus	timeout (CS_INT value)
virtual CS_INT	maximumConnections () const
virtual RWDBStatus	maximumConnections (CS_INT value)
CS_INT	textLimit () const
RWDBStatus	textLimit (CS_INT value)
virtual bool	exposeHiddenKeys () const
virtual RWDBStatus	exposeHiddenKeys (bool value)
RWCString	applicationName () const
RWDBStatus	applicationName (const RWCString &name)
CS_BOOL	noLongCharCapability () const
void	noLongCharCapability (CS_BOOL value)
void	locale (CS_LOCALE *locale)
void	localeProperty (CS_INT property, const RWCString &value)
RWCString	localeProperty (CS_INT property) const
size_t	maxBlobSize () const
RWDBStatus	maxBlobSize (size_t size)

---

Detailed Description

Class RWDBSybCtLibEnvironmentHandle provides methods for setting and retrieving certain connect time and configuration parameters with Sybase Open Client Client-Library.

Please note that some connect time parameters are set only when a connection is established with the server. When the method returns a valid RWDBStatus for these parameters, it does not necessarily mean that the connection parameter has been accepted by the server. Appropriate error messages will be fielded to the application only when a connection is established.

Note:

Use of this class reduces an application's portability.

Synopsis

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

 RWDBSybCtLibEnvironmentHandle* env =
       (RWDBSybCtLibEnvironmentHandle*)myDatabase.environmentHandle();

Examples

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();

---

Member Function Documentation

RWDBStatus RWDBSybCtLibEnvironmentHandle::applicationName

(

const RWCString &

name

)

[inline]

Sets the application name name to be passed to the Sybase Client-Library when a RWDBConnection is obtained. To take effect, this method must be called before the RWDBConnection is obtained.

RWCString RWDBSybCtLibEnvironmentHandle::applicationName

(

)

const [inline]

Returns the application name that is passed to the Sybase Client- Library when an RWDBConnection is obtained.

CS_CONTEXT* RWDBSybCtLibEnvironmentHandle::cscontext

(

)

const

Returns a pointer to the CS_CONTEXT structure used by the application.

virtual RWDBStatus RWDBSybCtLibEnvironmentHandle::exposeHiddenKeys

(

bool

value

)

[virtual]

Enables or disables hidden keys that are part of a result set.

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

virtual bool RWDBSybCtLibEnvironmentHandle::exposeHiddenKeys

(

)

const [virtual]

Returns true if the Sybase Client-Library exposes hidden keys that are part of a result set. The default value is false.

void RWDBSybCtLibEnvironmentHandle::locale

(

CS_LOCALE *

locale

)

Sets the CS_LOCALE structure of the CS_CONTEXT to that provided by locale.

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.

RWCString RWDBSybCtLibEnvironmentHandle::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 RWDBSybCtLibEnvironmentHandle::localeProperty	(	CS_INT	property,
		const RWCString &	value
	)

Sets the locale property to the value specified in value. 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.

RWDBStatus RWDBSybCtLibEnvironmentHandle::loginTimeout

(

CS_INT

value

)

Sets the maximum number of seconds for the Sybase Client-Library should wait for a login response when making a connection attempt and returns an RWDBStatus indicating whether the operation was successful.

CS_INT RWDBSybCtLibEnvironmentHandle::loginTimeout

(

)

const

Returns the current value for the maximum number of seconds the Sybase Client-Library waits for a login response when making a connection attempt. The Sybase Client-Library documentation defines the default value as 60 seconds.

RWDBStatus RWDBSybCtLibEnvironmentHandle::maxBlobSize

(

size_t

size

)

Sets the maximum blob size to size, and returns an RWDBStatus indicating whether the operation succeeded.

size_t RWDBSybCtLibEnvironmentHandle::maxBlobSize

(

)

const

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

virtual RWDBStatus RWDBSybCtLibEnvironmentHandle::maximumConnections

(

CS_INT

value

)

[virtual]

Sets the maximum number of simultaneously open connections that an application allows, and returns an RWDBStatus indicating whether the operation succeeded.

This method has no effect if value is less than the number of currently open connections. This behavior is determined by Sybase, not the Access Module.

virtual CS_INT RWDBSybCtLibEnvironmentHandle::maximumConnections

(

)

const [virtual]

Returns the maximum number of simultaneously open connections that an application allows. The default value is 25, according to the Sybase Client-Library documentation.

void RWDBSybCtLibEnvironmentHandle::noLongCharCapability

(

CS_BOOL

value

)

[inline]

Changes the value used for the CS_DATA_NOLCHAR capability with 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.

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

CS_BOOL RWDBSybCtLibEnvironmentHandle::noLongCharCapability

(

)

const [inline]

Returns CS_TRUE if the CS_DATA_NOLCHAR capability is disabled for future connections, otherwise returns CS_FALSE.

The default setting is CS_TRUE, in order to disable connections' use of CS_LONGCHAR.

RWDBStatus RWDBSybCtLibEnvironmentHandle::textLimit

(

CS_INT

value

)

Sets the length in bytes of the longest text or image value an application is prepared to receive, and returns an RWDBStatus indicating whether the operation succeeded.

The Sybase Client-Library reads but ignores 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, call ct_options() directly.

CS_INT RWDBSybCtLibEnvironmentHandle::textLimit

(

)

const

Returns the length in bytes of the longest text or image value an application is prepared to receive.

RWDBStatus RWDBSybCtLibEnvironmentHandle::timeout

(

CS_INT

value

)

Sets the maximum number of seconds to wait for a server response to a command, and returns an RWDBStatus indicating whether the operation succeeded.

The application can set this value any time. It takes effect for all open connections immediately upon being called.

CS_INT RWDBSybCtLibEnvironmentHandle::timeout

(

)

const

Returns the current value for the maximum number of seconds to wait for a server response to a command. The Sybase Client- Library documentation defines the default timeout as infinite.