Home > Class Reference > %SYS namespace > SYS.Database


persistent class SYS.Database extends %Library.Persistent, %SYSTEM.Help

SQL Table Name: SYS.Database

Manages Database Operations.

To Create a new database with the system defaults do the following:

Set db=##Class(SYS.Database).%New()
Set db.Directory=Directory
Set status=db.%Save()

To modify an existing Database, do the following:
Set db=##Class(SYS.Database).%OpenId(Directory)
//Set the property you want to modify:
Set db.ExpansionSize=100
Set status=db.%Save()

Properties which can be set for database creation are:

Properties which can be modified for an already created database are:

Read-only properties which are managed by the system and cannot be modified are:

The maximum value of 'MaxSize' property for various block size of databases are different. They are:
    16777080 MB for 4K database.
    33553904 MB for 8K database.
    67106832 MB for 16K database.
    134202016 MB for 32K database.
    268392960 MB for 64K database.

When 'MaxSize' or 'Size' peoperty is modified Cache system internally adjusts the 'MaxSize' and 'Size' peoperties when:
    1) Setting 'MaxSize' which is over the maximum value then it is set with the maximum value.
    2) Setting 'MaxSize' which is less than 'Size' then it is set with the value of 'Size'.
    3) Setting 'Size' which is greater than 'MaxSize' then the 'Size' is increased to the value of 'MaxSize'.

Property Inventory

Method Inventory


Inherited description: DEFAULTCONCURRENCY is the default value for the concurrency formal argument defined for %Open, %OpenId, %Delete and %DeleteId methods. It is not the default value of the %Concurrency property of persistent classes. If the value of the actual concurrency argument passed to any of the above methods is -1 then the formal argument value will be set to the value of the DEFAULTCONCURRENCY parameter value defined for the class.
parameter DOMAIN = %Utility;
Default Localization Domain


property BlockSize as %Integer (VALUELIST = ",2048,4096,8192,16384,32768,65536") [ InitialExpression = $$$8k ];
Block size in bytes of the database.
Either 2048, 4096, 8192, 16384, 32768, or 65536
Property methods: BlockSizeDisplayToLogical(), BlockSizeGet(), BlockSizeIsValid(), BlockSizeLogicalToDisplay(), BlockSizeNormalize(), BlockSizePrompt(), BlockSizeSet()
property ClusterMountMode as %Boolean [ InitialExpression = 0 ];
Database is configured to be mounted in cluster mode
If this property is set then this database has to be mounted explicitly.
Property methods: ClusterMountModeDisplayToLogical(), ClusterMountModeGet(), ClusterMountModeIsValid(), ClusterMountModeLogicalToDisplay(), ClusterMountModeNormalize(), ClusterMountModePrompt(), ClusterMountModeSet()
property ClusterMounted as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database is currently cluster mounted
Property methods: ClusterMountedDisplayToLogical(), ClusterMountedGet(), ClusterMountedIsValid(), ClusterMountedLogicalToDisplay(), ClusterMountedNormalize(), ClusterMountedSet()
property Directory as %SysPath;
Directory containing the database
Property methods: DirectoryBlockDisplayToLogical(), DirectoryBlockGet(), DirectoryBlockIsValid(), DirectoryBlockLogicalToDisplay(), DirectoryBlockNormalize(), DirectoryDisplayToLogical(), DirectoryGet(), DirectoryIsValid(), DirectoryLogicalToDisplay(), DirectoryLogicalToOdbc(), DirectoryNormalize(), DirectorySet()
property EncryptedDB as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Database is encrypted
Property methods: EncryptedDBDisplayToLogical(), EncryptedDBGet(), EncryptedDBIsValid(), EncryptedDBLogicalToDisplay(), EncryptedDBLogicalToODBC(), EncryptedDBNormalize(), EncryptedDBPrompt(), EncryptedDBSet()
property EncryptionKeyID as %String (MAXLEN = 63, MINLEN = 2);
Database encryption key ID
Property methods: EncryptionKeyIDDisplayToLogical(), EncryptionKeyIDGet(), EncryptionKeyIDIsValid(), EncryptionKeyIDLogicalToDisplay(), EncryptionKeyIDLogicalToOdbc(), EncryptionKeyIDNormalize(), EncryptionKeyIDSet()
property Expanding as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database is expanding.
Property methods: ExpandingDisplayToLogical(), ExpandingGet(), ExpandingIsValid(), ExpandingLogicalToDisplay(), ExpandingNormalize()
property ExpansionSize as %Integer (MINVAL = 0) [ InitialExpression = 0 ];
Size in MB to Expand by.
0 - Use system defaults (recommended)
Property methods: ExpansionSizeDisplayToLogical(), ExpansionSizeGet(), ExpansionSizeIsValid(), ExpansionSizeLogicalToDisplay(), ExpansionSizeNormalize(), ExpansionSizePrompt(), ExpansionSizeSet()
property GlobalJournalState as %Library.JournalState;
Journal setting for database.
2 - No
3 - Yes
Property methods: GlobalJournalStateBooleanToLogical(), GlobalJournalStateDisplayToLogical(), GlobalJournalStateGet(), GlobalJournalStateIsValid(), GlobalJournalStateLogicalToBoolean(), GlobalJournalStateLogicalToDisplay(), GlobalJournalStateLogicalToMenu(), GlobalJournalStateLogicalToSystem(), GlobalJournalStateMenuToLogical(), GlobalJournalStateNormalize(), GlobalJournalStatePrompt(), GlobalJournalStateSet(), GlobalJournalStateSystemToLogical()
property InActiveMirror as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database has a status of InActiveMirror which means either we're the primary and the db is read/write and available for use or we're an active backup and the db is being replayed to by the mirror dejournal jobs to keep it updated with changes occurring on the primary.
Property methods: InActiveMirrorDisplayToLogical(), InActiveMirrorGet(), InActiveMirrorIsValid(), InActiveMirrorLogicalToDisplay(), InActiveMirrorNormalize()
property LastExpansionTime as %String [ InitialExpression = 0 , ReadOnly ];
Last time database expanded, converted to local time.
Property methods: LastExpansionTimeDisplayToLogical(), LastExpansionTimeGet(), LastExpansionTimeIsValid(), LastExpansionTimeLogicalToDisplay(), LastExpansionTimeLogicalToOdbc(), LastExpansionTimeNormalize()
property MaxSize as %Integer (MINVAL = 0) [ InitialExpression = 0 ];
Maximum size in MB, 0=unlimited (recommended).
Property methods: MaxSizeDisplayToLogical(), MaxSizeGet(), MaxSizeIsValid(), MaxSizeLogicalToDisplay(), MaxSizeNormalize(), MaxSizePrompt(), MaxSizeSet()
property MirrorActivationRequired as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database has a status of activation-required which means it is mounted but there is a problem or it needs to be activated before use.
Property methods: MirrorActivationRequiredDisplayToLogical(), MirrorActivationRequiredGet(), MirrorActivationRequiredIsValid(), MirrorActivationRequiredLogicalToDisplay(), MirrorActivationRequiredNormalize()
property MirrorDBCatchup as %Boolean [ InitialExpression = 0 , ReadOnly ];
Mirrored Database is running for CatchupDB.
Property methods: MirrorDBCatchupDisplayToLogical(), MirrorDBCatchupGet(), MirrorDBCatchupIsValid(), MirrorDBCatchupLogicalToDisplay(), MirrorDBCatchupNormalize()
property MirrorDBCreatedNew as %Boolean [ InitialExpression = 0 , ReadOnly ];
Mirrored Database is created by %New instead of 'Added' to existing DB.
Property methods: MirrorDBCreatedNewDisplayToLogical(), MirrorDBCreatedNewGet(), MirrorDBCreatedNewIsValid(), MirrorDBCreatedNewLogicalToDisplay(), MirrorDBCreatedNewNormalize()
property MirrorDBName as %String;
Database name identified in mirror set
Property methods: MirrorDBNameDisplayToLogical(), MirrorDBNameGet(), MirrorDBNameIsValid(), MirrorDBNameLogicalToDisplay(), MirrorDBNameLogicalToOdbc(), MirrorDBNameNormalize(), MirrorDBNamePrompt(), MirrorDBNameSet()
property MirrorDBPaused as %Boolean [ InitialExpression = 0 , ReadOnly ];
Mirrored Database is paused for dejournaling.
Property methods: MirrorDBPausedDisplayToLogical(), MirrorDBPausedGet(), MirrorDBPausedIsValid(), MirrorDBPausedLogicalToDisplay(), MirrorDBPausedNormalize()
property MirrorFailoverDB as %Boolean [ InitialExpression = 0 , ReadOnly ];
Mirrored Database is on failover members
Property methods: MirrorFailoverDBDisplayToLogical(), MirrorFailoverDBGet(), MirrorFailoverDBIsValid(), MirrorFailoverDBLogicalToDisplay(), MirrorFailoverDBNormalize()
property MirrorNoWrite as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database has a status of mirrored-no-write which means it is mounted read-only so it cannot be written to.
Property methods: MirrorNoWriteDisplayToLogical(), MirrorNoWriteGet(), MirrorNoWriteIsValid(), MirrorNoWriteLogicalToDisplay(), MirrorNoWriteNormalize()
property MirrorObsolete as %Boolean [ InitialExpression = 0 , ReadOnly ];
Mirror Database is obsolete due to the database's GUID mismatched with GUID in mirror journal file directory block during dejournaling.
Property methods: MirrorObsoleteDisplayToLogical(), MirrorObsoleteGet(), MirrorObsoleteIsValid(), MirrorObsoleteLogicalToDisplay(), MirrorObsoleteNormalize()
property MirrorSetName as %String;
Mirror set name of this mirrored database.
Property methods: MirrorSetNameDisplayToLogical(), MirrorSetNameGet(), MirrorSetNameIsValid(), MirrorSetNameLogicalToDisplay(), MirrorSetNameLogicalToOdbc(), MirrorSetNameNormalize(), MirrorSetNamePrompt(), MirrorSetNameSet()
property Mirrored as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database is marked as mirrored
Property methods: MirroredDisplayToLogical(), MirroredGet(), MirroredIsValid(), MirroredLogicalToDisplay(), MirroredNormalize()
property Mounted as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database is mounted.
Property methods: MountedDisplayToLogical(), MountedGet(), MountedIsValid(), MountedLogicalToDisplay(), MountedNormalize()
property NewGlobalCollation as %Library.Collate [ InitialExpression = ##Class(%Library.Collate).GetSystemDefaultNumber() ];
Default collation for new globals.
Property methods: NewGlobalCollationCollationListClose(), NewGlobalCollationCollationListExecute(), NewGlobalCollationCollationListFetch(), NewGlobalCollationDisplayToLogical(), NewGlobalCollationGet(), NewGlobalCollationGetLocalName(), NewGlobalCollationGetLocalNumber(), NewGlobalCollationGetSystemDefaultName(), NewGlobalCollationGetSystemDefaultNumber(), NewGlobalCollationIsValid(), NewGlobalCollationIsValidName(), NewGlobalCollationIsValidNumber(), NewGlobalCollationLogicalToDisplay(), NewGlobalCollationMakeArray(), NewGlobalCollationNormalize(), NewGlobalCollationPrompt(), NewGlobalCollationSet(), NewGlobalCollationSetLocalName(), NewGlobalCollationSetLocalNumber()
property NewGlobalGrowthBlock as %Integer (MINVAL = 50) [ InitialExpression = 50 ];
Default growth block for new globals.
Property methods: NewGlobalGrowthBlockDisplayToLogical(), NewGlobalGrowthBlockGet(), NewGlobalGrowthBlockIsValid(), NewGlobalGrowthBlockLogicalToDisplay(), NewGlobalGrowthBlockNormalize(), NewGlobalGrowthBlockPrompt(), NewGlobalGrowthBlockSet()
property NewGlobalIsKeep as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Default Keep value for New globals.
Property methods: NewGlobalIsKeepDisplayToLogical(), NewGlobalIsKeepGet(), NewGlobalIsKeepIsValid(), NewGlobalIsKeepLogicalToDisplay(), NewGlobalIsKeepLogicalToODBC(), NewGlobalIsKeepNormalize(), NewGlobalIsKeepPrompt(), NewGlobalIsKeepSet()
property NewGlobalPointerBlock as %Integer (MINVAL = 6) [ InitialExpression = 16 ];
Block where the index pointer starts.
Property methods: NewGlobalPointerBlockDisplayToLogical(), NewGlobalPointerBlockGet(), NewGlobalPointerBlockIsValid(), NewGlobalPointerBlockLogicalToDisplay(), NewGlobalPointerBlockNormalize(), NewGlobalPointerBlockPrompt(), NewGlobalPointerBlockSet()
property ReadOnly as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Database attribute in label says Read Only.
Property methods: ReadOnlyDisplayToLogical(), ReadOnlyGet(), ReadOnlyIsValid(), ReadOnlyLogicalToDisplay(), ReadOnlyLogicalToODBC(), ReadOnlyMountedDisplayToLogical(), ReadOnlyMountedGet(), ReadOnlyMountedIsValid(), ReadOnlyMountedLogicalToDisplay(), ReadOnlyMountedNormalize(), ReadOnlyNormalize(), ReadOnlyPrompt(), ReadOnlySet()
property ReadOnlyMounted as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database is mounted for read only
Property methods: ReadOnlyMountedDisplayToLogical(), ReadOnlyMountedGet(), ReadOnlyMountedIsValid(), ReadOnlyMountedLogicalToDisplay(), ReadOnlyMountedNormalize()
property ResourceName as %String [ InitialExpression = "%DB_%DEFAULT" ];
Resource name for the database.
Property methods: ResourceNameDisplayToLogical(), ResourceNameGet(), ResourceNameIsValid(), ResourceNameLogicalToDisplay(), ResourceNameLogicalToOdbc(), ResourceNameNormalize(), ResourceNamePrompt(), ResourceNameSet()
property RunCatchupDBOnCreate as %Boolean [ InitialExpression = 1 ];
Run CatchupDB when this mirrored DB is created.
Property methods: RunCatchupDBOnCreateDisplayToLogical(), RunCatchupDBOnCreateGet(), RunCatchupDBOnCreateIsValid(), RunCatchupDBOnCreateLogicalToDisplay(), RunCatchupDBOnCreateNormalize(), RunCatchupDBOnCreateSet()
property Size as %Integer (MINVAL = 1) [ InitialExpression = 1 ];
Size in MB.
Property methods: SizeDisplayToLogical(), SizeGet(), SizeIsValid(), SizeLogicalToDisplay(), SizeNormalize(), SizePrompt(), SizeSet()


classmethod AuditJournalStateChange(db As SYS.Database) as %Status
classmethod CheckBlockSizeAllowed(Size As %String) as %Boolean
This checks to see if this configuration allows creating block sizes other than the default, which is 8k.
classmethod CheckForWideCharacters(Directory As %String, Mask As %String = "*", ByRef GlobalNodes) as %Status
Scans CACHE.DAT for any wide characters.
This method is useful if you have a database mounted on a 16 bit system, and you wish to move that database to an 8 bit system. Scanning the database before you move it for wide characters (16 bit characters) will allow you to fix the global references so you can avoid errors after you move the database to the 8 bit system.
Directory - Database directory to check for wide characters
Global - Mask of globals to check, "*"=default.
Valid masks are as follows:
ABC* - All globals starting with ABC
A:D - All globals between A and D
A:D,Y* - All globals between A and D, and all globals starting with Y
A:D,'C* - All globals between A and D, except those starting with C Return Values:
Globals (byref) - Array of global nodes which contain wide characters.
Note: The maximum number of nodes returned is 5,000 so errors can be avoided.
method CheckIntegrity() as %Status
classmethod ClearMirrorFailoverDB(Directory As %String) as %Status
This method will clear the MirrorFailoverDB flag in this mirrored DB.
method Compact(PercentFull As %Integer = 90, ByRef MbProcessed As %Integer, ByRef MbCompressed As %Integer, Display As %Boolean, Device As %String, ByRef GloSel As %String) as %Status
Compact all or selected globals in a database.
When GloSel does not exist ($D(GloSel)=0) all globals in the database will be compacted. Otherwise the array of GloSel contains the globals to be compacted.

If a global that was selected for compaction is deleted before that global is processed, the global is ignored as if it had not been specified. If detailed progress information is being displayed (global names and compaction level), the global name will be displayed on a blank line, without any compaction details.
classmethod CompactDatabase(Directory As %String, PercentFull As %Integer = 90, ByRef MbProcessed As %Integer, ByRef MbCompressed As %Integer, Display As %Boolean, Device As %String) as %Status
Compact all globals in a database.
classmethod Copy(SrcDir As %String, DstDir As %String = "", BlockSize As %Integer = 0, ByRef Msg As %String, Flags As %Integer = 0, Collation As %Integer = 5) as %Status
Copy a database to another directory.
This method will copy a source database to a newly created destination database, and optionally replace the source database with the destination database after the copy completes. The main use of this method is to change the blocksize of a database. The destination database which is created will be created with its pages fully packed, all free space removed, and blocks re-ordered. Globals which were created with old ISM collation values of 0-4 will be created with collation 5 (Cache' Standard) when they are copied. Globals which have old ISM collations of 128 and 129 will be created with a collation of 133.

Mirrored databases can be copied however the resulting copy will not be mirrored.

NOTE: This method is only for use with a local database, it does not work across ECP or on cluster mounted databases. If the database is a cluster mounted database, it must be mounted privately before using this method on it.

SrcDir - Source database directory to copy. This must be a valid database which is mounted on the system. During the copy operation, the Source database will be set to read only.
DstDir - New destination database directory to be created. This must be a valid directory specification for the system. If the directory does not exist, it will be created. If DstDir is not specified, then a directory named "cvt" will be created under the source directory. The device where the destination directory specified must have enough free space on it to accommodate the copy. If the destination database already exists, the method will return a failure.
BlockSize - If the block size is specified, the newly created database will be created with this size of database blocks. If the block size is not specified, the new database will be created with the same block size of the source database. If the source database is a 2KB database, the destination database will be created with the system default size. The block size specified must be a valid database block size allowed by the system as specified in the Config.Startup.AllowedBlockSizes property, and must have global buffers allocated for that size or larger in the Config.config class.
Msg (by ref) - Array of success and error messages returned by the method.
Flags - Bit string specifying the following options (Default = 0):
Bit 0 - Display progress messages.
Bit 1 - Do not set the source directory to read only.
Bit 2 - If the destination database already exists, do not generate an error.
Bit 3 - Unused.
Bit 4 - Replace the source database with the destination database after the copy completes. If the source database is cluster mounted or mirrored, this option is not allowed.
WARNING: If you are replacing the source database with the destination database, you MUST make a backup of your source database before running this method.
Bit 5 - Set switch 10 (freeze reads and write on the system) for the duration of the copy. Setting this bit will allow the source database to be copied and replaced by the destination database while avoiding having any processes trying to write to the database error with a protect error.
Bit 6 - Write the global sets to the journal file. If the Source database is set to not be journaled, then the sets will not be journaled even if this bit is set.
Bit 7 - If the original database is encrypted, do not encrypt the copy.
Bit 8 - Create the destination database and all the copied globals with the passed in collation.
Collation - The destination database is created with this collation if bit 8 is set in the Flags parameter. All globals which are copied here will be created with this collation. The globals collation in the source database will be ignored. The ^COLLATE routine will give a list of the available collations on the system. The collation must be loaded and active on the system to use this parameter. Note that the system globals such as the routine and objects globals will contain to be set to collation 5 (Cache' standard.)

Make a copy of the prod database into the test directory.
s x=##Class(SYS.Database).Copy("c:\prod\","c:\test\")

Make a copy of the prod database into the prod\cvt directory with a block size of 16384. Messages and errors are returned in the Msg array.
s x=##Class(SYS.Database).Copy("c:\prod\",,16384,.Msg)

Make a copy of the prod database into the prod\cvt directory with a block size of 16384. After the database is copied, delete the prod database and replace it with the prod\cvt database. Success and error messages are displayed to the screen.
s x=##Class(SYS.Database).Copy("c:\prod\",,16384,.Msg,1+16)

Make a copy of the prod database into the prod\cvt directory with a block size of 16384. Write all the global sets into the journal.
s x=##Class(SYS.Database).Copy("c:\prod\","c:\test\,16384,.Msg,64)

Combine 2 different databases into one test database.
s x=##Class(SYS.Database).Copy("c:\prod\","c:\test\,,.Msg,4)
s x=##Class(SYS.Database).Copy("c:\prod1\","c:\test\,,.Msg,4)

Copy the source to the destination, change the blocksize to 32768, then replace the source with the destination. Processes on the system will be frozen while the copy runs. This is useful if you want to do this and not have any processes which write to the database error with a protect error.
s x=##Class(SYS.Database).Copy("c:\prod\","c:\test\,32768,.Msg,16+32)

Change the CACHESYS database to use an 8192 block size. Freeze the system while the database is copied. This is useful to convert the CACHESYS database while the system is up and running.
s x=##Class(SYS.Database).Copy($zu(12),,8192,.Msg,16+32)

Change the collation of all the globals to Danish.
s x=##Class(SYS.Database).Copy("c:\prod\","c:\test\",8192,.Msg,256,15)

classmethod CreateDatabase(Directory As %String, Size As %Integer = 1, BlockSize As %Integer = $$$DefaultDatabaseBlockSize, EncryptedDB As %Boolean = 0, Resource As %String = "%DB_%DEFAULT", GlobalJournalState As %Integer, MirrorDBName As %String = "", MirrorSetName As %String = "", RunCatchupDB As %Boolean = 1) as %Status
Create a database. This assumes the Directory has been created. The Directory can be a relative or absolute path. The Size is in MB. Only the Directory is required.
classmethod DBCompactStatus(Directory As %String, ByRef State As %Integer, ByRef LogFile As %String) as %Status
Check the state of a background database compaction.
State = 0-(in progress), 1-(finished), 2-(no compaction logged)
classmethod Defragment(Directory As %String) as %Status
Rearranges global blocks within the database specified by Directory so that all of the data blocks for a given global are in consecutive sequence and packed to at least 70% full. The operation does not place big string blocks or pointer blocks from a global in sequence, but it does locate them in a contiguous area.

Defragment requires enough free space at the end of the database file to temporarily store all data blocks. If there is insufficient free space at the end, the database will expand as necessary. The amount of free space required is equal to the space in use plus 20MB working space. You may be able to create additional free space at the end by first running FileCompact(). Following the defragmentation you can return unused space at the end of the database file with ReturnUnusedSpace().

This method is not available on VMS

method Delete() as %Status
Delete a database.
classmethod DeleteDatabase(Directory As %String) as %Status
Delete a database.
method DisableJournaling() as %Status
Disable journaling for Database.
method Dismount() as %Status
Dismount a database.
classmethod DismountDatabase(Directory As %String) as %Status
Dismount a database.
method EnableJournaling(val As %Integer) as %Status
Enable journaling for Database.
classmethod FileCompact(Directory As %String, TargetFree As %Integer = 0, ByRef ActualFree As %Integer) as %Status
Moves free space distributed throughout the database file to its end. You can then return the free space to the file system using ReturnUnusedSpace().

FileCompact starts at the end of the database file, moving in-use blocks into free space at the beginning. It stops when there is no more free space available, or there is at least TargetFree MB of free space at the end of the file. Specifying 0 for TargetFree reports the amount of free space located at the end of the file without moving any blocks.

This method is not available on VMS

Input Parameters:

  • Directory - the database directory
  • TargetFree - the desired amount of free space (in MB) at the end of the database.
  • Output Parameters:

  • ActualFree - returns the total amount of space (in MB) at the end of the database which can be returned by truncation. The amount of space available for data storage may be slightly smaller as there are internal control structures which can be freed by trunction but are required if the space is used for data storage.
  • classmethod FixDefaultGlobalCollation(Directory As %String, Flags As %Integer = 0, ByRef Messages As %String) as %Status
    Set the default Cache' system globals in a database to have the correct Cache Standard collation.
    Bit 0 - If not set, only diagnose errors and do not modify the database Bit 1 - Do not set switch 10 during the operation Bit 2 - Do not print message array to principal device
    classmethod FormatSizes(val As %Float, RoundDown As %Integer = 0) as %Float
    Used for formatting database and global sizes in MB, GB, or TB
    classmethod GetDatabaseFreeSpace(Directory As %String, ByRef FreeSpace As %Integer) as %Status
    Return number of MB of free space in a database.
    classmethod GetDirectory(Prompt, Value, Obj, Min, Max, Help, Flag, Timeout) as %Integer
    Prompt for a directory.
    classmethod GetFreeSpace(Directory As %String, ByRef FreeSpace As %Integer, ByRef FreeBlocks As %Integer) as %Status
    Return number of MB of free space in a database, and the number of FreeBlocks
    method GetStatus(Internal As %Boolean = 1) as %String
    Return the status of the database.
    Internal - True(default): return plan text of the status. False: return text with current language setting (for displaying).

    Possible returned texts:
    method GlobalJournalStateGet() as %JournalState
    classmethod GlobalJournalStatePrompt(Prompt, Obj)
    prompt for global journal state.
    classmethod IntegrityCheck(Dirnames As %String) as %String
    This runs an integrity check on all or selected databases. For selected databases pass a list of directory names.
    classmethod IsSystemDB(Directory As %String) as %Boolean
    Check whether the database directory path is configured as a system database (the DB name as CACHESYS, CACHELIB, CACHE, CACHETEMP, CACHEAUDIT).
    classmethod JobCompact(Directory As %String, PercentFull As %Integer = 90, LogFile As %String) as %Status
    Background routine for compacting a database.
    classmethod JobCompactDatabase(Directory As %String, PercentFull As %Integer = 90, ByRef LogFile As %String) as %Status
    Compact all globals in a database, using a background job.
    classmethod ModifyDatabase(Directory As %String, Size As %Integer, Resource As %String, GlobalJournalState As %Integer) as %Status
    Modifies parameters of a database.
    method Mount(readonly As %Boolean = 0, cluster As %Boolean = 0, mirrorcatchup As %Boolean = 1) as %Status
    Mount a database

    Uses Readonly, ClusterMountMode and Mirrored properties

    Input Parameters:
    • readonly defaults to 0 (not readonly). When True causes the database which would normally be mounted read-write to be mounted read-only. Normally a database is only mounted read-only if is not writeable (due to protection or filesystem issues) or if the internal database read-only property is set.
    • cluster defaults to 0 (private mount). This is ignored on non-cluster members. On a cluster member setting this to 1 causes the database to be mounted for clustered (shared) access. If the system is not a cluster member, this will cause the system to try to join the cluster.
    • mirrorcatchup defaults to 1 (start catchup). This parameter is ignored if the system is not a mirror member or if the database being mounted is not a mirrored database. When set to 1 database catchup is started when a mirrored database is successfully mounted. If the current system is an async member which has stopped dejournaling, catchup will run up to the point that dejournaling was stopped (for example, the database will be made "as current" as the other mirrored databases). Otherwise catchup will apply as much journal data as possible and try to link the database into the active dejournaling system. When set to 0 catchup is not started after the mount and must be started manually later. When mounting several mirrored databases it is best to not start catchup as part of the mount but rather start catchup for all the databases using the ^MIRROR utility after they have all been mounted. This is much more efficient as catchup will make a single pass through the journal files to cover all the databases rather than running though the journal files for each database.

    classmethod MountDatabase(Directory As %String, readonly As %Boolean = 0, cluster As %Boolean = 0, mirrorcatchup As %Boolean = 1) as %Status
    Mount a database.
    classmethod ReturnUnusedSpace(Directory As %String, TargetSize As %Integer = 0, ByRef ReturnSize As %Integer) as %Status
    Free blocks at the end of the CACHE.DAT file are returned to the physical filesystem, and the file is shortened.

    TargetSize is the desired size in MB of the resulting file. Specify 0 to return all available freespace at the end of the file. On success, ReturnSize is set to the new file size in MB.

    Fails and returns error status if a conflicting database operation is in progress in the same database. Conflicting operations include expansion, backup, defragmentation, compaction and ReturnUnusedSpace.

    Note: Since freespace is not returned all at once when a global is killed, but rather done in the background, there may be a delay following the kill before the space is available to be returned.

    This method is not available on VMS

    classmethod SilentIntegrityCheck(Filename As %String, dirlist As %String, gbllist As %String = "", StopAfterAnyError As %Boolean = 0) as %Status
    This class method starts a job that checks the integrity of globals in one or more databases.

    The parameters are:

  • Filename - File to store results in
  • dirlist - Optional $list of directories that contain databases to check, by default all databases are checked.
  • gbllist - Optional $list of globals to check,if specified then dirlist must contain a single database.
  • StopAfterAnyError - set true to stop on error.
  • classmethod ViewIntegrityLog(Filename As %String) as %Status
    This displays the contents of a file containing the output from a previous call to ##class(SYS.Database).SilentIntegrityCheck(filename) on the current device


    query CompactLocalList(Mask As %String)
    Selects Directory As %String, SFN As %Integer, ReadOnly As %Integer, Resource As %String, BlockSize As %Integer, Collation As %Integer
    This is a quick query for list of databases.

    Mask="*" or $lb(directory1,directory2,...)
    Returns SFN, directory, Read Only status, Resource Name, Block size and Collation.
    query Detail(Mask As %String, Unused As %Boolean)
    Selects Directory As %String, MirrorDBName As %String, MaxSize As %Integer, Size As %Integer, Status As %String, BlockSize As %String, ClusterMountMode As %String, ClusterMounted As %String, ExpansionSize As %String, LastExpansionTime As %String, Mounted As %String, NewGlobalCollation As %String, NewGlobalGrowthBlock As %String, NewGlobalIsKeep As %String, GlobalJournalState As %String, NewGlobalPointerBlock As %String, ReadOnly As %String, ResourceName As %String, MountedReadOnly As %Integer, EncryptedDB As %String, EncryptionKeyID As %String
    Provides detail of all local databases (mounted or dismounted) in the systems SFN table.

    Mask="*" or $lb(directory1,directory2,...)
    Databases which are never mounted are not returned by this query. For example, if the databases in Config.Databases were not mounted at startup, they won't be returned in this query.
    The Status field is the mount status of the database, and how it is mounted, e.g. "Mounted/RW"
    query FreeSpace(Mask As %String = "*", Unused As %Boolean)
    Selects DatabaseName As %String, Directory As %String, MaxSize As %String, Size As %String, ExpansionSize As %String, Available As %String, Free As %Float, DiskFreeSpace As %String, Status As %String, SizeInt As %Integer, AvailableNum As %Integer, DiskFreeSpaceNum As %Integer, ReadOnly As %Boolean
    Provides a freespace list of all local databases mounted in this configuration.

    Note that calculating the free space may take a while.
    Mask="*" or $lb(directory1,directory2,...)
    For the FreeSpace Report, You can also enter the following in order to select by database name:
    "String,String1" - Any name matching one of these elements
    "String*" - Any Name starting with "String"
    "String,String1*,String2" - Any Name matching one of these elements, or starting with "String1"
    Notes: Databases which are not mounted are not returned by this query.
    query Integrity(Mask As %String, Filename As %String)
    Selects Directory As %String, Status As %Boolean
    This runs an integrity check of all local databases mounted in this configuration.

    Note that calculating the integrity may take a while.
    Mask="*" or $lb(directory1,directory2,...)
    Filename - Filename to write Integrity output to
    Notes: Databases which are not mounted are not returned by this query.
    query List(Mask As %String, Unused As %Boolean)
    Selects Directory As %String, MaxSize As %String, Size As %Integer, Status As %String, Resource As %String, Encrypted As %Boolean, StateInt As %String, Mirrored As %Boolean, SFN As %String
    Provides a list of all local databases (mounted or dismounted) in the systems SFN table.

    Mask="*" or $lb(directory1,directory2,...)
    The Status field is the mount status of the database, and how it is mounted, e.g. "Mounted/RW"
    Databases which are never mounted are not returned by this query. For example, if the databases in Config.Databases were not mounted at startup, they won't be returned in this query.
    query RemoteDatabaseList(Serverxname As %String = ServerxName)
    Selects RemoteDirectory As %String, DBStatus As %String, DBName As %String
    Returns a list of all remote databases for the passed server mounted on this configuration.

    query RemoteGlobalList(Serverxname As %String = ServerxName, Serverxdir As %String = Serverxdir)
    Selects Global As %String
    Returns a list of globals on the passed server and directory.

    Inherited Members

    Inherited Methods