freem.texi 102 KB
Newer Older
John P. Willis's avatar
John P. Willis committed
1
\input texinfo
John P. Willis's avatar
John P. Willis committed
2
@paragraphindent 0
John P. Willis's avatar
John P. Willis committed
3 4 5 6
@setfilename freem.info
@settitle The FreeM Manual

@copying
7
This manual is for FreeM, (version 0.27.1), which is a free and open-source implementation of the M programming language and database system.
John P. Willis's avatar
John P. Willis committed
8 9 10 11 12


Copyright @copyright{} 2020 Coherent Logic Development LLC

@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.
John P. Willis's avatar
John P. Willis committed
14 15 16 17
@end quotation
@end copying

@titlepage
18

John P. Willis's avatar
John P. Willis committed
19
@title The FreeM Manual
John P. Willis's avatar
John P. Willis committed
20
@subtitle @sc{The Official Manual of FreeM}
21
@subtitle Version 0.27.1
22 23
@c@vskip 10pt
@c@center @image{freem-logo-sm,,,,.png}
John P. Willis's avatar
John P. Willis committed
24 25 26 27 28 29 30 31 32 33 34
@author John P. Willis
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents

@ifnottex
@node Top
@top The FreeM Manual

35
This is the official manual for the FreeM programming language and database.
John P. Willis's avatar
John P. Willis committed
36 37
@end ifnottex

38 39
@dircategory The FreeM Manual
@direntry
40
* FreeM: (freem).                       The FreeM M programming language and database.
41 42
@end direntry

John P. Willis's avatar
John P. Willis committed
43
@menu
John P. Willis's avatar
John P. Willis committed
44
* Introduction::                        About the FreeM Project, its history, and its goals.
John P. Willis's avatar
John P. Willis committed
45
* FreeM Invocation::                    How to invoke FreeM from the command line.
46
* The FreeM Direct-Mode Environment::   Executing M programs interactively.
John P. Willis's avatar
John P. Willis committed
47

John P. Willis's avatar
John P. Willis committed
48 49 50 51 52
* Intrinsic Special Variables::         Intrinsic Special Variables.
* Intrinsic Functions::                 Intrinsic Functions.
* Commands::                            Commands.
* Structured System Variables::         Structured System Variables.
* Operators::                           FreeM Operators.
John P. Willis's avatar
John P. Willis committed
53

John P. Willis's avatar
John P. Willis committed
54 55 56 57 58 59 60 61 62
* Sequential I/O::                      Processing sequential files in FreeM.
* Network I/O::                         Handling network sockets in FreeM.

* Asynchronous Event Handling::         Handling asynchronous events in FreeM.
* Synchronous Event Handling::          Synchronous events in FreeM.

* GUI Programming with MWAPI::          Creating graphical interfaces in FreeM.

* User-Defined Z Commands::             Adding your own Z commands to FreeM.
John P. Willis's avatar
John P. Willis committed
63
* User-Defined Z Functions::            Adding your own Z functions to FreeM.
John P. Willis's avatar
John P. Willis committed
64
* User-Defined SSVs::                   Adding your own SSVs to FreeM.
John P. Willis's avatar
John P. Willis committed
65

66
* System Library Routines::             FreeM built-in library of M routines.
John P. Willis's avatar
John P. Willis committed
67

68 69 70
* Error Processing::                    How to handle errors in M program code.
* Debugging::                           The program development cycle of FreeM.

John P. Willis's avatar
John P. Willis committed
71
* System Configuration::                Configuring your FreeM installation.
John P. Willis's avatar
John P. Willis committed
72
* Accessing FreeM from C Programs::     How to use the mlib interface.
John P. Willis's avatar
John P. Willis committed
73

74 75
* FreeM Administrator::                 The fmadm system manager tool.
* FreeM Legacy Utilities::              FreeM legacy system manager utilities.
John P. Willis's avatar
John P. Willis committed
76 77
* FreeM VIEW Commands and Functions::   Getting and setting info about FreeM internals.
* Implementation Limits::               FreeM limitations.
John P. Willis's avatar
John P. Willis committed
78
* US-ASCII Character Set::              The US-ASCII character set.
John P. Willis's avatar
John P. Willis committed
79
* FreeM Project Coding Standards::      How to write code for submission to the FreeM project.
80
* Conformance Clause::                  FreeM conformance to ANSI X11 Standard M.
John P. Willis's avatar
John P. Willis committed
81 82 83 84

* Index::               Complete index.
@end menu

John P. Willis's avatar
John P. Willis committed
85 86 87 88
@node Introduction
@unnumbered Introduction


89
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.
John P. Willis's avatar
John P. Willis committed
90

John P. Willis's avatar
John P. Willis committed
91 92 93
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 John 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.

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.
John P. Willis's avatar
John P. Willis committed
94 95 96 97 98 99 100

@section Production Readiness

FreeM is not yet production-ready. There are several show-stopping bugs that preclude a general release for public use:

@itemize @bullet
@item
John P. Willis's avatar
John P. Willis committed
101
SSVs, aside from @code{^$JOB}, @code{^$DEVICE}, @code{^$EVENT}, and @code{^$ZPROCESS} are not implemented.
John P. Willis's avatar
John P. Willis committed
102 103

@item
John P. Willis's avatar
John P. Willis committed
104
@code{VIEW} commands and @code{$VIEW} functions are used extensively to configure and inspect the run-time behavior of FreeM, rather than the "canonical" SSV-based approach.
John P. Willis's avatar
John P. Willis committed
105 106 107

@item
Server sockets are not yet implemented.
John P. Willis's avatar
John P. Willis committed
108 109 110 111
@end itemize

@section Contributors
Current contributors denoted with a @emph{+} following their name and role.
John P. Willis's avatar
John P. Willis committed
112
@cindex contributors, ha-Ashkenaz, Shalom
John P. Willis's avatar
John P. Willis committed
113
@cindex contributors, Best, John
John P. Willis's avatar
John P. Willis committed
114
@cindex contributors, Diamond, Jon
John P. Willis's avatar
John P. Willis committed
115
@cindex contributors, Fox, Ronald L.
John P. Willis's avatar
John P. Willis committed
116 117 118 119 120 121 122 123 124 125
@cindex contributors, Gerum, Winfried
@cindex contributors, Kreis, Greg
@cindex contributors, Landis, Larry
@cindex contributors, Marshall, Frederick D.S.
@cindex contributors, Milligan, Lloyd
@cindex contributors, Morris, Steve
@cindex contributors, Murray, John
@cindex contributors, Pastoors, Wilhelm
@cindex contributors, Schell, Kate
@cindex contributors, Schofield, Lyle
126
@cindex contributors, Stefanik, Jim
John P. Willis's avatar
John P. Willis committed
127 128 129 130 131 132
@cindex contributors, Trocha, Axel
@cindex contributors, Walters, Dick
@cindex contributors, Whitten, David
@cindex contributors, Wicksell, David
@cindex contributors, Willis, John P.
@cindex contributors, Zeck, Steve
John P. Willis's avatar
John P. Willis committed
133 134 135 136 137 138

@itemize @bullet

@item
Shalom ha-Ashkenaz (Original Implementer)

John P. Willis's avatar
John P. Willis committed
139
@item
140
John Best (IBM i and OS/400)
John P. Willis's avatar
John P. Willis committed
141

John P. Willis's avatar
John P. Willis committed
142 143 144
@item
Jon Diamond (Library, Utilities, Conformance)

John P. Willis's avatar
John P. Willis committed
145 146 147
@item
Ronald L. Fox (Initial port to Red Hat 5/libc-6)

John P. Willis's avatar
John P. Willis committed
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
@item
Winfried Gerum (Code, Advice, MTA coordination)

@item
Greg Kreis (Hardhats coordination, Dependencies)

@item
Larry Landis (Coordination, Code, Documentation)

@item
Frederick D.S. Marshall (MDC Standards Conformance) @emph{+}

@item
Lloyd Milligan (Code, Testing, Documentation)

@item
Steve Morris (Code, Microsoft)

@item
John Murray (Code, Conformance)

@item
Wilhelm Pastoors (Testing, Documentation)

@item
Kate Schell (Coordination, Conformance, MTA, MDC, Advice)

@item
Lyle Schofield (Advice, Prioritization, Tracking, Project Management)

178
@item
179
Jim Stefanik (GNU/Linux on s390x, IBM AIX, IBM z/OS)
180

John P. Willis's avatar
John P. Willis committed
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
@item
Axel Trocha (Code, Utilities)

@item
Dick Walters (Project Lead, Chief Coordinator, MTA)

@item
David Whitten (QA Test Suite, MDC, Advice) @emph{+}

@item
David Wicksell (Debugging, Code, Testing) @emph{+}

@item
John Willis (Current Maintainer and Project Lead) @emph{+}

@item
Steve Zeck (Code)

@end itemize
John P. Willis's avatar
John P. Willis committed
200 201 202 203 204
@node FreeM Invocation
@chapter FreeM Invocation
@cindex invocation, command-line
@cindex options, command-line

John P. Willis's avatar
John P. Willis committed
205 206
@section Synopsis
@example
John P. Willis's avatar
John P. Willis committed
207
$ @command{./freem} [@emph{OPTIONS}...] [[-r <entryref>] | [--routine=<entryref>]]
John P. Willis's avatar
John P. Willis committed
208 209
@end example

John P. Willis's avatar
John P. Willis committed
210
When FreeM loads, it searches the @code{SYSTEM} namespace for the @code{^%ZFREEM} routine, and begins executing it.
John P. Willis's avatar
John P. Willis committed
211

John P. Willis's avatar
John P. Willis committed
212
When @code{-r} or @code{--routine} are passed on the command line, FreeM will load and run the specified routine instead of @code{^ZFREEM}. 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. 
John P. Willis's avatar
John P. Willis committed
213 214 215 216 217

@section Command-Line Options

@table @asis
@item @option{-h}, @option{--hardcopy}
John P. Willis's avatar
John P. Willis committed
218
Enables hardcopy mode, echoing all output to a disk file. By default, this disk file is @file{\$freem_base/@emph{<namespace-name>}/freem.hardcopy}, but can be changed with the following command:
219 220 221 222

@example
USER> VIEW 13:"@option{</path/to/hardcopy/file>}"
@end example
John P. Willis's avatar
John P. Willis committed
223

John P. Willis's avatar
John P. Willis committed
224 225
The file used for hardcopy mode may also be specified in @file{/etc/freem.conf} or @file{~/.freemrc}.

John P. Willis's avatar
John P. Willis committed
226
@item @option{-f}, @option{--filter}
227
Allows your M routines to be used as UNIX filters.
John P. Willis's avatar
John P. Willis committed
228 229 230 231 232 233 234 235 236 237 238

@item @option{-n}, @option{--noclear}
Disables automatic screen clearing when FreeM loads.

@item @option{-s}, @option{--standard}
Restricts the use of non-standard language features, including @code{$Z...} intrinsic special variables, @code{$Z...} intrinsic functions, @code{Z...} commands, as well as @code{VIEW} and @code{$VIEW}.

@item @option{-i}, @option{--import}
Causes your UNIX environment variables to be imported into FreeM's local symbol table.

@item @option{-r @emph{<entryref>}}, @option{--routine=@emph{<entryref>}}
John P. Willis's avatar
John P. Willis committed
239
Causes @code{<entryref>} to be executed at load, instead of @code{^%ZFREEM}.
John P. Willis's avatar
John P. Willis committed
240

John P. Willis's avatar
John P. Willis committed
241
@item @option{-n @emph{<namespace-name>}}, @option{--namespace=@emph{<namespace-name>}}
242
Selects the FreeM namespace to be entered on startup. Must be defined in @file{/etc/freem.conf}.
John P. Willis's avatar
John P. Willis committed
243

John P. Willis's avatar
John P. Willis committed
244
@end table
John P. Willis's avatar
John P. Willis committed
245

246 247 248 249 250
@section Using FreeM for Shell Scripting
@cindex routines, as shell scripts
@cindex shebang line
@cindex shell scripting

251
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.
252 253 254 255 256
The following example presumes that FreeM is installed at @file{/usr/local/bin/freem} and uses the @code{USER} namespace:

@example
#!/usr/local/bin/freem
MYSCRIPT ;
John P. Willis's avatar
John P. Willis committed
257
 SET ^$JOB($JOB,"NAMESPACE")="USER"
258
 WRITE "This is output from an M routine used as a shell script.",!
259 260 261
 Q
@end example

John P. Willis's avatar
John P. Willis committed
262
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.
263 264 265 266 267 268 269

You will also need to set the script's permissions to @emph{executable} in order for this to work:

@example
$ chmod +x @emph{myscript.m}
@end example

John P. Willis's avatar
John P. Willis committed
270 271 272 273
@node The FreeM Direct-Mode Environment
@chapter The FreeM Direct-Mode Environment
@cindex command line interface
@cindex direct mode
John P. Willis's avatar
John P. Willis committed
274 275 276
@cindex execution, interactive
@cindex modes, programmer

John P. Willis's avatar
John P. Willis committed
277 278 279 280

The FreeM direct-mode environment is the mode entered when FreeM is loaded without the use of @option{-r @emph{<entryref>}} or @option{--routine=@emph{<entryref>}}:

@example
John P. Willis's avatar
John P. Willis committed
281
Coherent Logic Development FreeM
282
Version 0.27.1-x86_64-Linux (commit 4ececff; jpw AT pasithea Tue 13 Oct 2020 09:03:27 AM MDT)
John P. Willis's avatar
John P. Willis committed
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313

           *
          * *
         *   *
    ***************
     * *       * *
      *  FreeM  *
     * *       * *
    ***************
         *   *
          * *     Copyright (C) 1998 MUG Deutschland
           *      Copyright (C) 2014, 2020 Coherent Logic Development LLC

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

   PID:              3343
   Principal I/O:    0:"/dev/pts/5"


USER>
John P. Willis's avatar
John P. Willis committed
314 315
@end example

John P. Willis's avatar
John P. Willis committed
316
The prompt (@code{USER>}) indicates the currently-active namespace. If any uncommitted direct-mode transactions have been started, the prompt will change to reflect the current value of @code{$TLEVEL}:
317 318

@example
John P. Willis's avatar
John P. Willis committed
319
TL1:USER>
320 321 322 323
@end example

In the above example, @code{TL1} indicates that @code{$TLEVEL} is currently @emph{1}.

John P. Willis's avatar
John P. Willis committed
324 325
@section Direct-Mode Commands

326
When you are in direct mode, in addition to M commands, a number of internal commands are available to help developers be more productive:
John P. Willis's avatar
John P. Willis committed
327 328 329 330 331 332

@table @asis

@item @command{?}
Accesses FreeM online help. Requires GNU @command{info(1)} to be installed on your local system.

John P. Willis's avatar
John P. Willis committed
333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
@item @command{events}
Writes a list of @emph{event classes} and their @code{ABLOCK} counts:

@example
USER> events
 
Event Class          Processing Mode ABLOCK Count
-----------          --------------- ------------
COMM                 Disabled        0
HALT                 Disabled        0
IPC                  Disabled        0
INTERRUPT            Disabled        0
POWER                Disabled        0
TIMER                Disabled        0
USER                 Disabled        0
WAPI                 Disabled        0
@end example

John P. Willis's avatar
John P. Willis committed
351 352 353 354 355 356 357
@item @command{history}
Prints a list of all the direct-mode commands you have entered across all sessions.

@item @command{rcl @emph{<history-index>}}
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.

@item @command{!@emph{<external-command>}}
358
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}.
John P. Willis's avatar
John P. Willis committed
359

360
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.
John P. Willis's avatar
John P. Willis committed
361

362
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{%}.
John P. Willis's avatar
John P. Willis committed
363

364 365 366 367
@code{%} contains the number of lines in the input or output. @code{%(1)..%(@emph{n})} contains the data for lines 1-@emph{n}.

@item @command{tdump}
Writes detailed information about the status of any pending transactions to @code{$PRINCIPAL}.
John P. Willis's avatar
John P. Willis committed
368 369 370

@end table

371 372 373 374 375 376
@cindex HALT, in direct-mode
If you issue a @code{HALT} command at the direct-mode prompt, you will exit out of FreeM. However, if you issue a @code{HALT} command when  @code{$TLEVEL} is greater than zero, you will be given the opportunity to commit or rollback any pending transactions:

@example
USER> TSTART
 
John P. Willis's avatar
John P. Willis committed
377

378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399
TL1:USER> SET ^MYGLOBAL=1
 
 
TL1:USER> HALT
 
UNCOMMITTED TRANSACTIONS EXIST:
 
 $TLEVEL 1*
  Operations for Transaction ID: k8xj1de
  1:	action = 0  key = ^MYGLOBAL  data = 1
 
Would you like to c)ommit or r)ollback the above transactions and their operations? ($TLEVEL = 1) r


Transactions have been rolled back.
@end example

In the above example, the user selected @code{r} to rollback the single pending transaction.

@section REPL Functionality
@cindex REPL, direct-mode

400
FreeM direct mode allows you to enter M expressions directly from the direct-mode prompt, as long as they begin with a number:
401 402 403 404 405 406 407 408 409 410 411 412

@example
USER> S DENOM=10
 
 
USER> 100/DENOM
 
10
USER> 
@end example

Such expressions will be immediately evaluated, and the result printed on @code{$PRINCIPAL}.
John P. Willis's avatar
John P. Willis committed
413

John P. Willis's avatar
John P. Willis committed
414 415
@node Intrinsic Special Variables
@chapter Intrinsic Special Variables
John P. Willis's avatar
John P. Willis committed
416 417 418 419 420 421
@cindex variables, intrinsic special

@section $DEVICE
@cindex $DEVICE
@cindex intrinsic special variables, $DEVICE

John P. Willis's avatar
John P. Willis committed
422 423 424 425
Returns the status of the device currently in use, and is writable.

If @code{$DEVICE} returns @emph{1}, an error condition exists on the current device.

John P. Willis's avatar
John P. Willis committed
426 427 428 429
@section $ECODE
@cindex $ECODE
@cindex intrinsic special variables, $ECODE

John P. Willis's avatar
John P. Willis committed
430 431
Returns a comma-delimited list of error conditions currently present, and is writable. An empty @code{$ECODE} indicates no errors.

John P. Willis's avatar
John P. Willis committed
432 433 434 435
@section $ESTACK
@cindex $ESTACK
@cindex intrinsic special variables, $ESTACK

John P. Willis's avatar
John P. Willis committed
436
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{$STACK} ISV in that it is @code{NEW}-able, and resets to a value of 0 when @code{NEW}ed.
John P. Willis's avatar
John P. Willis committed
437

John P. Willis's avatar
John P. Willis committed
438 439 440
@section $ETRAP
@cindex $ETRAP
@cindex intrinsic special variables, $ETRAP
John P. Willis's avatar
John P. Willis committed
441

John P. Willis's avatar
John P. Willis committed
442
Sets or retrieves the M code that is run when an error is encountered or @code{$ECODE} is set to a non-blank value. @code{$ETRAP} code executes when @code{$ECODE} becomes non-blank.
John P. Willis's avatar
John P. Willis committed
443

John P. Willis's avatar
John P. Willis committed
444 445 446 447 448

@section $HOROLOG
@cindex $HOROLOG
@cindex intrinsic special variables, $HOROLOG

449
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),
John P. Willis's avatar
John P. Willis committed
450 451
and @code{<seconds>} represents the number of seconds since the most recent midnight.

John P. Willis's avatar
John P. Willis committed
452 453 454 455
@section $IO
@cindex $IO
@cindex intrinsic special variables, $IO

John P. Willis's avatar
John P. Willis committed
456 457
Represents the current input/output device. Read-only.

John P. Willis's avatar
John P. Willis committed
458 459 460 461
@section $JOB
@cindex $JOB
@cindex intrinsic special variables, $JOB

John P. Willis's avatar
John P. Willis committed
462 463
Represents the process ID of the FreeM instance currently in use.

John P. Willis's avatar
John P. Willis committed
464 465 466 467
@section $KEY
@cindex $KEY
@cindex intrinsic special variables, $KEY

John P. Willis's avatar
John P. Willis committed
468 469
Represents the sequence of control characters that terminated the last @code{READ} command on @code{$IO}.

John P. Willis's avatar
John P. Willis committed
470 471 472 473
@section $PRINCIPAL
@cindex $PRINCIPAL
@cindex intrinsic special variables, $PRINCIPAL

John P. Willis's avatar
John P. Willis committed
474 475
Represents the primary input/output device. Usually a terminal or virtual terminal.

John P. Willis's avatar
John P. Willis committed
476 477 478 479
@section $QUIT
@cindex $QUIT
@cindex intrinsic special variables, $QUIT

John P. Willis's avatar
John P. Willis committed
480 481 482 483
If the current execution context was invoked as an extrinsic function, @code{$QUIT} returns @emph{1}. Otherwise, returns @emph{0}.

When @code{$QUIT} returns @emph{1}, a subsequent @code{QUIT} command must have an argument.

John P. Willis's avatar
John P. Willis committed
484 485 486 487
@section $STACK
@cindex $STACK
@cindex intrinsic special variables, $STACK

John P. Willis's avatar
John P. Willis committed
488 489
Represents the current stack level.

John P. Willis's avatar
John P. Willis committed
490 491 492 493
@section $STORAGE
@cindex $STORAGE
@cindex intrinsic special variables, $STORAGE

John P. Willis's avatar
John P. Willis committed
494 495
Represents the number of bytes of free space available in FreeM's heap.

John P. Willis's avatar
John P. Willis committed
496 497 498 499
@section $SYSTEM
@cindex $SYSTEM
@cindex intrinsic special variables, $SYSTEM

John P. Willis's avatar
John P. Willis committed
500 501
Returns the MDC system ID of FreeM.

John P. Willis's avatar
John P. Willis committed
502 503 504 505
@section $TEST
@cindex $TEST
@cindex intrinsic special variables, $TEST

506
@code{$TEST} is a writable, @code{NEW}-able ISV that is @emph{1} if the most recently evaluated expression was @emph{true}. Otherwise, returns @emph{0}.
John P. Willis's avatar
John P. Willis committed
507

John P. Willis's avatar
John P. Willis committed
508 509
@code{$TEST} is implicitly @code{NEW}ed when entering a new stack frame for extrinsic functions and argumentless @code{DO}. @code{$TEST}
is @emph{not} implicitly @code{NEW}ed when a new stack frame is entered with an argumented @code{DO}.
John P. Willis's avatar
John P. Willis committed
510

John P. Willis's avatar
John P. Willis committed
511 512 513 514
@section $TLEVEL
@cindex $TLEVEL
@cindex intrinsic special variables, $TLEVEL

John P. Willis's avatar
John P. Willis committed
515 516
Returns a numeric value indicating the current level of transaction nesting in the process. When @code{$TLEVEL} is greater than @emph{0},
uncommitted transactions exist.
John P. Willis's avatar
John P. Willis committed
517

John P. Willis's avatar
John P. Willis committed
518 519 520 521 522
@section $TRESTART
@cindex $TRESTART
@cindex intrinsic special variables, $TRESTART
@cindex intrinsic special variables, unimplemented

523
Returns an empty string, as FreeM transaction processing does not yet support restartable transactions.
John P. Willis's avatar
John P. Willis committed
524

John P. Willis's avatar
John P. Willis committed
525 526 527 528
@section $X
@cindex $X
@cindex intrinsic special variables, $X

John P. Willis's avatar
John P. Willis committed
529
Represents the current column position of the FreeM cursor.
John P. Willis's avatar
John P. Willis committed
530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554

@cartouche
@quotation
@emph{Non-Standard Behavior}

In FreeM, setting @code{$X} will move the FreeM cursor.
@end quotation
@end cartouche


@section $Y
@cindex $Y
@cindex intrinsic special variables, $Y

Represents the current row position of the FreeM cursor.

@cartouche
@quotation
@emph{Non-Standard Behavior}

In FreeM, setting @code{$Y} will move the FreeM cursor.
@end quotation
@end cartouche


John P. Willis's avatar
John P. Willis committed
555 556 557 558 559
@section $ZA
@cindex $ZA
@cindex intrinsic special variables, $ZA
@cindex intrinsic special variables, implementation-specific

560 561
On the @code{HOME} device, always @code{0}. On other devices, represents the byte offset to the beginning of the file.

John P. Willis's avatar
John P. Willis committed
562 563 564 565 566
@section $ZB
@cindex $ZB
@cindex intrinsic special variables, $ZB
@cindex intrinsic special variables, implementation-specific

567 568
Represents the last keystroke.

John P. Willis's avatar
John P. Willis committed
569 570 571 572 573 574 575 576 577 578
@section $ZCONTROLC
@cindex $ZCONTROLC
@cindex intrinsic special variables, $ZCONTROLC
@cindex intrinsic special variables, implementation-specific

@section $ZDATE
@cindex $ZDATE
@cindex intrinsic special variables, $ZDATE
@cindex intrinsic special variables, implementation-specific

579 580
Returns the current date, in @code{YYYY/MM/DD} format.

John P. Willis's avatar
John P. Willis committed
581 582 583 584 585
@section $ZERROR
@cindex $ZERROR
@cindex intrinsic special variables, $ZERROR
@cindex intrinsic special variables, implementation-specific

586 587
Returns the last error message.

John P. Willis's avatar
John P. Willis committed
588 589 590 591 592 593 594 595 596 597
@section $ZF
@cindex $ZF
@cindex intrinsic special variables, $ZF
@cindex intrinsic special variables, implementation-specific

@section $ZHOROLOG
@cindex $ZHOROLOG
@cindex intrinsic special variables, $ZHOROLOG
@cindex intrinsic special variables, implementation-specific

598 599
Output @code{$HOROLOG}-style time, with the addition of milliseconds.

John P. Willis's avatar
John P. Willis committed
600 601 602 603 604
@section $ZINRPT
@cindex $ZINRPT
@cindex intrinsic special variables, $ZINRPT
@cindex intrinsic special variables, implementation-specific

605 606
Gets or sets the interrupt enable/disable flag.

John P. Willis's avatar
John P. Willis committed
607 608 609 610 611
@section $ZJOB
@cindex $ZJOB
@cindex intrinsic special variables, $ZJOB
@cindex intrinsic special variables, implementation-specific

612 613
Returns the @code{$JOB} value of the parent process (used in subroutines started with the @code{JOB} command).

John P. Willis's avatar
John P. Willis committed
614 615 616 617 618
@section $ZLOCAL
@cindex $ZLOCAL
@cindex intrinsic special variables, $ZLOCAL
@cindex intrinsic special variables, implementation-specific

619 620
Returns the last local variable referenced.

John P. Willis's avatar
John P. Willis committed
621 622 623 624 625
@section $ZMATCHCONTROL
@cindex $ZMATCHCONTROL
@cindex intrinsic special variables, $ZMATCHCONTROL
@cindex intrinsic special variables, implementation-specific

626 627
Returns control characters.

John P. Willis's avatar
John P. Willis committed
628 629 630 631 632
@section $ZMATCHNUMERIC
@cindex $ZMATCHNUMERIC
@cindex intrinsic special variables, $ZMATCHNUMERIC
@cindex intrinsic special variables, implementation-specific

633 634
Returns all numbers @code{0}-@code{9}.

John P. Willis's avatar
John P. Willis committed
635 636 637 638 639
@section $ZMATCHPUNCTUATION
@cindex $ZMATCHPUNCTUATION
@cindex intrinsic special variables, $ZMATCHPUNCTUATION
@cindex intrinsic special variables, implementation-specific

640 641
Returns all punctuation characters.

John P. Willis's avatar
John P. Willis committed
642 643 644 645 646
@section $ZMATCHALPHABETIC
@cindex $ZMATCHALPHABETIC
@cindex intrinsic special variables, $ZMATCHALPHABETIC
@cindex intrinsic special variables, implementation-specific

647 648
Returns all alphabetic characters.

John P. Willis's avatar
John P. Willis committed
649 650 651 652 653
@section $ZMATCHLOWERCASE
@cindex $ZMATCHLOWERCASE
@cindex intrinsic special variables, $ZMATCHLOWERCASE
@cindex intrinsic special variables, implementation-specific

654 655
Returns all lowercase characters.

John P. Willis's avatar
John P. Willis committed
656 657 658 659 660
@section $ZMATCHUPPERCASE
@cindex $ZMATCHUPPERCASE
@cindex intrinsic special variables, $ZMATCHUPPERCASE
@cindex intrinsic special variables, implementation-specific

661 662
Returns all uppercase characters.

John P. Willis's avatar
John P. Willis committed
663 664 665 666 667
@section $ZMATCHEVERYTHING
@cindex $ZMATCHEVERYTHING
@cindex intrinsic special variables, $ZMATCHEVERYTHING
@cindex intrinsic special variables, implementation-specific

668
Returns control characters, numbers, punctuation, and alphabetic characters.
John P. Willis's avatar
John P. Willis committed
669 670 671 672 673 674

@section $ZPRECISION
@cindex $ZPRECISION
@cindex intrinsic special variables, $ZPRECISION
@cindex intrinsic special variables, implementation-specific

675 676
Gets or sets the number of digits of numeric precision used for fixed-point decimal arithmetic. Defaults to 100 digits.

John P. Willis's avatar
John P. Willis committed
677 678 679 680 681
@section $ZREFERENCE
@cindex $ZREFERENCE
@cindex intrinsic special variables, $ZREFERENCE
@cindex intrinsic special variables, implementation-specific

682 683
Returns the last @emph{glvn} referenced.

John P. Willis's avatar
John P. Willis committed
684 685 686 687 688 689 690 691 692 693
@section $ZSYSTEM
@cindex $ZSYSTEM
@cindex intrinsic special variables, $ZSYSTEM
@cindex intrinsic special variables, implementation-specific

@section $ZTIME
@cindex $ZTIME
@cindex intrinsic special variables, $ZTIME
@cindex intrinsic special variables, implementation-specific

694 695
Returns the system time in @code{HH:MM:SS} (24-hour) format.

John P. Willis's avatar
John P. Willis committed
696 697 698 699 700
@section $ZTRAP
@cindex $ZTRAP
@cindex intrinsic special variables, $ZTRAP
@cindex intrinsic special variables, implementation-specific

701 702 703 704 705 706 707 708 709 710
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.

In FreeM-style error processing, @code{$ZTRAP} is specific to each program execution stack level.

In DSM 2.0-style error processing, @code{$ZTRAP} is the same for all program execution stack levels.

When FreeM encounters an error, if @code{$ZTRAP} is nonempty and @code{$ETRAP} is empty, FreeM will perform an implicit @code{GOTO} to the entryref indicated in @code{$ZTRAP}.

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.

John P. Willis's avatar
John P. Willis committed
711 712 713 714
@section $ZVERSION
@cindex $ZVERSION
@cindex intrinsic special variables, $ZVERSION
@cindex intrinsic special variables, implementation-specific
John P. Willis's avatar
John P. Willis committed
715

716 717
Returns the version of FreeM in use, as well as the git commit hash, username, host, and date and time of the build in use.

John P. Willis's avatar
John P. Willis committed
718 719 720
@node Intrinsic Functions
@chapter Intrinsic Functions

John P. Willis's avatar
John P. Willis committed
721 722 723 724
@section $ASCII
@cindex $ASCII
@cindex intrinsic functions, $ASCII

John P. Willis's avatar
John P. Willis committed
725 726 727 728 729 730 731 732 733
Returns the ASCII code (in decimal) for one character in a string.

@example
SET RESULT=$ASCII(@emph{<string>}[,@emph{<index>}])
@end example


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>}.

John P. Willis's avatar
John P. Willis committed
734 735 736 737
@section $CHAR
@cindex $CHAR
@cindex intrinsic functions, $CHAR

John P. Willis's avatar
John P. Willis committed
738 739 740 741 742 743
Returns a string of characters corresponding to a list of ASCII codes.

@example
SET RESULT=$CHAR(@emph{<ascii-code>}[,@emph{<ascii-code>},...])
@end example

John P. Willis's avatar
John P. Willis committed
744 745 746 747
@section $DATA
@cindex $DATA
@cindex intrinsic functions, $DATA

John P. Willis's avatar
John P. Willis committed
748 749 750 751 752 753 754 755 756 757 758 759 760 761 762
Returns a numeric value 0, 1, 10, or 11, depending on whether a referenced node is defined, has data, or has children:

@example
SET RESULT=$DATA(@emph{<node>})
@end example

The return values are as follows:

@example
0: @emph{<node>} is undefined
1: @emph{<node>} has data but no children
10: @emph{<node>} has children but no data
11: @emph{<node>} has children and data
@end example

John P. Willis's avatar
John P. Willis committed
763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830
@section $EXTRACT
@cindex $EXTRACT
@cindex intrinsic functions, $EXTRACT

@section $FIND
@cindex $FIND
@cindex intrinsic functions, $FIND

@section $FNUMBER
@cindex $FNUMBER
@cindex intrinsic functions, $FNUMBER

@section $GET
@cindex $GET
@cindex intrinsic functions, $GET

@section $JUSTIFY
@cindex $JUSTIFY
@cindex intrinsic functions, $JUSTIFY

@section $LENGTH
@cindex $LENGTH
@cindex intrinsic functions, $LENGTH

@section $NAME
@cindex $NAME
@cindex intrinsic functions, $NAME

@section $NEXT
@cindex $NEXT
@cindex intrinsic functions, $NEXT

@section $ORDER
@cindex $ORDER
@cindex intrinsic functions, $ORDER

@section $PIECE
@cindex $PIECE
@cindex intrinsic functions, $PIECE

@section $QLENGTH
@cindex $QLENGTH
@cindex intrinsic functions, $QLENGTH

@section $QSUBSCRIPT
@cindex $QSUBSCRIPT
@cindex intrinsic functions, $QSUBSCRIPT

@section $QUERY
@cindex $QUERY
@cindex intrinsic functions, $QUERY

@section $RANDOM
@cindex $RANDOM
@cindex intrinsic functions, $RANDOM

@section $REVERSE
@cindex $REVERSE
@cindex intrinsic functions, $REVERSE

@section $SELECT
@cindex $SELECT
@cindex intrinsic functions, $SELECT

@section $STACK
@cindex $STACK
@cindex intrinsic functions, $STACK

John P. Willis's avatar
John P. Willis committed
831 832 833 834
Returns information about the program execution stack. The @code{$STACK} intrinsic function has both a one-argument form and a two-argument form.

@emph{Syntax (One-Argument)}

835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854
@example
 $STACK(@emph{<num>})
@end example

If @emph{num} is @code{0}, returns the command with which this FreeM instance was invoked.

If @emph{num} is @code{-1}, returns the current program execution stack level.

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:

@table @asis

@item @code{$$}
If @code{$STACK(@emph{<num>})="$$"}, program execution stack level @code{num} was created as the result of an extrinsic function call

@item @emph{<m-command>}
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.

@end table

John P. Willis's avatar
John P. Willis committed
855 856
@emph{Syntax (Two-Argument})

857
@example
858
 $STACK(@emph{<num>},"[ECODE|MCODE|PLACE]")
859 860 861
@end example

Returns the error codes, M program code, or entryref applicable to the action that created program execution stack level @emph{num}.
John P. Willis's avatar
John P. Willis committed
862

John P. Willis's avatar
John P. Willis committed
863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879
@section $TEXT
@cindex $TEXT
@cindex intrinsic functions, $TEXT

@section $TRANSLATE
@cindex $TRANSLATE
@cindex intrinsic functions, $TRANSLATE

@section $VIEW
@cindex $VIEW
@cindex intrinsic functions, $VIEW

@section $ZBOOLEAN
@cindex $ZBOOLEAN
@cindex intrinsic functions, $ZBOOLEAN
@cindex intrinsic functions, implementation-specific

880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925

Performs @emph{boolean-operation} on numeric arguments @emph{A} and @emph{B}.

@emph{Syntax}

@example
SET RESULT=$ZBOOLEAN(@emph{A},@emph{B},@emph{boolean-operation})
@end example

@code{$ZBOOLEAN} Operations (@emph{boolean-operation} values)

@table @code
@item 0
Always @emph{false}
@item 1
@code{A AND B}
@item 2
@code{A AND NOT B}
@item 3
@code{A}
@item 4
@code{NOT A AND B}
@item 5
@code{B}
@item 6
@code{A XOR B}
@item 7
@code{A OR B}
@item 8
@code{A NOR B}
@item 9
@code{A EQUALS B}
@item 10
@code{NOT B}
@item 11
@code{A OR NOT B}
@item 12
@code{NOT A}
@item 13
@code{NOT A OR B}
@item 14
@code{A NAND B}
@item 15
Always @emph{true}
@end table

John P. Willis's avatar
John P. Willis committed
926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030
@section $ZCALL
@cindex $ZCALL
@cindex intrinsic functions, $ZCALL
@cindex intrinsic functions, implementation-specific

@section $ZCR
@cindex $ZCR
@cindex intrinsic functions, $ZCR
@cindex intrinsic functions, implementation-specific

@section $ZCRC
@cindex $ZCRC
@cindex intrinsic functions, $ZCRC
@cindex intrinsic functions, implementation-specific

@section $ZDATA
@cindex $ZCRC
@cindex intrinsic functions, $ZCRC
@cindex intrinsic functions, implementation-specific

@section $ZDATE
@cindex $ZDATE
@cindex intrinsic functions, $ZDATE
@cindex intrinsic functions, implementation-specific

@section $ZEDIT
@cindex $ZEDIT
@cindex intrinsic functions, $ZEDIT
@cindex intrinsic functions, implementation-specific

@section $ZHOROLOG
@cindex $ZHOROLOG
@cindex intrinsic functions, $ZHOROLOG
@cindex intrinsic functions, implementation-specific

@section $ZHT
@cindex $ZHT
@cindex intrinsic functions, $ZHT
@cindex intrinsic functions, implementation-specific

@section $ZKEY
@cindex $ZKEY
@cindex intrinsic functions, $ZKEY
@cindex intrinsic functions, implementation-specific

@section $ZLENGTH
@cindex $ZLENGTH
@cindex intrinsic functions, $ZLENGTH
@cindex intrinsic functions, implementation-specific

@section $ZLSD
@cindex $ZLSD
@cindex intrinsic functions, $ZLSD
@cindex intrinsic functions, implementation-specific

@section $ZM
@cindex $ZM
@cindex intrinsic functions, $ZM
@cindex intrinsic functions, implementation-specific

@section $ZNAME
@cindex $ZNAME
@cindex intrinsic functions, $ZNAME
@cindex intrinsic functions, implementation-specific

@section $ZNEXT
@cindex $ZNEXT
@cindex intrinsic functions, $ZNEXT
@cindex intrinsic functions, implementation-specific

@section $ZORDER
@cindex $ZORDER
@cindex intrinsic functions, $ZORDER
@cindex intrinsic functions, implementation-specific

@section $ZPIECE
@cindex $ZPIECE
@cindex intrinsic functions, $ZPIECE
@cindex intrinsic functions, implementation-specific

@section $ZPREVIOUS
@cindex $ZPREVIOUS
@cindex intrinsic functions, $ZPREVIOUS
@cindex intrinsic functions, implementation-specific

@section $ZREPLACE
@cindex $ZREPLACE
@cindex intrinsic functions, $ZREPLACE
@cindex intrinsic functions, implementation-specific

@section $ZSYNTAX
@cindex $ZSYNTAX
@cindex intrinsic functions, $ZSYNTAX
@cindex intrinsic functions, implementation-specific

@section $ZSORT
@cindex $ZSORT
@cindex intrinsic functions, $ZSORT
@cindex intrinsic functions, implementation-specific

@section $ZTIME
@cindex $ZTIME
@cindex intrinsic functions, $ZTIME
@cindex intrinsic functions, implementation-specific

John P. Willis's avatar
John P. Willis committed
1031 1032 1033 1034
@node Commands
@chapter Commands
@cindex commands

John P. Willis's avatar
John P. Willis committed
1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047
@section !
@cindex !
@cindex commands, !
@cindex commands, external

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}.

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.

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{%}.

@code{%} contains the number of lines in the input or output. @code{%(1)..%(@emph{n})} contains the data for lines 1-@emph{n}.

1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154
@section ABLOCK
@cindex ABLOCK
@cindex commands, ABLOCK

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).

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.

@emph{Syntax}

@example
  ABLOCK@emph{:postcondition}
@end example

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.

@example
  ABLOCK@emph{:postcondition} @emph{evclass1}...,@emph{evclassN}
@end example

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.

@example
  ABLOCK@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN}
@end example

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.

@section ASTART
@cindex ASTART
@cindex commands, ASTART

Enables asynchronous event handling for one or more event classes.

@emph{Syntax}

@example
  ASTART@emph{:postcondition}
@end example

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.

@example
  ASTART@emph{:postcondition} @emph{evclass1}...,@emph{evclassN}
@end example

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.

@example
  ASTART@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN})
@end example

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.

@section ASTOP
@cindex ASTOP
@cindex commands, ASTOP

Disables asynchronous event handling for one or more event classes.

@emph{Syntax}

@example
  ASTOP@emph{:postcondition}
@end example

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.

@example
  ASTOP@emph{:postcondition} @emph{evclass1}...,@emph{evclassN}
@end example

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.

@example
  ASTOP@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN})
@end example

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.

@section AUNBLOCK
@cindex AUNBLOCK
@cindex commands, AUNBLOCK

Decrements the event block counter for one or more event classes.

@emph{Syntax}

@example
  AUNBLOCK@emph{:postcondition}
@end example

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.

@example
  AUNBLOCK@emph{:postcondition} @emph{evclass1}...,@emph{evclassN}
@end example

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.

@example
  AUNBLOCK@emph{:postcondition} (@emph{evclass1}...,@emph{evclassN}
@end example

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.


John P. Willis's avatar
John P. Willis committed
1155 1156 1157 1158
@section BREAK
@cindex BREAK
@cindex commands, BREAK

1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186
Interrupts running routine to allow interactive debugging.

@emph{Syntax}

@example
@code{BREAK@emph{:postcondition}}
@end example

In its argumentless form, @code{BREAK} suspends execution of running code, provided the optional @emph{postcondition} is @emph{true} or omitted.

@example
@code{BREAK@emph{:postcondition} @emph{breakflag}}
@end example

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.
The following table enumerates the possible values of @emph{breakflag}

@table @code
@item 0
Disables @emph{Ctrl-C} handling
@item -2
Enables normal FreeM error handling
@item 2
Enables @emph{Digital Standard MUMPS} v2 error handling
@item "default"
Enables @emph{Ctrl-C} handling
@end table

John P. Willis's avatar
John P. Willis committed
1187 1188 1189 1190
@section CLOSE
@cindex CLOSE
@cindex commands, CLOSE

1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206
Closes an input/output device.

@emph{Syntax}

@example
@code{CLOSE@emph{:postcondition}}
@end example

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.

@example
@code{CLOSE@emph{:postcondition} @emph{channel}}
@end example

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.

John P. Willis's avatar
John P. Willis committed
1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245
@section DO
@cindex DO
@cindex commands, DO

@section ELSE
@cindex ELSE
@cindex commands, ELSE

@section FOR
@cindex FOR
@cindex commands, FOR

@section GOTO
@cindex GOTO
@cindex commands, GOTO

@section HALT
@cindex HALT
@cindex commands, HALT

@section HANG
@cindex HANG
@cindex commands, HANG

@section IF
@cindex IF
@cindex commands, IF

@section JOB
@cindex JOB
@cindex commands, JOB

@section KILL
@cindex KILL
@cindex commands, KILL

@section KSUBSCRIPTS
@cindex KSUBSCRIPTS
@cindex commands, KSUBSCRIPTS
John P. Willis's avatar
John P. Willis committed
1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275

Kills only the descendant subscripts (but not the data value) of a referenced global, local, or SSV (where allowed).

@emph{Syntax}

@example
KSUBSCRIPTS@emph{:postcondition} @emph{var1},...
@end example

In the above @emph{inclusive} form, @code{KVALUE} will kill the descendant subscripts at each local, global, or SSV node specified in the list (provided that the optional @emph{postcondition} is @emph{true} or omitted), but will leave the data value intact.

@cartouche
@quotation
@emph{Note}
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.
@end quotation
@end cartouche

@example
KSUBSCRIPTS@emph{:postcondition}
@end example

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.

@example
KSUBSCRIPTS@emph{:postcondition} (@emph{var1},...)
@end example

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.

John P. Willis's avatar
John P. Willis committed
1276 1277 1278 1279

@section KVALUE
@cindex KVALUE
@cindex commands, KVALUE
John P. Willis's avatar
John P. Willis committed
1280

John P. Willis's avatar
John P. Willis committed
1281
Kills only the data value (but not descendant subscripts) of a referenced global, local, or SSV (where allowed).
John P. Willis's avatar
John P. Willis committed
1282 1283 1284 1285

@emph{Syntax}

@example
John P. Willis's avatar
John P. Willis committed
1286
KVALUE@emph{:postcondition} @emph{var1},...
John P. Willis's avatar
John P. Willis committed
1287 1288
@end example

John P. Willis's avatar
John P. Willis committed
1289
In the above @emph{inclusive} form, @code{KVALUE} will kill the data values at each local, global, or SSV node specified in the list (provided that the optional @emph{postcondition} is @emph{true} or omitted), but will leave descendant subscripts intact.
John P. Willis's avatar
John P. Willis committed
1290 1291 1292 1293

@cartouche
@quotation
@emph{Note}
1294
The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.27.1, but are planned for a future release.
John P. Willis's avatar
John P. Willis committed
1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309
@end quotation
@end cartouche

@example
KVALUE@emph{:postcondition}
@end example

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.

@example
KVALUE@emph{:postcondition} (@emph{var1},...)
@end example

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.

John P. Willis's avatar
John P. Willis committed
1310 1311 1312 1313 1314 1315 1316 1317 1318

@section LOCK
@cindex LOCK
@cindex commands, LOCK

@section MERGE
@cindex MERGE
@cindex commands, MERGE

John P. Willis's avatar
John P. Willis committed
1319
Merges the contents of one global, local, or SSV subtree to another global, local, or SSV.
1320 1321 1322 1323 1324 1325 1326

@emph{Syntax}

@example
@code{MERGE A=^$JOB}
@end example

John P. Willis's avatar
John P. Willis committed
1327
The above example will merge the @code{^$JOB} SSV 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.
1328

John P. Willis's avatar
John P. Willis committed
1329 1330 1331 1332 1333 1334 1335 1336
@section NEW
@cindex NEW
@cindex commands, NEW

@section OPEN
@cindex OPEN
@cindex commands, OPEN

1337
Opens sequential or socket I/O devices and files and associates them with a numeric FreeM input/output channel.
1338

1339
@emph{Syntax (Sequential Files)}
1340 1341 1342 1343 1344 1345 1346 1347

@example
@code{OPEN@emph{:postcondition} @emph{channel}:"@emph{filename}/@emph{access-mode}"}
@end example

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.
The below table lists the valid options for @emph{access-mode}:

1348 1349 1350 1351 1352 1353 1354 1355 1356 1357
@table @code
@item r
Read-only access
@item w
Create a new file for write access
@item a
Write access; append to existing file
@item r+
Read/write access
@end table
1358 1359 1360

@cartouche
@quotation
1361
@emph{I/O Path}
1362

1363
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
1364
access files in other directories, you must first set the @emph{I/O Path} in @code{^$JOB($JOB,"IOPATH")}.
1365

1366
The following example will set the I/O path to @code{/etc}:
1367 1368

@example
1369
@code{SET ^$JOB($JOB,"IOPATH")="/etc"}
1370 1371 1372 1373 1374 1375 1376
@end example

@end quotation
@end cartouche

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}.

1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406
@emph{Syntax (Network Sockets)}

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.

@example
  OPEN@emph{:postcondition} @emph{socket-channel}:"@emph{hostname-or-address}:@emph{port}:@emph{address-family}:@emph{connection-type}"
@end example

@emph{Socket Parameters}

@table @emph

@item socket-channel
The socket I/O channel to use. This must be in the range of 100-255.

@item hostname-or-address
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.

@item port
The TCP or UDP port to which the socket will connect on the remote host.

@item address-family
The address family to use. Either @emph{IPV4} or @emph{IPV6}.

@item connection-type
Which connection type to use. Either @emph{TCP} or @emph{UDP}.

@end table

If you do not specify the address family and connection type, they will default to @emph{IPV4} and @emph{TCP}, respectively.
1407

John P. Willis's avatar
John P. Willis committed
1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428