IBM Books

API Reference

Appendix E. Threaded Applications with Concurrent Access

In the default implementation of threaded applications against a DB2 database, serialization of access to the database is enforced by the database APIs. If one thread performs a database call that is blocked for some reason (that is, the table is already in exclusive use), all other threads will be blocked as well. In addition, all threads within a process share a commit scope. True concurrent access to a database can only be achieved through separate processes, or by using the APIs that are described in this section.

This section describes APIs that can be used to allocate and manipulate separate enviroments (contexts) for the use of database APIs and embedded SQL. Each context is a separate entity, and any connection or attachment using one context is independent of all other contexts (and thus all other connections or attachments within a process). In order for work to be done on a context, it must first be associated with a thread. A thread must always have a context when making database API calls or when using embedded SQL. If these APIs to manipuate contexts are not used, all threads within a process share the same context. If these APIs are used, each thread can have its own context. It will have a separate connection to a database or attachment to an instance, and will have its own commit scope.

Contexts need not be associated with a given thread for the duration of a connection or attachment. One thread can attach to a context, connect to a database, detach from the context, and then a second thread can attach to the context and continue doing work using the already existing database connection. Contexts can be passed around among threads in a process, but not among processes.

If the new APIs are not used, the old behavior is in effect, and existing applications need not change.

Even if the new APIs are used, the following APIs continue to be serialized:

The new APIs can be used with embedded SQL and the transaction APIs.

These APIs have no effect (that is, they are no-ops) on platforms that do not support application threading.
Note:CLI automatically uses the new scheme (it creates a new context for each incoming connection), and it is up to the user to disable this explicitly. For more information, see the CLI Guide and Reference.

sqleAttachToCtx - Attach to Context

Makes the current thread use a specified context. All subsequent database calls made on this thread will use this context. If more than one thread is attached to a given context, access is serialized for these threads, and they share a commit scope.

Scope

The scope of this API is limited to the immediate process.

Authorization

None

Required Connection

Database

API Include File

sql.h

C API Syntax 



int sqleAttachToCtx (
void           *pCtx,
void           *reserved,
struct sqlca   *pstSqlca);

API Parameters

pCtx
Input. A structure defining the context.
Note:pCtx must be a valid context previously allocated by sqleBeginCtx - Create and Attach to an Application Context.
reserved
Reserved for future use.
pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

sqleBeginCtx - Create and Attach to an Application Context

Creates an application context, or creates and then attaches to an application context. More than one application context can be created. Each context has its own commit scope. Different threads can attach to different contexts (see sqleAttachToCtx - Attach to Context). Any database API calls made by such threads will not be serialized with one another.

Scope

The scope of this API is limited to the immediate process.

Authorization

None

Required Connection

Database

API Include File

sql.h

C API Syntax 



int sqleBeginCtx (
void           **ppCtx,
long           lOptions,
void           *reserved,
struct sqlca   *pstSqlca);

API Parameters

ppCtx
Output. A structure defining the context. This API allocates a data area out of private memory for the storage of context information.
lOptions
Input. Valid values are:
SQL_CTX_CREATE_ONLY
The context memory will be allocated, but there will be no attachment.
SQL_CTX_BEGIN_ALL
The context memory will be allocated, and then a call to sqleAttachToCtx - Attach to Context will be made for the current thread. If this option is used, the ppCtx parameter can be NULL. If the thread is already attached to a context, the call will fail.
reserved
Reserved for future use.
pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

sqleDetachFromCtx - Detach From Context

Detaches the context being used by the current thread. The context will be detached only if an attach to that context has previously been made.

Scope

The scope of this API is limited to the immediate process.

Authorization

None

Required Connection

Database

API Include File

sql.h

C API Syntax 



int sqleDetachFromCtx (
void           *pCtx,
void           *reserved,
struct sqlca   *pstSqlca);

API Parameters

pCtx
Input. A structure defining the context.
Note:pCtx must be a valid context previously allocated by sqleBeginCtx - Create and Attach to an Application Context.
reserved
Reserved for future use.
pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

sqleEndCtx - Detach and Destroy Application Context

Frees all memory associated with a given context.

Scope

The scope of this API is limited to the immediate process.

Authorization

None

Required Connection

None

API Include File

sql.h

C API Syntax 



int sqleEndCtx (
void           **pCtx,
long           lOptions,
void           *reserved,
struct sqlca   *pstSqlca);

API Parameters

pCtx
Output. A structure defining the context. This API frees a data area in private memory used for the storage of context information.
lOptions
Input. Valid values are:
SQL_CTX_FREE_ONLY
The context memory will be freed only if a prior detach has been done.
Note:pCtx must be a valid context previously allocated by sqleBeginCtx - Create and Attach to an Application Context.
SQL_CTX_END_ALL
If necessary, a call to sqleDetachFromCtx - Detach From Context will be made before the memory is freed.
Note:A detach will be done even if the context is still in use. If this option is used, the ppCtx parameter can be NULL, but if passed, it must be a valid context previously allocated by sqleBeginCtx - Create and Attach to an Application Context. A call to sqleGetCurrentCtx - Get Current Context will be made, and the current context freed from there.
reserved
Reserved for future use.
pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

Usage Notes

If a database connection exists, or the context has been attached by another thread, this call will fail.
Note:If a context calls an API that establishes an instance attachment (for example, sqlfxdb - Get Database Configuration), it is necessary to detach from the instance using sqledtin - Detach before calling sqleEndCtx.

sqleGetCurrentCtx - Get Current Context

Returns the current context associated with a thread.

Scope

The scope of this API is limited to the immediate process.

Authorization

None

Required Connection

Database

API Include File

sql.h

C API Syntax 



int sqleGetCurrentCtx (
void           **ppCtx,
void           *reserved,
struct sqlca   *pstSqlca);

API Parameters

ppCtx
Input. A structure defining the context.
reserved
Reserved for future use.
pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

sqleInterruptCtx - Interrupt Context

Interrupts the specified context.

Scope

The scope of this API is limited to the immediate process.

Authorization

None

Required Connection

Database

API Include File

sql.h

C API Syntax 



int sqleInterruptCtx (
void           *pCtx,
void           *reserved,
struct sqlca   *pstSqlca);

API Parameters

pCtx
Input. A structure defining the context.
Note:pCtx must be a valid context previously allocated by sqleBeginCtx - Create and Attach to an Application Context.
reserved
Reserved for future use.
pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

Usage Notes

During processing, this API:

sqleSetTypeCtx - Set Application Context Type

Sets the application context type. This API should be the first database API called inside an application.

Scope

The scope of this API is limited to the immediate process.

Authorization

None

Required Connection

Database

API Include File

sql.h

C API Syntax 



int sqleSetTypeCtx (
long   lOptions);

API Parameters

lOptions
Input. Valid values are:
SQL_CTX_ORIGINAL
All threads will use the same context, and concurrent access will be blocked. This is the default if none of these APIs is called.
SQL_CTX_MULTI_MANUAL
All threads will use separate contexts, and it is up to the application to manage the contex for each thread. See

The following restrictions/changes apply when this option is used:

Usage Notes

This API must be called before any other database call, and only the first call is effective.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]