--- freem/doc/freem.texi 2025/04/04 02:40:32 1.17 +++ freem/doc/freem.texi 2025/04/10 17:21:54 1.24 @@ -4,7 +4,7 @@ @settitle The FreeM Manual @copying -This manual is for FreeM, (version 0.63.0), 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-2025 Coherent Logic Development LLC @@ -18,7 +18,7 @@ Permission is granted to copy, distribut @title The FreeM Manual @subtitle @sc{The Official Manual of FreeM} -@subtitle Version 0.63.0 +@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. @@ -238,23 +238,27 @@ $ @command{./freem} [@emph{OPTIONS}...] 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 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. +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}. + +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,7 +276,7 @@ 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}. @@ -305,7 +309,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 +337,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 as follows: +One daemon process is required per FreeM environment, and can be started in the following ways, in order of preference: @example -$ freem --daemon [--nofork] [--environment=] [--user=] \ - [--group=] [--pidfile=] [--shmsize=] +$ sudo fmadm start environment [-e=] +@end example + +@example +$ 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 +372,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.63.0 (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>}) 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 +400,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 +420,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. @@ -457,14 +464,14 @@ 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{}} @@ -482,13 +489,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 +517,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}}. @@ -1081,13 +1088,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 +1121,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 +1161,10 @@ The first argument is a string represent The second argument is a string representing a valid FreeM class. - - @example -USER> N STR=$$^%STRING +DEFAULT.USER> N STR=$$^%STRING -USER> W $INSTANCEOF("STR","^%STRING") +DEFAULT.USER> W $INSTANCEOF("STR","^%STRING") 1 @end example @@ -1861,36 +1881,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 +1941,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 +2003,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 +2252,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 +2265,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 +2285,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 @@ -2434,7 +2454,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.63.0, 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 @@ -3218,15 +3238,15 @@ WATCH[@emph{:postcondition}] [+|-|?]@emp 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)}. @example -USER> WATCH +DEFAULT.USER> WATCH Watchpoints enabled. -USER> WATCH +^JPW(1) +DEFAULT.USER> WATCH +^JPW(1) Added '^JPW("1")' to the watchlist. -USER> SET ^JPW(1)="new value" +DEFAULT.USER> SET ^JPW(1)="new value" >> WATCHPOINT: ^JPW("1") => 'new value' (changed 1 times) @@ -3235,11 +3255,11 @@ USER> SET ^JPW(1)="new value" The following example will remove that watchpoint: @example -USER> WATCH -^JPW(1) +DEFAULT.USER> WATCH -^JPW(1) Removed '^JPW("1")' from the watchlist. -USER> WATCH ?^JPW(1) +DEFAULT.USER> WATCH ?^JPW(1) '^JPW("1")' is not being watched. @end example @@ -3806,25 +3826,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. @@ -4477,18 +4478,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 @@ -4558,7 +4547,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] @@ -4818,7 +4807,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} @@ -5071,10 +5060,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]