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