GT.M Programmer's Guide

Home | Frameless version | Revision History

GT.M Programmer’s Guide 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 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 the support for the Unicode standard : Philosophy of GT.M’s support for the Unicode standard 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 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 : 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 Interrupt Handling 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 Key Considerations - Writing TP Code 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 Auto-ZLINK setup 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 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() $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() $ZBITCOUNT() $ZBITFIND() $ZBITGET() $ZBITLEN() $ZBITNOT() $ZBITOR() $ZBITSET() $ZBITSTR() $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() 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 $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 $ZSOurce $ZStatus $ZSTep $ZSTRPllim $ZSYstem $ZTExit $ZTIMeout $ZTrap $ZUSedstor $ZUT $ZVersion $ZYERror Triggers ISVs : $ZTDAta $ZTDElim $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 %JSWRITE %LCASE %OD %OH %UCASE Mathematic Utilities : %EXP %SQROOT String Utilities : %TRIM %MPIECE Global Utilities : %G %GC %GCE %GD %GED %GI %GO %GSE %GSEL %ZSHOWVTOLCL Routine Utilities : %FL %RANDSTR %RCE %RD %RI %RO %RSE %RSEL Internationalization Utilities : %GBLDEF %LCLCOL %PATCODE System Management Utilities : %DUMPFHEAD %FREECNT %XCMD %PEEKBYNAME() %YGBLSTAT() UTF-8 Mode 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) 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 : $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 : 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 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