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
    CompressionEngine
Properties which can be modified for an already created database are:
    ReadOnly
    Size
    ExpansionSize
    MaxSize
    GlobalJournalState
    NewGlobalCollation
    NewGlobalIsKeep
    NewGlobalGrowthBlock
    NewGlobalPointerBlock
    ClusterMountMode
    ResourceName
    CompressionEngine
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 '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 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'.
Database block compression support (accessed via the CompressionEngine
property) varies by platform and filesystem. System databases cannot
be marked for compression.
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.
property CompressionEngine as %Integer [ InitialExpression = 0 ];
0 - No compression
>0 - Internal id+1 of compression engine
-1 - only used on input for modify means leave unchanged
Support for this feature varies by platform and filesystem. System databases cannot
be marked for compression. The DBCompressionSupported() class method
indicates whether a given platform supports database compression or not.
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.
classmethod AuditJournalStateChange(db As SYS.Database) as %Status [ Language = objectscript ]
classmethod CheckBlockSizeAllowed(Size As %String) as %Boolean [ Language = objectscript ]
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 [ Language = objectscript ]
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 [ Language = objectscript ]
classmethod ClearMirrorFailoverDB(Directory As %String) as %Status [ Language = objectscript ]
This method will clear the MirrorFailoverDB flag in this mirrored DB.
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 [ Language = objectscript ]
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.
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, CompressionEngine As %Integer = 0, MaxSize=0, ExpansionSize=0, NewGlobalIsKeep=0, NewGlobalCollation=##Class(%Library.Collate).GetSystemDefaultNumber()) as %Status [ Language = objectscript ]
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.
CompressionEngine is the numeric value (eg. from DisplayToLogical) of the engine or 0 for none.
classmethod DBCompactStatus(Directory As %String, ByRef State As %Integer, ByRef LogFile As %String) as %Status [ Language = objectscript ]
Check the state of a background database compaction.
State = 0-(in progress), 1-(finished), 2-(no compaction logged)
classmethod DBCompressionSupported() as %Boolean [ Language = objectscript ]
Returns TRUE if this platform supports database block compression,
or FALSE if it does not.
classmethod DecryptDatabase(Directory As %String) as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
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 [ Language = objectscript ]
Delete a database.
classmethod DeleteDatabase(Directory As %String) as %Status [ Language = objectscript ]
Delete a database.
method DisableJournaling() as %Status [ Language = objectscript ]
Disable journaling for Database.
method Dismount() as %Status [ Language = objectscript ]
Dismount a database.
classmethod DismountDatabase(Directory As %String) as %Status [ Language = objectscript ]
Dismount a database.
method EnableJournaling(val As %Integer) as %Status [ Language = objectscript ]
Enable journaling for Database.
classmethod EncryptDatabase(Directory As %String) as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
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.
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 [ Language = objectscript ]
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 [ Language = objectscript ]
Used for formatting database and global sizes in MB, GB, or TB
classmethod GetDatabaseFreeSpace(Directory As %String, ByRef FreeSpace As %Float) as %Status [ Language = objectscript ]
Return number of MB of free space in a database.
classmethod GetDirectory(Prompt, Value, Obj, Min, Max, Help, Flag, Timeout) as %Integer [ Language = objectscript ]
Prompt for a directory.
classmethod GetFreeSpace(Directory As %String, ByRef FreeSpace As %Float, ByRef FreeBlocks As %Integer) as %Status [ Language = objectscript ]
Return number of MB of free space in a database, and the number of FreeBlocks
method GetStatus(Internal As %Boolean = 1) as %String [ Language = objectscript ]
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 [ Language = objectscript ]
classmethod GlobalJournalStatePrompt(Prompt, Obj) [ Language = objectscript ]
prompt for global journal state.
classmethod IntegrityCheck(Dirnames As %String) as %String [ Language = objectscript ]
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 [ Language = objectscript ]
Check whether the database directory path is configured as a system database (the DB name as IRISSYS, IRISLIB, IRISLOCALDATA, IRISTEMP, IRISAUDIT).
classmethod JobCompact(Directory As %String, PercentFull As %Integer = 90, LogFile As %String) as %Status [ Language = objectscript ]
Background routine for compacting a database.
classmethod JobCompactDatabase(Directory As %String, PercentFull As %Integer = 90, ByRef LogFile As %String) as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
Modifies parameters of a database.
method Mount(readonly As %Boolean = 0, cluster As %Boolean = 0, mirrorcatchup As %Boolean = 1) as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
Mount a database.
classmethod ReturnUnusedSpace(Directory As %String, TargetSize As %Integer = 0, ByRef ReturnSize As %Integer) as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
This class method starts a job that checks the integrity of globals in one or more databases.
classmethod ViewIntegrityLog(Filename As %String) as %Status [ Language = objectscript ]
This displays the contents of a file containing the output from a previous call to
##class(SYS.Database).SilentIntegrityCheck(filename) on the current device
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"
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.
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.
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)