Name, Region, and Segment Qualifiers

GDE -JOURNAL Option List
QUALIFIER	DEFAULT	MINIMUM	MAXIMUM
-C[OLLATION_SEQUENCE]=id-number (integer)	0	0	255
-D[YNAMIC_SEGMENT] =segment-name (char)	-	1	16
-K[EY_SIZE]=size in bytes (integer)	64	3	255
-R[ECORD_SIZE]=size in bytes (integer)	256	7	block_size - block_header_size - reserved_bytes where block_header_size is 16 bytes.
-N[ULL_SUBSCRIPTS]=[ALWAYS\|NEVER\|EXISTING]	NEVER	-	-
-[NO]STDNULLCOLL[=TRUE\|FALSE]	FALSE	-	-
-[NO]J[OURNAL] [=journal-option-list]	-	-	-

JOL Summary

With GDE, you can create the journal files and define the journal parameters; however, you must use MUPIP SET to actually enable journaling.

For information on all Journal options and their allowable minimum and maximum values, see Chapter 6: “GT.M Journaling”.

Segment Qualifiers

The following -SEGMENT qualifiers can be used with the ADD, CHANGE, or TEMPLATE commands.

-AC[CESS_METHOD]=code

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 triggers 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 chapter.
- MM does not support backward recovery/rollback.
- MM is a possible choice 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.

-AL[LOCATION]=blocks

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 200 blocks.
The maximum ALLOCATION is 8388607 (4GB-512 bytes, the maximum journal file size) blocks.
By default, GDE uses an ALLOCATION of 2048 blocks.
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.

-BL[OCK_SIZE]=size

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.

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 16KB. 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. 4KB and 8KB are popular database block sizes.

By default, GDE uses a BLOCK_SIZE of 1024 bytes.

-[NO]ENcryption

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.

-EX[TENSION_COUNT]=blocks

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.

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 with GT.M projects. Use larger extensions for larger files. Because multiple file extensions adversely affect performance, set up extensions appropriate to the file allocation.

-F[ILE_NAME]=file-name

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.

-G[LOBAL_BUFFER_COUNT]=size

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 memory, increasing GLOBAL_BUFFER_COUNT may trigger paging.

If database global buffers are paged out, it may 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.

Generally, you should increase the number of GLOBAL_BUFFERs for production GDS databases. This is because GT.M uses the shared memory database cache associated with each GDS file for the majority of caching.

The minimum for BG is 64 blocks.

The maximum for BG is normally 65,536 blocks, but may vary depending on your platform.

By default, GDE uses a GLOBAL_BUFFER_COUNT that is appropriate for the typical size of the platform. The most common value is 1024 blocks. Increases above the default for your platform may require modifications to your UNIX kernel configuration.

	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."

-L[OCK_SPACE]=integer

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.5KB 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 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.

-R[ESERVED_BYTES]=size

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)	2048	200	8,388,607 (4GB-512 bytes, the maximum journal file size)
-BL[OCK_SIZE]=size (bytes)	1024	512	65024
-[NO]EN[CRYPTION]	0
-EX[TENSION_COUNT]=size (blocks)	2048	0	1073741823 (one less than 1 giga) blocks
-F[ILE_NAME]=file-name (chars)	mumps.dat	-	255
-G[LOBAL_BUFFER_COUNT]=size (buffers)	1024*	64	4096
-L[OCK_SPACE]=size (pages)	40	10	65536
-R[ESERVED_BYTES]=size (bytes)	0	0	block size-7

Prev	Up	Next
	Home

Name, Region, and Segment QualifiersChapter 4. Global Directory Editor

Name, Region, and Segment Qualifiers

Name Qualifiers

Region Qualifiers

Segment Qualifiers

Name, Region, and Segment Qualifiers
Chapter 4. Global Directory Editor