GT.M Administration and Operations Guide

GT.M Administration and Operations Guide

Copyright 2011-2023 Fidelity National Information Services, Inc. and/or its subsidiaries. All rights reserved.

April09,2026

Table of Contents

About This Manual

Intended Audience

Purpose of the Manual

How to Use This Manual

Revision History

Conventions Used in This Manual

1. About GT.M

Hardware/Operating System Environment

Program Development Environment

Database Subsystem

GT.M Utility Programs

Command Qualifiers

Database Integrity

Interprocess Communication

2. Installing GT.M

Obtaining GT.M Distribution Media

Before you begin

Installation Procedure: Compiling the Reference Implementation Plugin

gtminstall script

3. Basic Operations

GT.M Environment Setup

Environment Variables

Configuring and operating GT.M with Unicode support (optional): M mode and UTF-8 mode
Compiling ICU

Configuring huge pages for GT.M x86[-64] on Linux: Using huge pages
Configuring the Restriction facility: ZSYSTEM and PIPE OPEN command restriction facility
Audit Logging facility

4. Global Directory Editor

Global Directory

GDE Overview

Identifying the Current Global Directory

Creating a Default Global Directory

Mapping Global Variables in a Global Directory

Examining the Default Global Directory

Global Directory Abbreviations

Customizing a Global Directory

Guidelines for Mapping

Global Director Editor Commands

Specifying File Names in Command Lines

Font/Capitalization Conventions Used in this Chapter

Name, Region, and Segment Qualifiers

Name Qualifiers

Region Qualifiers

Segment Qualifiers

Gblname Qualifiers

Instance Qualifier

GDE Command Summary

GDE Command Qualifier Summary

5. General Database Management

Introduction

Operations - Standalone and Concurrent Access

Commands and Qualifiers

MUPIP Command Summary

6. GT.M Journaling

Introduction

Recovery from a Journal File

rolled_bak* files

Journal Files Access Authorization

Triggers in Journal Files

BEFORE_IMAGE Journaling

NOBEFORE_IMAGE Journaling

Choosing between BEFORE_IMAGE and NOBEFORE_IMAGE

Broken Transaction File

Lost Transaction File

Journaling Benefits

Backup Journal Files

Select database files for Journaling

Fencing Transactions

Deciding Whether to Use Fencing

$VIEW() Keywords

SET Object Identifying Qualifiers

SET Action Qualifiers

Examples for MUPIP SET

Journal Action Qualifiers

Journal Direction Qualifiers

Journal Time Qualifiers

Journal Sequence Number Qualifiers

Journal Control Qualifiers

Journal Selection Qualifiers

Journal Extract Formats

7. Database Replication

Introduction

Database Transaction Number

Journal Sequence Number

Stream Sequence Number

Instance Bound Global Directories

Limitations - SI Replication

Replication Architecture

Implementing Replication and Recovery

Application Architecture

System Requirements

Instance Freeze

TLS/SSL Replication

Network Link between Systems

Choosing between BEFORE_IMAGE and NOBEFORE_IMAGE journaling

Database Repair

Download Replication Examples

Setting up an A→B replication configuration with empty databases

Setting up an A→B→C replication configuration with empty databases

Setting up an A→P replication configuration with empty databases

Replicating Instance Starts from Backup of Originating Instance (A→B and A→P )

Switchover possibilities in an A→B replication configuration

Switchover possibilities in a B←A→P replication configuration

Switchover possibilities in a B←A→P→Q replication configuration

Changing the global directory in an A→B replication configuration

Rolling Software Upgrade

Shutting down an instance

Creating a new Replication Instance File

Setting up a secured TLS replication connection

Schema Change Filters

Recovering from the replication WAS_ON state

Rollback data from crashed (idle) regions

Setting up a new replicating instance of an originating instance (A→B, P→Q, or A→P)

Replacing the replication instance file of a replicating instance (A→B and P→Q)

Replacing the replication instance file of a replicating instance (A→P)

Setting up a new replicating instance from a backup of the originating instance (A→P)

Setting up an A→P configuration for the first time if P is an existing instance (having its own set of updates)

Commands and Qualifiers

Turning Replication On/Off

Creating the Replication Instance File

Displaying/Changing the attributes of Replication Instance File and Journal Pool

Starting the Source Server

Shutting down the Source Server

Activating a Passive Source Server

Deactivating an Active Source Server

Stopping the Source Filter

Stopping the Receiver Filter

Freezing an Instance

Checking Server Health

Changing the Log File

Enabling/Disabling Detailed Logging

Reporting the Current Backlog of Journal Records

Processing Lost Transactions File

Starting the Receiver Server

Starting the Update Process

Stopping the Receiver Server and/or the Update Process

Checking Server Health

Changing the Log File

Enabling/Disabling Detailed Logging

Reporting the Current Backlog of Journal Records

Rolling Back a Replicated Database

8. M Lock Utility (LKE)

Introduction

To Invoke and Exit LKE

To establish a Global Directory

LKE Commands and Qualifiers

LKE Exercises: Exercise 1: Preventing concurrent updates using M Locks
Exercise 2: Rectifying a deadlock situation

9. GT.M Database Structure(GDS)

Database File Organization with GDS: Database File Header
File Header Data Elements

Database Structure

Tree Organization

Compression Count

Characteristics of Keys

Global Variable Names

String Subscripts

Numeric Subscripts

10. Database Structure Editor

Operating in DSE

DSE Commands and Qualifiers

DSE Command Summary

11. Maintaining Database Integrity

Verifying Database Integrity

Regularly Scheduled Verification

Before or After Major Transfers

Immediately after Catastrophic Events

Immediately after Run-Time Database Errors

Immediately After Database Repairs

Approaches to Database Recovery

Recover from Journals

Restore from Backup

Repair with DSE

Preventive Maintenance

Repairing the Database with DSE

Using the Proper Database File

Locating Structures with DSE

Safety in Repairs

Discarding Data

Concurrent Repairs

Terminating Processes

Recovering data from damaged binary extracts

Finding and Fixing Database Errors

C1–Possible Cache Control Problems

H1–Process Hangs

H3–Database Access Problems

H4–Database Cache Problems

H5–Critical Section Problems

H6–UNIX Problems

H7–Disk Hardware Problems

H8–Application Problems

I1–MUPIP INTEG Errors

MUPIP INTEG Error Classification Table

I2–GT.M Version Mismatch

I3–File Header Errors

I4–File Size Errors

I5–More Database Access Problems

I6–Transient Errors

I7–Database Rundown Problem

I8–Repair-Induced Problems

K2–Keys Misplaced

K3–Block Doubly Allocated

K4–Pointer Problems

K5–Star Key Problems

K6–Compression Count Error

K7–Key Warning

M1–Bitmap Errors

M2–Bitmap Header Problems

O2–Record Errors

O3–Data Block Errors

O4–Salvage of Data Blocks with Lost Indices

O5–Salvage of a damaged spanning node

O6–Block Size Errors

P1–Process Damage

Q1–Restricting Database Access

R1–GT.M Run-Time Errors

R2–Structural Database Integrity Errors

Run-Time Database Restart Codes

R3–Run-time Database Cache Problems

R4–Stopped Processes

R5–No More Room in the File

R6–GTMASSERT and GTMCHECK Errors

R7–Interlocked Queue Hardware Problems

R8–Database Tree Maximum Level Exceeded

R9–Read-only Process Blocked

12. Database Encryption

Introduction

Limitations of GT.M Database Encryption

Alternatives to Database Encryption

Theory of Operation

Definition of Terms

Examples of use

Tested Reference Implementations

Special note - GNU Privacy Guard and Agents: Using the reference implementation’s custom pinentry program

Administration and Operation of Encrypted Databases

Utility Programs

Changing the Encryption Keys

Encrypted Database Creation

Plugin Architecture & Interface

Extensions to the GT.M External Interface

Using the Reference Implementation with Older Releases

13. GT.CM Client/Server

GT.CM Server Startup and Shutdown

Types of Operations

A. GT.M’s IPC Resource Usage

Examining GT.M’s IPC Resources

B. Monitoring GT.M

Monitoring GT.M Messages

Managing core dumps

C. Building Encryption Libraries

Building Encryption Libraries: Debian, Ubuntu, RedHat and Fedora
IBM AIX 7.1 (pSeries)

D. GT.M Security Philosophy

Philosophy: Normal User and Group Id Rule
Recommendations

gtmsecshr commands

Shared Resource Authorization Permissions

E. GTMPCAT - GT.M Process/Core Analysis Tool

Interactive Mode

F. Packaging GT.M Applications

Setting up a Captive User Application with GT.M: Sample .profile

Invoking GT.M through a C main() program

Defensive Practices

G. Creating a $gtmcrypt_config file

Why do we need a $gtmcrypt_config file?

Configuration File Version 2

Plugins Configuration

File Encryption

Database Key Management

Annotated Example Configuration

OpenSSL Options

Generating demo TLS certificates

Creating a demo CA (Certification Authority)

Creating and signing demo leaf-level certificates

Example: Creating demo certificates

H. V6 to V7 DB Upgrade

Database Upgrade Matrix