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

SQLDBC_IRuntime Class Reference

#include <SQLDBC_IRuntime.h>

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 91 of file SQLDBC_IRuntime.h.

Public Types

Public Methods


Member Typedef Documentation

typedef void* SQLDBC_IRuntime::CounterHandle
 

Type definition for a counter handle.

Definition at line 107 of file SQLDBC_IRuntime.h.

typedef void* SQLDBC_IRuntime::MutexHandle
 

Type definition for a mutex.

Definition at line 97 of file SQLDBC_IRuntime.h.

typedef void* SQLDBC_IRuntime::SemaphoreHandle
 

Type definition for a semaphore.

Definition at line 102 of file SQLDBC_IRuntime.h.

typedef SAPDB_UInt4 SQLDBC_IRuntime::TaskID
 

Type definition for a task ID.

Definition at line 128 of file SQLDBC_IRuntime.h.


Constructor & Destructor Documentation

virtual SQLDBC_IRuntime::~SQLDBC_IRuntime   [inline, virtual]
 

Destructor.

Definition at line 133 of file SQLDBC_IRuntime.h.


Member Function Documentation

virtual SAPDB_Bool SQLDBC_IRuntime::cancelCurrentCommand SAPDB_Int8    sessionID,
SAPDBErr_MessageList &    errorMessages
[pure virtual]
 

Cancels the current SQL statment.

Parameters:
sessionID The session ID previously fetched using getSession().
errorMessages A message list, which is filled in case of an error.
Returns:
true if the execution succeeds, false if it fails. In this case the message list 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,
SAPDBErr_MessageList &    errorMessages
[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.
errorMessages A message list, 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 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 168 of file SQLDBC_IRuntime.h.

virtual SAPDB_Bool SQLDBC_IRuntime::createCounter CounterHandle   counterHandle,
SAPDBMem_IRawAllocator &    allocator,
SAPDBErr_MessageList &    errorMessages
[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.
errorMessages A message list, which is filled in case of an error.
Returns:
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.

Parameters:
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.
Returns:
true if the execution succeeds, false if it fails. In this case the message list is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::createSemaphore SemaphoreHandle   semaphoreHandle,
SAPDB_Int4    initialValue,
SAPDBMem_IRawAllocator &    allocator,
SAPDBErr_MessageList &    errorMessages
[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.
errorMessages A message list, which is filled in case of an error.
Returns:
true if the execution succeeds, false if it fails. In this case the message list is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::destroyCounter CounterHandle    counterHandle,
SAPDBMem_IRawAllocator &    allocator,
SAPDBErr_MessageList &    errorMessages
[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.
errorMessages A message list, which filled in case of an error.
Returns:
true if the execution succeeds, false if it fails. In this case the message list is filled.

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.

Parameters:
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.
Returns:
true if the execution succeeds, false if it fails. In this case the message list is filled.

virtual SAPDB_Bool SQLDBC_IRuntime::destroySemaphore SemaphoreHandle   semaphoreHandle,
SAPDBMem_IRawAllocator &    allocator,
SAPDBErr_MessageList &    errorMessages
[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.
errorMessages A message list, which is filled in case of an error.
Returns:
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.

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 140 of file SQLDBC_IRuntime.h.

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.

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.
errorMessages A message list, 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 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 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,
SAPDBErr_MessageList &    errorMessages
[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.
errorMessages A message list, which filled in case of an error.
Returns:
true if the execution succeeds, false if it fails. In this case the message list 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,
SAPDBErr_MessageList &    errorMessages
[pure virtual]
 

Closes a session previously fetched via getSession().

Parameters:
sessionID The session id previously acquired using getSession().
errorMessages A message list, which filled in case of an error.
Returns:
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.

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.
errorMessages A message list, which filled in case of an error.
Returns:
true if the execution succeeds, false if it fails. In this case the message list is filled.

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 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, but of cu

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 464 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.


The documentation for this class was generated from the following file: