The -NAME, -REGION, and -SEGMENT qualifiers each have additional qualifiers used to further define or specify characteristics of a name, region, or segment. The following sections describe these additional qualifiers.
The following -NAME qualifier can be used with the ADD or CHANGE commands.
-REGION=region-name
Specifies the name of a region. Region names are not case-sensitive, but are represented as uppercase by GDE.
The minimum length is one alphabetic character.
The maximum length is 31 alphanumeric characters.
Example:
GDE> add -name a* -region=areg
This command creates the namespace a*, if it does not exist, and maps it to the region areg.
Summary
The following -REGION qualifiers can be used with the ADD, CHANGE, or TEMPLATE commands.
Specifies the number of the collation sequence definition to be used as the default for this database file. The number can be any integer from 0 to 255. The number you assign as a value must match the number of a defined collation sequence that resides in the shared library pointed to by the environment variable gtm_collate_n. For information on defining this environment variable and creating an alternate collation sequence, refer to the "Internationalization" chapter in the GT.M Programmer's Guide.
The minimum COLLATION_DEFAULT number is zero, which is the standard M collation sequence.
The maximum COLLATION_DEFAULT number is 255.
By default, GDE uses zero (0) as the COLLATION_DEFAULT.
-D[YNAMIC_SEGMENT]=segment-name
Specifies the name of the segment to which the region is mapped. Segment-names are not case-sensitive, but are displayed as uppercase by GDE.
The minimum length is one alphabetic character.
The maximum length is 31 alphanumeric characters.
Specifies the maximum size of keys, in bytes, which can be stored in the region. The KEY_SIZE must be less than the RECORD_SIZE. GDE rejects the command if the KEY_SIZE is inappropriate for the RECORD_SIZE.
The minimum KEY_SIZE is three bytes.
The maximum KEY_SIZE is 1,019 bytes.
When determining the maximum key size, applications should consider the following:
GT.M uses packed decimal representation for numeric subscripts which may be larger or smaller than the original representation.
GT.M substitutes an element terminator for the caret (^), any comma (,), and any right parenthesis ()).
GT.M adds an extra byte for every string element, including the global name.
For example, the key ^ACN ("Name", "Type") internally occupies 17 bytes.
By default, GDE uses a KEY_SIZE of 64 bytes.
Specifies the maximum size (in bytes) of a global variable node's value that can be stored in a region.
If the size of a global exceeds one database block, GT.M implicitly spans that global across multiple database blocks. In the event a global variable node spans multiple blocks, and the process is not already within a TP transaction, the GT.M run-time system automatically and transparently performs the entire operation within an implicit TP transaction (as it does for Triggers).
The minimum RECORD_SIZE is zero. A RECORD_SIZE of zero only allows a global variable node that does not have a value. A typical use of a global variable node with RECORD_SIZE of zero is for creating indices (where the presence of a node is all that is required).
The maximum RECORD_SIZE is 1,048,576 bytes (1MiB).
By default, GDE uses a RECORD_SIZE of 256 bytes.
-[NO]N[ULL_SUBSCRIPTS]=[ALWAYS|NEVER|EXISTING]
Indicates whether GT.M allows null subscripts for global variables stored in the region (that is, whether GT.M permits references such as ^aaa("",1)).
ALWAYS indicates that the null subscripts for global variables are allowed.
NEVER indicates that null subscripts for global variables are not allowed.
EXISTING indicates that null subscripts for global variable can be accessed and updated, but not created anew.
By default, regions have -NULL_SUBSCRIPTS=NEVER.
Determines whether GT.M null subscripts collate in conformance to the M standard.
If STDNULLCOLL is specified, subscripts of globals in the database follow the M standard where the null subscript collates before all other subscripts.
If NOSTDNULLCOLL is specified, null subscripts collate between numeric and string subscripts. FIS strongly recommends that you use STDNULL and against using this non-standard null collation, which is the default for historical reasons.
Controls whether custom errors in a region should automatically cause an Instance Freeze. This qualifier modifies the value of "Inst Freeze on Error" file header element.
For more information on setting up a list of custom errors that automatically invoke an Instance Freeze, refer to “Instance Freeze”.
For more information on setting or clearing an Instance Freeze on an instance irrespective of whether any region is enabled for Instance, refer to “Starting the Source Server”.
Quickens normal process shutdown where a large number of processes accessing a database file are required to shutdown almost simultaneously, for example, in benchmarking scenarios. When a terminating GT.M process observes that a large number of processes are attached to a database file and QDBRUNDOWN is enabled, it bypasses checking whether it is the last process accessing the database. Such a check occurs in a critical section and bypassing it also bypasses the usual RUNDOWN actions which accelerates process shutdown removing a possible impediment to process startup. By default, QDBRUNDOWN is disabled.
Note that with QDBRUNDOWN there is a possibility of race condition that might leave the database fileheader and IPC resources in need of cleanup. Although QDBRUNDOWN minimizes the probability of such a race condition, it cannot eliminate it. FIS recommends restricting QDBRUNDOWN usage to special circumstances such as benchmarking and recommends NOQDBRUNDOWN for normal GT.M usage. When using QDBRUNDOWN, FIS recommends an explicit MUPIP RUNDOWN of the database file after the last process exits, to ensure the cleanup of database fileheader and IPC resources.
-[NO]J[OURNAL][=journal-option-list]
This qualifier establishes characteristics for the journal file on newly created databases.
-NOJOURNAL specifies that updates to the database file are not journaled. -NOJOURNAL does not accept an argument assignment.
-JOURNAL specifies that journaling is allowed. -JOURNAL takes one or more arguments in a journal-option-list. The journal-option-list contains keywords separated with commas (,) enclosed in parentheses ( ) with file-names quoted (for example, change -region test -journal=(before,file="foo") . If the list contains only one keyword, the parentheses and quotes are optional.
Although you do not have to establish the criteria for your journaling process at this point, it is efficient to do so, even if you are not entirely sure you will use journaling. The options available for -JOURNAL set up the environment, so it is ready for you to enable with MUPIP SET -JOURNAL. You can also change or add any of the established options at that time.
For more information about journaling, see Chapter 6: “GT.M Journaling”.
The journal-option-list includes:
The following section describes some -JOURNAL options.
Specifies the limit on the size of a journal file. When the journal file size reaches the limit, GT.M automatically switches to a new journal file with a back-pointer to the prior journal file.
[NO]BEFORE_IMAGE controls whether the journal should include before-image records.
The BEFORE_IMAGE option is required if you plan to consider "roll-back" (Backward) recovery of the associated database file or if you plan to use certain database replication options. For a description of this type of recovery, refer to Chapter 6: “GT.M Journaling”.
Specifies the name of the journal file.
Unless the name is the sole journaling option, and is the last parameter on the line, it should always be enclosed in quotation marks in this context.
Journal file-specifications-names are limited to 255 characters.
By default, GDE derives the file-specification-name from the database "file-name".
By default, GDE uses a journal file extension of .mjl.
Journal Options Summary
With GDE, you can create the journal files and define the journal parameters; however, you must use MUPIP SET to explicitly turn it ON, and you must specify BEFORE/NOBEFORE at that time.
For information on all Journal options and their allowable minimum and maximum values, see “SET -JOURNAL Options ” in the "GT.M Journaling" chapter.
Summary
The following table summarizes GDE region qualifiers. It provides their abbreviations, defaults (as provided by FIS), and allowable minimum and maximum values.
|
GDE REGION Qualifiers | |||
|---|---|---|---|
|
QUALIFIER |
DEFAULT |
MINIMUM |
MAXIMUM |
|
-C[OLLATION_DEFAULT]=number (integer) |
0 |
0 |
255 |
|
-D[YNAMIC_SEGMENT] =segment-name (char) |
- |
1 |
16 |
|
-K[EY_SIZE]=size in bytes (integer) |
64 |
3 |
1,019 |
|
-R[ECORD_SIZE]=size in bytes (integer) |
256 |
7 |
1,048,576 (1 MiB) |
|
-N[ULL_SUBSCRIPTS]=[ALWAYS|NEVER|EXISTING] |
NEVER |
- | - |
|
-[NO]STDNULLCOLL |
N |
- | - |
|
-[NO]INST[_FREEZE_ON_ERROR] |
DISABLED |
- | - |
|
-[NO]Q[DBRUNDOWN] |
DISABLED |
- | - |
|
-[NO]J[OURNAL] [=journal-option-list] |
-NOJ | - | - |
The following -SEGMENT qualifiers can be used with the ADD, CHANGE, or TEMPLATE commands.
Specifies the access method or the GT.M buffering strategy for storing and retrieving data from the global database file.
code can have 2 values - Buffered Global (BG) or Memory Mapped (MM). The default value is BG.
-
With BG, the global buffer pool manages the buffers (the OS/file system may also provide additional buffering). You get the choice of using BEFORE_IMAGE or NOBEFORE_IMAGE journaling for your database. For details on the implications of these forms of Journaling, see Chapter 6: “GT.M Journaling”.
BG supports both forward and backward recovery and rollback to recover a database without a restore. For more information forward and backward recovery and rollback, see Chapter 5: “General Database Management”.
BG is a likely choice when you need faster recovery times from system failures.
-
With MM, GT.M bypasses the global buffer pool and relies entirely on the OS/file system to manage the data traffic between memory and disk. GT.M has no control over the timing of disk updates, therefore there is a greater reliance on the OS/file system for database performance.
MM supports NOBEFORE_IMAGE journaling only. GT.M issues an error if you use MM with BEFORE_IMAGE Journaling. MM also supports MUPIP FORWARD -RECOVER and MUPIP JOURNAL -ROLLBACK with the -RESYNC or -FETCHRESYNC qualifiers to generate lost and broken transaction files. For more information, see the Journaling and Replication chapters.
MM does not support backward recovery/rollback.
Depending on your file system, MM may be an option when you need performance advantage in situations where the above restrictions are acceptable.
GDE maintains a separate set of segment qualifier values for each ACCESS_METHOD.
When GDE modifies the ACCESS_METHOD, it activates the appropriate set of TEMPLATEs and sets all unspecified qualifiers to the default values of the new ACCESS_METHOD.
Example:
GDE> change -segment DEFAULT -access_method=MM
This command sets MM as the access method or the GT.M buffering strategy for storing and retrieving database for segment DEFAULT.
Specifies the number of blocks GT.M allocates to a disk file when MUPIP creates the file. For GDS files, the number of bytes allocated is the size of the database file header plus the ALLOCATION size times the BLOCK_SIZE.
The minimum ALLOCATION is 10 blocks.
The maximum ALLOCATION is 1,040,187,392 blocks.
By default, GDE uses an ALLOCATION of 100 blocks.
The maximum size of a database file is 1,040,187,392(992Mi) blocks.
Out of the requested allocation, GT.M always reserves 32 global buffers for BG access method for read-only use to ensure that non-dirty global buffers are always available.
The default ALLOCATION was chosen for initial development and experimentation with GT.M. Because file fragmentation impairs performance, make the initial allocation for production files and large projects large enough to hold the anticipated contents of the file for a length of time consistent with your UNIX file reorganization schedule.
Specifies the size, in bytes, of each database block in the file system. The BLOCK_SIZE must be a multiple of 512. If the BLOCK_SIZE is not a multiple of 512, GDE rounds off the BLOCK_SIZE to the next highest multiple of 512 and issues a warning message.
If the specified BLOCK_SIZE is less than the minimum, GDE uses the minimum BLOCK_SIZE. If the specified BLOCK_SIZE is greater than the maximum, GDE issues an error message.
A BLOCK_SIZE that is equal to the page size used by your UNIX implementation serves well for most applications, and is a good starting point.
You should determine the block sizes for your application through performance timing and benchmarking. In general, larger block sizes are more efficient from the perspective of the input/output subsystem. However, larger block sizes use more system resources (CPU and shared memory) and may increase collision and retry rates for transaction processing.
![[Note]](images/note.jpg) |
Note |
|---|---|
Global nodes that span blocks incur some overhead and optimum application performance is likely to be obtained from a BLOCK_SIZE that accommodates the majority of nodes within a single block. If you adjust the BLOCK_SIZE, you should also adjust GLOBAL_BUFFER_COUNT. |
GDE does not allow you to change the block size to an arbitrary number. It always rounds the block size to the next higher multiple of 512, because the database block size must always be a multiple of 512.
The minimum BLOCK_SIZE is 512 bytes.
The maximum BLOCK_SIZE is 65,024 bytes.
|
Note |
|---|---|
FIS recommends against using databases with block sizes larger than 16KiB. If a specific global variable has records that have large record sizes, FIS recommends placing that global variable in a file by itself with large block sizes and using more appropriate block sizes for other global variables. 4KiB and 8KiB are popular database block sizes. |
By default, GDE uses a BLOCK_SIZE of 1024 bytes.
Specifies whether or not the database file for a segment is flagged for encryption. Note that MUPIP CREATE acquires an encryption key for this file and puts a cryptographic hash of the key in the database file header.
Specifies the number of extra GDS blocks of disk space by which the file should extend. The extend amount is interpreted as the number of usable GDS blocks to create with the extension. To calculate the number of host operating system blocks added with each extension, multiply the number of GDS blocks added by (GDS BLOCK_SIZE/host BLOCK_SIZE); add one local bitmap block for each 512 blocks added in each extension to the amount from step 1. If the extension is not a multiple of 512, remember to roundup when figuring the number of bitmap blocks.
When a MUPIP EXTEND command does not include a -BLOCKS= qualifier, EXTEND uses the extension size in the database header.
The extension amount may be changed with the MUPIP SET command.
The minimum EXTENSION is zero blocks.
When a database file with automatic extension disabled (EXTENSION_COUNT=0) starts to get full, GT.M records the FREEBLSLOW warning in the system log. So as to not compromise performance, GT.M checks whenever the master bit map must be updated to show that a local bit map is full, and issues the warning if there are fewer than 512 free blocks or if the number of free blocks is less than total blocks/32. This means that for databases whose size is 512 blocks or less the warning comes at the last successful update before the database becomes full.
The maximum EXTENSION is 65,535 blocks.
By default, GDE uses an EXTENSION of 100 blocks.
Like allocation, the default extension amount was chosen for initial development and experimentation. Use larger extensions for larger actual applications. Because multiple file extensions adversely affect performance, set up extensions appropriate to the file allocation.
Specifies the file for a segment.
The maximum file name length is 255 characters.
By default, GDE uses a file-name of mumps followed by the default extension, which is .dat. You can specify any filename and extension of your choice for a database file as long as it is valid on your operating system.
Specifies the number of global buffers for a file. Global buffers reside in shared memory and are part of the database caching mechanisms. Global buffers do not apply to MM databases.
Choose the settings for this qualifier carefully. Small numbers of global buffers tend to throttle database performance. However, if your system has limited memory and the database file traffic is not heavy enough to hold the cache in RAM, increasing GLOBAL_BUFFER_COUNT may trigger paging.
If database global buffers are paged out, it will result in poor performance. Therefore, do not increase this factor to a large value without careful observation.
The proper number of GLOBAL_BUFFERs depends on the application and the amount of primary memory available on the system. Most production databases exhibit a direct relationship between the number of GLOBAL_BUFFERs and performance. However, the relationship is not linear, but asymptotic, so that increases past some point have progressively less benefit. This point of diminishing returns depends on the application. For most applications, FIS expects the optimum number of GLOBAL_BUFFERs to be between 1K and 64K.
Because transaction processing can be involved in an update and a transaction is limited to half the GLOBAL_BUFFER_COUNT, the value for GLOBAL_BUFFER_COUNT should therefore be at least twenty-six plus twice the number of the blocks required by the largest global variable node in your application.
Generally, you should increase the number of GLOBAL_BUFFERs for production GDS database files. This is because GT.M uses the shared memory database cache associated with each GDS file for the majority of caching.
The minimum GLOBAL_BUFFER_COUNT for BG is 64 blocks.
The maximum for GLOBAL_BUFFER_COUNT for BG is 2,147,483,647 blocks, but may vary depending on your platform.
By default, GDE uses a GLOBAL_BUFFER_COUNT that is appropriate for initial development use on each platform, but probably too small for production applications.
|
Note |
|---|---|
If global buffers are "paged out," improvements in system performance resulting from more global buffers will be more than offset by the dramatic slowdown that results from globals buffers that are "paged out." |
Specifies the number of pages of space to use for the lock database stored with this segment. The size of a page is always 512 bytes.
As GT.M runs out of space to store LOCK control information, LOCKs become progressively less efficient. If a single process consumes all the LOCK space, it cannot continue, and any other processes cannot proceed using LOCKs.
The minimum LOCK_SPACE is 10 pages.
The maximum LOCK_SPACE is 65,536 pages.
By default, GDE uses a LOCK_SPACE of 40 pages.
LOCK_SPACE usage depends on the number of locks and the number of processes waiting for locks. To estimate lock space needs, here is a rule of thumb:
1.5KiB overhead for the lock space, plus
640 bytes for each lock base name, plus
128 bytes for each subscript, plus
128 bytes for each waiting process.
Generally, you would limit LOCK_SPACE only when memory is scarce or you want to be made aware of unexpected levels of LOCK usage. For most other cases, there is no reason to limit the LOCK_SPACE. If you are introducing new code, FIS recommends using TSTART and TCOMMIT as a more efficient alternate for most LOCKs because it pushes the responsibility for Isolation onto GT.M, which internally manages them with optimistic algorithms.
Specifies the number of mutex slots for a database file. GT.M uses mutex slots to manage database contention. FIS recommends you configure the slots to cover the maximum number of processes you expect to concurrently access the database file, as an insufficient number of slots can lead to much steeper and more severe degradation of performance under heavy loads. The minimum is 1Ki and the maximum is 32Ki. The default of 1Ki should be appropriate for most situations.
Specifies the size to be reserved in each database block. RESERVED_BYTES is generally used to reserve room for compatibility with other implementations of M or to observe communications protocol restrictions. RESERVED_BYTES may also be used as a user-managed fill factor.
The minimum RESERVED_BYTES is zero bytes.
The maximum Reserved_Bytes is the block size minus the size of the block header (which is 7 or 8 depending on your platform) minus the maximum record size.
By default, GDE uses a RESERVED_BYTES size of zero bytes.
Summary
The following table summarizes GDE segment qualifiers. It provides abbreviations, defaults (as provided by FIS), and allowable minimum and maximum values.
|
GDE SEGMENT Qualifiers | |||
|---|---|---|---|
|
QUALIFIER |
DEFAULT |
MIN |
MAX |
|
** BLOCK_SIZE minus the size of the block header | |||
|
* May vary by platform | |||
|
-AC[CESS_METHOD]=BG|MM |
BG |
- |
- |
|
-AL[LOCATION]=size (blocks) |
100 |
10 |
1,040,187,392(992Mi) |
|
-BL[OCK_SIZE]=size (bytes) |
1,024 |
512 |
65,024 |
|
-[NO]EN[CRYPTION] |
0 |
||
|
-EX[TENSION_COUNT]=size (blocks) |
100 |
0 |
65,535 |
|
-F[ILE_NAME]=file-name (chars) |
mumps.dat |
- |
255 |
|
-G[LOBAL_BUFFER_COUNT]=size (blocks) |
1024* |
64 |
2,147,483,647 |
|
-L[OCK_SPACE]=size (pages) |
40 |
10 |
65536 |
|
-M[UTEX_SLOTS]=integer |
1,024 |
1,024 |
32,768 |
|
-R[ESERVED_BYTES]=size (bytes) |
0 |
0 |
block size-7 |
The following -GBLNAME qualifier can be used with the ADD, CHANGE, or TEMPLATE commands.
Specifies the collation number for a global name; a value of 0 specifies standard M collation. The first time that a GT.M processes accesses a global variable name in a database file, it determines the collation sequence as follows:
-
If a Global Variable Tree (GVT) exists (that is, global variable nodes exist, or have previously existed, even if they have been KILL'd), use the existing collation:
If there is a collation specified in the Directory Tree (DT) for that variable, use it after confirming that this matches the collation in the global directory.
-
else (that is, there is no collation specified in the DT):
If there is collation specified for that global variable in the global directory use it
else if there is a default for that database file, use it
else (that is, neither exists), use standard M collation
-
else (that is, a GVT does not exist, which in turn means there is no DT):
If there is collation specified for that global variable in the global directory use it
else, if there is a default for that database file, use it
else (that is, neither exists), use standard M collation