--- freem/doc/freem.texi 2025/04/10 17:21:54 1.24 +++ freem/doc/freem.texi 2025/04/18 19:43:18 1.28 @@ -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,15 +235,15 @@ 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. +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}. +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}. -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. +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 @@ -279,7 +278,7 @@ Allows your M routines to be used as UNI 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. @@ -379,7 +378,7 @@ Copyright (C) 2014, 2020, 2021 Coherent USER> @end example -The prompt (@code{DEFAULT.USER>}) 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}}: +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:DEFAULT.USER> @@ -436,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. @@ -475,7 +470,7 @@ 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{}. @@ -664,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 @@ -1208,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 @@ -1235,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() @@ -1268,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} @@ -1276,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 @@ -1293,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() @@ -1399,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 @@ -1472,6 +1500,8 @@ Always @emph{true} @cindex intrinsic functions, $ZCALL @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZCRC() @section $ZCRC @cindex $ZCRC @@ -1492,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 @@ -1516,6 +1548,8 @@ The optional @emph{} foll @cindex intrinsic functions, $ZEDIT @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZHOROLOG() @section $ZHOROLOG @cindex $ZHOROLOG @@ -1540,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 @@ -1846,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. @@ -2419,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 @@ -2495,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. @@ -2571,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 @@ -2934,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} @@ -3090,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. @@ -3235,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 DEFAULT.USER> WATCH Watchpoints enabled. -DEFAULT.USER> WATCH +^JPW(1) +DEFAULT.USER> WATCH +^SNW(1) -Added '^JPW("1")' to the watchlist. +Added '^SNW("1")' to the watchlist. -DEFAULT.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 -DEFAULT.USER> WATCH -^JPW(1) +DEFAULT.USER> WATCH -^SNW(1) -Removed '^JPW("1")' from the watchlist. +Removed '^SNW("1")' from the watchlist. -DEFAULT.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 @@ -3271,6 +3342,8 @@ DEFAULT.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} @@ -3300,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 @@ -3317,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 @@ -3813,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. @@ -4115,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, / @@ -4555,7 +4650,7 @@ TL1:DEFAULT.USER> trantab ------- ------ -------- 1 SET ^FOO=3 2 KILL ^FOO - 3 SET ^jpw=10 + 3 SET ^snw=10 4 SET ^BRANDNEW=6 Global checkpoints: @@ -4563,8 +4658,8 @@ TL1:DEFAULT.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 @@ -4783,9 +4878,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. @@ -5787,11 +5882,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. @@ -6013,7 +6103,7 @@ Module headers should adhere to the foll * binding library * * - * Author: Serena Willis + * Author: Serena Willis * Copyright (C) 1998 MUG Deutschland * Copyright (C) Coherent Logic Development LLC *