For information on converting to InterSystems IRIS, see the
InterSystems IRIS Adoption Guide
and the InterSystems IRIS In-Place Conversion Guide,
both available on the WRC Distributions page (login required).
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 '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'.
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.
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 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.
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.
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.
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.
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 (Cache' 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 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.
Check the state of a background database compaction.
State = 0-(in progress), 1-(finished), 2-(no compaction logged)
classmethod DecryptDatabase(database 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:
database - Name of the database to decrypt.
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().
classmethod EncryptDatabase(database 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:
database - Name of the database to encrypt.
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
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
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
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 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.
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
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)