Setting effective tenancy

A super tenant can change effective tenancy for a given database connection with the ABL built-in function, SET-EFFECTIVE-TENANT. This function allows the super tenant to implicitly query data for the effective tenant without having to set a new user identity for the connection. All queries with this effective tenancy return only shared data and data owned by the effective tenant.

Once a super tenant has set an effective tenancy, the super tenant has all the same behaviors as the regular tenant for actions such as reading, creating, updating, and deleting data.

This is the syntax of the SET-EFFECTIVE-TENANT function:

Syntax

SET-EFFECTIVE-TENANT ( tenant-expression[ , database-name ])

Where tenant-expression evaluates to the tenant name or ID of a valid regular tenant, and database-name evaluates to the logical name or alias of a connected database that defines the specified tenant. If you do not specify database-name, and multiple databases are connected, the function raises an error. The function returns logical, TRUE if successful, and raises an error if not successful.

The purpose of this function is to allow a super tenant user to act as if it is a particular regular tenant without having to become that tenant by authenticating a new user identity. It creates an effective tenancy which is distinguished from the real tenancy of the user's identity, which in this case is a super-tenancy. If a user identity with regular tenancy executes this function, the specified tenant must match the user's real tenancy, and if not, the function raises an error. If a super tenant executes this function and tenant-expression is not a valid regular tenant, the function also raises an error.

The scope of SET-EFFECTIVE-TENANT ends when either an authentication operation sets the database connection to a new identity with a different real tenancy or another invocation of SET-EFFECTIVE-TENANT sets a new effective tenancy. The difference between setting and effective tenant and changing real tenancy is in how OpenEdge handles current buffers and cursors.

When you execute SET-EFFECTIVE-TENANT, OpenEdge does not clear buffers and cursors with existing tenant information from any previous SET-EFFECTIVE-TENANT call. Also, an UNDO does not undo the effective tenancy set using SET-EFFECTIVE-TENANT. In this way, a super tenant can retrieve records for more than one tenant by changing effective tenancy. So, for example any existing cursor in a FOR EACH statement or query remains unaffected. However, when you set a new user identity, with or without a new tenancy, OpenEdge cleans up all buffers and cursors for the new user identity.

CAUTION: If you want to remove all record of super-tenant activity, you must reset the user identity for the connection instead of setting a new effective tenancy.
Note: If a super tenant does invoke SET-EFFECTIVE-TENANT to change effective tenancy within a FOR EACH block or during an existing query, the next records read by the cursor are still read as the original effective tenant, and if written, are written back to that same tenant. Any new queries or record finds after the current query ends, operate under the new effective tenancy.

Alternatively, when a super tenant needs records for more than one tenant they can use the TENANT-WHERE option of the record phrase to retrieve all tenant records without having to change their effective tenancy for each tenant.