GT.M Programmer's Guide

Legal Notice

August 28, 2014

Revision History
Revision V6.1-000 28 August 2014

Updated for V6.1-000. For chapter-specific revisions, refer to Chapter 2: “GT.M Language Extensions, Chapter 6: “Commands, Chapter 7: “Functions, Chapter 8: “Intrinsic Special Variables, Chapter 9: “Input/Output Processing, and Chapter 11: “Integrating External Routines.

Revision V6.0-003 24 February 2014

Updated for V6.0-002 and V6.0-003. For chapter-specific revisions, refer to Chapter 3, Development Cycle, Chapter 6: “Commands, Chapter 7: “Functions, Chapter 8: “Intrinsic Special Variables, Chapter 9: “Input/Output Processing, Chapter 11: “Integrating External Routines and Chapter 13: “Error Processing.

Revision V6.0-001 21 March 2013

Updated for V6.0-001. For chapter-specific revisions, refer to Chapter 3, Development Cycle, Chapter 5: “General Language Features of M, Chapter 6: “Commands, Chapter 7: “Functions, Chapter 9: “Input/Output Processing, Chapter 10: “Utility Routines, Chapter 11: “Integrating External Routines, and Chapter 13: “Error Processing.

Revision V6.0-000 19 November 2012

Updated for V6.0-000. For chapter-specific revisions, refer to Chapter 6: “Commands and Chapter 9: “Input/Output Processing.

Revision V5.5-000/2 31 October 2012
Revision V5.5-000/1 05 October 2012
Revision V5.5-000 15 June 2012
Revision V5.4-002B 26 December 2011 Conversion to documentation revision history reflecting GT.M releases with revision history for each chapter.

Table of Contents

About This Manual
Intended Audience
Purpose of the Manual
How to Use This Manual
Conventions Used in This Manual
1. About GT.M
Programming Environment
Managing Data
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
Definitions
Performance
ZWRITE / ZSHOW "V" format
Pass-by-reference
SET * and QUIT * Examples
KILL * Examples
Annotated Alias Examples
Extensions for Unicode™ support
Philosophy of GT.M Unicode Support
ICU
Discussion and Best Practices
3. Development Cycle
Overview of the Program Development Cycle
Defining Environment Variables
gtm_dist
gtmgbldir
gtm_principal
gtmroutines
Editor
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 MCreate Edit 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
Data Types
Numeric Expressions
Numeric Accuracy
Integer Expressions
Truth-valued Expressions
M Names
Variables
Arrays and Subscripts
M Collation Sequences
Local Variables
Global Variables and Resource Name Environments
Naked References
Global Variable Name Environments
Literals
String Literals
Numeric Literals
Expressions
Operators
Precedence
Arithmetic Operators
Logical Operators
String Operators
Numeric Relational Operators
String Relational Operators
Pattern Match Operator
Commands
Postconditionals
Timeouts
M Locks
Intrinsic Functions
Intrinsic Special Variables
Routines
Lines
Entry References
Label References
Indirection
Argument Indirection
Atomic Indirection
Entryref Indirection
Pattern Code Indirection
Name Indirection
Indirection Concerns
Parameter Passing
Actuallists
Actualnames
Formallists
Formallabel
Parameter Passing Operation
Parameter Passing Mechanisms
GT.M Parameter Passing Extensions
External Calls
Extrinsic Functions
Extrinsic Special Variables
Transaction Processing
TP Definitions
TP Characteristics
TP Performance
TP Example
6. Commands
Break
Examples of BREAK
Close
Do
Examples of DO
Else
Examples of ELSE
For
Examples of FOR
Goto
Examples of GOTO
Halt
Hang
Examples of HANG
If
Examples of If
Job
The JOB Environment
JOB Processparameters
Examples of JOB
Kill
Examples of KILL
Lock
Using Locks within Transactions
Example of LOCK
Merge
Examples of MERGE
New
Examples of NEW
Open
Quit
Examples of QUIT
Read
Set
Examples of SET
TCommit
TREstart
TROllback
TStart
S[ERIAL]
T[RANSACTIONID]=expr
Use
View
Key Words in VIEW Command
Examples of VIEW
Write
Xecute
Examples of XECUTE
ZAllocate
Examples of ZALLOCATE
ZBreak
Examples of ZBREAK
ZCOMpile
Examples of ZCompile
ZContinue
ZDeallocate
Examples of ZDEALLOCATE
ZEDit
Examples of ZEDIT
ZGoto
Examples of ZGOTO
ZHALT
Examples of ZHALT
ZHelp
Examples of ZHELP
ZLink
ZLINK Compilation
Examples of ZLINK
Auto-ZLINK
ZLINK, auto-ZLINK and Routine Names
ZKill
ZMessage
Examples of ZMESSAGE
ZPrint
Examples of ZPRINT
ZSHow
ZSHOW Information Codes
Examples of ZSHow
ZSHOW Destination Variables
Use of ZSHOW
ZSTep
ZSTEP Into
ZSTep OUtof
ZSTep OVer
ZSTEP Actions
ZSTEP Interactions
Use of ZSTEP
Examples of ZSTEP
ZSYstem
Examples of ZSYSTEM
ZTCommit
Examples of ZTCOMMIT
ZTRigger
ZTStart
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()
$Next()
$Order()
Examples of $ORDER()
$Piece()
Examples of $PIECE()
$Qlength()
Examples of $QLENGTH()
$QSubscript()
Examples of $QSUBSCRIPT()
$Query()
Examples of $QUERY()
$Random()
Examples of $RANDOM()
$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()
$ZAHandle()
$ZBIT Functions
$ZBITAND()
$ZBITCOUNT()
$ZBITFIND()
$ZBITGET()
$ZBITLEN()
$ZBITNOT()
$ZBITOR()
$ZBITSET()
$ZBITSTR()
$ZBITXOR()
Examples of $ZBIT Functions
$ZAscii()
Examples of $ZASCII()
$ZCHar()
Example of $ZCHAR()
$ZCOnvert()
Examples of $ZCONVERT()
$ZDATA()
Examples of $ZDATA()
$ZDate()
$ZDATE Format Specification Elements
Examples of $ZDATE()
$ZExtract()
Examples of $ZEXTRACT()
$ZFind()
Examples
$ZGetjpi()
$ZJOBEXAM()
Examples of $ZJOBEXAM()
$ZJustify()
Examples of $ZJUSTIFY()
$ZLength()
Examples of $ZLength()
$ZMessage()
Examples of $ZMESSAGE()
$ZPARSE()
Examples of $ZPARSE()
$ZPiece()
Examples of $ZPIECE()
$ZPEEK()
$ZPrevious()
$ZQGBLMOD()
$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()
$ZWRite()
8. Intrinsic Special Variables
$Device
$ECode
$EStack
$ETrap
$Horolog
$IO
$Job
$Key
$Principal
$Quit
$Reference
$STack
$Storage
$SYstem
$Test
$TLevel
$TRestart
$X
$Y
$ZA
$ZALlocstor
$ZB
$ZCHset
$ZCMdline
$ZCOmpile
$ZCstatus
$ZCLose
$ZDAteform
$ZDirectory
$ZEDit
$ZEOf
$ZError
$ZGbldir
$ZINTerrupt
Interrupt Handling
$ZINInterrupt
$ZIO
$ZJob
$ZKey
$ZLevel
$ZMAXTPTIme
$ZMOde
$ZONLNrlbk
$ZPATNumeric
$ZPOSition
$ZPROMpt
$ZREalstor
$ZROutines
Establishing the Value from $gtmroutines
Setting a Value for $ZROutines
$ZROutines Examples
$ZROutines Search Types
$ZROutines Search Examples
Shared Library File Specification in $ZROUTINES
$ZSOurce
$ZStatus
$ZSTep
$ZSYstem
$ZTExit
$ZTrap
$ZUSedstor
$ZVersion
$ZYERror
Triggers ISVs
$ZTDAta
$ZTLevel
$ZTNAME
$ZTOLdval
$ZTRIggerop
$ZTSlate
$ZTUPdate
$ZTVAlue
$ZTWOrmhole
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
Read Command
WRITE Command
Socket Device Operation
Socket Deviceparameter Summary
Socket Device Examples
I/O Commands
Open
Use
READ
Write
WRITE *
Close
Deviceparameter Summary Table
10. Utility Routines
Using the Utilities
Date and Time Utilities
%D
%DATE
%H
%T
%TI
%TO
Conversion Utilities
%DH
%DO
%HD
%HO
%LCASE
%OD
%OH
%UCASE
Mathematic Utilities
%EXP
%SQROOT
String Utilities
%TRIM
%MPIECE
Global Utilities
%G
%GC
%GCE
%GD
%GED
%GI
%GO
%GSE
%GSEL
Routine Utilities
%FL
%RANDSTR
%RCE
%RD
%RI
%RO
%RSE
%RSEL
Internationalization Utilities
System Management Utilities
%DSEWRAP
%FREECNT
%XCMD
Unicode Utility Routines
%UTF2HEX
%HEX2UTF
GT.M Utilities Summary Table
11. Integrating External Routines
Introduction
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)
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
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
$ECODE
$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
Overview
Trigger Definition File
Trigger ISVs Summary
Chained and Nested Triggers
A Simple Example
Trigger Definition Storage
Trigger Invocation and Execution Semantics
Kill / ZKill
Set
Trigger Execution Environment
Error Handling during Trigger Execution
ZGoto
GT.CM
Other Utilities
Triggers in Journaling and Database Replication
Journaling
Multisite Database Replication
MUPIP Trigger and $ZTRIgger()
Index