Sets the effective tenancy of a multi-tenant
database connection for a super-tenant user. A super tenant has
no real tenancy of its own, but can act as if it is a particular
regular tenant without the user having to authenticate a new connection
identity that has that particular tenancy. Therefore, the effective
tenancy is the acting regular tenancy of a super tenant.
Initially,
OpenEdge sets the effective tenancy for any super-tenant identity to
the default tenant. The purpose of this function is to change the
effective tenancy of a super tenant identity to any regular tenant.
Syntax
SET-EFFECTIVE-TENANT ( tenant-expression[ , database-name ])
|
-
tenant-expression
- An integer or character string expression. If tenant-expression evaluates
to an integer, the value must be a valid tenant ID for a regular
or default tenant. If tenant-expression evaluates
to a character string, the value must be a valid tenant name for
a regular or default tenant. Otherwise, the statement raises ERROR.
-
database-name
- A character expression that evaluates to a logical database
name or database alias. If no database is specified and more than
one database is connected, the AVM raises an error. If the database
name is not a valid name for a connected database, the AVM raises
an error.
Notes
- The
function returns a logical TRUE if successful, and raises an error
if not successful.
- If a regular-tenant user executes this function, the tenant
identified by tenant-expression must match the
user's tenancy; otherwise, the function raises an error. If a super-tenant
user executes this function, and tenant-expression is
not a valid regular tenant (not a super tenant), the function raises
an error.
- All super-tenant users login with access to shared data and
data owned by the effective default tenant, with access conditioned
on the user's table and field permission settings. When a super-tenant
user executes SET-EFFECTIVE-TENANT, they have access to shared data
and data owned by the new effective tenant, with access, again,
conditioned by the user's same table and field permission settings.
This super-tenant access can include data for multiple tenants, without changing effective
tenancy, by using the TENANT-WHERE option of the record phrase.
(The TENANT-WHERE option, itself, does not change the effective
tenancy.)
- When you execute SET-EFFECTIVE-TENANT, buffers and cursors for
existing tenant data from a previous effective tenancy are not cleared. In
this way, a super tenant can get records for more than one tenant.
Note that regardless of changes in effective tenancy, any subsequent
updates to prior tenant data are written to the original tenant
tables.
- The scope of SET-EFFECTIVE-TENANT ends when a new identity is set
for the database connection using the SET-DB-CLIENT function, the SECURITY-POLICY:SET-CLIENT( ) method,
or the SETUSERID function,
at which point the effective tenancy changes back to the default
tenant for any super tenant user identity or to the real tenant
of a regular tenant user identity (including the default tenant).
Unlike setting the effective tenant, setting a new connection identity
also clears buffers and cursors of any prior tenant data.
- An UNDO does not undo the tenancy of a SET-EFFECTIVE-TENANT.
- The AVM looks up tenant-expression in the _Tenant table
with a share lock. The AVM waits 60 seconds to get the share lock,
and if it fails to get the share lock in that amount of time, the
AVM raises an error. The AVM releases the share lock immediately
after successfully retrieving the tenant information. This share
lock is released even if the function is called within a transaction.
