SYS.Database

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.

Default Localization Domain

Block size in bytes of the database.
Either 2048, 4096, 8192, 16384, 32768, or 65536

Database is configured to be mounted in cluster mode
If this property is set then this database has to be mounted explicitly.

Database is currently cluster mounted

Directory containing the database

Database is encrypted

Database encryption key ID

Database is expanding.

Size in MB to Expand by.
0 - Use system defaults (recommended)

Journal setting for database.
2 - No
3 - Yes

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.

Last time database expanded, converted to local time.

Maximum size in MB, 0=unlimited (recommended).

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.

Mirrored Database is running for CatchupDB.

Mirrored Database is created by %New instead of 'Added' to existing DB.

Database name identified in mirror set

Mirrored Database is paused for dejournaling.

Mirrored Database is on failover members

Database has a status of mirrored-no-write which means it is mounted read-only so it cannot be written to.

Mirror Database is obsolete due to the database's GUID mismatched with GUID in mirror journal file directory block during dejournaling.

Mirror set name of this mirrored database.

Database is marked as mirrored

Database is mounted.

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)

Default collation for new globals.

Default growth block for new globals.

Default Keep value for New globals.

Block where the index pointer starts.

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.

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.

Read-Only reason code

Read-Only reason text.

Database attribute in label says Read Only.

Database is mounted for read only

Resource name for the database.

Run CatchupDB when this mirrored DB is created.

Size in MB.

List of additional directories (beyond Directory) where volumes of this database may be located.

This checks to see if this configuration allows creating block sizes other than the default, which is 8k.

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.

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.
  

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)

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)

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.

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

Delete a database.

Delete a database.

Disable journaling for Database.

Dismount a database.

Dismount a database.

Enable journaling for Database.

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.

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.

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

Used for formatting database and global sizes in MB, GB, or TB

Return number of MB of free space in a database.

Prompt for a directory.

Return number of MB of free space in a database, and the number of FreeBlocks

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

prompt for global journal state.

This runs an integrity check on all or selected databases. For selected databases pass a list of directory names.

Check whether the database directory path is configured as a system database (the DB name as IRISSYS, IRISLIB, IRISLOCALDATA, IRISTEMP, IRISAUDIT).

Background routine for compacting a database.

Compact all globals in a database, using a background job.

Modifies parameters of a database.

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.

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.

Mount a database.

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.

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

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.

This displays the contents of a file containing the output from a previous call to ##class(SYS.Database).SilentIntegrityCheck(filename) on the current device