Purpose of the Manual
About This Manual
.
Prev
|
Up
|
Next
Purpose of the Manual
The GT.M Programmer's Guide documents all aspects of programming with M in the GT.M environment.
Contents
Search
About This Manual
Intended Audience
Purpose of the Manual
How to Use This Manual
About GT.M
Programming Environment
Managing Data
Database Management Utilities
Managing Source Code
Source File Management
Programming and Debugging Facilities
The GT.M Compiler
The Run-Time System
Automatic and Incremental Linking
Error Processing
Input-Output Processing
Integrating GT.M with Other Languages
Access to Non-M Routines
Internationalization
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
Alias Variables
Alias Container Variables
Performance
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
Glyphs and Unicode® characters
ICU
Discussion and Best Practices
Data interchange
Limitations
User-defined pattern codes are not supported
String Normalization
UTF-16 is not supported for $PRINCIPAL device
UTF-16 is not supported for Terminal Devices
Error messages are in [American] English
Performance and Capacity
Characters in arguments exchanged with external routines must be validated by the external routines
Maximums
M Name Length
M String Length
M Source Line Length
Database Key and Record Sizes
Ten Golden Rules
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
-di[rect_mode]
-dy[namic_literals]
-[no]embed_source
-[no]i[gnore]
-le[ngth]=lines
-[no]li[st][=filename]
-noin[line_literals]
-[no]o[bject][=filename]
-[n]ameofrtn=filename
-[no]w[arning]
-r[un]
-s[pace]=lines
MUMPS Command Qualifiers Summary
Executing a Source Program
Executing in Direct Mode
Locating the Source File Directory
Executing from the Shell
Processing Errors from Direct Mode and Shell
Operating and Debugging in Direct Mode
Operating in Direct Mode
Entering Direct Mode
Functionality Available in Direct Mode
Command Recall
Line Editing
The M Invocation Stack
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
Determining Levels of Nesting
Looking at the Invocation Stack
Using ZSHOW to Examine Context Information
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
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
Optional GT.M Environment Translation Facility
gtm_env_xlate
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
Command Postconditionals
Argument Postconditionals
Timeouts
Interrupt Handling
M Locks
Intrinsic Functions
Intrinsic Special Variables
Routines
Lines
Labels
Comments
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
Key Considerations - Writing TP Code
TP Performance
TP Example
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 Implications for Directories
JOB Processparameters
CMD[LINE]="strlit"
DEF[AULT]=strlit
ERR[OR]=strlit
GBL[DIR]=strlit
IN[PUT]=strlit
OUT[PUT]=strlit
PASS[CURLVN]
STA[RTUP]="/path/to/shell/script"
JOB Processparameter Summary Table
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
"BREAKMSG":value
[NO]BADCHAR
"DBFLUSH"[:<region_list>[:N]]
"DBSYNC"[:<region_list>]
[NO]DMTERM
"EPOCH"[:<region_list>]
"FLUSH"[:<region_list>]
[NO]FULL_BOOL[EAN|WARN]
"GDSCERT":value
"GVSRESET":"<region>"
"GVDUPSETNOOP":value
"JNLFLUSH"[:<region_list>]
JNLWAIT
"JOBPID":"value"
"LABELS":"value"
"LINK":"[NO]RECURSIVE"
[NO]LOGN[ONTP][:intexpr]
[NO]LOGT[PRESTART][:intexpr]
LV_GCOL
LV_REHASH
[NEVER]|[NO]LVNULLSUBS
"NOISOLATION":<expr>
"PATCODE":"tablename"
"PATLOAD":"file-specification"
"POOLLIMIT":<region>:expr
RCTLDUMP
RESETGVSTATS
[NO]STATSHARE"[:<region-list>]
STP_GCOL
[NO]UNDEF
"TRACE":value:<expr>
"ZDATE_FORM":"value"
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
Auto-ZLINK setup
Auto-zlink Benefits and Example
ZLINK, auto-ZLINK and Routine Names
ZKill
ZMessage
Examples of ZMESSAGE
ZPrint
Examples of ZPRINT
ZRUPDATE
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
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()
$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()
$ZAHandle()
$ZAscii()
Examples of $ZASCII()
$ZATRansform
Examples of $ZATRANSFORM()
$ZAUditlog
Examples of $ZAUDitlog()
$ZBIT Functions
$ZBITAND()
Example of $ZBITAND()
$ZBITCOUNT()
Example of $ZBITCOUNT()
$ZBITFIND()
Examples of $ZBITFIND()
$ZBITGET()
Examples of $ZBITGET()
$ZBITLEN()
Examples of $ZBITLEN()
$ZBITNOT()
Examples of $ZBITNOT()
$ZBITOR()
Examples of $ZBITOR()
$ZBITSET()
Examples of $ZBITSET()
$ZBITSTR()
Examples of $ZBITSTR()
$ZBITXOR()
Examples of $ZBITXOR()
Examples of $ZBIT Functions
$ZCHar()
Example of $ZCHAR()
$ZCOLlate()
Example of $ZCOLlate()
$ZCOnvert()
Examples of $ZCONVERT()
$ZDATA()
Examples of $ZDATA()
$ZDate()
$ZDATE Format Specification Elements
Examples of $ZDATE()
$ZExtract()
Examples of $ZEXTRACT()
$ZFind()
Examples
$ZGetjpi()
Examples
$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()
$ZREPLACE()
Examples of $ZREPLACE()
$ZSOCKET()
$ZSYSLOG()
$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()
Intrinsic Special Variables
$Device
$ECode
$EStack
$ETrap
$Horolog
$IO
$Job
$Key
$Principal
$Quit
$Reference
$STack
$Storage
$SYstem
$Test
$TLevel
$TRestart
$X
$Y
$ZA
$ZALlocstor
$ZAUDit
$ZB
$ZCHset
$ZCLose
$ZDAteform
$ZCMdline
$ZCOmpile
$ZCstatus
$ZDirectory
$ZEDit
$ZEOf
$ZError
$ZGbldir
$ZHorolog
$ZICUver
$ZINInterrupt
$ZINTerrupt
$ZIO
$ZJob
$ZKey
$ZLevel
$ZMALLoclim
$ZMAXTPTIme
$ZMOde
$ZONLNrlbk
$ZPATNumeric
$ZPIN
$ZPOSition
$ZPOUT
$ZPROMpt
$ZQuit
$ZREalstor
$ZRELdate
$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
Linking GT.M Shared Images
Compile source (.m) files to object (.o) files
Create a shared library from object (.o) files
Establish $ZROUTINES from gtmroutines
$ZROUTINES settings for auto-relink
$ZSOurce
$ZStatus
$ZSTep
$ZSTRPllim
$ZSYstem
$ZTExit
$ZTIMeout
$ZTrap
$ZUSedstor
$ZUT
$ZVersion
$ZYERror
Triggers ISVs
$ZTDAta
$ZTDElim
$ZTLevel
$ZTNAME
$ZTOLdval
$ZTRIggerop
$ZTSlate
$ZTUPdate
$ZTVAlue
$ZTWOrmhole
Examples of Trigger ISVs
Input/Output Processing
I/O Intrinsic Special Variables
Device Name Variables
$Io
$Principal
$ZIO
$ZPIN
$ZPOUT
Cursor Position Variables
$X
$Y
Maintenance of $X and $Y
Status Variables
$Device
$Key
$ZA
$ZB
$ZEOF
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
Setting the environment variable TERM
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
Examples of OPEN
OPEN Deviceparameters
APPEND
ATTACH
CHSET
COMMAND
CONNECT
DELIMITER
EXCEPTION
EMPTERM
FFLF
FIFO
FIXED
FOLLOW
GROUP
ICHSET
IKEY
INDEPENDENT
INREWIND
IOERROR
KEY
LISTEN
MOREREADTIME
NEWVERSION
OCHSET
OKEY
OPTIONS
OUTREWIND
OWNER
PAD
PARSE
READONLY
RECORDSIZE
REWIND
SEEK=strexpr
SHELL
STDERR
STREAM
SYSTEM
TRUNCATE
UIC
VARIABLE
WORLD
WRAP
WRITEONLY
ZBFSIZE
ZDELAY
ZFF
ZIBFSIZE
OPEN Deviceparameter Table
Use
USE Deviceparameters
ATTACH
CANONICAL
CENABLE
CLEARSCREEN
CONNECT
CONVERT
CTRAP
DELIMITER
DETACH
DOWNSCROLL
ECHO
EDITING
EMPTERM
ERASELINE
ESCAPE
EXCEPTION
FFLF
FILTER
FOLLOW
HOSTSYNC
HUPENABLE
IKEY
INREWIND
INSEEK=strexpr
INSERT
IOERROR
KEY
LENGTH
LISTEN
OKEY
OPTIONS
OUTREWIND
OUTSEEK=strexpr
PASTHRU
READSYNC
REWIND
SEEK=strexpr
SOCKET
TERMINATOR
TRUNCATE
TTSYNC
TYPEAHEAD
UPSCROLL
WIDTH
WRAP
X
Y
ZBFSIZE
ZDELAY
ZFF
ZIBFSIZE
USE Deviceparameters Summary
READ
READ * Command
READ X#maxlen Command
Write
WRITE *
Close
CLOSE Deviceparameters
DELETE
DESTROY
EXCEPTION
GROUP
OWNER
RENAME
REPLACE
SOCKET
SYSTEM
TIMEOUT
UIC
WORLD
CLOSE Deviceparameters Table
Deviceparameter Summary Table
Utility Routines
Using the Utilities
Date and Time Utilities
%D
Utility Labels
Output Variables
Examples of %D
%DATE
Utility Labels
Prompts
Input Variables
Output Variables
Date Input Formats Table
Examples of %DATE
%H
Utility Labels
Input Variables
Output Variables
Examples of %H
%T
Utility Labels
Output Variables
Examples of %T
%TI
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %TI
%TO
Utility Labels
Input Variables
Output Variables
Examples of %TO
Conversion Utilities
%DH
Utility Labels
Input Variables
Prompts
Output Variables
Examples of %DH
%DO
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %DO
%HD
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %HD
%HO
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %HO
%JSWRITE
The fis-gtm-jswrite.tar.gz npm package
Overview
Installation
Dynamic Journal File Progress Bar
Journal File Chain Report
Global Buffer Dashboard
^%YGBLSTAT Sparkline Charts
^%YGBLSTAT to JSON
JSWRITE Utility Class
Getter Method
Other Methods
%LCASE
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %LCASE
%OD
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %OD
%OH
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %OH
%UCASE
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %UCASE
Mathematic Utilities
%EXP
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %EXP
%SQROOT
Utility Labels
Prompts
Input Variables
Output Variables
Examples of %SQROOT
String Utilities
%TRIM
%MPIECE
Global Utilities
%G
Prompts
Examples of %G
%GC
Prompts
Examples of %GC
%GCE
Utility Labels
Prompts
Examples of %GCE
%GD
Prompts
Examples of %GD
%GED
Prompts
Examples of %GED
%GI
Prompts
Examples of %GI
%GO
Prompts
Examples of %GO
%GSE
Prompts
Utility Labels
Examples of %GSE
%GSEL
Utility Labels
Output Variables
Prompts
Examples of %GSEL
%ZSHOWVTOLCL
Input Variables
Routine Utilities
%FL
Prompts
Examples of %FL
%RANDSTR
%RCE
Prompts
Utility Labels
Input Variables
Examples of %RCE
%RD
Prompts
Utility Labels
Examples of %RD
%RI
Prompts
Examples of %RI
%RO
Prompts
Utility Labels
Input Variables
Examples of %RO
%RSE
Prompts
Utility Labels
Input Variables
Examples of %RSE
%RSEL
Prompts
Utility Labels
Input Variables
Output Variables
Examples of %RSEL
Internationalization Utilities
%GBLDEF
Utility Labels
Input Variables
%LCLCOL
Utility Labels
Input Variables
%PATCODE
Utility Labels
Input Variables
System Management Utilities
%DUMPFHEAD
%FREECNT
%XCMD
%PEEKBYNAME()
%YGBLSTAT()
UTF-8 Mode Utility Routines
%UTF2HEX
%HEX2UTF
GT.M Utilities Summary Table
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
gtmxc_types.h
Call-In Table
Call-In Interface
Initialize GT.M
Call an M Routine from C
gtm_cip
gtm_ci
Example: Calling GT.M from a C Program
Print Error Messages
Exit from GT.M
Building Standalone Programs
IBM pSeries (RS/6000) AIX
X86 GNU/Linux
Nested Call-Ins
Rules to Follow in Call-Ins
Type Limits for Call-ins and Call-outs
Internationalization
Collation Sequence Definitions
Creating the Shared Library holding the alternative sequencing routines
Defining the Environment Variable
Considerations in Establishing Alternative Collations
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)
Input Arguments for gtm_ac_xform1
Output Arguments for gtm_ac_xform1
Input Arguments for gtm_ac_xform
Output Arguments for gtm_ac_xform
Transformation Routine Characteristics
Inverse Transformation Routine (gtm_ac_xback or gtm_ac_xback_1)
Transform Utility Routine (gtm_ac_xutil)
Input Arguments
Output Arguments
Version Control Routines (gtm_ac_version and gtm_ac_verify)
Version Identifier Routine (gtm_ac_version)
Verification Routine (gtm_ac_verify)
Using the %GBLDEF Utility
Assigning the Collation Sequence
Examining Global Collation Characteristics
Deleting Global Collation Characteristics
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
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
Example 1: Returning control to a specific execution level
Example 2: Ignoring an Error
Example 3: Nested Error Handlers
Example 4: Access to "cause of error"
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
Program to Record Information on an Error using $ZTRAP
Triggers
Triggers
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
Accessing Trigger Xecute Source Code
GT.CM
Other Utilities
Triggers in Journaling and Database Replication
Journaling
MUPIP JOURNAL -RECOVER / -ROLLBACK
Multisite Database Replication
Replicating to an instance with a different trigger configuration
Replicating to an instance that does not support triggers
Update & Helper Processes
MUPIP Trigger and $ZTRIgger()
M Coding Standards - Do's and Don'ts
M Coding Standards - Do's and Don'ts
Do's
Don'ts
Search
