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
typedef void * MutexHandle
Type definition for a mutex. typedef void * SemaphoreHandle
Type definition for a semaphore. typedef void * CounterHandle
Type definition for a counter handle. typedef SAPDB_UInt4 TaskID
Type definition for a task ID.
Public Member Functions
virtual ~SQLDBC_IRuntime ()
Destructor. virtual const char * getIdentifier () const
Returns an implementation identifier for diagnostic purposes. virtual SAPDB_Bool 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)
Analyzes a key option. virtual SAPDBMem_IRawAllocator & getGlobalAllocator ()=0
Retrieves the global allocator of the environment. virtual SAPDB_Bool 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)=0
Requests a session. virtual SAPDB_Bool 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)=0
virtual SAPDB_Bool releaseSession (SAPDB_Int8 sessionID, SQLDBC_IRuntime::Error &error)=0
Closes a session previously fetched via getSession() . virtual SAPDB_Bool request (SAPDB_Int8 sessionID, void *requestData, SAPDB_UInt4 requestDataLength, SQLDBC_IRuntime::Error &error)=0
Performs a request to the database kernel. virtual SAPDB_Bool receive (SAPDB_Int8 sessionID, void **replyData, SAPDB_Int4 &replyDataLength, SQLDBC_IRuntime::Error &error)=0
Retrieves data from the database kernel. virtual SAPDB_Bool isReplyAvailable (SAPDB_Int8 sessionID)
Checks whether there is reply available for the last command. virtual SAPDB_Bool cancelCurrentCommand (SAPDB_Int8 sessionID, SQLDBC_IRuntime::Error &error)=0
Cancels the current SQL statment. virtual SQLDBC_Spinlock * createSpinlock (SAPDBMem_IRawAllocator &allocator)=0
Creates a Spinlock object. virtual SAPDB_Bool releaseSpinlock (SAPDBMem_IRawAllocator &allocator, SQLDBC_Spinlock *lock)=0
Unlocks a Spinlock object. virtual SAPDB_Bool createMutex (MutexHandle &mutexHandle, SAPDBMem_IRawAllocator &allocator, SQLDBC_IRuntime::Error &error)=0
Creates a mutex. virtual SAPDB_Bool lockMutex (MutexHandle mutexHandle)=0
Locks a mutex. virtual SAPDB_Bool releaseMutex (MutexHandle mutexHandle)=0
Unlocks a mutex. virtual SAPDB_Bool destroyMutex (MutexHandle &mutexHandle, SAPDBMem_IRawAllocator &allocator, SQLDBC_IRuntime::Error &error)=0
Destroys a mutex. virtual SAPDB_Bool createCounter (CounterHandle &counterHandle, SAPDBMem_IRawAllocator &allocator, SQLDBC_IRuntime::Error &error)=0
Creates an atomic counter. virtual SAPDB_UInt4 nextCounter (CounterHandle counterHandle)=0
Increments the counter. virtual SAPDB_Bool destroyCounter (CounterHandle counterHandle, SAPDBMem_IRawAllocator &allocator, SQLDBC_IRuntime::Error &error)=0
Destroys an atomic counter. virtual TaskID getCurrentTaskID ()=0
Returns the ID of the current task. virtual SAPDB_Bool createSemaphore (SemaphoreHandle &semaphoreHandle, SAPDB_Int4 initialValue, SAPDBMem_IRawAllocator &allocator, SQLDBC_IRuntime::Error &error)=0
Creates a semaphore. virtual SAPDB_Bool waitSemaphore (SemaphoreHandle semaphoreHandle)=0
Waits for the semaphore, decreases its value by one and waits if the value of the semaphore is less or equal zero. virtual SAPDB_Bool signalSemaphore (SemaphoreHandle semaphoreHandle)=0
Release a semaphore, increases its value by one. virtual SAPDB_Bool destroySemaphore (SemaphoreHandle &semaphoreHandle, SAPDBMem_IRawAllocator &allocator, SQLDBC_IRuntime::Error &error)=0
Destroys a semaphore. virtual TaskTraceContext * getTaskTraceContext ()=0
Requests the task trace context. virtual void write (const char *s, SAPDB_Int4 size)=0
Writes in the trace. virtual void writeln (const char *s, SAPDB_Int4 size)=0
Writes in the trace an adds a new line. virtual void updateTraceFlags (SAPDB_Bool &traceEnabled)
Updates the internal trace flags, so that changes in trace settings are detected. virtual SAPDB_Bool traceError (SAPDB_Int4 errorcode)
Called when an error is traced. virtual void setTraceOptions (const char *optionstring)
virtual SAPDB_Int4 getTraceOptions (char *options, SAPDB_Int4 optionslength)
virtual void addTraceFlags (unsigned int flags)=0
Set trace flags programatically. virtual void removeTraceFlags (unsigned int flags)=0
Set trace flags programatically. virtual unsigned int getTraceFlags ()
Get trace flags programatically. virtual SAPDB_Bool 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)
Retrieve specific internally needed system information.
Protected Member Functions
Protected Attributes
Classes
Member Typedef Documentation
Constructor & Destructor Documentation
virtual SQLDBC_IRuntime::~SQLDBC_IRuntime
(
)
[inline, virtual]
SQLDBC_IRuntime::SQLDBC_IRuntime
(
SQLDBC_Spinlock *
lock
)
[inline, protected]
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 .
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.
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.
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.
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.
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]
virtual SAPDB_Int4 SQLDBC_IRuntime::getTraceOptions
(
char *
options ,
SAPDB_Int4
optionslength
)
[inline, virtual]
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]
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