FirebirdSQL logo
 Procedural SQL (PSQL) StatementsAggregate Functions 

RDB$SET_CONTEXT()

Creates, sets or clears a variable in one of the user-writable namespaces

Result type

INTEGER

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)
Table 1. RDB$SET_CONTEXT Function Parameters
Parameter Description

namespace

Namespace

varname

Variable name.Case-sensitive.Maximum length is 80 characters

value

Data of any type provided it can be cast to VARCHAR(255)
The namespaces

The USER_SESSION and USER_TRANSACTION namespaces are initially empty.A user can create and set variables with RDB$SET_CONTEXT() and retrieve them with [fblangref50-scalarfuncs-get-context].The USER_SESSION context is bound to the current connection, the USER_TRANSACTION context to the current transaction.

Lifecycle

  • When a transaction ends, its USER_TRANSACTION context is cleared.

  • When a connection is closed, its USER_SESSION context is cleared.

  • When a connection is reset using ALTER SESSION RESET, the USER_TRANSACTION and USER_SESSION contexts are cleared.

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.

Note

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

  • All USER_TRANSACTION variables 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.

  • ALTER SESSION RESET clears both USER_TRANSACTION and USER_SESSION contexts.
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
See also

[fblangref50-scalarfuncs-get-context]

Special Functions for DECFLOAT