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 96 of file SQLDBC_IRuntime.h.
typedef void* SQLDBC_IRuntime::MutexHandle |
typedef void* SQLDBC_IRuntime::SemaphoreHandle |
typedef void* SQLDBC_IRuntime::CounterHandle |
typedef SAPDB_UInt4 SQLDBC_IRuntime::TaskID |
virtual SQLDBC_IRuntime::~SQLDBC_IRuntime | ( | ) | [inline, virtual] |
virtual const char* SQLDBC_IRuntime::getIdentifier | ( | ) | const [inline, virtual] |
Returns an implementation identifier for diagnostic purposes.
Definition at line 145 of file SQLDBC_IRuntime.h.
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, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [inline, virtual] |
Analyzes a key option.
This means an XUSER record or the SQLOPT
environment variable is evaluated.
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. | |
errorMessages | A message list, which filled in case of an error. |
true
if the call succeeds, false
if it fails, or there was nothing to do. In case of a failure, the message list 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 173 of file SQLDBC_IRuntime.h.
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 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, | |||
SAPDBErr_MessageList & | errorMessages, | |||
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.
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. | |
errorMessages | A message list, which filled in case of an error. | |
allocator | The allocator for allocating memory. |
true
if the session is established, false
if it fails. In this case the errorMessages are filled. virtual SAPDB_Bool SQLDBC_IRuntime::releaseSession | ( | SAPDB_Int8 | sessionID, | |
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Closes a session previously fetched via getSession().
sessionID | The session id previously acquired using getSession() . | |
errorMessages | A message list, which filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. virtual SAPDB_Bool SQLDBC_IRuntime::request | ( | SAPDB_Int8 | sessionID, | |
void * | requestData, | |||
SAPDB_UInt4 | requestDataLength, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Performs a request to the database kernel.
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. | |
errorMessages | A message list, which filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. virtual SAPDB_Bool SQLDBC_IRuntime::receive | ( | SAPDB_Int8 | sessionID, | |
void ** | replyData, | |||
SAPDB_Int4 & | replyDataLength, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Retrieves data from the database kernel.
sessionID | The session ID previously fetched using getSession(). | |
replyData | Pointer to the pointer to the reply. | |
replyDataLength | Length of the reply returnes. | |
errorMessages | A message list, which filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. virtual SAPDB_Bool SQLDBC_IRuntime::cancelCurrentCommand | ( | SAPDB_Int8 | sessionID, | |
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Cancels the current SQL statment.
sessionID | The session ID previously fetched using getSession(). | |
errorMessages | A message list, which is filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. virtual SAPDB_Bool SQLDBC_IRuntime::createMutex | ( | MutexHandle & | mutexHandle, | |
SAPDBMem_IRawAllocator & | allocator, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Creates a mutex.
mutexHandle | The handle to the mutex, that is set on return. | |
allocator | The allocator used allocate the mutex handle. | |
errorMessages | A message list, which is filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. virtual SAPDB_Bool SQLDBC_IRuntime::lockMutex | ( | MutexHandle | mutexHandle | ) | [pure virtual] |
Locks a mutex.
mutexHandle | The handle to the mutex. |
true
if the method succeeds, false
if it fails. virtual SAPDB_Bool SQLDBC_IRuntime::releaseMutex | ( | MutexHandle | mutexHandle | ) | [pure virtual] |
Unlocks a mutex.
mutexHandle | The handle to the mutex that shall be unlocked. |
true
if the mutex was unlocked successfully, false
if it fails. virtual SAPDB_Bool SQLDBC_IRuntime::destroyMutex | ( | MutexHandle & | mutexHandle, | |
SAPDBMem_IRawAllocator & | allocator, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Destroys a mutex.
Write a zero in the handle.
mutexHandle | The handle to the mutex. | |
allocator | The allocator used for de-allocating the memory used by the mutex. | |
errorMessages | A message list, which is filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. virtual SAPDB_Bool SQLDBC_IRuntime::createCounter | ( | CounterHandle & | counterHandle, | |
SAPDBMem_IRawAllocator & | allocator, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Creates an atomic counter.
counterHandle | The handle to the counter that is created. | |
allocator | The allocator used to allocate memory to the counter handle. | |
errorMessages | A message list, which is filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. virtual SAPDB_UInt4 SQLDBC_IRuntime::nextCounter | ( | CounterHandle | counterHandle | ) | [pure virtual] |
Increments the counter.
counterHandle | The handle to the counter be incremented. |
virtual SAPDB_Bool SQLDBC_IRuntime::destroyCounter | ( | CounterHandle | counterHandle, | |
SAPDBMem_IRawAllocator & | allocator, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Destroys an atomic counter.
counterHandle | The counter to be destroyed. | |
allocator | The allocator used for deallocating the memory used by the counter. | |
errorMessages | A message list, which filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list 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.
virtual SAPDB_Bool SQLDBC_IRuntime::createSemaphore | ( | SemaphoreHandle & | semaphoreHandle, | |
SAPDB_Int4 | initialValue, | |||
SAPDBMem_IRawAllocator & | allocator, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Creates a semaphore.
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. | |
errorMessages | A message list, which is filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. 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.
semaphoreHandle | The handle to the semaphore. |
true
if the execution succeeds, false
if it fails. virtual SAPDB_Bool SQLDBC_IRuntime::signalSemaphore | ( | SemaphoreHandle | semaphoreHandle | ) | [pure virtual] |
Release a semaphore, increases its value by one.
semaphoreHandle | The handle to the semaphore. |
true
if the execution succeeds, false
if it fails. virtual SAPDB_Bool SQLDBC_IRuntime::destroySemaphore | ( | SemaphoreHandle & | semaphoreHandle, | |
SAPDBMem_IRawAllocator & | allocator, | |||
SAPDBErr_MessageList & | errorMessages | |||
) | [pure virtual] |
Destroys a semaphore.
semaphoreHandle | The handle to the semaphore that is destroyed. | |
allocator | The allocator used for de-allocating the memory used by the semaphore. | |
errorMessages | A message list, which is filled in case of an error. |
true
if the execution succeeds, false
if it fails. In this case the message list is filled. 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.
0
if this runtime implementation does not support tracing. virtual void SQLDBC_IRuntime::write | ( | const char * | s, | |
SAPDB_Int4 | size | |||
) | [pure virtual] |
Writes in the trace.
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.
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::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.
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 469 of file SQLDBC_IRuntime.h.
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.
errorcode | The error code that has happened. |
true
if some trace was switched off. Definition at line 477 of file SQLDBC_IRuntime.h.
virtual void SQLDBC_IRuntime::setTraceOptions | ( | const char * | optionstring | ) | [inline, virtual] |
Definition at line 481 of file SQLDBC_IRuntime.h.
virtual SAPDB_Int4 SQLDBC_IRuntime::getTraceOptions | ( | char * | options, | |
SAPDB_Int4 | optionslength | |||
) | [inline, virtual] |
Definition at line 486 of file SQLDBC_IRuntime.h.