freem/doc/freem.texi - view

File: [Coherent Logic Development] / freem / doc / freem.texi
Revision 1.46: download - view: text, annotated - select for diffs
Mon May 5 12:51:46 2025 UTC (5 months, 2 weeks ago) by snw
Branches: MAIN
CVS tags: HEAD

Correct ASSERT to ZASSERT in FreeM Manual

1: \input texinfo 2: @paragraphindent 0 3: @setfilename freem.info 4: @settitle The FreeM Manual 5: 6: @copying 7: This manual is for FreeM, (version 0.64.0-rc1), which is a free software implementation of the M programming language. 8: 9: Print-optimized versions of this book are typeset in @emph{Computer Modern} by the author using the @emph{GNU Texinfo} tools. 10: 11: Copyright @copyright{} 2014-2025 Coherent Logic Development LLC 12: 13: @quotation 14: Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. 15: @end quotation 16: @end copying 17: 18: @titlepage 19: 20: @title The FreeM Manual 21: @subtitle @sc{The Official Manual of FreeM} 22: @subtitle Version 0.64.0-rc1 23: @c@vskip 10pt 24: @c@center @image{freem-logo-sm,,,,.png} 25: @author Serena Willis 26: @page 27: @vskip 0pt plus 1filll 28: @insertcopying 29: @end titlepage 30: @contents 31: 32: @ifnottex 33: @node Top 34: @top The FreeM Manual 35: 36: This is the official manual for the FreeM programming language. 37: @end ifnottex 38: 39: @dircategory The FreeM Manual 40: @direntry 41: * FreeM: (freem). The FreeM M programming language. 42: @end direntry 43: 44: @menu 45: * Introduction:: About the FreeM Project, its history, and its goals. 46: * Document Conventions:: Conventions used in this manual. 47: * A Note on Standards:: FreeM positioning regarding the M Development Committee. 48: * FreeM Invocation:: How to invoke FreeM from the command line. 49: * The FreeM Environment Daemon:: Managing shared resources in the FreeM environment. 50: * The FreeM Direct-Mode Environment:: Executing M programs interactively. 51: * Debugging:: The program development cycle of FreeM. 52: 53: * Directives:: Per-Routine Language Directives. 54: * Intrinsic Special Variables:: Intrinsic Special Variables. 55: * Intrinsic Functions:: Intrinsic Functions. 56: * OBJECT Methods:: Methods for OBJECT variables. 57: * STRING Methods:: Methods for STRING variables. 58: * Commands:: Commands. 59: * Structured System Variables:: Structured System Variables. 60: * Operators:: FreeM Operators. 61: 62: * Routines:: The units of M code in FreeM. 63: * Types:: FreeM data types. 64: * Globals:: FreeM persistent sparse arrays. 65: * Concurrency Control:: @code{LOCK}ing and transaction processing. 66: * Local Variables:: In-memory variables. 67: * Scoping:: Scoping in FreeM. 68: * Decision Constructs:: @code{IF}, @code{THEN}, @code{ELSE}, @code{$SELECT}, and postconditionals. 69: * Branch Constructs:: Labels, @code{GOTO}, @code{DO}, and @code{JOB}. 70: * Loop Constructs:: The @code{FOR} loop. 71: * Modular Programming:: Extrinsic functions and subroutines. 72: * Object-Oriented Programming:: Classes and objects in FreeM. 73: * Libraries:: System and user libraries. 74: * Sequential I/O:: Processing sequential files in FreeM. 75: * Network I/O:: Handling network sockets in FreeM. 76: * Extended Global References:: Accessing globals in non-default namespaces. 77: * Global Aliasing:: Defining alternate names for globals. 78: * Global Mappings:: Mapping global names to non-default namespaces. 79: 80: * Asynchronous Event Handling:: Handling asynchronous events in FreeM. 81: * Global Triggers:: Responding to global accesses in M code. 82: * Synchronous Event Handling:: Synchronous events in FreeM. 83: 84: 85: * GUI Programming with MWAPI:: Creating graphical interfaces in FreeM. 86: 87: * User-Defined Z Commands:: Adding your own Z commands to FreeM. 88: * User-Defined Z Functions:: Adding your own Z functions to FreeM. 89: * User-Defined SSVNs:: Adding your own SSVNs to FreeM. 90: 91: * Language Dialects:: Controlling FreeM standards compliance. 92: 93: * System Library Routines:: FreeM built-in library of M routines. 94: 95: * Interrupt Handling:: How FreeM handles interrupts. 96: * Error Processing:: How to handle errors in M program code. 97: * FreeM Error Codes:: Explanations of each FreeM error code. 98: 99: * System Configuration:: Configuring your FreeM installation. 100: * Accessing FreeM from C Programs:: How to use the mlib interface. 101: 102: * FreeM Administrator:: The fmadm system manager tool. 103: * FreeM Legacy Utilities:: FreeM legacy system manager utilities. 104: * FreeM VIEW Commands and Functions:: Getting and setting info about FreeM internals. 105: * Implementation Limits:: FreeM limitations. 106: * US-ASCII Character Set:: The US-ASCII character set. 107: * FreeM Project Coding Standards:: How to write code for submission to the FreeM project. 108: 109: * Index:: Complete index. 110: @end menu 111: 112: @node Introduction 113: @unnumbered Introduction 114: 115: FreeM started its life as @emph{FreeMUMPS}, written for MS-DOS and ported to SCO UNIX by a mysterious individual going by the name of "Shalom ha-Ashkenaz". It was released to MUG Deutschland in 1998. In 1999, Ronald L. Fox ported FreeM to the Red Hat Linux 5 distribution of the GNU/Linux operating system. Thereafter, maintenance was taken over by the Generic Universal M Project, which changed its name first to Public Standard MUMPS and then by popular request to FreeM. 116: 117: When GT.M was open-sourced in late 1999, FreeM and GUMP were essentially abandoned. L.D. Landis, the owner of the original GUMP SourceForge project, and one of FreeM's significant contributors, passed maintenance of FreeM and ownership of its SourceForge project to Serena Willis in 2014. At this point, FreeM would not compile or run on modern Linux systems, so steps were taken to remedy the most pressing issues in the codebase. Limitations on the terminal size (previously hard-coded to 80x25) were lifted, and new @code{$VIEW} functions were added to retrieve the terminal size information. @code{$X} and @code{$Y} intrinsic special variables were updated to support arbitrary terminal sizes, and FreeM was once again able to build and run. 118: 119: In February of 2020, work began in earnest to build a development and support infrastructure for FreeM and begin the careful process of refining it into a more stable and robust application. 120: 121: For more information on FreeM history, see @code{@emph{$PREFIX}/share/freem/doc/freem_history.*} (distributed in PostScript, PDF, and plain text formats). 122: 123: @section Production Readiness 124: 125: FreeM is not yet production-ready. There are several show-stopping bugs that preclude a general release for public use: 126: 127: @itemize @bullet 128: 129: @item 130: @code{@ref{VIEW}} commands and @code{@ref{$VIEW()}} functions are used extensively to configure and inspect the run-time behavior of FreeM, rather than the "canonical" SSVN-based approach. 131: 132: @item 133: Server sockets are not yet implemented. 134: 135: @item 136: There are some situations that can result in segmentation faults and/or lock-ups. 137: 138: @item 139: In spite of our best efforts, this manual is not yet complete. 140: 141: @end itemize 142: 143: @section Contributors 144: Current contributors denoted with a @emph{+} following their name and role. 145: @cindex contributors, ha-Ashkenaz, Shalom 146: @cindex contributors, Best, John 147: @cindex contributors, Diamond, Jon 148: @cindex contributors, Fox, Ronald L. 149: @cindex contributors, Gerum, Winfried 150: @cindex contributors, Kreis, Greg 151: @cindex contributors, Landis, Larry 152: @cindex contributors, Milligan, Lloyd 153: @cindex contributors, Morris, Steve 154: @cindex contributors, Murray, John 155: @cindex contributors, Pastoors, Wilhelm 156: @cindex contributors, Schell, Kate 157: @cindex contributors, Schofield, Lyle 158: @cindex contributors, Stefanik, Jim 159: @cindex contributors, Trocha, Axel 160: @cindex contributors, Walters, Dick 161: @cindex contributors, Whitten, David 162: @cindex contributors, Wicksell, David 163: @cindex contributors, Willis, Serena 164: @cindex contributors, Zeck, Steve 165: 166: @itemize @bullet 167: 168: @item 169: Shalom ha-Ashkenaz (Original Implementer) 170: 171: @item 172: John Best (IBM i and OS/400) 173: 174: @item 175: Jon Diamond (Library, Utilities, Conformance) 176: 177: @item 178: Ronald L. Fox (Initial port to Red Hat 5/libc-6) 179: 180: @item 181: Winfried Gerum (Code, Advice, MTA coordination) 182: 183: @item 184: Greg Kreis (Hardhats coordination, Dependencies) 185: 186: @item 187: Larry Landis (Coordination, Code, Documentation) 188: 189: @item 190: Rick Marshall (Testing, MDC Conformance) @emph{+} 191: 192: @item 193: Lloyd Milligan (Code, Testing, Documentation) 194: 195: @item 196: Steve Morris (Code, Microsoft) 197: 198: @item 199: John Murray (Code, Conformance) 200: 201: @item 202: Wilhelm Pastoors (Testing, Documentation) 203: 204: @item 205: Kate Schell (Coordination, Conformance, MTA, MDC, Advice) 206: 207: @item 208: Lyle Schofield (Advice, Prioritization, Tracking, Project Management) 209: 210: @item 211: Jim Stefanik (GNU/Linux on s390x, IBM AIX, IBM z/OS) 212: 213: @item 214: Axel Trocha (Code, Utilities) 215: 216: @item 217: Dick Walters (Project Lead, Chief Coordinator, MTA) 218: 219: @item 220: David Whitten (QA Test Suite, MDC, Advice) @emph{+} 221: 222: @item 223: David Wicksell (Debugging, Code, Testing) @emph{+} 224: 225: @item 226: Serena Willis (Current Maintainer and Project Lead) @emph{+} 227: 228: @item 229: Steve Zeck (Code) 230: 231: @end itemize 232: 233: @node Document Conventions 234: @chapter Document Conventions 235: @cindex document conventions 236: @cindex conventions 237: 238: @section Formatting Conventions 239: 240: This manual uses the following formatting conventions: 241: @itemize 242: @item Code examples, filesystem paths, and commands are presented in @code{monospace} 243: @item Placeholders where the reader is expected to supply a replacement value are presented in @code{@emph{monospace italics}}, and depending on context, may be surrounded by angle brackets 244: @item New terminology is introduced in @emph{proportional italics} 245: @end itemize 246: 247: @section Definitions 248: 249: FreeM uses abbreviations for common language elements: 250: 251: @table @asis 252: @item @emph{$PREFIX} 253: Refers to the base filesystem location within which FreeM is installed. For most distribution methods of FreeM, @emph{$PREFIX} represents either @code{/} or @code{/usr/local}. 254: @item @emph{dlabel} 255: Refers to a label in an M routine, beginning in the first column of the line. Can be a @emph{name} or an @emph{intlit}. 256: @item @emph{entryref} 257: Refers to an M routine entry point, denoted in the format @code{@emph{dlabel} [+@emph{intexpr}][^@emph{routine}]}. 258: @item @emph{expr} 259: Refers to any expression. Often presented in the format @emph{expr V <type>}, where @emph{V} means @emph{giving}; e.g., @emph{expr V lvn} means @emph{expression giving local variable name}. 260: @item @emph{glvn} 261: Refers to the name of an M global, local, or structured system variable. 262: @item @emph{gvn} 263: Refers to the name of an M global variable. 264: @item @emph{intexpr} 265: Refers to an integer expression. 266: @item @emph{intlit} 267: Refers to an integer literal. 268: @item @emph{ISV}, @emph{isv} 269: Refers to an M intrinsic special variable; @code{$JOB} and @code{$IO} are examples of ISVs. 270: @item @emph{L} 271: Indicates a @emph{list} of the following item, e.g., @emph{L gvn} means @emph{list of global variable names}. 272: @item @emph{lvn} 273: Refers to the name of an M local variable. 274: @item @emph{strlit} 275: Refers to an M string literal. 276: @item @emph{ssvn} 277: Refers to the name of an M structured system variable. 278: @item @emph{tvexpr} 279: Refers to a truth-valued expression. 280: @end table 281: 282: @node A Note on Standards 283: @chapter A Note on Standards 284: @cindex MDC 285: @cindex M Development Committee 286: @cindex ANSI X11.1 287: @cindex standards, ANSI 288: @cindex standards, MDC 289: 290: FreeM attempts to implement as many features as possible from the M Development Committee's unpublished @emph{Millennium Draft Standard}, as well as its predecessors. 291: 292: The maintainer of FreeM (who is also the author of this book) is largely in favor of standardization efforts, and hopes that the MDC will resume activities, and will happily participate if it does so in an open, public, transparent, and democratic manner. Until then, however, FreeM will attempt to improve the M language, in cooperation with other free software M implementers where possible. Any breaking changes introduced in future MDC releases of the @emph{Standard} (such as the rumored @emph{M5}) which prove incompatible with FreeM will be handled via the @code{$DIALECT} special variable (to be changed to @code{$ZDIALECT} in a coming release). 293: 294: The conformance document required per the @emph{Standard} should be installed as a @code{man} page on any computer system where FreeM is made available. Simply type @code{man freem_conformance} to access. 295: 296: @node FreeM Invocation 297: @chapter FreeM Invocation 298: @cindex invocation, command-line 299: @cindex options, command-line 300: 301: @section Synopsis 302: @example 303: $ @command{./freem} [@emph{OPTIONS}...] [[-r <entryref>] | [--routine=<entryref>]] 304: @end example 305: 306: When FreeM loads, it searches the @code{SYSTEM} namespace for the @code{%SYSINIT} routine, and begins executing it. 307: 308: When @code{-r} or @code{--routine} are passed on the command line, FreeM will load and run the specified routine after running @code{%SYSINIT}. Beginning with FreeM 0.1.7, routines invoked in this manner are no longer required to perform their own namespace setup with @code{VIEW} commands. 309: 310: @section %SYSINIT Routine 311: 312: The @code{%SYSINIT} routine runs every time a FreeM interpreter process starts. This routine defines some useful constants, enables handling of @code{TRIGGER} events, and handles the execution of code passed via the @code{-x|--execute} or routines passed via @code{-r|--routine}. 313: 314: Do not modify the supplied @code{%SYSINIT} routine to add site-specific startup items. Instead, create a @code{LCLINIT} routine in the @code{USER} namespace of one or more environments. @code{%SYSINIT} will automatically run @code{LCLINIT} each time it starts. 315: 316: @section Command-Line Options 317: @cindex options, command-line 318: 319: @table @asis 320: 321: @item @option{-d}, @option{--daemon} 322: Starts the FreeM environment daemon, exactly one of which must be running at all times in order for FreeM interpreter and fmadm processes to function. 323: 324: @item @option{-e}, @option{--environment} 325: Selects the environment to be used. If no environment is specified, @code{DEFAULT} is used. 326: 327: @item @option{-k}, @option{--nofork} 328: When used with @option{-d} or @option{--daemon}, causes the FreeM environment daemon to run instead in the foreground. Useful for debugging. 329: 330: @item @option{-S}, @option{--shmsize} 331: When used with @option{-d} or @option{--daemon}, specifies the number of bytes of shared memory FreeM will allocate for the @code{LOCK} table, job table, and IPC table. This will determine the maximum number of concurrent FreeM processes and @code{LOCK}s available in this environment. 332: 333: @item @option{-c}, @option{--config} 334: Specify a configuration file other than @code{$PREFIX/etc/freem.conf}. 335: 336: @item @option{-h}, @option{--help} 337: Display a help message showing valid FreeM options. 338: 339: @item @option{-i}, @option{--import} 340: Causes your UNIX environment variables to be imported into FreeM's local symbol table. 341: 342: @item @option{-f}, @option{--filter} 343: Allows your M routines to be used as UNIX filters. 344: 345: @item @option{-n @emph{<namespace-name>}}, @option{--namespace=@emph{<namespace-name>}} 346: Selects the FreeM namespace to be entered on startup. Must be defined in @file{/etc/<environment>/freem.conf}. 347: 348: @item @option{-r @emph{<entryref>}}, @option{--routine=@emph{<entryref>}} 349: Causes @code{<entryref>} to be executed at load, instead of @code{%SYSINIT}. 350: 351: @item @option{--standard=@emph{<standard>}} 352: Sets the default FreeM dialect to use for new routine buffers. 353: 354: Valid values for @code{@emph{<standard>}} are as follows: 355: 356: @table @code 357: @item @code{M77} 358: Restricts FreeM to use only features specified by the 1977 M standard. 359: @item @code{M84} 360: Restricts FreeM to use only features specified by the 1984 M standard. 361: @item @code{M90} 362: Restricts FreeM to use only features specified by the 1990 M standard. 363: @item @code{M95} 364: Restricts FreeM to use only features specified by the 1995 M standard. 365: @item @code{MDS} 366: Restricts FreeM to use only features proposed by the Millennium Draft Standard. 367: @item @code{M5} 368: Restricts FreeM to use only features proposed by the upcoming M5 standard. 369: @item @code{FREEM}, @code{EXTENDED} 370: Removes all standards-based restrictions and allows full access to all FreeM features. This is the default value of @code{$DIALECT}. 371: @end table 372: 373: Please note that FreeM is not entirely standards-compliant, regardless of the value of @code{@emph{<standard>}}. 374: 375: @item @option{-v}, @option{--version} 376: Displays FreeM version information. 377: 378: @item @option{-x @emph{<mcode>}}, @option{--execute=@emph{<mcode>}} 379: Executes M code @code{<mcode>} at startup. 380: 381: @end table 382: 383: @section Using FreeM for Shell Scripting 384: @cindex routines, as shell scripts 385: @cindex shebang line 386: @cindex shell scripting 387: 388: FreeM M routines can be used as shell scripts by providing a @emph{shebang} line beginning with @code{#!/path/to/freem} as the first line of the routine. 389: The following example presumes that FreeM is installed at @file{/usr/local/bin/freem} and uses the @code{USER} namespace: 390: 391: @example 392: #!/usr/local/bin/freem 393: MYSCRIPT ; 394: SET ^$JOB($JOB,"NAMESPACE")="USER" 395: WRITE "This is output from an M routine used as a shell script.",! 396: Q 397: @end example 398: 399: Currently, the script needs to have a @file{.m} file extension. You will also need to select an appropriate namespace in your script using the @code{SET ^$JOB($JOB,"NAMESPACE")="@emph{<namespace>}"} command before attempting to call other routines or access globals. 400: 401: You will also need to set the script's permissions to @emph{executable} in order for this to work: 402: 403: @example 404: $ chmod +x @emph{myscript.m} 405: @end example 406: 407: @node The FreeM Environment Daemon 408: @chapter The FreeM Environment Daemon 409: @cindex daemon, freem 410: 411: The FreeM environment daemon manages shared resources for a given FreeM environment. These include the lock table, job table, inter-process communication, and concurrency control for transaction processing. Unlike some M implementations, the FreeM environment daemon does @emph{not} function as a write daemon for global storage. 412: 413: One daemon process is required per FreeM environment, and can be started in the following ways, in order of preference: 414: 415: @example 416: $ sudo fmadm start environment [-e=<environment-name>] 417: @end example 418: 419: @example 420: $ freem --daemon [--nofork] [--environment=<environment-name>] [--shmsize=<bytes>] 421: @end example 422: 423: If the daemon is started with @option{--nofork}, it will run in the foreground and its output will be reflected on the terminal. Otherwise, the daemon will run as a child process in the background and immediately return terminal control to the shell. The latter option is recommended in most cases. 424: 425: The @option{--environment} option will start the daemon for the specified @emph{environment-name}. The default environment, if unspecified, is called @code{DEFAULT}. If using an environment other than @code{DEFAULT}, interpreter processes that wish to also connect to the same environment must also use the @option{--environment} option when starting, and @code{libfreem} clients must also pass the environment name as the first argument to the @code{freem_init()} function. Environments allow you to run multiple, isolated instances of FreeM on the same machine, whose globals and routines are distinct and unique. 426: 427: The @option{--shmsize} option specifies the size in bytes of the FreeM shared memory segment. The default is 4194304 bytes. Increasing the size of the FreeM shared memory segment will, at the cost of increased memory usage, increase the number of concurrent jobs and lock table entries available to the environment; decreasing the size of the segment will have the expected opposite effect. Note that you must also pass @option{--shmsize} with the same number of bytes to any interpreter process to be used with an environment whose daemon uses a non-default shared memory segment size. 428: 429: Attempting to start a FreeM interpreter process without a daemon running with the same environment name will result in an error. 430: 431: @node The FreeM Direct-Mode Environment 432: @chapter The FreeM Direct-Mode Environment 433: @cindex command line interface 434: @cindex direct mode 435: @cindex execution, interactive 436: @cindex modes, programmer 437: 438: 439: The FreeM direct-mode environment is the mode entered when FreeM is invoked without the use of @option{-r @emph{<entryref>}} or @option{--routine=@emph{<entryref>}}: 440: 441: @example 442: Coherent Logic Development FreeM version 0.64.0-rc1 (x86_64-pc-linux-gnu) 443: Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC 444: 445: 446: USER> 447: @end example 448: 449: The prompt (@code{DEFAULT.USER>}) displays the current environment and namespace, @code{DEFAULT} and @code{USER}, respsectively. If any uncommitted direct-mode transactions have been started, the prompt will change to reflect the current value of @code{@ref{$TLEVEL}}: 450: 451: @example 452: TL1:DEFAULT.USER> 453: @end example 454: 455: In the above example, @code{TL1} indicates that @code{@ref{$TLEVEL}} is currently @emph{1}. 456: 457: @section Direct-Mode Commands 458: 459: When you are in direct mode, in addition to M commands, a number of internal commands are available to help developers be more productive: 460: 461: @table @asis 462: 463: @item @command{?} 464: Accesses FreeM online help. Requires GNU @command{info(1)} to be installed on your local system. 465: 466: @item @command{events} 467: Writes a list of @emph{event classes} and their @code{ABLOCK} counts: 468: 469: @example 470: DEFAULT.USER> events 471: 472: Event Class Processing Mode ABLOCK Count 473: ----------- --------------- ------------ 474: COMM Disabled 0 475: HALT Disabled 0 476: IPC Disabled 0 477: INTERRUPT Disabled 0 478: POWER Disabled 0 479: TIMER Disabled 0 480: USER Disabled 0 481: WAPI Disabled 0 482: TRIGGER Disabled 0 483: @end example 484: 485: 486: @anchor{trantab} 487: @item @command{trantab} 488: Displays information about any uncommitted transactions currently in-flight for this process. 489: 490: @anchor{glstat} 491: @item @command{trantab} 492: Displays statistics about globals that have been opened in the current FreeM process. 493: 494: @anchor{jobtab} 495: @item @command{jobtab} 496: Displays a summary of the FreeM job table. 497: 498: @anchor{locktab} 499: @item @command{locktab} 500: Displays a list of @code{LOCK}s held in the current environment. 501: 502: @anchor{rbuf} 503: @item @command{rbuf} 504: Lists the status of all FreeM routine buffers. 505: 506: @anchor{wh} 507: @item @command{wh} 508: Forces an immediate flush of this process's @code{readline} history buffer to disk. 509: 510: @anchor{shmstat} 511: @item @command{shmstat} 512: Displays the configuration of FreeM shared memory. Intended only for advanced debugging of the FreeM environment. 513: 514: @anchor{shmpages} 515: @item @command{shmpages} 516: Lists the status of each FreeM shared memory page. Intended only for advanced debugging of the FreeM environment. 517: 518: @anchor{history} 519: @item @command{history} 520: Prints a list of all the direct-mode commands you have entered across all sessions. 521: 522: @anchor{rcl} 523: @item @command{rcl @emph{<history-index>}} 524: Allows you to recall command number @emph{<history-index>} and run it again. Obtain the value for @emph{<history-index>} from the output of the @command{history} command. 525: 526: @item @command{!!} 527: Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands. 528: 529: @example 530: DEFAULT.USER> !! 531: 532: Type Ctrl-D to exit from the shell 533: $ uname -a 534: Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux 535: $ exit 536: 537: DEFAULT.USER> 538: @end example 539: 540: @item @command{!@emph{<external-command>}} 541: Invokes a shell to run @emph{<external-command>} from within FreeM. This temporarily disables @command{SIGALRM} handling in FreeM, which may interrupt the use of event-driven M programming commands including @command{ASTART} and @command{ASTOP}. 542: 543: If the @command{>} character is supplied immediately preceding @emph{<external-command>}, FreeM will append the contents of an M local or global variable referenced in @code{^$JOB($JOB,"PIPE_GLVN")} to the standard input stream of @emph{<external-command>}. 544: 545: If the @command{<} character is supplied immediately preceding @emph{<external-command>}, FreeM will take the standard output stream of @emph{<external-command>} and store it in M local or global variable referenced by @code{^$JOB($JOB,"PIPE_GLVN")}. 546: 547: The data value in the unsubscripted M local or global contains the number of lines in the input or output. Subscripts @code{(1)..(@emph{n})} contain the data for lines 1-@emph{n}. 548: 549: @end table 550: 551: @cindex HALT, in direct-mode 552: If you issue a @code{@ref{HALT}} command at the direct-mode prompt, you will exit out of FreeM. However, if you issue a @code{@ref{HALT}} command when @code{@ref{$TLEVEL}} is greater than zero, you will be given the opportunity to commit or rollback any pending transactions: 553: 554: @example 555: DEFAULT.USER> TSTART 556: 557: 558: TL1:DEFAULT.USER> SET ^MYGLOBAL=1 559: 560: 561: TL1:DEFAULT.USER> HALT 562: 563: UNCOMMITTED TRANSACTIONS EXIST: 564: 565: $TLEVEL 1* 566: Operations for Transaction ID: k8xj1de 567: 1: action = 0 key = ^MYGLOBAL data = 1 568: 569: Would you like to c)ommit or r)ollback the above transactions and their operations? ($TLEVEL = 1) r 570: 571: 572: Transactions have been rolled back. 573: @end example 574: 575: In the above example, the user selected @code{r} to rollback the single pending transaction. 576: 577: @section REPL Functionality 578: @cindex REPL, direct-mode 579: 580: FreeM direct mode allows you to enter M expressions directly from the direct-mode prompt, as long as they begin with a number: 581: 582: @example 583: DEFAULT.USER> S DENOM=10 584: 585: 586: DEFAULT.USER> 100/DENOM 587: 588: 10 589: DEFAULT.USER> 590: @end example 591: 592: Such expressions will be immediately evaluated, and the result printed on @code{@ref{$IO}}. 593: 594: @node Debugging 595: @chapter Debugging 596: @cindex debugging 597: 598: @section Debugging Synopsis 599: FreeM includes an interactive debugger, entered using the @code{BREAK "DEBUG"} command. The debugger is also entered if @code{Ctrl-C} is pressed, @code{Ctrl-C} handling is enabled, and you are in direct mode. 600: 601: If you would like to enter the debugger automatically each time an error is encountered, add the following to your @code{LCLINIT} routine: 602: 603: @example 604: S $ETR="B ""DEBUG""" 605: @end example 606: 607: @section Debugging Commands 608: The debugger uses its own unique command language, where M commands are unavailable. Commands are as follows: 609: 610: @table @asis 611: @item @code{exit}, @code{quit} 612: Exits the debugger and returns to direct mode or normal program execution. 613: @item @code{e} @emph{glvn}, @code{examine} @emph{glvn} 614: Prints the value of @emph{glvn} to the terminal. 615: @item @code{t}, @code{trace} 616: Toggles @emph{trace mode} on and off. When trace mode is on, FreeM will display information about each @code{DO} or @code{GOTO} command encountered, including the routine which invoked the branch, which type of branch was invoked, and the target of the branch. 617: @item @code{s}, @code{step} 618: Single-steps through FreeM code command-by-command. 619: @item @code{n}, @code{next} 620: Single-steps through FreeM code line-by-line. 621: @item @code{c}, @code{cont}, @code{continue} 622: Resumes normal program execution, disabling single-step mode. 623: @item @code{bt}, @code{backtrace} 624: Produces a stack trace. 625: @item @code{h}, @code{halt} 626: Halts the process being debugged and returns control to the operating system. 627: @item @code{w [[+|-|?]@emph{<glvn>}]}, @code{watch [[+|-|?]@emph{<glvn>}]} 628: With no arguments, toggles watchpoints on and off. With @code{+}, adds @emph{<glvn>} to the watchlist. With @code{-}, removes @emph{<glvn>} from the watchlist. With @code{?}, queries the watch status of @emph{<glvn>}. 629: @end table 630: 631: @node Directives 632: @chapter Directives 633: @cindex directives 634: 635: In FreeM, a directive is an instruction embedded in an M comment, and passed to the interpreter to affect a change that is specific to the current routine only. 636: 637: The format of a directive is @code{;%@emph{<directive-name>}}, where @code{@emph{<directive-name>}} is one of the directives listed below. 638: 639: @menu 640: * %DIALECT:: Sets the M dialect in effect. 641: @end menu 642: 643: @anchor{%DIALECT} 644: @section %DIALECT 645: @cindex %DIALECT 646: @cindex directives, %DIALECT 647: 648: Sets the M dialect in effect for the current routine buffer; also sets the @code{$DIALECT} special variable to match. See also @ref{$DIALECT}. 649: 650: @emph{Syntax} 651: 652: @example 653: ;%DIALECT @emph{<dialect>} 654: @end example 655: 656: Valid values for @code{@emph{<dialect>}} are as follows: 657: 658: @table @code 659: @item @code{M77} 660: Restricts FreeM to use only features specified by the 1977 M standard. 661: @item @code{M84} 662: Restricts FreeM to use only features specified by the 1984 M standard. 663: @item @code{M90} 664: Restricts FreeM to use only features specified by the 1990 M standard. 665: @item @code{M95} 666: Restricts FreeM to use only features specified by the 1995 M standard. 667: @item @code{MDS} 668: Restricts FreeM to use only features proposed by the Millennium Draft Standard. 669: @item @code{M5} 670: Restricts FreeM to use only features proposed by the upcoming M5 standard. 671: @item @code{FREEM}, @code{EXTENDED} 672: Removes all standards-based restrictions and allows full access to all FreeM features. This is the default value of @code{%DIALECT}. 673: @end table 674: 675: Please note that FreeM is not entirely standards-compliant, regardless of the value of @code{%DIALECT}. 676: 677: 678: @node Intrinsic Special Variables 679: @chapter Intrinsic Special Variables 680: @cindex variables, intrinsic special 681: 682: @menu 683: * $DEVICE:: $IO device status. 684: * $DIALECT:: Current M dialect. 685: * $ECODE:: Latest M error code. 686: * $ESTACK:: Error stack info. 687: * $ETRAP:: Standard error handler code. 688: * $HOROLOG:: Current date and time. 689: * $IO:: Current I/O device. 690: * $JOB:: PID of current process. 691: * $KEY:: Characters terminating last @code{READ} command. 692: * $PDISPLAY:: Current primary MWAPI display. 693: * $PRINCIPAL:: I/O channel of terminal. 694: * $REFERENCE:: Most recent global reference. 695: * $QUIT:: Whether a @code{QUIT} command requires an argument in the current execution context. 696: * $STACK:: Current program execution stack level. 697: * $STORAGE:: Number of bytes available in the heap. 698: * $SYSTEM:: MDC system ID of FreeM. 699: * $TEST:: Truth value of last conditional expression or result of certain @code{LOCK} operations. 700: * $TLEVEL:: Current level of transaction nesting. 701: * $WITH:: Current variable prefix set by @code{ZWITH} command. 702: * $X:: Current horizontal screen position. 703: * $Y:: Current vertical screen position. 704: * $ZA:: Current position of file on @code{$IO}. 705: * $ZB:: Most recent keystroke. 706: * $ZCONTROLC:: Control-C handling flag. 707: * $ZDATE:: Current date in locale-specific representation. 708: * $ZERROR:: Last error message. 709: * $ZHOROLOG:: Date and time, including milliseconds. 710: * $ZINRPT:: State of the interrupt enable/disable flag. 711: * $ZJOB:: PID of parent process, if applicable. 712: * $ZLOCAL:: Last local variable reference. 713: * $ZNAME:: Name of current M routine. 714: * $ZPRECISION:: Digits of arithmetical precision. 715: * $ZREFERENCE:: Last gvn referenced. 716: * $ZSYSTEM:: Return value of last external command. 717: * $ZTIME:: Current time in locale-specific representation. 718: * $ZTRAP:: Entryref to be executed on error condition. 719: * $ZUT:: Microseconds since the UNIX epoch. 720: * $ZVERSION:: Version of FreeM and GNU host triplet. 721: @end menu 722: 723: @node $DEVICE 724: @section $DEVICE 725: @cindex $DEVICE 726: @cindex intrinsic special variables, $DEVICE 727: 728: Returns the status of the device currently in use. 729: 730: If @code{$DEVICE} returns @emph{1}, an error condition exists on the current device. In this case, there will be two additional fields separated by commas, indicating the internal FreeM error code representing the error present on the device and a text explanation of the error. 731: 732: @node $DIALECT 733: @section $DIALECT 734: @cindex $DIALECT 735: @cindex intrinsic special variables, $DIALECT 736: 737: Returns or sets the language dialect of the current routine. 738: 739: Valid values for @code{$DIALECT} are as follows: 740: 741: @table @code 742: @item @code{M77} 743: Restricts FreeM to use only features specified by the 1977 M standard. 744: @item @code{M84} 745: Restricts FreeM to use only features specified by the 1984 M standard. 746: @item @code{M90} 747: Restricts FreeM to use only features specified by the 1990 M standard. 748: @item @code{M95} 749: Restricts FreeM to use only features specified by the 1995 M standard. 750: @item @code{MDS} 751: Restricts FreeM to use only features proposed by the Millennium Draft Standard. 752: @item @code{M5} 753: Restricts FreeM to use only features proposed by the upcoming M5 standard. 754: @item @code{FREEM}, @code{EXTENDED} 755: Removes all standards-based restrictions and allows full access to all FreeM features. This is the default value of @code{$DIALECT}. 756: @end table 757: 758: Please note that FreeM is not entirely standards-compliant, regardless of the value of @code{$DIALECT}. 759: 760: @node $ECODE 761: @section $ECODE 762: @cindex $ECODE 763: @cindex intrinsic special variables, $ECODE 764: 765: Returns a comma-delimited list of error conditions currently present, and is writable. An empty @code{$ECODE} indicates no errors. 766: 767: Writing a value in the format @code{,<error-code>,} into @code{$ECODE} will raise that error condition. 768: 769: @node $ESTACK 770: @section $ESTACK 771: @cindex $ESTACK 772: @cindex intrinsic special variables, $ESTACK 773: 774: Returns the depth of the program execution stack since the last time @code{$ESTACK} was @code{NEW}ed. @code{NEW}-able, but not @code{SET}-able. Differs from the @code{@ref{$STACK}} ISV in that it is @code{@ref{NEW}}-able, and resets to a value of 0 when @code{@ref{NEW}}ed. 775: 776: @node $ETRAP 777: @section $ETRAP 778: @cindex $ETRAP 779: @cindex intrinsic special variables, $ETRAP 780: 781: Sets or retrieves the M code that is run when an error is encountered or @code{@ref{$ECODE}} is set to a non-blank value. @code{$ETRAP} code executes when @code{$ECODE} becomes non-blank. 782: 783: 784: @node $HOROLOG 785: @section $HOROLOG 786: @cindex $HOROLOG 787: @cindex intrinsic special variables, $HOROLOG 788: 789: Returns a string containing the current date and time as @code{<days>,<seconds>}, where @code{<days>} represents the number of days since the M epoch (midnight on 31 December 1840), 790: and @code{<seconds>} represents the number of seconds since the most recent midnight. 791: 792: @cartouche 793: @quotation 794: @emph{FreeM Extension} 795: 796: In FreeM, @code{$HOROLOG} is @code{@ref{SET}}table. Setting @code{$HOROLOG} will set the system clock if your user account has the appropriate permissions. If your user account does not have permissions to modify the system clock, FreeM will raise a @code{ZPROTECT} error. 797: @end quotation 798: @end cartouche 799: 800: @node $IO 801: @section $IO 802: @cindex $IO 803: @cindex intrinsic special variables, $IO 804: 805: Represents the current input/output device. Read-only. 806: 807: @node $JOB 808: @section $JOB 809: @cindex $JOB 810: @cindex intrinsic special variables, $JOB 811: 812: Represents the process ID of the FreeM instance currently in use. 813: 814: @node $KEY 815: @section $KEY 816: @cindex $KEY 817: @cindex intrinsic special variables, $KEY 818: 819: Represents the sequence of control characters that terminated the last @code{@ref{READ}} command on @code{@ref{$IO}}. 820: 821: @node $PDISPLAY 822: @section $PDISPLAY 823: @cindex $PDISPLAY 824: @cindex intrinsic special variables, $PDISPLAY 825: 826: Represents the current principal display for M Windowing API operations. Commonly used as an index into the @code{@ref{^$DISPLAY}} structured system variable. 827: 828: @node $PRINCIPAL 829: @section $PRINCIPAL 830: @cindex $PRINCIPAL 831: @cindex intrinsic special variables, $PRINCIPAL 832: 833: Represents the primary input/output device. Usually a terminal or virtual terminal. 834: 835: @node $REFERENCE 836: @section $REFERENCE 837: @cindex $REFERENCE 838: @cindex intrinsic special variables, $REFERENCE 839: 840: Returns the last @emph{glvn} referenced. Can be @code{@ref{SET}}, and also stacked with @code{@ref{NEW}}. 841: 842: @node $QUIT 843: @section $QUIT 844: @cindex $QUIT 845: @cindex intrinsic special variables, $QUIT 846: 847: If the current execution context was invoked as an extrinsic function, @code{$QUIT} returns @emph{1}. Otherwise, returns @emph{0}. 848: 849: When @code{$QUIT} returns @emph{1}, a subsequent @code{@ref{QUIT}} command must have an argument. 850: 851: @node $STACK 852: @section $STACK 853: @cindex $STACK 854: @cindex intrinsic special variables, $STACK 855: 856: Represents the current stack level. 857: 858: @node $STORAGE 859: @section $STORAGE 860: @cindex $STORAGE 861: @cindex intrinsic special variables, $STORAGE 862: 863: Represents the number of bytes of free space available in FreeM's heap. 864: 865: @node $SYSTEM 866: @section $SYSTEM 867: @cindex $SYSTEM 868: @cindex intrinsic special variables, $SYSTEM 869: 870: Returns the MDC system ID of FreeM, as well as the environment ID of the current environment. 871: 872: @node $TEST 873: @section $TEST 874: @cindex $TEST 875: @cindex intrinsic special variables, $TEST 876: 877: @code{$TEST} is a writable, @code{@ref{NEW}}-able ISV that is @emph{1} if the most recently evaluated expression was @emph{true}. Otherwise, returns @emph{0}. 878: 879: @code{$TEST} is implicitly @code{NEW}ed when entering a new stack frame for extrinsic functions and argumentless @code{@ref{DO}}. @code{$TEST} 880: is @emph{not} implicitly @code{NEW}ed when a new stack frame is entered with an argumented @code{DO}. 881: 882: For single-line @code{@ref{IF}} or @code{@ref{ELSE}} expressions, you may use @code{@ref{THEN}} to stack @code{$TEST} until the end of the line. All new code should employ @code{THEN} in this manner, as stacking @code{$TEST} prevents a wide range of coding errors that can be very challenging to detect and eliminate. 883: 884: @node $TLEVEL 885: @section $TLEVEL 886: @cindex $TLEVEL 887: @cindex intrinsic special variables, $TLEVEL 888: 889: Returns a numeric value indicating the current level of transaction nesting in the process. When @code{$TLEVEL} is greater than @emph{0}, 890: uncommitted transactions exist. 891: 892: @node $WITH 893: @section $WITH 894: @cindex $WITH 895: @cindex intrinsic special variables, $WITH 896: 897: Returns the variable prefix set by the @code{@ref{ZWITH}} command. 898: 899: @node $X 900: @section $X 901: @cindex $X 902: @cindex intrinsic special variables, $X 903: 904: Represents the current column position of the FreeM cursor. 905: 906: @cartouche 907: @quotation 908: In FreeM, setting @code{$X} will move the FreeM cursor. 909: @end quotation 910: @end cartouche 911: 912: 913: @node $Y 914: @section $Y 915: @cindex $Y 916: @cindex intrinsic special variables, $Y 917: 918: Represents the current row position of the FreeM cursor. 919: 920: @cartouche 921: @quotation 922: In FreeM, setting @code{$Y} will move the FreeM cursor. 923: @end quotation 924: @end cartouche 925: 926: 927: @node $ZA 928: @section $ZA 929: @cindex $ZA 930: @cindex intrinsic special variables, $ZA 931: @cindex intrinsic special variables, implementation-specific 932: 933: On the @code{HOME} device, always @code{0}. On other devices, returns the current position of the file opened on I/O channel @code{@ref{$IO}}. 934: 935: @node $ZB 936: @section $ZB 937: @cindex $ZB 938: @cindex intrinsic special variables, $ZB 939: @cindex intrinsic special variables, implementation-specific 940: 941: Represents the last keystroke. 942: 943: @node $ZCONTROLC 944: @section $ZCONTROLC 945: @cindex $ZCONTROLC 946: @cindex intrinsic special variables, $ZCONTROLC 947: @cindex intrinsic special variables, implementation-specific 948: 949: Returns the status of the Ctrl-C flag and resets it to @emph{false}. 950: 951: @node $ZDATE 952: @section $ZDATE 953: @cindex $ZDATE 954: @cindex intrinsic special variables, $ZDATE 955: @cindex intrinsic special variables, implementation-specific 956: 957: Returns the current date, in the preferred representation for the current system locale. 958: 959: @node $ZERROR 960: @section $ZERROR 961: @cindex $ZERROR 962: @cindex intrinsic special variables, $ZERROR 963: @cindex intrinsic special variables, implementation-specific 964: 965: Returns the last error message. 966: 967: @node $ZHOROLOG 968: @section $ZHOROLOG 969: @cindex $ZHOROLOG 970: @cindex intrinsic special variables, $ZHOROLOG 971: @cindex intrinsic special variables, implementation-specific 972: 973: Output @code{@ref{$HOROLOG}}-style time, with the addition of milliseconds. 974: 975: @node $ZINRPT 976: @section $ZINRPT 977: @cindex $ZINRPT 978: @cindex intrinsic special variables, $ZINRPT 979: @cindex intrinsic special variables, implementation-specific 980: 981: Gets or sets the interrupt enable/disable flag. 982: 983: @node $ZJOB 984: @section $ZJOB 985: @cindex $ZJOB 986: @cindex intrinsic special variables, $ZJOB 987: @cindex intrinsic special variables, implementation-specific 988: 989: Returns the @code{@ref{$JOB}} value of the parent process if the current process was started by a @code{@ref{JOB}} command. Otherwise, returns an empty string. 990: 991: @node $ZLOCAL 992: @section $ZLOCAL 993: @cindex $ZLOCAL 994: @cindex intrinsic special variables, $ZLOCAL 995: @cindex intrinsic special variables, implementation-specific 996: 997: Returns the last local variable referenced. 998: 999: @node $ZNAME 1000: @section $ZNAME 1001: @cindex $ZNAME 1002: @cindex intrinsic special variables, $ZNAME 1003: @cindex intrinsic special variables, implementation-specific 1004: 1005: Returns the name of the current routine. 1006: 1007: @node $ZPRECISION 1008: @section $ZPRECISION 1009: @cindex $ZPRECISION 1010: @cindex intrinsic special variables, $ZPRECISION 1011: @cindex intrinsic special variables, implementation-specific 1012: 1013: Gets or sets the number of digits of numeric precision used for fixed-point decimal arithmetic. If @code{^$JOB($JOB,"MATH")} is @code{IEEE754}, @code{$ZPRECISION} defaults to 16 digits, with a maximum of 16 digits. If @code{^$JOB($JOB,"MATH")} is @code{FIXED}, @code{$ZPRECISION} defaults to 100 digits, with a maximum of 20,000 digits. 1014: 1015: @xref{^$JOB}. 1016: 1017: @node $ZREFERENCE 1018: @section $ZREFERENCE 1019: @cindex $ZREFERENCE 1020: @cindex intrinsic special variables, $ZREFERENCE 1021: @cindex intrinsic special variables, implementation-specific 1022: 1023: Returns the last @emph{gvn} referenced. 1024: 1025: @node $ZSYSTEM 1026: @section $ZSYSTEM 1027: @cindex $ZSYSTEM 1028: @cindex intrinsic special variables, $ZSYSTEM 1029: @cindex intrinsic special variables, implementation-specific 1030: 1031: Represents the return value of the last external command run with @code{!}. 1032: 1033: @node $ZTIME 1034: @section $ZTIME 1035: @cindex $ZTIME 1036: @cindex intrinsic special variables, $ZTIME 1037: @cindex intrinsic special variables, implementation-specific 1038: 1039: Returns the system time in the preferred representation for the current system locale. 1040: 1041: @node $ZTRAP 1042: @section $ZTRAP 1043: @cindex $ZTRAP 1044: @cindex intrinsic special variables, $ZTRAP 1045: @cindex intrinsic special variables, implementation-specific 1046: 1047: Sets or retrieves the entryref to be executed when an M program execution error occurs under FreeM-style or DSM 2.0-style error processing. 1048: 1049: In FreeM-style error processing, @code{$ZTRAP} is specific to each program execution stack level. 1050: 1051: In DSM 2.0-style error processing, @code{$ZTRAP} is the same for all program execution stack levels. 1052: 1053: When FreeM encounters an error, if @code{$ZTRAP} is nonempty and @code{$ETRAP} is empty, FreeM will perform an implicit @code{@ref{GOTO}} to the entryref indicated in @code{$ZTRAP}. 1054: 1055: If @code{$ETRAP} is nonempty when FreeM encounters an error, the value of @code{$ZTRAP} is ignored, whether FreeM-style or DSM 2.0-style error processing is enabled. 1056: 1057: @node $ZUT 1058: @section $ZUT 1059: @cindex $ZUT 1060: @cindex intrinsic special variables, $ZUT 1061: @cindex intrinsic special variables, implementation-specific 1062: 1063: Returns the number of microseconds elapsed since the UNIX epoch (Jan 1, 1970 0:00:00). 1064: 1065: @node $ZVERSION 1066: @section $ZVERSION 1067: @cindex $ZVERSION 1068: @cindex intrinsic special variables, $ZVERSION 1069: @cindex intrinsic special variables, implementation-specific 1070: 1071: Returns the version of FreeM in use, as well as the GNU host triplet for the current FreeM build. 1072: 1073: See @emph{https://wiki.osdev.org/Target_Triplet}. 1074: 1075: @node Intrinsic Functions 1076: @chapter Intrinsic Functions 1077: 1078: @menu 1079: * $ASCII():: Return ASCII code for character in string. 1080: * $CHAR():: Return character for one or more ASCII codes. 1081: * $DATA():: Retrieve definition and characteristics of array node. 1082: * $EXTRACT():: Return a substring of a string. 1083: * $FIND():: Find position of substring within string. 1084: * $FNUMBER():: Format a number according to formatting codes. 1085: * $GET():: Return value of glvn or a default if undefined. 1086: * $INSTANCEOF():: Determine if lvn is an instance of a class. 1087: * $JUSTIFY():: Right-justify a string based on specified length. 1088: * $LENGTH():: Return length or delimiter-based piece count of string. 1089: * $NAME():: Return canonical name from string representation of glvn. 1090: * $NEXT():: Return next numeric subscript following given glvn. 1091: * $ORDER():: Return next subscript at same level of specified glvn. 1092: * $PIECE():: Return one or more delimited pieces of a string. 1093: * $QLENGTH():: Return subscript count of glvn. 1094: * $QSUBSCRIPT():: Return a specified subscript from glvn. 1095: * $QUERY():: Return next subscript of specified glvn. 1096: * $RANDOM():: Return pseudorandom integer up to a maximum value. 1097: * $REVERSE():: Reverse a string. 1098: * $SELECT():: Return value from first true condition in list of expressions. 1099: * $STACK():: Return information about the program stack. 1100: * $TEXT():: Return line of code from a routine. 1101: * $TRANSLATE():: Substitute specified characters in a string. 1102: * $TYPE():: Return class of the specified lvn. 1103: * $VIEW():: Retrieve implementation-specific information. 1104: * $ZBOOLEAN():: Perform boolean operations on numeric arguments. 1105: * $ZCALL():: Unknown. 1106: * $ZCRC():: Generate checksum of a string argument. 1107: * $ZDATA():: Unknown. 1108: * $ZDATE():: Convert @code{@ref{$HOROLOG}} string into human-readable date. 1109: * $ZEDIT():: Unknown. 1110: * $ZHOROLOG():: Convert date/time values to @code{@ref{$HOROLOG}} format. 1111: * $ZKEY():: Unknown. 1112: * $ZLENGTH():: Unknown. 1113: * $ZLSD():: Compute Levenshtein distance between two arguments. 1114: * $ZM():: Unknown. 1115: * $ZNAME():: Unknown. 1116: * $ZNEXT():: Unknown. 1117: * $ZORDER():: Unknown. 1118: * $ZPIECE():: Unknown. 1119: * $ZPREVIOUS():: Unknown. 1120: * $ZREPLACE():: Replace all instances of a substring within a string. 1121: * $ZSYNTAX():: Perform syntax check on string argument. 1122: * $ZTIME():: Convert a @code{@ref{$HOROLOG}} string into human-readable time. 1123: @end menu 1124: 1125: @node $ASCII() 1126: @section $ASCII 1127: @cindex $ASCII 1128: @cindex intrinsic functions, $ASCII 1129: 1130: Returns the ASCII code (in decimal) for one character in a string. 1131: 1132: @example 1133: SET RESULT=$ASCII(@emph{<string>}[,@emph{<index>}]) 1134: @end example 1135: 1136: 1137: If @emph{<index>} is not supplied, @code{$ASCII} will return the ASCII code of the first character. Otherwise, returns the ASCII code of the character at position @emph{<index>}. 1138: 1139: @node $CHAR() 1140: @section $CHAR 1141: @cindex $CHAR 1142: @cindex intrinsic functions, $CHAR 1143: 1144: Returns a string of characters corresponding to a list of ASCII codes. 1145: 1146: @example 1147: SET RESULT=$CHAR(@emph{<ascii-code>}[,@emph{<ascii-code>},...]) 1148: @end example 1149: 1150: @node $DATA() 1151: @section $DATA 1152: @cindex $DATA 1153: @cindex intrinsic functions, $DATA 1154: 1155: Returns a numeric value 0, 1, 10, or 11, depending on whether a referenced node is defined, has data, or has children: 1156: 1157: @example 1158: SET RESULT=$DATA(@emph{<node>}) 1159: @end example 1160: 1161: The return values are as follows: 1162: 1163: @example 1164: 0: @emph{<node>} is undefined 1165: 1: @emph{<node>} has data but no children 1166: 10: @emph{<node>} has children but no data 1167: 11: @emph{<node>} has children and data 1168: @end example 1169: 1170: @node $EXTRACT() 1171: @section $EXTRACT 1172: @cindex $EXTRACT 1173: @cindex intrinsic functions, $EXTRACT 1174: 1175: Extracts a substring of a string. 1176: 1177: The first argument is the source string. 1178: 1179: The optional second argument specifies the starting position of the substring to extract, and defaults to @code{1}. 1180: 1181: The optional third argument specifies the ending position of the substring to extract, and defaults to the value of the second argument, or @code{1}. 1182: 1183: This example will extract the string @emph{FreeM} into the local variable @code{M}. 1184: 1185: @example 1186: SET NAME="FreeM is the best!" 1187: SET M=$EXTRACT(NAME,1,5) 1188: @end example 1189: 1190: It is also possible to use @code{$EXTRACT} on the left-hand side of a @code{SET} assignment in order to modify a substring: 1191: 1192: @example 1193: DEFAULT.USER> SET FOO="ABCDEFG" 1194: 1195: 1196: DEFAULT.USER> SET $EXTRACT(FOO,1,3)="XYZ" 1197: 1198: 1199: DEFAULT.USER> WRITE FOO 1200: 1201: XYZDEFG 1202: @end example 1203: 1204: @node $FIND() 1205: @section $FIND 1206: @cindex $FIND 1207: @cindex intrinsic functions, $FIND 1208: 1209: Finds the character immediately following the first occurence of a substring within a string. 1210: 1211: The first argument is the source string. 1212: 1213: The second argument is the substring to be located. 1214: 1215: The optional third argument indicates the position within the source string at which to begin searching. 1216: 1217: @node $FNUMBER() 1218: @section $FNUMBER 1219: @cindex $FNUMBER 1220: @cindex intrinsic functions, $FNUMBER 1221: 1222: Formats a number according to a particular set of formatting codes. 1223: 1224: The first argument is the number to format. 1225: 1226: The second argument is the series of formatting codes: 1227: 1228: @table @asis 1229: @item 'P' or 'p' 1230: Will display negative numbers within parentheses instead of showing a minus sign. 1231: @item , (comma) 1232: Will add commas as thousands separators. 1233: @item + 1234: Will include a plus sign for positive numbers. Not compatible with 'P' or 'p'. 1235: @item - 1236: Will remove the minus sign from negative numbers. Not compatible with 'p' or 'P'. 1237: @item 't' or 'T' 1238: Will place the sign after the number instead of before the number. 1239: @end table 1240: 1241: The optional third argument is a number indicating how many digits to which the fractional part of the number will be zero-padded. 1242: 1243: @node $GET() 1244: @section $GET 1245: @cindex $GET 1246: @cindex intrinsic functions, $GET 1247: 1248: Returns the value of a local, global, or SSVN if the specified item is defined, or a default value otherwise. 1249: 1250: The first argument is the local, global, or SSVN to be examined. 1251: 1252: The optional second argument is the default value to be returned if the referenced item is undefined, and defaults to the empty string. 1253: 1254: @node $INSTANCEOF() 1255: @section $INSTANCEOF 1256: @cindex $INSTANCEOF 1257: @cindex intrinsic functions, $INSTANCEOF 1258: @cindex object functions, $INSTANCEOF 1259: 1260: Returns @code{1} if the specified @emph{lvn} is an instance of class @emph{class}, or @code{0} otherwise. 1261: 1262: The first argument is a string representing a valid FreeM local variable. 1263: 1264: The second argument is a string representing a valid FreeM class. 1265: 1266: @example 1267: DEFAULT.USER> N STR=$$^%STRING 1268: 1269: DEFAULT.USER> W $INSTANCEOF("STR","^%STRING") 1270: 1 1271: @end example 1272: 1273: @node $JUSTIFY() 1274: @section $JUSTIFY 1275: @cindex $JUSTIFY 1276: @cindex intrinsic functions, $JUSTIFY 1277: 1278: Right-justifies a string based on a specified fixed length. 1279: 1280: The first argument is the source string. 1281: 1282: The second argument is the character length of the output. 1283: 1284: The optional third argument controls the number of fractional digits to be included in the output, and defaults to the number of digits specified in the first argument. 1285: 1286: @node $LENGTH() 1287: @section $LENGTH 1288: @cindex $LENGTH 1289: @cindex intrinsic functions, $LENGTH 1290: 1291: Returns the length of a string, or the number of items in a list delimited by a specified character (as used by @code{@ref{$PIECE()}}). 1292: 1293: The first argument is the source string. 1294: 1295: The optional second argument is the list delimiter to be used. When this argument is omitted, the length of the string in characters is returned. 1296: 1297: @node $NAME() 1298: @section $NAME 1299: @cindex $NAME 1300: @cindex intrinsic functions, $NAME 1301: 1302: Returns the canonical name reference along with some or all of its subscripts. 1303: 1304: The first argument is the source name. 1305: 1306: The optional second argument indicates the maximum subscript count to be returned, and defaults to the subscript count of the source name. 1307: 1308: @node $NEXT() 1309: @section $NEXT 1310: @cindex $NEXT 1311: @cindex intrinsic functions, $NEXT 1312: 1313: Deprecated. Use @code{$ORDER} instead. 1314: 1315: @node $ORDER() 1316: @section $ORDER 1317: @cindex $ORDER 1318: @cindex intrinsic functions, $ORDER 1319: 1320: Returns the previous subscript or next subscript in a local, global, or a subset of structured system variables. 1321: 1322: The first argument is the subscripted local, global, or SSVN. 1323: 1324: The optional second argument can be @code{1} to retrieve the next subscript, or @code{-1} to return the previous. 1325: 1326: @node $PIECE() 1327: @section $PIECE 1328: @cindex $PIECE 1329: @cindex intrinsic functions, $PIECE 1330: 1331: @emph{Syntax} 1332: 1333: @code{$PIECE(@emph{s},@emph{d}[,@emph{n}[,@emph{end}]])} 1334: 1335: Accesses the @code{n}th through @code{end} @code{d}-delimited pieces of string @code{s}. 1336: 1337: The first argument is the string to be evaluated. 1338: 1339: The second argument is the delimiter to be used. 1340: 1341: The optional third argument is the first @code{d}-delimited piece to access, and defaults to @code{1}. 1342: 1343: The optional fourth argument is the final @code{d}-delimited piece to access, and defaults to the value of the third argument (@code{n}). 1344: 1345: Can be used on the left-hand side of an expression in order to @code{@ref{SET}} a value into a @code{d}-delimited piece of @code{s}, as in: 1346: 1347: @example 1348: ; ^snw="this^is^a^piece" 1349: SET $PIECE(^snw,"^",2)="isn't" ; => "this^isn't^a^piece" 1350: @end example 1351: 1352: @node $QLENGTH() 1353: @section $QLENGTH 1354: @cindex $QLENGTH 1355: @cindex intrinsic functions, $QLENGTH 1356: 1357: @emph{Syntax} 1358: 1359: @example 1360: @code{$QLENGTH(@emph{expr V glvn})} 1361: @end example 1362: 1363: Returns the number of subscripts in @emph{glvn}. 1364: 1365: @emph{Example} 1366: @example 1367: @code{SET SUBCT=$QLENGTH("^GBL(1,2,3)") ; => 3} 1368: @end example 1369: 1370: @node $QSUBSCRIPT() 1371: @section $QSUBSCRIPT 1372: @cindex $QSUBSCRIPT 1373: @cindex intrinsic functions, $QSUBSCRIPT 1374: 1375: @emph{Syntax} 1376: 1377: @example 1378: @code{$QSUBSCRIPT(@emph{expr V glvn},@emph{expr V n})} 1379: @end example 1380: 1381: In the RHS form, returns the @emph{n}th subscript of @emph{glvn}. 1382: 1383: @emph{Example} 1384: 1385: @example 1386: @code{SET SUB=$QSUBSCRIPT("^GBL(1,2,3)",2) ; => 2} 1387: @end example 1388: 1389: @emph{Syntax} 1390: 1391: @example 1392: @code{SET $QSUBSCRIPT(@emph{expr V glvn},@emph{expr V n})=@emph{expr} ; => ^GBL(1,4,3)} 1393: @end example 1394: 1395: In the LHS form, sets the @emph{n}th subscript of @emph{glvn} to @emph{expr}. 1396: 1397: @node $QUERY() 1398: @section $QUERY 1399: @cindex $QUERY 1400: @cindex intrinsic functions, $QUERY 1401: 1402: Returns the next subscripted reference in a global. 1403: 1404: @emph{Syntax} 1405: 1406: @example 1407: @code{$QUERY(@emph{glvn})} 1408: @end example 1409: 1410: @emph{Example} 1411: 1412: We will assume the following data structure exists: 1413: @example 1414: ^snw(1)=1 1415: ^snw(1,2)="foo" 1416: ^snw(2)=3 1417: ^snw(3)="" 1418: @end example 1419: 1420: The following code will retrieve the next subscripted name after @code{^snw(1)}: 1421: 1422: @example 1423: @code{SET NEXTNAM=$QUERY(^snw(1)) ; => ^snw(1,2)} 1424: @end example 1425: 1426: @node $RANDOM() 1427: @section $RANDOM 1428: @cindex $RANDOM 1429: @cindex intrinsic functions, $RANDOM 1430: 1431: @emph{Syntax} 1432: 1433: @example 1434: $RANDOM(@emph{max}) 1435: @end example 1436: 1437: Returns a pseudo-random integer in the range of @code{0..@emph{max} - 1} 1438: 1439: @node $REVERSE() 1440: @section $REVERSE 1441: @cindex $REVERSE 1442: @cindex intrinsic functions, $REVERSE 1443: 1444: @emph{Syntax} 1445: 1446: @example 1447: $REVERSE(@emph{s}) 1448: @end example 1449: 1450: Returns the reverse of string @emph{s}. 1451: 1452: @emph{Example} 1453: 1454: @example 1455: SET FOO=$REVERSE("ABC") ; => CBA 1456: @end example 1457: 1458: @node $SELECT() 1459: @section $SELECT 1460: @cindex $SELECT 1461: @cindex intrinsic functions, $SELECT 1462: 1463: Returns a value corresponding to the first true condition in a list of conditional expressions. Each argument is an expression, followed by a colon, followed by an expression whose value will be returned if the first expression is true. If no expressions are true, error condition @code{M4} is raised. 1464: 1465: @emph{Example} 1466: 1467: @example 1468: SET FOO=$SELECT(1=2:"math is broken",1=1:"the world makes sense") ; => "the world makes sense" 1469: @end example 1470: 1471: @node $STACK() 1472: @section $STACK 1473: @cindex $STACK 1474: @cindex intrinsic functions, $STACK 1475: 1476: Returns information about the program execution stack. The @code{$STACK} intrinsic function has both a one-argument form and a two-argument form. 1477: 1478: @emph{Syntax (One-Argument)} 1479: 1480: @example 1481: $STACK(@emph{<num>}) 1482: @end example 1483: 1484: If @emph{num} is @code{0}, returns the command with which this FreeM instance was invoked. 1485: 1486: If @emph{num} is @code{-1}, returns the current program execution stack level. 1487: 1488: If @emph{num} represents a valid program execution stack depth above @code{0}, returns one of the following values indicating the reason for which the referenced program execution stack level was created: 1489: 1490: @table @asis 1491: 1492: @item @code{$$} 1493: If @code{$STACK(@emph{<num>})="$$"}, program execution stack level @code{num} was created as the result of an extrinsic function call 1494: 1495: @item @emph{<m-command>} 1496: If @code{$STACK(@emph{<num>})} returns a valid M command, the referenced program execution stack level was created as a result of the @emph{m-command} command. 1497: 1498: @end table 1499: 1500: @emph{Syntax (Two-Argument}) 1501: 1502: @example 1503: $STACK(@emph{<num>},"[ECODE|MCODE|PLACE]") 1504: @end example 1505: 1506: Returns the error codes, M program code, or entryref applicable to the action that created program execution stack level @emph{num}. 1507: 1508: @node $TEXT() 1509: @section $TEXT 1510: @cindex $TEXT 1511: @cindex intrinsic functions, $TEXT 1512: 1513: Returns a line of code from a routine. 1514: 1515: @node $TRANSLATE() 1516: @section $TRANSLATE 1517: @cindex $TRANSLATE 1518: @cindex intrinsic functions, $TRANSLATE 1519: 1520: Replaces characters in a string. 1521: 1522: The first argument is a string expression representing the text to be changed. 1523: 1524: The second argument is a list of characters to replace. 1525: 1526: The third argument is a list of characters to use as the replacements for the characters in the second argument. 1527: 1528: @emph{Example} 1529: 1530: @example 1531: DEFAULT.USER> W $TRANSLATE("twig","wt","rb") 1532: brig 1533: @end example 1534: 1535: @node $TYPE() 1536: @section $TYPE 1537: @cindex $TYPE 1538: @cindex intrinsic functions, $TYPE 1539: @cindex object functions, $TYPE 1540: 1541: Returns a string giving the class of the object specified in the parameter. 1542: 1543: @xref{Object-Oriented Programming} 1544: 1545: @node $VIEW() 1546: @section $VIEW 1547: @cindex $VIEW 1548: @cindex intrinsic functions, $VIEW 1549: 1550: @node $ZBOOLEAN() 1551: @section $ZBOOLEAN 1552: @cindex $ZBOOLEAN 1553: @cindex intrinsic functions, $ZBOOLEAN 1554: @cindex intrinsic functions, implementation-specific 1555: 1556: 1557: Performs @emph{boolean-operation} on numeric arguments @emph{A} and @emph{B}. 1558: 1559: @emph{Syntax} 1560: 1561: @example 1562: SET RESULT=$ZBOOLEAN(@emph{A},@emph{B},@emph{boolean-operation}) 1563: @end example 1564: 1565: @code{$ZBOOLEAN} Operations (@emph{boolean-operation} values) 1566: 1567: @table @code 1568: @item 0 1569: Always @emph{false} 1570: @item 1 1571: @code{A AND B} 1572: @item 2 1573: @code{A AND NOT B} 1574: @item 3 1575: @code{A} 1576: @item 4 1577: @code{NOT A AND B} 1578: @item 5 1579: @code{B} 1580: @item 6 1581: @code{A XOR B} 1582: @item 7 1583: @code{A OR B} 1584: @item 8 1585: @code{A NOR B} 1586: @item 9 1587: @code{A EQUALS B} 1588: @item 10 1589: @code{NOT B} 1590: @item 11 1591: @code{A OR NOT B} 1592: @item 12 1593: @code{NOT A} 1594: @item 13 1595: @code{NOT A OR B} 1596: @item 14 1597: @code{A NAND B} 1598: @item 15 1599: Always @emph{true} 1600: @end table 1601: 1602: @node $ZCALL() 1603: @section $ZCALL 1604: @cindex $ZCALL 1605: @cindex intrinsic functions, $ZCALL 1606: @cindex intrinsic functions, implementation-specific 1607: 1608: Purpose unknown. 1609: 1610: @node $ZCRC() 1611: @section $ZCRC 1612: @cindex $ZCRC 1613: @cindex intrinsic functions, $ZCRC 1614: @cindex intrinsic functions, implementation-specific 1615: 1616: Returns a checksum of @code{arg1}. 1617: 1618: @emph{Syntax} 1619: 1620: @code{$ZCRC(@emph{arg1})} 1621: 1622: @code{SET VAR=$ZCRC("MUMPS") ; => 86} 1623: 1624: @node $ZDATA() 1625: @section $ZDATA 1626: @cindex $ZDATA 1627: @cindex intrinsic functions, $ZDATA 1628: @cindex intrinsic functions, implementation-specific 1629: 1630: Purpose unknown. 1631: 1632: @node $ZDATE() 1633: @section $ZDATE 1634: @cindex $ZDATE 1635: @cindex intrinsic functions, $ZDATE 1636: @cindex intrinsic functions, implementation-specific 1637: 1638: Converts a @code{@ref{$HOROLOG}} string into a human-readable date. 1639: 1640: @emph{Syntax} 1641: 1642: @example 1643: SET VAR=$ZDATE($H[,@emph{<format-string>}]) 1644: @end example 1645: 1646: The optional @emph{<format-string>} follows the same rules as the UNIX @code{strftime} function. If @emph{<format-string>} is omitted, the value of @code{^$SYSTEM("ZDATE_FORMAT")} is used (typically @code{%x}). 1647: 1648: @xref{^$SYSTEM} 1649: 1650: @node $ZEDIT() 1651: @section $ZEDIT 1652: @cindex $ZEDIT 1653: @cindex intrinsic functions, $ZEDIT 1654: @cindex intrinsic functions, implementation-specific 1655: 1656: Purpose unknown. 1657: 1658: @node $ZHOROLOG() 1659: @section $ZHOROLOG 1660: @cindex $ZHOROLOG 1661: @cindex intrinsic functions, $ZHOROLOG 1662: @cindex intrinsic functions, implementation-specific 1663: 1664: Converts date and/or time values producible by @code{@ref{$ZDATE()}} or @code{@ref{$ZTIME()}} to @code{@ref{$HOROLOG}} format. 1665: 1666: @emph{Syntax} 1667: 1668: @example 1669: $ZHOROLOG(@emph{<date-value>},@emph{<format-string>}) 1670: @end example 1671: 1672: @emph{<date-value>} is a date or time string compatible with the formats from @code{@ref{$ZDATE()}} or @code{@ref{$ZTIME}}. 1673: 1674: @emph{<format-string>} is a format string of the same format as used by the @code{strptime(3)} UNIX function. 1675: 1676: @node $ZKEY() 1677: @section $ZKEY 1678: @cindex $ZKEY 1679: @cindex intrinsic functions, $ZKEY 1680: @cindex intrinsic functions, implementation-specific 1681: 1682: Purpose unknown. 1683: 1684: @node $ZLENGTH() 1685: @section $ZLENGTH 1686: @cindex $ZLENGTH 1687: @cindex intrinsic functions, $ZLENGTH 1688: @cindex intrinsic functions, implementation-specific 1689: 1690: Purpose unknown. 1691: 1692: @node $ZLSD() 1693: @section $ZLSD 1694: @cindex $ZLSD 1695: @cindex intrinsic functions, $ZLSD 1696: @cindex intrinsic functions, implementation-specific 1697: 1698: Returns the Levenshtein distance between two arguments. The Levenshtein distance represents the minimum number of edits needed to change the first argument into the second argument. 1699: 1700: @emph{Syntax} 1701: 1702: @code{SET VAR=$ZLSD(@emph{arg1},@emph{arg2})} 1703: 1704: @emph{Example} 1705: 1706: @code{SET VAR=$ZLSD("KITTENS","MITTENS") ; => 1} 1707: 1708: @node $ZM() 1709: @section $ZM 1710: @cindex $ZM 1711: @cindex intrinsic functions, $ZM 1712: @cindex intrinsic functions, implementation-specific 1713: 1714: @node $ZNAME() 1715: @section $ZNAME 1716: @cindex $ZNAME 1717: @cindex intrinsic functions, $ZNAME 1718: @cindex intrinsic functions, implementation-specific 1719: 1720: Purpose unknown. 1721: 1722: @node $ZNEXT() 1723: @section $ZNEXT 1724: @cindex $ZNEXT 1725: @cindex intrinsic functions, $ZNEXT 1726: @cindex intrinsic functions, implementation-specific 1727: 1728: Purpose unknown. 1729: 1730: @node $ZORDER() 1731: @section $ZORDER 1732: @cindex $ZORDER 1733: @cindex intrinsic functions, $ZORDER 1734: @cindex intrinsic functions, implementation-specific 1735: 1736: Purpose unknown. 1737: 1738: @node $ZPIECE() 1739: @section $ZPIECE 1740: @cindex $ZPIECE 1741: @cindex intrinsic functions, $ZPIECE 1742: @cindex intrinsic functions, implementation-specific 1743: 1744: Purpose unknown. 1745: 1746: @node $ZPREVIOUS() 1747: @section $ZPREVIOUS 1748: @cindex $ZPREVIOUS 1749: @cindex intrinsic functions, $ZPREVIOUS 1750: @cindex intrinsic functions, implementation-specific 1751: 1752: Purpose unknown. 1753: 1754: @node $ZREPLACE() 1755: @section $ZREPLACE 1756: @cindex $ZREPLACE 1757: @cindex intrinsic functions, $ZREPLACE 1758: @cindex intrinsic functions, implementation-specific 1759: 1760: Replaces all instances of @code{arg2} with @code{arg3} in string @code{arg1}. 1761: 1762: @emph{Syntax} 1763: @code{$ZREPLACE(@emph{arg1},@emph{arg2},@emph{arg3})} 1764: 1765: @emph{Example} 1766: 1767: @code{SET VAR=$ZREPLACE("CAT","C","B") ; => BAT} 1768: 1769: @node $ZSYNTAX() 1770: @section $ZSYNTAX 1771: @cindex $ZSYNTAX 1772: @cindex intrinsic functions, $ZSYNTAX 1773: @cindex intrinsic functions, implementation-specific 1774: 1775: @code{$ZSYNTAX} performs a very basic syntax check on @emph{expr V mcode}. Checks only for illegal commands, mismatched brackets, mismatched quotes, missing or surplus arguments, or surplus commas. 1776: 1777: @emph{Syntax} 1778: @example 1779: $ZSYNTAX(@emph{expr V mcode}) 1780: @end example 1781: 1782: If no syntax error is found, returns the empty string. 1783: 1784: If a syntax error is found, returns a number indicating the position in @emph{expr V mcode} at which the error was found, followed by a comma, and the FreeM error code that was found. 1785: 1786: @node $ZTIME() 1787: @section $ZTIME 1788: @cindex $ZTIME 1789: @cindex intrinsic functions, $ZTIME 1790: @cindex intrinsic functions, implementation-specific 1791: 1792: Converts a @code{@ref{$HOROLOG}} string into a human-readable time. 1793: 1794: @emph{Syntax} 1795: 1796: @example 1797: SET VAR=$ZTIME($H[,@emph{<format-string>}]) 1798: @end example 1799: 1800: The optional @emph{<format-string>} follows the same rules as the UNIX @code{strftime(3)} function. If @emph{<format-string>} is omitted, the value of @code{^$SYSTEM("ZTIME_FORMAT")} is used (typically @code{%X}). 1801: 1802: @node OBJECT Methods 1803: @chapter OBJECT Methods 1804: 1805: These methods are part of the @code{^%OBJECT} class, from which all FreeM objects ultimately inherit. 1806: 1807: Please note that classes may override @code{^%OBJECT} methods (or methods of any class) in order to provide results more fitting to the class's abstraction goals. 1808: 1809: @menu 1810: * $$TONUMBER:: Returns the canonical numeric representation of the object. 1811: * $$TYPE:: Returns the fully-qualified class name of the object. 1812: * $$VALUE:: Returns the value of the object. 1813: @end menu 1814: 1815: @node $$TONUMBER 1816: @section $$TONUMBER 1817: 1818: Returns (when applicable) a canonical numeric representation of the referenced object. 1819: 1820: @emph{Syntax} 1821: 1822: @example 1823: W $$MYOBJECT.TONUMBER(),! 1824: @end example 1825: 1826: If no canonical numeric representation of the object is possible, will return the empty string. 1827: 1828: @node $$TYPE 1829: @section $$TYPE 1830: 1831: Returns the fully-qualified class of the referenced object. 1832: 1833: @emph{Syntax} 1834: 1835: @example 1836: W $$MYOBJECT.TYPE() 1837: @end example 1838: 1839: Note that M variables that are created by non-object-oriented means will be objects of the @code{^%STRING} class. 1840: 1841: @node $$VALUE 1842: @section $$VALUE 1843: 1844: Returns the value of the referenced object. 1845: 1846: @emph{Syntax} 1847: 1848: @example 1849: W $$MYOBJECT.VALUE() 1850: @end example 1851: 1852: @node STRING Methods 1853: @chapter STRING Methods 1854: 1855: These are methods inherent to the @code{^%STRING} class, which is the default class for M variables created without specifying a class. 1856: 1857: @menu 1858: * $$ASCII:: Return the ASCII code of a character within the string. 1859: * $$DATA:: Return tree characteristics of the string. 1860: * $$DISTANCE:: Determine Levenstein distance between this string and another. 1861: * $$EXTRACT:: Return a substring of the string. 1862: * $$FIND:: Find the position of a substring within the string. 1863: * $$FNUMBER:: Format numbers. 1864: * $$JUSTIFY:: Pad the string to specific positions. 1865: * $$LENGTH:: Return the length of the string. 1866: * $$PIECECOUNT:: Return the count of pieces existing between instances of a delimiter. 1867: * $$PIECE:: Return a delimited subset of the string. 1868: * $$REPLACE:: Replace instances of a substring within the string. 1869: * $$REVERSE:: Reverse the order of characters in the string. 1870: * $$TOLOWER:: Return a lowercase version of the string. 1871: * $$TOUPPER:: Return an uppercase version of the string. 1872: * $$TRANSLATE:: Replace individual characters within the string. 1873: @end menu 1874: 1875: @node $$ASCII 1876: @section $$ASCII 1877: 1878: Returns the ASCII code of a character within the string. See @ref{$ASCII()}. 1879: 1880: @emph{Syntax} 1881: 1882: @example 1883: W $$MYOBJECT.ASCII(3) 1884: @end example 1885: 1886: The above example returns the ASCII code in position 3 of string object @code{MYOBJECT}. 1887: 1888: @node $$DATA 1889: @section $$DATA 1890: 1891: Returns the value of the @code{$DATA} intrinsic function as performed on the value of the object. See @ref{$DATA()}. 1892: 1893: @emph{Syntax} 1894: 1895: @example 1896: W $$MYOBJECT.DATA() 1897: @end example 1898: 1899: @node $$DISTANCE 1900: @section $$DISTANCE 1901: 1902: Returns the Levenstein distance between the string and another string. See @ref{$ZLSD()}. 1903: 1904: @emph{Syntax} 1905: 1906: @example 1907: W $$MYOBJECT.DISTANCE("someString") 1908: @end example 1909: 1910: @node $$EXTRACT 1911: @section $$EXTRACT 1912: 1913: Returns a substring of the string. See @ref{$EXTRACT()}. 1914: 1915: @emph{Syntax} 1916: 1917: @example 1918: $$<objectName>.EXTRACT(<start>,<end>) 1919: @end example 1920: 1921: 1922: @node $$FIND 1923: @section $$FIND 1924: 1925: Finds the character immediately following the first occurence of a substring within a string. 1926: 1927: The first argument is the substring to be located. 1928: 1929: The second argument is the position within the string at which to begin searching. 1930: 1931: See @ref{$FIND()}. 1932: 1933: @node $$FNUMBER 1934: @section $$FNUMBER 1935: 1936: Formats a number according to a set of formatting codes. 1937: 1938: The argument is a series of formatting codes. See @ref{$FNUMBER()} for details. 1939: 1940: @node $$JUSTIFY 1941: @section $$JUSTIFY 1942: 1943: Right-justifies a string based on a specified fixed length. 1944: 1945: The first argument is the character length of the output. 1946: 1947: The second argument controls the number of fractional digits to be included in the output, and defaults to the number of digits specified in the first argument. 1948: 1949: See @ref{$JUSTIFY()} for details. 1950: 1951: @node $$LENGTH 1952: @section $$LENGTH 1953: 1954: Returns the length of the string. 1955: 1956: @node $$PIECECOUNT 1957: @section $$PIECECOUNT 1958: 1959: Returns the number of items in a list delimited by the character specified in the argument. 1960: 1961: @node $$PIECE 1962: @section $$PIECE 1963: 1964: @emph{Syntax} 1965: 1966: @code{$PIECE(@emph{d}[,@emph{n}[,@emph{end}]])} 1967: 1968: Accesses the @code{n}th through @code{end} @code{d}-delimited pieces of the string. 1969: 1970: The first argument is the delimiter to be used. 1971: 1972: The optional second argument is the first @code{d}-delimited piece to access, and defaults to @code{1}. 1973: 1974: The optional third argument is the final @code{d}-delimited piece to access, and defaults to the value of the third argument (@code{n}). 1975: 1976: 1977: @node $$REPLACE 1978: @section $$REPLACE 1979: 1980: @emph{Syntax} 1981: @code{myString.$$REPLACE(@emph{arg1},@emph{arg2})} 1982: 1983: Replaces all instances of @code{arg2} with @code{arg3} in @code{myString}. 1984: 1985: @node $$REVERSE 1986: @section $$REVERSE 1987: 1988: Returns the reverse of the string. 1989: 1990: @node $$TOLOWER 1991: @section $$TOLOWER 1992: 1993: Returns an all-lowercase version of the string. 1994: 1995: @node $$TOUPPER 1996: @section $$TOUPPER 1997: 1998: Returns an all-uppercase version of the string. 1999: 2000: @node $$TRANSLATE 2001: @section $$TRANSLATE 2002: 2003: Identical to @ref{$TRANSLATE()}, except that the arguments are shifted left by one, and the input string is implicit (the object). 2004: 2005: @node Commands 2006: @chapter Commands 2007: @cindex commands 2008: 2009: @menu 2010: * @@:: Execute the following expression as M code. 2011: * !:: Run an external program or command. 2012: * !!:: Launch a subshell from FreeM direct mode. 2013: * ABLOCK:: Increment the block counter for one or more event classes. 2014: * ASTART:: Enable asynchronous event handling for one or more event classes. 2015: * ASTOP:: Disable asynchronous event handling for one or more event classes. 2016: * AUNBLOCK:: Decrement the block counter for one or more event classes. 2017: * BREAK:: Interrupt a running routine to allow interactive debugging. 2018: * CLOSE:: Close an input/output device. 2019: * DO:: Transfer program control to one or more subroutines or introduces a new execution level. 2020: * ELSE:: Execute the remainder of a line if @code{@ref{$TEST}} evaluates @emph{false}. 2021: * FOR:: Repeat execution of a line or block of code. 2022: * GOTO:: Unconditionally transfer program execution to a supplied @emph{entryref}. 2023: * HALT:: Terminate the current FreeM interpreter instance. 2024: * HANG:: Temporarily suspend the running program. 2025: * IF:: Execute the remainder of a line if a conditional expression evaluates @emph{true}. 2026: * JOB:: Execute an @emph{entryref} in a child process. 2027: * KILL:: Remove data from a local, global, or structured system variable. 2028: * KSUBSCRIPTS:: Kill only the descendant subscripts of a local, global, global, or structured system variable. 2029: * KVALUE:: Kill only the value of a local, global, or structured system variable. 2030: * LOCK:: Control advisory locking for concurrency control. 2031: * MERGE:: Merge contents of one local, global, or structured system variable into another. 2032: * NEW:: Introduce a new scope for a specified local variable or intrinsic special variable or instantiate an object. 2033: * OPEN:: Open a sequential or socket input/output device. 2034: * QUIT:: End execution of the current process level, optionally with return value. 2035: * READ:: Read input from an input/output device. 2036: * SET:: Set the value of a local variable, global, intrinsic special variable, or structured system variable. 2037: * TCOMMIT:: Commit a transaction. 2038: * THEN:: Preserve @code{@ref{$TEST}} until the end of the current line. 2039: * TROLLBACK:: Roll back all pending transactions. 2040: * TSTART:: Introduce a new transaction processing level. 2041: * USE:: Set the currently-active input/output device. 2042: * VIEW:: Modify FreeM internal parameters. 2043: * WRITE:: Write output to current input/output device. 2044: * XECUTE:: Interpret string as M code. 2045: * ZASSERT:: Raise error when a conditional expression evaluates @emph{false}. 2046: * ZBREAK:: Unknown. 2047: * ZCONST:: Define a constant that cannot be altered after initial definition. 2048: * ZGO:: Unknown. 2049: * ZHALT:: Unknown. 2050: * ZINSERT:: Insert code into routine buffer. 2051: * ZJOB:: Invokes a job, ignoring any timeouts. 2052: * ZLOAD:: Load routine into routine buffer. 2053: * ZMAP:: Map a global name to a non-default namespace. 2054: * ZNEW:: Unknown. 2055: * ZPRINT:: Print contents of routine buffer. 2056: * ZQUIT:: Quits multiple stack levels at once. 2057: * ZREMOVE:: Remove code from routine buffer. 2058: * ZSAVE:: Save routine buffer to disk. 2059: * ZTHROW:: Programmatically raise an error condition. 2060: * ZTRAP:: Unknown. 2061: * ZUNMAP:: Remove a mapping of a global to a non-default namespace. 2062: * ZWATCH:: Enable or disable watchpoints, or set or clear watchpoints on specified globals, locals, or structured system variables. 2063: * ZWITH:: Set prefix for future variable references. 2064: * ZWRITE:: Write local variable, global, or structured system variable to @code{@ref{$IO}}. 2065: @end menu 2066: 2067: @node @@ 2068: @section @@ 2069: @cindex @@ 2070: @cindex commands, @@ 2071: @cindex commands, implementation-specific 2072: @cindex commands, non-standard 2073: 2074: Executes FreeM code @emph{expr V mcode}. 2075: 2076: @emph{Syntax} 2077: 2078: @example 2079: @@@emph{expr V mcode} 2080: @end example 2081: 2082: @emph{Example (Using Variable)} 2083: 2084: @example 2085: DEFAULT.USER> SET FOO="WRITE ""HELLO WORLD"",!" 2086: DEFAULT.USER> @@FOO 2087: 2088: HELLO WORLD 2089: 2090: DEFAULT.USER> 2091: @end example 2092: 2093: @emph{Example (Using String Literal)} 2094: 2095: @example 2096: DEFAULT.USER> @@"WRITE ""HELLO WORLD"",!" 2097: 2098: HELLO WORLD 2099: 2100: DEFAULT.USER> 2101: @end example 2102: 2103: @emph{Example (Using Indirection)} 2104: 2105: @example 2106: DEFAULT.USER> SET FOO="BAR" 2107: 2108: DEFAULT.USER> SET BAR="WRITE ""HELLO WORLD"",!" 2109: 2110: DEFAULT.USER> @@@@FOO 2111: 2112: HELLO WORLD 2113: 2114: DEFAULT.USER> 2115: @end example 2116: 2117: 2118: @node ! 2119: @section ! 2120: @cindex ! 2121: @cindex commands, ! 2122: @cindex commands, external 2123: @cindex commands, non-standard 2124: @emph{FreeM Extension} 2125: 2126: Invokes a shell to run @emph{<external-command>} from within FreeM. This temporarily disables @command{SIGALRM} handling in FreeM, which may interrupt the use of event-driven M programming commands including @command{ESTART} and @command{ESTOP}. 2127: 2128: If the @command{<} character is supplied immediately preceding @emph{<external-command>}, FreeM will append the contents of M local variable @code{%} to @emph{<external-command>} as standard input. 2129: 2130: If the @command{>} character is supplied immediately preceding @emph{<external-command>}, FreeM will take the standard output stream of @emph{<external-command>} and store it in M local variable @code{%}. 2131: 2132: @code{%} contains the number of lines in the input or output. @code{%(1)..%(@emph{n})} contains the data for lines 1-@emph{n}. 2133: 2134: @node !! 2135: @section !! 2136: @cindex !! 2137: @cindex commands, !! 2138: @cindex commands, external 2139: @cindex commands, non-standard 2140: @emph{FreeM Extension} 2141: 2142: Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands. 2143: 2144: @example 2145: DEFAULT.USER> !! 2146: 2147: Type Ctrl-D to exit from the shell 2148: $ uname -a 2149: Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux 2150: $ exit 2151: 2152: DEFAULT.USER> 2153: @end example 2154: 2155: 2156: @node ABLOCK 2157: @section ABLOCK 2158: @cindex ABLOCK 2159: @cindex commands, ABLOCK 2160: 2161: Increments the event block counter for one or more event classes. While the block counter for an event class is greater than zero, registered event handlers for that event class will not execute, and will instead be queued for later execution once the block counter reaches zero (all blocks removed). 2162: 2163: An implicit @code{ABLOCK} on all event classes occurs when an event handler subroutine is executing. As soon as a @code{QUIT} is reached within an event handler, an implicit @code{ABLOCK} will occur. 2164: 2165: @emph{Syntax} 2166: 2167: @example 2168: ABLOCK@emph{:postcondition} 2169: @end example 2170: 2171: In its argumentless form, @code{ABLOCK} increments the block counter for @emph{all} event classes, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2172: 2173: @example 2174: ABLOCK@emph{:postcondition} @emph{evclass1}...,@emph{evclassN} 2175: @end example 2176: 2177: In its inclusive form, @code{ABLOCK} increments the block counters for all event classes named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2178: 2179: @example 2180: ABLOCK@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN} 2181: @end example 2182: 2183: In its exclusive form, @code{ABLOCK} increments the block counters for all event classes @emph{except for} those named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2184: 2185: 2186: @node ASTART 2187: @section ASTART 2188: @cindex ASTART 2189: @cindex commands, ASTART 2190: 2191: Enables asynchronous event handling for one or more event classes. 2192: 2193: @emph{Syntax} 2194: 2195: @example 2196: ASTART@emph{:postcondition} 2197: @end example 2198: 2199: In its argumentless form, @code{ASTART} enables asynchronous event handling for all event classes, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2200: 2201: @example 2202: ASTART@emph{:postcondition} @emph{evclass1}...,@emph{evclassN} 2203: @end example 2204: 2205: In its inclusive form, @code{ASTART} enables asynchronous event handling for all event classes named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2206: 2207: @example 2208: ASTART@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN}) 2209: @end example 2210: 2211: In its exclusive form, @code{ASTART} enables asynchronous event handling for all event classes @emph{except for} those named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2212: 2213: @node ASTOP 2214: @section ASTOP 2215: @cindex ASTOP 2216: @cindex commands, ASTOP 2217: 2218: Disables asynchronous event handling for one or more event classes. 2219: 2220: @emph{Syntax} 2221: 2222: @example 2223: ASTOP@emph{:postcondition} 2224: @end example 2225: 2226: In its argumentless form, @code{ASTOP} disables asynchronous event handling for all event classes, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2227: 2228: @example 2229: ASTOP@emph{:postcondition} @emph{evclass1}...,@emph{evclassN} 2230: @end example 2231: 2232: In its inclusive form, @code{ASTOP} disables asynchronous event handling for all event classes named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2233: 2234: @example 2235: ASTOP@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN}) 2236: @end example 2237: 2238: In its exclusive form, @code{ASTOP} disables asynchronous event handling for all event classes @emph{except for} those named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2239: 2240: @node AUNBLOCK 2241: @section AUNBLOCK 2242: @cindex AUNBLOCK 2243: @cindex commands, AUNBLOCK 2244: 2245: Decrements the event block counter for one or more event classes. 2246: 2247: @emph{Syntax} 2248: 2249: @example 2250: AUNBLOCK@emph{:postcondition} 2251: @end example 2252: 2253: In its argumentless form, @code{AUNBLOCK} decrements the block counter for @emph{all} event classes, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2254: 2255: @example 2256: AUNBLOCK@emph{:postcondition} @emph{evclass1}...,@emph{evclassN} 2257: @end example 2258: 2259: In its inclusive form, @code{AUNBLOCK} decrements the block counters for all event classes named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2260: 2261: @example 2262: AUNBLOCK@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN} 2263: @end example 2264: 2265: In its exclusive form, @code{AUNBLOCK} decrements the block counters for all event classes @emph{except for} those named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. 2266: 2267: 2268: @node BREAK 2269: @section BREAK 2270: @cindex BREAK 2271: @cindex commands, BREAK 2272: 2273: Interrupts running routine to allow interactive debugging. 2274: 2275: @emph{Syntax} 2276: 2277: @example 2278: @code{BREAK@emph{:postcondition}} 2279: @end example 2280: 2281: In its argumentless form, @code{BREAK} suspends execution of running code, provided the optional @emph{postcondition} is @emph{true} or omitted. 2282: 2283: @example 2284: @code{BREAK@emph{:postcondition} @emph{breakflag}} 2285: @end example 2286: 2287: @emph{FreeM Extension} 2288: 2289: In its single-argument form, @code{BREAK} enters the interactive debugger or sets @emph{Ctrl-C} handling and error handling characteristics, provided the optional @emph{postcondition} is @emph{true} or omitted. 2290: The following table enumerates the possible values of @emph{breakflag} 2291: 2292: @table @code 2293: @item "DEBUG" 2294: Enters the interactive debugger 2295: @item 0 2296: Disables @emph{Ctrl-C} handling 2297: @item -2 2298: Enables normal FreeM error handling 2299: @item 2 2300: Enables @emph{Digital Standard MUMPS} v2 error handling 2301: @item @emph{any integer value other than 0, 2, or -2} 2302: Enables @emph{Ctrl-C} handling 2303: @end table 2304: 2305: @node CLOSE 2306: @section CLOSE 2307: @cindex CLOSE 2308: @cindex commands, CLOSE 2309: 2310: Closes an input/output device. 2311: 2312: @emph{Syntax} 2313: 2314: @example 2315: @code{CLOSE@emph{:postcondition}} 2316: @end example 2317: 2318: In its argumentless form, @code{CLOSE} closes all I/O devices except for device 0 (the @code{HOME} device), provided the optional @emph{postcondition} is @emph{true} or omitted. 2319: 2320: @example 2321: @code{CLOSE@emph{:postcondition} @emph{channel}} 2322: @end example 2323: 2324: In its single-argument form, @code{CLOSE} closes the I/O device associated with channel @emph{channel}, provided that @emph{channel} represents a currently-open device, and the optional @emph{postcondition} is @emph{true} or omitted. 2325: 2326: @node DO 2327: @section DO 2328: @cindex DO 2329: @cindex commands, DO 2330: 2331: In its inclusive form, transfers program control to one or more specified subroutines, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Line levels of entryrefs specified in the argument list must be one, or error @code{M14} is raised. 2332: 2333: @emph{Syntax} 2334: 2335: @example 2336: DO[@emph{:postcondition}] @emph{entryref}[@emph{:postcondition}[,...]] 2337: @end example 2338: 2339: @cartouche 2340: @quotation 2341: @emph{Non-Standard Behavior} 2342: 2343: FreeM allows @code{DO} @emph{entryref}s to follow the format of @code{+@emph{intexpr}}. In this case, the value of @emph{intexpr} will be interpreted as an offset from the first line of the current routine. 2344: @end quotation 2345: @end cartouche 2346: 2347: In its argumentless form, transfers control to the following block of code where the line level is one greater than the level at which @code{DO} was encountered, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2348: 2349: @emph{Syntax} 2350: 2351: @example 2352: DO[@emph{:postcondition}] 2353: @end example 2354: 2355: @node ELSE 2356: @section ELSE 2357: @cindex ELSE 2358: @cindex commands, ELSE 2359: 2360: Executes the remainder of the line of code on which @code{ELSE} is encountered only if @code{$TEST} evaluates to @emph{false}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2361: 2362: @emph{Syntax} 2363: 2364: @example 2365: ELSE[@emph{:postcondition}] 2366: @end example 2367: 2368: @cartouche 2369: @quotation 2370: @emph{Non-Standard Behavior} 2371: 2372: FreeM allows a @emph{postcondition} on @code{ELSE}. While explicitly forbidden in the @emph{Standard}, it was decided that FreeM should allow postconditions everywhere, both for the sake of foolish consistency (the likes of which Emerson warned against), and for the benefit of entrants to a hypothetical future obfuscated M contest, and those with a Machiavellian predisposition to wicked perversions and undue cleverness. 2373: 2374: Using postconditions on @code{ELSE} should be strictly avoided in production code, as they have no practical use, and may contribute to technical debt, hardening of the arteries, hobgoblins, a small mind, a surfeit of logic, climate change, @emph{Daily WTF} rants, or the meltdown of global financial markets. 2375: @end quotation 2376: @end cartouche 2377: 2378: @node FOR 2379: @section FOR 2380: @cindex FOR 2381: @cindex commands, FOR 2382: 2383: In its argumentless form, repeatedly executes the remainder of the line on which @code{FOR} was encountered until a @code{QUIT}, @code{GOTO}, or end-of-line is encountered, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2384: 2385: @emph{Syntax} 2386: 2387: @example 2388: FOR[@emph{:postcondition}] 2389: @end example 2390: 2391: @cartouche 2392: @quotation 2393: @emph{Non-Standard Behavior} 2394: 2395: When @code{$DIALECT} is set to @code{FREEM}, FreeM allows a @emph{postcondition} on @code{FOR}. Much like postconditions on @code{ELSE} and @code{IF}, this is explicitly forbidden in the @emph{standard}. The expression contained in the @emph{postcondition} is evaluated on each iteration of the @code{FOR} loop, and if it does not evaluate @emph{true}, the loop will be immediately exited. The effect is roughly similar to @code{WHILE} constructs present in other languages, but absent from standard M. 2396: 2397: As with all non-standard features of FreeM, please exercise caution when using this feature, especially in code that is expected to run in other, less preternaturally-inclined M implementations. 2398: @end quotation 2399: @end cartouche 2400: 2401: In its sentinel form, repeatedly executes the remainder of the line and sets a sentinel variable on each iteration, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2402: 2403: On the first iteration of the loop, @emph{glvn} will be set to @emph{initalizer-expression}. On each subsequent iteration, @emph{glvn} will be incremented by @emph{increment-expression}, and the loop will terminate when @emph{glvn} meets or exceeds the value of @emph{max-expression}. 2404: 2405: @emph{Syntax} 2406: 2407: @example 2408: FOR[@emph{:postcondition}] @emph{glvn}=@emph{initializer-expression}:@emph{increment-expression}:@emph{max-expression} 2409: @end example 2410: 2411: @emph{Example} 2412: 2413: @example 2414: DEFAULT.USER> FOR I=1:1:10 WRITE I,! 2415: 2416: 1 2417: 2 2418: 3 2419: 4 2420: 5 2421: 6 2422: 7 2423: 8 2424: 9 2425: 10 2426: 2427: DEFAULT.USER> FOR I=2:2:10 WRITE I,! 2428: 2429: 2 2430: 4 2431: 6 2432: 8 2433: 10 2434: @end example 2435: 2436: In its explicit parameter form, a variable is set to each of a series of explicit values, once per iteration, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. The loop terminates when no more values are available. 2437: 2438: @emph{Syntax} 2439: 2440: @example 2441: FOR[@emph{:postcondition}] @emph{glvn}=@emph{expr1}[,..@emph{exprN}] 2442: @end example 2443: 2444: @emph{Example} 2445: 2446: @example 2447: DEFAULT.USER> FOR I=60,"FOO",-3,"George",1450,$HOROLOG WRITE I,! 2448: 2449: 60 2450: FOO 2451: -3 2452: George 2453: 1450 2454: 66106,52388 2455: @end example 2456: 2457: @node GOTO 2458: @section GOTO 2459: @cindex GOTO 2460: @cindex commands, GOTO 2461: 2462: Transfers program execution to another line of code, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Attempting to @code{GOTO} a different line level or a different block when the line level of @code{GOTO} is greater than one will raise error @code{M45}. 2463: 2464: @emph{Syntax} 2465: 2466: @example 2467: GOTO[@emph{:postcondition}] @emph{entryref} 2468: @end example 2469: 2470: @cartouche 2471: @quotation 2472: @emph{Non-Standard Behavior} 2473: 2474: FreeM allows @code{GOTO} @emph{entryref}s to follow the format of @code{+@emph{intexpr}}. In this case, the value of @emph{intexpr} will be interpreted as an offset from the first line of the current routine. 2475: @end quotation 2476: @end cartouche 2477: 2478: 2479: @node HALT 2480: @section HALT 2481: @cindex HALT 2482: @cindex commands, HALT 2483: 2484: Halts program execution and frees resources allocated during execution, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2485: 2486: @emph{Syntax} 2487: 2488: @example 2489: HALT[@emph{:postcondition}] 2490: @end example 2491: 2492: @node HANG 2493: @section HANG 2494: @cindex HANG 2495: @cindex commands, HANG 2496: 2497: Temporarily suspends the program for @emph{expr} seconds, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Values of @emph{expr} that are zero or less than zero are ignored. 2498: 2499: @emph{Syntax} 2500: 2501: @example 2502: HANG[@emph{:postcondition}] @emph{expr} 2503: @end example 2504: 2505: @cartouche 2506: @quotation 2507: @emph{Non-Standard Behavior} 2508: 2509: FreeM supports sub-second values for @emph{expr}. 2510: @end quotation 2511: @end cartouche 2512: 2513: @node IF 2514: @section IF 2515: @cindex IF 2516: @cindex commands, IF 2517: 2518: In its argumented form, allows the remainder of the line of code following @code{IF} to execute only if all @emph{tvexpr}s evaluate to @emph{true}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2519: 2520: @emph{Syntax} 2521: @example 2522: IF[@emph{:postcondition}] @emph{tvexpr}[,...@emph{tvexpr}] 2523: @end example 2524: 2525: In its argumentless form, allows the remainder of the line of code following @code{IF} to execute only if @code{$TEST} evaluates to @emph{1}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2526: 2527: 2528: @emph{Syntax} 2529: @example 2530: IF[@emph{:postcondition}] @emph{command...} 2531: @end example 2532: 2533: @cartouche 2534: @quotation 2535: @emph{Style Recommendation} 2536: 2537: In the interest of readability and maintainability, we recommend avoiding the argumentless form of @code{IF} in new code. It is an obsolete relic of an era when routine sizes were severely limited, and can be difficult to spot, as the use of whitespace (@code{IF @emph{command}}) makes the intent of its use non-obvious at a glance. It is also far too easy to inadvertently delete the extra space, leading to program errors easily avoided otherwise. 2538: 2539: We recommend explicitly checking the value of @code{$TEST} instead, as in @code{IF $TEST @emph{command}} or @code{@emph{command}:$TEST ...}, as this makes the intent immediately clear both to M newcomers and seasoned experts, and sacrifices nothing of value, even on the oldest computer systems where FreeM can be used today. 2540: @end quotation 2541: @end cartouche 2542: 2543: @node JOB 2544: @section JOB 2545: @cindex JOB 2546: @cindex commands, JOB 2547: 2548: Executes @emph{entryref} in a separate process, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2549: 2550: @emph{Syntax} 2551: @example 2552: JOB[@emph{:postcondition}] @emph{entryref}[:@emph{job-parameters}[:@emph{timeout}]] 2553: @end example 2554: 2555: If @emph{timeout} is supplied, FreeM will set @code{$TEST} to @emph{1} if the child process completes within @emph{timeout} seconds. 2556: 2557: @node KILL 2558: @section KILL 2559: @cindex KILL 2560: @cindex commands, KILL 2561: 2562: In its inclusive form, @code{KILL} deletes the specified @emph{glvn}s and their descendant subscripts, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2563: 2564: @emph{Syntax} 2565: @example 2566: KILL[@emph{:postcondition}] @emph{glvn}[,...@emph{glvn}] 2567: @end example 2568: 2569: In its exclusive form, @code{KILL} deletes all local variables @emph{except} for those specified by @emph{lvn}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2570: 2571: @emph{Syntax} 2572: @example 2573: KILL[@emph{:postcondition}] (@emph{lvn}[,...@emph{lvn}]) 2574: @end example 2575: 2576: In its argumentless form, @code{KILL} deletes all local variables, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2577: 2578: @emph{Syntax} 2579: @example 2580: KILL[@emph{:postcondition}] 2581: @end example 2582: 2583: @node KSUBSCRIPTS 2584: @section KSUBSCRIPTS 2585: @cindex KSUBSCRIPTS 2586: @cindex commands, KSUBSCRIPTS 2587: 2588: Kills only the descendant subscripts (but not the data value) of a referenced global, local, or SSVN (where allowed). 2589: 2590: @emph{Syntax} 2591: 2592: @example 2593: KSUBSCRIPTS@emph{:postcondition} @emph{var1},... 2594: @end example 2595: 2596: In the above @emph{inclusive} form, @code{KVALUE} will kill the descendant subscripts at each local, global, or SSVN node specified in the list (provided that the optional @emph{postcondition} is @emph{true} or omitted), but will leave the data value intact. 2597: 2598: @cartouche 2599: @quotation 2600: @emph{Note} 2601: The below @emph{argumentless} and @emph{exclusive} forms of @code{KSUBSCRIPTS} are not implemented in FreeM, as of version 0.64.0-rc1, but are planned for a future release. 2602: @end quotation 2603: @end cartouche 2604: 2605: @example 2606: KSUBSCRIPTS@emph{:postcondition} 2607: @end example 2608: 2609: In the above @emph{argumentless} form, @code{KSUBSCRIPTS} will kill the descendant subscripts at the root of each local variable (provided that the optional @emph{postcondition} is @emph{true} or omitted), but will leave data values intact. 2610: 2611: @example 2612: KSUBSCRIPTS@emph{:postcondition} (@emph{var1},...) 2613: @end example 2614: 2615: In the above @emph{exclusive} form, @code{KSUBSCRIPTS} will kill the descendant subscripts of all local variables, @emph{with the exception of} those named in the list, provided that the optional @emph{postcondition} is @emph{true} or omitted, while leaving their data values intact. 2616: 2617: 2618: @node KVALUE 2619: @section KVALUE 2620: @cindex KVALUE 2621: @cindex commands, KVALUE 2622: 2623: Kills only the data value (but not descendant subscripts) of a referenced global, local, or SSVN (where allowed). 2624: 2625: @emph{Syntax} 2626: 2627: @example 2628: KVALUE@emph{:postcondition} @emph{var1},... 2629: @end example 2630: 2631: In the above @emph{inclusive} form, @code{KVALUE} will kill the data values at each local, global, or SSVN node specified in the list (provided that the optional @emph{postcondition} is @emph{true} or omitted), but will leave descendant subscripts intact. 2632: 2633: @cartouche 2634: @quotation 2635: @emph{Note} 2636: The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.64.0-rc1, but are planned for a future release. 2637: @end quotation 2638: @end cartouche 2639: 2640: @example 2641: KVALUE@emph{:postcondition} 2642: @end example 2643: 2644: In the above @emph{argumentless} form, @code{KVALUE} will kill the data values at the root of each local variable (provided that the optional @emph{postcondition} is @emph{true} or omitted), but will leave descendant subscripts intact. 2645: 2646: @example 2647: KVALUE@emph{:postcondition} (@emph{var1},...) 2648: @end example 2649: 2650: In the above @emph{exclusive} form, @code{KVALUE} will kill the data values of all local variables, @emph{with the exception of} those named in the list, provided that the optional @emph{postcondition} is @emph{true} or omitted, while leaving their descendant subscripts intact. 2651: 2652: @node LOCK 2653: @section LOCK 2654: @cindex LOCK 2655: @cindex commands, LOCK 2656: 2657: Acquires or releases ownership of names. 2658: 2659: In its argumentless form, @code{LOCK} releases ownership of all names previously locked by the current process, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2660: 2661: @emph{Syntax} 2662: @example 2663: LOCK[@emph{:postcondition}] 2664: @end example 2665: 2666: In its incremental form, increments or decrements the lock counter for each specified @emph{name}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Ownership of each @emph{name} is considered to be the current process as long as the lock counter for @emph{name} is greater than zero. If @emph{timeout} is specified, FreeM will wait no more than @emph{timeout} seconds in attempting to acquire ownership of @emph{name}. 2667: 2668: If @code{LOCK} succeeds within @emph{timeout}, @code{$TEST} is set to @emph{1}. Otherwise, @code{$TEST} is set to @emph{0}. 2669: 2670: @emph{Syntax} 2671: @example 2672: LOCK[@emph{:postcondition}] [+|-]@emph{name}[:@emph{timeout}][,...[+|-]@emph{name}[:@emph{timeout}]] 2673: @end example 2674: 2675: @emph{Example} 2676: 2677: This example will increment the lock counter for @code{^SNW} and decrement the lock counter for @code{^MJR}. 2678: 2679: @example 2680: LOCK +^SNW,-^MJR 2681: @end example 2682: 2683: In its non-incremental form, @code{LOCK} releases all @code{LOCK}s held by the current process, and then attempts to acquire a lock on each @emph{name}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. If @emph{timeout} is supplied, FreeM will attempt to lock @emph{name} for no more than @emph{timeout} seconds. 2684: 2685: If @code{LOCK} succeeds within @emph{timeout}, @code{$TEST} is set to @emph{1}. Otherwise, @code{$TEST} is set to @emph{0}. 2686: 2687: @emph{Syntax} 2688: @example 2689: LOCK[@emph{:postcondition}] @emph{name}[:@emph{timeout}][,...@emph{name}[:@emph{timeout}]] 2690: @end example 2691: 2692: @node MERGE 2693: @section MERGE 2694: @cindex MERGE 2695: @cindex commands, MERGE 2696: 2697: Merges the contents of one global, local, or SSVN subtree to another global, local, or SSVN. 2698: 2699: @emph{Syntax} 2700: 2701: @example 2702: @code{MERGE A=^$JOB} 2703: @end example 2704: 2705: The above example will merge the @code{^$JOB} SSVN into the @code{A} local. Note that the FreeM implementation of @code{MERGE} does not yet support multiple merge arguments. Returns error @code{M19} if either the source or the target variable are descendants of each other. 2706: 2707: @node NEW 2708: @section NEW 2709: @cindex NEW 2710: @cindex commands, NEW 2711: 2712: In all forms of @code{NEW}, @emph{name} must be a local variable name or @code{NEW}-able structured or intrinsic system variable. 2713: 2714: In its inclusive form, @code{NEW} saves each specified @emph{name} on the process stack and removes it, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current stack frame is exited, the previous values are restored. 2715: 2716: @emph{Syntax} 2717: 2718: @example 2719: NEW[@emph{:postcondition}] @emph{name}[,...@emph{name}] 2720: @end example 2721: 2722: In its exclusive form, @code{NEW} saves all local variables @emph{except} those named (each @emph{name}) and removes them, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current stack frame is exited, the previous values are restored. 2723: 2724: @emph{Syntax} 2725: @example 2726: NEW[@emph{:postcondition}] (@emph{name}[,...@emph{name}]) 2727: @end example 2728: 2729: In its argumentless form, @code{NEW} saves all local variables and removes them, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current stack frame is exited, the previous values are restored. 2730: 2731: @emph{Syntax} 2732: @example 2733: NEW@emph{:postcondition} @emph{name}=@emph{expr} 2734: @end example 2735: 2736: In its initializing form, @code{NEW} stacks variable @emph{name} and sets its value to @emph{expr}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current stack frame is exited, the previous value is restored. 2737: 2738: @emph{Syntax} 2739: @example 2740: NEW@emph{:postcondition} @emph{name}=$%@emph{^CLASS}(@emph{initializer-list}) 2741: @end example 2742: 2743: In its object-oriented form, @code{NEW} creates an instance of class @emph{^CLASS} in local variable @emph{name} and calls the constructor of @emph{^CLASS}, passing @emph{initializer-list} as its argument(s). 2744: 2745: @node OPEN 2746: @section OPEN 2747: @cindex OPEN 2748: @cindex commands, OPEN 2749: 2750: Opens sequential or socket I/O devices and files and associates them with a numeric FreeM input/output channel. 2751: 2752: @emph{Syntax (Sequential Files)} 2753: 2754: @example 2755: @code{OPEN@emph{:postcondition} @emph{channel}:"@emph{filename}/@emph{access-mode}"} 2756: @end example 2757: 2758: Opens @emph{filename} for reading and/or writing, and associates the file with FreeM I/O channel @emph{channel}, provided that the optional @emph{postcondition} is @emph{true} or omitted. 2759: The below table lists the valid options for @emph{access-mode}: 2760: 2761: @table @code 2762: @item r 2763: Read-only access 2764: @item w 2765: Create a new file for write access 2766: @item a 2767: Write access; append to existing file 2768: @item r+ 2769: Read/write access 2770: @end table 2771: 2772: @cartouche 2773: @quotation 2774: @emph{I/O Path} 2775: 2776: You cannot specify a fully-qualified filesystem path in the FreeM @code{OPEN} command. By default, FreeM will assume that @emph{filename} exists in the directory indicated in @code{^$JOB($JOB,"CWD")}. If you wish to 2777: access files in other directories, you must first set the @emph{I/O Path} in @code{^$JOB($JOB,"IOPATH")}. 2778: 2779: The following example will set the I/O path to @code{/etc}: 2780: 2781: @example 2782: @code{SET ^$JOB($JOB,"IOPATH")="/etc"} 2783: @end example 2784: 2785: @end quotation 2786: @end cartouche 2787: 2788: If @emph{channel} was already @code{OPEN}ed in the current process, calling @code{OPEN} on the same channel again implicitly closes the file or device currently associated with @emph{channel}. 2789: 2790: @emph{Syntax (Network Sockets)} 2791: 2792: Network sockets use a dedicated range of FreeM I/O channels ranging from 100-255. @code{OPEN}ing a socket I/O channel does @emph{not} implicitly connect the socket. Connecting the socket to the specified remote host is accomplished by the @code{/CONNECT} control mnemonic supplied to the @code{USE} command. 2793: 2794: @example 2795: OPEN@emph{:postcondition} @emph{socket-channel}:"@emph{hostname-or-address}:@emph{port}:@emph{address-family}:@emph{connection-type}" 2796: @end example 2797: 2798: @emph{Socket Parameters} 2799: 2800: @table @emph 2801: 2802: @item socket-channel 2803: The socket I/O channel to use. This must be in the range of 100-255. 2804: 2805: @item hostname-or-address 2806: The hostname or IP address to connect to. If a hostname is supplied, @code{OPEN} will implictly do a name lookup, the mechanism of which is typically determined by the configuration of @code{/etc/nsswitch.conf} on most UNIX and UNIX-like platforms. 2807: 2808: @item port 2809: The TCP or UDP port to which the socket will connect on the remote host. 2810: 2811: @item address-family 2812: The address family to use. Either @emph{IPV4} or @emph{IPV6}. 2813: 2814: @item connection-type 2815: Which connection type to use. Either @emph{TCP} or @emph{UDP}. 2816: 2817: @end table 2818: 2819: If you do not specify the address family and connection type, they will default to @emph{IPV4} and @emph{TCP}, respectively. 2820: 2821: @node QUIT 2822: @section QUIT 2823: @cindex QUIT 2824: @cindex commands, QUIT 2825: 2826: @code{QUIT} will end execution of the current process level, optionally returning @emph{expr}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2827: 2828: @code{QUIT} with @emph{expr} when an argument is not expected will raise error @code{M16}; @code{QUIT} without @emph{expr} when an argument is expected will raise error @code{M17}. 2829: 2830: Argumentless @code{QUIT} may also be used to exit a @code{FOR} loop occurring on the same line. 2831: 2832: @emph{Syntax} 2833: @example 2834: QUIT[@emph{:postcondition}] [@emph{expr}] 2835: @end example 2836: 2837: @node READ 2838: @section READ 2839: @cindex READ 2840: @cindex commands, READ 2841: 2842: The @code{READ} command takes input from I/O channel @code{$IO} and stores it into specified variables, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2843: 2844: @emph{Syntax} 2845: @example 2846: READ[@emph{:postcondition}] @emph{read-argument}[,...@emph{read-argument}] 2847: @end example 2848: 2849: Each @emph{read-argument} may be one of the following: 2850: 2851: @table @asis 2852: 2853: @item String Literal 2854: String literal @emph{read-argument}s will be output to @code{$IO} unmodified. 2855: 2856: @item Format Specifier 2857: One or more of the following: 2858: 2859: @table @asis 2860: @item @code{!} (newline) 2861: Advances the cursor down by one line and returns it to the first column. 2862: 2863: @item @code{#} (form-feed) 2864: Advances the screen down by @code{$ZROWS} and moves the cursor to the upper-left corner of the screen. 2865: 2866: @item @code{?@emph{n}} (position) 2867: Advances the cursor and @code{$X} forward to position @emph{n}. 2868: 2869: @end table 2870: 2871: @item Single-Character Read (@code{*@emph{variable-name}[@emph{:timeout}]}) 2872: Reads one character into variable @emph{variable-name}. If the optional @emph{timeout} is specified, will wait @emph{timeout} seconds to retrieve one character. If a character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{1}. If no character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{0}. 2873: 2874: @item Variable-Length Character Read (@code{@emph{variable-name}[@emph{:timeout}]}) 2875: Reads characters into @emph{variable-name} until the character or character pair in @code{^$DEVICE(@emph{io-channel},"OPTIONS","TERMINATOR")} is encountered. If the optional @emph{timeout} is specified, will wait @emph{timeout} seconds to retrieve characters. If characters are read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{1}. If no character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{0}. 2876: 2877: @item Fixed-Length Character Read (@code{@emph{variable-name}#@emph{count}[@emph{:timeout}]}) 2878: Reads @emph{count} characters into @emph{variable-name}. If the optional @emph{timeout} is specified, will wait @emph{timeout} seconds to retrieve characters. If characters are read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{1}. If no character is read within @emph{timeout} seconds, @code{$TEST} will be set to @emph{0}. 2879: 2880: @item Control Mnemonic (@code{/@emph{control-mnemonic}[@emph{(arg1[,...argN])}]}) 2881: Outputs X3.64 control mnemonic @emph{control-mnemonic} to @code{$IO}. Please see the appendix on X3.64 Control Mnemonics for more information. 2882: 2883: @end table 2884: 2885: @node SET 2886: @section SET 2887: @cindex SET 2888: @cindex commands, SET 2889: 2890: The @code{SET} command places values into one or more variables, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2891: 2892: @emph{Syntax} 2893: @example 2894: SET[@emph{:postcondition}] @emph{set-argument}[=@emph{expression} | @emph{postfix-operator}][@emph{,...set-argument}[=@emph{expression} | @emph{postfix-operator}]] 2895: @end example 2896: 2897: Each @emph{set-argument} can be: 2898: 2899: @table @asis 2900: @item @emph{variable-name} 2901: A local variable, global variable, writable intrinsic special variable, or writable structured system variable. 2902: 2903: @item @emph{lhs-function} 2904: @code{$EXTRACT} or @code{$PIECE}. 2905: @end table 2906: 2907: If any grouping of @emph{set-argument}s is surrounded by parentheses, all @emph{set-argument}s in the parenthesized group will be set to the result of @emph{expression}. 2908: 2909: If @emph{postfix-operator} is used instead of @code{=@emph{expression}}, the results of applying @emph{postfix-operator} to the @emph{set-argument} will be stored in @emph{set-argument}. @emph{postfix-operator} may not be used following a parenthesized group of @emph{set-argument}s. 2910: 2911: @emph{Example (postfix-operator)} 2912: 2913: @example 2914: SET A++,B-- ; increments A, decrements B 2915: @end example 2916: 2917: @node TCOMMIT 2918: @section TCOMMIT 2919: @cindex TCOMMIT 2920: @cindex commands, TCOMMIT 2921: 2922: Commits all pending transactions to the data files, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2923: 2924: @emph{Syntax} 2925: @example 2926: TCOMMIT[@emph{:postcondition}] 2927: @end example 2928: 2929: @node THEN 2930: @section THEN 2931: @cindex THEN 2932: @cindex commands, THEN 2933: 2934: Saves the value of @code{$TEST} until the end of the current line, restoring it at the end of the current line or when a @code{QUIT} is encountered. @code{THEN} should be used in all new code in conjunction with @code{IF}. 2935: 2936: @emph{Example} 2937: @example 2938: IF 1 THEN WRITE "HELLO!",! 2939: @end example 2940: 2941: @node TROLLBACK 2942: @section TROLLBACK 2943: @cindex TROLLBACK 2944: @cindex commands, TROLLBACK 2945: 2946: Rolls back all pending transactions for the current process, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 2947: 2948: @emph{Syntax} 2949: 2950: @example 2951: TROLLBACK[@emph{:postcondition}] 2952: @end example 2953: 2954: @node TSTART 2955: @section TSTART 2956: @cindex TSTART 2957: @cindex commands, TSTART 2958: 2959: Introduces a new transaction level, incrementing @code{$TLEVEL}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Any global data file operations encountered when @code{$TLEVEL} is greater than zero will not be committed to the global data files until @code{TCOMMIT} is encountered. 2960: 2961: If a transaction is restartable, variables in the @emph{variables-list} will be restored to their original values on a restart of the transaction. 2962: 2963: @emph{Syntax} 2964: 2965: @example 2966: TSTART[@emph{:postcondition}] @emph{<variables-list>}:@emph{<transaction-parameters>} 2967: @end example 2968: 2969: @emph{<variables-list>} can be: 2970: 2971: @table @asis 2972: 2973: @item @code{()} 2974: Do not save off any local variables. Makes the transaction non-restartable. 2975: 2976: @item @code{*} 2977: Save off all local variables. Makes the transaction restartable. 2978: 2979: @item @code{@emph{variableName}} 2980: Saves off only one local variable, @emph{variableName}. Makes the transaction restartable. 2981: 2982: @item @code{(@emph{variableName1},...,@emph{variableNameN})} 2983: Saves off all local variables listed. Makes the transaction restartable. 2984: 2985: @end table 2986: 2987: @emph{<transaction-parameters>} can be: 2988: 2989: @table @asis 2990: 2991: @item @code{S[ERIAL]} 2992: Forces ACID properties on the transaction. When @code{SERIAL} is not selected, transactions occur in batch mode, and no attempt is made to guarantee ACID properties. 2993: 2994: @item @code{T[RANSACTIONID]=@emph{transaction-id}} 2995: Sets the ID of the transaction to @emph{transaction-id} 2996: 2997: @end table 2998: 2999: If you are using more than one transaction parameter, surround all of them in parentheses and separate them with commas, e.g.: 3000: 3001: @example 3002: TSTART (FOO,BAR):(SERIAL,TRANSACTIONID="FOO") 3003: @end example 3004: 3005: 3006: @node USE 3007: @section USE 3008: @cindex USE 3009: @cindex commands, USE 3010: 3011: Sets @code{$IO} to a particular FreeM I/O channel, allowing @code{READ}s from and @code{WRITE}s to the associated terminal, sequential file, or network socket. Also sets various device parameters. 3012: 3013: @emph{Syntax (Terminal)} 3014: 3015: @example 3016: USE@emph{:postcondition} @emph{io-channel}[:(@emph{right-margin}:@emph{input-field-length}:@emph{device-status-word}:@emph{position}:@emph{line-terminator}:@emph{break-key})] 3017: @end example 3018: 3019: For terminals, @emph{io-channel} must be 0. 3020: 3021: Semantic and functional description of each device parameter TBA. 3022: 3023: @emph{Syntax (Sequential Files)} 3024: 3025: @example 3026: USE@emph{:postcondition} @emph{io-channel}[:@emph{seek-position}:@emph{terminator}:@emph{nodelay})] 3027: @end example 3028: 3029: For sequential files, @emph{io-channel} must be in the range 1-99. 3030: 3031: Semantic and functional description of each device parameter TBA. 3032: 3033: @emph{Syntax (Network Sockets)} 3034: 3035: @example 3036: USE@emph{:postcondition} @emph{io-channel} 3037: @end example 3038: 3039: The above syntax will set @code{$IO} to @emph{io-channel}, directing successive @code{READ}s and @code{WRITE}s to @emph{io-channel}, provided the optional @emph{postcondition} is @emph{true} or omitted. 3040: 3041: @example 3042: USE@emph{:postcondition} @emph{io-channel}:/CONNECT 3043: @end example 3044: 3045: The above syntax will set @code{$IO} to @emph{io-channel}, as in the prior example, but will also attempt to connect to the host and port specified for @emph{io-channel} when it was @code{OPEN}ed. The @code{/CONNECT} control mnemonic is only valid for socket channels whose connection type is @code{TCP}. Using @code{/CONNECT} on a @code{UDP} socket channel will throw @code{SCKAERR} (error code 55). 3046: 3047: For network sockets, @emph{io-channel} must be in the range 100-255. 3048: 3049: @node VIEW 3050: @section VIEW 3051: @cindex VIEW 3052: @cindex commands, VIEW 3053: 3054: Provides write access to various FreeM internal parameters, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 3055: 3056: @emph{Syntax} 3057: @example 3058: VIEW[@emph{:postcondition}] @emph{view-number}[:@emph{view-argument}[:@emph{view-argument}...]] 3059: @end example 3060: 3061: The @emph{view-number} argument can be one of the following: 3062: 3063: @table @asis 3064: 3065: @item @code{21} - Close All Globals 3066: Closes all global data files open in the current process. Takes no arguments. 3067: 3068: @emph{Syntax} 3069: @example 3070: VIEW 21 3071: @end example 3072: 3073: @item @code{52} - Set G0 Input Translation Table for @code{$IO} 3074: 3075: @emph{Syntax} 3076: @example 3077: VIEW 52:@emph{expr V trantab} 3078: @end example 3079: 3080: @item @code{53} - Set G0 Output Translation Table for @code{$IO} 3081: 3082: @emph{Syntax} 3083: @example 3084: VIEW 53:@emph{expr V trantab} 3085: @end example 3086: 3087: @item @code{54} - Set G1 Input Translation Table for @code{$IO} 3088: 3089: @emph{Syntax} 3090: @example 3091: VIEW 54:@emph{expr V trantab} 3092: @end example 3093: 3094: @item @code{55} - Set G1 Output Translation Table for @code{$IO} 3095: 3096: @emph{Syntax} 3097: @example 3098: VIEW 55:@emph{expr V trantab} 3099: @end example 3100: 3101: @item @code{62} - Set @code{$RANDOM} Seed Number 3102: Sets the seed number used by @code{$RANDOM} to @emph{numexpr}. 3103: 3104: @emph{Syntax} 3105: @example 3106: VIEW 62:@emph{numexpr} 3107: @end example 3108: 3109: @item @code{63} - Set @code{$RANDOM} Parameter A 3110: Sets the number used for @code{$RANDOM} Parameter A to @emph{numexpr}. 3111: 3112: @emph{Syntax} 3113: @example 3114: VIEW 63:@emph{numexpr} 3115: @end example 3116: 3117: @item @code{64} - Set @code{$RANDOM} Parameter B 3118: Sets the number used for @code{$RANDOM} Parameter B to @emph{numexpr}. 3119: 3120: @emph{Syntax} 3121: @example 3122: VIEW 64:@emph{numexpr} 3123: @end example 3124: 3125: @item @code{65} - Set @code{$RANDOM} Parameter C 3126: Sets the number used for @code{$RANDOM} Parameter C to @emph{numexpr}. 3127: 3128: @emph{Syntax} 3129: @example 3130: VIEW 65:@emph{numexpr} 3131: @end example 3132: 3133: @item @code{66} - Set or Clear @code{SIGTERM} Handling Flag 3134: Enables or disables handling of @code{SIGTERM} UNIX signals. If @emph{tvexpr} evaluates to 1 (@emph{true}), @code{SIGTERM} handling will be enabled. Otherwise, @code{SIGTERM} handling will be disabled. 3135: 3136: @emph{Syntax} 3137: @example 3138: VIEW 66:@emph{tvexpr} 3139: @end example 3140: 3141: @item @code{67} - Set or Clear @code{SIGHUP} Handling Flag 3142: Enables or disables handling of @code{SIGHUP} UNIX signals. If @emph{tvexpr} evaluates to 1 (@emph{true}), @code{SIGHUP} handling will be enabled. Otherwise, @code{SIGHUP} handling will be disabled. 3143: 3144: @emph{Syntax} 3145: @example 3146: VIEW 67:@emph{tvexpr} 3147: @end example 3148: 3149: @item @code{70} - Set @code{$ZSORT}/@code{$ZSYNTAX} Flag 3150: Selects whether @code{$ZS} resolves to @code{$ZSORT} or @code{$ZSYNTAX}. 3151: 3152: If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZSYNTAX}. Otherwise, selects @code{$ZSORT}. 3153: 3154: @emph{Syntax} 3155: @example 3156: VIEW 70:@emph{tvexpr} 3157: @end example 3158: 3159: @item @code{71} - Set @code{$ZNEXT}/@code{$ZNAME} Flag 3160: Selects whether @code{$ZN} resolves to @code{$ZNEXT} or @code{$ZNAME}. 3161: 3162: If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZNAME}. Otherwise, selects @code{$ZNEXT}. 3163: 3164: @emph{Syntax} 3165: @example 3166: VIEW 71:@emph{tvexpr} 3167: @end example 3168: 3169: @item @code{72} - Set @code{$ZPREVIOUS}/@code{$ZPIECE} Flag 3170: Selects whether @code{$ZP} resolves to @code{$ZPREVIOUS} or @code{$ZPIECE}. 3171: 3172: If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZPIECE}. Otherwise, selects @code{$ZPREVIOUS}. 3173: 3174: @emph{Syntax} 3175: @example 3176: VIEW 72:@emph{tvexpr} 3177: @end example 3178: 3179: @item @code{73} - Set @code{$ZDATA}/@code{$ZDATE} Flag 3180: Selects whether @code{$ZD} resolves to @code{$ZDATA} or @code{$ZDATE}. 3181: 3182: If @emph{tvexpr} evaluates to @emph{true}, selects @code{$ZDATE}. Otherwise, selects @code{$ZDATA}. 3183: 3184: @emph{Syntax} 3185: @example 3186: VIEW 73:@emph{tvexpr} 3187: @end example 3188: 3189: @item @code{79} - Set Old @code{ZJOB} vs. New @code{ZJOB} Flag 3190: If @emph{tvexpr} evaluates to @emph{true}, sets the @code{ZJOB} mode to new, otherwise, sets it to old. 3191: 3192: @emph{Syntax} 3193: @example 3194: VIEW 79:@emph{tvexpr} 3195: @end example 3196: 3197: @item @code{80} - Set or Clear 8-Bit Flag 3198: If @emph{tvexpr} evaluates to @emph{true}, sets FreeM to 8-bit mode. Otherwise, sets FreeM to 7-bit mode. 3199: 3200: @emph{Syntax} 3201: @example 3202: VIEW 80:@emph{tvexpr} 3203: @end example 3204: 3205: @item @code{81} - Set or Clear PF1 Flag 3206: If @emph{tvexpr} evaluates to @emph{true}, sets the @code{PF1} flag. We do not yet know what this does. 3207: 3208: @emph{Syntax} 3209: @example 3210: VIEW 81:@emph{tvexpr} 3211: @end example 3212: 3213: @item @code{83} - Set or Clear Text in @code{$ZERROR} Flag 3214: If @emph{tvexpr} evaluates to @emph{true}, descriptive error messages will be included in @code{$ZERROR}. Otherwise, only the short error code (i.e. @emph{ZILLFUN}) will be included in @code{$ZERROR}. 3215: 3216: @emph{Syntax} 3217: @example 3218: VIEW 83:@emph{tvexpr} 3219: @end example 3220: 3221: @item @code{92} - Set Type Mismatch Error Flag on @code{EUR2DEM} 3222: If @emph{tvexpr} evaluates to @emph{true}, a type mismatch error will be thrown in @code{EUR2DEM} currency conversions in certain situations that we do not yet understand. 3223: 3224: @emph{Syntax} 3225: @example 3226: VIEW 92:@emph{tvexpr} 3227: @end example 3228: 3229: @item @code{93} - Define @code{ZKEY} Production Rule 3230: We do not know what this does. 3231: 3232: @item @code{96} - Set Global Prefix 3233: Forces global data filenames to be prefixed with the result of @emph{expr}. 3234: 3235: @emph{Syntax} 3236: @example 3237: VIEW 96:@emph{expr V string} 3238: @end example 3239: 3240: @item @code{97} - Set Global Postfix 3241: Forces global data filenames to be postfixed with the result of @emph{expr}. 3242: 3243: @emph{Syntax} 3244: @example 3245: VIEW 97:@emph{expr V string} 3246: @end example 3247: 3248: @item @code{98} - Set Routine Extension 3249: Sets the default extension for M routine filenames to the result of @emph{expr}. 3250: 3251: @emph{Syntax} 3252: @example 3253: VIEW 98:@emph{expr V string} 3254: @end example 3255: 3256: @item @code{101} - Set @code{ierr} 3257: Sets the FreeM internal @code{ierr} value to @emph{intexpr}. Used by some FreeM polyfills (commands or functions implemented in M code). 3258: 3259: @emph{Syntax} 3260: @example 3261: VIEW 101:@emph{intexpr} 3262: @end example 3263: 3264: @item @code{102} - Set @code{ierr} (Deferred) 3265: Sets the FreeM internal @code{ierr} value to @emph{intexpr}, but only after the current process stack level is exited. Used by FreeM polyfills to throw an error that will appear to come from the user's own code rather than the polyfill implementation M code. 3266: 3267: @emph{Syntax} 3268: @example 3269: VIEW 102:@emph{intexpr} 3270: @end example 3271: 3272: @item @code{103} - Signal @code{MERGE} to @code{^$WINDOW} Complete 3273: Signals FreeM's MWAPI implementation that a @code{MERGE} to @code{^$WINDOW} or descendant subscripts thereof has completed. 3274: 3275: @emph{Syntax} 3276: @example 3277: VIEW 103[@emph{:subscript}] 3278: @end example 3279: 3280: @item @code{110} - Set Local @code{$ORDER}/@code{$QUERY} Data Value 3281: Sets the local variable @code{$ORDER}/@code{$QUERY} data value to the result of @emph{expr}. We're not entirely sure what this is. 3282: 3283: @emph{Syntax} 3284: @example 3285: VIEW 110:@emph{expr} 3286: @end example 3287: 3288: @item @code{111} - Set Global @code{$ORDER}/@code{$QUERY} Data Value 3289: Sets the global variable @code{$ORDER}/@code{$QUERY} data value to the result of @emph{expr}. We're not entirely sure what this is. 3290: 3291: @emph{Syntax} 3292: @example 3293: VIEW 111:@emph{expr} 3294: @end example 3295: 3296: @item @code{113} - Set @code{termio} Information 3297: We don't know what this does. 3298: 3299: @item @code{133} - Remember @code{ZLOAD} Directory on @code{ZSAVE} 3300: We don't know what this does, but it takes a @emph{tvexpr}. 3301: 3302: @emph{Syntax} 3303: @example 3304: VIEW 133:@emph{tvexpr} 3305: @end example 3306: 3307: @end table 3308: 3309: 3310: 3311: @node WRITE 3312: @section WRITE 3313: @cindex WRITE 3314: @cindex commands, WRITE 3315: 3316: @node XECUTE 3317: @section XECUTE 3318: @cindex XECUTE 3319: @cindex commands, XECUTE 3320: 3321: @node ZASSERT 3322: @section ZASSERT 3323: @cindex ZASSERT 3324: @cindex commands, ZASSERT 3325: @cindex commands, debugging 3326: @cindex commands, implementation-specific 3327: @cindex commands, non-standard 3328: @emph{FreeM Extension} 3329: 3330: Triggers error @code{ZASSERT} if the supplied truth-valued expression @emph{tvexpr} is @emph{false} (@emph{1} is @emph{true}, and @emph{0} is @emph{false}), and that the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 3331: 3332: The @code{ZASSERT} error is catchable whether using standard-style, FreeM-style, or DSM 2.0-style error processing. 3333: 3334: @emph{Syntax} 3335: 3336: @example 3337: ZASSERT@emph{:postcondition} @emph{<tvexpr>} 3338: @end example 3339: 3340: @emph{Example} 3341: 3342: @example 3343: DEFAULT.USER> SET DEBUG=1 3344: 3345: 3346: DEFAULT.USER> ZASSERT:DEBUG 1=1 3347: 3348: 3349: DEFAULT.USER> ZASSERT:DEBUG 1=0 3350: 3351: 3352: >> Error ZASSERT: programmer assertion failed in SYSTEM::^%SYSINIT [$STACK = 0] 3353: >> ZASSERT:DEBUG 1=0 3354: ^ 3355: @end example 3356: 3357: @node ZBREAK 3358: @section ZBREAK 3359: @cindex ZBREAK 3360: @cindex commands, ZBREAK 3361: @cindex commands, debugging 3362: @cindex commands, implementation-specific 3363: @cindex commands, non-standard 3364: @emph{FreeM Extension} 3365: 3366: @node ZCONST 3367: @section ZCONST 3368: @cindex ZCONST 3369: @cindex commands, ZCONST 3370: @cindex commands, non-standard 3371: @emph{FreeM Extension} 3372: 3373: Defines a local @emph{constant}, or variable that cannot be altered after its initial definition, provided the optional @emph{postcondition} is @emph{true} or omitted. 3374: 3375: Constants must only be locals, and globals are not supported. 3376: 3377: @emph{Syntax} 3378: 3379: @example 3380: @code{ZCONST@emph{:postcondition} @emph{mref1}=@emph{initial-value1},...,@emph{mrefN}=@emph{initial-valueN}} 3381: @end example 3382: 3383: @node ZGO 3384: @section ZGO 3385: @cindex ZGO 3386: @cindex commands, ZGO 3387: @cindex commands, implementation-specific 3388: @cindex commands, non-standard 3389: @emph{FreeM Extension} 3390: 3391: @node ZHALT 3392: @section ZHALT 3393: @cindex ZHALT 3394: @cindex commands, ZHALT 3395: @cindex commands, implementation-specific 3396: @cindex commands, non-standard 3397: @emph{FreeM Extension} 3398: 3399: @node ZINSERT 3400: @section ZINSERT 3401: @cindex ZINSERT 3402: @cindex commands, ZINSERT 3403: @cindex commands, implementation-specific 3404: @cindex commands, non-standard 3405: @emph{FreeM Extension} 3406: 3407: @node ZJOB 3408: @section ZJOB 3409: @cindex ZJOB 3410: @cindex commands, ZJOB 3411: @cindex commands, implementation-specific 3412: @cindex commands, non-standard 3413: @emph{FreeM Extension} 3414: 3415: When @code{ZJOB} is used, the semantics are identical to @code{JOB}, with the exception that the @emph{timeout} is forced to be @code{0}, regardless of what the user specifies. 3416: 3417: For more information, see @code{JOB}. 3418: 3419: @node ZLOAD 3420: @section ZLOAD 3421: @cindex ZLOAD 3422: @cindex commands, ZLOAD 3423: @cindex commands, implementation-specific 3424: @cindex commands, non-standard 3425: @emph{FreeM Extension} 3426: 3427: Loads routine @emph{<routine-name>} into FreeM's routine buffer, provided the optional @emph{postcondition} is @emph{true} or omitted. 3428: 3429: @emph{Syntax} 3430: 3431: @example 3432: ZLOAD@emph{:postcondition} @emph{<routine-name>} 3433: @end example 3434: 3435: 3436: @node ZMAP 3437: @section ZMAP 3438: @cindex ZMAP 3439: @cindex commands, ZMAP 3440: @cindex commands, implementation-specific 3441: @cindex commands, non-standard 3442: 3443: Maps global name @code{gvn} to be mapped to the non-default namespace @emph{expr V namespace}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 3444: 3445: @emph{Syntax} 3446: 3447: @example 3448: ZMAP[@emph{:postcondition}] GLOBAL @emph{gvn}=@emph{expr V namespace} 3449: @end example 3450: 3451: @node ZNEW 3452: @section ZNEW 3453: @cindex ZNEW 3454: @cindex commands, ZNEW 3455: @cindex commands, implementation-specific 3456: @cindex commands, non-standard 3457: @emph{FreeM Extension} 3458: 3459: @node ZPRINT 3460: @section ZPRINT 3461: @cindex ZPRINT 3462: @cindex commands, ZPRINT 3463: @cindex commands, implementation-specific 3464: @cindex commands, non-standard 3465: @emph{FreeM Extension} 3466: 3467: Prints the contents of the current routine buffer, provided the optional @emph{postcondition} is @emph{true} or omitted. 3468: 3469: @emph{Syntax} 3470: 3471: @example 3472: ZPRINT@emph{:postcondition} 3473: @end example 3474: 3475: @node ZQUIT 3476: @section ZQUIT 3477: @cindex ZQUIT 3478: @cindex commands, ZQUIT 3479: @cindex commands, implementation-specific 3480: @cindex commands, non-standard 3481: @emph{FreeM Extension} 3482: 3483: In its single-argument form, quits from @emph{levels} levels of the stack, provided the optional @emph{postcondition} is @emph{true} or omitted. 3484: 3485: In its argumentless form, quits from @code{$STACK} levels of the stack, provided the optional @emph{postcondition} is @emph{true} or omitted. 3486: 3487: @emph{Syntax} 3488: 3489: @example 3490: @code{ZQUIT@emph{:postcondition} [@emph{levels}]} 3491: @end example 3492: 3493: @node ZREMOVE 3494: @section ZREMOVE 3495: @cindex ZREMOVE 3496: @cindex commands, ZREMOVE 3497: @cindex commands, implementation-specific 3498: @cindex commands, non-standard 3499: @emph{FreeM Extension} 3500: 3501: @node ZSAVE 3502: @section ZSAVE 3503: @cindex ZSAVE 3504: @cindex commands, ZSAVE 3505: @cindex commands, implementation-specific 3506: @cindex commands, non-standard 3507: @emph{FreeM Extension} 3508: 3509: 3510: @node ZTHROW 3511: @section ZTHROW 3512: @cindex ZTHROW 3513: @cindex commands, ZTHROW 3514: @cindex commands, non-standard 3515: @emph{FreeM Extension} 3516: 3517: Raises an error condition as long as the optional @emph{postcondition} is @emph{true} or omitted. 3518: 3519: @emph{Syntax} 3520: 3521: @example 3522: @code{ZTHROW@emph{:postcondition} @emph{expr V error-code}} 3523: @end example 3524: 3525: @emph{Example} 3526: 3527: @example 3528: @code{ZTHROW "M102"} 3529: @end example 3530: 3531: @node ZTRAP 3532: @section ZTRAP 3533: @cindex ZTRAP 3534: @cindex commands, ZTRAP 3535: @cindex commands, debugging 3536: @cindex commands, implementation-specific 3537: @cindex commands, non-standard 3538: @emph{FreeM Extension} 3539: 3540: @node ZUNMAP 3541: @section ZUNMAP 3542: @cindex ZUNMAP 3543: @cindex commands, ZUNMAP 3544: @cindex commands, implementation-specific 3545: @cindex commands, non-standard 3546: 3547: Removes any mapping connecting @emph{gvn} to a non-default namespace, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. 3548: 3549: @emph{Syntax} 3550: 3551: @example 3552: ZUNMAP GLOBAL @emph{gvn} 3553: @end example 3554: 3555: @node ZWATCH 3556: @section ZWATCH 3557: @cindex ZWATCH 3558: @cindex commands, ZWATCH 3559: @cindex commands, debugging 3560: @cindex commands, implementation-specific 3561: @cindex commands, non-standard 3562: @emph{FreeM Extension} 3563: 3564: Sets a watchpoint on a global, local, or SSVN node. 3565: 3566: @emph{Syntax} 3567: 3568: 3569: In its @emph{argumentless} form, @code{ZWATCH} toggles watchpoints on and off, provided the optional @emph{postcondition} is @emph{true} or omitted. 3570: 3571: @example 3572: ZWATCH[@emph{:postcondition}] 3573: @end example 3574: 3575: In its @emph{inclusive} form, @code{ZWATCH} adds, removes, or examines watchpoints, provided the optional @emph{postcondition} is @emph{true} or omitted. 3576: 3577: A @code{+} adds a new watchpoint to the following variable. 3578: 3579: A @code{-} removes an existing watchpoint for the following variable. 3580: 3581: A @code{?} examines the status of a watchpoint for the following variable. 3582: 3583: @example 3584: ZWATCH[@emph{:postcondition}] [+|-|?]@emph{var1}...,[+|-|?]@emph{varN} 3585: @end example 3586: 3587: 3588: The following example demonstrates turning watchpoint processing on and adding a watchpoint for global variable @code{^snw(1)}. It then changes the value of @code{^snw(1)}. 3589: 3590: @example 3591: DEFAULT.USER> ZWATCH 3592: 3593: Watchpoints enabled. 3594: 3595: DEFAULT.USER> ZWATCH +^SNW(1) 3596: 3597: Added '^SNW("1")' to the watchlist. 3598: 3599: DEFAULT.USER> SET ^SNW(1)="new value" 3600: 3601: >> WATCHPOINT: ^SNW("1") => 'new value' (changed 1 times) 3602: 3603: @end example 3604: 3605: The following example will remove that watchpoint: 3606: 3607: @example 3608: DEFAULT.USER> ZWATCH -^SNW(1) 3609: 3610: Removed '^SNW("1")' from the watchlist. 3611: 3612: DEFAULT.USER> ZWATCH ?^SNW(1) 3613: 3614: '^SNW("1")' is not being watched. 3615: @end example 3616: 3617: @node ZWITH 3618: @section ZWITH 3619: @cindex ZWITH 3620: @cindex commands, ZWITH 3621: @cindex commands, non-standard 3622: @emph{FreeM Extension} 3623: 3624: NOTE: This command may be deprecated and removed in future FreeM releases. 3625: 3626: Sets a prefix to be applied to all subsequent local variable or constant references. 3627: 3628: @emph{Syntax} 3629: 3630: @example 3631: @code{ZWITH@emph{:postcondition} @emph{var-prefix}} 3632: @end example 3633: 3634: In the above single-argument form, sets the @code{$WITH} prefix to @emph{var-prefix}, provided that the optional @emph{postcondition} is either @emph{true} or omitted. 3635: 3636: The @emph{var-prefix} argument may be a string literal or any valid FreeM expression. 3637: 3638: @example 3639: @code{ZWITH@emph{:postcondition}} 3640: @end example 3641: 3642: In the above argumentless form, clears the @code{$WITH} prefix, provided the optional @emph{postcondition} is either @emph{true} or omitted. Equivalent to @code{ZWITH ""}. 3643: 3644: 3645: 3646: 3647: 3648: 3649: 3650: 3651: @node ZWRITE 3652: @section ZWRITE 3653: @cindex ZWRITE 3654: @cindex commands, ZWRITE 3655: @cindex commands, implementation-specific 3656: @cindex commands, non-standard 3657: @emph{FreeM Extension} 3658: 3659: Writes the names and values of M variables to @code{$IO}. 3660: 3661: @emph{Syntax} 3662: 3663: @example 3664: ZWRITE@emph{:postcondition} 3665: @end example 3666: 3667: In the argumentless form, writes the names and values of all local variables to @code{$IO} if the optional @emph{postcondition} is @emph{true} or omitted. 3668: 3669: @example 3670: ZWRITE@emph{:postcondition} @emph{ArrayName},@dots{} 3671: @end example 3672: 3673: In the inclusive form, writes the names and values of all local, global, or structured system variables specified in the list of @emph{ArrayName}s to @code{$IO} if the optional @emph{postcondition} is @emph{true} or omitted. 3674: 3675: @example 3676: ZWRITE@emph{:postcondition} (@emph{ArrayName},@dots{}) 3677: @end example 3678: 3679: In the exclusive form, writes all local variables @emph{except} those specified in the list of @emph{ArrayName}s to @code{$IO} if the optional @emph{postcondition} is @emph{true} or omitted. 3680: 3681: 3682: @node Structured System Variables 3683: @chapter Structured System Variables 3684: @cindex variables, structured system 3685: @cindex structured system variables 3686: @cindex SSVNs 3687: 3688: @menu 3689: * ^$CHARACTER:: Character set information. 3690: * ^$DEVICE:: Device information. 3691: * ^$DISPLAY:: Information about graphic display. 3692: * ^$EVENT:: Information supplied about a synchronous or asynchronous event. 3693: * ^$GLOBAL:: Information about M globals. 3694: * ^$JOB:: Information about and control of FreeM jobs. 3695: * ^$LOCK:: Information about the FreeM lock table. 3696: * ^$OBJECT:: Information about FreeM objects. 3697: * ^$ROUTINE:: Information about FreeM routines. 3698: * ^$SYSTEM:: Information about the running system. 3699: * ^$WINDOW:: Configuration of MWAPI windows. 3700: * ^$ZPROCESS:: Information about and control of system processes. 3701: * ^$ZRPI:: Information about and control of Raspberry Pi GPIO pins. 3702: @end menu 3703: 3704: SSVN subscripts are each described in the following format: 3705: 3706: @table @asis 3707: @item @code{@emph{<ssvn-subscript-name>}} +/-R +/-U +/-D 3708: @end table 3709: 3710: The R, U, and D flags represent Read, Update, and Delete. A minus sign indicates that the given operation is @emph{not} allowed, and a plus sign indicates that the given operation @emph{is} allowed. 3711: 3712: @node ^$CHARACTER 3713: @section ^$CHARACTER 3714: @cindex ^$CHARACTER 3715: @cindex structured system variables, ^$CHARACTER 3716: 3717: Exposes character set information. As FreeM currently only supports the @code{M} character set, the first subscript of @code{^$CHARACTER} must always be @code{"M"}. 3718: 3719: The following values for the second subscript are supported: 3720: 3721: @table @asis 3722: 3723: @item @code{IDENT} +R -U -D 3724: Returns the empty string. 3725: 3726: @item @code{COLLATE} +R -U -D 3727: Returns the empty string. 3728: 3729: @item @code{INPUT} +R -U -D 3730: Returns the empty string if the third subscript is @code{M}, otherwise, raises error @code{M38}. 3731: 3732: @item @code{OUTPUT} +R -U -D 3733: Returns the empty string if the third subscript is @code{M}, otherwise, raises error @code{M38}. 3734: 3735: @end table 3736: 3737: @node ^$DEVICE 3738: @section ^$DEVICE 3739: @cindex ^$DEVICE 3740: @cindex structured system variables, ^$DEVICE 3741: 3742: FreeM implements several important pieces of functionality in the @code{^$DEVICE} SSVN. 3743: 3744: The first subscript of @code{^$DEVICE} represents the I/O channel of an @code{OPEN}ed device. 3745: 3746: The following values for the second subscript are supported: 3747: 3748: @table @asis 3749: 3750: @item @code{$DEVICE} 3751: Returns the value of @code{$DEVICE} for the specified I/O channel. 3752: 3753: @item @code{$X} +R -U -D 3754: Returns the horizontal cursor position of a terminal device. Only valid if the I/O channel is @code{0}. 3755: 3756: @item @code{$Y} +R -U -D 3757: Returns the vertical cursor position of a terminal device. Only valid if the I/O channel is @code{0}. 3758: 3759: @item @code{ROWS} +R -U -D 3760: Returns the number of character rows on the terminal device. Only valid if the I/O channel is @code{0}. 3761: 3762: @item @code{COLUMNS} +R -U -D 3763: Returns the number of character columns on the terminal device. Only valid if the I/O channel is @code{0}. 3764: 3765: @item @code{CHARACTER} +R -U -D 3766: Returns the character set of the specified I/O channel; always @code{M} in the current implementation. 3767: 3768: @item @code{INPUT_BUFFER} +R +U -D 3769: Returns or sets the contents of the input buffer for the specified I/O channel. Data populated in this node will remain in the buffer until subsequent @code{READ} command(s) remove it. This can be used to perform input buffer stuffing, i.e., to fill out an interactive form programmatically. 3770: 3771: @item @code{NAME} +R -U -D 3772: Returns the operating system's name for the file, device, or socket attached to the specified I/O channel. 3773: 3774: @item @code{FD} +R -U -D 3775: Returns the UNIX file descriptor of the specified I/O channel. 3776: 3777: @item @code{MODE} +R -U -D 3778: Returns one of @code{READ}, @code{WRITE}, @code{READWRITE}, or @code{APPEND}, depending on the mode in which the specified I/O channel was opened. 3779: 3780: @item @code{EOF} +R -U -D 3781: Returns @code{1} if the I/O channel has encountered an end-of-file condition; @code{0} otherwise. Only valid if the I/O channel is connected to a sequential file. 3782: 3783: @item @code{LENGTH} +R -U -D 3784: Returns the length of the file connected to the I/O channel. Only valid if the I/O channel is connected to a sequential file. 3785: 3786: @item @code{NAMESPACE} +R -U -D 3787: Returns the current @emph{mnemonic-space} in use for the referenced I/O channel. Always @code{X364} for terminals and blank for sequential files. 3788: 3789: @item @code{TYPE} +R -U -D 3790: Returns either @code{1,FILE}, @code{2,SOCKET}, or @code{4,TERMINAL}, depending on the device type associated with the specified I/O channel. 3791: 3792: @item @code{OPTIONS} -R -U -D 3793: The following subscripts reside beneath @code{^$DEVICE(<io-channel>,"OPTIONS")}, and this subscript may not be accessed without one of the following third-level subscripts being specified: 3794: 3795: @table @asis 3796: 3797: @item @code{DSW} +R +U -D 3798: Sets or returns the current @emph{Device Status Word} controlling terminal characteristics. Only valid for I/O channel 0. 3799: 3800: @item @code{TERMINATOR} +R +U -D 3801: Sets or returns the @code{READ} terminator for the specified I/O channel. Must be either @code{$C(13,10)} or @code{$C(10)}. Currently only supported for socket devices (those having an I/O channel of 100-255). 3802: 3803: @item @code{TERMID} +R -U -D 3804: Returns the type of terminal connected to channel 0. Only valid for I/O channel 0. 3805: 3806: @item @code{ECHO} +R +U -D 3807: Enables or disables local echo of characters typed in a @code{READ} command. Only valid for I/O channel 0. Corresponds to bit 0 of the Device Status Word. 3808: 3809: @item @code{DELMODE} +R +U -D 3810: Enables or disables visual backspace during a @code{READ} command. Only valid for I/O channel 0. Corresponds to bit 2 of the Device Status Word. 3811: 3812: @item @code{ESCAPE} +R +U -D 3813: Enables or disables escape sequence processing during a @code{READ} command. Only valid for I/O channel 0. Corresponds to bit 6 of the Device Status Word. 3814: 3815: @item @code{CONVUPPER} +R +U -D 3816: Enables or disables automatic conversion to uppercase of alphabetical characters during a @code{READ} command. Only valid for I/O channel 0. Corresponds to bit 14 of the Device Status Word. 3817: 3818: @item @code{DELEMPTY} +R +U -D 3819: Enables or disables the automatic deletion of empty strings supplied to a @code{READ} command. Only valid for I/O channel 0. Corresponds to bit 19 of the Device Status Word. 3820: 3821: @item @code{NOCTRLS} +R +U -D 3822: TBD. Only valid for I/O channel 0. Corresponds to bit 20 of the Device Status Word. 3823: 3824: @item @code{CTRLOPROC} +R +U -D 3825: Enables or disables @emph{Ctrl-O} processing during @code{READ} commands. Only valid for I/O channel 0. Corresponds to bit 21 of the Device Status Word. 3826: 3827: @item @code{NOTYPEAHEAD} +R +U -D 3828: Enables or disables typeahead buffering during @code{READ} commands. Only valid for I/O channel 0. Corresponds to bit 25 of the Device Status Word. 3829: @end table 3830: @end table 3831: 3832: @emph{Example} 3833: 3834: The following example M code opens @code{/etc/freem.conf} and reads its contents line-by-line until the end of the file is reached. 3835: 3836: @example 3837: SET ^$JOB($JOB,"IOPATH")="/etc" ; set I/O path to /etc 3838: OPEN 1:"freem.conf/r" ; open freem.conf for reading 3839: ; 3840: ; read until we run out of lines 3841: ; 3842: FOR USE 1 READ LINE USE 0 QUIT:^$DEVICE(1,"EOF") D 3843: . WRITE LINE,! 3844: ; 3845: CLOSE 1 3846: QUIT 3847: @end example 3848: 3849: @node ^$DISPLAY 3850: @section ^$DISPLAY 3851: @cindex ^$DISPLAY 3852: @cindex structured system variables, ^$DISPLAY 3853: 3854: Provides information about the specified graphical display. The first subscript corresponds to a display number, which is an integer value, often corresponding to the current value of the @code{$PDISPLAY} ISV. 3855: 3856: The following second-level subscripts and specified descendant subscripts are supported: 3857: 3858: @table @asis 3859: 3860: @item @code{CLIPBOARD} +R +U +D 3861: Retrieves, sets, or erases the contents of the system clipboard. 3862: 3863: @item @code{PLATFORM} +R -U -D 3864: Retrieves the name and version of the underlying window system platform. 3865: 3866: @item @code{SIZE} +R -U -D 3867: Retrieves the display resolution of the specified graphical display. For instance, a 1080p display would have a @code{SIZE} value of @code{1920,1080}. 3868: 3869: @item @code{SPECTRUM} +R -U -D 3870: Retrieves the color depth (number of colors supported) of the specified graphical display. 3871: 3872: @item @code{COLORTYPE} +R -U -D 3873: Always returns @code{COLOR}, as monochrome and grayscale displays are not yet supported in FreeM. 3874: 3875: @item @code{UNITS} +R -U -D 3876: Returns the measurement unit of the specified display, i.e., @code{PIXEL}. 3877: 3878: @item @code{TYPEFACE} +R -U -D 3879: The third-level subscripts beneath this subscript represent a list of font families available on this display. The fourth level subscript is a list of sizes supported for the specified typeface, or @code{0} for vector typefaces, such as TrueType, OpenType, and Adobe Type 1 fonts. 3880: 3881: @end table 3882: 3883: @node ^$EVENT 3884: @section ^$EVENT 3885: @cindex ^$EVENT 3886: @cindex structured system variables, ^$EVENT 3887: 3888: The @code{^$EVENT} SSVN is not yet implemented. 3889: 3890: @node ^$GLOBAL 3891: @section ^$GLOBAL 3892: @cindex ^$GLOBAL 3893: @cindex structured system variables, ^$GLOBAL 3894: 3895: The @code{^$GLOBAL} structured system variable provides information about M globals. The first-level subscript is a global name, sans the leading caret symbol. 3896: 3897: The following second-level subscripts are supported: 3898: 3899: @table @asis 3900: 3901: @item @code{BYTES} +R -U -D 3902: Returns the number of bytes this global occupies in fixed storage. 3903: 3904: @item @code{BLOCKS} +R -U -D 3905: Returns the number of blocks contained in this global. 3906: 3907: @item @code{BLOCKSIZE} +R -U -D 3908: Returns the size of data blocks for this global. Currently, FreeM only supports 1024-byte blocks. 3909: 3910: @item @code{FILE} +R -U -D 3911: Returns the full filesystem path to the data file where this global resides in fixed storage. 3912: 3913: @item @code{NAMESPACE} +R +U +D 3914: Returns or sets the name of the FreeM namespace to which this global belongs. @code{SET}ting this node creates a mapping for the specified global name to a non-default namespace. @code{KILL}ing this node restores the mapping configuration for the specified global to the default. 3915: 3916: @end table 3917: 3918: @node ^$JOB 3919: @section ^$JOB 3920: @cindex ^$JOB 3921: @cindex structured system variables, ^$JOB 3922: 3923: FreeM fully implements @code{^$JOB} per ANSI X11.1-1995, as well as several extensions proposed in the M Millennium Draft Standard. 3924: 3925: The first subscript of @code{^$JOB} represents the @code{$JOB} of the process. 3926: 3927: If you @code{KILL} a first-level subscript of @code{^$JOB}, the @code{SIGTERM} signal will be sent to the corresponding UNIX process, causing pending transactions to be rolled back and the process to be terminated. If the targeted process is in direct mode, the user will be prompted with options of either rolling back or committing any pending transactions. 3928: 3929: The following subscripts are supported: 3930: 3931: @table @asis 3932: 3933: @item @code{GVNDEFAULT} +R +U +D 3934: Contains a default expression to be evaluated if a global variable access attempt results in an @code{M7} error. 3935: 3936: Equivalent to wrapping all global accesses in @code{$GET(@emph{global-name},@emph{string-expr})}. 3937: 3938: @item @code{LVNDEFAULT} +R +U +D 3939: Contains a default expression to be evaluated if a local variable access attempt results in an @code{M6} error. 3940: 3941: Equivalent to wrapping all local accesses in @code{$GET(@emph{global-name},@emph{string-expr})}. 3942: 3943: @item @code{LVNQOVAL} +R +U +D 3944: Contains the data value (if any) at the subscripted local variable reference from the most recent @code{$ORDER} or @code{$QUERY} operation. 3945: 3946: This node is useful for code that uses @code{$ORDER} or @code{$QUERY} heavily in loops that retrieve successive data values, as it will prevent an additional symbol table scan that would result from retrieving the data value in the usual way, thus improving application performance. However, this optimization comes at the cost of compatibility with other M implementations. 3947: 3948: @item @code{GVNQOVAL} +R +U +D 3949: Contains the data value (if any) at the subscripted global variable reference from the most recent @code{$ORDER} or @code{$QUERY} operation. 3950: 3951: This node is useful for code that uses @code{$ORDER} or @code{$QUERY} heavily in loops that retrieve successive data values, as it will prevent an additional data file scan that would result from retrieving the data value in the usual way, thus improving application performance. However, this optimization comes at the cost of compatibility with other M implementations. 3952: 3953: @item @code{ZCOMMANDS} +R +U -D 3954: Contains a space-delimited list of @code{Z}-commands to be treated as intrinsic. Any @code{Z}-command not appearing in this list will be treated as a user-defined command. 3955: 3956: For instance, if command @code{ZFOO} does @emph{not} appear in this list, FreeM will attempt to run @code{^%ZFOO} as a subroutine when the @code{ZFOO} command is encountered in program code. 3957: 3958: If you remove a command from this list, you may provide your own private M implementation of the command in the manner described above. 3959: 3960: If an argument is passed to a @code{Z}-command you implement in M, it is made available to your M code in a variable whose name is specified in @code{^$JOB($JOB,"ZCOMMAND_ARGUMENT_NAME")}, which defaults to @code{%}. 3961: 3962: @item @code{PIPE_GLVN} +R +U -D 3963: Contains an M local or global variable to be used as standard input or standard output for the external shell commands run by @code{!<} and @code{!>}. 3964: 3965: @item @code{ZCOMMAND_ARGUMENT_NAME} +R +U -D 3966: Returns or sets the variable name in which arguments to user-defined @code{Z}-commands are passed. Defaults to @code{%}. 3967: 3968: @item @code{ZFUNCTIONS} +R +U -D 3969: Contains a space-delimited list of @code{Z} functions to be treated as intrinsic. Any @code{Z} function not appearing in this list will be treated as a user-defined extrinsic function. 3970: 3971: For instance, if function @code{$ZFOO} does @emph{not} appear in this list, FreeM will attempt to return the value of @code{$$^%ZFOO} called as an extrinsic function. 3972: 3973: If you remove a function from this list, you may provide your own private M implementation of the function in the manner described above. 3974: 3975: @item @code{ZSVS} +R +U -D 3976: Contains a space-delimited list of @code{Z} special variables to be treated as intrinsic. Any @code{Z} special variable not appearing in this list will be treated as a user-defined extrinsic function taking no arguments. 3977: 3978: For instance, if the special variable @code{$ZFOO} does @emph{not} appear in this list, FreeM will attempt to return the value of @code{$$^%ZFOO} called as an extrinsic function. 3979: 3980: If you remove a built-in special variable from this list, you may provide your own private M implementation of the special variable in the manner described above. 3981: 3982: @item @code{BREAK_HANDLER} +R +U -D 3983: Contains M code to be executed when the @code{BREAK} command is run. 3984: 3985: @item @code{ROUTINE_BUFFER_SIZE} +R +U -D 3986: Returns or sets the number of bytes allocated to each routine buffer. If @code{ROUTINE_BUFFER_AUTO_ADJUST} is set to @code{0}, this determines the maximum size of routines that FreeM will execute. 3987: 3988: @item @code{ROUTINE_BUFFER_COUNT} +R +U -D 3989: Returns or sets the number of routine buffers that FreeM will store in memory concurrently. Raising this value will increase memory usage, but will also increase performance if your applications call many different routines repeatedly. 3990: 3991: @item @code{ROUTINE_BUFFER_AUTO_ADJUST} +R +U -D 3992: Determines whether or not the size of routine buffers will be automatically adjusted at runtime. If set to @code{0}, routine buffers will be fixed to the byte size specified in @code{ROUTINE_BUFFER_SIZE} and may be manually resized using @code{ROUTINE_BUFFER_SIZE}. If set to @code{1}, routine buffers will grow automatically as necessary. 3993: 3994: @item @code{SYMBOL_TABLE_SIZE} +R +U -D 3995: Returns or sets the number of bytes allocated to each of the two FreeM symbol tables. If @code{SYMBOL_TABLE_AUTO_ADJUST} is @code{1}, this value is treated as a default, initial size. If @code{SYMBOL_TABLE_AUTO_ADJUST} is @code{0}, this value controls the fixed size of the two symbol tables. 3996: 3997: @item @code{SYMBOL_TABLE_AUTO_ADJUST} +R +U -D 3998: Determines whether or not the size of the two FreeM symbol tables will be automatically adjusted at runtime. If set to @code{0}, the symbol table will be fixed to the byte size specified in @code{SYMBOL_TABLE_SIZE} and may be manually resized by modifying @code{SYMBOL_TABLE_SIZE}. If set to @code{1}, the two symbol tables will grow automatically as necessary. 3999: 4000: 4001: @item @code{USER_DEFINED_ISV_TABLE_SIZE} +R +U -D 4002: Returns or sets the number of bytes allocated to the FreeM user-defined intrinsic special variable table. If @code{USER_DEFINED_ISV_TABLE_AUTO_ADJUST} is @code{1}, this value is treated as a default, initial size. If @code{USER_DEFINED_ISV_TABLE_AUTO_ADJUST} is @code{0}, this value controls the fixed byte size of the user-defined intrinsic special variable table. 4003: 4004: @item @code{USER_DEFINED_ISV_TABLE_AUTO_ADJUST} +R +U -D 4005: Determines whether or not the size of the FreeM user-defined intrinsic special variable table will be automatically adjusted at runtime. If set to @code{0}, the user-defined ISV table will be fixed to the byte size specified in @code{USER_DEFINED_ISV_TABLE_SIZE} and may be manually resized by modifying @code{USER_DEFINED_ISV_TABLE_SIZE}. If set to @code{1}, the user-defined ISV table will grow automatically as necessary. 4006: 4007: @item @code{GVN_UNIQUE_CHARS} +R +U -D 4008: Returns or sets the number of characters of a global name that make it unique, from 1 to 255. 4009: 4010: @item @code{GVN_CASE_SENSITIVE} +R +U -D 4011: Returns or sets the case sensitivity of global names. If set to @code{0}, global names are case-insensitive. If set to @code{1}, global names are case-sensitive. 4012: 4013: @item @code{GVN_NAME_SUB_LENGTH} +R +U -D 4014: Returns or sets the maximum number of characters of a global name plus all of its subscripts, from 1-255. 4015: 4016: @item @code{GVN_SUB_LENGTH} +R +U -D 4017: Returns or sets the maximum number of characters of a single global subscript, from 1-255. 4018: 4019: @item @code{SINGLE_USER} +R +U -D 4020: If set to @code{1}, FreeM will skip all file locking operations on globals. If set to @code{0}, FreeM will enforce file locking on both. 4021: 4022: Setting @code{SINGLE_USER} to @code{1} will improve FreeM performance, but you must @emph{ONLY} use this on systems where you are absolutely sure that only one FreeM process will run at any given time, as running multiple instances of FreeM concurrently when any of them are set to @code{SINGLE_USER} mode @emph{will} cause global data corruption. 4023: 4024: @item @code{CHARACTER} +R -U -D 4025: Returns the character set of the job. 4026: 4027: @item @code{CWD} +R +U -D 4028: Returns or sets the current working directory of the job. 4029: 4030: @item @code{OPEN} +R -U -D 4031: The @code{^$JOB($JOB,"OPEN",<channel>} subscripts list the open I/O channels in the specified job. 4032: 4033: @item @code{BERKELEYDB,FLUSH_THRESHOLD} +R +U -D 4034: Returns or sets the number of write operations that will be cached in the BerkeleyDB global handler prior to flushing BerkeleyDB's cache to disk. 4035: 4036: @item @code{EVENT} +R +U +D 4037: The subtree contained under @code{^$JOB($J,"EVENT")} defines asynchronous event handlers for the current job. Please see @emph{Asynchronous Event Handling} for more information. 4038: 4039: @item @code{GLOBAL} +R -U -D 4040: Returns the global environment of the job. 4041: 4042: @item @code{IOPATH} +R +U -D 4043: Returns or sets the @emph{I/O path} to be used by the @code{OPEN} command. 4044: 4045: @item @code{PRIORITY} +R +U -D 4046: Returns or sets the @emph{nice} value of the FreeM job. 4047: 4048: @item @code{REVSTR} +R +U -D 4049: When set to 1, allows @code{$EXTRACT} to accept negative values. 4050: 4051: @item @code{ROUTINE} +R -U -D 4052: Returns the name of the routine currently being executed by the job. 4053: 4054: @item @code{SYMTAB} +R +U -D 4055: Returns or sets the current local variable symbol table in use. 4056: 4057: FreeM supports two unique and independent symbol tables, allowing FreeM programs to maintain two independent sets of identically- or differently-named local variables per process. 4058: 4059: The default symbol table is @code{0}, and the alternate symbol table is @code{1}, corresponding to the valid values for @code{^$JOB($JOB,"SYMTAB")}. 4060: 4061: Setting this subscript to values other than @code{0} or @code{1} will result in a @code{ZINVEXPR} error. 4062: 4063: @item @code{$PDISPLAY} +R -U -D 4064: Returns the value of @code{$PDISPLAY} for the job. 4065: 4066: @item @code{$PRINCIPAL} +R -U -D 4067: Returns the value of @code{$PRINCIPAL} for the job. 4068: 4069: @item @code{$TLEVEL} +R -U -D 4070: Returns the current transaction level (value of @code{$TLEVEL} for the job. 4071: 4072: @item @code{$IO} +R -U -D 4073: Returns the current value of @code{$IO} for the job. 4074: 4075: @item @code{USER} +R -U -D 4076: Returns the UID of the user owning the job. 4077: 4078: @item @code{GROUP} +R -U -D 4079: Returns the GID of the group owning the job. 4080: 4081: @item @code{NAMESPACE} +R +U -D 4082: Returns or sets the name of the job's currently-active namespace. 4083: 4084: @item @code{MATH} +R +U -D 4085: Returns or sets the mode in which decimal comparisons and arithmetic calculations are conducted. Valid values are @code{FIXED}, for fixed-point decimals having up to 20,000 digits of precision, as determined by the @code{$ZPRECISION} intrinsic special variable, and @code{IEEE754}, to use IEEE 754 floating-point decimals. When in @code{IEEE754} mode, floating-point numbers support up to 16 digits of numeric precision. 4086: 4087: @code{IEEE754} mode will make mathematical calculations significantly faster, especially when accelerated by a floating-point processor, at the expense of precision and accuracy. 4088: 4089: @code{FIXED} mode is recommended for financial calculations, or where precision and accuracy are valued over performance. @code{FIXED} is the default mode of FreeM operation. 4090: 4091: Attempting to @code{SET} this node to values other than @code{FIXED} or @code{IEEE754} will set @code{$ECODE} to @code{M29}. 4092: 4093: @end table 4094: 4095: @node ^$LOCK 4096: @section ^$LOCK 4097: @cindex ^$LOCK 4098: @cindex structured system variables, ^$LOCK 4099: 4100: The first-level subscript of @code{^$LOCK} is a lock name. The value at each node is the PID which owns the lock, a comma, and the lock counter for the locked resource. 4101: 4102: Attempting to @code{SET} or @code{KILL} any node in @code{^$LOCK} will raise error @code{M29}. 4103: 4104: @node ^$OBJECT 4105: @section ^$OBJECT 4106: @cindex ^$OBJECT 4107: @cindex structured system variables, ^$OBJECT 4108: 4109: @node ^$ROUTINE 4110: @section ^$ROUTINE 4111: @cindex ^$ROUTINE 4112: @cindex structured system variables, ^$ROUTINE 4113: 4114: The @code{^$ROUTINE} SSVN exposes a list of routines available in the current FreeM namespace, as well as additional attributes further describing each routine. 4115: 4116: The first-level subscript is the name of a FreeM routine minus the leading caret symbol. 4117: 4118: The following second-level subscripts are supported: 4119: 4120: @table @asis 4121: 4122: @item @code{CHARACTER} +R -U -D 4123: Returns the character set of the routine. 4124: 4125: @item @code{NAMESPACE} +R -U -D 4126: Returns the name of the FreeM namespace in which the routine resides. 4127: 4128: @item @code{PATH} +R -U -D 4129: Returns the full filesystem path to the routine in fixed storage. 4130: 4131: @end table 4132: 4133: @node ^$SYSTEM 4134: @section ^$SYSTEM 4135: @cindex ^$SYSTEM 4136: @cindex structured system variables, ^$SYSTEM 4137: 4138: The @code{^$SYSTEM} SSVN exposes system-level implementation details. 4139: 4140: The following first-level subscripts are supported: 4141: 4142: @table @asis 4143: 4144: @item @code{DEFPSIZE} +R -U -D 4145: Returns the default size in bytes of the symbol table and routine buffer memory partition. 4146: 4147: @item @code{DEFUDFSVSIZ} +R -U -D 4148: Returns the default size in bytes of the user-defined intrinsic special variable table. 4149: 4150: @item @code{DEFNSIZE} +R -U -D 4151: Returns the default size of the @code{NEW} stack, in number of entries. 4152: 4153: @item @code{MAXNO_OF_RBUF} +R -U -D 4154: Returns the maximum number of routine buffers. 4155: 4156: @item @code{DEFNO_OF_RBUF} +R -U -D 4157: Returns the default number of routine buffers. 4158: 4159: @item @code{DEFPSIZE0} +R -U -D 4160: Returns the default size in bytes of each routine buffer. 4161: 4162: @item @code{NO_GLOBLS} +R -U -D 4163: Returns the maximum number of globals that can be concurrently opened. 4164: 4165: @item @code{NO_OF_GBUF} +R -U -D 4166: Returns the number of global buffers. 4167: 4168: @item @code{NESTLEVLS} +R -U -D 4169: Returns the depth of the @code{DO}, @code{FOR}, @code{XECUTE} stack. 4170: 4171: @item @code{PARDEPTH} +R -U -D 4172: Returns the maximum depth of the parser's parameter stack. 4173: 4174: @item @code{PATDEPTH} +R -U -D 4175: Returns the maximum number of @emph{patatom}s in each pattern. 4176: 4177: @item @code{TRLIM} +R -U -D 4178: Returns the trace limit of the @code{BUILTIN} global handler. 4179: 4180: @item @code{ARGS_IN_ESC} +R -U -D 4181: Returns the maximum number of arguments in a terminal escape sequence. 4182: 4183: @item @code{ZTLEN} +R -U -D 4184: Returns the maximum length of @code{$ZTRAP}. 4185: 4186: @item @code{FUNLEN} +R -U -D 4187: Returns the maximum length of the @code{$ZF} (function key) variable. 4188: 4189: @item @code{NAME_LENGTH} +R -U -D 4190: Returns the maximum length of variable names in the current FreeM build. Compatible with the same SSVN node in @emph{Reference Standard M} 4191: 4192: @item @code{STRING_MAX} +R -U -D 4193: Returns the maximum length of character strings in the current FreeM build. Compatible with the same SSVN node in @emph{Reference Standard M} 4194: 4195: @item @code{$NEXTOK} +R -U -D 4196: Returns a value indicating whether or not the @code{$NEXT} intrinsic function is allowed. In FreeM, @code{$NEXT} is always enabled, and this SSVN is provided solely for compatibility with @emph{Reference Standard M}. Thus, this SSVN node always returns @code{1}. 4197: 4198: @item @code{EOK} +R -U -D 4199: Returns a value indicating whether or not @code{E} notation for exponents is allowed. In FreeM, this feature is always enabled, and this SSVN is provided solely for compatibility with @emph{Reference Standard M}. Thus, this SSVN node always returns @code{1}. 4200: 4201: @item @code{OFFOK} +R -U -D 4202: Returns a value indicating whether or not offsets are allowed in @code{DO} and @code{GOTO}. In FreeM, this feature is always enabled, and this SSVN is provided solely for compatibility with @emph{Reference Standard M}. Thus, this SSVN node always returns @code{1}. 4203: 4204: @item @code{BIG_ENDIAN} +R -U -D 4205: Returns a 1 if FreeM is running on a big-endian platform, or a 0 otherwise. Compatible with the same SSVN node in @emph{Reference Standard M}. 4206: 4207: @item @code{NAMESPACE} +R -U -D 4208: The descendant subscripts of this node list each namespace in the current FreeM environment. 4209: 4210: @item @code{MAPPINGS,GLOBAL} +R -U -D 4211: Descendant subscripts of this node represent global name mappings set in @code{^$GLOBAL(@emph{gvn},"NAMESPACE")} 4212: 4213: @end table 4214: 4215: @node ^$WINDOW 4216: @section ^$WINDOW 4217: @cindex ^$WINDOW 4218: @cindex structured system variables, ^$WINDOW 4219: 4220: The @code{^$WINDOW} SSVN has no nodes yet defined. However, completing a @code{MERGE} to this SSVN will cause MWAPI-ish things to happen, and further work is proceeding on MWAPI implementation. 4221: 4222: @node ^$ZPROCESS 4223: @section ^$ZPROCESS 4224: @cindex ^$ZPROCESS 4225: @cindex structured system variables, ^$ZPROCESS 4226: 4227: Provides access to @code{procfs}, which is a filesystem-like abstraction for UNIX process metadata contained in @code{/proc}, as well as features for examining and controlling the state of processes external to the FreeM interpreter. 4228: 4229: The first subscript always represents the @emph{process ID} of the external process being acted upon. 4230: 4231: The following values for the second subscript are supported: 4232: 4233: 4234: @table @asis 4235: 4236: @item @code{EXISTS} +R -U -D 4237: Returns 1 if the referenced process exists; 0 otherwise. 4238: 4239: @item @code{ATTRIBUTE} +R -U -D 4240: Exposes the @code{/proc} files as descendant subscripts, i.e., @code{WRITE ^$ZPROCESS(2900,"ATTRIBUTE","cmdline"),!} would print the initial command line used to invoke process ID 2900. Note that the third subscript (the immediate descendant of the @code{ATTRIBUTE} subscript) is case sensitive. 4241: 4242: @item @code{SIGNAL} -R +U -D 4243: Allows signals to be sent to the referenced process. The following subscript is an integer value corresponding to the desired signal number. You may obtain a list of signal numbers on most UNIX systems with the command @code{kill -l}. 4244: 4245: The constants @code{%SYS.SIGNAL.HUP}, @code{%SYS.SIGNAL.INT}, @code{%SYS.SIGNAL.KILL}, and @code{%SYS.SIGNAL.TERM} are provided for convenient use of this SSVN subscript. 4246: 4247: @end table 4248: 4249: @node ^$ZRPI 4250: @section ^$ZRPI 4251: @cindex ^$ZRPI 4252: @cindex structured system variables, ^$ZRPI 4253: 4254: The @code{^$ZRPI} structured system variable provides easy access to general-purpose input/output (GPIO) pins on Raspberry Pi single-board computers. 4255: 4256: To initialize the GPIO subsystem, @code{SET ^$ZRPI("INITIALIZE")=1}. 4257: 4258: Individual pins are accessed through @code{^$ZRPI("GPIO",<pin>,...)}, where @code{<pin>} represents the desired pin number. Descendant subscripts of @code{^$ZRPI("GPIO",<pin>)} are as follows: 4259: 4260: @table @asis 4261: 4262: @item @code{MODE} +R +U -D 4263: Represents the operating mode of the selected pin. One of @code{INPUT}, @code{OUTPUT}, @code{PWM_OUTPUT}, or @code{GPIO_CLOCK}. 4264: 4265: @item @code{DIGITAL} +R +U -D 4266: Reads or writes the selected pin digitally. The value is limited to @code{1} or @code{0}. 4267: 4268: @item @code{ANALOG} +R +U -D 4269: Reads or writes the selected pin in an analog fashion. The value represents analog voltage. 4270: 4271: @end table 4272: 4273: @node Operators 4274: @chapter Operators 4275: 4276: @menu 4277: * Unary +:: Force a value to positive. 4278: * Unary -:: Force a value to negative. 4279: * +:: Add. 4280: * +=:: Add and assign. 4281: * ++:: Postfix increment. 4282: * -:: Subtract. 4283: * -=:: Subtract and assign. 4284: * --:: Postfix decrement. 4285: * *:: Multiply. 4286: * *=:: Multiply and assign. 4287: * /:: Divide. 4288: * /=:: Divide and assign. 4289: * \:: Integer divide. 4290: * \=:: Integer divide and assign. 4291: * #:: Modulo. 4292: * #=:: Modulo and assign. 4293: * **:: Exponentiate. 4294: * **=:: Exponentiate and assign. 4295: * <:: Less than. 4296: * <=:: Less than or equal to. 4297: * >:: Greater than. 4298: * >=:: Greater than or equal to. 4299: * _:: Concatenate. 4300: * _=:: Concatenate and assign. 4301: * =:: Equals. 4302: * [:: Contains. 4303: * ]:: Follows. 4304: * ]]:: Sorts after. 4305: * ?:: Pattern match. 4306: * &:: Logical AND. 4307: * ! (Operator):: Logical OR. 4308: * ':: Logical NOT. 4309: * @@ (Operator):: Indirect 4310: @end menu 4311: 4312: @node Unary + 4313: @section Unary + 4314: @cindex operators, unary + 4315: 4316: Forces a number to positive, whether positive or negative. Also forces numeric coercion of strings. 4317: 4318: @node Unary - 4319: @section Unary - 4320: @cindex operators, unary - 4321: 4322: Forces a number to negative, whether positive or negative. Also forces numeric coercion of strings. 4323: 4324: @node + 4325: @section + (Add) 4326: @cindex operators, + 4327: 4328: @emph{Syntax} 4329: 4330: @example 4331: S X=1+2 ; => 3 4332: @end example 4333: 4334: Adds numbers together. 4335: 4336: @node += 4337: @section += (Add/Assign) 4338: @cindex operators, += 4339: 4340: @emph{Syntax} 4341: 4342: @example 4343: S X=5 4344: S X+=3 ; => 8 4345: @end example 4346: 4347: Increments the variable on the LHS by the value on the RHS. 4348: 4349: @node ++ 4350: @section ++ (Postfix Increment) 4351: @cindex operators, ++ 4352: 4353: Increments a variable by 1. 4354: 4355: @node - 4356: @section - (Subtract) 4357: @cindex operators, - 4358: 4359: Subtracts one number from another. 4360: 4361: @node -= 4362: @section -= (Subtract/Assign) 4363: @cindex operators, -= 4364: 4365: @emph{Syntax} 4366: 4367: @example 4368: S X=5 4369: S X-=3 ; => 2 4370: @end example 4371: 4372: Decrements the variable on the LHS by the value on the RHS. 4373: 4374: @node -- 4375: @section -- (Postfix Decrement) 4376: @cindex operators, -- 4377: 4378: Decrements the variable by one. 4379: 4380: @node * 4381: @section * (Multiply) 4382: @cindex operators, * 4383: 4384: Multiplies one number by another. 4385: 4386: @node *= 4387: @section *= (Multiply/Assign) 4388: @cindex operators, *= 4389: 4390: 4391: 4392: @node / 4393: @section / (Divide) 4394: @cindex operators, / 4395: 4396: @node /= 4397: @section /= (Divide/Assign) 4398: @cindex operators, /= 4399: 4400: @node \ 4401: @section \ (Integer Divide) 4402: @cindex operators, \ 4403: 4404: @node \= 4405: @section \= (Integer Divide/Assign) 4406: @cindex operators, \= 4407: 4408: @node # 4409: @section # (Modulo) 4410: @cindex operators, # 4411: 4412: @node #= 4413: @section #= (Modulo/Assign) 4414: @cindex operators, #= 4415: 4416: @node ** 4417: @section ** (Exponentiate) 4418: @cindex operators, ** 4419: 4420: @node **= 4421: @section **= (Exponentiate/Assign) 4422: @cindex operators, **= 4423: 4424: @node < 4425: @section < (Less Than) 4426: @cindex operators, < 4427: 4428: @node <= 4429: @section <= (Less Than or Equal To) 4430: @cindex operators, <= 4431: 4432: @node > 4433: @section > (Greater Than) 4434: @cindex operators, > 4435: 4436: @node >= 4437: @section >= (Greater Than or Equal To) 4438: @cindex operators, >= 4439: 4440: @node _ 4441: @section _ (Concatenate) 4442: @cindex operators, _ 4443: 4444: @node _= 4445: @section _= (Concatenate/Assign) 4446: @cindex operators, _= 4447: 4448: @node = 4449: @section = (Equals) 4450: @cindex operators, = 4451: 4452: @node [ 4453: @section [ (Contains) 4454: @cindex operators, [ 4455: 4456: @node ] 4457: @section ] (Follows) 4458: @cindex operators, ] 4459: 4460: @node ]] 4461: @section ]] (Sorts After) 4462: @cindex operators, ]] 4463: 4464: @node ? 4465: @section ? (Pattern Match) 4466: @cindex operators, ? 4467: 4468: @node & 4469: @section & (Logical AND) 4470: @cindex operators, & 4471: 4472: @node ! (Operator) 4473: @section ! (Logical OR) 4474: @cindex operators, ! 4475: 4476: @node ' 4477: @section ' (Logical NOT) 4478: @cindex operators, ' 4479: 4480: @node @@ (Operator) 4481: @section @@ (Indirect) 4482: @cindex operators, @@ 4483: 4484: @node Routines 4485: @chapter Routines 4486: @cindex routines 4487: 4488: A @emph{routine} is a file containing M source code to be processed by FreeM. 4489: 4490: Routines exist within a @emph{namespace} (such as @code{SYSTEM} or @code{USER}), which in turn exist within an @emph{environment} (such as @code{DEFAULT}). 4491: 4492: @menu 4493: * Routine Naming:: Requirements and conventions for routine names. 4494: @end menu 4495: 4496: 4497: @node Routine Naming 4498: @section Routine Naming 4499: The routine's filename follows the format @code{NAME.m}, where @code{NAME} is the name of the routine, and @code{.m} is the filename extension. 4500: 4501: Routine naming rules are as follows: 4502: 4503: @itemize @bullet 4504: @item Routine names must begin with an upper- or lower-case letter, or a @code{%} sign 4505: @item Within the routine name, you may have upper-case or lower-case letters or digits 4506: @item The entire routine name must not be longer than 255 characters 4507: @end itemize 4508: 4509: Routines whose names begin with @code{%} must be located in the @code{SYSTEM} namespace. Other routines may be located in any namespace. 4510: 4511: @node Types 4512: @chapter Types 4513: @cindex types 4514: @cindex data types 4515: 4516: FreeM supports all @emph{libdatatype} types defined in the former MDC's @emph{Millennium Draft Standard}, with the exception of @code{MATRIX}, and with extensions supporting object-oriented programming. A notable enhancement in FreeM is that the library data types can be used in the @emph{formallist} of any extrinsic function or subroutine; not only in @emph{libraryelement}s. 4517: 4518: @menu 4519: * BOOLEAN:: Truth values. 4520: * COMPLEX:: Numbers with real and imaginary parts. 4521: * INTEGER:: Numbers with no decimal part. 4522: * REAL:: Numbers with a decimal part. 4523: * STRING:: Arbitrary strings of characters. 4524: * Custom Types (Classes):: User-defined, object-oriented types. 4525: @end menu 4526: 4527: @node BOOLEAN 4528: @section BOOLEAN 4529: @cindex data types, BOOLEAN 4530: @cindex types, BOOLEAN 4531: 4532: The @code{BOOLEAN} type represents any M value that can be interpreted as a truth-value. 4533: 4534: @node COMPLEX 4535: @section COMPLEX 4536: @cindex data types, COMPLEX 4537: @cindex types, COMPLEX 4538: 4539: The @code{COMPLEX} type is a complex number represented as a string in the format @code{@emph{<real-part>}%@emph{<imaginary-part>}}, where @emph{real-part} and @emph{imaginary-part} are both @code{REAL} numbers. See @ref{REAL} for more information. 4540: 4541: FreeM will attempt to interpret any @code{COMPLEX} value according to the usual rules for M canonical numbers, i.e., the string @code{sabc123.345%fbd3.1} would be interpreted as a complex number with the real part being @code{123.345} and the imaginary part being @code{3.1}. 4542: 4543: @node INTEGER 4544: @section INTEGER 4545: @cindex data types, INTEGER 4546: @cindex types, INTEGER 4547: 4548: An @code{INTEGER} is an interpretation of numeric data with any fractional part removed. 4549: 4550: @node REAL 4551: @section REAL 4552: @cindex data types, REAL 4553: @cindex types, REAL 4554: 4555: A @code{REAL} is a numeric interpretation of data including a fractional part. 4556: 4557: @node STRING 4558: @section STRING 4559: @cindex data types, STRING 4560: @cindex types, STRING 4561: 4562: The @code{STRING} is the fundamental FreeM data type. Other types are inferred from the context of their usage. 4563: 4564: @subsection String Rules 4565: 4566: The following rules apply to all FreeM strings: 4567: 4568: @itemize 4569: @item Must not exceed 255 characters 4570: @item Must not contain @code{$C(0)}, @code{$C(201)}, or @code{$C(202)} 4571: @end itemize 4572: 4573: @subsection String Quoting Rules 4574: Strings in FreeM must be surrounded in double quotes: 4575: 4576: @example 4577: SET MYSTRING="This is a string literal" 4578: @end example 4579: 4580: If you want to include double quotes inside of a string, simply double them: 4581: 4582: @example 4583: SET MYSTRING="This is a ""string literal"" with embedded double quotes" 4584: @end example 4585: 4586: 4587: @node Custom Types (Classes) 4588: @section Custom Types (Classes) 4589: @cindex data types, custom 4590: @cindex types, custom 4591: @cindex classes 4592: 4593: See @ref{Object-Oriented Programming}. 4594: 4595: @node Globals 4596: @chapter Globals 4597: @cindex globals 4598: @cindex variables, global 4599: @cindex data 4600: 4601: @menu 4602: * Globals Overview:: Basics of FreeM persistent storage. 4603: * Creating Globals:: How to create globals. 4604: * Removing Globals:: How to remove globals. 4605: * Global Storage:: How globals are stored. 4606: @end menu 4607: 4608: @node Globals Overview 4609: @section Globals Overview 4610: 4611: FreeM supports typical M globals, which are often described as persistent, hierachical sparse arrays. Globals make it relatively simple to include persistent data in an application without requiring the developer to use an external database management system, and offer syntax and semantics so similar to M local variables and structured system variables that moving from one to the other is seamless. 4612: 4613: Each global comprises three elements: 4614: 4615: @itemize @bullet 4616: @item 4617: An alphabetic name beginning with a caret (@code{^}) or a caret and a percent sign (@code{^%}) 4618: @item 4619: Optionally, one or more comma-delimited subscripts, enclosed in parentheses 4620: @item 4621: A value of up to 255 characters in length 4622: @end itemize 4623: 4624: A leading percent sign in the global name will force the named global into the @code{SYSTEM} namespace of the current FreeM environment. 4625: 4626: @node Creating Globals 4627: @section Creating Globals 4628: @cindex globals, creating 4629: 4630: To create a global, you can use the @code{SET} command: 4631: 4632: @example 4633: SET ^MYGLOBAL("foo","bar")="this is the data value" 4634: @end example 4635: 4636: @node Removing Globals 4637: @section Removing Globals 4638: @cindex globals, removing 4639: 4640: To remove an entire global, you can use the @code{KILL} command with the unsubscripted name of the global: 4641: 4642: @example 4643: KILL ^MYGLOBAL 4644: @end example 4645: 4646: If you only want to remove part of a global, i.e., beginning at a certain subscript level, use the @code{KILL} command with a subscripted name: 4647: 4648: @example 4649: KILL ^MYGLOBAL("foo") 4650: @end example 4651: 4652: This will remove only the @code{"foo"} subscript and all of its children. 4653: 4654: If you only want to remove the data value at a specific subscript level, leaving the subscript itself intact, use @code{KVALUE}: 4655: 4656: @example 4657: KVALUE ^MYGLOBAL("foo") 4658: @end example 4659: 4660: @node Global Storage 4661: @section Global Storage 4662: @cindex globals, storage 4663: 4664: FreeM globals are stored in @code{$PREFIX/var/freem/@emph{<environment-name>}/@emph{<namespace-name>}/globals} in a binary format. 4665: 4666: Global files have a header of the following format: 4667: 4668: @verbatim 4669: typedef struct global_header { 4670: 4671: char magic[5]; /* FRMGL */ 4672: int format_version; 4673: char host_triplet[40]; 4674: char host_id[256]; 4675: 4676: unsigned long block_size; 4677: unsigned long last_transaction_id; 4678: 4679: long created; 4680: long last_backup; 4681: 4682: } global_header; 4683: @end verbatim 4684: 4685: @node Concurrency Control 4686: @chapter Concurrency Control 4687: @cindex concurrency control 4688: @cindex locking 4689: @cindex transaction processing 4690: 4691: @menu 4692: * Concurrency Control Overview:: Basics of concurrency control. 4693: * Advisory Locks:: Coordinating access voluntarily. 4694: * Transaction Processing:: Ensuring logical consistency. 4695: @end menu 4696: 4697: @node Concurrency Control Overview 4698: @section Concurrency Control Overview 4699: 4700: Multitasking, multi-user FreeM applications must concern themselves with conscientious management of concurrent access to globals in order to maintain logical consistency and prevent concurrent reads and writes from conflicting with each other. 4701: 4702: In FreeM, there are two mechanisms provided for managing concurrent global access: @emph{advisory locks}, and @emph{transaction processing}. 4703: 4704: Advisory locks allow applications to voluntarily coordinate concurrent access to globals with the @code{LOCK} command, and require each application to check the @code{LOCK} status prior to accessing a global. 4705: 4706: Transaction processing allows applications to delineate sets of global operations (sets, kills, etc.) as being part of a transaction, in which no operations are performed against the globals contained within the transaction until the transaction is committed. In addition, processes other than the one running the transaction will be forced to wait to access globals for either the duration of the commit phase (@emph{batch mode}), or for the entire duration of the transaction (@emph{serial mode}). 4707: 4708: @node Advisory Locks 4709: @section Advisory Locks 4710: 4711: @node Transaction Processing 4712: @section Transaction Processing 4713: @cindex transaction processing 4714: 4715: FreeM implements a significant subset of the transaction processing features from @emph{ANSI X11.1-1995}. This allows a series of global operations to be conducted all at once, either in batch mode (where concurrent operation is not interrupted until the last possible moment), or in serial mode (where writes are guaranteed to be atomic, consistent, isolated, and durable). 4716: 4717: @subsection Theory of Operation 4718: 4719: FreeM uses a pessimistic concurrency control mechanism for @code{SERIAL} transactions, meaning that any @code{TSTART} command that includes the @code{SERIAL} transaction parameter will cause the process to acquire the transaction processing mutex, which prevents any process but the one holding the mutex from performing any data access (read or write) until either @code{TCOMMIT} or @code{TROLLBACK} is called, either committing or rolling back the transaction, respectively. 4720: 4721: Any transaction in between its @code{TSTART} and @code{TCOMMIT}/@code{TROLLBACK} is said to be @emph{in-flight}. During the in-flight stage, pending global operations are held only in memory and after-image journals. 4722: 4723: FreeM maintains a list of all globals affected during a transaction in-flight. When a @code{TCOMMIT} is reached, FreeM will generate a @emph{checkpoint} of each global data file to be changed by the transaction. These checkpoints allow all FreeM globals to be restored to their pre-transaction state if a @code{TCOMMIT} should fail part of the way through its operation. 4724: 4725: Checkpoints can have one of two modes: 4726: 4727: @table @asis 4728: 4729: @item @code{CP_REMOVE} 4730: Used for globals that did not exist prior to the beginning of this transaction. Simply marks the entire global data file for deletion in case of @code{TCOMMIT} failure. 4731: 4732: @item @code{CP_RESTORE} 4733: Used for globals that @emph{did} exist prior to the beginning of this transaction. In this case, the entire global data file is copied to a new file with a @code{.chk} extension. In cases of @code{TCOMMIT} failure, @code{CP_RESTORE} checkpoint files will be restored over the partially-modified live data file. 4734: 4735: @end table 4736: 4737: The below example shows a few global operations and checkpoints for a transaction in-flight using the @code{trantab} direct-mode command: 4738: 4739: @verbatim 4740: TL1:DEFAULT.USER> trantab 4741: $TLEVEL 1* 4742: Operations for Transaction ID: 6ea14aad-b8f1-47f9-9f52-4f513f892bc0 [RESTARTABLE SERIAL] 4743: 4744: OP. NO. ACTION KEY/DATA 4745: ------- ------ -------- 4746: 1 SET ^FOO=3 4747: 2 KILL ^FOO 4748: 3 SET ^snw=10 4749: 4 SET ^BRANDNEW=6 4750: 4751: Global checkpoints: 4752: 4753: GLOBAL MODE FILES 4754: ------ ---- ----- 4755: ^BRANDNEW CP_REMOVE IN: /usr/local/var/freem/USER/globals/^BRANDNEW 4756: ^snw CP_RESTORE IN: /usr/local/var/freem/USER/globals/^snw 4757: OUT: /usr/local/var/freem/USER/globals/^snw.23390.1.chk 4758: ^FOO CP_RESTORE IN: /usr/local/var/freem/USER/globals/^FOO 4759: OUT: /usr/local/var/freem/USER/globals/^FOO.23390.1.chk 4760: @end verbatim 4761: 4762: In the above example, @code{IN} files are the live data file that will be overwritten or removed, and @code{OUT} files are the checkpoints themselves. Note that @code{OUT} files are only used for @code{CP_RESTORE} checkpoints. 4763: 4764: @subsection Using Transaction Processing 4765: 4766: To use transactions in FreeM, you need to be familiar with three commands: 4767: 4768: @itemize @bullet 4769: @item 4770: @code{TSTART} 4771: @item 4772: @code{TCOMMIT} 4773: @item 4774: @code{TROLLBACK} 4775: @end itemize 4776: 4777: With transaction processing, global variable operations occurring between @code{TSTART} and @code{TCOMMIT} commands will be contained within the transaction. 4778: 4779: The atomicity, consistency, isolation, and durability facets of FreeM transaction hinge on the transaction mode. 4780: 4781: @subsubsection BATCH Transactions 4782: @code{BATCH} transactions offer higher performance, and allow other applications aside from the one doing the transaction to continue normal operations until the transaction is committed with @code{TCOMMIT}. In batch mode, other processes are only locked out of normal operation during the commit phase of the transaction. 4783: 4784: The effect of this is that the operations within the batch transaction will not be interleaved with global writes from other applications, but the entire lifetime of the transaction is not guaranteed to be serialized with respect to the transaction processing activities of other running applications in the environment. 4785: 4786: @subsubsection SERIAL Transactions 4787: @code{SERIAL} transactions offer full ACID compliance at the expense of multiprocessing performance. In serial mode, a @code{TSTART} blocks all activity from all other FreeM processes in the environment, and this blocking effect is not released until the transaction is committed with @code{TCOMMIT} or rolled back with @code{TROLLBACK} (or due to abnormal conditions in the environment that preclude the successful completion of the transaction). 4788: 4789: @node Local Variables 4790: @chapter Local Variables 4791: @cindex variables, local 4792: @cindex local variables 4793: 4794: @menu 4795: * Local Variables Overview:: The basics of locals. 4796: * Creating Local Variables:: Creating locals with SET. 4797: * Removing Local Variables:: Removing locals with KILL. 4798: @end menu 4799: 4800: @node Local Variables Overview 4801: @section Local Variables Overview 4802: 4803: FreeM @emph{local variables} have the same data structure as global variables, but are scoped to a single FreeM process, and stored in memory. 4804: 4805: Each local comprises three elements: 4806: 4807: @itemize @bullet 4808: @item 4809: An alphabetic name beginning with a letter or a percent sign (@code{%}) 4810: @item 4811: Optionally, one or more comma-delimited subscripts, enclosed in parentheses 4812: @item 4813: A value of up to 255 characters in length 4814: @end itemize 4815: 4816: @node Creating Local Variables 4817: @section Creating Local Variables 4818: @cindex local variables, creating 4819: 4820: To create a local variable, use the @code{SET} command: 4821: 4822: @example 4823: SET MYLOCAL("foo","bar")="this is the data value" 4824: @end example 4825: 4826: @node Removing Local Variables 4827: @section Removing Local Variables 4828: @cindex local variables, removing 4829: 4830: To remove an entire local variable, you can use the @code{KILL} command with the unsubscripted name of the variable: 4831: 4832: @example 4833: KILL MYLOCAL 4834: @end example 4835: 4836: If you only want to remove part of a local variable, i.e., beginning at a certain subscript level, use the @code{KILL} command with a subscripted name: 4837: 4838: @example 4839: KILL MYLOCAL("foo") 4840: @end example 4841: 4842: This will remove only the @code{"foo"} subscript and all of its children. 4843: 4844: If you only want to remove the data value at a specific subscript level, leaving the subscript itself intact, use @code{KVALUE}: 4845: 4846: @example 4847: KVALUE MYLOCAL("foo") 4848: @end example 4849: 4850: @node Scoping 4851: @chapter Scoping 4852: @cindex scoping 4853: 4854: By default, FreeM local variables and their values are scoped to the entire process, meaning that any function or subroutine can access and modify their values. This can lead to pernicious bugs. 4855: 4856: M provides the @code{NEW} command to work around these issues. When @code{NEW} is called with a local variable as its argument, FreeM will scope the variable to the process stack frame in which the @code{NEW} command occured. When exiting the stack frame (i.e. with the @code{QUIT} command), FreeM will restore the variable to its value prior to being @code{NEW}ed. 4857: 4858: @emph{Example} 4859: 4860: @example 4861: MYRTN ; 4862: S J=1 ; set local variable J to 1 4863: W J,! ; this will output "1" 4864: D X ; execute subroutine X 4865: W J,! ; this will output "1", as the value of J was restored 4866: Q 4867: ;; 4868: X ; 4869: N J ; stack J 4870: S J=6 ; set its value to 6 4871: W J,! ; this will output "6" 4872: Q ; quit from the subroutine, destroying its stack frame 4873: ;; 4874: @end example 4875: 4876: @section Scoping Considerations for $TEST 4877: 4878: In M, the truth value of comparisons, logic operations, and certain forms of @code{LOCK} is stored in the @code{$TEST} intrinsic special variable, which follows the same rules as any M local variable. 4879: 4880: This is probably the most significant design flaw of the language, as the side effects of logic on @code{$TEST} lead to incredibly difficult bugs. However, M allows @code{$TEST} to be @code{NEW}ed, and FreeM provides the @code{THEN} command@footnote{From MDC Type A extension X11/1998-31} to help in the case of conditionals. @code{THEN} stacks @code{$TEST} to the end of the line. 4881: 4882: When writing new M code in FreeM, we strongly suggest using @code{THEN} as follows: 4883: 4884: @example 4885: MYRTN ; 4886: IF MYVAR=1 THEN DO SUBRT 4887: @end example 4888: 4889: This is instead of the traditional form: 4890: 4891: @example 4892: MYRTN ; 4893: IF MYVAR=1 DO SUBR 4894: @end example 4895: 4896: @cartouche 4897: @quotation 4898: @emph{Style Recommendation} 4899: 4900: Note that @code{THEN} is not in any currently published version of the @emph{Standard}, but is part of MDC Type A extension X11/1998-31. However, we recommend using @code{THEN} instead of favoring portability, as there is no defensible reason for this incredibly simple feature @emph{not} to be ubiquitous. 4901: 4902: If you use other M implementations, you should bug the implementers to implement @code{THEN}, as it at least partially mitigates an inexcusable flaw in the design of M. 4903: @end quotation 4904: @end cartouche 4905: 4906: @node Decision Constructs 4907: @chapter Decision Constructs 4908: @cindex decision constructs 4909: @cindex IF 4910: @cindex ELSE 4911: @cindex THEN 4912: @cindex postconditionals 4913: 4914: @node Branch Constructs 4915: @chapter Branch Constructs 4916: @cindex branch constructs 4917: @cindex DO 4918: @cindex GOTO 4919: @cindex JOB 4920: 4921: @node Loop Constructs 4922: @chapter Loop Constructs 4923: @cindex loop constructs 4924: @cindex FOR 4925: 4926: @node Modular Programming 4927: @chapter Modular Programming 4928: @cindex modular programming 4929: @cindex functions, extrinsic 4930: @cindex subroutines 4931: 4932: @menu 4933: * Subroutines:: Making sections of code reusable. 4934: * Extrinsic Functions:: Reusable code that returns a value. 4935: @end menu 4936: 4937: @node Subroutines 4938: @section Subroutines 4939: 4940: @node Extrinsic Functions 4941: @section Extrinsic Functions 4942: 4943: @node Object-Oriented Programming 4944: @chapter Object-Oriented Programming 4945: @cindex object-oriented programming 4946: @cindex programming, object-oriented 4947: 4948: @menu 4949: * Classes:: The organizing concept of object-oriented programming. 4950: * Inheritance:: Making one class derive from another. 4951: * Methods:: Attach code to classes. 4952: * Public and Private Variables:: Determining accessibility. 4953: * Instantiating Objects:: Creating instances of classes. 4954: @end menu 4955: 4956: @node Classes 4957: @section Classes 4958: @subsection Class Overview 4959: 4960: A @emph{class} is the primary organizing concept of FreeM support for object-oriented programming, and in FreeM, is simply an M routine with a few special properties: 4961: 4962: @example 4963: MYCLASS(THIS,INIT):OBJECT ; Constructor for MYCLASS, inherits OBJECT 4964: ; two private variables 4965: S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) 4966: S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) 4967: Q 4968: ; 4969: DESTROY(THIS) ; This is the destructor 4970: Q 4971: @end example 4972: 4973: The above example demonstrates general class syntax. 4974: 4975: @subsection Constructors 4976: 4977: A @emph{constructor} is an M entry point that is called when a new instance of a class is created. 4978: 4979: A constructor must be the first entry point in a class routine, its tag must match the class/routine name, and it must take two arguments, @code{THIS} and @code{INIT}. 4980: 4981: @code{THIS} represents the instance of the object being accessed, and @code{INIT} represents an initializer that can be used to assign an initial value to the object when instantiating the class. 4982: 4983: A constructor looks like this: 4984: 4985: @example 4986: %FRACTION(THIS,INIT):OBJECT ; 4987: S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) 4988: S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) 4989: Q 4990: @end example 4991: 4992: @emph{Syntax} 4993: @example 4994: @emph{<class-name>}(THIS,INIT)[:@emph{<superclass>}] 4995: @end example 4996: 4997: In the above example, @emph{<superclass>} represents the name of a class from which this class should inherit. In this case, the @code{FRACTION} class inherits from the @code{OBJECT} class. Note that this is not strictly necessary in this case, as all classes in FreeM automatically inherit from @code{OBJECT}. 4998: 4999: @subsection Destructors 5000: A @code{destructor} is called when you @code{KILL} an instance variable. Its tag must be @code{DESTROY}, and it must take one argument (@code{THIS}). 5001: 5002: The destructor should be used to clean up any resources used by class methods. 5003: 5004: A destructor looks like this: 5005: 5006: @example 5007: DESTROY(THIS) ; 5008: ; free any resources that should be freed at the end of the object's lifetime 5009: Q 5010: @end example 5011: 5012: @node Inheritance 5013: @section Inheritance 5014: 5015: Every class you create will automatically inherit the methods and functionality of the @code{OBJECT} class, supplied with FreeM. 5016: 5017: When attempting to call a method, FreeM will first search the class routine for a matching entry point, and then follow the inheritance chain upwards until a matching entry point is found. If the final class in the chain does not have a matching entry point, FreeM will try to find a matching entry point in the @code{OBJECT} class. 5018: 5019: Inheritance is achieved by specifying the name of the superclass in the constructor: 5020: 5021: @example 5022: CLASS(THIS,INIT):SUPERCLASS 5023: @end example 5024: 5025: @subsection Runtime Polymorphism 5026: 5027: You can achieve runtime polymorphism by subclassing, and defining methods in the subclass that match the names of existing methods in the superclass. Following FreeM inheritance rules, the overridden method in the subclass will be called, and the method in the superclass will not. 5028: 5029: Note that the overridden method in the subclass can take a different set or number of arguments than the @emph{formallist} of the superclass method would specify. 5030: 5031: @node Methods 5032: @section Methods 5033: Class methods are defined as tags with @emph{formallist}s in a class routine, and per the typical FreeM object pattern, must take at least one argument, being @code{THIS} (representing a reference to the object instance being accessed). 5034: 5035: The following class (@code{MYCLASS}) has a constructor, a destructor, and a method called @code{MYMETHOD}: 5036: 5037: @example 5038: %MYCLASS(THIS,INIT) ; 5039: Q THIS 5040: DESTROY(THIS) ; 5041: Q 5042: MYMETHOD(THIS) ; 5043: Q "VALUE" 5044: @end example 5045: 5046: The dot operator is used to invoke class methods: 5047: 5048: @example 5049: DEFAULT.USER> N MYOBJ=$#^%MYCLASS("") 5050: DEFAULT.USER> W MYOBJ.MYMETHOD() 5051: VALUE 5052: @end example 5053: 5054: @node Public and Private Variables 5055: @section Public and Private Variables 5056: 5057: FreeM supports private fields with the @code{:PRIVATE} specifier in the @code{SET} command, enforcing classical object-oriented data encapsulation. The @code{:PUBLIC} specifier is provided for completeness, and is the default. 5058: 5059: The below constructor for a @code{FRACTION} class defines two private fields: 5060: 5061: @example 5062: %FRACTION(THIS,INIT):OBJECT ; 5063: S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) 5064: S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) 5065: Q 5066: @end example 5067: 5068: Either of the following commands will create a public field: 5069: 5070: @example 5071: S THIS("VARNAM")="Initial Value" 5072: S THIS("VARNAM"):PUBLIC="Initial Value" 5073: @end example 5074: 5075: Attempting to access private fields from outside of the class will raise error condition @code{ZOBJFLDACCV}. 5076: 5077: @node Instantiating Objects 5078: @section Instantiating Objects 5079: 5080: To instantiate an object (i.e., create an object from a certain class), you will use the @code{NEW} command as follows: 5081: 5082: @example 5083: NEW MYSTR=$#^%STRING("myString") 5084: @end example 5085: 5086: This will create a local variable called MYSTR of type STRING, and initialize it with the value myString. 5087: 5088: @subsection Determining Object Class 5089: 5090: To determine the class of any FreeM local variable, you will use the @code{$$TYPE()} method: 5091: 5092: @example 5093: USER> W MYSTR.$$TYPE() 5094: ^%STRING 5095: @end example 5096: 5097: The @code{$$TYPE()} method is a member of the @code{OBJECT} class. 5098: 5099: @node Libraries 5100: @chapter Libraries 5101: @cindex libraries 5102: 5103: @node Sequential I/O 5104: @chapter Sequential I/O 5105: 5106: @node Network I/O 5107: @chapter Network I/O 5108: @cindex networks, input and output 5109: 5110: Network I/O in FreeM is supplied through I/O channels 100-255. The normal @code{READ} and @code{WRITE} syntax will work with network sockets, with a few exceptions. 5111: 5112: @section Opening and Connecting a Client Socket 5113: @cindex networks, opening and connecting client sockets 5114: 5115: To open a client socket and connect to it, you will need to call the @code{OPEN} command and the @code{USE} command: 5116: 5117: @example 5118: ; 5119: ; Set socket read terminator to LF 5120: ; 5121: SET ^$DEVICE(100,"OPTIONS","TERMINATOR")=$C(10) 5122: ; 5123: ; Open an IPv4 TCP socket to mail.mydomain.com on port 25 (SMTP) 5124: ; and connect to it 5125: ; 5126: OPEN 100:"mail.mydomain.com:25:IPV4:TCP" 5127: USE 100:/CONNECT 5128: ; 5129: ; Read a line of input from the remote host and write it to the terminal 5130: ; 5131: NEW LINE 5132: READ LINE 5133: USE 0 5134: WRITE LINE,! 5135: ; 5136: ; CLOSE the socket and disconnect 5137: ; 5138: CLOSE 100 5139: QUIT 5140: @end example 5141: 5142: @node Extended Global References 5143: @chapter Extended Global References 5144: @cindex global references, extended 5145: @cindex extended global references 5146: 5147: @section Standard Extended Global References 5148: @cindex extended global references, standard 5149: 5150: FreeM supports extended global references, allowing the user to access globals in namespaces other than the current default namespace and the @code{SYSTEM} namespace, without switching to the other namespace. 5151: 5152: For example, if you are in the @code{USER} namespace, the following code will print the value of @code{^VA(200,0)} in the @code{VISTA} namespace: 5153: 5154: @example 5155: WRITE ^|"VISTA"|VA(200,0),! 5156: @end example 5157: 5158: You may also use an expression that resolves to a string containing a valid namespace name: 5159: 5160: @example 5161: SET NS="VISTA" 5162: WRITE ^|NS|VA(200,0),! 5163: @end example 5164: 5165: @node Global Aliasing 5166: @chapter Global Aliasing 5167: @cindex aliasing, global 5168: @cindex globals, aliasing 5169: 5170: FreeM provides the ability to set alternative names for M global variables. 5171: 5172: To create an alias of @code{^FOO} named @code{^BAR}, use the following command: 5173: 5174: @example 5175: SET ^$JOB($JOB,"ALIASES","^BAR")="^FOO" 5176: @end example 5177: 5178: If such an alias is set, any reference to global variable @code{^BAR} will affect @code{^FOO} instead of @code{^BAR} until @code{^$JOB($JOB,"ALIASES","^BAR")} is @code{KILL}ed. If @code{^BAR} existed prior to the definition of this alias, its data will be unavailable to and unaffected by application code. 5179: 5180: @node Global Mappings 5181: @chapter Global Mappings 5182: @cindex mappings, global 5183: @cindex globals, mapping 5184: 5185: FreeM supports creating persistent mappings through which arbitrary global names may be mapped to specific namespaces. This allows non-@code{%} globals to be stored in the @code{SYSTEM} namespace, or @code{%} globals to be stored in non-@code{SYSTEM} namespaces. 5186: 5187: To map the @code{^FOO} global to the @code{SYSTEM} namespace, any of the following will work: 5188: 5189: @example 5190: MAP GLOBAL ^FOO="SYSTEM" 5191: SET ^$GLOBAL("FOO","NAMESPACE")="SYSTEM" 5192: SET ^$SYSTEM("MAPPINGS","GLOBAL","^FOO")="SYSTEM" 5193: @end example 5194: 5195: There is no functional difference in any of the three approaches; the method you choose is a matter of personal preference. 5196: 5197: To remove the above mapping, any of the following examples will also work: 5198: 5199: @example 5200: UNMAP GLOBAL ^FOO 5201: KILL ^$GLOBAL("FOO","NAMESPACE") 5202: KILL ^$SYSTEM("MAPPINGS","GLOBAL","^FOO") 5203: @end example 5204: 5205: 5206: 5207: @node Asynchronous Event Handling 5208: @chapter Asynchronous Event Handling 5209: @cindex event handling, asynchronous 5210: 5211: Asynchronous event handling in FreeM follows the specifications of the unpublished MDC @emph{Millennium Draft Standard}. 5212: 5213: @section Setting Up Async Event Handlers 5214: 5215: Asynchronous event handlers are configured through the @code{^$JOB} structured system variable for job-specific events, and the @code{^$SYSTEM} structured system variable for system-wide events. In order to become proficient in writing asynchronous event handling code, you need to be aware of several important concepts: 5216: 5217: @table @emph 5218: 5219: @item Event Classes 5220: @emph{Event classes} denote particular categories of events. These include @code{COMM}, @code{HALT}, @code{IPC}, @code{INTERRUPT}, @code{POWER}, @code{TIMER}, @code{TRIGGER}, and @code{USER} event classes. At present, only @code{INTERRUPT} and @code{TRIGGER} event classes are supported. 5221: 5222: @item Event Identifiers 5223: @emph{Event identifiers} denote the precise nature of the event that has occurred. For instance, resizing the terminal window in which a FreeM job is running will send an event of class @code{INTERRUPT} with an event identifier of @code{SIGWINCH} (short for @emph{SIGnal WINdow CHange}). 5224: 5225: @item Event Handlers 5226: @emph{Event handlers} are M routines or subroutines that can be registered to run when an event of a certain event class occurs. 5227: 5228: @item Event Registration 5229: @emph{Event registration} is the process of modifying the @code{^$JOB} or @code{^$SYSTEM} SSVN to associate a particular event class and event identifier with an event handler routine or subroutine. 5230: 5231: @item Event Blocking and Unblocking 5232: @emph{Event blocking} is the means by which asynchronous event handling can be temporarily suspended. For example, asynchronous events are temporarily and implicitly blocked for the duration of event handler execution, unless explicitly un-blocked within the event handler. Event handling can also be blocked and unblocked programatically from M code using the @code{ABLOCK} and @code{AUNBLOCK} commands. 5233: 5234: @end table 5235: 5236: The following sections of this chapter will take you step-by-step through setting up an event handler for @code{SIGWINCH} signal handling. 5237: 5238: @section Registering an Asynchronous Event Handler 5239: @cindex event handlers, registration 5240: 5241: To register a job-specific event handler that will only execute in the current FreeM process, use the following syntax: 5242: 5243: @example 5244: SET ^$JOB($JOB,"EVENT",@emph{event-class},@emph{event-identifier})=@emph{entryref} 5245: @end example 5246: 5247: To register a system-wide event handler that will execute in every FreeM process, use the following syntax: 5248: 5249: @example 5250: SET ^$SYSTEM("EVENT",@emph{event-class},@emph{event-identifier})=@emph{entryref} 5251: @end example 5252: 5253: For example, use the following to register @code{^RESIZE} as an asynchronous event handler for @code{SIGWINCH} events: 5254: 5255: @example 5256: SET ^$JOB($JOB,"EVENT","INTERRUPT","SIGWINCH")="^RESIZE" 5257: @end example 5258: 5259: This by itself will not enable asynchronous event handling, as it merely @emph{registers} an event handler, associating it with event class @code{INTERRUPT} and event identifier @code{SIGWINCH}. 5260: 5261: @section Enabling Asynchronous Event Handling 5262: @cindex event handlers, enabling 5263: 5264: In order to enable asyncronous event handling, the @code{ASTART} command is used. In the following example, we will enable asynchronous event handling for the @code{INTERRUPT} event class: 5265: 5266: @example 5267: ASTART "INTERRUPT" 5268: @end example 5269: 5270: Omitting the @code{"INTERRUPT"} argument will enable asynchronous event handling for @emph{all} event classes. See @code{ASTART} in the commands section for more details. 5271: 5272: Once this is done, any event handlers registered for the @code{INTERRUPT} event class in @code{^$JOB} will be executed asynchronously as appropriate. 5273: 5274: Please note that @code{ASTART "TRIGGER"} is run implicitly at FreeM startup, to ensure consistency in applications depending on business logic contained in system-wide global triggers. To disable this behavior, add @code{ASTOP "TRIGGER"} to the @code{LOCAL.STARTUP} routine in the @code{USER} namespace. If @code{LOCAL.STARTUP} does not yet exist in your environment, you may create it by typing @code{fmadm edit routine USER LOCAL.STARTUP} from your UNIX command-line shell. 5275: 5276: @section Disabling Asynchronous Event Handling 5277: @cindex event handlers, disabling 5278: 5279: To disable asynchronous event handling, the @code{ASTOP} command is used. In the following example, we will disable asynchronous event handling for the @code{INTERRUPT} event class: 5280: 5281: @example 5282: ASTOP "INTERRUPT" 5283: @end example 5284: 5285: Omitting the @code{"INTERRUPT"} argument will disable asynchronous event handling for @emph{all} event classes. See @code{ASTOP} in the commands section for more details. 5286: 5287: You may also disable asynchronous event handling for a specific event identifier by @code{KILL}ing the appropriate node in the @code{^$JOB} SSVN, which unregisters the event handler altogether. The following example will unregister the event handler for the @code{SIGWINCH} event identifier: 5288: 5289: @example 5290: KILL ^$JOB($JOB,"EVENT","INTERRUPT","SIGWINCH") 5291: @end example 5292: 5293: @section Temporarily Blocking Asynchronous Event Handling 5294: @cindex event handlers, blocking 5295: 5296: To temporarily block processing of specific event classes, you will use the @code{ABLOCK} command. @code{ABLOCK} functions incrementally, that is, each successive call to @code{ABLOCK} will increment a counter of blocks held for the specified event class or classes, and each successive call to @code{AUNBLOCK} will decrement that counter. Event handling for the specified event classes will be blocked as long as the @code{ABLOCK} counter for those classes is greater than zero. Thus, event blocking is cumulative, in a manner similar to M incremental locks. 5297: 5298: The following example blocks asynchronous event handling for the @code{INTERRUPT} event class: 5299: 5300: @example 5301: ABLOCK "INTERRUPT" 5302: @end example 5303: 5304: Note that entering an event handler causes an implicit @code{ABLOCK} of @emph{all} event classes, to prevent event handlers from interrupting other event handlers during their execution. This may be overridden by calling @code{AUNBLOCK} for one or more event classes within an event handler. However, unblocking event handling during an event handler should be done with great caution, as this can make the flow of code execution somewhat unpredictable, especially if M globals are modified inside of an event handler routine or subroutine. 5305: 5306: Modifying M globals within event handlers is allowed but strongly discouraged, as doing so can lead to logical corruption of the data. If you must modify an M global within an event handler, guard all such operations with prodigious and careful use of @code{LOCK}s, ensuring that such modifications occur in the desired logical order. 5307: 5308: @node Global Triggers 5309: @chapter Global Triggers 5310: @cindex global triggers 5311: @cindex triggers 5312: 5313: Global triggers use the FreeM asynchronous event handling subsystem to allow a FreeM process to execute arbitrary M code when a particular action occurs on a particular global. 5314: 5315: To set up a global trigger, you must set up an event handler for event class @code{TRIGGER}. The event identifier must be in the format of @code{"<action>:<gvn>"}, where @emph{<gvn>} is a global variable name, and @emph{<action>} is one of the following: 5316: 5317: @table @asis 5318: 5319: @item @code{DATA} 5320: Trigger will fire when the @code{$DATA} intrinsic function is called on @emph{<gvn>}. 5321: 5322: @item @code{GET} 5323: Trigger will fire when @emph{<gvn>} is read from. 5324: 5325: @item @code{INCREMENT} 5326: Trigger will fire when intrinsic function @code{$INCREMENT} is called on @emph{<gvn>}. 5327: 5328: @item @code{KILL} 5329: Trigger will fire when @emph{<gvn>} is @code{KILL}ed. 5330: 5331: @item @code{NEXT} 5332: Trigger will fire when intrinsic function @code{$NEXT} is called on @emph{<gvn>}. 5333: 5334: @item @code{ORDER} 5335: Trigger will fire when intrinsic function @code{$ORDER} is called on @emph{<gvn>}. 5336: 5337: @item @code{QUERY} 5338: Trigger will fire when intrinsic function @code{$QUERY} is called on @emph{<gvn>}. 5339: 5340: @item @code{SET} 5341: Trigger will fire when @code{SET @emph{<gvn>}=@emph{value}} occurs. 5342: 5343: @item @code{ZDATA} 5344: Trigger will fire when intrinsic function @code{ZDATA} is called on @emph{<gvn>}. 5345: 5346: @end table 5347: 5348: When a @code{TRIGGER} event occurs, the @code{"GLOBAL"} node of the @code{^$EVENT} structured system variable will be populated with the global reference that invoked the trigger event. 5349: 5350: If a @code{SET} or @code{KILL} trigger was the source of the @code{TRIGGER} event, the @code{OLD_VALUE} node of @code{^$EVENT} will be populated with original value of @code{^$EVENT("GLOBAL")} prior to the change, and @code{NEW_VALUE} will be populated with the new value. This allows triggers to contain logic to undo global changes. This functionality can also be used to provide auditing of specific global changes. 5351: 5352: The following example shows a trigger implemented for @code{SET} operations on the @code{^DD} global. 5353: 5354: @example 5355: TRIGGER ; 5356: ; 5357: ; Set up a SET trigger on ^DD 5358: ; 5359: SET ^$JOB($JOB,"EVENT","TRIGGER","SET:^DD")="ONSET^TRIGGER" 5360: ; 5361: ; Enable the TRIGGER event class 5362: ; 5363: ASTART "TRIGGER" 5364: ; 5365: ; Try setting a node in ^DD 5366: ; 5367: SET ^DD(1)="Test" 5368: ; 5369: ; Quit 5370: ; 5371: QUIT 5372: ; 5373: ; 5374: ONSET ; 5375: WRITE "The "_^$EVENT("GLOBAL")_" global node was SET.",! 5376: QUIT 5377: @end example 5378: 5379: You can also set up a trigger that applies to all FreeM processes by setting descendant subscripts of @code{^$SYSTEM("EVENT","TRIGGER",...)} instead of using @code{^$JOB($JOB,"EVENT","TRIGGER",...)}. 5380: 5381: @node Synchronous Event Handling 5382: @chapter Synchronous Event Handling 5383: 5384: @node GUI Programming with MWAPI 5385: @chapter GUI Programming with MWAPI 5386: 5387: @node User-Defined Z Commands 5388: @chapter User-Defined Z Commands 5389: 5390: @node User-Defined Z Functions 5391: @chapter User-Defined Z Functions 5392: 5393: @cindex z functions, user-defined 5394: 5395: @node User-Defined SSVNs 5396: @chapter User-Defined SSVNs 5397: 5398: @cindex structured system variables, user-defined 5399: @cindex structured system variables 5400: 5401: @node Language Dialects 5402: @chapter Language Dialects 5403: 5404: @cindex language dialects 5405: @cindex dialects, language 5406: 5407: 5408: @node System Library Routines 5409: @chapter System Library Routines 5410: @cindex system library routines 5411: 5412: @section ^%ZCOLUMNS 5413: @cindex ^%ZCOLUMNS 5414: @cindex system library routines, ^%ZCOLUMNS 5415: 5416: This routine is the implementation of the @code{$ZCOLUMNS} intrinsic special variable. 5417: 5418: @section %SYSINIT 5419: @cindex %SYSINIT 5420: @cindex system library routines, %SYSINIT 5421: 5422: This routine is the default startup routine for FreeM running in direct mode. 5423: 5424: Running @code{DO INFO} from direct mode will use this routine to display information about the current FreeM status and namespace configuration. 5425: 5426: @section ^%ZHELP 5427: @cindex ^%ZHELP 5428: @cindex system library routines, ^%ZHELP 5429: 5430: This routine implements the online help feature of FreeM, invoked by typing @code{?} in direct mode. It simply asks the underlying system to execute the command @command{info freem}. 5431: 5432: @section ^%ZROWS 5433: @cindex ^%ZROWS 5434: @cindex system library routines, ^%ZROWS 5435: 5436: This routine is the implementation of the @code{$ZROWS} intrinsic special variable. 5437: 5438: @node Interrupt Handling 5439: @chapter Interrupt Handling 5440: @cindex interrupt handling 5441: 5442: When FreeM receives the @code{SIGINT} signal, either by pressing @code{Ctrl-C} during program execution, or by external signal from the operating system, the FreeM environment daemon, or another external process, one of two things can happen, depending on the state of the @code{$ZI} special variable: 5443: 5444: @table @asis 5445: @item @code{$ZI} evaluates @emph{true} 5446: In this case, the @code{ZINRPT} error is raised, and normal error handling procedures apply. If neither @code{$ZTRAP} nor @code{$ETRAP} are set, FreeM prints an error diagnostic on the home device and will exit the FreeM process in application mode (i.e., the @code{freem} executable was started with the @code{--routine} or @code{-r} flag), or return to the direct mode prompt otherwise. 5447: 5448: This is the default behavior of FreeM. 5449: @item @code{$ZI} evaluates @emph{false} 5450: In this case, no error is raised, but the @code{$ZCONTROLC} flag is set. In this mode of operation, it is up to program code to check for @code{$ZCONTROLC} and take appropriate action. 5451: 5452: Checking the value of @code{$ZCONTROLC} will reset it to @emph{false}. 5453: @end table 5454: 5455: In either case, if asynchronous event handling is enabled for the @code{INTERRUPT} event class (i.e., @code{ASTART "INTERRUPT"} or @code{ASTART} have been invoked by the current process), an asynchronous event of event class @code{INTERRUPT} and event identifier @code{SIGINT} will be enqueued. 5456: 5457: @node Error Processing 5458: @chapter Error Processing 5459: @cindex error processing 5460: 5461: FreeM exposes three means of processing M program execution errors: 5462: 5463: @table @emph 5464: 5465: @item FreeM-style error processing 5466: FreeM-style error processing exposes a read/write error trap in @code{$ZTRAP}. The contents of @code{$ZTRAP} must be either empty or a valid M entryref, to which FreeM will @code{GOTO} if an error occurs. Each program stack execution level can have its own @code{$ZTRAP} error handler enabled. 5467: 5468: @item DSM 2.0-style error processing 5469: DSM 2.0-style error processing emulates the @code{$ZTRAP} behavior of Digital Standard MUMPS v2. It has the same behavior as FreeM-style error handling, with the exception that in DSM 2.0-style error processing, only one @code{$ZTRAP} error handler is set across all program stack execution levels. 5470: 5471: @item Standard error processing 5472: Standard error processing uses the @code{NEW}-able @code{$ETRAP} variable to store error handler code, which may be any valid M code. The code in @code{$ETRAP} will run when an error occurs or the @code{$ECODE} ISV becomes non-empty. Stack information for standard error handling is provided by the @code{$STACK} ISV, the @code{$STACK()} intrinsic pseudo-function, and the @code{NEW}-able @code{$ESTACK} ISV. 5473: 5474: If @code{$ETRAP} is non-empty when an error condition occurs, @code{$ZTRAP} is ignored, regardless of whether FreeM-style or DSM 2.0-style error processing is enabled at the time of the error. 5475: 5476: @end table 5477: 5478: For further information on switching between FreeM-style and DSM 2.0-style @code{$ZTRAP} error handling, see the documentation for the @code{BREAK} command. 5479: 5480: @node FreeM Error Codes 5481: @chapter FreeM Error Codes 5482: @cindex Error Codes 5483: 5484: @table @asis 5485: 5486: @item @code{ZINRPT} - @emph{interrupt} 5487: Raised when an interrupt signal is received. 5488: 5489: @item @code{ZBKERR} - @emph{BREAK point} 5490: Raised when a @code{BREAK} point is reached. 5491: 5492: @item @code{ZNOSTAND} - @emph{non standard syntax} 5493: Raised when features incompatible with the current value of @code{$DIALECT} are used. 5494: 5495: @item @code{ZUNDEF} - @emph{variable not found} 5496: Raised when an undefined local or global variable is accessed. This error code has been deprecated in favor of standard error codes @code{M6} and @code{M7}. 5497: 5498: @item @code{ZLBLUNDEF} - @emph{label not found} 5499: Raised when a referenced label is not found. 5500: 5501: @item @code{ZMISSOPD} - @emph{missing operand} 5502: Raised when an operand is missing from an expression. 5503: 5504: @item @code{ZMISSOP} - @emph{missing operator} 5505: Raised when an operator is missing from an expression. 5506: 5507: @item @code{ZILLOP} - @emph{unrecognized operator} 5508: Raised when an unrecognized operator is encountered in an expression. 5509: 5510: @item @code{ZQUOTER} - @emph{unmatched quotes} 5511: Raised when unbalanced quotes are encountered. 5512: 5513: @item @code{ZCOMMAER} - @emph{comma expected} 5514: Raised when a comma is expected in program syntax but is not found. 5515: 5516: @item @code{ZASSIGNER} - @emph{equals '=' expected} 5517: Raised when an equals sign is expected in program syntax but is not found. 5518: 5519: @item @code{ZARGER} - @emph{argument not permitted} 5520: Raised when an argument is encountered in a syntactic position where arguments are not permitted. 5521: 5522: @item @code{ZSPACER} - @emph{blank ' ' expected} 5523: Raised when a space character is expected in program syntax but is not found. 5524: 5525: @item @code{ZBRAER} - @emph{unmatched parentheses} 5526: Raised when unbalanced parentheses are detected in program syntax. 5527: 5528: @item @code{ZLVLERR} - @emph{level error} 5529: Raised when a level error occurs. 5530: 5531: @item @code{ZDIVER} - @emph{divide by zero} 5532: Raised when program code attempts to divide by zero. Deprecated in favor of standard error code @code{M9}. 5533: 5534: @item @code{ZILLFUN} - @emph{function not found} 5535: Raised when program code attempts to call intrinsic or extrinsic functions that are not defined. 5536: 5537: @item @code{ZFUNARG} - @emph{wrong number of function arguments} 5538: Raised when an intrinsic or extrinsic function is called with the wrong number of arguments. 5539: 5540: @item @code{ZZTERR} - @emph{ZTRAP error} 5541: Raised when a @code{$ZTRAP} error occurs. 5542: 5543: @item @code{ZNEXTERR} - @emph{$NEXT/$ORDER error} 5544: Raised when an error occurs in @code{$NEXT} or @code{$ORDER}. 5545: 5546: @item @code{ZSELER} - @emph{$SELECT error} 5547: Raised when an error occurs in @code{$SELECT} 5548: 5549: @item @code{ZCMMND} - @emph{illegal command} 5550: Raised when program code attempts to execute an illegal command. 5551: 5552: @item @code{ZARGLIST} - @emph{argument list incorrect} 5553: Raised when the argument list supplied to an M language element does not match that language element's syntactic requirements. 5554: 5555: @item @code{ZINVEXPR} - @emph{invalid expression} 5556: Raised when an invalid expression is encountered. 5557: 5558: @item @code{ZINVREF} - @emph{invalid reference} 5559: Raised when an invalid variable reference is encountered. 5560: 5561: @item @code{ZMXSTR} - @emph{string too long} 5562: Raised when a string is encountered that exceeds @code{^$SYSTEM("STRING_MAX")}. 5563: 5564: @item @code{ZTOOPARA} - @emph{too many parameters} 5565: Raised when too many parameters are passed to a function or subroutine. 5566: 5567: @item @code{ZNOPEN} - @emph{unit not open} 5568: Raised when attempting to access an I/O channel that has not been opened. 5569: 5570: @item @code{ZNODEVICE} - @emph{unit does not exist} 5571: Raised when attempting to access a device that does not exist. 5572: 5573: @item @code{ZPROTECT} - @emph{file protection violation} 5574: Raised when attempting to access a file or device to which you do not have permission. 5575: 5576: @item @code{ZGLOBER} - @emph{global not permitted} 5577: Raised when attempting to use a global in a syntactic element where global variables are not permitted. 5578: 5579: @item @code{ZFILERR} - @emph{file not found} 5580: Raised when attempting to access a file that does not exist. 5581: 5582: @item @code{ZPGMOV} - @emph{program overflow} 5583: Raised when a program overflows the limits of a routine buffer. 5584: 5585: @item @code{ZSTKOV} - @emph{stack overflow} 5586: Raised when @code{DO}, @code{FOR}, or @code{XECUTE} nesting levels exceed the value in @code{^$SYSTEM("NESTLEVLS")}. 5587: 5588: @item @code{ZSTORE} - @emph{symbol table overflow} 5589: Raised when program code attempts to store too much data in the local symbol table. Should not occur unless symbol table auto-adjust is disabled. 5590: 5591: @item @code{ZNOREAD} - @emph{file won't read} 5592: Raised when program code attempts to read from an unreadable file. 5593: 5594: @item @code{ZNOWRITE} - @emph{file won't write} 5595: Raised when program code attempts to write to an unwritable file. 5596: 5597: @item @code{ZNOPGM} - @emph{routine not found} 5598: Raised when an attempt is made to load or execute a routine that does not exist in the current namespace. 5599: 5600: @item @code{ZNAKED} - @emph{illegal naked reference} 5601: Raised when an attempt is made to use an illegal naked reference. 5602: 5603: @item @code{ZSBSCR} - @emph{illegal subscript} 5604: Raised when an illegal subscript access is attempted. 5605: 5606: @item @code{ZISYNTX} - @emph{insert syntax} 5607: Raised when illegal insert syntax is used. 5608: 5609: @item @code{ZDBDGD} - @emph{global data degradation} 5610: Raised when corruption is detected in global data files. 5611: 5612: @item @code{ZKILLER} - @emph{job kill signal} 5613: Raised on a job kill signal. 5614: 5615: @item @code{ZHUPER} - @emph{hangup signal} 5616: Raised on a job hangup signal. 5617: 5618: @item @code{ZMXNUM} - @emph{numeric overflow} 5619: Raised when an assignment or expression result exceeds @code{$ZPRECISION}. 5620: 5621: @item @code{ZNOVAL} - @emph{function returns no value} 5622: Raised when a function does not return a value. Extrinsic functions must @code{QUIT} with a value. 5623: 5624: @item @code{ZTYPEMISMATCH} - @emph{type mismatch} 5625: Raised when a type mismatch occurs. 5626: 5627: @item @code{ZMEMOV} - @emph{out of memory} 5628: Raised when FreeM runs out of heap memory. 5629: 5630: @item @code{ZNAMERES} - @emph{error in name resolution} 5631: Raised when an attempted name resolution fails. 5632: 5633: @item @code{ZSCKCREAT} - @emph{error creating socket} 5634: Raised when an error occurs creating a socket for network I/O. 5635: 5636: @item @code{ZSCKIFAM} - @emph{invalid address family (must be IPV4 or IPV6)} 5637: Raised when the address family specified in an @code{OPEN} command for a socket I/O channel is not IPV4 or IPV6. 5638: 5639: @item @code{ZSCKITYP} - @emph{invalid connection type (must be TCP or UDP)} 5640: Raised when the connection type specified in an @code{OPEN} command for a socket I/O channel is not @code{TCP} or @code{UDP}. 5641: 5642: @item @code{ZSCKIPRT} - @emph{invalid port number} 5643: Raised when the port number specified in an @code{OPEN} command for a socket I/O channel is invalid. Valid TCP and UDP ports are in the range of 1-65535. 5644: 5645: @item @code{ZSCKCERR} - @emph{connection error} 5646: Raised when an error occurs on a @code{USE <channel>:/CONNECT} command. 5647: 5648: @item @code{ZSCKAERR} - @emph{USE action invalid for connection type (possibly CONNECT on UDP socket?)} 5649: Raised when an attempt is made to @code{USE <channel>:/CONNECT} on a UDP socket I/O channel. The UDP protocol is connectionless. 5650: 5651: @item @code{ZSCKACON} - @emph{attempted to CONNECT an already-connected socket} 5652: Raised when an attempt is made to @code{USE <channel>:/CONNECT} on a TCP socket I/O channel that is already connected. 5653: 5654: @item @code{ZSCKNCON} - @emph{attempted to READ from a disconnected TCP socket} 5655: Raised when an attempt is made to @code{READ} a TCP socket that has not yet been connected. 5656: 5657: @item @code{ZSCKEOPT} - @emph{error setting socket options} 5658: Raised when an error is encountered while setting socket options. 5659: 5660: @item @code{ZSCKERCV} - @emph{error in READ from socket} 5661: Raised when an error occurs in a socket I/O channel @code{READ}. 5662: 5663: @item @code{ZSCKESND} - @emph{error in WRITE to socket} 5664: Raised when an error occurs while attempting to @code{WRITE} to a socket I/O channel. 5665: 5666: @item @code{ZNORPI} - @emph{^$ZRPI only supported on Raspberry Pi hardware} 5667: Raised when an attempt is made to use the @code{^$ZRPI} structured system variable on a platform other than the Raspberry Pi single-board computer. 5668: 5669: @item @code{ZCREDEF} - @emph{cannot redefine CONST} 5670: Raised when attempts are made to redefine a @code{CONST} after its initial definition. 5671: 5672: @item @code{ZCMODIFY} - @emph{cannot modify CONST} 5673: Raised when attempts are made to change the value of a @code{CONST}. 5674: 5675: @item @code{ZFILEXWR} - @emph{cannot open existing file for WRITE} 5676: Raised when an attempt is made to open an existing file in write (but not append) mode. 5677: 5678: @item @code{INEWMULT} - @emph{initializing NEW with multiple setarguments not supported} 5679: Raised when you attempt to use multiple setarguments with initializing @code{NEW}, e.g. @code{NEW X=2,Y=3}. 5680: 5681: @item @code{ZECODEINV} - @emph{invalid value for $ECODE} 5682: Raised when attempts are made to set @code{$ECODE} to an invalid error code value. Obsolete and replaced by standard error code @code{M101}. 5683: 5684: @item @code{ZASSERT} - @emph{programmer assertion failed} 5685: Raised when an @code{ZASSERT} expression's result is not true. 5686: 5687: @item @code{ZUSERERR} - @emph{user-defined error} 5688: Raised when program code calls @code{THROW} with an error code argument for which the first character is @code{U}, or when @code{$ECODE} is set to an error code for which the first character is @code{U}. 5689: 5690: Custom error messages for @code{ZUSERERR} may be set in @code{^$JOB($JOB,"USER_ERRORS",<user_error_code>)}, where @code{<user_error_code>} represents the custom error code. 5691: 5692: For example: 5693: 5694: @example 5695: DEFAULT.USER> S ^$JOB($JOB,"USER_ERRORS","UBLACKHOLE")="black hole encountered" 5696: 5697: 5698: DEFAULT.USER> THROW UBLACKHOLE 5699: 5700: 5701: >> Error UBLACKHOLE: black hole encountered in SYSTEM::^%SYSINIT [$STACK = 0] 5702: >> THROW UBLACKHOLE 5703: ^ 5704: @end example 5705: 5706: @item @code{ZSYNTERR} - @emph{syntax error} 5707: Raised when a syntax error without a more specific error code is encountered. 5708: 5709: @item @code{ZCTRLB} - @emph{break} 5710: Pseudo-error used by the FreeM debugger. Not visibly raised in normal program operation. 5711: 5712: @item @code{ZASYNC} - @emph{asynchronous interruption} 5713: Pseudo-error used by the FreeM asynchronous events subsystem. Not visibly raised in normal program operation. 5714: 5715: @item @code{M1} - @emph{naked indicator undefined} 5716: Raised when an attempt is made to use a naked reference before the naked indicator is set. 5717: 5718: @item @code{M2} - @emph{invalid combination with $FNUMBER code atom} 5719: 5720: 5721: @item @code{M3} - @emph{$RANDOM seed less than 1} 5722: 5723: 5724: @item @code{M4} - @emph{no true condition in $SELECT} 5725: 5726: 5727: @item @code{M5} - @emph{line reference less than zero} 5728: 5729: 5730: @item @code{M6} - @emph{undefined local variable} 5731: 5732: 5733: @item @code{M7} - @emph{undefined global variable} 5734: 5735: 5736: @item @code{M8} - @emph{undefined intrinsic special variable} 5737: 5738: 5739: @item @code{M9} - @emph{divide by zero} 5740: 5741: 5742: @item @code{M10} - @emph{invalid pattern match range} 5743: 5744: 5745: @item @code{M11} - @emph{no parameters passed} 5746: 5747: 5748: @item @code{M12} - @emph{invalid line reference (negative offset)} 5749: 5750: 5751: @item @code{M13} - @emph{invalid line reference (line not found)} 5752: 5753: 5754: @item @code{M14} - @emph{line level not 1} 5755: 5756: 5757: @item @code{M15} - @emph{undefined index variable} 5758: 5759: 5760: @item @code{M16} - @emph{argumented QUIT not allowed} 5761: 5762: 5763: @item @code{M17} - @emph{argumented QUIT required} 5764: 5765: 5766: @item @code{M18} - @emph{fixed length READ not greater than zero} 5767: 5768: 5769: @item @code{M19} - @emph{cannot copy a tree or subtree onto itself} 5770: 5771: 5772: @item @code{M20} - @emph{line must have a formal parameter list} 5773: 5774: 5775: @item @code{M21} - @emph{algorithm specification invalid} 5776: 5777: 5778: @item @code{M22} - @emph{SET or KILL to ^$GLOBAL when data in global} 5779: 5780: 5781: @item @code{M23} - @emph{SET or KILL to ^$JOB for non-existent job number} 5782: 5783: 5784: @item @code{M24} - @emph{change to collation algorithm while subscripted local variables defined} 5785: 5786: 5787: @item @code{M26} - @emph{non-existent environment} 5788: 5789: 5790: @item @code{M27} - @emph{attempt to rollback a transaction that is not restartable} 5791: 5792: 5793: @item @code{M28} - @emph{mathematical function, parameter out of range} 5794: 5795: 5796: @item @code{M29} - @emph{SET or KILL on structured system variable not allowed by implementation} 5797: 5798: 5799: @item @code{M30} - @emph{reference to global variable with different collating sequence within a collating algorithm} 5800: 5801: 5802: @item @code{M31} - @emph{control mnemonic used for device without a mnemonic space selected} 5803: 5804: 5805: @item @code{M32} - @emph{control mnemonic used in user-defined mnemonic space which has no associated line} 5806: 5807: 5808: @item @code{M33} - @emph{SET or KILL to ^$ROUTINE when routine exists} 5809: 5810: 5811: @item @code{M35} - @emph{device does not support mnemonic space} 5812: 5813: 5814: @item @code{M36} - @emph{incompatible mnemonic spaces} 5815: 5816: 5817: @item @code{M37} - @emph{READ from device identified by empty string} 5818: 5819: 5820: @item @code{M38} - @emph{invalid structured system variable subscript} 5821: 5822: 5823: @item @code{M39} - @emph{invalid $NAME argument} 5824: 5825: 5826: @item @code{M40} - @emph{call-by-reference in JOB actual parameter} 5827: 5828: 5829: @item @code{M41} - @emph{invalid LOCK argument within a transaction} 5830: 5831: 5832: @item @code{M42} - @emph{invalid QUIT within a transaction} 5833: 5834: 5835: @item @code{M43} - @emph{invalid range value ($X, $Y} 5836: 5837: 5838: @item @code{M44} - @emph{invalid command outside of a transaction} 5839: 5840: 5841: @item @code{M45} - @emph{invalid GOTO reference} 5842: 5843: 5844: @item @code{M56} - @emph{identifier exceeds maximum length} 5845: 5846: 5847: @item @code{M57} - @emph{more than one defining occurrence of label in routine} 5848: 5849: 5850: @item @code{M58} - @emph{too few formal parameters} 5851: 5852: 5853: @item @code{M60} - @emph{illegal attempt to use an undefined SSVN} 5854: 5855: 5856: @item @code{M101} - @emph{invalid value for $ECODE} 5857: 5858: 5859: @item @code{M102} - @emph{synchronous and asynchronous event processing cannot be simultaneously enabled for the same event class} 5860: 5861: 5862: @item @code{M103} - @emph{invalid event identifier} 5863: 5864: 5865: @item @code{M104} - @emph{ETRIGGER event identifier for IPC event class does not match job process identifier} 5866: 5867: 5868: @end table 5869: 5870: 5871: @node System Configuration 5872: @chapter System Configuration 5873: @cindex configuration, system 5874: 5875: @section Installing FreeM 5876: @cindex installation 5877: 5878: @subsection Installation Methods 5879: 5880: FreeM allows the following installation methods: 5881: @table @asis 5882: @item Binary Repository 5883: On recent versions the Ubuntu and Debian distributions of GNU/Linux, we provide package repositories from which FreeM may easily be installed. See the @emph{FreeM Wiki} for more information, and @emph{https://packages.coherent-logic.com} for instructions. 5884: 5885: If available, this is the simplest method of installing FreeM. 5886: @item Binary Packages 5887: We provide binary packages of FreeM for @emph{dpkg} and @emph{rpm}-based distributions of GNU/Linux, and @emph{pkgadd} packages for Solaris 8-10. If you cannot use repositories, this is the easiest option. 5888: 5889: See @emph{https://freem.coherent-logic.com/binaries.cfm} for downloads and instructions. 5890: @item Source Archive 5891: If you prefer installing from source, we recommend that you download the latest @emph{.tar.gz} file from @emph{https://freem.coherent-logic.com/downloads.cfm}, and follow these steps: 5892: 5893: @example 5894: $ gunzip freem-@emph{<version>}.tar.gz 5895: $ tar xf freem-@emph{<version>}.tar 5896: $ cd freem 5897: $ ./configure # see the Build Configuration section for optional flags 5898: $ make 5899: $ sudo make install 5900: @end example 5901: 5902: Once this process has been completed, you may proceed to @emph{Initial Configuration}. 5903: 5904: Installation from source archive is the most challenging but flexible supported option for advanced users. 5905: @item CVS Repository 5906: If you wish to try the bleeding-edge development version of FreeM, you may do so by following these steps: 5907: 5908: @verbatim 5909: $ cvs -d :pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem 5910: $ cd freem 5911: $ ./autogen.sh 5912: $ ./configure # see the Build Configuration section for optional flags 5913: $ make 5914: $ sudo make install 5915: @end verbatim 5916: 5917: Once this process has been completed, you may proceed to @emph{Initial Configuration}. 5918: 5919: This installation method is by far the most complicated, and is intended only for those who wish to contribute to FreeM development. It is not intended for end users, and no technical support will be provided. 5920: 5921: See the @emph{Contributor Guide} on the @emph{FreeM Wiki} for more information. 5922: @end table 5923: @subsection Build Configuration 5924: @cindex build configuration 5925: 5926: When configuring FreeM with the supplied @code{configure} script, there are some FreeM-specific options that may be used to compile in optional features, or exclude default ones: 5927: 5928: @table @asis 5929: 5930: @item @code{--enable-mwapi} (EXPERIMENTAL) 5931: Enables experimental support for the M Windowing API (ANSI @emph{X11.6-1995}) using the OSF/Motif widget toolkit. Requires that you have the @code{X11}, @code{Xt}, @code{ICE}, and @code{Xm} libraries, as well as all of their C header files. 5932: 5933: Please consult your operating system's documentation for the correct commands to install the required libraries. 5934: 5935: @emph{Example} 5936: 5937: @example 5938: $ ./configure --enable-mwapi 5939: $ make 5940: $ sudo make install 5941: @end example 5942: 5943: @end table 5944: 5945: @subsection Initial Configuration 5946: Once FreeM is installed, you will need to configure it: 5947: 5948: @enumerate 5949: @item Create a user and group, each named @emph{freem}, under which FreeM will run 5950: @item Add any user accounts that will need to run FreeM to the @emph{freem} group 5951: @item Have all users added in step 2 sign out and sign in for the new group membership to take effect 5952: @item Run @code{fmadm configure} with superuser privileges to create the @code{DEFAULT} environment with @code{SYSTEM} and @code{USER} namespaces and default after-image journal settings, and populate the bundled vendor routines 5953: @item Run @code{fmadm start environment} with superuser privileges to start the @code{DEFAULT} environment 5954: @item Make sure the environment is ready by running @code{fmadm status environment} with superuser privileges 5955: @end enumerate 5956: 5957: @subsubsection Creating Additional Environments 5958: To create additional environments, do the following steps: 5959: 5960: @enumerate 5961: @item Create a new user and group for the environment @emph{(optional)} 5962: @item Run @code{fmadm configure -e=@emph{<environment>} -u=@emph{<username>} -g=@emph{<groupname>} [-E=@emph{true|false}]} @emph{(the @code{-E} flag enables or disables the environment)} 5963: @item Run @code{fmadm start environment -e=@emph{<environment>}} to start the environment 5964: @item Run @code{fmadm status environment} to make sure the environment is healthy 5965: @end enumerate 5966: 5967: @subsubsection Additional Customization 5968: 5969: See the FreeM @emph{environment catalog} at @code{@emph{$PREFIX}/etc/freem/env.conf}, and the @emph{fmadm}(1) @code{man} page for more information. 5970: 5971: @emph{$PREFIX} represents the root location of your FreeM installation. This can be @code{/usr/local}, @code{/}, or others, depending on how FreeM was built and installed. 5972: 5973: @node Accessing FreeM from C Programs 5974: @chapter Accessing FreeM from C Programs 5975: 5976: FreeM provides a library, @file{libfreem.so}, as well as corresponding header file @file{freem.h}, allowing C programmers to write programs that access FreeM globals, locals, structured system variables, subroutines, and extrinsic functions. This functionality can be used to implement language bindings and data access drivers for external systems. 5977: 5978: In order to be used in your C programs, your C programs must link with @file{libfreem.so} and include @file{freem.h}. This will allow your C code access to the function prototypes, data structures, and constants required for calling the @file{libfreem.so} APIs. 5979: 5980: You must exercise caution in developing programs that interface with FreeM through @file{libfreem.so} to ensure that all @file{libfreem.so} API calls are serialized, as FreeM and the @file{libfreem.so} library are neither thread-safe nor reentrant. 5981: 5982: You must also avoid setting signal handlers for @code{SIGALRM}, as FreeM uses @code{SIGALRM} to manage timeouts for @command{LOCK}, @command{READ}, and @command{WRITE}. 5983: 5984: @section freem_ref_t Data Structure 5985: @cindex libfreem, data structures: freem_ref_t 5986: 5987: The @code{libfreem} API uses a @code{struct} of type @code{freem_ref_t} in order to communicate state, pass in values, and return results. 5988: 5989: The data structure, defined in @file{freem.h}, looks like this: 5990: 5991: @verbatim 5992: typedef struct freem_ref_t { 5993: 5994: /* 5995: * The 'reftype' field can be one of: 5996: * 5997: * MREF_RT_LOCAL 5998: * MREF_RT_GLOBAL 5999: * MREF_RT_SSV 6000: */ 6001: short reftype; 6002: 6003: /* 6004: * The 'name' field is the name of the local variable, 6005: * global variable, or SSVN (without ^ or ^$). 6006: */ 6007: char name[256]; 6008: 6009: /* 6010: * Returned data goes in a string, so you've got to figure out the 6011: * whole M canonical number thing yourself. Good luck. :-) 6012: */ 6013: char value[STRLEN]; 6014: 6015: short status; 6016: 6017: unsigned int subscript_count; 6018: char subscripts[255][256]; 6019: 6020: } freem_ref_t; 6021: @end verbatim 6022: 6023: @emph{freem_ref_t Members} 6024: 6025: @table @asis 6026: @cindex libfreem, freem_ref_t.reftype 6027: @item @option{reftype} 6028: The @option{reftype} member determines whether we are operating on a local variable, a global variable, or a structured system variable. It may be set to any of following constants: @code{MREF_RT_LOCAL}, @code{MREF_RT_GLOBAL}, or @code{MREF_RT_SSV}. 6029: 6030: @cindex libfreem, freem_ref_t.name 6031: @item @option{name} 6032: The @option{name} member contains the name of the global, local, or SSVN to be accessed. You @emph{must not} include leading characters, such as @code{^} or @code{^$}. 6033: 6034: @cindex libfreem, freem_ref_t.value 6035: @item @option{value} 6036: This member contains the value read from or the value to be written to the global, local, or SSVN. 6037: 6038: @cindex libfreem, freem_ref_t.status 6039: @item @option{status} 6040: This member gives us various API status values after the API call returns. In general, this value is also returned by each API function. 6041: 6042: @cindex libfreem, freem_ref_t.subscript_count 6043: @item @option{subscript_count} 6044: The number of subscripts to be passed into the API function being called. This value represents the maximum index into the first dimension of the @code{subscripts} array. 6045: 6046: @cindex libfreem, freem_ref_t.subscripts 6047: @item @option{subscripts} 6048: A two-dimensional array containing the subscripts to which we are referring in this API call. 6049: 6050: @end table 6051: 6052: @section freem_ent_t Data Structure 6053: @cindex libfreem, data structures: freem_ent_t 6054: 6055: The @code{freem_function()} and @code{freem_procedure()} APIs in @code{libfreem} use the @code{freem_ent_t} struct in order to indicate the name of the entry point being called, any arguments being passed to it, and the return value of the called function (not used for @code{freem_procedure()}). 6056: 6057: The data structure, defined in @file{freem.h}, looks like this: 6058: 6059: @verbatim 6060: typedef struct freem_ent_t { 6061: 6062: /* name of function or procedure entry point */ 6063: char name[256]; 6064: 6065: /* return value */ 6066: char value[STRLEN]; 6067: 6068: /* value of ierr on return */ 6069: short status; 6070: 6071: /* argument count and array */ 6072: unsigned int argument_count; 6073: char arguments[255][256]; 6074: 6075: } freem_ent_t; 6076: @end verbatim 6077: 6078: @emph{freem_ent_t Members} 6079: 6080: @table @asis 6081: 6082: @item @option{name} 6083: @cindex libfreem, freem_ent_t.name 6084: The @option{name} member contains the name of the extrinsic function or procedure to be called. 6085: 6086: @cindex libfreem, freem_ent_t.value 6087: @item @option{value} 6088: This member contains the value returned by the function called. Not used by @code{freem_procedure()}. 6089: 6090: @cindex libfreem, freem_ent_t.status 6091: @item @option{status} 6092: This member gives us the value of @code{ierr} after the function or procedure call returns. The possible values of @code{ierr} are listed in @code{merr.h}. 6093: 6094: @cindex libfreem, freem_ent_t.argument_count 6095: @item @option{argument_count} 6096: The number of arguments to be passed into the extrinsic function or procedure being called. This value represents the maximum index into the first dimension of the @code{arguments} array. 6097: 6098: @cindex libfreem, freem_ent_t.arguments 6099: @item @option{arguments} 6100: A two-dimensional array containing the arguments to be passed into the extrinsic function or procedure being called. 6101: 6102: @end table 6103: 6104: @section freem_init() 6105: @cindex libfreem, freem_init() 6106: 6107: Initializes @code{libfreem} in preparation for calling other APIs. 6108: 6109: @emph{Synopsis} 6110: 6111: @code{pid_t freem_init(char *environment_name, char *namespace_name);} 6112: 6113: @emph{Parameters} 6114: 6115: @table @asis 6116: @item @code{environment_name} 6117: Specifies the environment to use. 6118: @item @code{namespace_name} 6119: Specifies the namespace to use. 6120: @end table 6121: 6122: @emph{Return Values} 6123: 6124: Returns the process ID of the @code{libfreem} process on success, or @code{-1} on failure. 6125: 6126: @emph{Example} 6127: 6128: This example prompts the user to enter a FreeM namespace and then attempts to initialize @code{libfreem} to use the selected namespace. 6129: 6130: @verbatim 6131: #include <stdio.h> 6132: #include <string.h> 6133: #include <freem.h> 6134: 6135: int main(int argc, char **argv, char **envp) 6136: { 6137: char namespace[256]; 6138: 6139: /* get the namespace name to use */ 6140: printf("Enter FreeM namespace to use: "); 6141: fgets(namespace, 255, stdin); 6142: 6143: /* remove the trailing newline */ 6144: namespace[strcspn(buffer, "\n")] = '\0'; 6145: 6146: /* initialize libfreem using the provided namespace */ 6147: if(freem_init("DEFAULT", namespace) == TRUE) { 6148: printf("\nSuccess\n"); 6149: } 6150: else { 6151: printf("\nFailure\n"); 6152: } 6153: 6154: return 0; 6155: } 6156: @end verbatim 6157: 6158: @section freem_version() 6159: @cindex libfreem, freem_version() 6160: 6161: Returns the version of FreeM in use. 6162: 6163: @emph{Synopsis} 6164: 6165: @code{short freem_version(char *result);} 6166: 6167: @emph{Parameters} 6168: 6169: @table @asis 6170: @item @code{result} 6171: The @code{result} parameter is a pointer to a buffer in which the FreeM version information will be returned. The caller must allocate memory for this buffer prior to calling this API. It should be at least 20 bytes in length. 6172: @end table 6173: 6174: @emph{Return Value} 6175: 6176: Returns @code{0}. 6177: 6178: @emph{Example} 6179: 6180: This example will display the FreeM version on standard output. 6181: 6182: @verbatim 6183: #include <stdio.h> 6184: #include <string.h> 6185: #include <freem.h> 6186: 6187: int main(int argc, char **argv, char **envp) 6188: { 6189: char version[20] = {0}; 6190: 6191: freem_init(``USER''); 6192: freem_version(version); 6193: 6194: printf(``FreeM version: %s\n'', version); 6195: 6196: } 6197: @end verbatim 6198: 6199: @section freem_set() 6200: @cindex libfreem, freem_set() 6201: 6202: Sets a FreeM local node, global node, or writable SSVN node. 6203: 6204: @emph{Synopsis} 6205: 6206: @code{short freem_set(freem_ref_t *ref);} 6207: 6208: @emph{Parameters} 6209: 6210: @table @asis 6211: @item @code{freem_ref_t} 6212: This parameter is a pointer to a @code{freem_ref_t} struct. The caller must allocate the memory for this struct. 6213: @end table 6214: 6215: @emph{Return Value} 6216: 6217: Returns @code{OK} on success, or one of the other error values defined in @code{merr.h}. 6218: 6219: @emph{Example} 6220: 6221: This example sets the value @code{blue} into global node @code{^car("color")}. 6222: 6223: @verbatim 6224: #include <stdio.h> 6225: #include <string.h> 6226: #include <freem.h> 6227: 6228: int main(int argc, char **argv, char **envp) 6229: { 6230: freem_ref_t ref; 6231: 6232: /* we're setting a global */ 6233: ref.reftype = MREF_RT_GLOBAL; 6234: 6235: /* access global "car" */ 6236: strcpy(ref.name, "car"); 6237: 6238: /* set up the subscripts */ 6239: ref.subscript_count = 1; 6240: strcpy(ref.subscripts[0], "color"); 6241: 6242: 6243: /* use the USER namespace */ 6244: freem_init("USER"); 6245: 6246: /* write the data out */ 6247: freem_set(&ref); 6248: 6249: } 6250: @end verbatim 6251: 6252: @section freem_get() 6253: @cindex libfreem, freem_get() 6254: 6255: Retrieves a FreeM local node, global node, or writable SSVN node. 6256: 6257: @emph{Synopsis} 6258: 6259: @code{short freem_get(freem_ref_t *ref);} 6260: 6261: @emph{Parameters} 6262: 6263: @table @asis 6264: @item @code{freem_ref_t} 6265: This parameter is a pointer to a @code{freem_ref_t} struct. The caller must allocate the memory for this struct. 6266: @end table 6267: 6268: @emph{Return Value} 6269: 6270: Returns @code{OK} on success, or one of the other error values defined in @code{merr.h}. 6271: 6272: @emph{Example} 6273: 6274: This example retrieves the character set of the current process. 6275: 6276: @verbatim 6277: #include <stdio.h> 6278: #include <sys/types.h> 6279: #include <unistd.h> 6280: #include <string.h> 6281: #include <freem.h> 6282: 6283: int main(int argc, char **argv, char) 6284: { 6285: pid_t pid; 6286: freem_ref_t ref; 6287: 6288: /* get the PID of this process */ 6289: pid = getpid(); 6290: 6291: /* we want to access an SSVN */ 6292: ref.reftype = MREF_RT_SSV; 6293: 6294: /* set up the name and subscripts */ 6295: strcpy(ref.name, "JOB"); 6296: 6297: ref.subscript_count = 2; 6298: sprintf(ref.subscripts[0], "%d", pid); 6299: strcpy(ref.subscripts[1], "CHARACTER"); 6300: 6301: /* initialize libfreem, using the USER namespace */ 6302: freem_init("USER"); 6303: 6304: /* call libfreem API */ 6305: freem_get(&ref); 6306: 6307: /* output the character set info */ 6308: printf("PID %d character set is '%s'\n", pid, ref.value); 6309: } 6310: @end verbatim 6311: 6312: @section freem_kill() 6313: @cindex libfreem, freem_kill() 6314: 6315: Deletes a FreeM local node, global node, or killable SSVN node, as well as all of its children. 6316: 6317: @emph{short freem_kill(freem_ref_t *ref);} 6318: 6319: @emph{Parameters} 6320: 6321: @table @asis 6322: @item @code{freem_ref_t} 6323: This parameter is a pointer to a @code{freem_ref_t} struct. The caller must allocate the memory for this struct. 6324: @end table 6325: 6326: @emph{Return Value} 6327: 6328: Returns @code{OK} on success, or one of the other error values defined in @code{merr.h}. 6329: 6330: @emph{Example} 6331: 6332: @verbatim 6333: #include <stdio.h> 6334: #include <string.h> 6335: #include <freem.h> 6336: 6337: int main(int argc, char **argv, char **envp) 6338: { 6339: freem_ref_t ref; 6340: 6341: /* we're killing a global node */ 6342: ref.reftype = MREF_RT_GLOBAL; 6343: 6344: /* access global "car" */ 6345: strcpy(ref.name, "car"); 6346: 6347: /* set up the subscripts */ 6348: ref.subscript_count = 0; 6349: 6350: /* use the USER namespace */ 6351: freem_init("USER"); 6352: 6353: /* kill the global and all its descendant subscripts */ 6354: freem_kill(&ref); 6355: } 6356: @end verbatim 6357: 6358: @section freem_data() 6359: @cindex libfreem, freem_data() 6360: 6361: @section freem_order() 6362: @cindex libfreem, freem_order() 6363: 6364: @section freem_query() 6365: @cindex libfreem, freem_query() 6366: 6367: @section freem_lock() 6368: @cindex libfreem, freem_lock() 6369: 6370: @section freem_unlock() 6371: @cindex libfreem, freem_unlock() 6372: 6373: @section freem_tstart() 6374: @cindex libfreem, freem_tstart() 6375: 6376: @section freem_trestart() 6377: @cindex libfreem, freem_trestart() 6378: 6379: @section freem_trollback() 6380: @cindex libfreem, freem_trollback() 6381: 6382: @section freem_tlevel() 6383: @cindex libfreem, freem_tlevel() 6384: 6385: @section freem_tcommit() 6386: @cindex libfreem, freem_tcommit() 6387: 6388: @section freem_function() 6389: @cindex libfreem, freem_function() 6390: 6391: @section freem_procedure() 6392: @cindex libfreem, freem_procedure() 6393: 6394: @node FreeM Administrator 6395: @appendix FreeM Administrator 6396: @cindex utilities, system management 6397: @cindex utilities, fmadm 6398: @cindex fmadm 6399: 6400: The @code{fmadm} utility is the preferred method of managing a FreeM installation, and will eventually replace all of the existing utilities. 6401: Unlike the existing, legacy utilities, @code{fmadm} presents a consistent, simple interface for all FreeM management tasks, and is namespace-aware. 6402: This appendix will document each @code{fmadm} facility as it is implemented, until all of the legacy utilities have been replaced. 6403: 6404: The @code{fmadm} utility's functions all follow the below, consistent syntax: 6405: 6406: @example 6407: usage: fmadm <action> <object> <namespace> [OPTIONS] 6408: @end example 6409: 6410: The @emph{action} keyword can be one of the following: 6411: 6412: @table @emph 6413: 6414: @item list 6415: Lists instances of @emph{object} 6416: 6417: @item examine 6418: Examines a single instance of @emph{object} 6419: 6420: @item verify 6421: Verifies the integrity of @emph{object} 6422: 6423: @item compact 6424: Compacts @emph{object} 6425: 6426: @item repair 6427: Repairs integrity problems in @emph{object} 6428: 6429: @item create 6430: Creates an instance of @emph{object} 6431: 6432: @item remove 6433: Removes an instance of @emph{object} 6434: 6435: @item import 6436: Imports an @emph{object} 6437: 6438: @item export 6439: Exports an @emph{object} 6440: 6441: @item backup 6442: Creates a backup of @emph{object} 6443: 6444: @item restore 6445: Restores a backup of @emph{object} 6446: 6447: @item migrate 6448: Migrates an instance of @emph{object} from an older FreeM version to the current version 6449: 6450: @item edit 6451: Edits an instance of @emph{object} 6452: 6453: @end table 6454: 6455: The @emph{object} keyword can be one of the following: 6456: 6457: @table @emph 6458: 6459: @item lock 6460: The FreeM @code{LOCK} table. 6461: 6462: Supported actions are @code{list} and @code{remove}. 6463: 6464: @item journal 6465: FreeM after-image journaling. 6466: 6467: Supported actions are @code{examine} and @code{restore}. 6468: 6469: The @code{examine} action will dump the after-image journal entries for the selected namespace in human-readable format. 6470: 6471: The @code{restore} action will play after-image journals forward for the selected namespace. 6472: 6473: @item namespace 6474: FreeM namespaces (collections of M routines and globals). 6475: 6476: No actions yet implemented. 6477: 6478: @item global 6479: The data files representing each FreeM @emph{global}. 6480: 6481: Supported actions are @code{list}, @code{examine}, @code{remove}, and @code{verify}. 6482: 6483: @item routine 6484: An M routine, stored as a @code{.m} file. 6485: 6486: Supported actions are @code{list}, @code{examine}, @code{remove}, @code{import}, @code{export}, @code{backup}, and @code{edit}. 6487: 6488: @item job 6489: A UNIX process representing an instance of the FreeM runtime. 6490: 6491: Supported actions are @code{list} and @code{examine}. 6492: 6493: @end table 6494: 6495: 6496: @node FreeM Legacy Utilities 6497: @appendix FreeM Legacy Utilities 6498: @cindex utilities, legacy 6499: 6500: @section Global Compactor (gcompact) 6501: @cindex utilities, legacy, gcompact 6502: 6503: Compacts the specified global in place. 6504: 6505: @emph{Syntax} 6506: 6507: @example 6508: gcompact @emph{/path/to/global/file} 6509: @end example 6510: 6511: @section Block Examiner (gfix) 6512: @cindex utilities, gfix 6513: 6514: The @emph{gfix} interactive utility program permits navigation of the B-tree structure of the specified global a block at a time. 6515: 6516: @emph{Syntax} 6517: 6518: @example 6519: gfix @emph{</path/to/global/file>} 6520: @end example 6521: 6522: @section Global Repair Tool (grestore) 6523: @cindex utilities, legacy, grestore 6524: 6525: This utility will fix problems with the specified global. 6526: 6527: @emph{Syntax} 6528: 6529: @example 6530: grestore @emph{</path/to/global/file>} 6531: @end example 6532: 6533: @node FreeM VIEW Commands and Functions 6534: @appendix FreeM VIEW Commands and Functions 6535: 6536: @section VIEW 16: Total Count of Error Messages/View Single Error Message 6537: @cindex VIEW commands/functions, 16, total count of error messages/view single error message 6538: 6539: Unknown semantics 6540: 6541: @section VIEW 17: Intrinsic Z-Commands 6542: @cindex VIEW commands/functions, 17, intrinsic Z-commands 6543: 6544: Allows the user to retrieve or specify the list of intrinsic Z-commands that FreeM will attempt to run internally, allowing intrinsic Z-commands implemented internally to be replaced with M equivalents implemented as %-routines in the @code{SYSTEM} namespace. 6545: 6546: @section VIEW 18: Intrinsic Z-Functions 6547: @cindex VIEW commands/functions, 18, intrinsic Z-functions 6548: 6549: Allows the user to retrieve or specify the list of intrinsic Z-functions that FreeM will attempt to run internally, allowing intrinsic Z-functions implemented internally to be replaced with M equivalents implemented as %-routines in the @code{SYSTEM} namespace. 6550: 6551: @section VIEW 19: Intrinsic Special Variables 6552: @cindex VIEW commands/functions, 19, intrinsic special variables 6553: 6554: Allows the user to retrieve or specify which special variables are implemented internally. 6555: 6556: @section VIEW 20: Break Service Code 6557: @cindex VIEW commands/functions, 20, break service code 6558: 6559: Allows the user to view or specify the code that will be run when a @code{BREAK} is encountered. 6560: 6561: @section VIEW 21: View Size of Last Global 6562: @cindex VIEW commands/functions, 21, view size of last global 6563: 6564: Allows the user to view the size of the last referenced global. 6565: 6566: @section VIEW 22: Count VIEW 22 Aliases 6567: @cindex VIEW commands/functions, 22, count VIEW 22 aliases 6568: 6569: Retrieves the number of VIEW 22 aliases in effect. 6570: 6571: @section VIEW 23: View Contents of Input Buffer 6572: @cindex VIEW commands/functions, 23, input buffer contents 6573: 6574: Retrieves the contents of the I/O input buffer. 6575: 6576: @section VIEW 24: Maximum Number of Screen Rows 6577: @cindex VIEW commands/functions, 24, maximum number of screen rows 6578: 6579: Retrieves the maximum number of screen rows supported in the current FreeM build. 6580: 6581: @section VIEW 25: Maximum Number of Screen Columns 6582: @cindex VIEW commands/functions, 25, maximum number of screen columns 6583: 6584: Retrieves the maximum number of screen columns supported in the current FreeM build. 6585: 6586: @section VIEW 26: DO/FOR/XECUTE Stack Pointer 6587: @cindex VIEW commands/functions, 26, DO/FOR/XECUTE stack pointer 6588: 6589: Retrieves the @code{DO}, @code{FOR}, and @code{XECUTE} stack pointer. 6590: 6591: @section VIEW 27: DO/FOR/XECUTE Stack Pointer (On Error) 6592: @cindex VIEW commands/functions, 27, DO/FOR/XECUTE stack pointer, on error 6593: 6594: Retrieves the @code{DO}, @code{FOR}, and @code{XECUTE} stack pointer (on error). 6595: 6596: @section VIEW 29: Copy Symbol Table 6597: @cindex VIEW commands/functions, 29, copy symbol table 6598: 6599: Copies the symbol table? We aren't currently aware of what this means. 6600: 6601: @section VIEW 30: Inspect Arguments 6602: @cindex VIEW commands/functions, 30, inspect arguments 6603: 6604: Retrieves the arguments passed to the @code{freem} executable. 6605: 6606: @section VIEW 31: Count Environment Variables 6607: @cindex VIEW commands/functions, 31, count environment variables 6608: 6609: Allows the user to inspect the number of variables in the process environment table. 6610: 6611: @emph{Syntax} 6612: 6613: @example 6614: WRITE $VIEW(31),! 6615: @end example 6616: 6617: @node Implementation Limits 6618: @appendix Implementation Limits 6619: 6620: @cindex limitations, memory 6621: @cindex maximum size, routine 6622: @cindex maximum size, global 6623: @cindex maximum size, string 6624: 6625: @node US-ASCII Character Set 6626: @appendix US-ASCII Character Set 6627: 6628: @multitable {Code} {Character} 6629: @item Code @tab Character 6630: @item 000 @tab @code{<NUL>} 6631: @item 001 @tab @code{<SOH>} 6632: @item 002 @tab @code{<STX>} 6633: @item 003 @tab @code{<ETX>} 6634: @item 004 @tab @code{<EOT>} 6635: @item 005 @tab @code{<ENQ>} 6636: @item 006 @tab @code{<ACK>} 6637: @item 007 @tab @code{<BEL>} 6638: @item 008 @tab @code{<BS>} 6639: @item 009 @tab @code{<HT>} 6640: @item 010 @tab @code{<LF>} 6641: @item 011 @tab @code{<VT>} 6642: @item 012 @tab @code{<FF>} 6643: @item 013 @tab @code{<CR>} 6644: @item 014 @tab @code{<SO>} 6645: @item 015 @tab @code{<SI>} 6646: @item 016 @tab @code{<DLE>} 6647: @item 017 @tab @code{<DC1>} 6648: @item 018 @tab @code{<DC2>} 6649: @item 019 @tab @code{<DC3>} 6650: @item 020 @tab @code{<DC4>} 6651: @item 021 @tab @code{<NAK>} 6652: @item 022 @tab @code{<SYN>} 6653: @item 023 @tab @code{<ETB>} 6654: @item 024 @tab @code{<CAN>} 6655: @item 025 @tab @code{<EM>} 6656: @item 026 @tab @code{<SUB>} 6657: @item 027 @tab @code{<ESC>} 6658: @item 028 @tab @code{<FS>} 6659: @item 029 @tab @code{<GS>} 6660: @item 030 @tab @code{<RS>} 6661: @item 031 @tab @code{<US>} 6662: @item 032 @tab @code{<space>} 6663: @item 033 @tab ! 6664: @item 034 @tab `` 6665: @item 035 @tab # 6666: 6667: 6668: @end multitable 6669: 6670: @node FreeM Project Coding Standards 6671: @appendix FreeM Project Coding Standards 6672: 6673: @section Module Headers 6674: @cindex coding standards, module headers 6675: 6676: Module headers should adhere to the following format (where @code{Dollar} should be replaced with a dollar sign): 6677: 6678: @verbatim 6679: /* 6680: * DollarIdDollar 6681: * Function prototypes, structs, and macros for FreeM 6682: * binding library 6683: * 6684: * 6685: * Author: Serena Willis <snw@coherent-logic.com> 6686: * Copyright (C) 1998 MUG Deutschland 6687: * Copyright (C) <Year> Coherent Logic Development LLC 6688: * 6689: * This file is part of FreeM. 6690: * 6691: * FreeM is free software: you can redistribute it and/or modify 6692: * it under the terms of the GNU Affero Public License as published by 6693: * the Free Software Foundation, either version 3 of the License, or 6694: * (at your option) any later version. 6695: * 6696: * FreeM is distributed in the hope that it will be useful, 6697: * but WITHOUT ANY WARRANTY; without even the implied warranty of 6698: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 6699: * GNU Affero Public License for more details. 6700: * 6701: * You should have received a copy of the GNU Affero Public License 6702: * along with FreeM. If not, see <https://www.gnu.org/licenses/>. 6703: * 6704: * DollarLogDollar 6705: * 6706: * SPDX-FileCopyrightText: (C) 2025 Coherent Logic Development LLC 6707: * SPDX-License-Identifier: AGPL-3.0-or-later 6708: **/ 6709: @end verbatim 6710: 6711: @section Variable Naming 6712: @cindex coding standards, variable naming 6713: 6714: Variables should be named in all lowercase letters, and words within them delimited by underscores, such as @code{my_useful_variable}. @code{PascalCase} and @code{camelCase} are not to be used in this codebase under any circumstances. 6715: 6716: Constants defined via the C preprocessor should be in all uppercase letters, with words within them likewise delimited by underscores, such as: 6717: 6718: @verbatim 6719: #define MY_USEFUL_CONSTANT 1 6720: @end verbatim 6721: 6722: @section Indentation and General Layout 6723: @cindex coding standards, indentation 6724: @cindex coding standards, layout 6725: 6726: This project uses four spaces for indentation. Tabs are not to be used under any circumstances, and all source files must use a linefeed character to delineate lines. If you are working on a Windows machine, you must take care to follow this, as Windows will use a carriage return followed by a linefeed by default. 6727: 6728: This project follows a modified version of what is known as the Stroustrup indentation style. 6729: 6730: @section Brace Placement (Functions) 6731: @cindex coding standards, brace placement, functions 6732: 6733: We use modern, ANSI-style function prototypes, with the type specifier on the same line as the function name. You may encounter other styles in the code, but we are transitioning to the new style as time permits. 6734: 6735: Below is a correct example: 6736: 6737: @verbatim 6738: int main(int argc, char **argv, char **envp) 6739: { 6740: 6741: } 6742: @end verbatim 6743: 6744: @section Brace Placement (if-for-while-do) 6745: @cindex coding standards, brace placement, if-for-while-do 6746: 6747: The @code{if} keyword should be followed by one space, then the opening paren and conditional expression. We also use Stroustrup-style @code{else} blocks, rather than the K&R 'cuddled' @code{else}: 6748: 6749: @verbatim 6750: if (x) { 6751: ... 6752: } 6753: else { 6754: ... 6755: } 6756: 6757: while (1) { 6758: ... 6759: } 6760: 6761: for (i = 1; i < 10; i++) { 6762: ... 6763: } 6764: 6765: do { 6766: ... 6767: } while (x); 6768: @end verbatim 6769: 6770: Single-statement if blocks should be isolated to a single line: 6771: 6772: @verbatim 6773: if (x) stmt(); 6774: @end verbatim 6775: 6776: not: 6777: 6778: @verbatim 6779: if (x) 6780: stmt (); 6781: @end verbatim 6782: 6783: Notice that there is a space between @code{if} and @code{(x)}, and also between @code{stmt} and @code{()}. This should be followed throughout the code. 6784: 6785: If an @code{if} block has an @code{else if} or @code{else}, all parts of the construct must be bracketed, even if one or more of them contain only one statement: 6786: 6787: @verbatim 6788: if (x) { 6789: foo(); 6790: } 6791: else if (y) { 6792: bar(); 6793: } 6794: else { 6795: bas(); 6796: } 6797: @end verbatim 6798: 6799: @section Labels and goto 6800: @cindex coding standards, labels 6801: @cindex coding standards, goto 6802: 6803: Labels must begin in column 1, and have two lines of vertical space above and one beneath. 6804: 6805: @section Preprocessor Conditionals 6806: @section coding standards, preprocessor conditionals 6807: 6808: I have struggled with this, but have settled upon the standard practice of keeping them in column 1. 6809: 6810: @section Overall Program Spacing 6811: @cindex coding standards, spacing of programs 6812: 6813: @itemize @bullet 6814: @item 6815: Variable declarations fall immediately beneath the opening curly brace, and should initialize the variable right there whenever initialization is used. 6816: 6817: @item 6818: One line between the last variable declaration and the first line of real code. 6819: 6820: @item 6821: The @code{return} statement of a function (when used as the last line of a function) should have one blank line above it and none below it. 6822: 6823: @item 6824: Really long functions (those whose entire body is longer than 24 lines) should have a comment immediately following the closing curly brace of the function, telling you what function the closing brace terminates. 6825: @end itemize 6826: 6827: @section The switch() Statement 6828: @cindex coding standards, switch() 6829: 6830: We indent @code{case} one level beneath @code{switch()}, and the code within each @code{case} beneath the @code{case}. Each @code{case} should have one line of vertical whitespace above it: 6831: 6832: @verbatim 6833: switch(foo) { 6834: 6835: case some_const: 6836: foo(); 6837: 6838: break; 6839: 6840: case some_other_const: 6841: bar(); 6842: 6843: break; 6844: 6845: default: 6846: exit(1); 6847: 6848: break; 6849: } 6850: @end verbatim 6851: 6852: @section Comments 6853: @cindex coding standards, comments 6854: 6855: We use C-style comments (@code{/* comment */}) exclusively, even on single-line comments. C++ comments (@code{// comment}) are not permitted. 6856: 6857: @node Index 6858: @unnumbered Index 6859: 6860: @printindex cp 6861: 6862: @bye