The following /NAME qualifier can be used with the ADD or CHANGE commands.

/REGION=region-name Applies to: BG MM

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 16 alphanumeric characters.

Example:

DE> ADD /NAME A* /REGION=AREG

This command creates the NAME-space A* if it does not exist, and maps it to the region AREG.

The following /REGION qualifiers can be used with the ADD, CHANGE, or TEMPLATE commands.

/C[OLLATION_SEQUENCE]=id number Applies to: BG MM

The minimum COLLATION_SEQUENCE ID number is zero, which is the standard M collation sequence.

/COLLATION_SEQUENCE=ID number specifies the number of the collation sequence definition to be used as the default for this database file. The number can be any integer between zero (0) and 255. The number you assign as a value must match the number of a defined collation sequence that resides in the executable image pointed to by the logical name GTM_COLLATE_n. For information on defining this logical name and creating an alternative collation sequence, refer to the "Internationalization" chapter in the GT.M Programmer's Guide.

The maximum COLLATION_SEQUENCE ID number is 255.

By default, GDE uses zero (0) as the COLLATION_SEQUENCE ID.

/D[YNAMIC_SEGMENT]=segment-name Applies to: BG MM

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 16 alphanumeric characters.

/K[EY_SIZE]=size in bytes Applies to: BG MM

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 255 bytes.

By default, GDE uses a KEY_SIZE of 64 bytes.

/R[ECORD_SIZE]=size in bytes Applies to: BG MM

Specifies the maximum RECORD_SIZE, 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.

If the RECORD_SIZE is greater than the BLOCK_SIZE minus the number of reserved bytes, minus the size of the record header (7 or 8 bytes, depending on your platform), GDE issues an error message.

The minimum RECORD_SIZE is seven or eight, depending on your platform.

The maximum RECORD_SIZE is 32,767 bytes.

By default, GDE uses a RECORD_SIZE of 256 bytes.

/[NO]N[ULL_SUBSCRIPTS] Applies to: BG MM

Indicates whether GT.M allows null subscripts for global variables stored in the region (i.e., whether GT.M permits references such as ^aaa("",1)).

By default, regions have /NONULL_SUBSCRIPTS.

/[NO]J[OURNAL][=journal-option-list] Applies to: BG MM

Specifies whether the database file allows journaling. If it does, this qualifier establishes characteristics for the journal file.

/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 ( ). If the list contains only one keyword, the parentheses 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.

/[NO]BE[FORE_IMAGE] Applies to: BG MM

[NO]BEFORE_IMAGE controls whether the journal should capture before images of information that an update is about to modify.

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, see Chapter 6: “GT.M Journaling”.

/F[ILE_NAME]=file-specification Applies to: BG MM

Specifies the name of the journal file.

The name 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-specification.

By default, GDE uses a journal file extension of .MJL.

/A[LLOCATION]=blocks Applies to: BG MM

ALLOCATION=blocks specifies the initial size of the journal file in RMS blocks. The default ALLOCATION was chosen for small development projects. Because frequent journal file extensions degrade run-time performance, make journal file ALLOCATION ample for a production database file.

When you change the ALLOCATION and do not also specify EXTENSION, the EXTENSION automatically changes to equal the ALLOCATION.

The minimum allocation is 10 blocks.

The maximum allocation is 16777216 blocks.

By default, GDE uses an allocation of 100 blocks.

/E[XTENSION]=blocks Applies to: BG MM

EXTENSION=blocks specifies the size by which a journal file extends when it becomes full. EXTENSION=0 prevents automatic journal file extension. The default EXTENSION amount was chosen for small development projects. Use larger extensions for larger files. Because frequent journal file extensions degrade run-time performance, make the journal file EXTENSION ample for a production database file.

When you change the ALLOCATION and do not also specify EXTENSION, the EXTENSION automatically changes to equal the ALLOCATION.

The minimum EXTENSION is zero blocks.

The maximum EXTENSION is 65535 blocks.

By default, GDE uses an EXTENSION of 100 blocks.

/BU[FFER_SIZE]=pages Applies to: BG MM

BUFFER_SIZE=pages specifies the amount of memory used to buffer journal file output. A larger BUFFER_SIZE usually smooths and improves run-time performance.

A larger BUFFER_SIZE requires more memory resources, which may be scarce.

The minimum BUFFER_SIZE is enough 512-byte pages to hold two GDS database blocks.

The maximum BUFFER_SIZE is 2000 pages.

By default, GDE uses a BUFFER_SIZE of 128 pages.

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

/AC[CESS_METHOD]=code Applies to: BG MM

Specifies the access method or the GT.M buffering strategy for storing and retrieving data from the global database file.

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.

/BL[OCK_SIZE]=size Applies to: BG MM

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.

By default, GDE uses a BLOCK_SIZE of 1024 bytes for BG and MM files.

/[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 Applies to: BG MM

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.

BG files may extend automatically when the file is full. A zero extension size prevents a BG file from automatically extending. GDS files may be extended with MUPIP EXTEND, even when there are other processes accessing the database.

MM files must be extended with MUPIP EXTEND when there is no process accessing the database.

The extension amount may be changed with the MUPIP SET command. To force explicit expansion for BG files with MUPIP EXTEND, set /EXTENSION_COUNT to zero.

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-spec Applies to BG MM

Specifies the file for a segment.

GT.M allows full file-specifications and logical names. Note that if the file specification is a search list, the first file in the list is used and all others are ignored. GT.M allows the use of logical names in the filename.

The maximum file name length is 255 characters.

By default, GDE uses a file-name of MUMPS and a .DAT file extension.

	Database and journal files that have a large number of extensions may require unexpectedly large values of the BYTLM quota. Refer to the "Installing GT.M" chapter for more information.

/G[LOBAL_BUFFER_COUNT]=size Applies to: BG MM

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

The maximum number of database blocks that can be modified by a transaction is half the number of global buffers. In practice, few applications are expected to have such large transactions that can degrade performance.

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.

Values under 250 are not recommended, even for development.

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.

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

/NO]D[EFER] Applies to: MM

Instructs GT.M whether or not to store updates on the disk immediately.

DEFER has a significant performance benefit for database files that are heavily updated. However, DEFER should only be used for segments files, (such as those containing temporary storage for reports) that can be recreated if the system crashes.

By default, GDE makes MM database files /DEFER.

/L[OCK_SPACE]=pages Applies to: BG MM

Specifies the number of pages of space to use for the lock database stored with this segment. If GT.M runs out of space to store locks, LOCKS become somewhat less efficient. If the process accumulates locks and does not release them, it will deadlock at a point that is a function of the LOCK_SPACE.

The minimum LOCK_SPACE is 10 pages.

The maximum LOCK_SPACE is 64K pages for BG and 1,000 pages for MM.

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:

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 Applies to: BG MM

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.