GT.M Programmer's Guide

GT.M Programmer’s 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

1. About GT.M

Programming Environment

Managing Source Code

Integrating GT.M with Other Languages

Access to Non-M Routines

Internationalization

2. GT.M Language Extensions

Operating System Interface Facilities

Debugging Facilities

Exception Handling Facilities

Journaling Extensions

Extensions For Additional Capability

GT.M Device Handling Extensions

Alias Variables Extensions

ZWRITE / ZSHOW “V” format

Pass-by-reference

SET * and QUIT * Examples

KILL * Examples

Annotated Alias Examples

Extensions for the support for the Unicode standard

Philosophy of GT.M’s support for the Unicode standard

Discussion and Best Practices

3. Development Cycle

Overview of the Program Development Cycle

Defining Environment Variables

Preparing the Database

Creating and Editing a Source Program

Editing from GT.M

Editing from the Shell

Compiling a Source Program

Compiling from GT.M

Compiling from the Shell

Qualifiers for the mumps command

Executing a Source Program

Executing in Direct Mode

Locating the Source File Directory

Executing from the Shell

Processing Errors from Direct Mode and Shell

4. Operating and Debugging in Direct Mode

Operating in Direct Mode

Entering Direct Mode

Functionality Available in Direct Mode

Exiting Direct Mode

Debugging a Routine in Direct Mode

Creating and Displaying M Routines

Executing M Routines Interactively

Processing with Run-time and Syntax Errors

Correcting Errors

Stepping Through a Routine

Continuing Execution From a Breakpoint

Interrupting Execution

Using the Invocation Stack in Debugging

Transferring Routine Control

Displaying Source Code

Correcting Errors in an M Routine

Relinking the Edited Routine

Re-executing the Routine

Using Forked Processes

Summary of GT.M Debugging Tools

5. General Language Features of M

Numeric Expressions

Numeric Accuracy

Integer Expressions

Truth-valued Expressions

Arrays and Subscripts

M Collation Sequences

Local Variables

Global Variables and Resource Name Environments

Naked References

Global Variable Name Environments

String Literals

Numeric Literals

Arithmetic Operators

Logical Operators

String Operators

Numeric Relational Operators

String Relational Operators

Pattern Match Operator

Postconditionals

Interrupt Handling

Intrinsic Functions

Intrinsic Special Variables

Entry References

Label References

Indirection

Argument Indirection

Atomic Indirection

Entryref Indirection

Pattern Code Indirection

Name Indirection

Indirection Concerns

Parameter Passing

Parameter Passing Operation

Parameter Passing Mechanisms

GT.M Parameter Passing Extensions

Extrinsic Functions

Extrinsic Special Variables

Transaction Processing

Key Considerations - Writing TP Code

6. Commands

Break: Examples of BREAK

Do: Examples of DO
Else: Examples of ELSE
For: Examples of FOR
Goto: Examples of GOTO

Examples of HANG

The JOB Environment

JOB Processparameters

Examples of JOB

Examples of KILL

Using Locks within Transactions: Example of LOCK
Merge: Examples of MERGE
New: Examples of NEW

Quit: Examples of QUIT

Set: Examples of SET

TStart: S[ERIAL]
T[RANSACTIONID]=expr

View: Key Words in VIEW Command
Examples of VIEW

Xecute: Examples of XECUTE
ZAllocate: Examples of ZALLOCATE
ZBreak: Examples of ZBREAK
ZCOMpile: Examples of ZCompile

ZDeallocate

Examples of ZDEALLOCATE

Examples of ZEDIT

Examples of ZGOTO

Examples of ZHALT

Examples of ZHELP

ZLINK Compilation

Examples of ZLINK

Auto-ZLINK setup

ZLINK, auto-ZLINK and Routine Names

ZMessage: Examples of ZMESSAGE
ZPrint: Examples of ZPRINT

ZSHOW Information Codes

Examples of ZSHow

ZSHOW Destination Variables

ZSTEP Interactions

Examples of ZSTEP

Examples of ZSYSTEM

Examples of ZTCOMMIT

ZWIthdraw: Examples of ZWITHDRAW
ZWRite: ZWRITE Format for Alias Variables
Examples of ZWRITE

7. Functions

$ASCII(): Examples of $ASCII()
$Char(): Examples of $CHAR()
$Data(): Examples of $DATA()
$Extract(): Examples of $EXTRACT()
$Find(): Examples of $FIND()
$FNumber(): Examples of $FNUMBER()
$Get(): Examples of $GET()
$Increment(): Examples of $INCREMENT()
$Justify(): Examples of $JUSTIFY()
$Length(): Examples of $LENGTH()
$NAme(): Examples of $NAME()

$Order(): Examples of $ORDER()
$Piece(): Examples of $PIECE()
$Qlength(): Examples of $QLENGTH()
$QSubscript(): Examples of $QSUBSCRIPT()
$Query(): Examples of $QUERY()
$Random(): Examples of $RANDOM()
$REPLACE(): Examples of $REPLACE()
$REverse(): Examples of $REVERSE()
$Select(): Examples of $SELECT()
$STack(): Examples of $STACK()
$Text(): Examples of $TEXT()
$TRanslate(): Examples of $TRANSLATE()
$View(): Argument Keywords of $VIEW()
Examples of $VIEW()

Examples of $ZASCII()

$ZATRansform

Examples of $ZATRANSFORM()

Examples of $ZAUDitlog()

$ZBIT Functions

Examples of $ZBIT Functions

Example of $ZCHAR()

$ZCOLlate()

Example of $ZCOLlate()

$ZCOnvert()

Examples of $ZCONVERT()

Examples of $ZDATA()

$ZDATE Format Specification Elements

Examples of $ZDATE()

$ZExtract()

Examples of $ZEXTRACT()

$ZJOBEXAM()

Examples of $ZJOBEXAM()

$ZJustify()

Examples of $ZJUSTIFY()

Examples of $ZLength()

$ZMessage()

Examples of $ZMESSAGE()

Examples of $ZPARSE()

Examples of $ZPIECE()

$ZREPLACE(): Examples of $ZREPLACE()

$ZSEARCH(): Examples of $ZSEARCH()
$ZSIGPROC(): Examples of $ZSIGPROC()
$ZSUBstr(): Examples of $ZSUBSTR()
$ZTRanslate(): Examples of $ZTRANSLATE()
$ZTRIgger(): Examples of $ZTRIGGER()
$ZTRNLNM(): Examples of $ZTRNLNM()
$ZWidth(): Examples of $ZWIDTH()

8. Intrinsic Special Variables

Establishing the Value from $gtmroutines

Setting a Value for $ZROutines

$ZROutines Examples

$ZROutines Search Types

$ZROutines Search Examples

Shared Library File Specification in $ZROUTINES

Triggers ISVs

9. Input/Output Processing

I/O Intrinsic Special Variables

Device Name Variables

Cursor Position Variables

Status Variables

I/O Devices

I/O Device Recognition

Device Specification Defaults

How I/O Device parameters Work

Abbreviating Deviceparameters

Document Conventions

Device-Independent Programming

Using Terminals

Setting Terminal Characteristics

Logical Records for Terminals

READ * Command for Terminals

READ X#maxlen Command for Terminals

Terminal Deviceparameter Summary

Terminal Examples

Using Sequential Files

Setting Sequential File Characteristics

Sequential File Pointers

Line Terminators

READ/WRITE Operations

Writing Binary Files

Sequential File Deviceparameter Summary

Sequential File Examples

FIFO Characteristics

Considerations in Implementing FIFOs

Error Handling for FIFOs

GT.M Recognition of FIFOs

FIFO Device Examples

FIFO Deviceparameter Summary

Using Null Devices

Null Deviceparameter Summary

Null Device Examples

Using PIPE Devices

Modes of PIPE Operation

PIPE Characteristics

PIPE Device Examples

PIPE Deviceparameter Summary

Using Socket Devices

Message Management

Socket Read Operation

Socket Read Termination Conditions

Message Delimiters

Socket Device Operation

Socket Deviceparameter Summary

Socket Device Examples

I/O Commands

Deviceparameter Summary Table

10. Utility Routines

Using the Utilities

Date and Time Utilities

Conversion Utilities

Mathematic Utilities

String Utilities

Global Utilities

Routine Utilities

Internationalization Utilities

System Management Utilities

UTF-8 Mode Utility Routines

GT.M Utilities Summary Table

11. Integrating External Routines

Access to Non-M Routines

Creating a Shareable Library

Using External Calls

Database Encryption Extensions to the GT.M External Interface

Pre-allocation of Output Parameters

Callback Mechanism

Limitations on the External Program

Examples of Using External Calls

Calls from External Routines: Call-Ins

Relevant files for Call-Ins

Call-In Interface

Building Standalone Programs

Nested Call-Ins

Rules to Follow in Call-Ins

Type Limits for Call-ins and Call-outs

12. Internationalization

Collation Sequence Definitions

Creating the Shared Library holding the alternative sequencing routines

Defining the Environment Variable

Defining a Default Database Collation Method

Establishing A Local Collation Sequence

Creating the Alternate Collation Routines

Transformation Routine (gtm_ac_xform_1 or gtm_ac_xform)

Inverse Transformation Routine (gtm_ac_xback or gtm_ac_xback_1)

Transform Utility Routine (gtm_ac_xutil)

Version Control Routines (gtm_ac_version and gtm_ac_verify)

Using the %GBLDEF Utility

Example of Upper and Lower Case Alphabetic Collation Sequence

Example of Collating Alphabets in Reverse Order using gtm_ac_xform_1 and gtm_ac_xback_1

Implementing an Alternative Collation Sequence for Unicode characters

Matching Alternative Patterns: Pattern Code Definition
Pattern Code Selection

13. Error Processing

Compile Time Error Message Format

Processing Compile Time Errors

Run-time Error Message Format

Processing Run-time Errors

Run-time Errors in Direct Mode

Run-time Errors Outside of Direct Mode

Program Handling of Errors

$ZSTATUS Content

$ZERROR and $ZYERROR

$ETRAP Behavior

Nesting $ETRAP and using $ESTACK

$ZTRAP Behavior

Differences between $ETRAP and $ZTRAP

$ZTRAP Interaction With $ETRAP

Choosing $ETRAP or $ZTRAP

Error Processing Cautions

Input/Output Errors

Error Actions

Break on an Error

Unconditional Transfer on an Error

Setting $ZTRAP for Each Level

Nested Error Handling

Terminating Execution on an Error

Setting $ZTRAP to Other Actions

Summary of $ETRAP & $ZTRAP Error-Handling Options

Errors in $ZTRAP

Recording Information about Errors

14. Triggers

Trigger Definition File

Trigger ISVs Summary

Chained and Nested Triggers

A Simple Example

Trigger Definition Storage

Trigger Invocation and Execution Semantics

Trigger Execution Environment

Error Handling during Trigger Execution

Accessing Trigger Xecute Source Code

Other Utilities

Triggers in Journaling and Database Replication

Multisite Database Replication

MUPIP Trigger and $ZTRIgger()

A. M Coding Standards - Do’s and Don’ts

M Coding Standards - Do’s and Don’ts: Do’s
Don’ts