--- freem/doc/freem.texi 2025/04/18 15:39:23 1.27 +++ freem/doc/freem.texi 2025/04/18 19:43:18 1.28 @@ -235,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 @@ -278,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. @@ -435,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. @@ -474,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{}. @@ -663,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 @@ -1242,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() @@ -1275,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} @@ -1283,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 @@ -1300,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() @@ -3300,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 @@ -4166,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, / @@ -4606,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: @@ -4614,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 @@ -4834,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. @@ -6059,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 *