The USE DATABASE command switches the current process to the specified namespace and its associated database. This allows you to change namespaces within SQL. The DATABASE keyword is optional.
The specified dbname is the name of the desired namespace and corresponding directory that contains the database files. Specify dbname as an identifier. Namespace names are not case-sensitive. For further information on using namespaces, see Namespaces and Databases.
Because USER is an SQL Reserved Word, you must use a delimited identifier to specify the USER namespace, as shown in the following SQL Shell example:
USER>>USE DATABASE Samples
SAMPLES>>USE DATABASE "User"
If the specified dbname does not exist, InterSystems IRIS issues an SQLCODE -400 error.
The USE DATABASE command is a privileged operation. Prior to using USE DATABASE, it is necessary to be logged in as a user with appropriate privileges. Failing to do so results in an SQLCODE -99 error (Privilege Violation).
Use the $SYSTEM.Security.Login()Opens in a new tab method to assign a user with appropriate privileges:
You must have the %Service_Login:Use privilege to invoke the $SYSTEM.Security.Login method. For further information, refer to %SYSTEM.SecurityOpens in a new tab in the InterSystems Class Reference.
You can also switch to a different namespace using the ObjectScript ZNSPACE command, or the SET $NAMESPACE statement.
Executing via a Database Driver
When the USE DATABASE command is executed via a database driver, the server process performs a simulated connection reset. Data structures used by the server process are cleaned up. However, commit mode is not changed. The Read Committed setting is not changed either. If a transaction is in process, the transaction simply continues and is not committed or rolled back.