Skip to main content


persistent class Config.Databases extends %Library.Persistent, Config.CommonMultipleMethods, Config.CommonProperties, %SYSTEM.Help

SQL Table Name: Config.Databases

This class allows you to modify and view the [Databases] section of the CPF file through programatic APIs. While properties are usually modified through the System Management portal, there may be some occasion where modifying them through the APIs is best for your system. In all the Config methods, if you do not specify the CPFFile parameter, the currently active CPF file is used. If you wish to modify a CPF file which is not the currently active one, then specify the CPFFile you wish to modify in the method call.
The Flags parameter does not normally need to be specified; the defaults are usually sufficient for most cases.
You can use either the provided APIs (Create/Get/Modify/Delete) to modify the properties by passing in the correct parameters, or use Object syntax to open and directly manipulate the config objects (Open() and Exists()). Most objects created here need only to specify the Name of the object, and 1 or 2 properties since the the defaults are what are commonly used for most cases.


 ; Use class methods to create an instance
 %SYS>set Name="ABC"
 %SYS>set Properties("Directory")="c:\abc\"
 %SYS>set Status=##Class(Config.Databases).Create(Name,.Properties)
 %SYS>if '$$$ISOK(Status) write !,"Error="_$SYSTEM.Status.GetErrorText(Status)
 ; Use class methods to modify properties
 %SYS>set Status=##Class(Config.Databases).Get(Name,.Properties)
 %SYS>if '$$$ISOK(Status) write !,"Error="_$SYSTEM.Status.GetErrorText(Status)
 %SYS>zwrite Properties
 %SYS>set Properties("MountRequired")=1
 %SYS>set Status=##Class(Config.Databases).Modify(Name,.Properties)
 %SYS>if '$$$ISOK(Status) w !,"Error="_$SYSTEM.Status.GetErrorText(Status)
 ; Now use Objects to modify properties
 %SYS>set Obj=##Class(Config.Databases).Open(Name)
 ; We could have used if ##Class(Config.Databases).Exists(Name,.Obj) instead of Open()
 %SYS>write Obj.MountRequired
 %SYS>set Obj.MountRequired=0
 %SYS>set Status=Obj.%Save()
 %SYS>if '$$$ISOK(Status) write !,"Error="_$SYSTEM.Status.GetErrorText(Status)
 ; Now delete the object we just created
 %SYS>set Status=##Class(Config.Databases).Delete(Name)
 %SYS>if '$$$ISOK(Status) write !,"Error="_$SYSTEM.Status.GetErrorText(Status)

Property Inventory

Method Inventory


parameter CAPITALNAME = 1;
Database name is always capitalized.


property ClusterMountMode as Security.Datatype.BooleanYN [ InitialExpression = 0 , Required ];
Specifies whether the database should be mounted privately or clustered.
0 - Mount private
1 - Mount clustered
Property methods: ClusterMountModeDisplayToLogical(), ClusterMountModeGet(), ClusterMountModeGetStored(), ClusterMountModeIsValid(), ClusterMountModeLogicalToDisplay(), ClusterMountModeLogicalToOdbc(), ClusterMountModeLogicalToXSD(), ClusterMountModeNormalize(), ClusterMountModeOdbcToLogical(), ClusterMountModeSet(), ClusterMountModeXSDToLogical()
property Directory as %SysPath [ Required ];
Directory where the database resides.

On ECP Clients of a mirror this contains logical references to the databases on the failover mirror members as the path may be different on the various nodes.
This has two forms:
     :mirror:<mirror name>:<mirror database name>
     :ds:<config database name>

The 1st form, :mirror:<mirror name>:<mirror database name>, refers to a mirrored database. The mirror database name is the internal mirror name assigned to the database when it was added to the mirror. This is generally the same as the database name in the configuration.

The 2nd form, :ds:<config database name>, refers to a non-mirrored database on the server. The config database name is the name of the database in the configuration and this database name is expected to exist on all of the failover members. This form is only used in special circumstances as normally non-mirrored databases are hosted on the ECP Client, not the ECP Server. This is used in cases where scratch data (eg. the data will be lost during a mirror failover) needs to be hosted on the server for some reason.
Property methods: DirectoryDisplayToLogical(), DirectoryGet(), DirectoryGetStored(), DirectoryIsValid(), DirectoryLogicalToDisplay(), DirectoryLogicalToOdbc(), DirectoryNormalize(), DirectorySet()
property MountAtStartup as Security.Datatype.BooleanYN [ InitialExpression = 0 , Required ];
On a clustered system, specifies whether the database should be mounted at startup.
This property is valid for cluster systems only, and is ignored for non-cluster systems.
0 - Don't mount at startup
1 - Mount at startup
Property methods: MountAtStartupDisplayToLogical(), MountAtStartupGet(), MountAtStartupGetStored(), MountAtStartupIsValid(), MountAtStartupLogicalToDisplay(), MountAtStartupLogicalToOdbc(), MountAtStartupLogicalToXSD(), MountAtStartupNormalize(), MountAtStartupOdbcToLogical(), MountAtStartupSet(), MountAtStartupXSDToLogical()
property MountRequired as Security.Datatype.BooleanYN [ InitialExpression = 0 , Required ];
Specifies that the database MUST be successfully mounted at startup.
0 - Successful mount not required for startup to succeed.
1 - Successful mount required for startup to succeed.
Property methods: MountRequiredDisplayToLogical(), MountRequiredGet(), MountRequiredGetStored(), MountRequiredIsValid(), MountRequiredLogicalToDisplay(), MountRequiredLogicalToOdbc(), MountRequiredLogicalToXSD(), MountRequiredNormalize(), MountRequiredOdbcToLogical(), MountRequiredSet(), MountRequiredXSDToLogical()
property Server as %String (MAXLEN = 64, MINLEN = 0);
Name of the remote server where the DB resides.
If empty, the database is local.
Remote server must already be configured to be entered here.
Property methods: ServerDisplayToLogical(), ServerGet(), ServerGetStored(), ServerIsValid(), ServerLogicalToDisplay(), ServerLogicalToOdbc(), ServerNormalize()
property StreamLocation as %SysPath;
Directory where the streams associated with this database go.
By default (value=""), the location is in the subdirectory "stream", underneath the database directory, e.g. for a database located in c:\abc, the default would be c:\abc\stream. InterSystems recommends leaving this parameter as "".
Property methods: StreamLocationDisplayToLogical(), StreamLocationGet(), StreamLocationGetStored(), StreamLocationIsValid(), StreamLocationLogicalToDisplay(), StreamLocationLogicalToOdbc(), StreamLocationNormalize(), StreamLocationSet()


classmethod DatabaseByName(Name As %String) as %String
Return the ^system^directory where the database is located.
classmethod DatabasesByDirectory(Server As %String, Directory As %String, ByRef DBList As %String, CPFFile As %String = "") as %Status
Returns a list of databases that share the same given server/directory pair.
classmethod DatabasesByServer(Server As %String, ByRef DatabaseList As %String, CPFFile As %String = "") as %Status
Returns a list of databases that reference a given server.
classmethod GetNextDatabaseByUCI(UCI As %String) as %String
Return the Next UCI after the passed one, or null if at end.
classmethod KillDatabaseByUCI(UCI As %String) as %String
Kill the ^SYS("UCI",UCI) node.
classmethod Modify(Name As %String, ByRef Properties As %String, ByRef CPFFile As %String = "", Flags As %Integer = $$$CPFSave+$$$CPFWrite+$$$CPFActivate) as %Status
Modify Dataset section instance in CPF file. If the Server or Directory path is changed, it will be reflected on all Namespaces referring this DB.

Name - Name of the Dataset to modify.
Properties (byref) - List of the properties to modify in Properties(Name)=Value format. See the subclass for a list of valid properties. If a specific property is not passed in the properties array, the value is not modified.
CPFFile (byref) - Name of the CPF file to use, Default=current active CPF file.
Flags - Bit string of options to perform. For values, see the Create method, inherited from Config.CommonMultipleMethods.

Return values:
CPFFile (byref) - Name of the CPF file the modification was made in.
classmethod Rename(OldName As %String, NewName As %String, ByRef CPFFile As %String = "") as %Status
Rename the database name in the CPF file.

OldName - Name of the database to rename.
NewName (byref) - New name of the database.
CPFFile (byref) - Name of the CPF file to use, Default=current active CPF file.

Return values:
CPFFile (byref) - Name of the CPF file the modification was made in.


query List(Names As %String = "*", CPFFile As %String = "", Flags As %Integer = 0, Format As %Integer = 0)
Selects Name As %String, Directory As %String, Server As %String, ClusterMountMode As %Integer, MountRequired As %Integer, MountAtStartup As %Integer, StreamLocation As %String, Comments As %List
List Databases in a CPF file.

Names - Comma separated list of Database names
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record matching one of these elements, or starting with "String1"
CPFFile - Name of the CPF file to use. A null string means use the active CPF file.
Flags - Type of databases to return 0 - All databases 1 - Local databases 2 - Remote databases Format
0 - Standard report list format
1 - ^CONFIG global format
2 - CPF file format format
Note: This query may change in future versions
query MirrorDatabaseList(Names As %String = "*", CPFFile As %String = "")
Selects Name As %String, Mirror As %String, Directory As %String, Maximum Size in GB As %String, Size in MB As %Integer, Status As %String, Resource As %String, Encrypted As %String, Journal As %String, StatusInt As %String, MirrorStatus As %String, MirrorDBName As %String, MirrorFailoverDB As %Boolean, MirrorStatusInt As %Integer
Returns a list of the Local databases listed in the configuration file which are mirrored along with their current mirror status.

MirrorStatus is the current "mirror state" of the database, it could be one of the following values.
'Normal' - (Primary Only) The mirrored database is writable (if not a read-only database) and global updates are being journaled.
'Dejournaling' - (Backup and Async) The database has been activated and caught up and mirroring is applying journal data to the database.
'Needs Catchup' - The database has been activated but not caught up yet; the Catchup operation is needed.
'Needs Activation' - The database has not been activated yet; the Activate and Catchup operations are needed.
'Obsolete' - The mirrored database is obsolete and should be removed from the mirror.
'Dejournaling Stopped' - Dejournaling has been stopped by an operator or an error.
'Database Dismounted' - The database is dismounted.
'Catchup Running' - The Catchup operation is running on the database.
'Orphaned' - The mirrored database is missing in primary.


index (CPFNameSectionHeaderName on CPFName,SectionHeader,Name) [IdKey, Type = key, Unique];
Index methods: CPFNameSectionHeaderNameCheck(), CPFNameSectionHeaderNameDelete(), CPFNameSectionHeaderNameExists(), CPFNameSectionHeaderNameOpen(), CPFNameSectionHeaderNameSQLCheckUnique(), CPFNameSectionHeaderNameSQLExists(), CPFNameSectionHeaderNameSQLFindPKeyByConstraint(), CPFNameSectionHeaderNameSQLFindRowIDByConstraint()

Inherited Members

Inherited Properties

Inherited Methods


Storage Model: Storage (Config.Databases)

FeedbackOpens in a new tab