CONTEXT

CONTEXT
Prev	Up	34.14. Embedded SQL Commands	Home	Next

CONTEXT — context for database connection

Synopsis

      CONTEXT ALLOCATE context_var
      CONTEXT USE context_var
      CONTEXT USE DEFAULT
      CONTEXT FREE context_var

Description

The CONTEXT is used for context operations that are compatible with Oracle database connections. In LightDB, CONTEXT defines and records a unique label for the associated database connection, allowing database connections to be managed through CONTEXT.

Command

ALLOCATE: Allocate memory space to the context.
USE: Runs the last database connection associated with the specified context.
FREE: To disconnect the database connection associated with a context, while also releasing the memory of the context defined using ALLOCATE.

Parameters

context_var: The context defined by context_var must be declared as a type of sql_context before it can be used.
DEFAULT: All database connections that are not associated using CONTEXT USE.

Examples

Here are some examples of using contexts:

sql_context ctx1;
sql_context ctx12;
EXEC SQL CONTEXT ALLOCATE :ctx1;
EXEC SQL CONTEXT USE :ctx1;
EXEC SQL CONNECT TO :usr1;


EXEC SQL CONTEXT ALLOCATE :ctx2;
EXEC SQL CONTEXT USE :ctx2;
EXEC SQL CONNECT TO  :usr2;


EXEC SQL CONTEXT USE :ctx1;
EXEC SQL CONTEXT USE :ctx2;

EXEC SQL CONTEXT USE DEFAULT;

EXEC SQL CONTEXT FREE :ctx1;
EXEC SQL CONTEXT FREE :ctx2;

Here is an example program demonstrating the use of contexts:

int
main(void)
{
	EXEC SQL BEGIN DECLARE SECTION;
	char *dbname     = "testdb";    /* database name */
	char *user       = "testuser";  /* connection user name */
	char *connection = "tcp:postgresql://localhost:5432/testdb"; /* connection string */
	char date[64];                  /* Buffer for storing the date */
	EXEC SQL END DECLARE SECTION;
	
	sql_context ctx1;
	sql_context ctx12;
	
	ECPGdebug(1, stderr);
	
	EXEC SQL CONTEXT ALLOCATE :ctx1;
	EXEC SQL CONTEXT USE :ctx1;
	EXEC SQL CONNECT TO :dbname USER :user;
	EXEC SQL ALTER SESSION SET NLS_DATE_FORMAT = 'yyyy::mm::dd';　
	EXEC SQL SELECT sysdate INTO :date;
	printf("sysdate: %s\n", date);
	
	EXEC SQL CONTEXT ALLOCATE :ctx２;
	EXEC SQL CONTEXT USE :ctx2;
	EXEC SQL CONNECT TO :connection USER :user;
	EXEC SQL ALTER SESSION SET NLS_DATE_FORMAT = 'yyyy_mm_dd';　
	EXEC SQL SELECT sysdate INTO :date;
	printf("sysdate: %s\n", date);
	
	EXEC SQL CONTEXT USE :ctx1;
	EXEC SQL SELECT sysdate INTO :date;
	printf("sysdate: %s\n", date);
	
	EXEC SQL CONTEXT USE :ctX2;
	EXEC SQL SELECT sysdate INTO :date;
	printf("sysdate: %s\n", date);
	
	EXEC SQL CONTEXT FREE :ctx1;
	EXEC SQL CONTEXT FREE :ctx2;
	
	return 0;
}

Characterization

Multi-threading is not supported.
The length of the identifier for the context is limited to a maximum of 132 characters, including 132.
The CONTEXT ALLOCATE command will reallocate a new memory space for the context, and the information such as database connections associated with the context will not be copied or inherited.
Only by using CONTEXT FREE will all database connections associated with the context be disconnected. At the same time, if the current context was defined using CONTEXT ALLOCATE, it will release the dynamically allocated memory for the current context.
When a function starts but does not connect to the database using CONTEXT or CONNECT, the SQL executed will use the DEFAULT connection.

When one of the following three situations occurs, the SQL that requires a database connection to execute will be intercepted.

1.CONTEXT does not use ALLOCATE to allocate memory.
2. CONTEXT USE is used, but the context has not been associated with the database yet. CONNECT has not established a database connection or failed to establish a database connection due to URL errors, password errors, etc.
3. Use DEFAULT, but DEFAULT has not been associated with the database. CONNECT has not established a database connection or failed to establish a database connection due to URL errors, password errors, etc.