--- freem/doc/freem.texi 2025/01/19 02:04:04 1.1 +++ freem/doc/freem.texi 2025/04/18 22:02:33 1.29 @@ -4,10 +4,10 @@ @settitle The FreeM Manual @copying -This manual is for FreeM, (version 0.61.2), which is a free and open-source implementation of the M programming language. +This manual is for FreeM, (version 0.64.0-rc0), which is a free and open-source implementation of the M programming language. -Copyright @copyright{} 2014-2024 Coherent Logic Development LLC +Copyright @copyright{} 2014-2025 Coherent Logic Development LLC @quotation 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. @@ -18,7 +18,7 @@ Permission is granted to copy, distribut @title The FreeM Manual @subtitle @sc{The Official Manual of FreeM} -@subtitle Version 0.61.2 +@subtitle Version 0.64.0-rc0 @c@vskip 10pt @c@center @image{freem-logo-sm,,,,.png} @author Serena Willis @@ -43,7 +43,7 @@ This is the official manual for the Free @menu * Introduction:: About the FreeM Project, its history, and its goals. * FreeM Invocation:: How to invoke FreeM from the command line. -* The FreeM Daemon:: Managing shared resources in the FreeM environment. +* The FreeM Environment Daemon:: Managing shared resources in the FreeM environment. * The FreeM Direct-Mode Environment:: Executing M programs interactively. * Directives:: Per-Routine Language Directives. @@ -110,7 +110,6 @@ This is the official manual for the Free @node Introduction @unnumbered Introduction - 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. 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. @@ -236,25 +235,29 @@ Steve Zeck (Code) $ @command{./freem} [@emph{OPTIONS}...] [[-r ] | [--routine=]] @end example -When FreeM loads, it searches the @code{SYSTEM} namespace for the @code{^%SYSINIT} routine, and begins executing it. +When FreeM loads, it searches the @code{SYSTEM} namespace for the @code{%SYSINIT} routine, and begins executing it. + +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. + +@section %SYSINIT Routine + +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}. -When @code{-r} or @code{--routine} are passed on the command line, FreeM will load and run the specified routine instead of @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. +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. @section Command-Line Options +@cindex options, command-line @table @asis @item @option{-d}, @option{--daemon} -Starts the FreeM daemon, exactly one of which must be running at all times in order for FreeM interpreter and fmadm processes to function. +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. @item @option{-e}, @option{--environment} Selects the environment to be used. If no environment is specified, @code{DEFAULT} is used. @item @option{-k}, @option{--nofork} -When used with @option{-d} or @option{--daemon}, causes the FreeM daemon to run instead in the foreground. Useful for debugging. - -@item @option{-p}, @option{--pidfile} -When used with @option{-d} or @option{--daemon}, sets the file in which the PID of the running daemon is stored. +When used with @option{-d} or @option{--daemon}, causes the FreeM environment daemon to run instead in the foreground. Useful for debugging. @item @option{-S}, @option{--shmsize} 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. @@ -272,10 +275,10 @@ Causes your UNIX environment variables t Allows your M routines to be used as UNIX filters. @item @option{-n @emph{}}, @option{--namespace=@emph{}} -Selects the FreeM namespace to be entered on startup. Must be defined in @file{/etc/freem.conf}. +Selects the FreeM namespace to be entered on startup. Must be defined in @file{/etc//freem.conf}. @item @option{-r @emph{}}, @option{--routine=@emph{}} -Causes @code{} to be executed at load, instead of @code{^%SYSINIT}. +Causes @code{} to be executed at load, instead of @code{%SYSINIT}. @item @option{--standard=@emph{}} Sets the default FreeM dialect to use for new routine buffers. @@ -305,7 +308,7 @@ Please note that FreeM is not entirely s Displays FreeM version information. @item @option{-x @emph{}}, @option{--execute=@emph{}} -Executes M code @code{} at startup instead of the startup routine. +Executes M code @code{} at startup. @end table @@ -333,27 +336,26 @@ You will also need to set the script's p $ chmod +x @emph{myscript.m} @end example -@node The FreeM Daemon -@chapter The FreeM Daemon +@node The FreeM Environment Daemon +@chapter The FreeM Environment Daemon @cindex daemon, freem -The FreeM 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 daemon does @emph{not} function as a write daemon for global storage. +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. + +One daemon process is required per FreeM environment, and can be started in the following ways, in order of preference: -One daemon process is required per FreeM environment, and can be started as follows: +@example +$ sudo fmadm start environment [-e=] +@end example @example -$ freem --daemon [--nofork] [--environment=] [--user=] \ - [--group=] [--pidfile=] [--shmsize=] +$ freem --daemon [--nofork] [--environment=] [--shmsize=] @end example 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. 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. -The @option{--user} and @option{--group} options are only valid when the FreeM daemon is started by the superuser, and will cause the daemon to reduce its runtime privileges to those of the specified user and group, and run as that user and/or group. We recommend creating a @code{freem} user and group and running the FreeM daemon with @code{--user=freem --group=freem}. - -The @option{--pidfile} option specifies the file in which the FreeM daemon will store its own PID. If running as the superuser, the FreeM daemon will store the PID file in @code{/var/run/freem.pid}. Otherwise, the PID file will be stored as @code{.freem.pid} in the home directory of the user account which owns the FreeM daemon process. - 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. Attempting to start a FreeM interpreter process without a daemon running with the same environment name will result in an error. @@ -369,17 +371,17 @@ Attempting to start a FreeM interpreter The FreeM direct-mode environment is the mode entered when FreeM is invoked without the use of @option{-r @emph{}} or @option{--routine=@emph{}}: @example -Coherent Logic Development FreeM version 0.61.2 (x86_64-pc-linux-gnu) +Coherent Logic Development FreeM version 0.64.0-rc0 (x86_64-pc-linux-gnu) Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC USER> @end example -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{@ref{$TLEVEL}}: +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}}: @example -TL1:USER> +TL1:DEFAULT.USER> @end example In the above example, @code{TL1} indicates that @code{@ref{$TLEVEL}} is currently @emph{1}. @@ -397,7 +399,7 @@ Accesses FreeM online help. Requires GNU Writes a list of @emph{event classes} and their @code{ABLOCK} counts: @example -USER> events +DEFAULT.USER> events Event Class Processing Mode ABLOCK Count ----------- --------------- ------------ @@ -417,6 +419,10 @@ TRIGGER Disabled 0 @item @command{trantab} Displays information about any uncommitted transactions currently in-flight for this process. +@anchor{glstat} +@item @command{trantab} +Displays statistics about globals that have been opened in the current FreeM process. + @anchor{jobtab} @item @command{jobtab} Displays a summary of the FreeM job table. @@ -429,10 +435,6 @@ Displays a list of @code{LOCK}s held in @item @command{rbuf} Lists the status of all FreeM routine buffers. -@anchor{dbstats} -@item @command{dbstats} -Shows statistics for the BerkeleyDB global handler. - @anchor{wh} @item @command{wh} Forces an immediate flush of this process's @code{readline} history buffer to disk. @@ -457,18 +459,18 @@ Allows you to recall command number @emp Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands. @example -USER> !! +DEFAULT.USER> !! Type Ctrl-D to exit from the shell $ uname -a Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux $ exit -USER> +DEFAULT.USER> @end example @item @command{!@emph{}} -Invokes a shell to run @emph{} 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}. +Invokes a shell to run @emph{} from within FreeM. This temporarily disables @command{SIGALRM} handling in FreeM, which may interrupt the use of event-driven M programming commands including @command{ASTART} and @command{ASTOP}. If the @command{>} character is supplied immediately preceding @emph{}, 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{}. @@ -482,13 +484,13 @@ The data value in the unsubscripted M lo 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: @example -USER> TSTART +DEFAULT.USER> TSTART -TL1:USER> SET ^MYGLOBAL=1 +TL1:DEFAULT.USER> SET ^MYGLOBAL=1 -TL1:USER> HALT +TL1:DEFAULT.USER> HALT UNCOMMITTED TRANSACTIONS EXIST: @@ -510,13 +512,13 @@ In the above example, the user selected FreeM direct mode allows you to enter M expressions directly from the direct-mode prompt, as long as they begin with a number: @example -USER> S DENOM=10 +DEFAULT.USER> S DENOM=10 -USER> 100/DENOM +DEFAULT.USER> 100/DENOM 10 -USER> +DEFAULT.USER> @end example Such expressions will be immediately evaluated, and the result printed on @code{@ref{$IO}}. @@ -657,6 +659,8 @@ Please note that FreeM is not entirely s Returns a comma-delimited list of error conditions currently present, and is writable. An empty @code{$ECODE} indicates no errors. +Writing a value in the format @code{,,} into @code{$ECODE} will raise that error condition. + @node $ESTACK @section $ESTACK @cindex $ESTACK @@ -1081,13 +1085,13 @@ SET M=$EXTRACT(NAME,1,5) It is also possible to use @code{$EXTRACT} on the left-hand side of a @code{SET} assignment in order to modify a substring: @example -USER> SET FOO="ABCDEFG" +DEFAULT.USER> SET FOO="ABCDEFG" -USER> SET $EXTRACT(FOO,1,3)="XYZ" +DEFAULT.USER> SET $EXTRACT(FOO,1,3)="XYZ" -USER> WRITE FOO +DEFAULT.USER> WRITE FOO XYZDEFG @end example @@ -1114,7 +1118,22 @@ Formats a number according to a particul The first argument is the number to format. -The second argument is the series of formatting codes. +The second argument is the series of formatting codes: + +@table @asis +@item 'P' or 'p' +Will display negative numbers within parentheses instead of showing a minus sign. +@item , (comma) +Will add commas as thousands separators. +@item + +Will include a plus sign for positive numbers. Not compatible with 'P' or 'p'. +@item - +Will remove the minus sign from negative numbers. Not compatible with 'p' or 'P'. +@item 't' or 'T' +Will place the sign after the number instead of before the number. +@end table + +The optional third argument is a number indicating how many digits to which the fractional part of the number will be zero-padded. @node $GET() @section $GET @@ -1139,12 +1158,10 @@ The first argument is a string represent The second argument is a string representing a valid FreeM class. -@xref{Object-Oriented Programming} - @example -USER> N STR=$$^%STRING +DEFAULT.USER> N STR=$$^%STRING -USER> W $INSTANCEOF("STR","^%STRING") +DEFAULT.USER> W $INSTANCEOF("STR","^%STRING") 1 @end example @@ -1188,11 +1205,19 @@ The optional second argument indicates t @cindex $NEXT @cindex intrinsic functions, $NEXT +Deprecated. Use @code{$ORDER} instead. + @node $ORDER() @section $ORDER @cindex $ORDER @cindex intrinsic functions, $ORDER +Returns the previous subscript or next subscript in a local, global, or a subset of structured system variables. + +The first argument is the subscripted local, global, or SSVN. + +The optional second argument can be @code{1} to retrieve the next subscript, or @code{-1} to return the previous. + @node $PIECE() @section $PIECE @cindex $PIECE @@ -1215,8 +1240,8 @@ The optional fourth argument is the fina 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: @example -; ^jpw="this^is^a^piece" -SET $PIECE(^jpw,"^",2)="isn't" ; => "this^isn't^a^piece" +; ^snw="this^is^a^piece" +SET $PIECE(^snw,"^",2)="isn't" ; => "this^isn't^a^piece" @end example @node $QLENGTH() @@ -1248,7 +1273,7 @@ Returns the number of subscripts in @emp @code{$QSUBSCRIPT(@emph{expr V glvn},@emph{expr V n})} @end example -Returns the @emph{n}th subscript of @emph{glvn}. +In the RHS form, returns the @emph{n}th subscript of @emph{glvn}. @emph{Example} @@ -1256,6 +1281,14 @@ Returns the @emph{n}th subscript of @emp @code{SET SUB=$QSUBSCRIPT("^GBL(1,2,3)",2) ; => 2} @end example +@emph{Syntax} + +@example +@code{SET $QSUBSCRIPT(@emph{expr V glvn},@emph{expr V n})=@emph{expr} ; => ^GBL(1,4,3)} +@end example + +In the LHS form, sets the @emph{n}th subscript of @emph{glvn} to @emph{expr}. + @node $QUERY() @section $QUERY @cindex $QUERY @@ -1273,16 +1306,16 @@ Returns the next subscripted reference i We will assume the following data structure exists: @example -^jpw(1)=1 -^jpw(1,2)="foo" -^jpw(2)=3 -^jpw(3)="" +^snw(1)=1 +^snw(1,2)="foo" +^snw(2)=3 +^snw(3)="" @end example -The following code will retrieve the next subscripted name after @code{^jpw(1)}: +The following code will retrieve the next subscripted name after @code{^snw(1)}: @example -@code{SET NEXTNAM=$QUERY(^jpw(1)) ; => ^jpw(1,2)} +@code{SET NEXTNAM=$QUERY(^snw(1)) ; => ^snw(1,2)} @end example @node $RANDOM() @@ -1379,6 +1412,21 @@ Returns a line of code from a routine. @cindex $TRANSLATE @cindex intrinsic functions, $TRANSLATE +Replaces characters in a string. + +The first argument is a string expression representing the text to be changed. + +The second argument is a list of characters to replace. + +The third argument is a list of characters to use as the replacements for the characters in the second argument. + +@emph{Example} + +@example + DEFAULT.USER> W $TRANSLATE("twig","wt","rb") + brig +@end example + @node $TYPE() @section $TYPE @cindex $TYPE @@ -1452,6 +1500,8 @@ Always @emph{true} @cindex intrinsic functions, $ZCALL @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZCRC() @section $ZCRC @cindex $ZCRC @@ -1472,6 +1522,8 @@ Returns a checksum of @code{arg1}. @cindex intrinsic functions, $ZDATA @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZDATE() @section $ZDATE @cindex $ZDATE @@ -1496,6 +1548,8 @@ The optional @emph{} foll @cindex intrinsic functions, $ZEDIT @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZHOROLOG() @section $ZHOROLOG @cindex $ZHOROLOG @@ -1520,12 +1574,16 @@ $ZHOROLOG(@emph{},@emph{.EXTRACT(,) @node $$FIND @section $$FIND +Finds the character immediately following the first occurence of a substring within a string. + +The first argument is the substring to be located. + +The second argument is the position within the string at which to begin searching. + +See @ref{$FIND()}. + @node $$FNUMBER @section $$FNUMBER +Formats a number according to a set of formatting codes. + +The argument is a series of formatting codes. See @ref{$FNUMBER()} for details. + @node $$JUSTIFY @section $$JUSTIFY +Right-justifies a string based on a specified fixed length. + +The first argument is the character length of the output. + +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. + +See @ref{$JUSTIFY()} for details. + @node $$LENGTH @section $$LENGTH +Returns the length of the string. + @node $$PIECECOUNT @section $$PIECECOUNT +Returns the number of items in a list delimited by the character specified in the argument. + @node $$PIECE @section $$PIECE +@emph{Syntax} + +@code{$PIECE(@emph{d}[,@emph{n}[,@emph{end}]])} + +Accesses the @code{n}th through @code{end} @code{d}-delimited pieces of the string. + +The first argument is the delimiter to be used. + +The optional second argument is the first @code{d}-delimited piece to access, and defaults to @code{1}. + +The optional third argument is the final @code{d}-delimited piece to access, and defaults to the value of the third argument (@code{n}). + + @node $$REPLACE @section $$REPLACE +@emph{Syntax} +@code{myString.$$REPLACE(@emph{arg1},@emph{arg2})} + +Replaces all instances of @code{arg2} with @code{arg3} in @code{myString}. + @node $$REVERSE @section $$REVERSE +Returns the reverse of the string. + @node $$TOLOWER @section $$TOLOWER +Returns an all-lowercase version of the string. + @node $$TOUPPER @section $$TOUPPER +Returns an all-uppercase version of the string. + @node $$TRANSLATE @section $$TRANSLATE +Identical to @ref{$TRANSLATE()}, except that the arguments are shifted left by one, and the input string is implicit (the object). + @node Commands @chapter Commands @cindex commands @@ -1826,9 +1944,7 @@ $$.EXTRACT(,) * WITH:: Set prefix for future variable references. * WRITE:: Write output to current input/output device. * XECUTE:: Interpret string as M code. -* ZALLOCATE:: Alternative to @code{LOCK}. * ZBREAK:: Unknown. -* ZDEALLOCATE:: Alternative to @code{LOCK}. * ZGO:: Unknown. * ZHALT:: Unknown. * ZINSERT:: Insert code into routine buffer. @@ -1861,36 +1977,36 @@ Executes FreeM code @emph{expr V mcode}. @emph{Example (Using Variable)} @example -USER> SET FOO="WRITE ""HELLO WORLD"",!" -USER> @@FOO +DEFAULT.USER> SET FOO="WRITE ""HELLO WORLD"",!" +DEFAULT.USER> @@FOO HELLO WORLD -USER> +DEFAULT.USER> @end example @emph{Example (Using String Literal)} @example -USER> @@"WRITE ""HELLO WORLD"",!" +DEFAULT.USER> @@"WRITE ""HELLO WORLD"",!" HELLO WORLD -USER> +DEFAULT.USER> @end example @emph{Example (Using Indirection)} @example -USER> SET FOO="BAR" +DEFAULT.USER> SET FOO="BAR" -USER> SET BAR="WRITE ""HELLO WORLD"",!" +DEFAULT.USER> SET BAR="WRITE ""HELLO WORLD"",!" -USER> @@@@FOO +DEFAULT.USER> @@@@FOO HELLO WORLD -USER> +DEFAULT.USER> @end example @@ -1921,14 +2037,14 @@ If the @command{>} character is supplied Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands. @example -USER> !! +DEFAULT.USER> !! Type Ctrl-D to exit from the shell $ uname -a Linux hesperos 4.19.0-17-amd64 #1 SMP Debian 4.19.194-3 (2021-07-18) x86_64 GNU/Linux $ exit -USER> +DEFAULT.USER> @end example @@ -1983,13 +2099,13 @@ The @code{ASSERT} error is catchable whe @emph{Example} @example -USER> SET DEBUG=1 +DEFAULT.USER> SET DEBUG=1 -USER> ASSERT:DEBUG 1=1 +DEFAULT.USER> ASSERT:DEBUG 1=1 -USER> ASSERT:DEBUG 1=0 +DEFAULT.USER> ASSERT:DEBUG 1=0 >> Error ZASSERT: programmer assertion failed in SYSTEM::^%SYSINIT [$STACK = 0] @@ -2232,7 +2348,7 @@ FOR[@emph{:postcondition}] @emph{glvn}=@ @emph{Example} @example -USER> FOR I=1:1:10 WRITE I,! +DEFAULT.USER> FOR I=1:1:10 WRITE I,! 1 2 @@ -2245,7 +2361,7 @@ USER> FOR I=1:1:10 WRITE I,! 9 10 -USER> FOR I=2:2:10 WRITE I,! +DEFAULT.USER> FOR I=2:2:10 WRITE I,! 2 4 @@ -2265,7 +2381,7 @@ FOR[@emph{:postcondition}] @emph{glvn}=@ @emph{Example} @example -USER> FOR I=60,"FOO",-3,"George",1450,$HOROLOG WRITE I,! +DEFAULT.USER> FOR I=60,"FOO",-3,"George",1450,$HOROLOG WRITE I,! 60 FOO @@ -2399,7 +2515,7 @@ In the above @emph{inclusive} form, @cod @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. +The below @emph{argumentless} and @emph{exclusive} forms of @code{KSUBSCRIPTS} are not implemented in FreeM, as of version 0.64.0-rc0, but are planned for a future release. @end quotation @end cartouche @@ -2434,7 +2550,7 @@ In the above @emph{inclusive} form, @cod @cartouche @quotation @emph{Note} -The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.61.2, but are planned for a future release. +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. @end quotation @end cartouche @@ -2475,10 +2591,10 @@ LOCK[@emph{:postcondition}] [+|-]@emph{n @emph{Example} -This example will increment the lock counter for @code{^JPW} and decrement the lock counter for @code{^MJR}. +This example will increment the lock counter for @code{^SNW} and decrement the lock counter for @code{^MJR}. @example -LOCK +^JPW,-^MJR +LOCK +^SNW,-^MJR @end example 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. @@ -2551,6 +2667,13 @@ NEW@emph{:postcondition} @emph{name}=@em 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. +@emph{Syntax} +@example +NEW@emph{:postcondition} @emph{name}=$%@emph{^CLASS}(@emph{initializer-list}) +@end example + +In its object-oriented form, @code{NEW} creates an instance of class @emph{^CLASS} in local variable @emph{name} and calls the constructor of @emph{^CLASS}, passing @emph{initializer-list} as its argument(s). + @node OPEN @section OPEN @cindex OPEN @@ -2914,14 +3037,6 @@ Closes all global data files open in the VIEW 21 @end example -@item @code{29} - Symbol Table Copy -Copies the primary symbol table's contents to the alternate symbol table. Takes no arguments. - -@emph{Syntax} -@example -VIEW 29 -@end example - @item @code{52} - Set G0 Input Translation Table for @code{$IO} @emph{Syntax} @@ -3070,30 +3185,6 @@ If @emph{tvexpr} evaluates to @emph{true VIEW 83:@emph{tvexpr} @end example -@item @code{87} - Date Type Definition -We believe this defines date formats for @code{$ZDATE}, but we have not yet figured out how it works. - -@emph{Syntax} -@example -; Syntax unknown -@end example - -@item @code{88} - Time Type Definition -We believe this defines time formats for @code{$ZTIME}, but we have not yet figured out how it works. - -@emph{Syntax} -@example -; Syntax unknown -@end example - -@item @code{91} - Set Default Expression for Missing @code{QUIT} Expression -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. - -@emph{Syntax} -@example -; Syntax unknown -@end example - @item @code{92} - Set Type Mismatch Error Flag on @code{EUR2DEM} 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. @@ -3215,33 +3306,33 @@ WATCH[@emph{:postcondition}] [+|-|?]@emp @end example -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)}. +The following example demonstrates turning watchpoint processing on and adding a watchpoint for global variable @code{^snw(1)}. It then changes the value of @code{^snw(1)}. @example -USER> WATCH +DEFAULT.USER> WATCH Watchpoints enabled. -USER> WATCH +^JPW(1) +DEFAULT.USER> WATCH +^SNW(1) -Added '^JPW("1")' to the watchlist. +Added '^SNW("1")' to the watchlist. -USER> SET ^JPW(1)="new value" +DEFAULT.USER> SET ^SNW(1)="new value" ->> WATCHPOINT: ^JPW("1") => 'new value' (changed 1 times) +>> WATCHPOINT: ^SNW("1") => 'new value' (changed 1 times) @end example The following example will remove that watchpoint: @example -USER> WATCH -^JPW(1) +DEFAULT.USER> WATCH -^SNW(1) -Removed '^JPW("1")' from the watchlist. +Removed '^SNW("1")' from the watchlist. -USER> WATCH ?^JPW(1) +DEFAULT.USER> WATCH ?^SNW(1) -'^JPW("1")' is not being watched. +'^SNW("1")' is not being watched. @end example @node WITH @@ -3251,6 +3342,8 @@ USER> WATCH ?^JPW(1) @cindex commands, non-standard @emph{FreeM Extension} +NOTE: This command may be deprecated and removed in future FreeM releases. + Sets a prefix to be applied to all subsequent local variable or constant references. @emph{Syntax} @@ -3280,14 +3373,6 @@ In the above argumentless form, clears t @cindex XECUTE @cindex commands, XECUTE -@node ZALLOCATE -@section ZALLOCATE -@cindex ZALLOCATE -@cindex commands, ZALLOCATE -@cindex commands, implementation-specific -@cindex commands, non-standard -@emph{FreeM Extension} - @node ZBREAK @section ZBREAK @cindex ZBREAK @@ -3297,14 +3382,6 @@ In the above argumentless form, clears t @cindex commands, non-standard @emph{FreeM Extension} -@node ZDEALLOCATE -@section ZDEALLOCATE -@cindex ZDEALLOCATE -@cindex commands, ZDEALLOCATE -@cindex commands, implementation-specific -@cindex commands, non-standard -@emph{FreeM Extension} - @node ZGO @section ZGO @cindex ZGO @@ -3793,9 +3870,9 @@ Returns or sets the maximum number of ch Returns or sets the maximum number of characters of a single global subscript, from 1-255. @item @code{SINGLE_USER} +R +U -D -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. +If set to @code{1}, FreeM will skip all file locking operations on globals. If set to @code{0}, FreeM will enforce file locking on both. -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! +Setting @code{SINGLE_USER} to @code{1} will improve FreeM performance, but you must @emph{ONLY} use this on systems where you are absolutely sure that only one FreeM process will run at any given time, as running multiple instances of FreeM concurrently when any of them are set to @code{SINGLE_USER} mode @emph{will} cause global data corruption. @item @code{CHARACTER} +R -U -D Returns the character set of the job. @@ -3806,25 +3883,6 @@ Returns or sets the current working dire @item @code{OPEN} +R -U -D The @code{^$JOB($JOB,"OPEN",} subscripts list the open I/O channels in the specified job. -@item @code{ENGINES} +R -U -D -Returns or sets the storage engines for various FreeM subsystems. - -The following table lists the types of storage engines that can be defined. - -@table @asis - -@item @code{GLOBAL} +R +U -D -Returns or sets the global handler for a particular FreeM namespace: - -The following code would set the global handler for the @code{SYSTEM} namespace to @code{BERKELEYDB}: - -@code{SET ^$JOB($JOB,"ENGINES","GLOBAL","SYSTEM")="BERKELEYDB"} - -@item @code{LOCAL} +R -U -D -Returns the local handler for a particular FreeM namespace. Always @code{BUILTIN} in the current FreeM release. - -@end table - @item @code{BERKELEYDB,FLUSH_THRESHOLD} +R +U -D 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. @@ -4114,38 +4172,76 @@ Forces a number to positive, whether pos @section Unary - @cindex operators, unary - +Forces a number to negative, whether positive or negative. Also forces numeric coercion of strings. + @node + @section + (Add) @cindex operators, + +@emph{Syntax} + +@example +S X=1+2 ; => 3 +@end example + +Adds numbers together. + @node += @section += (Add/Assign) @cindex operators, += +@emph{Syntax} + +@example +S X=5 +S X+=3 ; => 8 +@end example + +Increments the variable on the LHS by the value on the RHS. + @node ++ @section ++ (Postfix Increment) @cindex operators, ++ +Increments a variable by 1. + @node - @section - (Subtract) @cindex operators, - +Subtracts one number from another. + @node -= @section -= (Subtract/Assign) @cindex operators, -= +@emph{Syntax} + +@example +S X=5 +S X-=3 ; => 2 +@end example + +Decrements the variable on the LHS by the value on the RHS. + @node -- @section -- (Postfix Decrement) @cindex operators, -- +Decrements the variable by one. + @node * @section * (Multiply) @cindex operators, * +Multiplies one number by another. + @node *= @section *= (Multiply/Assign) @cindex operators, *= + + @node / @section / (Divide) @cindex operators, / @@ -4309,11 +4405,15 @@ An @code{INTEGER} is an interpretation o @cindex data types, REAL @cindex types, REAL +A @code{REAL} is a numeric interpretation of data including a fractional part. + @node STRING @section STRING @cindex data types, STRING @cindex types, STRING +A @code{STRING} is any data in FreeM. + @node Custom Types (Classes) @section Custom Types (Classes) @cindex data types, custom @@ -4369,6 +4469,11 @@ See @ref{Classes}. @cindex functions, extrinsic @cindex subroutines +@menu +* Subroutines:: Making sections of code reusable. +* Extrinsic Functions:: Reusable code that returns a value. +@end menu + @node Subroutines @section Subroutines @@ -4380,21 +4485,127 @@ See @ref{Classes}. @cindex object-oriented programming @cindex programming, object-oriented +@menu +* Classes:: The basis of object-oriented programming. +* Inheritance:: Basing one class upon another. +* Methods:: Attaching code to a class. +* Public and Private Variables:: Managing class member access. +@end menu + @node Classes @section Classes +A @emph{class} is the primary organizing concept of FreeM support for object-oriented programming, and in FreeM, is simply an M routine with a few special properties: + +@example +MYCLASS(THIS,INIT):OBJECT ; Constructor for MYCLASS, inherits OBJECT + ; two private variables + S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) + S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) + Q + ; +DESTROY(THIS) ; This is the destructor + Q +@end example + +The above example demonstrates general class syntax. + +@node Constructors +@subsection Constructors + +A @emph{constructor} is an M entry point that is called when a new instance of a class is created. + +A constructor must be the first entry point in a class routine, its tag must match the class/routine name, and it must take two arguments, @code{THIS} and @code{INIT}. + +@code{THIS} represents the instance of the object being accessed, and @code{INIT} represents an initializer that can be used to assign an initial value to the object when instantiating the class. + +A constructor looks like this: + +@example +%FRACTION(THIS,INIT):OBJECT ; + S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) + S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) + Q +@end example + +@emph{Syntax} +@example +@emph{}(THIS,INIT)[:@emph{}] +@end example + +In the above example, @emph{} represents the name of a class from which this class should inherit. In this case, the @code{FRACTION} class inherits from the @code{OBJECT} class. Note that this is not strictly necessary in this case, as all classes in FreeM automatically inherit from @code{OBJECT}. + +@node Destructors +@subsection Destructors +A @code{destructor} is called when you @code{KILL} an instance variable. Its tag must be @code{DESTROY}, and it must take one argument (@code{THIS}). + +The destructor should be used to clean up any resources used by class methods. + +A destructor looks like this: + +@example +DESTROY(THIS) ; + ; free any resources that should be freed at the end of the object's lifetime + Q +@end example + @node Inheritance -@subsection Inheritance +@section Inheritance + +Every class you create will automatically inherit the methods and functionality of the @code{OBJECT} class, supplied with FreeM. + +When attempting to call a method, FreeM will first search the class routine for a matching entry point, and then follow the inheritance chain upwards until a matching entry point is found. If the final class in the chain does not have a matching entry point, FreeM will try to find a matching entry point in the @code{OBJECT} class. + +Inheritance is achieved by specifying the name of the superclass in the constructor: + +@example +CLASS(THIS,INIT):SUPERCLASS +@end example + +@node Runtime Polymorphism +@subsection Runtime Polymorphism + +You can achieve runtime polymorphism by subclassing, and defining methods in the subclass that match the names of existing methods in the superclass. Following FreeM inheritance rules, the overridden method in the subclass will be called, and the method in the superclass will not. + +Note that the overridden method in the subclass can take a different set or number of arguments than the @emph{formallist} of the superclass method would specify. @node Methods -@subsection Methods +@section Methods +Class methods are defined as tags with @emph{formallist}s in a class routine, and per the typical FreeM object pattern, must take at least one argument, being @code{THIS} (representing a reference to the object instance being accessed). -@node Public Variables -@subsection Public Variables +The following class (@code{MYCLASS}) has a constructor, a destructor, and a method called @code{MYMETHOD}: -@node Private Variables -@subsection Private Variables +@example +%MYCLASS(THIS,INIT) ; + Q THIS +DESTROY(THIS) ; + Q +MYMETHOD(THIS) ; + Q "VALUE" +@end example + +@node Public and Private Variables +@section Public and Private Variables + +FreeM supports private fields with the @code{:PRIVATE} specifier in the @code{SET} command, enforcing classical object-oriented data encapsulation. The code{:PUBLIC} specifier is provided for completeness, and is the default. + +The below constructor for a @code{FRACTION} class defines two private fields: + +@example +%FRACTION(THIS,INIT):OBJECT ; + S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) + S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) + Q +@end example +Either of the following commands will create a public field: + +@example + S THIS("VARNAM")="Initial Value" + S THIS("VARNAM"):PUBLIC="Initial Value" +@end example + +Attempting to access private fields from outside of the class will raise error condition @code{ZOBJFLDACCV}. @node Libraries @chapter Libraries @@ -4462,18 +4673,6 @@ You may also use an expression that reso WRITE ^|NS|VA(200,0),! @end example -@section File Path Extended Global References -@cindex extended global references, file path - -If a namespace is configured to use the @code{BUILTIN} global handler, FreeM supports accessing a global data file by way of its filesystem path. - -The following file path extended global reference will write the value of @code{^VA(200,0)}, assuming the @code{^VA} data file exists at path @code{/home/jpw/^VA}: - -@example - WRITE ^/home/jpw/VA(200,0),! -@end example - - @node Global Aliasing @chapter Global Aliasing @cindex aliasing, global @@ -4543,7 +4742,7 @@ Used for globals that @emph{did} exist p The below example shows a few global operations and checkpoints for a transaction in-flight using the @code{trantab} direct-mode command: @verbatim -TL1:USER> trantab +TL1:DEFAULT.USER> trantab $TLEVEL 1* Operations for Transaction ID: 6ea14aad-b8f1-47f9-9f52-4f513f892bc0 [RESTARTABLE SERIAL] @@ -4551,7 +4750,7 @@ TL1:USER> trantab ------- ------ -------- 1 SET ^FOO=3 2 KILL ^FOO - 3 SET ^jpw=10 + 3 SET ^snw=10 4 SET ^BRANDNEW=6 Global checkpoints: @@ -4559,8 +4758,8 @@ TL1:USER> trantab GLOBAL MODE FILES ------ ---- ----- ^BRANDNEW CP_REMOVE IN: /usr/local/var/freem/USER/globals/^BRANDNEW - ^jpw CP_RESTORE IN: /usr/local/var/freem/USER/globals/^jpw - OUT: /usr/local/var/freem/USER/globals/^jpw.23390.1.chk + ^snw CP_RESTORE IN: /usr/local/var/freem/USER/globals/^snw + OUT: /usr/local/var/freem/USER/globals/^snw.23390.1.chk ^FOO CP_RESTORE IN: /usr/local/var/freem/USER/globals/^FOO OUT: /usr/local/var/freem/USER/globals/^FOO.23390.1.chk @end verbatim @@ -4779,9 +4978,9 @@ You can also set up a trigger that appli This routine is the implementation of the @code{$ZCOLUMNS} intrinsic special variable. -@section ^%SYSINIT -@cindex ^%SYSINIT -@cindex system library routines, ^%SYSINIT +@section %SYSINIT +@cindex %SYSINIT +@cindex system library routines, %SYSINIT This routine is the default startup routine for FreeM running in direct mode. @@ -4803,7 +5002,7 @@ This routine is the implementation of th @chapter Interrupt Handling @cindex interrupt handling -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 daemon, or another external process, one of two things can happen, depending on the state of the @code{$ZI} special variable: +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: @table @asis @item @code{$ZI} evaluates @emph{true} @@ -5056,10 +5255,10 @@ Custom error messages for @code{ZUSERERR For example: @example -USER> S ^$JOB($JOB,"USER_ERRORS","UBLACKHOLE")="black hole encountered" +DEFAULT.USER> S ^$JOB($JOB,"USER_ERRORS","UBLACKHOLE")="black hole encountered" -USER> THROW UBLACKHOLE +DEFAULT.USER> THROW UBLACKHOLE >> Error UBLACKHOLE: black hole encountered in SYSTEM::^%SYSINIT [$STACK = 0] @@ -5783,11 +5982,6 @@ The FreeM @code{LOCK} table. Supported actions are @code{list} and @code{remove}. -@item zallocate -The FreeM @code{ZALLOCATE} table. - -No actions yet implemented. - @item journal FreeM after-image journaling. @@ -6000,37 +6194,40 @@ WRITE $VIEW(31),! @section Module Headers @cindex coding standards, module headers -Module headers should adhere to the following format: +Module headers should adhere to the following format (where @code{Dollar} should be replaced with a dollar sign): @verbatim /* - * * - * * * - * * * - * *************** - * * * * * - * * MUMPS * - * * * * * - * *************** - * * * - * * * - * * - * - * mlib.h + * DollarIdDollar * Function prototypes, structs, and macros for FreeM * binding library * * - * Author: Serena Willis + * Author: Serena Willis * Copyright (C) 1998 MUG Deutschland - * Copyright (C) 2020 Coherent Logic Development LLC + * Copyright (C) Coherent Logic Development LLC + * + * This file is part of FreeM. + * + * FreeM is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * FreeM 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 Public License for more details. + * + * You should have received a copy of the GNU Affero Public License + * along with FreeM. If not, see . + * + * DollarLogDollar * - * Last modified: 29 February 2020 - * + * SPDX-FileCopyrightText: (C) 2025 Coherent Logic Development LLC + * SPDX-License-Identifier: AGPL-3.0-or-later **/ @end verbatim -@cindex ha-Ashkenaz, Shalom -The Star of David in module headers is a convention started by Shalom ha-Ashkenaz, the unidentified original author of FreeMUMPS/FreeM. We will continue to employ it in honor of his most valuable contribution to the M community. @section Variable Naming @cindex coding standards, variable naming