SET-EFFECTIVE-TENANT function

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.