Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

SQLDBC_IRuntime Class Reference

List of all members.

Detailed Description

SQLDBC_IRuntime is the interface to the runtime environment abstraction.

The applications (for example client applications or the database kernel) may use different environments.. The SQLDBC_IRuntime encapsulates all calls related to the runtime environment like synchronization, tracing, and global memory allocation.

The implemented client runtime environment is the default for client applications.

If another runtime implementation is required , it must be set when the SQLDBC_Environment is initialized.

Example:

 MyRuntime runtime;
 SQLDBC_Environment *env=
   SQLDBC_Environment::createEnvironment(&runtime);
 

For creating a new runtime environment, implement the interface. It must be completely initialized when the runtime environment is passed on as argument to the SQLDBC environment. Do not destroy the runtime environment object before the SQLDBC environment has been destroyed.

Decide whether the runtime object shall be 'default constructible', 'copy constructible', or 'assignable'. The interface runtime guarantees only that no other instances are created by the runtime itself using copy and/or assignment. only those instances are used that are handed out to an environment, and no other instances are created by the runtime itself through copy and/or assignment.

The interfaces makes also no statement about the relation between the runtime, environments, and connections. With the client runtime, there is a relation 1:n:m between these, but if you guarantee by your application for example an 1:1:1 relation you may be able to omit a lot of functionality, or supply dummy implementations.

The same applies to multi-threading - if it is not needed you may supply dummy placeholder implementations for the lock operations.

Definition at line 108 of file SQLDBC_IRuntime.h.

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Classes


Member Typedef Documentation

typedef void* SQLDBC_IRuntime::CounterHandle
 

Type definition for a counter handle.

Definition at line 143 of file SQLDBC_IRuntime.h.

typedef void* SQLDBC_IRuntime::MutexHandle
 

Type definition for a mutex.

Definition at line 133 of file SQLDBC_IRuntime.h.

typedef void* SQLDBC_IRuntime::SemaphoreHandle
 

Type definition for a semaphore.

Definition at line 138 of file SQLDBC_IRuntime.h.

typedef SAPDB_UInt4 SQLDBC_IRuntime::TaskID
 

Type definition for a task ID.

Definition at line 164 of file SQLDBC_IRuntime.h.


Constructor & Destructor Documentation

virtual SQLDBC_IRuntime::~SQLDBC_IRuntime  )  [inline, virtual]
 

Destructor.

Definition at line 169 of file SQLDBC_IRuntime.h.

SQLDBC_IRuntime::SQLDBC_IRuntime SQLDBC_Spinlock *  lock  )  [inline, protected]
 

Definition at line 629 of file SQLDBC_IRuntime.h.


Member Function Documentation

virtual void SQLDBC_IRuntime::addTraceFlags unsigned int  flags  )  [pure virtual]
 

Set trace flags programatically.

Parameters:
flags Bitmask that is added to the current setting.

virtual SAPDB_Bool SQLDBC_IRuntime::cancelCurrentCommand SAPDB_Int8  sessionID,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Cancels the current SQL statment.

Parameters:
sessionID The session ID previously fetched using getSession().
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::checkKeyOption const char *  keyoption,
char *  servernode,
SAPDB_Int4 &  servernodelength,
char *  serverdb,
SAPDB_Int4 &  serverdblength,
SAPDB_Int4 &  isolationlevel,
SAPDB_Int4 &  cachelimit,
SAPDB_Int4 &  sqlmode,
SAPDB_Int4 &  timeout,
char *  username,
SAPDB_Int4 &  usernamelength,
SQLDBC_StringEncoding &  usernameEncoding,
SQLDBC_IRuntime::Error error
[inline, virtual]
 

Analyzes a key option.

This means an XUSER record or the SQLOPT environment variable is evaluated.

Parameters:
keyoption The KEY option value.
servernode The name of the database server (ASCII)
servernodelength The length in bytes of the database server name.
serverdb The name of the database instance (ASCII).
serverdblength The length in bytes of the database instance name.
isolationlevel The isolation level.
cachelimit The CACHELIMIT value.
sqlmode The SQL mode.
timeout The TIMEOUT value.
username The name of the database user. The encoding of this string depends on the usernameEncoding argument.
usernamelength The length in bytes of the database user name.
usernameEncoding The character encoding of the username.
error A error object, which filled in case of an error.
Returns:
true if the call succeeds, false if it fails, or there was nothing to do. In case of a failure, the error object is filled. If the call succeeds, servernode, servernodelength, serverdb, serverdblength, isolationlevel, isolationlevel, cachelimit, sqlmode, timeout, username, and usernamelength are filled with the respective data extracted from the URL.

Definition at line 204 of file SQLDBC_IRuntime.h.

virtual SAPDB_Bool SQLDBC_IRuntime::createCounter CounterHandle counterHandle,
SAPDBMem_IRawAllocator &  allocator,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Creates an atomic counter.

Parameters:
counterHandle The handle to the counter that is created.
allocator The allocator used to allocate memory to the counter handle.
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::createMutex MutexHandle mutexHandle,
SAPDBMem_IRawAllocator &  allocator,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Creates a mutex.

Parameters:
mutexHandle The handle to the mutex, that is set on return.
allocator The allocator used allocate the mutex handle.
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::createSemaphore SemaphoreHandle semaphoreHandle,
SAPDB_Int4  initialValue,
SAPDBMem_IRawAllocator &  allocator,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Creates a semaphore.

Parameters:
semaphoreHandle Handle to the semaphore that is created.
initialValue The initial value of the counter.
allocator The allocator used to allocate memory to the semaphore.
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SQLDBC_Spinlock* SQLDBC_IRuntime::createSpinlock SAPDBMem_IRawAllocator &  allocator  )  [pure virtual]
 

Creates a Spinlock object.

Parameters:
allocator The allocator used allocate the spinlock handle.
Returns:
SQLDBC_Spinlock if the execution succeeds, 0 if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::destroyCounter CounterHandle  counterHandle,
SAPDBMem_IRawAllocator &  allocator,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Destroys an atomic counter.

Parameters:
counterHandle The counter to be destroyed.
allocator The allocator used for deallocating the memory used by the counter.
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::destroyMutex MutexHandle mutexHandle,
SAPDBMem_IRawAllocator &  allocator,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Destroys a mutex.

Write a zero in the handle.

Parameters:
mutexHandle The handle to the mutex.
allocator The allocator used for de-allocating the memory used by the mutex.
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::destroySemaphore SemaphoreHandle semaphoreHandle,
SAPDBMem_IRawAllocator &  allocator,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Destroys a semaphore.

Parameters:
semaphoreHandle The handle to the semaphore that is destroyed.
allocator The allocator used for de-allocating the memory used by the semaphore.
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual TaskID SQLDBC_IRuntime::getCurrentTaskID  )  [pure virtual]
 

Returns the ID of the current task.

If it is single threaded, the implementation needs not distinguish between threads and can return a constant value.

Returns:
The task ID of the current task.

virtual SAPDBMem_IRawAllocator& SQLDBC_IRuntime::getGlobalAllocator  )  [pure virtual]
 

Retrieves the global allocator of the environment.

The global allocator is used for allocating globally used memory. It is also used if no special allocator is specified when a connection is created.

virtual const char* SQLDBC_IRuntime::getIdentifier  )  const [inline, virtual]
 

Returns an implementation identifier for diagnostic purposes.

Returns:
An implementation identifier to be used for diagnostic purposes.

Definition at line 176 of file SQLDBC_IRuntime.h.

virtual SAPDB_Bool SQLDBC_IRuntime::getSession const char *  connectUrl,
const char *  connectCommand,
const char *  username,
SAPDB_Int4  usernamelength,
const char *  password,
SAPDB_Int4  passwordLength,
const SQLDBC_StringEncoding  commandEncoding,
SAPDB_Int8 &  sessionID,
SAPDB_UInt4 &  packetSize,
SAPDB_Int4 &  packetListSize,
void **  packetList,
void **  sessionInfoReply,
SQLDBC_IRuntime::Error error,
SAPDBMem_IRawAllocator *  allocator = 0
[pure virtual]
 

virtual SAPDB_Bool SQLDBC_IRuntime::getSession const char *  connectUrl,
const char *  connectCommand,
const char *  password,
SAPDB_Int4  passwordLength,
const SQLDBC_StringEncoding  commandEncoding,
SAPDB_Int8 &  sessionID,
SAPDB_UInt4 &  packetSize,
SAPDB_Int4 &  packetListSize,
void **  packetList,
void **  sessionInfoReply,
SQLDBC_IRuntime::Error error,
SAPDBMem_IRawAllocator *  allocator = 0
[pure virtual]
 

Requests a session.

The session is used to send SQL statement to the database server. Depending on the application context, this method may open a client connection, or re-use an existing context.

Parameters:
connectUrl The URL for the physical connection. If the parameter is not used, its value must be zero.
connectCommand The SQL CONNECT statement, as it will be sent to the database null-terminated. If the parameter is not used, its value must be zero.
password The unencrypted password. If the parameter is not used, its value must be zero.
passwordLength The length of the password in bytes.
commandEncoding The encoding of the connect command and the password.
sessionID [out] The ID of the session. It must be a number > zero.
packetSize [out] The size of the packet in bytes.
packetListSize [in|out] The size of the packet list. The number of returned packets may be smaller but must not exceed the number of packets specified in the list. The number of packets actually created is reported in this variable return.
packetList The packet list. An array of packetListSize pointers to void *, which point to a block having the size of packetSize which are to be used in the request() method.
sessionInfoReply Pointer reply to th to the CONNECT statement. The reply contains at least a session info part to inform the application on details about the database (Unicode flag, date format, etc.). The reply is associated with the first element of the returned packet list.
error A error object, which filled in case of an error.
allocator The allocator for allocating memory.
Returns:
true if the session is established, false if it fails. In this case the errorMessages are filled.

virtual SAPDB_Bool SQLDBC_IRuntime::getSessionInformation SQLDBC_Connection connection,
SAPDB_Int8 &  sessionID,
SAPDB_UInt4 &  packetSize,
SAPDB_UInt4 &  pagesSize,
SAPDB_Int4 &  packetListSize,
void **  packetList,
char *  usergroup,
char *  sysdba,
SQLDBC_StringEncoding &  userencoding
[inline, virtual]
 

Retrieve specific internally needed system information.

Definition at line 600 of file SQLDBC_IRuntime.h.

virtual TaskTraceContext* SQLDBC_IRuntime::getTaskTraceContext  )  [pure virtual]
 

Requests the task trace context.

Must return for each task a unique pointer to the data structure of the type TaskTraceContext.

Returns:
For each task a unique pointer to the data structure of the type TaskTraceContext, or 0 if this runtime implementation does not support tracing.

virtual unsigned int SQLDBC_IRuntime::getTraceFlags  )  [inline, virtual]
 

Get trace flags programatically.

Definition at line 591 of file SQLDBC_IRuntime.h.

virtual SAPDB_Int4 SQLDBC_IRuntime::getTraceOptions char *  options,
SAPDB_Int4  optionslength
[inline, virtual]
 

Definition at line 568 of file SQLDBC_IRuntime.h.

virtual SAPDB_Bool SQLDBC_IRuntime::isReplyAvailable SAPDB_Int8  sessionID  )  [inline, virtual]
 

Checks whether there is reply available for the last command.

Parameters:
sessionID The session id of the session to query.

Definition at line 347 of file SQLDBC_IRuntime.h.

virtual SAPDB_Bool SQLDBC_IRuntime::lockMutex MutexHandle  mutexHandle  )  [pure virtual]
 

Locks a mutex.

Parameters:
mutexHandle The handle to the mutex.
Returns:
true if the method succeeds, false if it fails.

virtual SAPDB_UInt4 SQLDBC_IRuntime::nextCounter CounterHandle  counterHandle  )  [pure virtual]
 

Increments the counter.

Parameters:
counterHandle The handle to the counter be incremented.
Returns:
The new value of the counter.

virtual SAPDB_Bool SQLDBC_IRuntime::receive SAPDB_Int8  sessionID,
void **  replyData,
SAPDB_Int4 &  replyDataLength,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Retrieves data from the database kernel.

Parameters:
sessionID The session ID previously fetched using getSession().
replyData Pointer to the pointer to the reply.
replyDataLength Length of the reply returnes.
error A error object, which filled in case of an error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::releaseMutex MutexHandle  mutexHandle  )  [pure virtual]
 

Unlocks a mutex.

Parameters:
mutexHandle The handle to the mutex that shall be unlocked.
Returns:
true if the mutex was unlocked successfully, false if it fails.

virtual SAPDB_Bool SQLDBC_IRuntime::releaseSession SAPDB_Int8  sessionID,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Closes a session previously fetched via getSession().

Parameters:
sessionID The session id previously acquired using getSession().
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::releaseSpinlock SAPDBMem_IRawAllocator &  allocator,
SQLDBC_Spinlock *  lock
[pure virtual]
 

Unlocks a Spinlock object.

Parameters:
allocator The allocator used to free the spinlock handle.
lock Spinlock object, the handle to the Spinlock object that shall be unlocked.
Returns:
true if the Spinlock object was unlocked successfully, false if it fails.

virtual void SQLDBC_IRuntime::removeTraceFlags unsigned int  flags  )  [pure virtual]
 

Set trace flags programatically.

Parameters:
flags Bitmask that is removed from the current setting.

virtual SAPDB_Bool SQLDBC_IRuntime::request SAPDB_Int8  sessionID,
void *  requestData,
SAPDB_UInt4  requestDataLength,
SQLDBC_IRuntime::Error error
[pure virtual]
 

Performs a request to the database kernel.

Parameters:
sessionID The session ID previously fetched using getSession().
requestData Pointer to the request data, usually an element of the packet list fetched using getSession().
requestDataLength The number of bytes to be sent.
error An error object to be filled in case of error.
Returns:
true if the execution succeeds, false if it fails. In this case the error object is filled.

virtual void SQLDBC_IRuntime::setTraceOptions const char *  optionstring  )  [inline, virtual]
 

Definition at line 563 of file SQLDBC_IRuntime.h.

virtual SAPDB_Bool SQLDBC_IRuntime::signalSemaphore SemaphoreHandle  semaphoreHandle  )  [pure virtual]
 

Release a semaphore, increases its value by one.

Parameters:
semaphoreHandle The handle to the semaphore.
Returns:
true if the execution succeeds, false if it fails.

virtual SAPDB_Bool SQLDBC_IRuntime::traceError SAPDB_Int4  errorcode  )  [inline, virtual]
 

Called when an error is traced.

The runtime may count or disable tracing as result of this method call.

Parameters:
errorcode The error code that has happened.
Returns:
true if some trace was switched off.

Definition at line 559 of file SQLDBC_IRuntime.h.

virtual void SQLDBC_IRuntime::updateTraceFlags SAPDB_Bool &  traceEnabled  )  [inline, virtual]
 

Updates the internal trace flags, so that changes in trace settings are detected.

This method is called by the interface runtime from time to check whether updates are available. If the update fails, there shall be no error reported.

Parameters:
traceEnabled Flag, which is is set to true if any trace is enabled, and set to false if there is no trace that can be enabled.

Definition at line 541 of file SQLDBC_IRuntime.h.

virtual SAPDB_Bool SQLDBC_IRuntime::waitSemaphore SemaphoreHandle  semaphoreHandle  )  [pure virtual]
 

Waits for the semaphore, decreases its value by one and waits if the value of the semaphore is less or equal zero.

Parameters:
semaphoreHandle The handle to the semaphore.
Returns:
true if the execution succeeds, false if it fails.

virtual void SQLDBC_IRuntime::write const char *  s,
SAPDB_Int4  size
[pure virtual]
 

Writes in the trace.

Parameters:
s The string to be printed, in UTF8 code.
size The size of the string or -1 if the size of the string is to be determined using strlen.

virtual void SQLDBC_IRuntime::writeln const char *  s,
SAPDB_Int4  size
[pure virtual]
 

Writes in the trace an adds a new line.

Parameters:
s The string to be printed, in UTF8 code.
size The size of the string or -1 if the size of the string is to be determined using strlen.


Member Data Documentation

EnvironmentList SQLDBC_IRuntime::m_environmentlist [protected]
 

Definition at line 639 of file SQLDBC_IRuntime.h.

Profile SQLDBC_IRuntime::m_profile [protected]
 

Definition at line 640 of file SQLDBC_IRuntime.h.