8.1. Context Functions

8.1.1. RDB$GET_CONTEXT()

Available in

DSQL, PSQL * As a declared UDF it should be available in ESQL

Syntax

RDB$GET_CONTEXT ('<namespace>', <varname>)
<namespace> ::= SYSTEM | USER_SESSION | USER_TRANSACTION
<varname>   ::= A case-sensitive quoted string of max. 80 characters

Result type

VARCHAR(255)

Description

Retrieves the value of a context variable from one of the namespaces SYSTEM, USER_SESSION and USER_TRANSACTION.

The namespaces

The USER_SESSION and USER_TRANSACTION namespaces are initially empty. The user can create and set variables in them with RDB$SET_CONTEXT() and retrieve them with RDB$GET_CONTEXT(). The SYSTEM namespace is read-only. It contains a number of predefined variables, shown below.

Context variables in the SYSTEM namespace

DB_NAME

Either the full path to the database or — if connecting via the path is disallowed — its alias.

NETWORK_PROTOCOL

The protocol used for the connection: 'TCPv4', 'WNET', 'XNET' or NULL.

CLIENT_ADDRESS

For TCPv4, this is the IP address. For XNET, the local process ID. For all other protocols this variable is NULL.

CURRENT_USER

Same as global CURRENT_USER variable.

CURRENT_ROLE

Same as global CURRENT_ROLE variable.

SESSION_ID

Same as global CURRENT_CONNECTION variable.

TRANSACTION_ID

Same as global CURRENT_TRANSACTION variable.

ISOLATION_LEVEL

The isolation level of the current transaction: 'READ COMMITTED', 'SNAPSHOT' or 'CONSISTENCY'.

ENGINE_VERSION

The Firebird engine (server) version. Added in 2.1.

Return values and error behaviour

If the polled variable exists in the given namespace, its value will be returned as a string of max. 255 characters. If the namespace doesn’t exist or if you try to access a non-existing variable in the SYSTEM namespace, an error is raised. If you request a non-existing variable in one of the other namespaces, NULL is returned. Both namespace and variable names must be given as single-quoted, case-sensitive, non-NULL strings.

Examples

select rdb$get_context('SYSTEM', 'DB_NAME') from rdb$database
New.UserAddr = rdb$get_context('SYSTEM', 'CLIENT_ADDRESS');
insert into MyTable (TestField)
  values (rdb$get_context('USER_SESSION', 'MyVar'))

See also

RDB$SET_CONTEXT()

8.1.2. RDB$SET_CONTEXT()

Available in

DSQL, PSQL * As a declared UDF it should be available in ESQL

Syntax

RDB$SET_CONTEXT ('<namespace>', <varname>, <value> | NULL)
<namespace> ::= USER_SESSION | USER_TRANSACTION
<varname>   ::= A case-sensitive quoted string of max. 80 characters
<value>     ::= A value of any type, as long as it's castable
                to a VARCHAR(255)

Result type

INTEGER

Description

Creates, sets or unsets a variable in one of the user-writable namespaces USER_SESSION and USER_TRANSACTION.

The namespaces

The USER_SESSION and USER_TRANSACTION namespaces are initially empty. The user can create and set variables in them with RDB$SET_CONTEXT() and retrieve them with RDB$GET_CONTEXT(). The USER_SESSION context is bound to the current connection. Variables in USER_TRANSACTION only exist in the transaction in which they have been set. When the transaction ends, the context and all the variables defined in it are destroyed.

Return values and error behaviour

The function returns 1 when the variable already existed before the call and 0 when it didn’t. To remove a variable from a context, set it to NULL. If the given namespace doesn’t exist, an error is raised. Both namespace and variable names must be entered as single-quoted, case-sensitive, non-NULL strings.

Examples

select rdb$set_context('USER_SESSION', 'MyVar', 493) from rdb$database
rdb$set_context('USER_SESSION', 'RecordsFound', RecCounter);
select rdb$set_context('USER_TRANSACTION', 'Savepoints', 'Yes')
  from rdb$database

Notes

• The maximum number of variables in any single context is 1000.

• All USER_TRANSACTION variables will survive a ROLLBACK RETAIN (see ROLLBACK Options) or ROLLBACK TO SAVEPOINT unaltered, no matter at which point during the transaction they were set.

• Due to its UDF-like nature, RDB$SET_CONTEXT can — in PSQL only — be called like a void function, without assigning the result, as in the second example above. Regular internal functions don’t allow this type of use.

See also

RDB$GET_CONTEXT()