Skip to main content

SYS.Database

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

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:
    Directory
    BlockSize
    EncryptedDB
    EncryptionKeyID
    Size
    ExpansionSize
    MaxSize
    MirrorDBName
    MirrorSetName
    GlobalJournalState
    NewGlobalCollation
    NewGlobalIsKeep
    NewGlobalGrowthBlock
    NewGlobalPointerBlock
    ClusterMountMode
    ResourceName

Properties which can be modified for an already created database are:
    ReadOnly
    Size
    ExpansionSize
    MaxSize
    GlobalJournalState
    NewGlobalCollation
    NewGlobalIsKeep
    NewGlobalGrowthBlock
    NewGlobalPointerBlock
    ClusterMountMode
    ResourceName

Read-only properties which are managed by the system and cannot be modified are:
    Expanding
    LastExpansionTime
    Mounted
    ReadOnlyMounted
    ClusterMounted
    Mirrored
    MirrorNoWrite
    MirrorActivationRequired
    MirrorFailoverDB
    InActiveMirror
    MirrorObsolete

The maximum value of the 'MaxSize' property depends on the block size of the database, as follows:
    17 TB (16777080 MB) for 4K database.
    34 TB (33553904 MB) for 8K database.
    67 TB (67106832 MB) for 16K database.
    134 TB (134202016 MB) for 32K database.
    268 TB (268392960 MB) for 64K database.

When 'MaxSize' or 'Size' peoperty is modified InterSystems IRIS instance 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

Parameters

parameter DEFAULTCONCURRENCY = 0;
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

Properties

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(), 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(), ClusterMountModeSet()
property ClusterMounted as %Boolean [ InitialExpression = 0 , ReadOnly ];
Database is currently cluster mounted
Property methods: ClusterMountedDisplayToLogical(), ClusterMountedGet(), ClusterMountedIsValid(), ClusterMountedLogicalToDisplay(), ClusterMountedNormalize()
property Directory as %SysPath;
Directory containing the database
Property methods: DirectoryDisplayToLogical(), DirectoryGet(), DirectoryIsValid(), DirectoryLogicalToDisplay(), DirectoryLogicalToOdbc(), DirectoryNormalize()
property EncryptedDB as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Database is encrypted
Property methods: EncryptedDBDisplayToLogical(), EncryptedDBGet(), EncryptedDBIsValid(), EncryptedDBLogicalToDisplay(), EncryptedDBLogicalToOdbc(), EncryptedDBNormalize(), EncryptedDBOdbcToLogical(), EncryptedDBSet()
property EncryptionKeyID as %String (MAXLEN = 64, MINLEN = 1);
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(), ExpansionSizeLogicalToDisplay(), ExpansionSizeNormalize(), ExpansionSizeSet()
property GlobalJournalState as %Library.JournalState;
Journal setting for database.
2 - No
3 - Yes
Property methods: GlobalJournalStateBooleanToLogical(), GlobalJournalStateDisplayToLogical(), GlobalJournalStateIsValid(), GlobalJournalStateLogicalToBoolean(), GlobalJournalStateLogicalToDisplay(), GlobalJournalStateLogicalToMenu(), GlobalJournalStateLogicalToSystem(), GlobalJournalStateMenuToLogical(), GlobalJournalStateNormalize(), 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(), MaxSizeLogicalToDisplay(), MaxSizeNormalize(), 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(), 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(), 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 MultiVolume as %Integer [ InitialExpression = 0 , ReadOnly ];
Number of additional volume files beyond the IRIS.DAT file that comprise this database. 0 if the database is not multi-volume (just an IRIS.DAT)
Property methods: MultiVolumeDisplayToLogical(), MultiVolumeGet(), MultiVolumeIsValid(), MultiVolumeLogicalToDisplay(), MultiVolumeNormalize()
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(), NewGlobalCollationSet(), NewGlobalCollationSetLocalName(), NewGlobalCollationSetLocalNumber()
property NewGlobalGrowthBlock as %Integer (MINVAL = 50) [ InitialExpression = 50 ];
Default growth block for new globals.
Property methods: NewGlobalGrowthBlockDisplayToLogical(), NewGlobalGrowthBlockGet(), NewGlobalGrowthBlockIsValid(), NewGlobalGrowthBlockLogicalToDisplay(), NewGlobalGrowthBlockNormalize(), NewGlobalGrowthBlockSet()
property NewGlobalIsKeep as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Default Keep value for New globals.
Property methods: NewGlobalIsKeepDisplayToLogical(), NewGlobalIsKeepGet(), NewGlobalIsKeepIsValid(), NewGlobalIsKeepLogicalToDisplay(), NewGlobalIsKeepLogicalToOdbc(), NewGlobalIsKeepNormalize(), NewGlobalIsKeepOdbcToLogical(), NewGlobalIsKeepSet()
property NewGlobalPointerBlock as %Integer (MINVAL = 6) [ InitialExpression = 16 ];
Block where the index pointer starts.
Property methods: NewGlobalPointerBlockDisplayToLogical(), NewGlobalPointerBlockGet(), NewGlobalPointerBlockIsValid(), NewGlobalPointerBlockLogicalToDisplay(), NewGlobalPointerBlockNormalize(), NewGlobalPointerBlockSet()
property NewVolumeDirectory as %SysPath;
If expansion creates a new volume as described in VolumeSize), it will be created in this directory. Defaults to Directory (the same directory as IRIS.DAT) and if this property is null on creation, it will be set to Directory. If set to a different directory and that directory is not already in the VolumeDirectoryList, it will be added on save.
Property methods: NewVolumeDirectoryDisplayToLogical(), NewVolumeDirectoryGet(), NewVolumeDirectoryIsValid(), NewVolumeDirectoryLogicalToDisplay(), NewVolumeDirectoryLogicalToOdbc(), NewVolumeDirectoryNormalize(), NewVolumeDirectorySet()
property NewVolumeThreshold as %Integer (MINVAL = 0) [ InitialExpression = 0 ];
If 0, expansion of this database will never create a new volume. If non-zero, when the current last volume expands past this size in MB, a new database volume will be created instead.
Property methods: NewVolumeThresholdDisplayToLogical(), NewVolumeThresholdGet(), NewVolumeThresholdIsValid(), NewVolumeThresholdLogicalToDisplay(), NewVolumeThresholdNormalize(), NewVolumeThresholdSet()
property ROReasonCode as %Integer [ InitialExpression = 0 , ReadOnly ];
Read-Only reason code
Property methods: ROReasonCodeDisplayToLogical(), ROReasonCodeGet(), ROReasonCodeIsValid(), ROReasonCodeLogicalToDisplay(), ROReasonCodeNormalize()
property ROReasonText as %String [ ReadOnly ];
Read-Only reason text.
Property methods: ROReasonTextDisplayToLogical(), ROReasonTextGet(), ROReasonTextIsValid(), ROReasonTextLogicalToDisplay(), ROReasonTextLogicalToOdbc(), ROReasonTextNormalize()
property ReadOnly as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Database attribute in label says Read Only.
Property methods: ReadOnlyDisplayToLogical(), ReadOnlyGet(), ReadOnlyIsValid(), ReadOnlyLogicalToDisplay(), ReadOnlyLogicalToOdbc(), ReadOnlyNormalize(), ReadOnlyOdbcToLogical()
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 = $$$DBDEFAULTResourceName ];
Resource name for the database.
Property methods: ResourceNameDisplayToLogical(), ResourceNameGet(), ResourceNameIsValid(), ResourceNameLogicalToDisplay(), ResourceNameLogicalToOdbc(), ResourceNameNormalize(), 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(), SizeSet()
property VolumeDirectoryList as %List [ ReadOnly ];
List of additional directories (beyond Directory) where volumes of this database may be located.
Property methods: VolumeDirectoryListGet(), VolumeDirectoryListIsValid(), VolumeDirectoryListLogicalToOdbc(), VolumeDirectoryListOdbcToLogical()

Methods

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 a database 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.
Parameters:
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.

Parameters:
  • PercentFull Target percentage full for the blocks at the data level. Defaults to 90% if omitted.
  • MbProcessed (by reference) returns how many MB of data was processed
  • MbCompressed (by reference) returns how many MB the data processed occupies at the end of the operation
  • Display True(1) or False(0) as to whether the method should display status output on a per-global basis as it executes. Defaults to False. If True, then Device controls where the output is displayed. If Device is omitted, output is written to the current device.
  • Device When Display is true, this is where the output is displayed. This must already be open although it does not have to be the current I/O device. If omitted and Display is true, output is written to the current device.
  • GloSel (by reference) If present this is an array passed by reference where the subscripts are the names of the globals to be processed. If omitted, all globals are processed.

classmethod CompactDatabase(Directory As %String, PercentFull As %Integer = 90, ByRef MbProcessed As %Integer, ByRef MbCompressed As %Integer, Display As %Boolean = 0, Device As %String) as %Status
Compact all globals in a database.

Parameters:
  • Directory Directory specification of the database to compact.
  • PercentFull Target percentage full for the blocks at the data level. Defaults to 90% if omitted.
  • MbProcessed (by reference) returns how many MB of data was processed
  • MbCompressed (by reference) returns how many MB the data processed occupies at the end of the operation
  • Display True(1) or False(0) as to whether the method should display status output on a per-global basis as it executes. Defaults to False. If True, then Device controls where the output is displayed. If Device is omitted, output is written to the current device.
  • Device When Display is true, this is where the output is displayed. This must already be open although it does not have to be the current I/O device. If omitted and Display is true, output is written to the current device.
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 (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.

Parameters:
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 (Standard.)

Examples:
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 system database to use an 8192 block size. Freeze the system while the database is copied. This is useful to convert the system 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 = $$$DBDEFAULTResourceName, GlobalJournalState As %Integer, MirrorDBName As %String = "", MirrorSetName As %String = "", RunCatchupDB As %Boolean = 1, MaxSize=0, ExpansionSize=0, NewGlobalIsKeep=0, NewGlobalCollation=##Class(%Library.Collate).GetSystemDefaultNumber(), NewVolumeThreshold=0) 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 DecryptDatabase(Directory As %String) as %Status
This method decrypts a database. The database must be dismounted, and the database encryption key that was used to encrypt the database must be activated.

Input parameters:
Directory - the database's directory path (either absolute or relative to the installation directory)

Return value: Return status.
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 EncryptDatabase(Directory As %String) as %Status
This method encrypts a database using the default key for encrypting new databases. The database must be dismounted, and the default database encryption key must be activated. If the database is already encrypted, it will be re-encrypted.

Input parameters:
Directory - the database's directory path (either absolute or relative to the installation directory)

Return value: Return status.
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 system globals in a database to have the correct 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 %Float) 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 %Float, 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.
    Parameters:
    Internal - True(default): return plan text of the status. False: return text with current language setting (for displaying).

    Possible returned texts:
    Unmounted
    Dismounted
    Expanding
    ClusterMounted/R
    ClusterMounted/RW
    Mounted/R
    Mounted/RW
    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 IRISSYS, IRISLIB, IRISLOCALDATA, IRISTEMP, IRISAUDIT, IRISMETRICS).
    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.
    classmethod ModifyVolumeDirectoryList(Directory As %String, VolDirs As %List, NewVolDirNum As %Integer = 0) as %Status
    Writes a new VolumeDirectoryList to a dismounted multi-volume database.

    This method is to be used when the directories used to store volumes of the database have changed in order to allow the database to be mounted, such as when a copy of the database volumes are restored to a different directory structure (perhaps on a different system). This method can also be used when volumes of the databases are consolidated from multiple directories back into a smaller number of directories, to remove the unneeded directories from the list. Note: the primary database directory (the directory containing the IRIS.DAT) is never needed in the VolumeDirectoryList, as that directory is implictly included in the search for volumes.

    Parameters:

  • Directory - primary database directory (location of the IRIS.DAT)
  • VolDirs - the new value of VolumeDirectoryList to write
  • NewVolDirNum - the number corresponding to the list element in the VolDirs parameter that is to be the new NewVolumeDirectory, or 0 for the primary directory

    The database must be dismounted and must have been configured for multiple volumes in the past (e.g. it has multiple volumes or has a non-null VolumeDirectoryList). Otherwise and error is returned

    The directories in the VolDirs parameter must have no duplicates and must be different than the primary database directory or an error is returned. If any directory in the list already contains an iris.dbdir file indicating the primary volume directory for volumes in that directory, then it must match the primary volume directory or its an error. A new iris.dbdir file will be written to each directory that doesn't have one.

  • 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 NewVolume(Directory As %String, NewVolDir As %String, InitialSize As %Integer) as %Status
    Expands a database into a new volume in a specified directory. This may be used to expand the database into another storage device with more space, preventing further expansion of the current last volume in the storage device where it resides. It can also be used to create a new volume in the same directory to limit individual file sizes (though the NewVolumeThreshold can be used to perform that function automatically).

    The directory where the new volume is created must be specified in the 'NewVolDir' parameter. The directory may be the same directory as the IRIS.DAT file, another directory that already contains volumes of this database, or a different directory. If the directory doesn't exist, it will be created. This directory will also be set as the NewVolumeDirectory and it will therefore be used for any further volumes created automatically due to the NewVolumeThreshold.

    The 'InitialSize' parameter specifies the initial size of the volume in MB. If NewVolumeThreshold is non-zero, it is taken as an upper bound to InitialSize.

    classmethod ReturnUnusedSpace(Directory As %String, TargetSize As %Integer = 0, ByRef ReturnSize As %Integer) as %Status
    Free blocks at the end of the database 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

    Queries

    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, ReadOnlyReason As %String, EncryptedDB As %String, EncryptionKeyID As %String, NewVolumeThreshold As %Integer, NewVolumeDirectory As %String, MultiVolume As %Integer
    Provides detail of all local databases (mounted or dismounted) in the systems SFN table.

    Parameters:
    Mask="*" or $lb(directory1,directory2,...)
    Notes:
    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.
    Parameters:
    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.
    Parameters:
    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.

    Parameters:
    Mask="*" or $lb(directory1,directory2,...)
    Notes:
    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.

    query VolumeFiles(Directory As %SysPath, ByVolDir As %Integer = 0)
    Selects VolumeNumber As %String, VolumeDirectory As %SysPath, File As %String, Size As %Integer, VolumeDirectoryTotalSize As %Integer, DiskFree As %Integer
    Returns information about each volume that comprise a particular database. If the database is mounted in a normal state, information is returned from memory; otherwise it is fetched from disk.

    Parameters:
    Directory - database directory
    ByVolDir - 0/1: If 1 and VolumeDirectoryList is not null then the results will ordered by VolumeDirectory (starting with the primary directory), and any directory that has no volumes will be returned in a row with File="*None*" (for display purposes) and VolumeNumber=-1. If 0 then rows are returned in volume order, and any empty VolumeDirectory is ignored.

    Each row returned contains:

  • VolumeNumber - 0 for IRIS.DAT, 1..n for additional volumes, or -1 when File is "*None*" (see below)
  • VolumeDirectory - Either Directory, one of the directories in the VolumeDirectoryList, or "*Unknown*" if a volume is missing and its location is uncertain (see below).
  • File - File name for the volume or a special value beginning with "*" as described below
  • Size - Size of volume in MB
  • VolumeDirectoryTotalSize - Size in MB of all volumes in the VolumeDirectory
  • DiskFree - Free space on disk containing the volume in MB; -1 on error.

    Special Flags

    File="*None*" and VolumeNumber=-1 indicates a row being returned where VolumeDirectory is a directory in the VolumeDirectoryList that contains no volumes.

    File contains "*Missing*" followed by the file name if the volume wasn't found. In that case, VolumeDirectory="*Unknown*" if there are more than one directory where it could be found (because VolumeDirectoryList is non-null).

    File contains "*Conflict*" followed by the file name if the file appears in more than one directory.

  • Indexes

    index (IDKEY on ) [IdKey, Type = key];
    Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()

    Inherited Members

    Inherited Methods

    FeedbackOpens in a new tab